MPMoviePlayerController Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/MediaPlayer.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Declared in
MPMoviePlayerController.h
Related sample code

Overview

A movie player (of type MPMoviePlayerController) manages the playback of a movie from a file or a network stream. Playback occurs in a view owned by the movie player and takes place either fullscreen or inline. You can incorporate a movie player’s view into a view hierarchy owned by your app, or use an MPMoviePlayerViewController object to manage the presentation for you.

Movie players (iOS 4.3 and later) support wireless movie playback to AirPlay-enabled hardware such as Apple TV. The movie player presents a control that allows the user to choose AirPlay-enabled hardware for playback when such hardware is in range. Starting in iOS 5.0, AirPlay playback is enabled by default. To disable AirPlay in your app, set the allowsAirPlay property to NO.

When you add a movie player’s view to your app’s view hierarchy, be sure to size the frame correctly, as shown here:

MPMoviePlayerController *player =
        [[MPMoviePlayerController alloc] initWithContentURL: myURL];
[player prepareToPlay];
[player.view setFrame: myView.bounds];  // player's frame must match parent's
[myView addSubview: player.view];
// ...
[player play];

Consider a movie player view to be an opaque structure. You can add your own custom subviews to layer content on top of the movie but you must never modify any of its existing subviews.

In addition to layering content on top of a movie, you can provide custom background content by adding subviews to the view in the backgroundView property. Custom subviews are supported in both inline and fullscreen playback modes but you must adjust the positions of your views when entering or exiting fullscreen mode. Use the MPMoviePlayerWillEnterFullscreenNotification and MPMoviePlayerWillExitFullscreenNotification notifications to detect changes to and from fullscreen mode.

This class supports programmatic control of movie playback, and user-based control via buttons supplied by the movie player. You can control most aspects of playback programmatically using the methods and properties of the MPMediaPlayback protocol, to which this class conforms. The methods and properties of that protocol let you start and stop playback, seek forward and backward through the movie’s content, and even change the playback rate. In addition, the controlStyle property of this class lets you display a set of standard system controls that allow the user to manipulate playback. You can also set the shouldAutoplay property for network-based content to start automatically.

You typically specify the movie you want to play when you create a new MPMoviePlayerController object. However, you can also change the currently playing movie by changing the value in the contentURL property. Changing this property lets you reuse the same movie player controller object in multiple places. For performance reasons you may want to play movies as local files. Do this by first downloading them to a local directory.

To facilitate the creation of video bookmarks or chapter links for a long movie, the MPMoviePlayerController class defines methods for generating thumbnail images at specific times within a movie. You can request a single thumbnail image using the thumbnailImageAtTime:timeOption: method or request multiple thumbnail images using the requestThumbnailImagesAtTimes:timeOption: method.

To play a network stream whose URL requires access credentials, first create an appropriate NSURLCredential object. Do this by calling, for example, the initWithUser:password:persistence: method, as shown here:

NSURLCredential *credential = [[NSURLCredential alloc]
                        initWithUser: @"userName"
                            password: @"password"
                         persistence: NSURLCredentialPersistenceForSession];
 
self.credential = credential;
[credential release];

In addition, create an appropriate NSURLProtectionSpace object, as shown here. Make appropriate modifications for the realm you are accessing:

NSURLProtectionSpace *protectionSpace = [[NSURLProtectionSpace alloc]
                            initWithHost: "@streams.mydomain.com"
                                    port: 80
                                protocol: @"http"
                                   realm: @"mydomain.com"
                    authenticationMethod: NSURLAuthenticationMethodDefault];
 
self.protectionSpace = protectionSpace;
[protectionSpace release];

Add the URL credential and the protection space to the Singleton NSURLCredentialStorage object. Do this by calling, for example, the setCredential:forProtectionSpace: method, as shown here:

[[NSURLCredentialStorage sharedCredentialStorage]
                    setDefaultCredential: credential
                      forProtectionSpace: protectionSpace];

With the credential and protection space information in place, you can then play the protected stream.

Movie Player Notifications

A movie player generates notifications to keep your app informed about the state of movie playback. In addition to being notified when playback finishes, your app can be notified in the following situations:

  • When the movie player begins playing, is paused, or begins seeking forward or backward

  • When AirPlay playback starts or ends

  • When the scaling mode of the movie changes

  • When the movie enters or exits fullscreen mode

  • When the load state for network-based movies changes

  • When meta-information about the movie itself becomes available

For more information, see the Notifications section in this document.

Supported Formats

