QTMovie Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/QTKit.framework
Availability
Available in OS X v10.4 and later.
Declared in
QTMovie.h
Related sample code

Overview

A QTMovie object is an object that represents a playable collection of media data.

A QTMovie object can be initialized from a file, from a resource specified by a URL, from a block of memory, from a pasteboard, or from an existing QuickTime movie. Once a QTMovie object has been initialized, it will typically be used in combination with a QTMovieView for playback. It can also be used for other purposes, such as converting the media data into a different format.

The designated initializer for the QTMovie class is initWithAttributes:error:, whose first parameter is a dictionary of attribute keys and their desired values. One of these attributes must specify the location of the media data (for instance, using the QTMovieURLAttribute key). Other attributes may specify desired movie-opening behaviors, and others still may specify desired initial values of QTMovie properties (for instance, QTMovieVolumeAttribute).

There are two movie-opening behaviors. Specifying QTMovieOpenForPlaybackAttribute with the value YES indicates that the QTMovie object will be used only for playback, in which case QTKit may be able to use more efficient code paths for some media data. Specifying QTMovieOpenAsyncRequiredAttribute with the value YES indicates that all operations necessary to open the movie file (or other container) and to create a valid QTMovie object must occur asynchronously. In other words, initWithAttributes:error: will return almost immediately, performing any lengthy operations on another thread.

An exception, QTDisallowedForInitializationPurposeException, is raised whenever the client attempts to call a method that is not allowed under a requested movie-opening behavior. For example, if a QTMovie object is initialized with QTMovieOpenForPlaybackAttribute set to YES, then QTDisallowedForInitializationPurposeException is raised if the client attempts to call methods that export the media data. An exception, QTMovieUneditableException, is raised whenever the client attempts to directly or indirectly edit a QTMovie object that is not currently set as editable (for instance, by calling appendSelectionFromMovie: on an uneditable movie).

Tasks

Determining If a Movie Can Be Initialized

Getting a List of Supported File Types

Creating a Movie

Controlling Movie Playback

Managing Threaded Operations of Movie Objects

Initializing a QTMovie

Getting Information About a Movie and Its Chapters

Inspecting Movie Properties

Managing QTMovie Idling States

Setting QTMovie Properties

Setting Movie Attributes

Supporting Aperture Modes

Getting and Setting Selection Times

Getting Movie Tracks

Getting Movie Images

Storing Movie Data

Editing a Movie

Saving a Movie

Getting QTMovie Primitives

Getting and Setting QTMovie Delegates

Accessing QTMovie Visual Contexts

Instance Methods

movieShouldLoadData:

If implemented by a delegate of a QTMovie object, called periodically while the movie is loading its data.

- (BOOL)movieShouldLoadData:(id)sender
Parameters
sender

The QTMovie object that is loading its data.

Return Value

A BOOL value; this value is ignored by QTKit.

Special Considerations

This delegate method is deprecated and should not be used in new code. This delegate method is not called when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Constants

Constants For Use With movieFileTypes: Method

The following values can be used to include some or all of the file types that are normally excluded:

typedef enum {
   QTIncludeStillImageTypes  =  1 << 0,
   QTIncludeTranslatableTypes =  1 << 1,
   QTIncludeAggressiveTypes =  1 << 2,
   QTIncludeCommonTypes = 0,
   QTIncludeAllTypes = 0xffff
} QTMovieFileTypeOptions;
Constants
QTIncludeStillImageTypes

This value adds to the array all file types for still images that can be opened using a graphics importer.

Available in OS X v10.3 and later.

Declared in QTMovie.h.

QTIncludeTranslatableTypes

This value adds to the array all file types for files that can be opened using a movie importer but for which a new file must be created.

Available in OS X v10.3 and later.

Declared in QTMovie.h.

QTIncludeAggressiveTypes

This value adds to the array all file types for files that can be opened using a movie importer but that are not commonly used in connection with movies (for instance, text or HTML files).

Available in OS X v10.3 and later.

Declared in QTMovie.h.

QTIncludeCommonTypes

This value adds to the array all common file types that QuickTime can open in place on the current system.

Available in OS X v10.3 and later.

Declared in QTMovie.h.

QTIncludeAllTypes

This value adds to the array all file types that QuickTime can open on the current system, using any available movie or graphics importer.

Available in OS X v10.3 and later.

Declared in QTMovie.h.

Settable and Gettable Movie Attributes

The following constants specify the movie attributes that you can get and set using the movieAttributes and setMovieAttributes methods. To get or set a single attribute, use attributeForKey or setAttribute.

