Advanced Search

Log In | Not a Member?

Contact ADC

Next Page > Hide TOC

QTMovie Class Reference

Overview

The QTMovie class represents both a QuickTime movie and a movie controller. A movie is a collection of playable and editable media content. It describes the sources and types of the media in that collection and their spatial and temporal organization. These collections may be used for presentation (such as playback on the screen) or for the organization of media for processing (such as composition and transcoding to a different compression type). The collection may be as simple as a single file that plays at its natural size for its intrinsic duration, or it may be very complex (with multiple sources of content, rich composition rules, interactivity, and a variety of contingencies).

Just as a QuickTime movie contains a set of tracks, each of which defines the type, the segments, and the ordering of the media data it presents, a QTMovie object is associated with instances of the QTTrack class. In turn, a QTTrack object is associated with a single QTMedia object.

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.

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

• + canInitWithFile:
• + canInitWithURL:
• + canInitWithPasteboard:
• + canInitWithDataReference:
• – initWithPasteboard:error:

Getting a List of Supported File Types

• + movieFileTypes:
• + movieTypesWithOptions:
• + movieUnfilteredFileTypes
• + movieUnfilteredPasteboardTypes

Creating a Movie

• + movie
• + movieNamed:error:
• + movieWithData:error:
• + movieWithURL:error:
• + movieWithPasteboard:error:
• + movieWithFile:error:
• + movieWithDataReference:error:
• + movieWithQuickTimeMovie:disposeWhenDone:error:
• + movieWithAttributes:error:

Controlling Movie Playback

• – autoplay
• – play
• – stop
• – gotoBeginning
• – gotoEnd
• – gotoNextSelectionPoint
• – gotoPreviousSelectionPoint
• – gotoPosterFrame
• – setCurrentTime:
• – stepForward
• – stepBackward

Managing Threaded Operations of Movie Objects

• + enterQTKitOnThread
• + enterQTKitOnThreadDisablingThreadSafetyProtection
• + exitQTKitOnThread
• – attachToCurrentThread
• – detachFromCurrentThread

Initializing a QTMovie

• – initWithFile:error:
• – initWithURL:error:
• – initWithData:error:
• – initWithDataReference:error:
• – initWithMovie:timeRange:error:
• – initWithQuickTimeMovie:disposeWhenDone:error:
• – initWithAttributes:error:

Getting Information About a Movie and Its Chapters

• – hasChapters
• – chapterCount
• – chapters
• – addChapters
• – removeChapters
• – startTimeOfChapter:
• – chapterIndexForTime:

Inspecting Movie Properties

• – duration
• – currentTime
• – rate
• – volume
• – muted
• – movieWithTimeRange:error:
• – attributeForKey:
• – movieAttributes

Managing QTMovie Idling States

• – setIdling:
• – idling

Setting QTMovie Properties

• – setRate:
• – setVolume:
• – setMuted:

Setting Movie Attributes

• – setAttribute:forKey:
• – setMovieAttributes:

Supporting Aperture Modes

• – generateApertureModeDimensions
• – removeApertureModeDimensions

Getting and Setting Selection Times

• – selectionStart
• – selectionEnd
• – selectionDuration
• – setSelection:

Getting Movie Tracks

• – tracks
• – tracksOfMediaType:

Getting Movie Images

• – posterImage
• – currentFrameImage
• – frameImageAtTime:
• – frameImageAtTime:withAttributes:error:

Storing Movie Data

• – initToWritableDataReference:error:
• – initToWritableFile:error:
• – initToWritableData:error:
• – movieFormatRepresentation
• – writeToFile:withAttributes:
• – writeToFile:withAttributes:error:

Editing a Movie

• – replaceSelectionWithSelectionFromMovie:
• – appendSelectionFromMovie:
• – insertSegmentOfMovie:timeRange:atTime:
• – insertSegmentOfMovie:fromRange:scaledToRange:
• – insertEmptySegmentAt:
• – deleteSegment:
• – scaleSegment:newDuration:
• – addImage:forDuration:withAttributes:

Saving a Movie

• – canUpdateMovieFile
• – updateMovieFile

Getting QTMovie Primitives

• – quickTimeMovie
• – quickTimeMovieController