This class plays any movie or audio file supported in iOS. This includes both streamed content and fixed-length files. For movie files, this typically means files with the extensions .mov, .mp4, .mpv, and .3gp and using one of the following compression standards:

  • H.264 Baseline Profile Level 3.0 video, up to 640 x 480 at 30 fps. (The Baseline profile does not support B frames.)

  • MPEG-4 Part 2 video (Simple Profile)

If you use this class to play audio files, it displays a white screen with a QuickTime logo while the audio plays. For audio files, this class supports AAC-LC audio at up to 48 kHz, and MP3 (MPEG-1 Audio Layer 3) up to 48 kHz, stereo audio.

Behavior in iOS 4.3 and Earlier

In iOS 4.3 and earlier, a new movie player was automatically prepared to play. Starting in iOS 5.0, in order to facilitate finer-grained playback control, a new movie player is not automatically prepared to play. See the discussion for the initWithContentURL: instance method.

Also, AirPlay was disabled by default in iOS 4.3 and earlier. Starting in iOS 5.0, the default for the allowsAirPlay property is YES.

Behavior in iOS 3.1 and Earlier

In iOS 3.1 and earlier, this class implemented a full-screen movie player only. After creating the movie player and initializing it with a single movie file, you called the play method to present the movie. (The definition of the play method has since moved out of this class and into the MPMediaPlayback protocol.) The movie player object itself handled the actual presentation of the movie content.

Tasks

Creating and Initializing the Object

Accessing Movie Properties

Accessing the Movie Duration

Accessing the View

Controlling and Monitoring Playback

See also the methods of the MPMediaPlayback protocol.

Generating Thumbnail Images

Retrieving Movie Logs

Unavailable Methods and Properties

The following methods and properties are no longer available as of iOS 3.2 and must not be used.

Properties

accessLog

A snapshot of the network playback log for the movie player if it is playing a network stream.

@property (nonatomic, readonly) MPMovieAccessLog *accessLog
Discussion

Can be nil. For information about movie access logs, refer to MPMovieAccessLog Class Reference.

Availability
  • Available in iOS 4.3 and later.
Declared In
MPMoviePlayerController.h

airPlayVideoActive

Indicates whether the movie player is currently playing video via AirPlay.

@property (nonatomic, readonly, getter=isAirPlayVideoActive) BOOL airPlayVideoActive
Discussion

You can query this property after receiving an MPMoviePlayerIsAirPlayVideoActiveDidChangeNotification notification to find out whether the AirPlay video started or stopped.

Availability
  • Available in iOS 5.0 and later.
Declared In
MPMoviePlayerController.h

allowsAirPlay

Specifies whether the movie player allows AirPlay movie playback.

@property (nonatomic) BOOL allowsAirPlay
Discussion

A movie player supports wireless movie playback to AirPlay-enabled hardware. When enabled, the movie player presents a control that allows the user to choose AirPlay-enabled hardware for playback when such hardware is in range.

The default value is YES. To disable AirPlay movie playback, set this property’s value to NO.

Availability
  • Available in iOS 4.3 and later.
Related Sample Code
Declared In
MPMoviePlayerController.h

backgroundView

A customizable view that is displayed behind the movie content. (read-only)

@property (nonatomic, readonly) UIView *backgroundView
Discussion

This view provides the backing content, on top of which the movie content is displayed. You can add subviews to the background view if you want to display custom background content.

This view is part of the view hierarchy returned by the view property.

Availability
  • Available in iOS 3.2 and later.
Related Sample Code
Declared In
MPMoviePlayerController.h

contentURL

The URL that points to the movie file.

@property (nonatomic, copy) NSURL *contentURL
Discussion

If you set this property while a movie is playing, that movie pauses and the new movie begins loading. The new movie starts playing at the beginning.

Availability
  • Available in iOS 2.0 and later.
Declared In
MPMoviePlayerController.h

controlStyle

The style of the playback controls.

@property (nonatomic) MPMovieControlStyle controlStyle
Discussion

The default value of this property is MPMovieControlStyleDefault. You can change the value of this property to change the style of the controls or to hide the controls altogether. For a list of available control styles, see “MPMovieControlStyle.”

Availability
  • Available in iOS 3.2 and later.
Related Sample Code
Declared In
MPMoviePlayerController.h

duration

The duration of the movie, measured in seconds. (read-only)

@property (nonatomic, readonly) NSTimeInterval duration
Discussion

If the duration of the movie is not known, the value in this property is 0.0. If the duration is subsequently determined, this property is updated and a MPMovieDurationAvailableNotification notification is posted.