NSString * const QTMovieApertureModeAttribute;
NSString * const QTMovieActiveSegmentAttribute;
NSString * const QTMovieAutoAlternatesAttribute;
NSString * const QTMovieCopyrightAttribute;
NSString * const QTMovieCreationTimeAttribute;
NSString * const QTMovieCurrentSizeAttribute;
NSString * const QTMovieCurrentTimeAttribute;
NSString * const QTMovieDataSizeAttribute;
NSString * const QTMovieDelegateAttribute;
NSString * const QTMovieDisplayNameAttribute;
NSString * const QTMovieDurationAttribute;
NSString * const QTMovieEditableAttribute;
NSString * const QTMovieFileNameAttribute;
NSString * const QTMovieHasApertureModeDimensionsAttribute;
NSString * const QTMovieHasAudioAttribute;
NSString * const QTMovieHasDurationAttribute;
NSString * const QTMovieHasVideoAttribute;
NSString * const QTMovieIsActiveAttribute;
NSString * const QTMovieIsInteractiveAttribute;
NSString * const QTMovieIsLinearAttribute;
NSString * const QTMovieIsSteppableAttribute;
NSString * const QTMovieLoadStateAttribute;
NSString * const QTMovieLoadStateErrorAttribute;
NSString * const QTMovieLoopsAttribute;
NSString * const QTMovieLoopsBackAndForthAttribute;
NSString * const QTMovieModificationTimeAttribute;
NSString * const QTMovieMutedAttribute;
NSString * const QTMovieNaturalSizeAttribute;
NSString * const QTMoviePlaysAllFramesAttribute;
NSString * const QTMoviePlaysSelectionOnlyAttribute;
NSString * const QTMoviePosterTimeAttribute;
NSString * const QTMoviePreferredMutedAttribute;
NSString * const QTMoviePreferredRateAttribute;
NSString * const QTMoviePreferredVolumeAttribute;
NSString * const QTMoviePreviewModeAttribute;
NSString * const QTMoviePreviewRangeAttribute;
NSString * const QTMovieRateAttribute;
NSString * const QTMovieSelectionAttribute;
NSString * const QTMovieTimeScaleAttribute;
NSString * const QTMovieURLAttribute;
NSString * const QTMovieVolumeAttribute;
NSString * const QTMovieRateChangesPreservePitchAttribute;
Constants
QTMovieApertureModeAttribute

Sets the aperture mode attribute on a QTMovie object to indicate whether aspect ratio and clean aperture correction should be performed.

This attribute can be read but not written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieActiveSegmentAttribute

The active segment of a QTMovie object; the value for this key is of type NSValue, interpreted as a QTTimeRange structure. This constant is available in OS X v10.4 and later, but deprecated in OS X v10.5.

This attribute can be read but not written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.5.

Declared in QTMovie.h.

QTMovieAutoAlternatesAttribute

The auto-alternate state of a QTMovie object. The value for this key is of type NSNumber, interpreted as a BOOL.

This attribute can be read but not written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieCopyrightAttribute

The copyright string of a QTMovie object; the value for this key is of type NSString.

This attribute can be read but not written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieCreationTimeAttribute

The creation time of a QTMovie object; the value for this key is of type NSDate.

This attribute can be read but not written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieCurrentSizeAttribute

The current size of a QTMovie object; the value for this key is of type NSValue, interpreted as an NSSize structure.

This attribute can be read and written. This attribute cannot be read or written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES. This attribute is deprecated in QTKit version 7.6 and later.

Available in OS X v10.4 and later.

Deprecated in OS X v10.6.

Declared in QTMovie.h.

QTMovieCurrentTimeAttribute

The current time of a QTMovie object; the value for this key is of type NSValue, interpreted as a QTTime structure.

This attribute can be read and written. This attribute can be read and written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieDataSizeAttribute

The data size of a QTMovie. The value for this key is of type NSNumber, which is interpreted as a longlong.

This attribute can be read but not written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieDelegateAttribute

The delegate for a QTMovie object. The value for this key is of type NSObject.

This attribute can be read and written. This attribute can be read and written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieDisplayNameAttribute

The display name of a QTMovie object. A display name is stored as user data in a movie file and hence may differ from the base name of the movie’s filename or URL. The value for this key is of type NSString.

This attribute can be read and written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieDontInteractWithUserAttribute

When set in a dictionary passed to movieWithAttributes or initWithAttributes, this prevents QuickTime from interacting with the user during movie initialization. The value for this key is of type NSNumber, interpreted as a BOOL.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieDurationAttribute

The duration of a QTMovie object; the value for this key is of type NSValue, interpreted as a QTTime structure.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieEditableAttribute

The editable setting; the value for this key is of type NSNumber, interpreted as a BOOL. This value is YES if the movie can be edited.

This attribute can be read and written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieFileNameAttribute

The file name string of a QTMovie object; the value for this key is of type NSString.

This attribute can be read but not written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieHasApertureModeDimensionsAttribute

The aperture mode dimensions set on any track in this QTMovie object, even if those dimensions are all identical to the classic dimensions (as is the case for content with square pixels and no edge-processing region). The value for this key is of type NSNumber, interpreted as a BOOL.

This attribute can be read but not written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieHasAudioAttribute

The audio data setting; the value for this key is of type NSNumber, interpreted as a BOOL. This value is YES if the movie contains audio data.

This attribute can be read but not written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieHasDurationAttribute

The duration setting; the value for this key is of type NSNumber, interpreted as a BOOL. This value is YES if the movie has a duration. (Some types of movies, for instance QuickTime VR movies, have no duration.)

This attribute can be read but not written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieHasVideoAttribute

The video data setting; the value for this key is of type NSNumber, interpreted as a BOOL. This value is YES if the movie contains video data.

This attribute can be read but not written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieIsActiveAttribute

The active setting; the value for this key is of type NSNumber, interpreted as a BOOL.

This attribute can be read and written. This attribute can be read and written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieIsInteractiveAttribute

The interactive setting; the value for this key is of type NSNumber, interpreted as a BOOL. This value is YES if the movie is interactive.

This attribute can be read but not written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieIsLinearAttribute

The linear setting; the value for this key is of type NSNumber, interpreted as a BOOL. This value is YES if the movie is linear, as opposed to a non-linear QuickTime VR movie.

This attribute can be read but not written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieIsSteppableAttribute

The steppable setting; the value for this key is of type NSNumber, interpreted as a BOOL. This value is YES if the movie can step from frame to frame.

This attribute can be read but not written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieLoadStateAttribute

The load state value; the value for this key is of type NSNumber, interpreted as a long.

This attribute can be read but not written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Declared in QTMovie.h.

OS X v10.5 and later.

Deprecated in OS X v10.9.

QTMovieLoadStateErrorAttribute

The load state error of a QTMovie object; the value for this key is of type NSError.

This attribute can be read but not written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Declared in QTMovie.h.

QuickTime 7.6.3 and later.

Deprecated in OS X v10.9.

QTMovieLoopsAttribute

The looping setting; the value for this key is of type NSNumber, interpreted as a BOOL. This value is YES if the movie is set to loop, NO otherwise.

This attribute can be read and written. This attribute can be read and written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieLoopsBackAndForthAttribute

The palindrome looping setting; the value for this key is of type NSNumber, interpreted as a BOOL. This value is YES if the movie is set to loop back and forth. Note that QTMovieLoopsAttribute and QTMovieLoopsBackAndForthAttribute are independent and indeed exclusive. QTMovieLoopsAttribute is used to get and set the state of normal looping; QTMovieLoopsBackAndForthAttribute is used to get and set the state of palindrome looping.

This attribute can be read and written. This attribute can be read and written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieModificationTimeAttribute

The modification time of a QTMovie object; the value for this key is of type NSDate.

This attribute can be read but not written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieMutedAttribute

The mute setting; the value for this key is of type NSNumber, interpreted as a BOOL. This value is YES if the movie volume is muted.

This attribute can be read and written. This attribute can be read and written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieNaturalSizeAttribute

The natural size of a QTMovie object; the value for this key is of type NSValue, interpreted as an NSSize structure.

This attribute can be read but not written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMoviePlaysAllFramesAttribute

The play-all-frames setting; the value for this key is of type NSNumber, interpreted as a BOOL. This value is YES if the movie will play all frames.

This attribute can be read and written. This attribute can be read and written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMoviePlaysSelectionOnlyAttribute

The play-selection setting; the value for this key is of type NSNumber, interpreted as a BOOL. This value is YES if the movie will play only the current selection.

This attribute can be read and written. This attribute can be read and written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMoviePosterTimeAttribute

The movie poster time of a QTMovie object; the value for this key is of type NSValue, interpreted as a QTTime structure.

This attribute can be read and written. This attribute can be read and written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMoviePreferredMutedAttribute

The preferred mute setting; the value for this key is of type NSNumber, interpreted as a BOOL. This value is YES if the movie preferred mute setting is muted.

This attribute can be read and written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

The preferred settings refer to settings contained in the movie file (or movie data) itself. The actual settings refer to the actual values of those settings. For instance, a movie can have a preferred rate of 2, and a good movie playing application will respect that setting. But an application or the user can set the actual rate to some other value. The non-preferred settings can change dynamically, but the preferred settings will not.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMoviePreferredRateAttribute

The preferred rate; the value for this key is of type NSNumber, interpreted as a float.

This attribute can be read and written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

