QuickTime Movie Playback Programming Guide 2005-08-11 Simultaneously published in the United Apple Computer, Inc. States and Canada. © 2005 Apple Computer, Inc. Even though Apple has reviewed this document, All rights reserved. APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS No part of this publication may be DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A reproduced, stored in a retrieval system, or PARTICULAR PURPOSE. AS A RESULT, THIS transmitted, in any form or by any means, DOCUMENT IS PROVIDED “AS IS,” AND mechanical, electronic, photocopying, YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND recording, or otherwise, without prior ACCURACY. written permission of Apple Computer, Inc., IN NO EVENT WILL APPLE BE LIABLE FOR with the following exceptions: Any person DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES is hereby authorized to store documentation RESULTING FROM ANY DEFECT OR on a single computer for personal use only INACCURACY IN THIS DOCUMENT, even if and to print copies of documentation for advised of the possibility of such damages. personal use provided that the THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN documentation contains Apple’s copyright LIEU OF ALL OTHERS, ORAL OR WRITTEN, notice. EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any The Apple logo is a trademark of Apple modification, extension, or addition to this Computer, Inc. warranty. Some states do not allow the exclusion or Use of the “keyboard” Apple logo limitation of implied warranties or liability for (Option-Shift-K) for commercial purposes incidental or consequential damages, so the above limitation or exclusion may not apply to without the prior written consent of Apple you. This warranty gives you specific legal may constitute trademark infringement and rights, and you may also have other rights which vary from state to state. 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, Carbon, Cocoa, iTunes, Mac, Mac OS, Quartz, QuickDraw, and QuickTime are trademarks of Apple Computer, Inc., registered in the United States and other countries. eMac and Sound Manager are trademarks of Apple Computer, Inc. OpenGL is a registered trademark of Silicon Graphics, Inc. Contents Introduction Introduction To QuickTime Movie Playback Programming Guide 7 Organization of This Document 7 See Also 7 Chapter 1 Overview 9 Chapter 2 Setting Up Graphics and Audio Output 11 Creating a Visual Context 12 Using a Graphics Port or GWorld 13 Changing a Movie’s Graphics Destination 13 Switching to Full-Screen Mode 14 Setting an Audio Context 14 Chapter 3 Getting a Movie 15 Getting a Movie in QuickTime 7 or Later 15 The Movie Properties Array 15 Specifying a Visual Context Property 17 Specifying a Movie Data Source Property 18 Getting a Movie Using NewMovieFromProperties 18 Getting a Movie in QuickTime 6 21 Setting a Graphics Destination in QuickTime 6 and Earlier 21 Specifying a Movie Data Source Using a Data Reference 21 Getting a Movie Using NewMovieFromDataRef 22 Getting a Movie in Older Versions of QuickTime 23 Chapter 4 Monitoring the Load State 25 The Download Sequence 25 Local Movies 26 Movie Files on the Internet 26 Non-Movie Data Sources 27 Example of Getting a Movie and Monitoring the Load State 27 3 2005-08-11 | © 2005 Apple Computer, Inc. All Rights Reserved. CONTENTS Chapter 5 Playing a Movie 31 Playing a Movie Using HIMovieView 32 Creating an HIMovieView 32 Configuring an HIMovieView 34 HIMovieView and Your Run Loop 36 Playing a Movie Using a Carbon Movie Control 36 Creating and Configuring a Carbon Movie Control 36 Carbon Movie Controls and Your Run Loop 37 Playing a Movie Using a Movie Controller Component 38 Working Directly with Movie Controller Components 39 Bypassing the Movie Controller 41 Chapter 6 Appendix A 43 File Types that QuickTime Can Open as Movies 43 Playing a Movie Using Low-Level Commands 44 Chapter 7 Movie Playback Reference 47 Error Functions 47 FullScreen Functions 47 Event Loop Functions 47 Graphics Destination Functions 48 Visual Playback Functions 48 Audio Playback Functions 48 Functions that Get Movies from Storage 49 HIMovieView Functions 49 Carbon Movie Controller Functions 49 Movie Controller Component Functions 50 Low-Level Movie Toolbox Functions 51 Constants and Selectors 51 Movie Property Constants 52 Full Screen Flags 53 Movie Controller Component Constants and Selectors 53 Document Revision History 57 4 2005-08-11 | © 2005 Apple Computer, Inc. All Rights Reserved. Figures and Listings Chapter 3 Getting a Movie 15 Listing 3-1 Creating a visual context 17 Listing 3-2 Creating a URL from a string 18 Listing 3-3 Getting a movie using NewMovieFromProperties 20 Listing 3-4 Creating a data reference and calling NewMovieFromDataRef 23 Chapter 4 Monitoring the Load State 25 Listing 4-1 Getting a movie and monitoring the load state 27 Chapter 5 Playing a Movie 31 Figure 5-1 Creating an HIMovieView with Interface Builder 33 Listing 5-1 Using a movie controller component to play a movie 38 Chapter 6 Appendix A 43 Listing 6-1 Movie playing loop 45 5 2005-08-11 | © 2005 Apple Computer, Inc. All Rights Reserved. FIGURES AND LISTINGS 6 2005-08-11 | © 2005 Apple Computer, Inc. All Rights Reserved. INTRODUCTION Introduction To QuickTime Movie Playback Programming Guide This document describes how to open and play stored media, including QuickTime movies and other formats that QuickTime can automatically import and play, from sources such as a file, URL, pointer, or handle. This document supersedes and replaces "Opening and Playing Movies." The information in this document is of interest to nearly all developers working with QuickTime. This document is intended for programmers working in C or C++ using the Carbon or QuickTime for Windows frameworks. Cocoa developers should generally use the QuickTime Kit framework instead, but may have occasion to use the interfaces described here for access to low-level functions not duplicated in Cocoa. Organization of This Document This document contains the following sections: ■ “Overview” (page 9) ■ “Setting Up Graphics and Audio Output” (page 11) ■ “Getting a Movie” (page 15) ■ “Monitoring the Load State” (page 25) ■ “Playing a Movie” (page 31) ■ “Appendix A: File Types QuickTime Can Open as Movies” (page 43) ■ “Appendix B: Playing a Movie Using Low-Level Commands” (page 44) ■ “Movie Playback Reference” (page 47) See Also Before you read this document, you should already be familiar with QuickTime Initialization Guide and QuickTime Overview. If you are new to QuickTime, see Getting Started with QuickTime. Organization of This Document 7 2005-08-11 | © 2005 Apple Computer, Inc. All Rights Reserved. INTRODUCTION Introduction To QuickTime Movie Playback Programming Guide 8 See Also 2005-08-11 | © 2005 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Overview In QuickTime you play media of any kind—sound, video, still images, text, or animation—by creating a movie data structure in memory and playing the movie. The movie is the fundamental data structure in QuickTime; it describes what media to present, where the media samples are located, and how and when to present them (duration, sequencing, compositing, layering, rotation and scaling, sound volume, and so on). Important: Movies do not contain sample data, such as images or sound samples; movies contain datareferences that point to blocks of sample data. These data references can be file aliases, URLs, pointers, handles, or other types of references. Playing a movie typically generates graphic output in a window, but other kinds of output are possible: a sound-only movie may not create a visible display; a movie may display using the whole screen instead of a window, or may render to an offscreen buffer or an external device such as a Firewire video recorder. Video output can be rendered directly to video memory as a series of OpenGL textures. Audio output can be directed to an external device or recorder. In addition to playing existing QuickTime movies, QuickTime can automatically play media in over forty different formats and file types, including AIFF, WAVE, and MP3 audio; MPEG-1, MPEG-4, 3GPP, and DV video; JPEG, PNG, and GIF still images; and Flash and various other animation formats. For a full list, see “File Types that QuickTime Can Open as Movies” (page 43). The movie or other media to be played can be stored in a file, a stream, or a buffer in memory, and can be accessed through a data reference such as a path and filename, file specification, URL, pointer, or handle. Movies are typically stored in QuickTime movie files. The movie data samples are stored separately, either elsewhere in the same file or in other storage locations. When you get a movie from a QuickTime movie file, QuickTime copies the stored movie data structure into memory, then resolves the references to the sample data. When you get a movie from a source other than a QuickTime movie file, such as a native MP3 or JPEG file, QuickTime creates a new movie describing the sample data; this is called importinginplace, because the sample data is not modified but remains in place. The import process consists of creating a movie data structure that describes the existing media.