Getting and Setting QTMovie Delegates

• – delegate
• – setDelegate:
• – externalMovie:  delegate method
• – movieShouldTask:  delegate method
• – movie:shouldContinueOperation:withPhase:atPercent:withAttributes:  delegate method
• – movie:linkToURL:  delegate method

Class Methods

canInitWithDataReference:

Returns YES if the specified data reference can be used to initialize a QTMovie object.

+ (BOOL)canInitWithDataReference:(QTDataReference*)dataReference

Availability

• Available in Mac OS X v10.3 and later.

Declared In

canInitWithFile:

Returns YES if the contents of the specified file can be used to initialize a QTMovie object.

+ (BOOL)canInitWithFile:(NSString *)fileName

Availability

• Available in Mac OS X v10.3 and later.

Declared In

canInitWithPasteboard:

Returns YES if the contents of the specified pasteboard can be used to initialize a QTMovie object.

+ (BOOL)canInitWithPasteboard:(NSPasteboard *)pasteboard

Availability

• Available in Mac OS X v10.3 and later.

Declared In

canInitWithURL:

Returns YES if the contents of the specified URL can be used to initialize a QTMovie object.

+ (BOOL)canInitWithURL:(NSURL *)url

Availability

• Available in Mac OS X v10.3 and later.

Declared In

enterQTKitOnThread

Performs any QuickTime-specific initialization for the current (non-main) thread; must be paired with a call to exitQTKitOnThread.

+ (void)enterQTKitOnThread

Availability

• Mac OS X v10.5 and later.

Declared In

enterQTKitOnThreadDisablingThreadSafetyProtection

Performs any QuickTime-specific initialization for the current (non-main) thread, allowing non-threadsafe components; must be paired with a call to exitQTKitOnThread.

+ (void)enterQTKitOnThreadDisablingThreadSafetyProtection

Availability

• Mac OS X v10.5 and later.

Declared In

exitQTKitOnThread

Performs any QuickTime-specific shut-down for the current (non-main) thread; must be paired with a call to enterQTKitOnThread or enterQTKitOnThreadDisablingThreadSafetyProtection.

+ (void)exitQTKitOnThread

Availability

• Mac OS X v10.5 and later.

Declared In

movie

Creates an empty QTMovie object.

+ (id)movie

Availability

• Available in Mac OS X v10.3 and later.

Declared In

movieFileTypes:

Returns an array of file types that can be opened as QuickTime movies.

+ (NSArray *)movieFileTypes:(QTMovieTypeOptions)types

Discussion

Passing zero as the options parameter returns an array of all the common file types that QuickTime can open in place on the current system. This array includes the file type .mov and .mqv, and any files types that can be opened using a movie importer that does not need to write data into a new file while performing the import. This array excludes any file types for still images and any file types that require an aggressive movie importer (for instance, the movie importer for text files). The following values can be used to include some or all of the file types that are normally excluded:

enum {

    QTIncludeStillImageTypes  =  1 << 0,

    QTIncludeTranslatableTypes =  1 << 1,

    QTIncludeAggressiveTypes =  1 << 2,

    QTIncludeCommonTypes = 0,

    QTIncludeAllTypes = 0xffff

} QTMovieFileTypeOptions;

Availability

• Available in Mac OS X v10.3 and later.

Declared In

movieNamed:error:

Creates a QTMovie object initialized with the data from the QuickTime movie of the specified name in the application’s bundle.

+ (id)movieNamed:(NSString *)name error:(NSError **)errorPtr

Discussion

If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

movieTypesWithOptions:

Returns an array of UTIs that QuickTime can open.

+ (NSArray *)movieTypesWithOptions:(QTMovieFileTypeOptions)types

Discussion

This method gets an array of NSString objects that specify the uniform type identifiers (UTIs) for types of files that QuickTime can open. The types parameter is interpreted just like the types parameter to + (NSArray *)movieFileTypes:(QTMovieFileTypeOptions)types.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

movieUnfilteredFileTypes

Returns an array of file types that can be used to initialize a QTMovie object.

+ (NSArray *)movieUnfilteredFileTypes

Availability

• Available in Mac OS X v10.3 and later.

Declared In