The preferred settings refer to settings contained in the movie file (or movie data) itself. The actual settings refer to the actual values of those settings. For instance, a movie can have a preferred rate of 2, and a good movie playing application will respect that setting. But an application or the user can set the actual rate to some other value. The non-preferred settings can change dynamically, but the preferred settings will not.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMoviePreferredVolumeAttribute

The preferred volume; the value for this key is of type NSNumber, interpreted as a float.

This attribute can be read and written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

The preferred settings refer to settings contained in the movie file (or movie data) itself. The actual settings refer to the actual values of those settings. For instance, a movie can have a preferred rate of 2, and a good movie playing application will respect that setting. But an application or the user can set the actual rate to some other value. The non-preferred settings can change dynamically, but the preferred settings will not.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMoviePreviewModeAttribute

The preview mode setting; the value for this key is of type NSNumber, interpreted as a BOOL. This value is YES if the movie is in preview mode.

This attribute can be read and written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMoviePreviewRangeAttribute

The preview range of a QTMovie object; the value for this key is of type NSValue, interpreted as a QTTimeRange structure.

This attribute can be read and written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieRateAttribute

The movie rate; the value for this key is of type NSNumber, interpreted as a float.

This attribute can be read and written. This attribute can be read and written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieRateChangesPreservePitchAttribute

When the playback rate is not unity, audio must be resampled in order to play at the new rate. The default resampling affects the pitch of the audio (for example, playing at 2x speed raises the pitch by an octave, 1/2x lowers an octave). If this property is set on the movie, an alternative algorithm is used, which alters the speed without changing the pitch. Since this is more computationally expensive, this property may be silently ignored on some slow CPUs.

This attribute can be read but not written; it must be among the initialization attributes to have any effect. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieSelectionAttribute

The selection range of a QTMovie object; the value for this key is of type NSValue, interpreted as a QTTimeRange structure.

This attribute can be read and written. This attribute cannot be read or written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieTimeScaleAttribute

The time scale of a QTMovie object; the value for this key is of type NSNumber, interpreted as a long. This attribute can be read and (in OS X v10.5 and later) written; in earlier versions of OS X, this attribute is readable only. In general, you should set this attribute only on newly-created movies or on movies that have not been edited. Also, you should only increase the time scale value, and you should try to use integer multiples of the existing time scale.

This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieURLAttribute

The URL of a QTMovie object; the value for this key is of type NSURL.

This attribute can be read but not written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieVolumeAttribute

The movie volume; the value for this key is of type NSNumber, interpreted as a float.

This attribute can be read and written. This attribute can be read and written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

Aperture Modes

When a movie is in clean, production, or encoded pixels aperture mode, each track's dimensions are overridden by special dimensions for that mode. The original track dimensions are preserved and can be restored by setting the movie into classic aperture mode. Aperture modes are not saved in movies. The associated value is of type NSString and is assumed to be one of the following strings:

NSString * const QTMovieApertureModeClassic;
NSString * const QTMovieApertureModeClean;
NSString * const QTMovieApertureModeProduction;
NSString * const QTMovieApertureModeEncodedPixels;
Constants
QTMovieApertureModeClassic

No aspect ratio or clean aperture correction is performed. This is the default aperture mode and provides compatibility with behavior in QuickTime 7.0.x and earlier. If you call -[QTTrack setDimensions], the movie is automatically switched to classic mode.

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieApertureModeClean

An aperture mode for general display. Where possible, video will be displayed at the correct pixel aspect ratio, trimmed to the clean aperture. A movie in clean aperture mode sets each track’s dimensions to match the size returned by -[QTTrack apertureModeDimensionsForMode:QTMovieApertureModeClean].

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieApertureModeProduction

An aperture mode for modal use in authoring applications. Where possible, video will be displayed at the correct pixel aspect ratio, but without trimming to the clean aperture so that the edge processing region can be viewed. A movie in production aperture mode sets each track's dimensions to match the size returned by -[QTTrack apertureModeDimensionsForMode:QTMovieApertureModeProduction].

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieApertureModeEncodedPixels

An aperture mode for technical use. Displays all encoded pixels with no aspect ratio or clean aperture compensation. A movie in encoded pixels aperture mode sets each track's dimensions to match the size returned by -[QTTrack apertureModeDimensionsForMode:QTMovieApertureModeEncodedPixels].

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

Movie Load State Values

The movie load state values. The attributeForKey:QTMovieLoadStateAttribute returns an NSNumber that wraps a long integer; the enumerated constants shown here are the possible values of that long integer.

