Advanced Search

Log In | Not a Member?

Contact ADC

< Previous PageNext Page > Hide TOC

Reference Movies

A QuickTime movie can act as a container for a set of alternate movies that should be displayed under specified conditions. One of these movies may be contained within the same file; any others are included by reference.

For example, a QuickTime movie can contain a list of references to movies having different data rates, allowing an application to choose the best-looking movie that can play smoothly as it downloads over the Internet, based on the user’s connection speed.

A movie that contains references to alternate movies is called a reference movie.

A reference movie contains a reference movie atom ('rmra') at the top level of the movie atom. The movie atom may also contain a movie header atom, or it may contain the reference movie atom alone.

Figure 2-40  A movie atom containing a 'rmra' atom instead of a 'mvhd' atom

The reference movie atom contains one or more reference movie descriptor atoms, each of which describes an alternate movie.

Each reference movie descriptor atom contains a data reference atom, which specifies the location of a movie.

A reference movie descriptor atom may contain other atoms that specify the movie’s system requirements and the movie quality. If so, there will be an atom of an appropriate type for each requirement that must be met for the movie to play, and there may be a quality atom as well.

Applications should play the highest-quality movie whose requirements are met by the user’s system. If the data reference to the selected movie cannot be resolved—because the file cannot be found, for example—the application should recursively attempt to play the next-highest-quality movie until it succeeds or has exhausted the list of movies whose requirements are met.

If a movie contains both a reference movie atom and a movie header atom, applications should play the appropriate movie indicated by the reference movie atom.

If the user’s system does not meet any of the alternate movies’ criteria, or none of the qualifying data references can be resolved, applications should play the movie defined in the movie header atom. (The movie defined in the movie header atom can also be indicated by one of the alternate movie references.)

The movie header atom is sometimes used to provide a fallback movie for applications that can play older QuickTime movies but do not understand reference movies.

When parsing a reference movie, the reader should treat the URL or file reference in the reference movie atom as a new starting point, making no assumptions that the reference is a valid URL, or an existing file, or a well-formed and playable QuickTime movie.

In this section:

Reference Movie Atom
Reference Movie Descriptor Atom
Data Reference Atom
Data Rate Atom
CPU Speed Atom
Version Check Atom
Component Detect Atom
Constants
Quality Atom

Reference Movie Atom

A reference movie atom contains references to one or more movies. It can optionally contain a list of system requirements in order for each movie to play, and a quality rating for each movie. It is typically used to specify a list of alternate movies to be played under different conditions.

A reference movie atom’s parent is always a movie atom ('moov'). Only one reference movie atom is allowed in a given movie atom.

Figure 2-41  A 'rmra' atom with multiple 'rmda' atoms

A reference movie atom may contain the following fields:

Size

The number of bytes in this reference movie atom.

Type

The type of this atom; this field must be set to 'rmra'.

Reference movie descriptor atom

A reference movie atom must contain at least one reference movie descriptor atom, and typically contains more than one. See “Reference Movie Descriptor Atom” for more information.

Reference Movie Descriptor Atom

Each reference movie descriptor atom contains other atoms that describe where a particular movie can be found, and optionally what the system requirements are to play that movie, as well as an optional quality rating for that movie.

A reference movie descriptor atom’s parent is always a movie reference atom ('rmra'). Multiple reference movie descriptor atoms are allowed in a given movie reference atom, and more than one is usually present.

Figure 2-42  Reference movie descriptor atom

A reference movie descriptor atom may contain the following fields:

Size

The number of bytes in this reference movie descriptor atom.

Type

The type of this atom; this field must be set to 'rmda'.

Data reference atom

Each reference movie atom must contain exactly one data reference atom. See “Data Reference Atoms” for more information.

Data rate atom

A reference movie atom may contain an optional data rate atom. Only one data rate atom can be present. See “Data Rate Atom” for more information.

CPU speed atom

A reference movie atom may contain an optional CPU speed atom. Only one CPU speed atom can be present. See “CPU Speed Atom” for more information.