movieUnfilteredPasteboardTypes

Returns an array of pasteboard types that can be used to initialize a QTMovie object.

+ (NSArray *)movieUnfilteredPasteboardTypes

Availability

• Available in Mac OS X v10.3 and later.

Declared In

movieWithAttributes:error:

Creates a QTMovie object initialized with the attributes specified in attributes.

+ (id)movieWithAttributes:(NSDictionary *)attributes error:(NSError **)errorPtr

Discussion

If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

A new QTMovie object is created using the specified attributes. There are three types of attributes that can be included in this dictionary:

• Attributes that specify the location of the movie data

• Attributes that specify how the movie is to be instantiated

• Attributes that specify playback characteristics of the movie or other properties of the QTMovie object

The following is a list of the keys that specify the location of the movie data; at least one of these must occur in the dictionary. If more than one occurs, the first one in the dictionary is used.

The following is a list of the keys that specify movie instantiation options; none of these keys is required. If a key is missing, the specified default value is used.

The following is a list of the new keys that specify movie playback characteristics or other properties of the QTMovie object; most other existing movie attributes can be included as well.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

movieWithData:error:

Creates a QTMovie object initialized with the data specified by data.

+ (id)movieWithData:(NSData *)data error:(NSError **)errorPtr

Discussion

If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

movieWithDataReference:error:

Creates a QTMovie object intitalized with the data specified by the data reference dataReference.

+ (id)movieWithDataReference:(QTDataReference *)dataReference error:(NSError **)errorPtr

Discussion

If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

movieWithFile:error:

Creates a QTMovie object initialized with the data in the file specified by the name fileName.

+ (id)movieWithFile:(NSString *)fileName error:(NSError **)errorPtr

Discussion

The fileName is assumed to be a full path name for a file.

If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

movieWithPasteboard:error:

Creates a QTMovie object initialized with the contents of the pasteboard specified by pasteboard.

+ (id)movieWithPasteboard:(NSPasteboard *)pasteboard error:(NSError **)errorPtr

Discussion

These contents can be a QuickTime movie (of type Movie), a file path, or data of type QTMoviePasteboardType.

If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

movieWithQuickTimeMovie:disposeWhenDone:error:

Creates a QTMovie object initialized with the data from an existing QuickTime movie movie.

+ (id)movieWithQuickTimeMovie:(Movie)movie disposeWhenDone:(BOOL)dispose error:(NSError **)errorPtr

Discussion

The dispose parameter (a BOOL) indicates whether the QTKit should call DisposeMovie on the specified movie when the QTMovie object is deallocated. Passing YES effectively transfers “ownership” of the Movie to the QTKit. (Note that most applications will probably want to pass YES; passing NO means that the application wants to call DisposeMovie itself, perhaps so that it can operate on a Movie after it has been disassociated with a QTMovie object.)

If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Note that command-line tools that pass NO for the disposeWhenDone parameter must make sure to release the active autorelease pool before calling DisposeMovie on the specified QuickTime movie. Failure to do this may result in a crash. Tools that need to call DisposeMovie before releasing the main autorelease pool can create another autorelease pool associated with the movie.

Availability

• Available in Mac OS X v10.3 and later.
• Not available to 64-bit applications.

Declared In

movieWithURL:error:

Creates a QTMovie object initialized with the data in the URL specified by url.

+ (id)movieWithURL:(NSURL *)url error:(NSError **)errorPtr

Discussion

If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

Instance Methods

addChapters

Adds chapters to the receiver using the information specified in the chapters array. 

- (void)addChapters:(NSArray *)chapters withAttributes:(NSDictionary *)attributes error:(NSError **)errorPtr

Discussion

Each array element is an NSDictionary containing key-value pairs. Currently two keys are defined for this dictionary, QTMovieChapterName and QTMovieChapterStartTime. The value for the QTMovieChapterName key is an NSString object that is the chapter name. The value for the QTMovieChapterStartTime key is an NSValue object that wraps a QTTime structure that indicates the start time of the chapter. The receiving QTMovie object must be editable or an exception will be raised.