enum {
   QTMovieLoadStateError = -1L,
   QTMovieLoadStateLoading = 1000,
   QTMovieLoadStateLoaded = 2000,
   QTMovieLoadStatePlayable = 10000,
   QTMovieLoadStatePlaythroughOK = 20000,
   QTMovieLoadStateComplete = 100000L
};
typedef NSInteger QTMovieLoadState;
Constants
QTMovieLoadStateError

An error occurred while loading the movie.

Available in OS X v10.5 and later.

Declared in QTMovie.h.

QTMovieLoadStateLoading

The movie is loading.

Available in OS X v10.5 and later.

Declared in QTMovie.h.

QTMovieLoadStateLoaded

The movie atom has loaded; it’s safe to query movie properties.

Available in OS X v10.5 and later.

Declared in QTMovie.h.

QTMovieLoadStatePlayable

The movie has loaded enough media data to begin playing.

Available in OS X v10.5 and later.

Declared in QTMovie.h.

QTMovieLoadStatePlaythroughOK

The movie has loaded enough media data to play through to the end.

Available in OS X v10.5 and later.

Declared in QTMovie.h.

QTMovieLoadStateComplete

The movie has loaded completely.

OS X v10.5 and later.

Declared in QTMovie.h.

Dictionary Items Passed to QTMovie Notifications

The following constants specify items in dictionaries passed to QTMovie notifications and delegate methods.

NSString * const QTMovieMessageNotificationParameter;
NSString * const QTMovieRateDidChangeNotificationParameter;
NSString * const QTMovieStatusFlagsNotificationParameter;
NSString * const QTMovieStatusCodeNotificationParameter;
NSString * const QTMovieStatusStringNotificationParameter;
NSString * const QTMovieTargetIDNotificationParameter;
NSString * const QTMovieTargetNameNotificationParameter;
Constants
QTMovieMessageNotificationParameter

Used as a key in the userInfo dictionary passed to the QTMovieMessageNotification notification to indicate the message. The associated value is an NSString.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieRateDidChangeNotificationParameter

Used as a key in the userInfo dictionary passed to the QTMovieRateDidChangeNotification notification to indicate the new playback rate. The associated value is an NSNumber that holds a float.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieStatusFlagsNotificationParameter

Used as a key in the userInfo dictionary passed to the QTMovieStatusStringPostedNotification notification to indicate status flags. The associated value is an NSNumber that holds a long.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieStatusCodeNotificationParameter

Used as a key in the userInfo dictionary passed to the QTMovieStatusStringPostedNotification notification to indicate a status code (or error code). The associated value is an NSNumber that holds an int.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieStatusStringNotificationParameter

Used as a key in the userInfo dictionary passed to the QTMovieStatusStringPostedNotification notification to indicate a status string.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieTargetIDNotificationParameter

Used as a key in the dictionary passed to the externalMovie: delegate method to indicate that the delegate should return a QTMovie object that has the movie ID specified by the key’s value.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieTargetNameNotificationParameter

Used as a key in the dictionary passed to the externalMovie: delegate method to indicate that the delegate should return a QTMovie object that has the movie name specified by the key’s value.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

Dictionary Keys For Movie Export

The following constants are dictionary keys that you can use to specify movie attributes, using the writeToFile method.

NSString * const QTMovieExport;
NSString * const QTMovieExportType;
NSString * const QTMovieFlatten;
NSString * const QTMovieExportSettings;
NSString * const QTMovieExportManufacturer;
Constants
QTMovieExport

The movie export setting; the value for this key is of type NSNumber, interpreted as a BOOL.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieExportType

The movie export type; the value for this key is of type NSNumber, interpreted as a long.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieFlatten

The movie flatten setting; the value for this key is of type NSNumber, interpreted as a BOOL.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieExportSettings

The movie export settings; the value of this key is of type NSData, interpreted as a QTAtomContainer.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieExportManufacturer

The export manufacturer value; the value for this key is of type NSNumber, interpreted as a long.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

Dictionary Keys For Image Codecs

The following constants are dictionary keys that you can use to specify movie attributes, using the addImage method.

NSString * const QTAddImageCodecType;
NSString * const QTAddImageCodecQuality;
Constants
QTAddImageCodecType

The image codec string; the value for this key is of type NSString.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTAddImageCodecQuality

The image codec value; the value for this key is of type NSNumber.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

Dictionary of Frame Image Attributes

The following is a dictionary of attributes that can contain frame image keys, using the frameImageAtTime:withAttributes:error: method.

