Contents
Navigation
Home User Reference Other Resources


QuickTime API implements many data structures, but, without any doubt, three of them are of common use for developing with QuickTime: , and .

The QTPlugin lets you access to and manipulate these data structures by defining the Container set of classes; root of this hierarchy of classes is the QTPlgContainer class. This is an abstract class that defines properties, methods and constants that will be implemented from any of its derived class.







The class has not constructor at all (you can always use the Realbasic common constructor syntax, of course, but you will obtain an usless object). Its destructor, will be implicitly invoked every time one of its derived classes will be destroyed.

Anyway, once a new instance of a class derived from QTPlgContainer is returned, it is good practice to check the class property to be sure that the new object can be used. As a rule of thumb, a class derived from QTPlgContainer is valid if it has obtained access to the appropriate container of data to be used (that is the value of the property is not 0)

returns a reference to the data container structure in use; the type of this reference depends on the type of the QTPlgContainer’s derived class:
and its derived classes return a handle to a movie record
and its derived classes return a handle to a track record
and its derived classes return a handle to a media record
useful for toolbox programmers (use with care: you could invalidate the handle causing unpredictable results (probably an application crash))
the parent container in the container’s hierarchy; this property is nil for a object
indicates if the container does contain visual data
indicates if the container does contain sound data
specifies if the QTPlgContainer instance in use can deal with aperture modes. What does it mean depends on the type of the object:
returns true if any track has aperture mode dimensions
returns true if have been set on the track the object represents, even if they are all identical to the classic dimensions (as is the case for content with square pixels and no edge processing region)
returns true if the media handler supports aperture modes, which enable video to be automatically scaled and cropped to compensate for non–square pixel aspect ratios and to trim possibly–dirty edge processing regions. The dimensions of such a track may change when the movie’s aperture mode is changed
indicates if the container in use can be used in a separate background thread. In case of a object, this property is set to true if at least one of its tracks supports multi–threading. Note that this condition is necessary but not enough to make sure that the movie can be put on a background thread
the current container’s status; you can use this property to enable and disable a container. A disabled container will not play
specifies the date and time when the container object was created expressed as number of seconds since midnight January 1 1904. You can set the totalSeconds property of a date Realbasic built–in object with this value to get a string representation of it
specifies the date and time when the container object was last changed and saved expressed as number of seconds since midnight January 1 1904. You can use the value returned to set the totalSeconds property of a date Realbasic built–in object and obtain a string representation of it
returns temporal informations about the container in use. The property is set to the current container’s time, the property specifies the amount of time remaining to the container’s end and the property indicates the container’s time scale, of course
a time value, expressed in the time scale of the container’s instance, that is calculated to be the maximum durations of all the tracks in the movie. By changing this value the container will be stretched or shrinked to accommodate the supplied duration (this is accomplished by working with references to the containers’s data).
determines the current container’s time scale
determines the current container time. In the case of a object, this value must be interpreted as relative to its parent movie’s current time; that is, this value is obtained by subtracting the track to the movie current time. If the value of this property is less than 0 or greater than the of the track the movie is not playing this track
a sound volume value; the meaning of this property and the values it can deal with depend on the type of container class and will be discussed in detail in the documentation of the specific classes
the user data list associated to the container
retrieves the metadata object associated to the container
requires QuickTime 7.0 or later
specifies the original bounds of the container
specifies the current bounds of the container; detailed informations about what does these bounds mean and wich values you can assign to them will be provided in the documentation of the QTPlgContainer’s derived classes
specifies a set of graphical properties for the container object in use. You can manipulate the following characteristics:
  • the current container’s bounds
  • the current container’s clipping region
  • the current container’s matrix
  • the graphics mode in use (applicable to and ) objects