The attributes dictionary specifies additional attributes for the chapters. Currently only one key is recognized for this dictionary, QTMovieChapterTargetTrackAttribute, which specifies the QTTrack in the receiver that is the target of the chapters; if none is specified, this method uses first video track in movie. If no video track is in the movie, this method uses the first audio track in the movie. If no audio track is in the movie, this method uses the first track in the movie. If an error occurs and errorPtr is non-NULL, then an NSError object is returned in that location.

Availability

• Mac OS X v10.5 and later.

addImage:forDuration:withAttributes:

Adds an image for the specified duration to the receiver, using attributes specified in the attributes dictionary.

- (void)addImage:(NSImage *)image forDuration:(QTTime)duration withAttributes:(NSDictionary *)attributes

Discussion

Keys in the dictionary can be QTAddImageCodecType to select a codec type and QTAddImageCodecQuality to select a quality. Qualities are expected to be specified as NSNumbers, using the codec values like codecNormalQuality. (See ImageCompression.h for the complete list.) The attributes dictionary can also contain a value for the QTTrackTimeScaleAttribute key, which is used as the time scale of the new track, should one need to be created. The default time scale for a new track is 600.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

appendSelectionFromMovie:

Appends to a QTMovie the current selection in movie.

- (void)appendSelectionFromMovie:(id)movie

Discussion

If the movie is not editable, this method raises an exception.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

attachToCurrentThread

Attaches the receiver to the current thread; returns YES if successful, NO otherwise.

- (BOOL)attachToCurrentThread

Availability

• Mac OS X v10.5 and later.

Declared In

attributeForKey:

Returns the current value of the movie attribute attributeKey.

- (id)attributeForKey:(NSString *)attributeKey

Discussion

A list of supported movie attributes and their acceptable values can be found in the “Constants” section.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

autoplay

Sets a movie to start playing when a sufficient amount of media data is available.

- (void)autoplay

Discussion

The autoplay method configures a QTMovie object to begin playing as soon as enough data is available that the playback can continue uninterrupted to the end of the movie. This is most useful for movies being loaded from a remote URL or from an extremely slow local device. For movies stored on most local devices, this method has the same effect as the -[QTMovie play] method.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

canUpdateMovieFile

Indicates whether a movie file can be updated with changes made to the movie object.

- (BOOL)canUpdateMovieFile

Discussion

This method returns NO if any of the following conditions are true:

• The movie is not associated with a file.

• The movie is not savable (has 'nsav' user data set to 1).

• The movie file is not writable.

• The movie file does not contain a movie atom (indicating that the movie was imported from a non-movie format).

Otherwise, the method returns YES.

Using this method, an application can check first to see if the movie file can be updated; if not, it can prompt the user for a new name and location of a file in which to save the updated movie.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

chapterCount

Returns the number of chapters in the receiver, or 0 if there are no chapters.

- (NSInteger)chapterCount

Availability

• Mac OS X v10.5 and later.

Declared In

chapterIndexForTime:

Returns the 0-based index of the chapter that contains the specified movie time.

- (NSInteger)chapterIndexForTime:(QTTime)time

Availability

• Mac OS X v10.5 and later.

Declared In

chapters

Returns an NSArray containing information about the chapters in the receiver.

- (NSArray *)chapters

Discussion

Each array element is an NSDictionary containing key-value pairs. Currently two keys are defined for this dictionary, QTMovieChapterName and QTMovieChapterStartTime. The value for the QTMovieChapterName key is an NSString object that is the chapter name. The value for the QTMovieChapterStartTime key is an NSValue object that wraps a QTTime structure that indicates the start time of the chapter.

Availability

• Mac OS X v10.5 and later.

Declared In

currentFrameImage

Returns an NSImage for the frame at the current time in a QTMovie.

- (NSImage *)currentFrameImage

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – frameImageAtTime:
• – posterImage

Declared In

currentTime

Returns the current time of a QTMovie object as a structure of type QTTime.

- (QTTime)currentTime

Availability

• Available in Mac OS X v10.3 and later.

Declared In

delegate

Returns the delegate of a QTMovie object.

- (id)delegate

Availability

• Available in Mac OS X v10.3 and later.

Declared In

deleteSegment:

Deletes from a QTMovie the segment delimited by segment.

- (void)deleteSegment:(QTTimeRange)segment

Discussion