Availability
  • Available in iOS 3.2 and later.
Declared In
MPMoviePlayerController.h

endPlaybackTime

The end time (measured in seconds) for playback of the movie.

@property (nonatomic) NSTimeInterval endPlaybackTime
Discussion

The default value of this property is -1, which indicates the natural end time of the movie. This property is not applicable for streamed content.

Availability
  • Available in iOS 3.2 and later.
Declared In
MPMoviePlayerController.h

errorLog

A snapshot of the playback failure error log for the movie player if it is playing a network stream.

@property (nonatomic, readonly) MPMovieErrorLog *errorLog
Discussion

Can be nil. For information about movie error logs, refer to MPMovieErrorLog Class Reference.

Availability
  • Available in iOS 4.3 and later.
Declared In
MPMoviePlayerController.h

fullscreen

A Boolean that indicates whether the movie player is in full-screen mode.

@property (nonatomic, getter=isFullscreen) BOOL fullscreen
Discussion

The default value of this property is NO. Changing the value of this property causes the movie player to enter or exit full-screen mode immediately. If you want to animate the transition to full-screen mode, use the setFullscreen:animated: method instead.

Whenever the movie player enters or exits full-screen mode, it posts appropriate notifications to reflect the change. For example, upon entering full-screen mode, it posts MPMoviePlayerWillEnterFullscreenNotification and MPMoviePlayerDidEnterFullscreenNotification notifications. Upon exiting from full-screen mode, it posts MPMoviePlayerWillExitFullscreenNotification and MPMoviePlayerDidExitFullscreenNotification notifications.

The value of this property may also change as a result of the user interacting with the movie player controls.

Availability
  • Available in iOS 3.2 and later.
Declared In
MPMoviePlayerController.h

initialPlaybackTime

The time, specified in seconds within the video timeline, when playback should start.

@property (nonatomic) NSTimeInterval initialPlaybackTime
Discussion

For progressively downloaded content, playback starts at the closest key frame prior to the provided time. For video-on-demand content, playback starts at the nearest segment boundary to the provided time. For live video streams, the playback start time is measured from the start of the current playlist and is rounded to the nearest segment boundary.

The default value of this property is -1, which indicates the natural start time of the movie.

Availability
  • Available in iOS 3.0 and later.
Declared In
MPMoviePlayerController.h

loadState

The network load state of the movie player. (read-only)

@property (nonatomic, readonly) MPMovieLoadState loadState
Discussion

See the “MPMovieLoadState” enumeration for possible values of this property. To be notified of changes to the load state of a movie player, register for the MPMoviePlayerLoadStateDidChangeNotification notification.

Availability
  • Available in iOS 3.2 and later.
Related Sample Code
Declared In
MPMoviePlayerController.h

movieMediaTypes

The types of media available in the movie. (read-only)

@property (nonatomic, readonly) MPMovieMediaTypeMask movieMediaTypes
Discussion

Movies can contain a combination of audio, video, or a combination of the two. The default value of this property is MPMovieMediaTypeMaskNone. See the “MPMovieMediaTypeMask” enumeration for possible values of this property.

Availability
  • Available in iOS 3.2 and later.
Declared In
MPMoviePlayerController.h

movieSourceType

The playback type of the movie.

@property (nonatomic) MPMovieSourceType movieSourceType
Discussion

The default value of this property is MPMovieSourceTypeUnknown. This property provides a clue to the playback system as to how it should download and buffer the movie content. If you know the source type of the movie, setting the value of this property before playback begins can improve the load times for the movie content. If you do not set the source type explicitly before playback, the movie player controller must gather this information, which might delay playback.

Availability
  • Available in iOS 3.2 and later.
Declared In
MPMoviePlayerController.h

naturalSize

The width and height of the movie frame. (read-only)

@property (nonatomic, readonly) CGSize naturalSize
Discussion

This property reports the clean aperture of the video in square pixels. Thus, the reported dimensions take into account anamorphic content and aperture modes.

It is possible for the natural size of a movie to change during playback. This typically happens when the bit-rate of streaming content changes or when playback toggles between audio-only and a combination of audio and video.

Availability
  • Available in iOS 3.2 and later.
Declared In
MPMoviePlayerController.h

playableDuration

The amount of currently playable content. (read-only)

@property (nonatomic, readonly) NSTimeInterval playableDuration
Discussion

For progressively downloaded network content, this property reflects the amount of content that can be played now.