indicates the number of entries into the edit states list associated to the container. An edit state contains information that completely defines a movie’s or track’s content at the time you create the edit state. It is, in essence, a checkpoint in the edit session. You can manage either a movie’s or track’s edit states in order to implement an undo capability for editing movies. For example, you can capture a movie’s edit state before performing an editing operation, such as a cut, and later restore the old state. You can have several edit states obtained at different times during an editing session, and restore to any one of them at any time. In this manner, you can provide a multilevel undo capability.
Note that an edit state does not save everything about a movie. Most important, the edit state does not contain information about the spatial characteristics of the target container. For example, the edit state does not store the current movie’s boundary rectangle or clipping region. Consequently, edit states are best suited to supporting undo operations involving movie content, including track creation and removal.
To know about how to capture and restore the edit state of a movie or track see the below
the edit state capture and restore mechanism is not implemented for the class
[Deprecated]: since version 6.5 of the plugin this property is deprecated and will be removed from a future plugin version; use the class property instead
returns the edit states list of objects associated to the container. You can add new entries to the list using the class method described below. Later you can restore the edit state of a movie or track simply by walking through the list, selecting an edit state from it and using the method of the selected object. An contains information that completely defines a movie’s or track’s content at the time you create the edit state. It is, in essence, a checkpoint in the edit session. You can manage either a movie’s or track’s edit states in order to implement an undo capability for editing movies. For example, you can capture a movie’s edit state before performing an editing operation, such as a cut, and later restore the old state. You can have several edit states obtained at different times during an editing session, and restore to any one of them at any time. In this manner, you can provide a multilevel undo capability.
Note that an edit state does not save everything about a movie. Most important, the edit state does not contain information about the spatial characteristics of the target container. For example, the edit state does not store the current movie’s boundary rectangle or clipping region. Consequently, edit states are best suited to supporting undo operations involving movie content, including track creation and removal
the edit state capture and restore mechanism is not implemented for the class
specifies the container’s localized language or region code; if the container object is a or a , this property should be set only at creation time. Instead, if the container instance is a , you can use this property to dinamically modify the language used by the movie itself
a 100 x 100 pixels thumbnail of the current container’s frame (if applicable). If the original picture dimensions do not fit into a square, then the picture will be scaled and centered within the thumbnail’s bounds mantaining its original proportions
specifies if the given container should render the highest quality. For example, the video media handler should turn off fast dithering and use high–quality dithering. Because rendering at the highest quality takes much more time and memory than rendering at a lesser quality, this mode is usually not appropriate for real–time playback. However, since this mode generates higher quality images, it is useful when recompressing. The changes done will be saved when saving the movie
determines if the given movie or media should render only one field. The changes done with this function will be saved when saving the movie
requires QuickTime 4.0 or later

