Contents
Navigation
Home User Reference Other Resources


When working with the QuickTime API, nearly all operations are performed on a data structure known as a QuickTime movie. The QuickTime movie is a description of a multimedia presentation. It tells a computer (or other multimedia-capable device):

  • What type of media to present
  • Where the data is located
  • When and how to present each sample
  • How to layer, arrange, and composite multiple elements

You can use QuickTime movies in several ways:

  • Record digital data into QuickTime movies
  • Import media from other formats into QuickTime movies
  • Export from QuickTime movies to other formats
  • Create, edit, and play all types of media (as QuickTime movies)

For example, to play an MP3 audio file using QuickTime, you create a new movie in memory from the MP3 file and play the movie. This does not directly copy the MP3 audio data into memory; it creates a small movie data structure that allows QuickTime to find, decompress, and play the audio data in the MP3 file.
A QuickTime movie does not contain sample data, such as audio samples or video frames. A movie is the organizing principle that allows a computer to locate and interpret the required sample data. Playing a movie causes QuickTime to locate and obtain sample data from wherever it is, decompress and composite it as necessary, and present it in the proper sequence and arrangement.

It’s important to distinguish between a QuickTime movie, the data structure we have been discussing, and a QuickTime movie file. A movie is not the same as a movie file. A movie file can contain a stored copy of a movie data structure, or it can contain only a reference to such a structure, stored somewhere else. If a movie file contains a stored movie, it can optionally contain the sample data used by the movie as well. This is sometimes called a self–contained movie file, and it is quite common. When the sample data is stored in a movie file, it is interleaved for smooth playback.

The QTPlgMovie class provides you with properties, methods and constants that let you manipulate QuickTime movies.







The QTPlgMovie class constructors are called when you create a new instance of the class, while the ˜QTPlgMovie class destructor, is called automatically when the class is no more in use. Also, you can invoke the class destructor by setting the instance of the class to nil.
Once a new class instance is returned, it is good practice to check the class property to be sure that the new object can be used. See the validity requirements for more details.

