Movie File Functions

The Movie Toolbox provides a set of functions that allow your application to create, access, and convert movie files, which files contain data for QuickTime movies. You can also use the Movie Toolbox to load movies into memory, in preparation for working with the movie. These functions differ based on where the movie is stored.

The following functions are used when saving a movie to a file.

• HasMovieChanged

• ClearMovieChanged

• AddMovieResource

• UpdateMovieResource

• RemoveMovieResource

• PutMovieIntoHandle

• FlattenMovie

• FlattenMovieData

• NewMovieFromDataFork

• PutMovieIntoDataFork

Before your application can play a movie, you must first open the file that contains the movie. Your application can use the OpenMovieFile function to open a movie file. Once you are done with the file, your application releases the file by calling the CloseMovieFile function. Your application can create and open a new movie file by calling the CreateMovieFile function. Your application can delete a movie file by calling the DeleteMovieFile function.

You can use the NewMovie function to create a new empty movie. If your application is loading a movie from an existing file, use either the NewMovieFromFile function or the NewMovieFromDataFork function. The NewMovieFromFile function works with the file reference number you obtain from the OpenMovieFile function. The NewMovieFromDataFork function works with movies stored in your document file’s data fork. Your application can then use the functions described in Saving Movies to load and store movies.

You can use the ConvertFileToMovieFile function to specify an input file and convert it to a movie file. The ConvertMovieToFile takes a specified movie (or a single track within that movie) and converts it into an output file.

You can use the AddMovieResource function to add a new movie resource to a movie file. Your application can also use this function to save a movie that it created. You can use the UpdateMovieResource function to replace an existing movie resource in a movie file. You can remove a movie resource by calling the RemoveMovieResource function.

The movie resources that your application creates with the AddMovieResource and UpdateMovieResource functions may contain references to movie data. These references identify the data that constitute the movie. However, the movie data can be stored outside of the movie file. If you want to create a movie file that contains all of its movie data, use the FlattenMovie or FlattenMovieData function. These functions can also be used to store the movie data in the movie file’s data fork, or to interleave the media data to optimize performance.

The PutMovieIntoHandle function places a QuickTime movie into a handle. You can then convert the movie into specialized data formats.

The HasMovieChanged and ClearMovieChanged functions allow your application to work with the movie changed flag that is maintained by the Movie Toolbox. You can use this flag to determine whether a movie has been changed.

The movie changed flag indicates whether you have changed the movie. Such actions as editing the movie, adding samples to a media, or changing a data reference cause the flag to indicate that the movie has changed. There are several operations that the movie changed flag does not reflect, including changing the volume, rate, or time settings for the movie. These settings change frequently when a movie is played. Your application must monitor these settings itself.

The Movie Toolbox also supplies functions for storing and retrieving movies that are stored in the data fork of a file. These functions provide robust data reference resolution and improve low memory performance. The NewMovieFromDataFork function enables you to retrieve a movie that is stored anywhere in the data fork of a file. You can use the PutMovieIntoDataFork function to store an atom version of a specified movie in the data fork of a file.

Once you are finished working with a movie, you should release the resources used by the movie by calling the DisposeMovie function.

Movie Files

The Movie Toolbox allows you to save movies in movie files. Movie files have a file type of 'MooV'Movie Toolbox. Typically, the movie itself is stored in the resource fork of the movie file. The movie can also be stored in data fork, for use on systems that do not support resource forks. The movie’s data may reside in the data fork of the movie file, or in other files.

When you create a new movie, you must create a file to contain the movie data. Use the CreateMovieFile function to create a new movie file. This function returns a file system reference number that you must use to identify the file to other Movie Toolbox functions. You can add your movie to the file by calling the AddMovieResource function. When you are done with the file, you close it by calling the CloseMovieFile function. Your movie is now safely stored in the movie file.

If you are working with an existing movie, you must read that movie from a movie file or choose a movie from the scrap. You first open the movie file by calling the OpenMovieFile function. You then load the movie from that file by calling the NewMovieFromFile function. Alternatively, you can use the NewMovieFromHandle function. After you have edited the movie, you must store it in your file if you want to save your changes. If you want to replace the old movie, use the UpdateMovieResource function. If you want to keep the old movie, create a new movie by calling the AddMovieResource function. A movie file may contain more than one movie resource. You should then close the movie file by calling the CloseMovieFile function.

The Movie Toolbox maintains a changed flag for each movie your application loads. You can use this flag to determine when to save your movie. The Movie Toolbox sets this flag to true whenever you make a change to a movie that should be saved. You can read this flag by calling the HasMovieChanged function. You can set the flag to false by calling the ClearMovieChanged function.

The Movie Toolbox provides two functions for deleting movies: DeleteMovieFile and RemoveMovieResource. Use DeleteMovieFile to delete a movie file. Use RemoveMovieResource to delete a movie from a movie file. Don’t use the corresponding standard Macintosh Toolbox routines (FSpDelete and RmveResourceMovie Toolbox). The Movie Toolbox maintains movie references between files correctly whereas these routines do not.

The Movie Toolbox allows you to create movie files that contain all of their movie data, rather than containing references to data in other files. This is often desirable when creating a version of a movie that will be moved to another computer. You can use the FlattenMovie or FlattenMovieData functions to resolve all of the data references and create a self-contained movie.

The Movie Toolbox also accommodates operating systems that do not recognize files that contain more than one fork. You can create a movie file that contains the movie and all of its data in the data fork of the movie file. You can then use that file on operating systems that do not recognize resource forks. You can use the FlattenMovie or FlattenMovieData functions to put the movie in the data fork at the same time it creates a self-contained movie file. This would be the usual approach when creating a movie on a Macintosh computer that you want to store on a Unix web server. You can also create a single-fork movie file by calling the CreateMovieFile function with the flag createMovieFileDontCreateResFileMovie Toolbox. This would be the usual approach when creating movies using QuickTime for Windows.

Your application may allow the user to decide how to save the movie. In this case, you can use a Save As dialog box similar to the one shown in Figure 2-1. In this dialog box, the user can elect to create a movie file that contains all of the data for a movie by clicking the “Make movie self-contained” radio button.