Version check atom

A reference movie atom may contain an optional version check atom. Multiple version check atoms can be present. See “Version Check Atom” for more information.

Component detect atom

A reference movie atom may contain an optional component detect atom. Multiple component detect atoms can be present. See “Component Detect Atom” for more information.

Quality atom

A reference movie atom may contain an optional quality atom. Only one quality atom can be present. See “Quality Atom” for more information.

Data Reference Atom

A data reference atom contains the information necessary to locate a movie, or a stream or file that QuickTime can play, typically in the form of a URL or a file alias.

Only one data reference atom is allowed in a given movie reference descriptor atom.

A data reference atom may contain the following fields:

Size

The number of bytes in this data reference atom.

Type

The type of this atom; this field must be set to 'rdrf'.

Flags

A 32-bit integer containing flags. One flag is currently defined: movie is self-contained. If the least-significant bit is set to 1, the movie is self-contained. This requires that the parent movie contain a movie header atom as well as a reference movie atom. In other words, the current 'moov' atom must contain both a 'rmra' atom and a 'mvhd' atom. To resolve this data reference, an application uses the movie defined in the movie header atom, ignoring the remainder of the fields in this data reference atom, which are used only to specify external movies.

Data reference type

The data reference type. A value of 'alis' indicates a file system alias record. A value of 'url ' indicates a string containing a uniform resource locator. Note that the fourth character in 'url ' is an ASCII blank (0x20).

Data reference size

The size of the data reference in bytes, expressed as a 32-bit integer.

Data reference

A data reference to a QuickTime movie, or to a stream or file that QuickTime can play. If the reference type is 'alis' this field contains the contents of an AliasHandle. If the reference type is 'url ' this field contains a null-terminated string that can be interpreted as a URL. The URL can be absolute or relative, and can specify any protocol that QuickTime supports, including http://, ftp://, rtsp://, file:///, and data:.

Data Rate Atom

A data rate atom specifies the minimum data rate required to play a movie. This is normally compared to the connection speed setting in the user’s QuickTime Settings control panel. Applications should play the movie with the highest data rate less than or equal to the user’s connection speed. If the connection speed is slower than any movie’s data rate, applications should play the movie with the lowest data rate. The movie with the highest data rate is assumed to have the highest quality.

Only one data rate atom is allowed in a given reference movie descriptor atom.

A data rate atom may contain the following fields:

Size

The number of bytes in this data rate atom.

Type

The type of this atom; this field must be set to 'rmdr'.

Flags

A 32-bit integer that is currently always 0.

Data rate

The required data rate in bits per second, expressed as a 32-bit integer.

CPU Speed Atom

A CPU speed atom specifies the minimum computing power needed to display a movie. QuickTime performs an internal test to determine the speed of the user’s computer.

This is not a simple measurement of clock speed—it is a measurement of performance for QuickTime-related operations. Speed is expressed as a relative value between 100 and 2^31, in multiples of 100.

Applications should play the movie with the highest specified CPU speed that is less than or equal to the user’s speed. If the user’s speed is lower than any movie’s CPU speed, applications should play the movie with the lowest CPU speed requirement. The movie with the highest CPU speed is assumed to be the highest quality.

Only one CPU speed atom is allowed in a given reference movie descriptor atom.

A CPU speed atom may contain the following fields:

Size

The number of bytes in this CPU speed atom.

Type

The type of this atom; this field must be set to 'rmcs'.

Flags

A 32-bit integer that is currently always 0.

CPU speed

A relative ranking of required computer speed, expressed as a 32-bit integer divisible by 100, with larger numbers indicating higher speed.

Version Check Atom

A version check atom specifies a software package, such as QuickTime or QuickTime VR, and the version of that package needed to display a movie. The package is specified using a Macintosh Gestalt type, such a 'qtim' for QuickTime (QuickTime provides support for these Gestalt tests in the Windows computing environment).