NSString * const QTMovieFrameImageSize;
NSString * const QTMovieFrameImageType;
NSString * const QTMovieFrameImageTypeNSImage;
NSString * const QTMovieFrameImageTypeCGImageRef;
NSString * const QTMovieFrameImageTypeCIImage;
NSString * const QTMovieFrameImageTypeCVPixelBufferRef;
NSString * const QTMovieFrameImageTypeCVOpenGLTextureRef;
NSString * const QTMovieFrameImageRepresentationsType;
NSString * const QTMovieFrameImageOpenGLContext;
NSString * const QTMovieFrameImagePixelFormat;
NSString * const QTMovieFrameImageDeinterlaceFields;
NSString * const QTMovieFrameImageHighQuality;
NSString * const QTMovieFrameImageSingleField;
NSString * const QTMovieFrameImageSessionMode;
Constants
QTMovieFrameImageSize

Size of the image. The value is an NSValue containing an NSSize record. The default image size is the current movie size.

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieFrameImageType

Type of the image. The value is an NSString. The default image type is NSImage.

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieFrameImageTypeNSImage

A value for the QTMovieFrameImageType key of the QTMovie frameImageAtTime:withAttributes:error: attributes dictionary. Specifies that the type of image returned should be an NSImage.

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieFrameImageTypeCGImageRef

A value for the QTMovieFrameImageType key of the QTMovie frameImageAtTime:withAttributes:error: attributes dictionary. Specifies that the type of image returned should be a CGImageRef.

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieFrameImageTypeCIImage

A value for the QTMovieFrameImageType key of the QTMovie frameImageAtTime:withAttributes:error: attributes dictionary. Specifies that the type of image returned should be a CIImage.

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieFrameImageTypeCVPixelBufferRef

A value for the QTMovieFrameImageType key of the QTMovie frameImageAtTime:withAttributes:error: attributes dictionary. Specifies that the type of image returned should be a CVPixelBufferRef.

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieFrameImageTypeCVOpenGLTextureRef

A value for the QTMovieFrameImageType key of the QTMovie frameImageAtTime:withAttributes:error: attributes dictionary. Specifies that the type of image returned should be a CVOpenGLTextureRef. Clients that specify this attribute must also specify the OpenGL context and pixel format for the texture using the QTMovieFrameImageOpenGLContext and QTMovieFrameImagePixelFormat attribute keys.

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieFrameImageRepresentationsType

For NSImage, the image representations in the image. Value is an NSArray of NSString; strings are, for example, NSBitmapImageRep class description. The default is NSBitmapImageRep.

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieFrameImageOpenGLContext

For CVOpenGLTextureRef, the OpenGL context to use. The value is an NSValue (CGLContextObj).

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieFrameImagePixelFormat

For CVOpenGLTextureRef, the pixel format to use. Value is an NSValue (CGLPixelFormatObj).

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieFrameImageDeinterlaceFields

Image is de-interlaced. Value is an NSNumber (BOOL) (default = YES).

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieFrameImageHighQuality

Image is high quality. Value is an NSNumber (BOOL) (default = YES).

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieFrameImageSingleField

Image is single field. Value is an NSNumber (BOOL) (default = YES). The returned object is an autorelease object.

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieFrameImageSessionMode

Indicates that two or more calls to frameImageAtTime:withAttributes:error: will be made on the same QTMovie object.

By adding this key with the associated value that is an NSNumber wrapping the BOOLYES to the dictionary of attributes, an application indicates that it will make more than one call to frameImageAtTime:withAttributes:error: on the same QTMovie object. This knowledge permits QTMovie to cache certain objects and data structures used to generate a frame image, thereby improving performance. When the caller has obtained all the frame images desired from a given QTMovie object, the caller should follow those session calls with a call where this value is NO; this is a signal to QTMovie to dispose of that cached data.

Declared in QTMovie.h.

OS X v10.6; QuickTime 7.6.3 and later.

Deprecated in OS X v10.9.

Data Locator Attributes

The following constants are data locators that you can use to specify movie attributes, using the movieWithAttributes and initWithAttributes methods.

NSString * const QTMovieDataReferenceAttribute;
NSString * const QTMoviePasteboardAttribute;
NSString * const QTMovieDataAttribute;
Constants
QTMovieDataReferenceAttribute

The data reference of a QTMovie object;the value for this key is of type QTDataReference.

This attribute can be read but not written. This attribute can be read but not written when the movie has been initialized with QTMovieOpenForPlaybackAttribute set to YES.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMoviePasteboardAttribute

The pasteboard setting of a QTMovie object.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieDataAttribute

The data of a QTMovie object.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

Movie Instantiation Options

The following constants are movie instantiation options that you can use to specify movie attributes, using the movieWithAttributes and initWithAttributes methods.

NSString * const QTMovieFileOffsetAttribute;
NSString * const QTMovieResolveDataRefsAttribute;
NSString * const QTMovieAskUnresolvedDataRefsAttribute;
NSString * const QTMovieOpenAsyncOKAttribute;
NSString * const QTMovieOpenAsyncRequiredAttribute;
NSString * const QTMovieOpenForPlaybackAttribute;
Constants
QTMovieFileOffsetAttribute