Availability
  • Available in iOS 3.2 and later.
Declared In
MPMoviePlayerController.h

playbackState

The current playback state of the movie player. (read-only)

@property (nonatomic, readonly) MPMoviePlaybackState playbackState
Discussion

The playback state is affected by programmatic calls to play, pause, or stop the movie player. It can also be affected by user interactions or by the network, in cases where streaming content cannot be buffered fast enough.

See the “MPMoviePlaybackState” enumeration for possible values of this property. To be notified of changes to the playback state of a movie player, register for the MPMoviePlayerPlaybackStateDidChangeNotification notification.

Availability
  • Available in iOS 3.2 and later.
Related Sample Code
Declared In
MPMoviePlayerController.h

readyForDisplay

A Boolean that indicates whether the first video frame of the movie is ready to be displayed.

@property(nonatomic, readonly) BOOL readyForDisplay
Discussion

The default value of this property is NO. This property returns YES if the first video frame is ready to be displayed and returns NO if there are no video tracks associated. When the value of this property changes to YES, a MPMoviePlayerReadyForDisplayDidChangeNotification is sent.

Availability
  • Available in iOS 6.0 and later.
Declared In
MPMoviePlayerController.h

repeatMode

Determines how the movie player repeats the playback of the movie.

@property (nonatomic) MPMovieRepeatMode repeatMode
Discussion

The default value of this property is MPMovieRepeatModeNone. For a list of available repeat modes, see “MPMovieRepeatMode.”

Availability
  • Available in iOS 3.2 and later.
Related Sample Code
Declared In
MPMoviePlayerController.h

scalingMode

The scaling mode to use when displaying the movie.

@property (nonatomic) MPMovieScalingMode scalingMode
Discussion

Changing this property while the movie player is visible causes the current movie to animate to the new scaling mode.

The default value of this property is MPMovieScalingModeAspectFit. For a list of available scaling modes, see “MPMovieScalingMode.”

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
MPMoviePlayerController.h

shouldAutoplay

A Boolean that indicates whether a movie should begin playback automatically.

@property (nonatomic) BOOL shouldAutoplay
Discussion

The default value of this property is YES. This property determines whether the playback of network-based content begins automatically when there is enough buffered data to ensure uninterrupted playback.

Availability
  • Available in iOS 3.2 and later.
Declared In
MPMoviePlayerController.h

view

The view containing the movie content and controls. (read-only)

@property (nonatomic, readonly) UIView *view
Discussion

This property contains the view used for presenting the video content. This view incorporates all the background, content, and controls needed to display movies. You can incorporate this view into your own view hierarchies or present it by itself using a view controller.

To embed the view into your own view hierarchies, add it as a subview to one of your existing views. A good place to do this is in the loadView or viewDidLoad method of the custom view controller that presents your view hierarchy. You are free to change the view’s frame rectangle to accommodate the space available in your view hierarchy. The movie player uses the value in the scalingMode property to scale the movie content to match the frame you specify.

If you want to present the view by itself—that is, without embedding it in an existing view hierarchy—you can use an instance of the MPMoviePlayerViewController class to manage the presentation of the view. That class works directly with the movie player controller to present the view by itself.

You can add subviews to the view in this property. You might do this in cases where you want to display custom playback controls or add other custom content that is relevant to your app.

Availability
  • Available in iOS 3.2 and later.
Related Sample Code
Declared In
MPMoviePlayerController.h

Instance Methods

cancelAllThumbnailImageRequests

Cancels all pending asynchronous thumbnail image requests.

- (void)cancelAllThumbnailImageRequests
Discussion

This method cancels only requests made using the requestThumbnailImagesAtTimes:timeOption: method. It does not cancel requests made synchronously using the thumbnailImageAtTime:timeOption: method.

Availability
  • Available in iOS 3.2 and later.
Declared In
MPMoviePlayerController.h

initWithContentURL:

Returns a MPMoviePlayerController object initialized with the movie at the specified URL.

- (id)initWithContentURL:(NSURL *)url
Parameters
url

The location of the movie file. This file must be located either in your app directory or on a remote server.

Return Value

The movie player object.

Discussion

This method initializes a movie player, but does not prepare it for playback. To prepare a new movie player for playback, call the prepareToPlay method, described in MPMediaPlayback Protocol Reference.

To be notified when a new movie player is ready to play, register for the MPMoviePlayerLoadStateDidChangeNotification notification. You can then check load state by accessing the loadState property.

To check for errors in URL loading, register for the MPMoviePlayerPlaybackDidFinishNotification notification. On error, this notification contains an NSError object available using the @"error" key in the notification’s userInfo dictionary.

Availability
  • Available in iOS 2.0 and later.
Declared In
MPMoviePlayerController.h

requestThumbnailImagesAtTimes:timeOption:

Captures one or more thumbnail images asynchronously from the current movie.

- (void)requestThumbnailImagesAtTimes:(NSArray *)playbackTimes timeOption:(MPMovieTimeOption)option
Parameters
playbackTimes

An array of NSNumber objects containing the times at which to capture the thumbnail images. Each time value represents the number of seconds from the beginning of the current movie.

option

The option to use when determining which specific frame to use for each thumbnail image. For a list of possible values, see “MPMovieTimeOption.”

Discussion

This method processes each thumbnail request separately and asynchronously. When the results for a single image arrive, the movie player posts a MPMoviePlayerThumbnailImageRequestDidFinishNotification notification with the results for that image. Notifications are posted regardless of whether the image capture was successful or failed. You should register for this notification prior to calling this method.

Availability
  • Available in iOS 3.2 and later.
Declared In
MPMoviePlayerController.h

setFullscreen:animated:

Causes the movie player to enter or exit full-screen mode.

- (void)setFullscreen:(BOOL)fullscreen animated:(BOOL)animated
Parameters
fullscreen

Specify YES to enter full-screen mode or NO to exit full-screen mode.

animated

Specify YES to animate the transition between modes or NO to switch immediately to the new mode.

Availability
  • Available in iOS 3.2 and later.
Declared In
MPMoviePlayerController.h

timedMetadata

Obtains the most recent time-based metadata provided by the streamed movie.

- (NSArray *)timedMetadata
Return Value

An array of the most recent MPTimedMetadata objects provided by the streamed movie.

Availability
  • Available in iOS 4.0 and later.
Declared In
MPMoviePlayerController.h

Constants

MPMovieLoadState

Constants describing the network load state of the movie player.

enum {
   MPMovieLoadStateUnknown        = 0,
   MPMovieLoadStatePlayable       = 1 << 0,
   MPMovieLoadStatePlaythroughOK  = 1 << 1,
   MPMovieLoadStateStalled        = 1 << 2,
};
typedef NSInteger MPMovieLoadState;
Constants
MPMovieLoadStateUnknown

The load state is not known.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMovieLoadStatePlayable

The buffer has enough data that playback can begin, but it may run out of data before playback finishes.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMovieLoadStatePlaythroughOK

Enough data has been buffered for playback to continue uninterrupted.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMovieLoadStateStalled

The buffering of data has stalled. If started now, playback may pause automatically if the player runs out of buffered data.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMovieControlStyle

Constants describing the style of the playback controls.

enum {
   MPMovieControlStyleNone,
   MPMovieControlStyleEmbedded,
   MPMovieControlStyleFullscreen,
   MPMovieControlStyleDefault = MPMovieControlStyleFullscreen
};
typedef NSInteger MPMovieControlStyle;
Constants
MPMovieControlStyleNone

No controls are displayed.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMovieControlStyleEmbedded

Controls for an embedded view are displayed. The controls include a start/pause button, a scrubber bar, and a button for toggling between fullscreen and embedded display modes.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMovieControlStyleFullscreen

Controls for fullscreen playback are displayed. The controls include a start/pause button, a scrubber bar, forward and reverse seeking buttons, a button for toggling between fullscreen and embedded display modes, a button for toggling the aspect fill mode, and a Done button. Tapping the done button pauses the video and exits fullscreen mode.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMovieControlStyleDefault

Fullscreen controls are displayed by default.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMovieFinishReason

Constants describing the reason that playback ended.

enum {
   MPMovieFinishReasonPlaybackEnded,
   MPMovieFinishReasonPlaybackError,
   MPMovieFinishReasonUserExited
};
typedef NSInteger MPMovieFinishReason;
Constants
MPMovieFinishReasonPlaybackEnded

The end of the movie was reached.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMovieFinishReasonPlaybackError

There was an error during playback.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMovieFinishReasonUserExited

The user stopped playback.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMoviePlaybackState

Constants describing the current playback state of the movie player.

enum {
   MPMoviePlaybackStateStopped,
   MPMoviePlaybackStatePlaying,
   MPMoviePlaybackStatePaused,
   MPMoviePlaybackStateInterrupted,
   MPMoviePlaybackStateSeekingForward,
   MPMoviePlaybackStateSeekingBackward
};
typedef NSInteger MPMoviePlaybackState;
Constants
MPMoviePlaybackStateStopped

