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
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
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)
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
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
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
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)
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
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
requires MacOS X and QuickTime 7.0 or later
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
requires MacOS X and QuickTime 7.0 or later
use this function to reposition the movie to a time specified by the appropriate
constant
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
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 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 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 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 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
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
[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.
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
[Availability]: QTPlugin version 6.7 and later.
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
[Availability]: QTPlugin version 6.7 and later.
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)
[Availability]: QTPlugin version 6.7 and later.
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
[Availability]: QTPlugin version 6.7 and later.
use this method to remove the movie’s track identified by the
index parameter; such as index ranges from
0 to
–1
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
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
use this method to create a movie file that just contains a reference to the movie in use.
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
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
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
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
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)
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