The file offset value; the value for this key is of type NSNumber, interpreted as a long long.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieResolveDataRefsAttribute

Indicates whether external data references in a movie file should be resolved (NSNumber YES) or not resolved (NSNumber NO).

A movie file can contain references to media data in other locations. By default, QTMovie attempts to resolve these references at the time that the movie file is opened and a QTMovie object is instantiated. You can prevent that resolution from occurring by passing an NSNumber wrapping the value NO as the value of this attribute.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieAskUnresolvedDataRefsAttribute

Indicates whether the user should be prompted to help find any unresolved data references (NSNumber YES) or not (NSNumber NO).

When the value of the QTMovieResolveDataRefsAttribute attribute is an NSNumber wrapping the value YES and a movie file contains unresolved data references, this attribute indicates whether the user should be prompted to help find the missing referenced data (NSNumber YES) or not (NSNumber NO). Typically, QTMovie will display a dialog box that allows the user to navigate to the file or URL containing the referenced data. By setting this attribute to NO, you can prevent that dialog box from being displayed and thereby speed up the movie opening and initialization process.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieOpenAsyncOKAttribute

Indicates whether a movie file can be opened asynchronously if possible (NSNumber YES) or not (NSNumber NO).

Opening a movie file and initializing a QTMovie object for that file may require a considerable amount of time, perhaps to convert the data in the file from one format to another. By setting this attribute to an NSNumber wrapping the value YES, you grant QTMovie permission to return a non-nil QTMovie identifier to your application immediately and then to continue processing the file data internally. If a movie is opened asynchronously, you must monitor the movie load state and ensure that it has reached the appropriate threshold before attempting to perform certain operations on the movie. For instance, you cannot export or copy a QTMovie object until its load state has reached QTMovieLoadStateComplete.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieOpenAsyncRequiredAttribute

Indicates whether the QTMovie must be opened asynchronously (NSNumber YES) or not (NSNumber NO).

Set this attribute to an NSNumber wrapping YES to indicate that all operations necessary to open the movie file (or other container) and create a valid QTMovie object must occur asynchronously. That is to say, the methods +movieWithAttributes:error: and -initWithAttributes:error: must return almost immediately, performing any lengthy operations on another thread. Your application can monitor the movie load state to determine the progress of those operations.

If you require asynchronous opening but QTMovie is unable to honor your request, then the methods +movieWithAttributes:error: and -initWithAttributes:error: return nil with an NSError having the error domain QTKitErrorDomain and code QTErrorMovieOpeningCannotBeAsynchronous.

Declared in QTMovie.h.

OS X v10.6 and later; QuickTime 7.6.3 and later.

Deprecated in OS X v10.9.

QTMovieOpenForPlaybackAttribute

Indicates whether the QTMovie will be used only for playback (NSNumber YES) or not (NSNumber NO).

Set this attribute to an NSNumber wrapping YES to indicate that you intend to use movie playback methods (such as -play or -stop, or corresponding movie view methods such as -play: or -pause:) to control the movie, but do not intend to use other methods that edit, export, or in any way modify the movie. Knowing that you need playback services only may allow QTMovie to use more efficient code paths for some media files.

This attribute is meaningful only when added to the dictionary passed to -initWithAttributes:error:. In particular, setting this attribute on a QTMovie object that is already open has no effect.

Declared in QTMovie.h.

OS X v10.6 and later; QuickTime 7.6.3 and later.

Deprecated in OS X v10.9.

Movie Chapter Information

These constants allow applications to get information about a movie and its chapters, and to navigate within a movie by chapters. Since chapters are a reasonably common feature of movies and podcasts, QTKit enables developers to create them.

NSString * const QTMovieChapterName;
NSString * const QTMovieChapterStartTime;
NSString * const QTMovieChapterTargetTrackAttribute;
Constants
QTMovieChapterName

A key indicating the chapter name in the dictionaries that are array elements in the array returned by QTMoviechapters or passed to QTMovieaddChapters:withAttributes:error.

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieChapterStartTime

A key indicating the chapter start time in the dictionaries that are array elements in the array returned by QTMoviechapters or passed to QTMovieaddChapters:withAttributes:error.

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

QTMovieChapterTargetTrackAttribute

A key indicating the track in the QTMovie object that is the target of the chapter track.

Available in OS X v10.5 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

Pasteboard Support

The following constant is the type of movie data passed on the pasteboard.

NSString * const QTMoviePasteboardType;
Constants
QTMoviePasteboardType