Playback is currently stopped. Playback will commence from the beginning of the movie.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMoviePlaybackStatePlaying

Playback is currently under way.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMoviePlaybackStatePaused

Playback is currently paused. Playback will resume from the point where it was paused.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMoviePlaybackStateInterrupted

Playback is temporarily interrupted, perhaps because the buffer ran out of content.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMoviePlaybackStateSeekingForward

The movie player is currently seeking towards the end of the movie.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMoviePlaybackStateSeekingBackward

The movie player is currently seeking towards the beginning of the movie.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMovieRepeatMode

Constants describing how the movie player repeats content at the end of playback.

enum {
   MPMovieRepeatModeNone,
   MPMovieRepeatModeOne
};
typedef NSInteger MPMovieRepeatMode;
Constants
MPMovieRepeatModeNone

Content is not repeated when playback finishes

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMovieRepeatModeOne

The current movie is repeated when it finishes.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMovieScalingMode

Constants describing how the movie content is scaled to fit the frame of its view.

typedef enum {
   MPMovieScalingModeNone,
   MPMovieScalingModeAspectFit,
   MPMovieScalingModeAspectFill,
   MPMovieScalingModeFill
} MPMovieScalingMode;
Constants
MPMovieScalingModeNone

Do not scale the movie.

Available in iOS 2.0 and later.

Declared in MPMoviePlayerController.h.

MPMovieScalingModeAspectFit

Scale the movie uniformly until one dimension fits the visible bounds of the view exactly. In the other dimension, the region between the edge of the movie and the edge of the view is filled with a black bar. The aspect ratio of the movie is preserved.

Available in iOS 2.0 and later.

Declared in MPMoviePlayerController.h.

MPMovieScalingModeAspectFill

Scale the movie uniformly until the movie fills the visible bounds of the view. Content at the edges of the larger of the two dimensions is clipped so that the other dimension fits the view exactly. The aspect ratio of the movie is preserved.

Available in iOS 2.0 and later.

Declared in MPMoviePlayerController.h.

MPMovieScalingModeFill

Scale the movie until both dimensions fit the visible bounds of the view exactly. The aspect ratio of the movie is not preserved.

Available in iOS 2.0 and later.

Declared in MPMoviePlayerController.h.

MPMovieTimeOption

Constants describing which frame to use when generating thumbnail images.

enum {
   MPMovieTimeOptionNearestKeyFrame,
   MPMovieTimeOptionExact
};
typedef NSInteger MPMovieTimeOption;
Constants
MPMovieTimeOptionNearestKeyFrame

Generate a thumbnail image using the nearest key frame. This frame could be several frames away from the current frame. This option generally offers better performance than trying to find the exact frame.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMovieTimeOptionExact

Use the exact current frame.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMovieMediaTypeMask

Specifies the types of content available in the movie file.

enum {
   MPMovieMediaTypeMaskNone  = 0,
   MPMovieMediaTypeMaskVideo = 1 << 0,
   MPMovieMediaTypeMaskAudio = 1 << 1
};
typedef NSInteger MPMovieMediaTypeMask;
Constants
MPMovieMediaTypeMaskNone

The types of media available in the media are not yet known.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMovieMediaTypeMaskVideo

The movie file contains video media.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMovieMediaTypeMaskAudio

The movie file contains audio media.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

Discussion

You can OR the specified constants together to specify a movie

MPMovieSourceType

Specifies the type of the movie file.

enum {
   MPMovieSourceTypeUnknown,
   MPMovieSourceTypeFile,
   MPMovieSourceTypeStreaming
};
typedef NSInteger MPMovieSourceType;
Constants
MPMovieSourceTypeUnknown

The movie type is not yet known.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMovieSourceTypeFile

The movie is a local file or is a file that can be downloaded from the network.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMovieSourceTypeStreaming

The movie is a live or on-demand stream.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

Thumbnail Notification User Info Keys

The following keys may be found in the userInfo dictionary of a MPMoviePlayerThumbnailImageRequestDidFinishNotification notification.

NSString *const MPMoviePlayerThumbnailImageKey;
NSString *const MPMoviePlayerThumbnailTimeKey;
NSString *const MPMoviePlayerThumbnailErrorKey;
Constants
MPMoviePlayerThumbnailImageKey

The value of this key is a UIImage object containing the image that was obtained for the desired frame.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMoviePlayerThumbnailTimeKey

The value of this key is a NSNumber object containing a double value. This value represents the actual time (measured in seconds) from the beginning of the movie at which the image was captured.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMoviePlayerThumbnailErrorKey

The value of this key is an NSError object identifying the error that occurred, if any.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

Fullscreen Notification Keys

The following keys may be found in the userInfo dictionary of notifications for transitioning in or out of full-screen mode.

NSString *const MPMoviePlayerFullscreenAnimationDurationUserInfoKey;
NSString *const MPMoviePlayerFullscreenAnimationCurveUserInfoKey;
Constants
MPMoviePlayerFullscreenAnimationDurationUserInfoKey

The value of this key is an NSNumber containing a double value. This value represents the duration (measured in seconds) of the animation used to transition in or out of full-screen mode.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMoviePlayerFullscreenAnimationCurveUserInfoKey

The value of this key is an NSNumber containing an integer value that represents one of the UIViewAnimationCurve constants.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

Playback Finished Notification Key

The following key may be found in the userInfo dictionary of a MPMoviePlayerPlaybackDidFinishNotification notification.

NSString *const MPMoviePlayerPlaybackDidFinishReasonUserInfoKey;
Constants
MPMoviePlayerPlaybackDidFinishReasonUserInfoKey

The value of this key is an NSNumber containing an integer value that represents one of the “MPMovieFinishReason” constants.

Available in iOS 3.2 and later.

Declared in MPMoviePlayerController.h.

MPMovieControlMode

Options for displaying movie playback controls. (Deprecated. Use the “MPMovieControlStyle” constants in conjunction with the controlStyle property instead.)

typedef enum {
   MPMovieControlModeDefault,
   MPMovieControlModeVolumeOnly,
   MPMovieControlModeHidden
} MPMovieControlMode;
Constants
MPMovieControlModeDefault

Display the standard controls for controlling playback. This includes play/pause controls, a volume slider, and a timeline control.

Available in iOS 2.0 and later.

Declared in MPMoviePlayerController.h.

MPMovieControlModeVolumeOnly

Display volume controls only.

Available in iOS 2.0 and later.

Declared in MPMoviePlayerController.h.

MPMovieControlModeHidden

Do not display any controls. This mode prevents the user from controlling playback.

Available in iOS 2.0 and later.

Declared in MPMoviePlayerController.h.

Notifications

To be notified of changes in movie player state such as playability, or changes in the availability of movie information such as duration, register for the appropriate notification. For all movie player notifications, the movie player whose state has changed is available as the object associated with the notification.

MPMovieDurationAvailableNotification

Posted when the duration of a movie has been determined. There is no userInfo dictionary.

To retrieve the duration of a movie, access the movie player’s duration property. The movie player whose state has changed is available as the object associated with the notification.

Availability
Declared In
MPMoviePlayerController.h

MPMovieMediaTypesAvailableNotification

Posted when the available media types in a movie are determined. There is no userInfo dictionary.

To retrieve the available media types in a movie—audio, video, or both—access the movie player’s movieMediaTypes property. The movie player whose state has changed is available as the object associated with the notification.

Availability
Declared In
MPMoviePlayerController.h

MPMovieNaturalSizeAvailableNotification

Posted when the natural frame size of a movie is first determined or subsequently changes. There is no userInfo dictionary.

To retrieve the natural frame size for a movie, access the movie player’s naturalSize property. The movie player whose state has changed is available as the object associated with the notification.

Availability
Declared In
MPMoviePlayerController.h

MPMoviePlayerContentPreloadDidFinishNotification

Posted when a movie is in memory and ready to play. The movie player whose state has changed is available as the object associated with the notification. If an error occurred during loading, the userInfo dictionary of this notification contains a key with the name “error” whose value is the NSError object describing the problem. (Deprecated. Use the MPMoviePlayerLoadStateDidChangeNotification notification to determine the readiness of the player.)
Availability
Declared In
MPMoviePlayerController.h

MPMoviePlayerDidEnterFullscreenNotification

Posted when a movie player has entered full-screen mode. There is no userInfo dictionary.

A movie player can enter full screen mode programmatically (see the setFullscreen:animated: method) or by user interaction. The movie player whose state has changed is available as the object associated with the notification.

Availability
Declared In
MPMoviePlayerController.h

MPMoviePlayerDidExitFullscreenNotification

Posted when a movie player has exited full-screen mode. There is no userInfo dictionary.

A movie player can exit full screen mode programmatically (see the setFullscreen:animated: method) or by user interaction. The movie player whose state has changed is available as the object associated with the notification.

