Editing Movies
This chapter describes the functions of the movie toolbox that your application will use to edit movies and tracks. You will need to read this chapter if your application provides editing functions beyond those that are built into the movie controller.
The Movie Toolbox provides a set of high-level functions that allow you to edit movies. This chapter describes these high-level editing functions. These functions work with a movie’s current selection. The current selection is defined by a starting time and a duration.
The Movie Toolbox also provides functions that allow you to edit movie segments. Those functions are described in Low-Level Movie-Editing Functions.
The movies created by these functions contain references to the data in the source movie. Because the new movies contain references and not data, they are small and easily moved to and from the scrap. If you delete the movie that contains the data, the data references in the new movies are no longer valid and the new movies cannot be played. Therefore, before you delete the original movie, you should call the FlattenMovie function for each of the new movies. This function copies the data into each of the new movies, eliminating the data references.
Note that the Movie Toolbox does not always copy empty tracks from the source movie to the movies that are created by these functions. Specifically, the Movie Toolbox preserves the empty tracks until you paste or add the selection into the destination movie. At that time, the Movie Toolbox removes the empty tracks from the selection. In addition, if a track in the source movie has trailing empty space, the Movie Toolbox removes that empty space from the track when it is copied into the new movie. Therefore, if you want to add a segment beyond the end of a movie, you insert the space when you insert the new segment using the InsertMovieSegment function.
The Movie Toolbox allows you to paste different data types into a movie. For example, QuickDraw pictures and standard sound data can be pasted directly into a movie. If you are using the movie controller component, you do not need to use these functions to paste different data types into a movie. If you are calling the Movie Toolbox directly to do editing, you should use the functions described in this section.
In this section:
Handling Media Sample References
Manipulating Media Input Maps
Undo for Movies
Functions That Modify Movie Properties
Editing Tracks
Undo for Tracks
Selection and Scrap Functions
Low-Level Movie-Editing Functions
Summary of Editing Functions
Handling Media Sample References
You could always use GetMediaSampleReference to access samples in a movie one at a time. But QuickTime also has GetMediaSampleReferences (note that this is the plural form of the GetMediaSampleReference function), which you can use to obtain information about groups of samples. In addition you can use AddMediaSampleReferences to work with groups of samples that have already been added to a movie.
Manipulating Media Input Maps
The Movie Toolbox contains two functions for maintaining media input maps: GetMediaInputMap and SetMediaInputMap.
Each track has particular attributes such as size, position, and volume associated with it. The media input map of that track describes where the variable parameters are stored so that modifier tracks know where to send their data. When a track is copied, its input map is also copied. CopyTrackSettings also transfers the media input map.
Undo for Movies
The Movie Toolbox provides functions that allow you to capture and restore the edit state of a movie. An edit state contains information that completely defines a movie’s content at the time you create the edit state. It is, in essence, a checkpoint in the edit session. You can manage a movie’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 movie 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. This section describes the Movie Toolbox functions that work with edit states.
Note that a movie’s edit state does not save everything about a movie. Most important, the edit state does not contain information about the movie’s spatial characteristics. For example, the edit state does not store the current boundary rectangle or clipping region. Consequently, edit states are best suited to supporting undo operations involving movie content, including track creation and removal. You can use other Movie Toolbox functions to support undo operations for movie characteristics. See Functions That Modify Movie Properties to learn more about these functions.
You can use the NewMovieEditState function to capture a movie’s edit state. Use the UseMovieEditState to restore the movie to its condition according to a previous edit state. Your application must dispose of an edit state by calling the DisposeMovieEditState function. You must dispose of a movie’s edit states before you dispose of the movie.
Functions That Modify Movie Properties
The Movie Toolbox provides a number of functions that allow applications to edit existing movies or to create the contents of new movies. This section describes those functions. It has been divided into the following topics:
Working With Display Characteristics describes a number of functions that allow you to work with the display characteristics of movies
Working With Sound Volume discusses the functions that your application can use to work with the sound volume of a movie or a track
Locating a Movie’s Tracks and Media Structures describes the functions that allow your application to find tracks that are associated with a movie
Determining Movie Creation and Modification Time discusses the functions that you can use to determine when a movie was created or last changed
Working With Display Characteristics
The Movie Toolbox provides a number of functions that allow your application to determine and change the display characteristics of movies and tracks. These functions are discussed in the following sections. Before using any of these functions, you should be familiar with the way in which the Movie Toolbox displays movies.
You can use the SetMovieGWorld and GetMovieGWorld functions to work with a movie’s graphics world.
Your application can work with a movie’s matrix by calling the GetMovieMatrix and SetMovieMatrix functions, and it can work with a track’s matrix with the GetTrackMatrix and SetTrackMatrix functions. Then you can perform operations on matrices with the Movie Toolbox’s matrix functions.
The following functions affect the displayed movie and its tracks in the final display coordinate system. The SetMovieGWorld and GetMovieGWorld functions let you work with a movie’s display destination. The GetMovieBox and SetMovieBox functions allow you to work with a movie’s boundary rectangle and its associated transformations. Alternatively, you can use the GetMovieMatrix and SetMovieMatrix functions to work directly with a movie’s transformation matrix. The GetMovieDisplayBoundsRgn function determines a movie’s boundary region at the current movie time. On the other hand, the GetMovieSegmentDisplayBoundsRgn function determines a movie’s boundary region over a specified time segment. You can use the GetMovieDisplayClipRgn and SetMovieDisplayClipRgn functions to work with a movie’s display clipping region.
The GetTrackDisplayBoundsRgn and GetTrackSegmentDisplayBoundsRgn functions determine a track’s final boundary region. You can use the GetTrackLayer and SetTrackLayer functions to control the drawing order of tracks within a movie.
A number of functions affect a movie’s display boundaries before any display transformations. These functions operate in the movie’s display coordinate system. You can use the GetMovieClipRgn and SetMovieClipRgn functions to work with a movie’s clipping region; that is, the clipping region that is applied before the movie display transformation. Use the GetMovieBoundsRgn function to determine a movie’s boundary region at the current movie time.
Use the GetTrackMovieBoundsRgn function to work with a track’s boundary region after matrix transformations have placed the track into the movie’s display system. The SetTrackMatrix and GetTrackMatrix functions let you define a track’s matrix transformations.
The Movie Toolbox provides several functions that affect a track’s display boundaries. These functions operate in the track’s display coordinate system before any other display transformations are applied. The GetTrackDimensions and SetTrackDimensions functions allow you to establish a track’s coordinate system and to establish a track’s source rectangle.
Note: A track’s source rectangle defines the coordinate system of the track. You specify the dimensions of the rectangle by providing the coordinates of the lower-right corner of the rectangle. The Movie Toolbox sets the upper-left corner to (0,0) in the track’s coordinate system.
You can use the GetTrackBoundsRgn function to determine a track’s boundary region. The GetTrackClipRgn and SetTrackClipRgn functions let you work with a track’s clipping region. You can use the GetTrackMatte and SetTrackMatte functions to establish a track’s matte. The DisposeMatte function allows you to dispose of a matte once you are finished with it.
Working With Sound Volume
The Movie Toolbox allows you to set the sound volume of movies and tracks. Track volumes allow tracks within a movie to have different volumes. A track’s volume is scaled by the movie’s volume to produce the track’s final volume. Furthermore, the movie’s volume is scaled by the sound volume that is returned by the Sound Manager’s GetSoundVol routine. Thus, the user can control the overall volume from the Sound control panel.
Volume values range from -1.0 to 1.0. 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, if you want to toggle the current state of the volume, you can invert the sign of the current volume setting, as shown here:
SetMovieVolume ( theMovie, GetMovieVolume(theMovie) ); |
You can use the GetMovieVolume and SetMovieVolume functions to work with a movie’s volume.
The GetTrackVolume and SetTrackVolume functions allow you to work with a track’s volume.
Locating a Movie's Tracks and Media Structures
The Movie Toolbox provides a set of functions that help your application locate a movie’s tracks and media structures. This section describes these functions.
The Movie Toolbox identifies a movie’s tracks in two ways. First, every track in a movie has a unique ID value. This ID value is unique throughout the life of a movie, even after it has been saved. That is, no two tracks of a movie ever have the same ID, and no ID value is ever reused. Second, a movie’s current tracks may be identified by their index value. Index values always range from 1 to the number of tracks in the movie. Track indexes provide a convenient way to access each track of a movie.
There are several functions that allow you to find a movie’s tracks. You can use the GetMovieTrackCount function to determine the number of tracks in a movie. Use the GetMovieTrack function to obtain the track identifier for a specific track, given its ID. The GetMovieIndTrack function lets you obtain a track’s identifier, given its track index.
You can obtain a track’s ID value given its track identifier by calling the GetTrackID function.
You can determine the movie that contains a track by calling the GetTrackMovie function.
The GetTrackMedia function enables you to find a track’s media. Conversely, you can find the track that uses a media by calling the GetMediaTrack function.
Determining Movie Creation and Modification Time
The Movie Toolbox maintains two timestamps in every movie, track, and media. One timestamp, the creation date, indicates the date and time when the item was created. The other, the modification date, contains the date and time when the item was last changed and saved. The timestamp value is in the same format as Macintosh file system creation and modification times; that is, the timestamp indicates the number of seconds since midnight, January 1, 1904.
The Movie Toolbox provides a number of functions that allow your application to retrieve the creation and modification date information from movies, tracks, and media structures.
You can use the GetMovieCreationTime and GetMovieModificationTime functions to work with movie creation and modification dates.
You can use the GetTrackCreationTime and GetTrackModificationTime functions to retrieve a track’s creation and modification dates.
Your application can call the GetMediaCreationTime and GetMediaModificationTime functions to get a media’s creation and modification dates.
Editing Tracks
The Movie Toolbox provides a number of functions that allow your application to perform editing operations on tracks. These functions work with track segments (pieces of a track that are defined by a starting time and duration) and therefore give you a great deal of control over the editing process. These functions are similar to the low-level editing functions for movies that were described earlier in this chapter. However, these functions may copy movie data, if required by the operation.
When you edit a track you may change the duration of the movie that contains that track.
The CopyTrackSettings function lets you copy certain important settings from one track to another.
You can use the InsertTrackSegment function to copy a segment from one track to another, by reference or by moving data, or to copy a segment within a track. The InsertTrackEmptySegment function allows you to insert an empty segment into a track.
You can use the InsertMediaIntoTrack function to insert a media into a track.
Your application can delete a segment from a track by calling the DeleteTrackSegment function.
You can change a segment’s duration by calling the ScaleTrackSegment function. This function stretches or shrinks the segment to accommodate a specified duration.
You can use the GetTrackEditRate function to determine the rate of the track edit of a specified track at an indicated time.
Undo for Tracks
The Movie Toolbox provides functions that allow you to capture and restore the edit state of a track. As with the functions that manipulate a movie’s edit state, you can manage a track’s edit states in order to implement an undo capability for track editing. For example, you can capture a track’s edit state before performing an editing operation, such as a cut, and later restore the old state. You can have several track edit states obtained at different times during an editing session, and you can restore to any one of them at any time. In this manner, you can provide a multilevel undo capability. This section describes the Movie Toolbox functions that work with track edit states.
Note that a track’s edit state does not save everything about the track. Most important, the edit state does not contain information about track spatial characteristics. For example, the edit state does not store the current clipping region. Consequently, edit states are best suited to supporting undo operations involving track content. You can use other Movie Toolbox functions to support undo operations for track characteristics. See Functions That Modify Movie Properties to learn more about these functions.
You can use the NewTrackEditState function to capture a track’s edit state. Use the UseTrackEditState function to restore the track to its condition according to a previous edit state. Your application can dispose of an edit state by calling the DisposeTrackEditState function.
Selection and Scrap Functions
To get and change a movie’s current selection, your application can call the GetMovieSelection and SetMovieSelection functions.
Your application can work with a movie’s current selection by calling the CutMovieSelection, CopyMovieSelection, PasteMovieSelection, ClearMovieSelection, and AddMovieSelection functions.
The PutMovieOnScrap and NewMovieFromScrap functions enable your application to work with movies that are on the scrap.
The IsScrapMovie function examines the system scrap to determine whether it can translate any of the data into a movie. The PasteHandleIntoMovie takes the contents of a specified handle, together with its type, and pastes it into a movie. PutMovieIntoTypedHandle takes a movie (or a single track from within a movie) and converts it into a handle.
Low-Level Movie-Editing Functions
The Movie Toolbox provides a number of functions that allow your application to perform low-level editing operations on movies. These functions work with movie segments (pieces of a movie that are defined by a starting time and duration) and therefore give you a great deal of control over the editing process. These functions never copy the movie data; rather, they work with references to the movie’s data. Editing Movies discusses the Movie Toolbox functions that allow you to edit movies by working with the current selection.
You can use the CopyMovieSettings function to copy certain important settings from one movie to another.
You can use the InsertMovieSegment function to copy a segment from one movie to another. Use the InsertMovieEmptySegment function to insert an empty segment into a movie.
Your application can delete a segment from a movie by calling the DeleteMovieSegment function.
You can change a segment’s duration by calling the ScaleMovieSegment function. This function stretches or shrinks the segment to accommodate a specified duration.
Summary of Editing Functions
This section lists the functions described earlier in this chapter.
Editing Movies
Undo for Movies
Low Level Movie Editing Functions
Editing Tracks
Undo for Tracks
Locating a Movie’s Tracks and Media Structures
You can find details of these functions in the QuickTime API Reference.
© 2005, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-01-10)