Specifies the type of movie data passed on the pasteboard.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

Exceptions

The following exception is raised when calling a method requiring editing or modification of a movie that is uneditable.

NSString * const QTMovieUneditableException;
Constants
QTMovieUneditableException

Raised when the developer tries to call a method that requires editing or modifying the movie on an uneditable movie.

Available in OS X v10.4 and later.

Deprecated in OS X v10.9.

Declared in QTMovie.h.

Notifications

QTMovieApertureModeDidChangeNotification

Issued when the aperture mode of the target QTMovie object changes.
Availability
Declared In
QTMovie.h

QTMovieChapterDidChangeNotification

Issued when the chapter associated with QTMovie changes.

This notification contains no information in the userInfo dictionary.

Availability
Declared In
QTMovie.h

QTMovieChapterListDidChangeNotification

Issued when the chapter list associated with QTMovie changes.

This notification contains no information in the userInfo dictionary.

Availability
Declared In
QTMovie.h

QTMovieCloseWindowRequestNotification

Sent when a request is made to close the movie’s window.

This notification contains no information in the userInfo dictionary.

Availability
Declared In
QTMovie.h

QTMovieDidEndNotification

Sent when the movie is “done” or at its end.

This notification contains no userInfo parameters. It is equivalent to the standard player controller’s mcActionMovieFinished action.

Availability
Declared In
QTMovie.h

QTMovieEditabilityDidChangeNotification

Sent when the editable state of a movie has changed.

Availability
Declared In
QTMovie.h

QTMovieEditedNotification

Sent when a movie has been edited.

This notification contains no userInfo dictionary.

Availability
Declared In
QTMovie.h

QTMovieEnterFullScreenRequestNotification

Sent when a request is made to play back a movie in full screen mode.

This notification contains no information in the userInfo dictionary.

Availability
Declared In
QTMovie.h

QTMovieExitFullScreenRequestNotification

Sent when a request is made to play back a movie in normal windowed mode.

This notification contains no information in the userInfo dictionary.

Availability
Declared In
QTMovie.h

QTMovieLoadStateDidChangeNotification

Sent when the load state of a movie has changed.

Availability
Declared In
QTMovie.h

QTMovieLoopModeDidChangeNotification

Sent when a change is made in a movie’s looping mode.

This notification contains no information in the userInfo dictionary.

Availability
Declared In
QTMovie.h

QTMovieMessageStringPostedNotification

Sent when a movie message has been received by the movie controller.

Movie messages can be sent to an application by wired actions (for instance, a wired sprite) or by code that issues the mcActionShowMessageString movie controller action. The userInfo dictionary contains a single entry whose value is of type NSString, which is the movie message.

Availability
Declared In
QTMovie.h

QTMovieRateDidChangeNotification

Sent when the rate of a movie has changed.

The userInfo dictionary contains a single entry whose value is of type NSNumber that represents a float, which is the new rate.

Availability
Declared In
QTMovie.h

QTMovieSelectionDidChangeNotification

Sent when the selection of a movie has changed.

This notification contains no userInfo dictionary.

Availability
Declared In
QTMovie.h

QTMovieNaturalSizeDidChangeNotification

Posted whenever the natural size (that is, the original dimensions of the movie when it was authored) changes, either because the movie was edited or because new information about the movie was loaded asynchronously.

All clients that display movies using dimensions based on the QTMovieNaturalSizeAttribute should respond to this notification to update their display as necessary.

Availability
Declared In
QTMovie.h

QTMovieSizeDidChangeNotification

Sent when the size of a movie has changed.

This notification contains no userInfo dictionary.

Availability
Declared In
QTMovie.h

QTMovieStatusStringPostedNotification

Status messages can be sent by QuickTime’s streaming components or by any code that wants to display a message in the movie controller bar status area.

The userInfo dictionary contains a single entry whose value is of type NSString, which is the status message.

The following are keys (notification parameters) for userInfo items for the QTMovieStatusStringPostedNotification notification QTMovieStatusCodeNotificationParameter and QTMovieStatusStringNotificationParameter.

A status string notification can indicate an error (in which case QTMovieStatusCodeNotificationParameter will have a value), or it can contain a string (in which case QTMovieStatusStringNotificationParameter will have a value). For more information, see mcActionShowStatusString.

Availability
Declared In
QTMovie.h

QTMovieTimeDidChangeNotification

Sent when the time in a movie has changed.

The QTMovieTimeDidChangeNotification is fired whenever the movie time changes to a time other than what it would be during normal playback. So, for example, this notification is not fired every frame.

Availability
Declared In
QTMovie.h

QTMovieVolumeDidChangeNotification

Sent when the volume of a movie has changed.

Availability
Declared In
QTMovie.h