Availability
Declared In
MPMoviePlayerController.h

MPMoviePlayerIsAirPlayVideoActiveDidChangeNotification

Posted when a movie player has started or ended playing a movie via AirPlay. There is no userInfo dictionary.

To find out whether AirPlay playback started or stopped, query the airPlayVideoActive property. The movie player whose state has changed is available as the object associated with the notification.

Availability
Declared In
MPMoviePlayerController.h

MPMoviePlayerLoadStateDidChangeNotification

Posted when a movie player’s network buffering state has changed. There is no userInfo dictionary.

To retrieve the current load state of a movie player, access its loadState property. The movie player whose state has changed is available as the object associated with the notification.

Availability
Declared In
MPMoviePlayerController.h

MPMoviePlayerNowPlayingMovieDidChangeNotification

Posted when the currently playing movie has changed. There is no userInfo dictionary.

To retrieve the URL for currently playing movie, access the movie player’s contentURL property. The movie player whose state has changed is available as the object associated with the notification.

Availability
Declared In
MPMoviePlayerController.h

MPMoviePlayerPlaybackDidFinishNotification

Posted when a movie has finished playing. The userInfo dictionary of this notification contains the MPMoviePlayerPlaybackDidFinishReasonUserInfoKey key, which indicates the reason that playback finished. This notification is also sent when playback fails because of an error.

The movie player whose state has changed is available as the object associated with the notification.

This notification is not sent when a movie is displaying in fullscreen mode and the user taps Done. The Done button pauses playback and causes the movie player to exit fullscreen mode. To detect this scenario, register for other notifications such as MPMoviePlayerDidExitFullscreenNotification.

Availability
Declared In
MPMoviePlayerController.h

MPMoviePlayerPlaybackStateDidChangeNotification

Posted when a movie player’s playback state has changed. There is no userInfo dictionary.

Playback state can change programmatically (see MPMediaPlayback Protocol Reference) or by user interaction. To retrieve the playback state of a movie player, access its playbackState property. The movie player whose state has changed is available as the object associated with the notification.

Availability
Declared In
MPMoviePlayerController.h

MPMoviePlayerScalingModeDidChangeNotification

Posted when the scaling mode of a movie player has changed. There is no userInfo dictionary.

Scaling mode can change programmatically or by user interaction. To set or retrieve the scaling mode of a movie player, access its scalingMode property. The movie player whose state has changed is available as the object associated with the notification.

Availability
Declared In
MPMoviePlayerController.h

MPMoviePlayerThumbnailImageRequestDidFinishNotification

Posted when a request to capture a thumbnail from a movie has finished whether the request succeeded or failed. Upon successful capture of a thumbnail, the userInfo dictionary contains values for the following keys:

If the capture request finished with an error, the userInfo dictionary contains values for the following two keys:

The movie player whose state has changed is available as the object associated with the notification. The methods to use for capturing movie thumbnails are described in “Generating Thumbnail Images.”

Availability
Declared In
MPMoviePlayerController.h

MPMoviePlayerWillEnterFullscreenNotification

Posted when a movie player is about to enter full-screen mode. The userInfo dictionary contains keys whose values describe the transition animation used to enter full-screen mode. See “Fullscreen Notification Keys.”

A movie player can enter full screen mode programmatically (see the setFullscreen:animated: method) or by user interaction. The movie player whose state has changed is available as the object associated with the notification.

Availability
Declared In
MPMoviePlayerController.h

MPMoviePlayerWillExitFullscreenNotification

Posted when a movie player is about to exit full-screen mode. The userInfo dictionary contains keys whose values describe the transition animation used to exit full-screen mode. See “Fullscreen Notification Keys.”

A movie player can exit full screen mode programmatically (see the setFullscreen:animated: method) or by user interaction. The movie player whose state has changed is available as the object associated with the notification.

Availability
Declared In
MPMoviePlayerController.h

MPMovieSourceTypeAvailableNotification

Posted when the source type of a movie was previously unknown and is newly available. There is no userInfo dictionary.

To retrieve the source type of the movie, access the movie player’s movieSourceType property. The movie player whose state has changed is available as the object associated with the notification.

Availability
Declared In
MPMoviePlayerController.h

MPMoviePlayerReadyForDisplayDidChangeNotification

Posted when the ready for display state changes.

To check whether a movie player is ready for display, access its readyForDisplay property. The movie player whose display state has changed is available as the object associated with the notification.

Availability
Declared In
MPMoviePlayerController.h