If the movie is not editable, this method raises an exception.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

detachFromCurrentThread

Detaches the receiver from the current thread; returns YES if successful, NO otherwise.

- (BOOL)detachFromCurrentThread

Discussion

These methods allow applications to manage QTMovie objects on non-main threads. Before any QTKit operations can be performed on a secondary thread, either enterQTKitOnThread or enterQTKitOnThreadDisablingThreadSafetyProtection must be called, and exitQTKitOnThread must be called before exiting the thread. A QTMovie object can be migrated from one thread to another by first calling detachFromCurrentThread on the first thread and then attachToCurrentThread on the second thread.

Availability

• Mac OS X v10.5 and later.

Declared In

duration

Returns the duration of a QTMovie object as a structure of type QTTime.

- (QTTime)duration

Availability

• Available in Mac OS X v10.3 and later.

Declared In

frameImageAtTime:

Returns an NSImage for the frame at the time time in a QTMovie.

- (NSImage *)frameImageAtTime:(QTTime)time

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – currentFrameImage
• – posterImage

Declared In

frameImageAtTime:withAttributes:error:

Returns an NSImage*, CIImage*, CGImageRef, CVPixelBufferRef, or CVOpenGLTextureRef for the movie image at the specified time

- (void *)frameImageAtTime:(QTTime)time withAttributes:(NSDictionary *)attributes error:(NSError **)errorPtr

Discussion

if an error occurs and the desired type of image cannot be created, then this returns nil and sets errorPtr to an NSError * describing the error. The dictionary of attributes can contain these keys:

• QTMovieFrameImageSize

• QTMovieFrameImageType

• QTMovieFrameImageRepresentationsType

• QTMovieFrameImageOpenGLContext

• QTMovieFrameImagePixelFormat

• QTMovieFrameImageInterlaced

• QTMovieFrameImageHighQuality

• QTMovieFrameImageSingleField

Availability

• Available in Mac OS X v10.5 and later.

Declared In

generateApertureModeDimensions

Adds information to a QTMovie needed to support aperture modes for tracks created with applications and/or versions of QuickTime that did not support aperture mode dimensions.

- (void)generateApertureModeDimensions

Discussion

If the image descriptions in video tracks lack tags describing clean aperture and pixel aspect ratio information, the media data is scanned to see if the correct values can be divined and attached. Then the aperture mode dimensions are calculated and set. Afterwards, the QTTrackHasApertureModeDimensionsAttribute property will be set to YES for those tracks. Tracks that do not support aperture modes are not changed.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

gotoBeginning

Repositions the play position to the beginning of the movie.

- (void)gotoBeginning

Discussion

If the movie is playing, the movie continues playing from the new position.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

gotoEnd

Repositions the play position to the end of the movie.

- (void)gotoEnd

Discussion

If the movie is playing in one of the looping modes, the movie continues playing accordingly; otherwise, play stops.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

gotoNextSelectionPoint

Repositions the movie to the next selection point.

- (void)gotoNextSelectionPoint

Availability

• Available in Mac OS X v10.3 and later.

Declared In

gotoPosterFrame

Repositions the play position to the movie’s poster time.

- (void)gotoPosterFrame

Discussion

If no poster time is defined, the movie jumps to the beginning. If the movie is playing, the movie continues playing from the new position.

gotoPreviousSelectionPoint

Repositions the movie to the previous selection point.

- (void)gotoPreviousSelectionPoint

Availability

• Available in Mac OS X v10.3 and later.

Declared In

hasChapters

Returns YES if the receiver has chapters, NO otherwise.

- (BOOL)hasChapters

Availability

• Mac OS X v10.5 and later.

Declared In

idling

Returns the current idling state of a QTMovie object.

- (BOOL)idling

Discussion

This method allows you to manage the idling state of a QTMovie object, that is, whether it is being tasked. Note that movies attached to a background thread should not be idled; if they are idled, unexpected behavior can result.

initToWritableData:error:

Useful for directly passing filenames and data objects. The QTMovie returned by this method is editable.

- (id)initToWritableData:(NSMutableData *)data error:(NSError **)errorPtr

Discussion

These methods––initToWritableDataReference:error:, initToWritableFile:error: and