The class provides you with the following initializer methods:
()
This is the default constructor. Use this version of the class constructor to create an empty movie in memory. When you have done with such movie, you can save it by using one of the overloaded class method
(other as QTPlgMovie)
This is the copy constructor. If the object to be copied is valid, then its properties will be used to initialize the new class instance properties
(f as folderitem, [create as boolean=false])
use this version of the class constructor to open an existing movie file (the f parameter), or, setting the optional create parameter to true, to create and open a new one. If the create parameter is set to false and the movie file pointed by the f parameter does not exist, no movie structure will be allocated and the new class instance will be (this is the default behaviour)
(m as movie, [copy as boolean=false])
this constructor version, allows you to create a new class instance initializing it with the movie passed into the m parameter. If you want the class make a copy of the source movie so that you can safely dispose of it, set copy to true; omit this parameter or pass a value of false, instead, if you want to just wrap the new class instance around the RealBasic movie object. This being the case, it is up to you to ensure that the QTPlgMovie class instance is referring anytime to a valid RealBasic object
(mp as movieplayer)
use this initializer to wrap the new class instance around the movie associated to the movieplayer control specified by the m parameter. It is up to you to ensure that the QTPlgMovie class instance is referring anytime to a valid RealBasic movie
(url as string)
use this version of the class constructor to open an existing movie file specifying its path by the url string; this parameter can indicate a local (file:///) or a network path provided that it refers to a supported protocol (i.e http://). The string must be encoded in MacRoman
[Deprecated]: since version 6.5 of the plugin this initializer is deprecated and will be removed from a future plugin version; use the class constructor below instead
(dataRef as )
this constructor version tries to initialize the new class instance with the movie found at the location specified by the dataRef parameter. If no movie has been found no movie structure will be allocated and the new class instance will be

returns a copy of the movie which the class instance is referring to
determines whether the movie has changed and needs to be saved
specifies if the movie is a QuickTime VR movie
specifies if the movie contains a
set to true if the movie contains and they are
indicates if the movie contains hint tracks
specifies the movie’s default data reference
determines the time value, expressed in the time coordinate system of the movie, that represents the starting time for the movie frame that contains the poster image
extracts a 100x100 pixels thumbnail of the image that corresponds to the poster time. If no poster time has been set, you will obtain the thumbnail of the movie image that corresponds to a time value of 0. If the original picture dimensions do not fit into a square, then the picture will be scaled and centered into the thumbnail mantaining its original proportions
specifies the movie selection, expressed in the time coordinate system specified by the range instance. If the of the passed range is greater than 0 and differs from the of the movie in use, then the movie’s time scale will change accordingly . If you assign nil to this property the selection is assumed to be the entire
creates a new QTPlgMovie object using the segment identified by the class property
a four chars code that identifies the type of the controller associated to the movie. You can set up the movie’s controller to the no–interface movie controller (a controller that operates just like the standard movie controller except that no controller bar is displayed and no keyboard events are passed to it) by specifying a value of "none"
determines whether aspect ratio and clean aperture correction should be performed. You can use one of the values to instantiate a object with the appropriate aperture mode. When a movie is in clean, production or encoded pixels aperture mode, each track’s dimensions are overriden by special dimensions for that mode. The original track dimensions are preserved and can be restored by setting the movie into classic aperture mode
requires QuickTime 7.0 or later
determines the movie’s boundary rectangle, which is a rectangle that encompasses all of the movie’s enabled tracks
returns informations about the restrictions, if any, specified on a given movie
determines the current volume setting for the movie; the values of sound volume range from –255 to 255; higher values translate to louder volume. Negative values indicate muted volume. That is, the Movie Toolbox does not play any sound for movies or tracks with negative volume settings, but the original volume level is retained as the absolute value of the volume setting. Therefore, the current state of the volume can be toggled by inverting the sign of the current volume setting
specifies the movie’s preferred volume setting; the values of sound volume range from –255 to 255; higher values translate to louder volume. Negative values indicate muted volume. That is, the Movie Toolbox does not play any sound for movies or tracks with negative volume settings, but the original volume level is retained as the absolute value of the volume setting. Therefore, the current state of the volume can be toggled by inverting the sign of the current volume setting
mutes or unmutes the audio output of a movie. The mute setting is not stored in the movie; it is used only until the movie is closed
requires QuickTime 6.4 or later
specifies the audio balance of a movie; values range from –100(full left) to 100(full right). A value of 0 means centered. The balance setting is not stored in the movie; it is used only until the movie is closed
requires QuickTime 6.4 or later
determines the audio gain level for the audio output of the movie, altering the perceived volume of the movie’s playback. You can specify a value of 0.0 or greater; this value is multiplied by the movie’s volume. 0.0 is silent,0.5 is –6 dB, 1.0 is 0 dB (the audio from the movie is not modified), 2.0 is +6 dB, etc. The gain level can be set higher than 1.0 to allow quiet tracks to be boosted in volume. Gain settings higher than 1.0 may result in audio clipping. The movie’s gain setting is not stored in the movie; it is used only until the movie is closed
requires QuickTime 6.4 or later
specifies the movie pitch adjustment. It adjusts the pitch of all audio tracks that contribute to the AudioContext mix. The value is specified in cents: 0.0 means no change, 1.0 means one cent up, 100.0 means one–semitone up and –1.0 one cent down. The most useful ranges for pitch are ± 1200. (ie, one octave)
requires QuickTime 7.0 or later
reports the summary AudioChannelLayout of the movie in use. All like–labelled channels are combined, so there are no duplicates. For example, if there is a stereo (L/R) track, 5 single–channel tracks marked Left, Right, Left Surround, Right Surround and Center, and a 4 channel track marked L/R/Ls/Rs, then the returned summary will be L/R/Ls/Rs/C. It will not be L/R/L/R/Ls/Rs/C/L/R/Ls/Rs
requires QuickTime 7.0 or later
returns the AudioStreamBasicDescription corresponding to the Summary Mix of the movie in use. This will describe non–interleaved, Float32 linear PCM data, with a sample rate equal to the highest audio sample rate found among the sound tracks contributing to the AudioContext mix, and a number of channels that matches what is reported by the class property
requires QuickTime 7.0 or later
the rate at which the movie is currently playing. Positive integers indicate forward rates and negative integers indicate reverse rates. A value of 1.0 indicates normal speed, a value of 2.0 indicates double speed, –2.0 means the movie is playing backward at double speed, and so on. A value of 0.0 means the movie is paused or stopped
specifies the movie’s default playback rate. Positive integers indicate forward rates and negative integers indicate reverse rates (see also the class property)
returns the number of tracks in the movie
returns the movie’s track identified by the index i; such as index ranges from 0 to –1
returns a data presentation context appropriate to the current movie (i.e if the movie does not contain any visual data this property will return a class instance)

() as
this method searches for errors in all the enabled tracks of the movie and returns information about errors that are encountered during the processing associated with the data playback. These errors typically reflect playback problems, such as low–memory conditions. The method set the class property with the error associated with the first problem track and returns the found as result
returns the first problem or nil. Also, you can check the class property to obtain the error code, if any, associated to this operation
(audioDevice as ) as boolean
this method allows you to render QuickTime movie audio to a specific Audio Device indicated by the audioDevice parameter. Passing nil into this parameter causes the sound tracks to be routed to the default audio device
returns boolean if the audio device context has been successfully changed, otherwise returns false. Check the class property for errors
requires MacOS X and QuickTime 7.0 or later
(deviceUID as string) as boolean
this method allows you to render QuickTime movie audio to a specific Audio Device indicated by the deviceUID parameter. Passing "" into this parameter causes the sound tracks to be routed to the default audio device
returns boolean if the audio device context has been successfully changed, otherwise returns false. Check the class property for errors
requires MacOS X and QuickTime 7.0 or later
(seek as integer)
use this function to reposition the movie to a time specified by the appropriate constant
returns nothing. Check the class property for errors
(tmRange as , fType as string) as integer
by using this function you can count the number of samples of type fType within the specified time range; if you set the tmRange parameter to nil returns the total number of samples of type fType in the movie
returns the number of samples of type fType found; if some error has occurred during the search, the result is set to –1. Check the class property for errors
(e as boolean)
usually, the selection of alternate tracks based on the media language and quality occurs automatically when a movie file is first opened. You can use this method to change the state of auto–alternating dynamically
returns nothing. Check the class property for errors
([gc as ]) as picture
returns the image that corresponds to the poster time. If no poster time has been set, you will obtain the image that corresponds to a time value of 0. If you set the optional gc parameter, the original image will be transformed according to the parameters specified by the of the object. If the movie has not this function returns nil
returns a picture of the poster frame if no error occurs, otherwise returns nil. Check the class property for errors
(w as integer, h as integer) as picture
returns the frame displayed at current movie time scaled to the width specified by the w parameter and the height specified by the h parameter. If the movie has not this function returns nil
returns a picture of the current frame if no error occurs, otherwise returns nil. Check the class property for errors
(type as ) as
returns the list of all of movie’s that share the media type specified by the type parameter; if you want the list of all of movie’s pass nil into this parameter
returns a list of if no error occurs, otherwise returns nil. This being the case, check the class property for errors
(characteristic as ) as
returns the list of all of movie’s that own the media characteristic specified by the characteristic parameter (i.e. you can pass a value of 'eyes' if you need a list of the tracks that have a visual representation); if you want the list of all of movie’s pass nil into this parameter
returns a list of if no error occurs, otherwise returns nil. This being the case, check the class property for errors
(editFlag as integer)
use this method to edit a segment of the movie. You control the type of editing action you are setting about to do by the editFlag parameter; you can set this parameter with one of the constants defined by the QTPlugin. You specify the movie’s segment to be edited by setting the property
returns nothing. Check the class property for errors
[Deprecated]: since version 6.7 of the plugin this method is deprecated and will be removed from a future plugin version; use the editing methods listed below instead.
([selection as ]) as boolean
this method copies into the scrap the movie’s segment specified by the selection parameter. The and properties of the selection must be expressed in movie’s time scale. The selection parameter is optional: if you do not specify or pass nil as time interval, the method copies the current movie . This method clears the scrap before putting the movie on the scrap
returns true if the editing is successfully performed, false otherwise. Check the class property for errors
[Availability]: QTPlugin version 6.7 and later.
([selection as ]) as boolean
this method removes the segment of the movie that is defined by the selection specified by the selection parameter. The and properties of the selection must be expressed in movie’s time scale. The selection parameter is optional: if you do not specify or pass nil as time interval, the method uses the current movie . After removing the segment, this method updates the properties of the selection parameter (if any) to reflect the changes to the movie’s selection (the property should be set to 0 while the property should be unchanged). This method removes empty tracks from the resulting movie
returns true if the editing is successfully performed, false otherwise. Check the class property for errors
[Availability]: QTPlugin version 6.7 and later.
([selection as ]) as boolean
this method creates a new movie that contains the movie’s selection specified by the selection parameter puts it on the scrap and, finally, removes the current selection from the original movie. The and properties of the selection must be expressed in movie’s time scale. The selection parameter is optional: if you do not specify or pass nil as time interval, the method uses the current movie . After the current selection has been removed from the original movie, this function updates the selection parameter (if any) to reflect the changes to the movie’s selection (the property should be set to 0 while the property should be unchanged)
returns true if the editing is successfully performed, false otherwise. Check the class property for errors
[Availability]: QTPlugin version 6.7 and later.
([selection as ]) as boolean
if there is a movie on scrap, this method creates a new movie from the scrap contents and then places the tracks from this one into the movie in use. All of the tracks from the source movie are placed into the destination movie. If the selection parameter specifies a of 0, the source movie is inserted into the destination movie at the time indicated by the property. If the property of the selection is set to a nonzero value, the function clears the destination movie’s selection and then inserts the tracks from the source movie. The and properties of the selection must be expressed in current movie’s time scale. The selection parameter is optional: if you do not specify or pass nil as time interval, the method uses the current movie . After the paste operation, this function updates the time interval (if any) to reflect the changes to the movie’s selection (the property should be set to the source movie’s duration while the property should be unchanged). Whenever possible, this function uses existing tracks to store the data to be pasted. If no appropriate track can be found in the destination movie, a new track with the proper characteristics will be created. After the paste operation, any empty tracks will be removed from the destination movie
returns true if the editing is successfully performed, false otherwise. Check the class property for errors
[Availability]: QTPlugin version 6.7 and later.
(index as integer)
use this method to remove the movie’s track identified by the index parameter; such as index ranges from 0 to –1
returns nothing. Check the class property for errors
(m as QTPlgMovie, tmRange as , [append as boolean=true])
use this method to place a copy of the segment, which it obtained from the movie specified by the m parameter, into this destination movie. If you set the m parameter to nil, the method will copy the data internally to the movie. You specify the segment by setting the properties of the object; setting this parameter to nil will force the copy of the entire source movie. If the optional append parameter is set to false the specified segment will be inserted at the current movie time (use the class property to change the insertion point). If you are not copying data from one location in a movie to a different point in the same movie, this function may create new tracks, as appropriate
returns nothing. Check the class property for errors
(t as , tmRange as , [copy as boolean=false])
this method creates a new track in the movie and places a copy of the segment, which is obtained from the track specified by the t parameter, into this track. By setting the optional copy parameter to true, the data will be copied into the destination track; otherwise the segment will be copied by reference. If you choose to insert the movie by reference, the data can be copied later by the movie. You specify the segment by setting the properties of the object; setting this parameter to nil will force the copy of the entire source track. The values used to specify the time interval must be expressed into the movie’s time scale of the source track t
returns nothing. Check the class property for errors
(dstFile as folderitem)
use this method to create a movie file that just contains a reference to the movie in use.
returns nothing. Check the class property for errors
(masterMovie as QTPlgMovie, [offset double=0.0])
use this method to assign the time base of the source movie (the masterMovie movie) to the movie instance in use. The offset parameter allows you to set an offset between the synchronized movie and the master time base. Setting it to a value greater than 0.0 specifies the time value of the master movie, expressed in its time scale, that corresponds to a 0 time value for the synchronized movie. The default behaviour is to not specify any offset
returns nothing. Check the class property for errors
()
saves movie changes to disk; the data are written to the datafork of movie’s file. Using this version of the method makes sense only you are the owner of the movie (that is you have initialized the class instance using that opens and retains the movie
returns nothing. Check the class property for errors
(dstFile as folderitem, [selfContained as boolean=true])
save the movie to the file specified by dstFile; set the optional selfContained parameter to true if you want to make movie self–contained. Anyway, the data are written to the datafork of movie’s destination file
returns nothing. Check the class property for errors
(dstFile as folderitem, tmRange as , [selfContained as boolean=true])
save the movie segment specified by tmRange to the file specified by dstFile; if tmRange is set to nil, the method will save the entire movie to the specified file. Set the optional selfContained parameter to true if you want to make movie self–contained. Anyway, the data are written to the datafork of movie’s destination file
returns nothing. Check the class property for errors

(other as QTPlgMovie) as QTPlgMovie
use the + Realbasic operator to create a new movie that results from the appending that one you pass into the other parameter to the movie in use. The resulting movie contains only references to the source movies (that is no data is copied into the new movie)
returns a new QTPlgMovie class instance. Check the class property for errors


specifies the start of the movie. If the movie is in preview mode, specifies the start of the preview segment of the movie
specifies the end of the movie
specifies the time that corresponds to the previous sample of the movie. If the movie is positioned at its begin, this flag is ignored
specifies the time that corresponds to the next sample of the movie. If the movie is positioned at its end, this flag is ignored