([showDialog as boolean]) as boolean
determine if the current machine is authorized to play some QuickTime DRM–protected media (i.e. an imported music file). The optional parameter showDialog allows to turned off user interaction so no automatic dialog will pop up (the default behaviour is user interaction disabled)
returns true if the container object in use does not contain any DRM–protected contents or the current machine is authorized to play such contents; otherwise returns false. Check the class property for errors
requires QuickTime 7.0 or later
([gc as ]) as picture
returns the frame displayed at current movie time; if you do not set the gc parameter, the resulting picture has the same dimensions as those specified by the container property. Otherwise this function returns the frame modified according to the graphics transformation parameters specified by the of the class instance passed into the gc 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
(t as integer, [gc as ]) as picture
returns the frame displayed at the container’s time indicated by the t parameter; if you do not set the gc parameter, the resulting picture has the same dimensions as those specified by the container property. Otherwise this function returns the frame modified according to the graphics transformation parameters specified by the of the class instance passed into the gc parameter. If the movie has not this function returns nil
returns a picture of the specified containers’s time frame if no error occurs, otherwise returns nil. Check the class property for errors
(t as integer) as picture
a 100 x 100 pixels thumbnail of the frame displayed at the container’s time indicated by the t parameter (if applicable). If the original picture dimensions do not fit into a square, then the picture will be scaled and centered within the thumbnail’s bounds mantaining its original proportions. If the movie has not this function returns nil
returns a thumbnail of the specified containers’s time frame if no error occurs, otherwise returns nil. Check the class property for errors
(tm as double) as
use this method to find about temporal informations (if any) about the container’s sample located at time tm. The time of interest is intended to be expressed in movie’s time scale. The temporal informations are contained into an istance of the class that reports the starting time of the sample, its duration and the container’s time scale. All of the returned times are relative to display times (that is no information about decoding times are ever returned)
returns time informations about a container’s sample if no error occurs, otherwise returns nil. Check the class property for errors
(tmRange as , newDuration as integer)
this method allows you to selectively stretch or shrink the portion of the container’s instance determined by the tmRange parameter to accommodate the supplied duration (this is accomplished by working with references to the containers’s data). The time range provided must be appropriated to the target container’s instance; as this method, at time, is effective only on and , this means that the time range must be expressed in movie’s time scale
returns nothing. Check the class property for errors
(tmRange as )
this method allows you to add an empty segment to a container’s instance; you specify where the segment is to be inserted by the property and its duration by the property of the tmRange parameter. The time range provided must be appropriated to the target container’s instance; as this method, at time, is effective only on and , this means that the time range must be expressed in movie’s time scale. You cannot add an empty segment beyond the end of the container’s instance
returns nothing. Check the class property for errors
(tmRange as )
use this method to remove a segment from a container’s instance; you specify where the segment to be removed starts by the property and its duration by the property of the tmRange parameter. The time range provided must be appropriated to the target container’s instance; as this method, at time, is effective only on and , this means that the time range must be expressed in movie’s time scale. You cannot add an empty segment beyond the end of the container’s instance
returns nothing. Check the class property for errors
(tmRange as ) as double
use this function to obtain the size, in kilobytes, of the sample data in the segment of the container specified by the tmRange parameter. The time values of the tmRange object must be expressed in movie’s time scale. Setting the tmRange to nil will force the method to return the size of the entire container. If the container is a , note that the value returned does not necessarily correspond to the amount of sample data used in the track that contains the media. Some samples in the media may not be used in the track, and others may be used more than once
returns the size, in kilobytes of the specified sample data; if some errors has occurred while examining data the value returned is 0.0. Check the class property for errors
(tmRange as , flags as integer)
this function try to load a container’s data into memory. If the data does not fit, the function returns an error. You can instruct the function to load into memory either a portion or the entire container’s data: you set the starting time and the duration of the segment by using the of the tmRange object; by setting this parameter to nil you specify the length of the entire container. You can explicitly control what is loaded into memory and how long to keep it around by setting the flags parameter as appropriate. You can set the defined for this operation in any combination that makes sense for you by using the BitwiseOr operator
returns nothing. Check the class property for errors
(gc as )
this function allows you to specify a set of graphics transformations to apply to the container in use. You specify the display parameters by setting the properties of the class instance specified by the gc parameter. If the plugin container in use does not contain visual data (check the property to find about it) this method has no effect.
Note that the QTPlgContainer derived classes will not use all of the parameters specified by the graphics context class instance. The and container classes will modify their spatial properties by using the properties listed below:

Instead, a class object will just use the and to change the graphics mode of the media handler associated to it; note that this has the same effect as to use the and properties of the class.
returns nothing. Check the class property for errors
[Deprecated]: since version 6.5 of the plugin this method is deprecated and will be removed from a future plugin version; use the class property instead
(description as string)
use this function to capture a container’s edit state and add it to the internally held by the container instance in use. You can optionally assign a comment to the state by using the description parameter; anyway, you can change the description of any registered edit state at any time, using the property of the class. The description string must be encoded in MacRoman. If you do not specify any string, then the property of the registered edit state will be automatically set to the value of the of the instance. This method, used along with the class property and the class, supersedes and replaces all of the other class methods and properties previously devoted to the management of edit states
returns nothing. Check the class property for errors
(description as string)
use this function to capture a container’s edit state. You can optionally assign a comment to the state by using the description parameter; then, you can later retrieves the comment associated to a container’s edit state by using the class method. The description string must be encoded in MacRoman. If you do not specify any string, then the class will automatically assign a default value of "STATE_n" where n represents the index of the newly added edit state
returns nothing. Check the class property for errors
[Deprecated]: since version 6.5 of the plugin this property is deprecated and will be removed from a future plugin version; use the class method instead
(i as integer)
this method returns a container to the condition determined by the edit state created previously and identified through its index i (this index ranges from 0 to –1)
returns nothing. Check the class property for errors
[Deprecated]: since version 6.5 of the plugin this property is deprecated and will be removed from a future plugin version; use the class method instead
(i as integer)
use this method to dispose of the edit state specified by its index i (this index ranges from 0 to –1)
returns nothing. Check the class property for errors
[Deprecated]: since version 6.5 of the plugin this property is deprecated and will be removed from a future plugin version; use the class property instead
(i as integer) as string
by this method you can obtain the description associated to the edit state specified by its index i (this index ranges from 0 to –1). This string can be useful if you want, for example, to display the list of the registered edit states into a PopupMenu or MenuItem control
returns a string with the description of the edit state. Check the class property for errors
[Deprecated]: since version 6.5 of the plugin this property is deprecated and will be removed from a future plugin version; use the class property instead
(dst as , type as ,[showDialog as boolean=true])
by this function you can easily export the container’s data through the standard export dialog. You can choose the appropriate movie exporter component using the dialog and, then, export the source movie. If you do not want to display the standard export dialog, set the showDialog parameter to false; this being the case, you have to specify yourself the export format by passing a valid OSType value into the type parameter. This value will be used to set up the Mac OS file type of the storage location as well. This parameter is effective only if the showDialog parameter is set to false. If you need more control onto the export process you should use the class instead. You specify the target destination by the dst parameter; currently are supported alias data references only. If the target file already exists in the specified location, this function will delete it and will create a new one
returns nothing. Check the class property for errors
()
use this method to add information needed to support aperture modes to movies created with applications and/or versions of QuickTime that did not support . How this method works depends on the type of object that implements it:
: if the in video tracks lack tags describing and information, the media data may be scanned to see if the correct values can be divined and attached. Then the are calculated and set for each track. Afterwards, the property will be set to true for these tracks. Tracks which do not support aperture modes are not changed.
: same as above but only the track in use will be affected.
: if the sample descriptions tracks lack tags describing and information, the media data may be scanned to see if the correct values can be divined and attached. Then the are calculated and set by using the first media sample description
returns nothing. Check the class property for errors
requires QuickTime 7.1 or later
()
this method removes aperture mode dimension information from a movie’s tracks. For and it does not attempt to modify sample descriptions, so it may not completely reverse the effect of . It sets the property to false. Instead, calling this method on a object will cause the modification of the sample descriptions as well
returns nothing. Check the class property for errors
requires QuickTime 7.1 or later


the duration of the container expressed in the appropriate time scale
the time scale of the container
the container’s current time expressed in the appropriate time scale
the poster’s time in the container

specifies the copy editing action. The current container selection will be copied onto the scrap
specifies the clear editing action. The current container selection will be removed from the container itself
specifies the cut editing action. The current container selection will be removed from the container and copied onto the scrap
specifies the paste editing action. This action retrieves a container data from the scrap and inserts it at the current time in the container you are working with
specifies the undo editing action. This action discards the effects of the most recent edit operation. You can use this action with only

renders all data loaded with this flag set as nonpurgeable. Nonpurgeable data is not released from memory until you request it explicitly. This practice can fill up your heap very quickly. Exercise caution
renders all indicated data purgeable. The data is not necessarily released from memory immediately, however
purges all indicated data from memory, unless it is currently in use by a media handler (for example, if it is still drawing frames from the requested times). This flag makes the memory available for purging, and then performs the purge. You may want to use this option if you are particularly low on memory, for example after you have rendered the data loaded as non purgeable by setting the kLoad_keepInRam flag
in some cases, an edited movie plays back much more smoothly if the data around edits is already in RAM. By setting either this flag or the following one, you can load only the data around edits. The Movie Toolbox walks through the edits and decides the right amount of data to load for you. If you are going to play the movie forward, set only this flag. If you are going to play in both directions, or you don’t know which direction, set both this flag and the next one
in some cases, an edited movie plays back much more smoothly if the data around edits is already in RAM. By setting either this flag or that one seen above, you can load only the data around edits. The Movie Toolbox walks through the edits and decides the right amount of data to load for you. If you are going to play the movie only backward, set only this one. If you are going to play in both directions, or you don’t know which direction, set both this flag and the previous one