Movie Toolbox: Creating Movies

September 17, 2002

Apple Computer, Inc. ' 2004 Apple Computer, Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Computer, Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. The Apple logo is a trademark of Apple Computer, Inc. Use of the “keyboard” Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled or Apple-licensed computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Mac, Macintosh, and QuickTime are trademarks of Apple Computer, Inc., registered in the United States and other countries. Simultaneously published in the United States and Canada. Even though Apple has reviewed this manual, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS MANUAL, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS

MANUAL IS SOLD “AS IS,” AND YOU, THE PURCHASER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS MANUAL, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state.

Contents Chapter 1

Movie Toolbox: Creating Movies 5 Creating a Movie 5 Creating Tracks and Media Structures 5 Working With Data References 6 Working With Media Samples 6 Adding Samples to Media Structures 6 Working With Movie User Data 7

3 © 2004 Apple Computer, Inc. All Rights Reserved.

C O N T E N T S

4 © 2004 Apple Computer, Inc. All Rights Reserved.

C H A P T E R

1

Movie Toolbox: Creating Movies

This document describes the functions of the movie toolbox you can use to create new movies. This includes steps such as creating a new movie data structure, creating tracks and media structures, adding samples to the movie sample data with data references in a track’s media structure, and so on. This document covers most of the functions you use to create a movie containing sample data that you synthesize programmatically. If you are creating a movie by capturing real-time audio or video, see the sections on Sequence Grabbers. If you are creating a movie by importing and converting media files such as JPEG images and MP3 audio, see the sections on Import/Export. You will need to read this chapter if your application creates movies. You should also be familiar with Movie Basics.

Creating a Movie Inside Macintoshshows how to create a new movie. A sample program is given, detailing the necessary steps: creating and opening a file to hold the movie, creating the tracks and media structures for audio and video, adding sample data, and adding movie resources to the file. Read this section to see a sample program that will step you through the procedure in tutorial fashion.

Creating Tracks and Media Structures Inside Macintosh describes the functions your application can use to create and dispose of tracks and media structures. These functions are used when creating movies, or when editing movies at the track level. ■

NewMovieTrack

■

DisposeMovieTrack

■

NewTrackMedia

■

DisposeTrackMedia

Creating a Movie © 2004 Apple Computer, Inc. All Rights Reserved.

5

C H A P T E R

1

Movie Toolbox: Creating Movies

Working With Data References Inside Macintosh describes the functions used to work with data references. Media structures point to their actual sample data using data references. A data reference can point to sample data located in t he same movie file as the movie, or in a separate file, or referenced by a URL, pointer, or handle. Media handlers use data references in order to manipulate media data without needing to deal directly with filenames, network protocols, or URLs. ■

AddMediaDataRef

■

SetMediaDataRef

■

GetMediaDataRef

■

GetMediaDataRefCount

Working With Media Samples Inside Macintosh describes the functions your application can use to determine information about a movie's sample data, such as the size in bytes of the data in a movie, track, or media, or the number of samples in a media, or the media's sample description. ■

GetMovieDataSize

■

GetTrackDataSize

■

GetMediaDataSize

■

GetMediaSampleCount

■

GetMediaSampleDescriptionCount

■

GetMediaSampleDescription

■

SetMediaSampleDescription

■

MediaTimeToSampleNum

■

SampleNumToMediaTime

Adding Samples to Media Structures Inside Macintosh describes several functions your application can use to directly manipulate data samples and media references. When you add samples to a movie’s sample data, you also add references to the data in the media structure of a track in the movie. If you like, you can add references to existing sample data to a track’s media structure without adding new sample data. The function names can be somewhat misleading. BeginMediaEdits allows you to add actual data samples. You can add data references to a track’s media structure without calling BeginMediaEdits. It might be more accurate to think of this as Begin SampleEdits.

6

Working With Data References © 2004 Apple Computer, Inc. All Rights Reserved.

C H A P T E R

1

Movie Toolbox: Creating Movies

Note that you can add data samples, but not delete them. You can cause samples to be skipped by removing track segments that play them (this creates an edit list entry for the track). You can also save a flattened copy of the movie, which will include only the data samples that are played. By deleting track segments and f lattening the movie, you create a copy of the sample data that does not contain undesired samples. QuickTime is, by design, a nondestructive editing tool. New functions not described in Inside Macintosh have been added to the list. Note that GetMediaSampleReferences and AddMediaSampleReferences are new plural forms to the original GetMediaSampleReference and AddMediaSampleReference, allowing you to work with multiple samples at once. This is generally far more efficient. Original: ■

BeginMediaEdits

■

EndMediaEdits

■

AddMediaSample

■

AddMediaSampleReference

■

GetMediaSample

■

GetMediaSampleReference

New: ■

GetMediaSampleReferences

■

AddMediaSampleReferences

■

SetMediaDefaultDataRefIndex

■

SetMediaPreferredChunkSize

■

GetMediaPreferredChunkSize

Working With Movie User Data Inside Macintosh describes the functions your application can use to work with movie user data. Each movie, track and media can contain a user data list, which can be used for any purpose you like. You can create new user data types using the format described in this section. Predefined user data types are listed, including fields for the movie's name, copyright notice, and various credits. ■

GetMovieUserData

■

GetTrackUserData

■

GetMediaUserData

■

GetNextUserDataType

■

CountUserDataType

■

AddUserData

Working With Movie User Data © 2004 Apple Computer, Inc. All Rights Reserved.

7

C H A P T E R

1

Movie Toolbox: Creating Movies

8

■

GetUserData

■

RemoveUserData

■

AddUserDataText

■

GetUserDataText

■

RemoveUserDataText

■

SetUserDataItem

■

GetUserDataItem

■

NewUserData

■

DisposeUserData

■

PutUserDataIntoHandle

■

NewUserDataFromHandle

Working With Movie User Data © 2004 Apple Computer, Inc. All Rights Reserved.