You can specify a minimum required version to be returned by the Gestalt check, or you can require that a specific value be returned after performing a binary AND operation on the Gestalt bitfield and a mask.

Multiple version check atoms are allowed within a given reference movie descriptor atom. Applications should not attempt to play a movie unless all version checks are successful.

A version check atom may contain the following fields:

Size

The number of bytes in this version check atom.

Type

The type of this atom; this field must be set to 'rmvc'.

Flags

A 32-bit integer that is currently always 0.

Software package

A 32-bit Gestalt type, such as 'qtim', specifying the software package to check for.

Version

An unsigned 32-bit integer containing either the minimum required version or the required value after a binary AND operation.

Mask

The mask for a binary AND operation on the Gestalt bitfield.

Check type

The type of check to perform, expressed as 16-bit integer. Set to 0 for a minimum version check, set to 1 for a required value after a binary AND of the Gestalt bitfield and the mask.

Component Detect Atom

A component detect atom specifies a QuickTime component, such as a particular video decompressor, required to play the movie. The component type, subtype, and other required attributes can be specified, as well as a minimum version.

Multiple component detect atoms are allowed within a given reference movie descriptor atom. Applications should not attempt to play a movie unless at least the minimum versions of all required components are present.

A component detect atom may contain the following fields:

Size

The number of bytes in this component detect atom.

Type

The type of this atom; this field must be set to 'rmcd'.

Flags

A 32-bit integer that is currently always 0.

Component description

A component description record. For details, see “Component Description Record.”

Minimum version

An unsigned 32-bit integer containing the minimum required version of the specified component.

Component Description Record

Describes a class of components by their attributes. Fields that are set to 0 are treated as “don’t care.”

struct ComponentDescription {

OSType           componentType;

OSType           componentSubType;

OSType           componentManufacturer;

unsigned long    componentFlags;

unsigned long    componentFlagsMask;

};

componentType

A four-character code that identifies the type of component.

componentSubType

A four-character code that identifies the subtype of the component. For example, the subtype of an image compressor component indicates the compression algorithm employed by the compressor. A value of 0 matches any subtype.

componentManufacturer

A four-character code that identifies the manufacturer of the component. Components provided by Apple have a manufacturer value of 'appl'. A value of 0 matches any manufacturer.

componentFlags

A 32-bit field that contains flags describing required component capabilities. The high-order 8 bits should be set to 0. The low-order 24 bits are specific to each component type. These flags can be used to indicate the presence of features or capabilities in a given component.

componentFlagsMask

A 32-bit field that indicates which flags in the componentFlags field are relevant to this operation. For each flag in the componentFlags field that is to be considered as a search criterion, set the corresponding bit in this field to 1. To ignore a flag, set the bit to 0.

Constants

canMovieImportInPlace

Set this bit if a movie import component must be able to create a movie from a file without having to write to a separate disk file. Examples include MPEG and AIFF import components.

movieImportSubTypeIsFileExtension

Set this bit if the component's subtype is a file extension instead of a Macintosh file type. For example, if you require an import component that opens files with an extension of .doc, set this flag and set your component subtype to 'DOC '.

canMovieImportFiles

Set this bit if a movie import component must import files.

Quality Atom

A quality atom describes the relative quality of a movie. This acts as a tiebreaker if more than one movie meets the specified requirements, and it is not otherwise obvious which movie should be played.

This would be the case if two qualified movies have the same data rate and CPU speed requirements, for example, or if one movie requires a higher data rate and another requires a higher CPU speed, but both can be played on the current system. In these cases, applications should play the movie with the highest quality, as specified in the quality atom.

Only one quality atom is allowed in a given reference movie descriptor atom.

A quality atom may contain the following fields:

Size

The number of bytes in this quality atom.

Type

The type of this atom; this field must be set to 'rmqu'.

Quality

The relative quality of the movie, expressed as a 32-bit integer. A larger number indicates higher quality. A unique value should be given to each movie.

< Previous PageNext Page > Hide TOC

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice