QuickTime 4.1
Apple Technical Publications
January 2000
Apple Computer, Inc. Apple, the Apple logo, FireWire, Mac, LIMITED WARRANTY ON MEDIA AND © 2000 Apple Computer, Inc. Macintosh, and QuickTime are REPLACEMENT All rights reserved. trademarks of Apple Computer, Inc., ALL IMPLIED WARRANTIES ON THIS No part of this publication or the registered in the United States and other MANUAL, INCLUDING IMPLIED software described in it may be countries. WARRANTIES OF MERCHANTABILITY reproduced, stored in a retrieval system, The QuickTime logo is a trademark of AND FITNESS FOR A PARTICULAR or transmitted, in any form or by any Apple Computer, Inc. PURPOSE, ARE LIMITED IN DURATION means, mechanical, electronic, Adobe, Acrobat, Photoshop, and TO NINETY (90) DAYS FROM THE DATE photocopying, recording, or otherwise, PostScript are trademarks of Adobe OF DISTRIBUTION OF THIS PRODUCT. without prior written permission of Systems Incorporated or its subsidiaries Even though Apple has reviewed this Apple Computer, Inc., except in the and may be registered in certain manual, APPLE MAKES NO WARRANTY normal use of the software or to make a jurisdictions. OR REPRESENTATION, EITHER EXPRESS backup copy of the software or Flash is a trademark of Macromedia OR IMPLIED, WITH RESPECT TO THIS documentation. The same proprietary Incorporated. MANUAL, ITS QUALITY, ACCURACY, and copyright notices must be affixed to MacPaint is a trademark of Apple MERCHANTABILITY, OR FITNESS FOR A any permitted copies as were affixed to Computer, Inc., registered in the U.S. PARTICULAR PURPOSE. AS A RESULT, the original. This exception does not and other countries. THIS MANUAL IS DISTRIBUTED “AS IS,” allow copies to be made for others, AND YOU ARE ASSUMING THE ENTIRE whether or not sold, but all of the Helvetica and Palatino are registered trademarks of Linotype-Hell AG and/or RISK AS TO ITS QUALITY AND material purchased (with all backup ACCURACY. copies) may be sold, given, or loaned to its subsidiaries. another person. Under the law, copying Indeo and Intel are registered IN NO EVENT WILL APPLE BE LIABLE includes translating into another trademarks of Intel. FOR DIRECT, INDIRECT, SPECIAL, language or format. You may use the ITC Zapf Dingbats is a registered INCIDENTAL, OR CONSEQUENTIAL software on any computer owned by trademark of International Typeface DAMAGES RESULTING FROM ANY you, but extra copies cannot be made for Corporation. DEFECT OR INACCURACY IN THIS this purpose. MANUAL, even if advised of the possibility of such damages. The Apple logo is a trademark of Apple PowerPC and the PowerPC logo are Computer, Inc. Use of the “keyboard” trademarks of International Business THE WARRANTY AND REMEDIES SET Apple logo (Option-Shift-K) for Machines Corporation, used under FORTH ABOVE ARE EXCLUSIVE AND IN commercial purposes without the prior license therefrom. LIEU OF ALL OTHERS, ORAL OR written consent of Apple may constitute WRITTEN, EXPRESS OR IMPLIED. No trademark infringement and unfair Apple dealer, agent, or employee is competition in violation of federal and Simultaneously published in the United authorized to make any modification, state laws. States and Canada. extension, or addition to this warranty. No licenses, express or implied, are Printed in the United States of America. Some states do not allow the exclusion or granted with respect to any of the limitation of implied warranties or liability technology described in this book. for incidental or consequential damages, so Apple retains all intellectual property the above limitation or exclusion may not rights associated with the technology apply to you. This warranty gives you described in this book. Every effort has specific legal rights, and you may also have been made to ensure that the other rights which vary from state to state. information in this manual is accurate. Apple is not responsible for printing or clerical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010
Contents
Summary of Changes and Enhancements 9 SMIL Support 11 SMIL Usage 11 A Simple Sequence 12 A Sequence with HREF, Region and Background Text 13 QuickTime SMIL Extensions 14 Namespace Specification 15 SMIL Root Element Attributes 15 Media Object Attributes 17 Anchor-Tag and A-Tag Attributes 19 References 19 SMIL Importer Implementation 20 How It Works 20 Not Instantiating Media at Import Time 20 A New Movie Media Track 21 Movie Media Track Usage 21 Movie Media Handler 22 Sample Description 22 Sample Format 22 New Movie Media Handler APIs 28 New Movie Media Handler APIs to Handle Data References 30 Movie Media Handler Tasks 31 Using the Streaming Media Handler 32 A Note to Authors of Media Handlers 32 Support for Data URLs 33 URLs in Text Tracks 35 New Embed Tags 35 URLSUBSTITUTE Embed Tag 36 How It Works 36 AUTOHREF Embed Tag 37
3
QTSRCDONTUSEBROWSER Embed Tag 37 Support for an HTML Importer 37 How It Works 38 Additional Notes 39 Support for HTTP Streaming 40 New HTTP Streaming Functionality 40 Additional Cookie Support 42 64-bit File Offset Support for Mac OS 9 43 New Features For Creating More Interactive Movies 44 Introducing Embedded Movies 44 Creating New Types of QuickTime Movies 44 Using Embedded Movies 45 Dynamically Loading New Embedded Movies from URLs 46 Triggering Wired Actions When an Embedded Movie is Loaded 47 Targeting Elements of Embedded Movies with All Existing Wired Actions 47 New Movie Track and Movie Wired Actions 49 New Wired QT Event 50 Extended Wired Operand Functionality 50 Wired Actions and JavaScript 50 Added Flash Support 51 New Target Type Atoms for Hierarchical Movies 51 Example #1 53 Example #2 53 New Movie Property Atom Toolbox Routines 54 New Movie Controller Actions 54 Custom Wired Actions 55 Custom Action Handler Usage 56 Authoring Custom Wired Actions 57 Extension to Wired Movie Format: Executing Custom Actions 57 New Wired Actions 57 New Wired Operands 58
4
Writing a Custom Action Handler Component 58 The Action Being Executed 60 Fetching the Parameters 60 API Additions 62 Support for Playback of VBR Audio 62 Changes to Graphics Importers 62 New Anchor Data Reference 63 A New Data Handler Routine 63 Support for M3U Playlists and .CEL Files 64 JavaScript Support 64 Movie Commands 64 Movie Properties 65 Track Properties 72 Sprite Track Properties 72 QuickTime VR Movie Properties 73 Plug-in Properties 73 QuickTime Properties 74 Sample JavaScript Usage 75 Introduction of Asynchronous Movie Loading 77 A Change in the Loading Model 79 GetMovieStatus Updated 81 Other API Additions 82 Support for Playback of VBR Audio 82 Background 82 VBR-Supported Features 83 New Sound Manager APIs 83 Working with SoundConverterFillBuffer 86 Writing the SoundConverterFillBufferData Routine 88 Sound.h Updated 89 SoundMediaGetSource 89 API Changes 89 ExtendedSoundComponentData 90 ExtendedSoundParamBlock 91 ExtendedScheduledSoundHeader 92
5
Changes to QuickTime for Java 95 Deprecation of AWT Dependencies 95 A New Event Model and Suite of New Classes 96 New Mouse Controllers 97 New DragAdaptor and TranslateMatrix Classes 97 The quicktime.app.ui Package 98 New QTButton Sample Code 98 Support for QuickTime 4 APIs 98 New Additions 99 Support for Text Drawing 99 AppleScript Support 100 QuickTime Player Standard Suite terms 100 The close command 101 The count command 101 The exists command 102 The open command 102 The print command 103 The quit command 103 The save command 103 QuickTime Player Suite terms 104 The can export command 104 The export command 105 The find command 107 The open location command 107 The play command 108 The present command 108 The rewind command 109 The select command 109 The select all command 109 The select none command 110 The step backward command 110 The step forward command 110 The stop command 111 QuickTime Player Classes 111 The annotation class 111 The application class 113 The favorite class 115
6
The file class 116 The internet location class 117 The movie class 117 The track class 122 The window class 125
7
8
What’s New in QuickTime 4.1 1
This document provides you with a list of changes from QuickTime 4 to QuickTime 4.1, as well as new features and capabilities available in this software release. It is intended to supplement the information provided in the QuickTime 4 API Reference. If you are a QuickTime API-level developer or a QuickTime content creator or provider, you should read this document. For QuickTime developer documentation, refer to
Summary of Changes and Enhancements 1
The primary focus of the QuickTime 4.1 release is to provide advertising insertion capability for QuickTime content providers and firewall support for QuickTime end users. A number of additional features and enhancements have also been included in this release. These are intended to benefit both content providers and end users. In brief, QuickTime 4.1 includes the following changes: Added 64-bit file support for Mac OS 9, which enables recording and playback of movie files larger than 2 gigabytes (2G) on Mac OS 9. Added support for Synchronized Multimedia Integration Language (SMIL), a simple, text-based format defined by W3C
Summary of Changes and Enhancements 9
RELEASE 1.0
What’s New in QuickTime 4.1
insert advertising content in a sequence of streams, using QuickTime 4.1’s implementation of the SMIL standard. Added the capability of movies to embed other movies as a track, which means that movies may now contain other movies which may have independent clocks. This is accomplished by means of a new Movie Media Handler API. The addition of variable bit rate (VBR) support for MP3 and MP3 playlists via M3U files. Improved navigation through firewalls. The QuickTime Settings control panel has additional options for Streaming Proxy settings and a new Streaming Transport panel. Users may click the Auto Configure button in the Streaming Transport panel. AppleScript support (on Mac OS). Developers and scripters can now use AppleScript and QuickTime Player to automate tasks. AppleScript support provides Macintosh content creators with the capability to automate distribution and playback of QuickTime content. Access to sites requiring authentication, e.g., pay-per-view sites. New wired actions and events for creating more advanced, interactive wired movies. Additions and changes to QuickTime for Java, including deprecation of AWT dependencies and the addition of two new packages. Changes to the QuickTime VR controller, so that buttons now match the standard QuickTime controller. JavaScript support now includes the capability of accessing the QuickTime Plug-in, thus enabling you to control the Plug-in via JavaScript methods. Elimination of support for 68K Macintosh computers. However, QuickTime movies running under 68K Macintosh computers still work. QuickTime 4.1 now only supports Power PC computers and Mac OS 7.5.5 or later, in addition to Windows 95, Windows 98, and Windows NT. Note that QuickTime 4.1 is still backward compatible and plays all existing QuickTime movies.
10 Apple Summary of Changes and Enhancements
RELEASE 1.0
What’s New in QuickTime 4.1
SMIL Support 1
SMIL is a simple, text-based language that allows content creators and providers to mix and synchronize multimedia elements. This capability, now supported in QuickTime 4.1, enables content authors and developers to incorporate, for example, advertising clips into stored and live streams of QuickTime movies. SMIL, derived from XML, describes the temporal and spatial layouts of media clips within media presentations. It also allows the optional specification of hyperlinks for each clip. Because SMIL elegantly describes simple sequences and because it uses a familiar HTML-like syntax for specifying hyperlinks, it is ideal for the purpose of advertising insertion.
Note The complete SMIL specification is available at
SMIL Usage 1 Using the SMIL capability provided in QuickTime 4.1, you can generate a SMIL document that will trigger a sequence to play audio, video, animated GIFs, or any other QuickTime-supported media. This sequence can be used for advertising messages. An ad can be, for example, an audio clip, a video clip, an animated GIF, a fast-start QuickTime movie, or a streamed movie. Any media type that QuickTime can import is allowable as an ad. A sequence of media content, including ads and either the stored or live stream, is described within a SMIL document.
SMIL Support 11
RELEASE 1.0
What’s New in QuickTime 4.1
Playback and performance of media clips are designed to be as smooth as possible. Whenever there is sufficient network bandwidth to handle the requirements of the content used, transitions between different media are seamless. QuickTime delays opening the connection to the media on the server until as late as possible before displaying the media, so that servers can reliably count the hits. From a server-side application, SMIL documents can be customized for a particular user. You can also define the content of the sequence dynamically. This capability is similar to a playlist, but unlike playlists, you can specify the spatial and temporal characteristics of the sequence. For example, SMIL may be used in the following context. An end user clicks on a link in a Web browser or in a movie in QuickTime Player and then a server decides what will be the right sequence of media to present. In order to accomplish this, the server may generate a SMIL document via CGI or some other mechanism. The SMIL document may be a sequence of media, such as an advertisement followed by other content.
A Simple Sequence 1 In the example in Listing 1, an image starts by displaying a logo in JPEG format for five seconds. It then plays streaming video, which is a stored stream. This particular SMIL document does not specify the duration, which means that it will play for its entire length. Once it has finished, it will display the very same JPEG image at the end. Using this simple sequence, you could wrap or bracket a stream, for example, with your company logo.
Listing 1 A SMIL file displaying a JPEG image for five seconds, then playing a VOD stream to the end of the movie, followed by displaying a JPEG image without duration
12 Apple SMIL Support
RELEASE 1.0
What’s New in QuickTime 4.1
Simple sequences are very easy to create. In the body of a SMIL document, you can explicitly state that this is a sequence by using the
A Sequence with HREF, Region and Background Text 1 In the example in Listing 2, a streamed video of known duration that is hyperlinked is displayed for its entire duration, followed by a live video stream. In this more complex example, you specify a background color that defines a single region with a width and height. This one defines several regions and is more elaborate about the layout. It tells you that the overall presentation should be a certain size, the background color should be a certain value, and within the root layout you have several other regions which you use in playback. In this example, the playback is at 100 percent of the width and height. The result is an iBook commercial that appears first via RTSP. If you click in the content region during its duration, you invoke the URL in a browser window, launching the browser if it is not already open. Once the iBook commercial is finished, it is followed by the Apple PowerMac G4 tanks commercial via RTSP.
SMIL Support 13
RELEASE 1.0
What’s New in QuickTime 4.1
Listing 2 A SMIL file displaying a streamed video of known duration, which is click- through enabled (hyperlinked), followed by a live video stream
It is possible to extend these examples and introduce more elaborate spatial and temporal layouts, so that you can make more than one thing happen at a time. You can have sequences within hierarchies, for example.
QuickTime SMIL Extensions 1
This section discusses the extensions to SMIL (Synchronized Multimedia Integration Language) 1 that are implemented as part of the SMIL support provided in QuickTime 4.1. SMIL being an XML markup language 2, it describes the XML Namespace 3 under which the extensions are grouped; it also describes the extensions themselves –– grouped according to the SMIL
14 Apple QuickTime SMIL Extensions
RELEASE 1.0
What’s New in QuickTime 4.1
elements they may be used in conjunction with –– their syntax, and example usage. The QuickTime SMIL Extensions allow an author to optionally specify richer behaviors which are supported by QuickTime but do not have an SMIL equivalent; they also give the author tighter control over the behavior of the playback of SMIL presentations across bandwidth-constrained network connections.
Namespace Specification 1 These extensions to SMIL are described in a separate namespace from SMIL and must be referenced explicitly by any SMIL document that wants to take advantage of them. The namespace URL is
which must be used as an attribute to any SMIL element. Nsprefix (the selected namespace prefix) may be any character string which conforms to the requirements for an XML name. Once the namespace has been referenced by a SMIL element, that element itself or any elements within it may legally use the names defined in the namespace, and the usage is as follows: nsprefix:qt_attribute = attribute_value
In general, it is simplest to place the xmlns reference as the first attribute in the root
SMIL Root Element Attributes 1 The QuickTime SMIL Extensions define the following additional attributes for the
QuickTime SMIL Extensions 15
RELEASE 1.0
What’s New in QuickTime 4.1
next: Specifies to the player that after this presentation is finished, the presentation referenced in the attribute value should be invoked and played in the same space. Used to chain presentations together. A valid attribute value is any URL. This capability is equivalent to the QuickTime browser plug-in’s “qtnext” attribute. Common usage is:
time-slider: Specifies whether a time line should be displayed as part of the user interface. Because by default the QuickTime playback engine dynamically loads media objects as required, the duration of the overall media presentation can change as a movie is played or navigated. When the duration changes, the time line will change to reflect that. This can be unnecessarily confusing to the user. Therefore, by default, QuickTime movies created from a SMIL document do not display a time line as part of their user interface. This behavior can be overriden using the “time-slider” attribute. Common usage is:
immediate-instantiation: Specifies whether the media objects within the presentation should be instantiated immediately, i.e., at the same time the presentation itself is instantiated, or whether instantiation should be deferred until the element is ready to be played back. Legal values are either “true” or “false,” and the default is “false.” The value of this attribute may be overridden on a media-object basis by using it as an attribute to individual media-object elements, as described below. Because this attribute causes all media objects to be instantiated, it can take considerable time and memory for a complex presentation or one being loaded over a slow network connection. Therefore, it is recommended that it only be used on small media objects. Common usage is:
chapter-mode: Specifies to the player, both QuickTime Player and the Movie Controller, the way in which chapters should be used in the user interface when a time line is part of the interface. The chapter-mode attribute can have a value of “all” or “clip”. If the attribute is not present, the default value is “all”. If the chapter-mode attribute is “all”, then the player displays the time line of the entire duration of the presentation. Each chapter represents a point along that time line. If the chapter-mode attribute is set to “clip”, then the
16 Apple QuickTime SMIL Extensions
RELEASE 1.0
What’s New in QuickTime 4.1
time line no longer represents the entire duration of presentation. Instead, it represents the duration of the current chapter. The “clip” behavior is useful for long presentations where the granularity of the timeline may be unacceptably low. It is also useful for network-based presentations, particularly those using streaming media, where the actual duration of a clip isn’t known until it has started to play. By using the “clip” value of the chapter-mode, the user will not be exposed to the duration changes of the presentation caused by the loading of media as the presentation is played or navigated. Common usage is:
Media Object Attributes 1
composite-mode: Specifies how to composite a visual media element with other visual media elements behind it. Its value is a combination of a text string identifying the mode and an optional semicolon and second parameter, which will vary depending on the mode itself. The composite-mode SMIL attribute is equivalent to the graphics mode property of a Movie’s Media. Possible modes are: copy, none, direct: Specifies a direct copy. The default composite mode for most image formats. blend;percent : Specifies a weighted blend between the image and the background, with a required percent integer value (i.e., “50%”) specifying the blend weight. 0% means complete transparency, 100% complete opacity. transparent-color;color: Specifies that all pixels of a particular color within the image should be treated as transparent, similar to transparency in GIF files [GIF89]. It accepts a second parameter, color, which specifies the color to be rendered as transparent. The color parameter may be any valid color specification supported by Cascading Style Sheets Level 2 4. alpha, straight-alpha, premultiplied-white-alpha, premultiplied-black-alpha: Specify that the image has an internal alpha channel which should be used when compositing. Alpha and straight-alpha refer to a separate alpha component; the premultiplied modes refer to an image which has been premultiplied with the alpha against a white or black background, respectively.
QuickTime SMIL Extensions 17
RELEASE 1.0
What’s New in QuickTime 4.1
straight-alpha-blend: Specifies that the image has an internal alpha channel as a separate component, and that when compositing the alpha weight should also be multiplied by a percentage blend value, which is specified by a second parameter, similar to the second parameter in blend mode. Example usage:
immediate-instantiation: Performs the same function as the identically named attribute for the
bitrate: Specifies the bitrate at which a media object would need to be transmitted in order to play back in real time. It is used in conjunction with immediate-instantiation, in order to give QuickTime enough information to decide how far in advance it should attempt to read a delayed-instantiation media object in order to provide seamless playback. Possible values are positive integers, in units of bits-per-second. Example usage:
system-mime-type-supported: Specifies to the player the MIME type that needs to be supported in order to be able to play back this particular media-object. Though similar, at first blush, to the type attribute, this is intended to be used in conjunction with the switch element in SMIL, in a similar fashion as the other system attributes, such as system bitrate and system screen definitions. Possible values are character strings matching a valid MIME type. Example usage is:
attach-timebase: Defaults to "true", which slaves the timebase of the child movie to the parent’s. This means that play/pause controls will control the child movie as well as the parent. Setting it to “false” unlinks the timebase,
18 Apple QuickTime SMIL Extensions RELEASE 1.0
What’s New in QuickTime 4.1
which is useful for interactivity operations, especially when using the SMIL
chapter: Specifies to the player a chapter name to attach to this particular media object, which then may be used by the player to provide a higher-level navigation UI than a simple linear control. Valid values are any character string, and example usage is:
Anchor-Tag and A-Tag Attributes 1
target: Specifies where the presentation specified by the href attribute in the anchor tag will play; possible values are any values legal in the QuickTime Plug-in’s qtnext attribute. The target attribute can also be used to specify that a media object should be opened in the QuickTime Player, a new browser window, a QuickTime Player window, or a particular frame in the browser. Example usage:
References 1 1 Synchronized Multimedia Integration Language (SMIL) 1.0 Specification, P. Hoschka, 15 June 1998. Available at
QuickTime SMIL Extensions 19 RELEASE 1.0
What’s New in QuickTime 4.1
SMIL Importer Implementation 1
This section discusses in detail some of the features of the QuickTime SMIL importer implementation. Read this section if you need to understand the logic behind this implementation. The QuickTime SMIL importer creates media presentations in the form of QuickTime movies according to descriptions given in SMIL format. In QuickTime 4.1, the SMIL importer creates a movie with one or more tracks, using the Movie Media Handler.
How It Works 1 Once the movie has been constructed, the SMIL importer relies heavily on the Movie Media Handler to handle the runtime details. For example, the SMIL importer does not “know” the actual dimensions of the movie because it doesn’t instantiate the media. Thus, the spatial layout may need to be adjusted when the actual dimensions are known. The Movie Media Handler takes care of this by using the spatial composition information that the SMIL importer put into the movie media’s sample data (taken from the SMIL document’s layout section). Similarly, the duration of the media may not be known. A SMIL document does not have to –– and usually does not –– specify the duration of a media element. Instead, it describes the temporal relationships between elements (i.e., play this element after this other element). The Movie Media Handler adjusts the temporal layout of the movie by editing it at runtime. As with spatial layout changes, the temporal changes are made based on information taken from the SMIL document’s body and placed in the movie media sample.
Not Instantiating Media at Import Time 1 The SMIL importer does not instantiate the media elements at import time in order to get their spatial and temporal characteristics. The reasons for this are enumerated as follows: Time. Opening every media element will be slow, particularly over a network. And for streaming content, opening the media element isn’t
20 Apple SMIL Importer Implementation RELEASE 1.0
What’s New in QuickTime 4.1
sufficient. The duration and dimensions aren’t available until media data is actually flowing, which requires actually starting to play the content. Counting. Some of the anticipated users of SMIL may wish to track views of particular pieces of content. If the SMIL importer were to instantiate the media at import time, the hit counters would be incremented before the media had actually been viewed. In a composition of any duration, this means that it would be likely that some media would be counted even though it was never viewed. Changes in duration or spatial characteristics. The media element could change in duration or spatial characteristics between the time that the SMIL importer has finished its work and the media is actually viewed. In a longer composition this is more likely, but it can also occur if the user opens a composition but doesn’t play it immediately. Having the ability to compensate for these changes at runtime regardless of why they occur creates a more robust system.
A New Movie Media Track 1 The SMIL importer creates a movie media track for each media element in the SMIL composition. This is done primarily to accommodate the potentially unknown spatial layout of each element. Because a track can only have one location and size, if multiple media elements were combined in a single track the track would need to be resized and moved at runtime with much greater frequency than if each element is in its own track. The SMIL importer always creates a single video track which uses a solid color fill based on the background color specified in the SMIL document. This track exists for the entire duration of the SMIL composition, though it may or may not be visible depending on the overall layout.
Movie Media Track Usage 1 Because SMIL can refer to content indirectly and because access to media is avoided until as late as possible before displaying it –– in order to preserve meaningful hit counts –– the specific types of content a SMIL document references may not be known at import time. To handle this situation, QuickTime creates a generalized type of track that can play any type of content that QuickTime can import into a movie. Using this new type of track –– called a movie track –– the SMIL importer doesn’t have to
SMIL Importer Implementation 21 RELEASE 1.0
What’s New in QuickTime 4.1
“know” the type of the content a SMIL document references. It simply creates a movie track for each piece of content, and the movie track makes use of QuickTime’s extensive import facilities at the time the content is played. This new type of track is implemented by the Movie Media Handler.
Movie Media Handler 1
This section describes the features of the Movie Media handler available in QuickTime 4.1.
Sample Description 1 The Movie Media handler doesn’t have a unique Sample Description. It uses the minimum Sample Description which is SampleDescriptionRecord.
Sample Format 1 Each sample in the movie media is a QuickTime Atom Container. All root level atoms and their contents are enumerated in the following list. Note that the contents of all atoms are stored in big-endian format. kMovieMediaDataReference This atom contains a data reference type and a data reference. The data reference type is stored as an OSType at the start of the atom. The data reference is stored following the data reference type. If the data reference type is URL and the data reference is for a movie on the Apple Web site, the contents of the atom would be: “url http://www.apple.com/foo.mov”. There may be more than one atom of this type. The first atom of this type should have an atom ID of 1. Additional data references should be numbered sequentially. kMovieMediaDefaultDataReferenceID
This atom contains a QTAtomID which indicates the ID of the data reference to use when instantiating the embedded movie for this sample. If this atom is not present, the data reference with an ID of 1 is used.
22 Apple Movie Media Handler RELEASE 1.0
What’s New in QuickTime 4.1
kMovieMediaSlaveTime This atom contains a Boolean that indicates whether or not the TimeBase of the embedded movie should be slaved to the TimeBase of the parent movie. If the TimeBase is slaved, the embedded movie’s zero time will correspond to the start time of its movie media sample. Further, the playback rate of the embedded movie will always be the same as the parent movie’s. If the TimeBase is not slaved, the embedded movie will default to a rate of zero, and a default time of whatever default time value it instantiated with (which may not be zero). If the TimeBase is not slaved, the embedded movie can be played by either including an AutoPlay atom in the movie media sample or by using a Wired Action. If this atom is not present, the embedded movie defaults to not slaved. kMovieMediaSlaveAudio This atom contains a Boolean that indicates whether or not the audio properties of the embedded movie should be slaved to those of the parent movie. When audio is slaved, all audio properties of the containing track are duplicated in the embedded movie. These properties include sound volume, balance, bass and treble, and level metering. If this atom is not present, the embedded movie defaults to not slaved audio. kMovieMediaSlaveGraphicsMode This atom contains a Boolean that indicates how the graphics mode of the containing track is applied to the embedded movie. If the graphics mode is not slaved, then the entire embedded movie is imaged using its own graphics modes. Then the result of the drawing of the embedded movie is composited onto the containing movie using the graphics mode of the containing track. If the graphics mode is slaved, then the graphics mode of each track in the embedded movie is ignored and instead the graphics mode of the containing track is used. In this case, the tracks of the embedded movie composite their drawing directly into the parent movie’s contents. If this atom is not present, the graphics mode defaults to not slaved. Graphics mode slaving is useful for compositing semi-transparent media –– for example a PNG with an alpha channel –– on top of other media. kMovieMediaSlaveTrackDuration
Movie Media Handler 23 RELEASE 1.0
What’s New in QuickTime 4.1
This atom contains a Boolean that indicates how the Movie Media Handler should react when the duration of the embedded movie is different than the duration of the movie media sample that it is contained by. When the movie media sample is created, the duration of the embedded movie may not yet be known. Therefore, the duration of the media sample may not be correct. In this case, the Movie Media Handler can do one of two things. If this atom is not present or it contains a value of false, the Movie Media Handler will respect the duration of media sample that contains the embedded movie. If the embedded movie has a longer duration than the movie media sample, the embedded movie will be truncated to the duration of the containing movie media sample. If the embedded movie is shorter, there will be a gap after it is finished playing. If this atom contains a value of true, the duration of the movie media sample will be adjusted to match the actual duration of the embedded movie. Because it is not possible to change an existing media sample, this will cause a new media sample to be added to the movie and the track’s edit list to be updated to reference the new sample instead of the original sample.
Note When the duration of the embedded movie’s sample is adjusted, by default no other tracks are adjusted. This can cause the overall temporal composition to change in unintended ways. To maintain the complete temporal composition, a higher level data structure which describes the temporal relationships between the various tracks must also be included with the movie. kMovieMediaAutoPlay This atom contains a Boolean that indicates whether or not the embedded movie should start playing immediately after being instantiated. This atom is only used if the TimeBase of the embedded movie is not slaved to the parent movie (see the kMovieMediaSlaveTime atom for more information). If auto play is requested, the movie will be played at its preferred rate after being instantiated. If this atom is not present, the embedded movie will not automatically play. kMovieMediaLoop
24 Apple Movie Media Handler RELEASE 1.0
What’s New in QuickTime 4.1
This atom contains a UInt8 that indicates how the embedded movie should loop. This atom is only used if the TimeBase of the embedded movie is not slaved to the parent movie (see the kMovieMediaSlaveTime atom for more information). If this atom contains a zero, or if this atom is not present, the embedded movie will not loop. If this atom contains a value of 1, the embedded movie will loop normally –– that is, when it reaches the end it will loop back to the beginning. If this atom contains a value of 2, the embedded movie will use palindrome looping. All other values are reserved. kMovieMediaUseMIMEType This atom contains text (not a C string or a pascal string) that indicates the MIME type of the movie import component that should be used to instantiate this media. This is useful in cases where the data reference may not contain MIME type information. If this atom is not present, the MIME type of the data reference as determined at instantiation time will be used. This atom is intended to allow content creators a method for working around MIME type binding problems. It should not typically be required, and should not be included in movie media samples by default. kMovieMediaTitle Currently unused. Would contain text indicating the name of the embedded movie. kMovieMediaAltText This atom contains text (not a C string or a pascal string) that is displayed to the user when the embedded movie is being instantiated or if the embedded movie cannot be instantiated. If this atom is not present, the name of the data reference (typically the file name) will be used. kMovieMediaClipBegin
This atom contains a MovieMediaTimeRecord which indicates the time of the embedded movie that should be used. The clip begin atom provides a way to specify that a portion of the beginning of the embedded movie should not be used. If this atom is not present, the beginning of the embedded movie will not be changed. Note that this atom does not change the time at which the embedded movie begins playing in the parent movie’s time
Movie Media Handler 25 RELEASE 1.0
What’s New in QuickTime 4.1
line. If the time specified in the clip begin atom is greater than the duration of the embedded movie, then the embedded movie will not play at all.
struct MovieMediaTimeRecord { wide time; TimeScale scale; };
kMovieMediaClipDuration This atom contains a MovieMediaTimeRecord which indicates the duration of the embedded movie that should be used. The clip duration atom is applied by removing media from end of the embedded movie. If the clip duration atom is not present, then no media is removed from the end of the embedded movie. In situations where the sample contains both a clip duration and a clip begin atom, the clip begin is applied first. If the clip duration specifies a value that is larger than the duration of the embedded movie, no change is made to the embedded movie. kMovieMediaEnableFrameStepping This atom contains a Boolean which indicates whether or not the embedded movie should be considered when performing step operations, specifically using the interesting time calls with the nextTimeStep flag. If this atom is not present or is set to false, the embedded movie is not included in step calculations. If the atom is set to true, it is included in step calculations. kMovieMediaBackgroundColor
This atom contains an RGBColor which is used for filling the background when the movie is being instantiated or when it fails to instantiate. kMovieMediaRegionAtom This atom contains a number of child atoms, shown below, which describe how the Movie Media Handler should resize the embedded movie. If this atom is not present, the Movie Media Handler will resize the child movie to completely fill the containing track’s box. kMovieMediaSpatialAdjustment
26 Apple Movie Media Handler RELEASE 1.0
What’s New in QuickTime 4.1
This atom contains an OSType which indicates how the embedded movie should be scaled to fit the track box. If this atom is not present, the default value is kMovieMediaFitFill. These modes are all based on SMIL layout options. KMovieMediaFitClipIfNecessary If the media is larger than the track box, it will be clipped; if it is smaller, any additional area will be transparent.
kMovieMediaFitFill The media will be scaled to completely fill the track box.
kMovieMediaFitMeet The media will be proportionally scaled so that it is entirely visible in the track box and fills the largest area possible without changing the aspect ratio.
kMovieMediaFitSlice The media will be scaled proportionally so that the smaller dimension is completely visible.
kMovieMediaFitScroll Not currently implemented. It currently has the same behavior as kMovieMediaFitClipIfNecessary. When implemented, it will have the behavior described in the SMIL specification for a scrolling layout element. kMovieMediaRectangleAtom This atom contains four child atoms that define a rectangle. Not all child atoms must be present: top and left must both appear together, width and height must both appear together. The dimensions contained in this rectangle are used in place of the track box when applying the contents of the spatial adjustment atom. If the top and left are not specified, the top and left of the
Movie Media Handler 27 RELEASE 1.0
What’s New in QuickTime 4.1
containing track’s box are used. If the width and height are not specified, the width and height of the containing track’s box are used. Each child atom contains a UInt32.
kMovieMediaTop kMovieMediaLeft kMovieMediaWidth kMovieMediaHeight
New Movie Media Handler APIs 1
This section discusses the new Movie Media Handler APIs available in QuickTime 4.1.
MovieMediaGetCurrentMovieProperty 1
pascal ComponentResult MovieMediaGetCurrentMovieProperty( MediaHandler mh, OSType whichProperty, void *value )
This function allows an application to find out certain information about the currently instantiated embedded movie. The property for which information is desired is passed in the whichProperty parameter. The result is returned in the value parameter. The type of value parameter depends on the value of the whichProperty parameter. kMoviePropertyDuration
This parameter has a type of TimeValue and returns the result of calling GetMovieDuration on the embedded movie. kMoviePropertyTimeScale This parameter has a type of TimeScale and returns the result of calling GetMovieTimeScale on the embedded movie.
kMoviePropertyTime
This parameter has a type of TimeRecord and returns the result of calling GetMovieTime on the embedded movie.
28 Apple New Movie Media Handler APIs RELEASE 1.0
What’s New in QuickTime 4.1
kMoviePropertyNaturalBounds
This parameter has a type of Rect and returns the result of calling GetMovieNaturalBoundsRect on the embedded movie. KMoviePropertyMatrix
This parameter has a type of MatrixRecord and returns the result of calling GetMovieMatrix on the embedded movie. kMoviePropertyTrackList This parameter has a type of long **. It returns an array of UInt32 values, where each value is the ID of one of tracks in the embedded movie. These track ID’s can be passed to MovieMediaGetCurrentTrackProperty to find out information about the tracks of an embedded movie.
MovieMediaGetCurrentTrackProperty 1
pascal ComponentResult MovieMediaGetCurrentTrackProperty ( MediaHandler mh, long trackID, OSType whichProperty, void *value )
This function allows an application to find out certain information about the tracks of the currently instantiated embedded movie. The track to retrieve information about is specified by passing the id of the track in the trackID parameter. The ID’s of all the tracks in the movie can be obtained by calling MovieMediaGetCurrentMovieProperty. The property for which information is desired is passed in the whichProperty parameter. The result is returned in the value parameter. The type of value parameter depends on the value of the whichProperty parameter. kTrackPropertyMediaType This parameter has a type of OSType and returns the result of calling GetMediaHandlerDescription on the Media of the requested track.
New Movie Media Handler APIs 29 RELEASE 1.0
What’s New in QuickTime 4.1
New Movie Media Handler APIs to Handle Data References 1 The Movie Media Handler maintains a dynamic list of data references to movies that may be loaded. Each data reference is accessed by ID; IDs should be unique positive integers. When a new sample is loaded, the list is cleared and data references from the new sample are loaded into this list. Three new API routines, discussed as follows, let you add new data references, look up existing data references, and a load a movie from a data reference referred to by its ID.
Note These data references are not written to disk; they are temporary for this instantiation of the Movie Media Handler. Note that you are not changing the movie, just the changing the runtime property of it.
MovieMediaSetChildMovieDataReference 1
pascal ComponentResult MovieMediaSetChildMovieDataReference ( MediaHandler mh, QTAtomID dataRefID, OSType dataRefType, Handle dataRef )
Adds a data reference specified by dataRefType and dataRef with ID of dataRefID to the Movie Media Handler’s dynamic list.
MovieMediaGetChildMovieDataReference 1
pascal ComponentResult MovieMediaGetChildMovieDataReference ( MediaHandler mh, QTAtomID dataRefID, OSType* dataRefType, Handle* dataRef )
Returns a data reference in dataRefType and dataRef with ID from dataRefID to the Movie Media Handler’s dynamic list.
30 Apple New Movie Media Handler APIs RELEASE 1.0
What’s New in QuickTime 4.1
MovieMediaLoadChildMovieFromDataReference 1
pascal ComponentResult MovieMediaLoadChildMovieFromDataReference( MediaHandler mh, QTAtomID dataRefID )
Replaces the current movie displayed by the Movie Media Handler with the one specified by dataRefID. The new movie inherits the settings, such as audio and spatial slaving.
Movie Media Handler Tasks 1 The Movie Media Handler's primary task is to make each embedded movie appear like a single, integrated element within its containing movie. This means that it must mediate between the requests made by its containing movie and the capabilities of the embedded movie. These requests are typically made in the form of some kind of “set property” call to the Movie Media Handler. The properties themselves can be divided into a few groups: spatial, audio, and temporal with a few miscellaneous additions. Because the “right” behavior varies from case to case, the Movie Media Handler allows the exact behavior to be specified within each movie media sample. To allow for composition to occur within the embedded movie as intended, in this case, the embedded movie’s tracks are composed together independently of the containing movie, and then the transfer mode of the containing track is used to compose the result into the final containing movie’s composition. If the transfer mode is attached, the behavior is quite different. The transfer mode of the containing track is applied to each track within the embedded movie. The tracks are drawn directly into the containing movie’s composition buffer, allowing their transfer modes to interact with any background provided by the embedded movie. This effectively destroys the original transfer mode information, and so this mode is generally useful for embedded media streams that only contain a single visual track, such as still images. The SMIL importer only slaves transfer modes when a particular transfer mode is requested in the SMIL composition. Support for transfer modes is a QuickTime-specific extension to SMIL to allow for the application of the transparency information stored in GIF and PNG images.
New Movie Media Handler APIs 31 RELEASE 1.0
What’s New in QuickTime 4.1
Using the Streaming Media Handler 1 When a movie is playing, the Movie Media Handler tries to instantiate each media element at least 15 seconds before it is actually needed. This is done to allow for any prebuffering that might need to occur to be done by the time the media element is scheduled to play. In the case of a streaming movie, this allows the streaming media handler to connect to the server and begin buffering media data. In the case of local content, this ensures that the media is available to begin playing immediately instead of after an initial pause. In the case of HTTP/ftp content, this allows prefetch to occur (as with streaming, subject to any bandwidth management constraints). The QuickTime 4.1 implementation forwards status messages when the movie is stopped, but not when it is playing.
A Note to Authors of Media Handlers 1 QuickTime developers who may author media handlers should take note of the following: Specifically, consider a containing movie of duration 10 with a movie media track that contains a media element, which is active from time 4 to 6. At time 4, the embedded movie is at its time zero. But because the embedded movie is actually instantiated in advance of its play time (up to fifteen seconds) it will be active at times when its time is actually negative. (For more information on embedded movies, see the section “Introducing Embedded Movies” beginning on page 44.) Because the embedded movie’s time base has its start time set to zero, however, those negative times are pinned to zero. However, the rate is non-zero. So there is a strange situation where time is stopped at zero and the rate is moving. Some media handlers can misinterpret this situation and start playing before their actual start time. Media handlers can detect this situation by calling GetTimeBaseStatus instead of GetTimeBaseTime.
32 Apple New Movie Media Handler APIs RELEASE 1.0
What’s New in QuickTime 4.1
Support for Data URLs 1
QuickTime 4.1 now provides support for the "data:" URL scheme. You can avoid the overhead of a separate HTTP transaction for small files by embedding the data directly into the SMIL file using a data URL instead. The specification for this scheme is available at:
data:[
A number of applications can Base64 encode files; a useful one is MPack, which is available free at:
Listing 3 Usage of the “data:” scheme, producing a GIF image
The SMIL document shown in Listing 4 lets you create a simple text display, using text descriptors, as described at
Listing 4 A simple text display using text descriptors
34 Apple Support for Data URLs RELEASE 1.0
What’s New in QuickTime 4.1
URLs in Text Tracks 1
In QuickTime 4.1, you can have URL links in text tracks, as shown in the example in Listing 5. This example contains a number of links which, once saved as a text file, can be imported into QuickTime Player. Note that these URLs in text tracks cannot have line breaks in them, though they are printed that way to fit on a page here.
Listing 5 Usage of URLs in text tracks
{QTtext}{font:Times}{plain}{size:12}{textColor: 65535, 65535,65535}{backColor: 0, 0, 0}{justify:center}{timeScale:10}{width:160}{height:64}{timeStamps:abso lute}{language:0}{textEncoding:0}[00:00:00.0] {HREF:"http://www.apple.com/ "}Apple{endHREF}, the power to crush the other kid. [00:00:01.7]Get the latest copy of {HREF:"http://emulation.net/mame"}MacMame{endHREF}from {HREF:"http://www.emulation.net/ "}Emulation.net{endHREF}. You will love the old arcade games.[00:00:03.4]{HREF:"http:// www.apple.com/"}Apple{endHREF}, the power to crush the otherkid.[00:00:04.4]Without Quotes. Get the latest copy of {HREF:http://emulation.net/mame/}MacMame{endHREF} from {HREF:http://www.emulation.net}Emulation.net{endHREF}. You will love the old arcade games. [00:00:06.8]
New Embed Tags 1
QuickTime 4.1 provides support for a set of new embed tags. These are
URLSUBSTITUTE
AUTOREF
QTSRCDONTUSEBROWSER
URLs in Text Tracks 35 RELEASE 1.0
What’s New in QuickTime 4.1
URLSUBSTITUTE Embed Tag 1
The URLSUBSTITUTE tag can be used to override URLs in a QuickTime movie. The syntax for this new embed tag is:
URLSUBSTITUTE="
Note that angle brackets <> are required. If you need more than one URLSUBSTITUTE tag, you need to number them. Note that the QuickTime Plug-in treats any tag that begins with URLSUBSTITUTE the same. Thus, URLSUBSTITUTE1, URLSUBSTITUTE2, and URLSUBSTITUTE99 are all equivalent. This mechanism allows the same movie assets to be deployed multiple times, for example, on different servers, with different hyperlinks.
How It Works 1 When the QuickTime Plug-in encounters a URL, it compares the URL in an unpredictable order with the list of substitutes. Note that these comparisons are case sensitive. If the start of the supplied URL matches exactly one of the “oldprefixs”, oldprefix is removed and newprefix is inserted in its place and the search for substitution stops. The resulting URL is passed along to QuickTime or the browser as normal. This only affects URLs in HREF tracks, sprite action URLs, and hotspot URLs. (Note that QuickTime has been able to do this with VR hotspot URLs, using the HOTSPOT tag). Data reference URLs are not substituted. In general, URLs can be re-targeted when the same piece of content needs to be served for a variety of purposes. For example, in an HREF track and sprite actions one might have the following URLs:
=content=frontview.mov =content=backview.mov =action=buyit.cgi?item=hotplate
and an embed line with
URLSUBSTITUTE="<=content=>:
36 Apple New Embed Tags RELEASE 1.0
What’s New in QuickTime 4.1
Note This above example won’t work in the Internet Explorer browser, so we use URLSUBSTITUTE1 and URLSUBSTITUTE2, as shown below. and an embed line with
URLSUBSTITUTE1="<=content=>:http://contentserver.com/views/>" URLSUBSTITUTE2="<=action=>:http://ecommerce.com/actions/>"
which will result in the following URLs being used after substitution:
http://contentserver.com/views/frontview.mov http://contentserver.com/views/backview.mov http://ecommerce.com/actions/buyit.cgi?item=hotplate
This also helps in the situation where a URL has changed from the time that a movie was created. For example, a movie authored with the kActionGoToURL sprite action to the author’s home page could be quickly changed to point to a new home page by adding a URLSUBSTITUTE tag to the movie’s user data with the Plug-in Helper.
AUTOHREF Embed Tag 1 The AUTOHREF tag causes the QuickTime Plug-in to load the URL specified in the HREF tag immediately instead of waiting for the user to click on the movie. Note that this tag modifies the HREF tag and so has no effect unless there is also an HREF tag.
QTSRCDONTUSEBROWSER Embed Tag 1 The QTSRCDONTUSEBROWSER tag allows the QuickTime Plug-in to always use QuickTime instead of the browser to download a QTSRC file.
Support for an HTML Importer 1
Because most ad servers specify images and hyperlinks in HTML format and because many ad servers are geared specifically for HTML documents,
Support for an HTML Importer 37 RELEASE 1.0
What’s New in QuickTime 4.1
QuickTime 4.1 includes support for a limited HTML importer. This importer will scan an HTML document for its first anchored image with a hyperlink and import this image with its hyperlink into a QuickTime movie. All other tags will be ignored.
How It Works 1 When QuickTime’s HTML importer is invoked, it scans an HTML document in search of media that QuickTime can play. It does this by looking for specific HTML elements, namely ,
When QuickTime imports this document, it creates a movie that plays the animated GIF "winkinnblinkin.gif" and which, when clicked, will cause the preferred browser to display the linked HTML document, “http:// somewhere.net/main.html”. QuickTime supports the following attributes of the element: "href" and "target". It supports the following attributes of the element: "src", "width", "height", and "ismap". The QuickTime HTML importer also works with media described within the
When QuickTime imports this document, it creates a movie that plays the RTSP stream "mymovie.mov" and which, when clicked, will cause the preferred browser to display the linked HTML document, “http://somewhere.net/ main.html”.
38 Apple Support for an HTML Importer RELEASE 1.0
What’s New in QuickTime 4.1
QuickTime supports the following attributes of the
Additional Notes 1 The following are additional notes on the handling of HTML source: If QuickTime’s HTML importer fails to find playable media within an element or an
Support for an HTML Importer 39 RELEASE 1.0
What’s New in QuickTime 4.1
In the SMIL example above, the HTML document “insertion.html” is explicitly given the MIME type “text/x-html-insertion”. This signals QuickTime to use its HTML importer to scan the html source for a playable media element. If one is found, QuickTime will play it and then play “maincontent.mov”.
Support for HTTP Streaming 1
Streaming relies on the successful transmission of TCP and UDP packets to and from the user. Many firewalls, however, block either UDP, or both UDP and TCP packets transmitted over a protocol or port which they don’t recognize. Since QuickTime uses RTP and RTSP –– which are relatively new –– many firewalls do not yet recognize them. Because HTTP is so common, every firewall allows it through. QuickTime 4.1 now has the ability to transport streaming packets over HTTP. However, HTTP is not the preferred choice because it was not designed for real-time delivery.
New HTTP Streaming Functionality 1 Users may either click the Auto Configure button in the Streaming Transport control panel or select between UDP or HTTP.
40 Apple Support for HTTP Streaming RELEASE 1.0
What’s New in QuickTime 4.1
Figure 1 The new Streaming Transport control panel with various user options
The Streaming Proxy control panel, shown in Figure 2, allows the user to specify the proxy to be used. Using the HTTP setting in the Control Panel shown in Figure 2, streaming movies work using HTTP as a transport without requiring any further changes from the user. If the user clicks the Auto Configure button, shown in Figure 1, and is unable to make a successful test connection over UDP, QuickTime reverts to trying to make a connection via HTTP. As with RTSP proxies, if an HTTP proxy is required, the user will have to enter that information by hand.
Support for HTTP Streaming 41 RELEASE 1.0
What’s New in QuickTime 4.1
Figure 2 The new Streaming Proxy control panel
Additional Cookie Support 1
In QuickTime 4.1, servers can set and access cookies via the HTTP data handler. The HTTP data handler uses the cookie component to store and retrieve cookies, formatted according to the Netscape cookie specification, which is available at
42 Apple Additional Cookie Support RELEASE 1.0
What’s New in QuickTime 4.1
The way cookies are handled is affected by the following: the choice of what HTTP code is used the operating system the browser There may be multiple cookie databases on an end user’s system, and so a system using cookies may set a cookie into one database, which is then not returned when another database is referenced by a different HTTP handler. It may be necessary to perform some kind of cookie-synchronization to mitigate this effect. The HTTP data handler is used by QuickTime for all HTTP accesses which occur outside the QuickTime Plug-in, and for some of the accesses performed by the QuickTime Plug-in as well. In general, the Plug-in uses the browser’s built-in HTTP mechanism unless it is unsuitable, i.e., a scheme the browser can’t handle, such as RTSP. Note that there are parameters to the EMBED tag which can force the use of the QuickTime data handler. On the Mac OS the cookie component stores the cookies in the QuickTime Preferences file. This cookie database is distinct from that used by browsers. On Windows the cookie component stores cookies using Win32 Internet functions in the same database used by Internet Explorer (but not Netscape Navigator). On Windows, the user can control cookie hamdling using the Internet control panel, since the system’s cookie database is used. On Mac OS, there is no user control of the QuickTime cookie database.
64-bit File Offset Support for Mac OS 9 1
QuickTime 4.1 now includes support for 64-bit file offsets in Mac OS 9, which allow the use of files greater than 2 gigabytes (2G). QuickTime 4 had already been enhanced to include comprehensive support for 64-bit file offsets on Windows. For more information, refer to Letters from the Ice Floe, Dispatch 22 at
64-bit File Offset Support for Mac OS 9 43 RELEASE 1.0
What’s New in QuickTime 4.1
New Features For Creating More Interactive Movies 1
QuickTime 4.1 introduces a set of new features that allow for the creation of more advanced, interactive movies. These features include the introduction of embedded movies addition of new wired actions and events addition of new ways to communicate between a wired movie and JavaScript in a Web browser For more information about wired movies in QuickTime 4, refer to QuickTime Wired Movies And Sprite Animation, which describes and documents the API for creating interactive movies and sprites, including HREF Tracks and wired sprites. This is available for download as a PDF at
Introducing Embedded Movies 1 QuickTime 4.1 introduces a new embedded movie feature. This feature provides QuickTime content authors and developers with a set of new capabilities for the creation of more powerful, interactive wired movies. Some of these new features and their possible uses are outlined in this section. Embedded movies are implemented through the new track type –– the movie track, which is discussed in the section “A New Movie Media Track” beginning on page 21.
Creating New Types of QuickTime Movies 1 Because embedded movies can have independent clocks, new types of movies can now be created. For example, you can create a movie containing animated characters that are watching a video. This movie could contain an animation track, perhaps a sprite or Flash track, and an embedded movie track for the video content. In
44 Apple New Features For Creating More Interactive Movies RELEASE 1.0
What’s New in QuickTime 4.1 this example, the root movie’s time base would control the animation, but the video’s rate could be controlled independently from the animations’ rate. Wired actions could be sent to the embedded movie when a user clicks on buttons in the animation track. The wired actions could play, pause, and fast forward the video, or switch to a new one. Another way you can take advantage of independent time bases is to allow long audio tracks to be triggered interactively. For example, if you create a game with sound effects and background music that need to be played back at times defined by events that occur in the game, you can use an embedded movie for each audio track. The advantage of using an embedded movie instead of a music track with a custom sound is that the entire sound does not need to be loaded into memory, so it is appropriate for longer sounds. The disadvantage is that you may not control it similar to a MIDI instrument.
Using Embedded Movies 1 One way to use embedded movies is to break projects into components, allowing portions to be reused in other projects, and simplifying the authoring process. In QuickTime 4, this technique could be used in a Web browser using external movie-to-movie communication. Now in QuickTime 4.1 a single movie can be created that is playable in the QuickTime Player or any application that plays QuickTime movies. For example, an interactive movie could contain three elements, as illustrated in Figure 3: A control strip with custom controls for audio and scene navigation An area used to display text An area used for interactive animation
New Features For Creating More Interactive Movies 45 RELEASE 1.0
What’s New in QuickTime 4.1
Figure 3 An interactive movie example with three elements
Find the starfish and An area used to display text place it in the ship!
An area used for interactive animation
A control strip with custom controls Help Back to Top Score 23Time :15 Level 2
By encapsulating these three elements each in a separate movie, you can reload only portions that are necessary to reload. For example, the control strip may persist throughout the entire experience, while the animation area may be replaced once per scene and the displayed text changed several times per scene. By implementing each element as a movie and composing them together using movie tracks in a container movie, you can minimize reload time and memory usage, and even update the source movies on your Web server as you improve or change them.
Dynamically Loading New Embedded Movies from URLs 1 A movie track maintains a list of movies which may be loaded and played within the track. The movie track only plays one movie from the list at a given time. This list is initialized from data in a movie track sample, but the list may be augmented at runtime. Each entry in the list is identified by a unique ID, and contains a data reference to a movie. There are two new wired actions, which allow you to add a new URL data reference to this list, and to load and play a movie from this list.
46 Apple New Features For Creating More Interactive Movies RELEASE 1.0
What’s New in QuickTime 4.1
Dynamically loading a movie into a movie track is similar to loading a URL into a frame of a Web page. This dynamic loading allows for movies to manage memory efficiently by loading QuickTime playable content as it is needed. In addition, it allows for content which is generated on a Web server to be loaded into a movie; this content could even be created based upon information that a wired movie sends to the server using the GotoURL wired action.
Triggering Wired Actions When an Embedded Movie is Loaded 1
A new MovieLoaded QuickTime event has been added that allows wired actions to be executed when an embedded movie is loaded. There are two places to store these actions. The movie that is being loaded may store actions in its movie properties atom container, and the movie track may store these actions in its samples. These wired actions can be used to examine the current state of the parent movie, and to make changes both to the movie being loaded and to elements of the parent movie.
Targeting Elements of Embedded Movies with All Existing Wired Actions 1 All existing wired actions may now be performed on elements of embedded movies, and wired action handlers inside of embedded movies may perform actions on elements of their parent movie. To understand this new targeting hierarchy, we can look at the current runtime state of a movie as a tree, as shown in the example in Figure 4. The root of this tree is the root movie itself. The children of the root movie node are tracks. Some types of tracks, such as the sprite track, can contain child nodes that are sprites. In QuickTime 4 and earlier, this was as deep as the tree ever got, but now with the introduction of the movie track, the tree can be indefinitely deep. The movie track node has child track nodes based on its currently loaded movie; one or more of these tracks may be yet another movie track. Take, for example, a movie containing a Flash track and a movie track. The movie track’s currently loaded movie contains a video track, an audio track, and a sprite track with two sprites. This comprises the target hierarchy tree shown in Figure 4.
New Features For Creating More Interactive Movies 47 RELEASE 1.0
What’s New in QuickTime 4.1
Figure 4 An example of the new targeting hierarchy tree
Root Movie
Flash Child Track Movie
Video Audio Sprite Track Track Track
Sprite 1 Sprite 2
Conceptually, you may think of the movie track and its currently loaded movie as a single entity –– i.e., a movie track. A movie track such as Child Movie in this example may be the target of both track and movie actions. When specifying a target for an action, we first specify the movie (or movie track) that is the target or that contains the target. Then, we can further specify a track and track object if needed. Before QuickTime 4.1, you could specify external movies by name or ID. New procedures for specifying a movie within a hierarchical movie have been added, including: Child MovieTrack by Movie ID, Movie Name, Track ID, Track Index, or Track Name Parent Movie Root Movie These targets are relative to the current movie that contains the action handler. A few examples may help clarify how to target various elements. Example 1: Sprite 1 has an action handler on a mouse click that tells Root Movie to play.
48 Apple New Features For Creating More Interactive Movies RELEASE 1.0
What’s New in QuickTime 4.1
Since Sprite 1 is contained in Child Movie, the movie target is specified relative to Child Movie. This may be accomplished using Parent Movie or Root Movie. Example 2: Sprite 2 has an action handler that tells the Flash Track to pan left. Again, the target is relative to Child Movie, so you can use either Parent Movie or Root Movie to specify the root movie. Additionally, you specify the Flash track. Example 3: A button in Flash Track contains a mouse click handler that sets the volume of the audio track in Child Movie. In this example, Flash Track is contained in Root Movie, so the movie target is specified relative to Root Movie. You can use any of the Child Movie target types to specify Child Movie. You can specify that the target is the audio track.
New Movie Track and Movie Wired Actions 1 Two new actions operate on a movie track target: kActionMovieTrackAddChildMovie (QTAtomID childMovieID, CStr childMovieURL) This action adds a new movie URL data reference to the targeted movie track’s array of movie data references. The URL data reference is added with the specified ID. If a data reference with the same ID already exists, it is replaced. It is generally a good idea to use an ID that is not contained in the movie track's sample, since this may be reloaded under some conditions. kActionMovieTrackLoadChildMovie (QTAtomID childMovieID) This action loads a movie specified by childMovieID as the current movie being played by the movie track. The movie replaces the current movie. Another new action operates on a root movie or a movie track target:
kActionMovieRestartAtTime (TimeValue startTime, Fixed rate)
This action restarts the targeted movie at the specified movie time, restarting it at the specified rate. If rate is set to zero, then the current movie rate is used. More specifically, this action stops the current movie, changes the movie’s time to the specified time, and then prerolls the movie from that time at the specified rate. Note that the wired actions DoScript, GotoURL, DebugString, and StatusString are sent through the root movie’s MCDoActionProc when executed from a child
New Features For Creating More Interactive Movies 49 RELEASE 1.0
What’s New in QuickTime 4.1
movie, allowing them to work with existing applications that trap for these actions.
New Wired QT Event 1
kQTEventMovieLoaded event has been added to QuickTime 4.1. This event is sent when an embedded movie is loaded. Embedded movies may be loaded when a movie containing an embedded movie is first opened, when an embedded movie loads a new sample due to the movie’s time changing, or when an embedded movie is sent a kActionMovieTrackLoadChildMovie action. Action handlers for the kQTEventMovieLoaded event may reside in two places. They may be placed in a sample of a movie track’s media or placed in the movie property atom of a movie that is loaded into a movie track. If handlers exist in both places, the action list from the sample is appended to the one from the movie property atom. This means that the actions from the sample will be executed second, and if the same action resides in both places for the same target, the effect of the action from the sample will persist. To add an event handler to a movie media sample, you add an atom of type kQTEventMovieLoaded to the sample, with child atoms defining the actions. To add an event handler to a child movie that is to be loaded, you add an atom of type kQTEventMovieLoaded to the child movie’s movie property atom using the new QuickTime Movie Toolbox routine SetMoviePropertyAtom. You may use the GetMoviePropertyAtom function to first retrieve the existing movie properties container, add or modify the kQTEventMovieLoaded atom, and then write it back using the SetMoviePropertyAtom function.
Extended Wired Operand Functionality 1
A special case was added to the wired operand kOperandComponentVersion. By using the arguments kOperandComponentVersion("mac ", "os ", "vers" ) the version of Mac OS is returned. Zero is returned on Windows.
Wired Actions and JavaScript 1
kActionDoScript (long flags, CStr commands, CStr arguments)
50 Apple New Features For Creating More Interactive Movies RELEASE 1.0
What’s New in QuickTime 4.1
This new wired action has no target (system target). The action calls the root movie controller’s mcActionDoScript, so that scripts can be invoked by a host application. For example, the QuickTime Plug-in in a browser can invoke JavaScripts. If the script flags are set to kScriptIsUnknownType or kScriptIsJavaScript, the QuickTime Plug-in invokes a JavaScript routine in the HTML file that has embedded the QuickTime movie, with the following prototype:
function DoFSCommand(command, arguments) { }
If the movie is embedded with a NAME tag, a movieName tag, or is named by user data, then this prototype is used instead:
function movieName_DoFSCommand(command, arguments) { }
This allows for wired movies to invoke a JavaScript. The QuickTime Plug-in now also supports many movie-related JavaScript routines, so it is possible to set sprite track variables and post custom wired events to a wired movie from JavaScript as well. It is important to note that this functionality works only with the QuickTime Plug-in and that some versions of some browsers do not support the necessary interfaces to allow for these things to work. See the section “JavaScript Support” beginning on page 64 in this document for more details.
Added Flash Support 1
QuickTime Flash 3 support now includes the DoFSCommand mechanism. This allows JavaScript routines with a specific function prototype to be invoked with parameters passed from the Flash track. The JavaScript routine’s prototype is discussed above in the kActionDoScript wired action. You may refer to Macromedia’s Flash 3 documentation for more details on how to author a .swf 3 file with a Flash FSCommand.
New Target Type Atoms for Hierarchical Movies 1 There are new target atoms added to accommodate the addition of embedded movies in QuickTime 4.1. They allow for paths to be specified in a hierarchical movie tree. Target movies may be an external movie, the default movie, or any movie embedded within another movie. Targets are specified using a movie path that
New Features For Creating More Interactive Movies 51 RELEASE 1.0
What’s New in QuickTime 4.1
may include parent and child movie relationships, and may additionally include track and track object target atoms as needed. By using embedded kActionTarget atoms along with new parent and child movie target atoms, you can build up paths for movie targets. Note that we only look for these embedded kActionTargetAtoms when evaluating a movie target, and any movie target type may contain a sibling kActionTargetAtom. Paths start from the current movie, which is the movie containing the object that is handling an event. You may go up the tree using a new kTargetParentMovie atom or down the tree using one of five new child movie atoms. You may use a new kTargetRootMovie atom as a shortcut to get to the top of the tree containing an embedded movie and may use the existing movieByName and movieByID atoms to specify a root external movie. The new target atoms are described below. Note that there are five ways to specify an embedded child movie. Three of them specify MovieTrack properties. Two specify properties of the currently loaded movie in a movie track. kTargetRootMovie (leaf atom –– no data) The root movie containing the action handler. kTargetParentMovie (leaf atom –– no data) The parent movie.
kTargetChildMovieTrackName [Pstring movieTrackName]
A child movie track specified by track name.
kTargetChildMovieTrackID [QTAtomID movieTrackID]
A child movie track specified by track ID.
kTargetChildMovieTrackIndex [long movieTrackIndex]
A child movie track specified by track index.
kTargetChildMovieMovieName [Pstring movieName]
52 Apple New Features For Creating More Interactive Movies RELEASE 1.0
What’s New in QuickTime 4.1
A child movie specified by the currently loaded movie's movie name. The child movie must contain movieName user data with the specified name.
kTargetChildMovieMovieID [QTAtomID movieID]
A child movie specified by the currently loaded movie’s movie ID. The child movie must contain movieID user data with the specified ID.
Example #1 1 Movie "Root" contains two embedded movies. "Controller" is an embedded movie controller movie. "ControlMe" is an embedded audio/video movie to be controlled. "Controller" and "ControlMe" are both child movies of the Root Movie. To control the rate of the movie’s audio/video, a sprite in the “Controller” movie uses the following target:
kActionTarget kTargetParentMovie kActionTarget kTargetChildMovieMovieName [movieName = "ControlMe"]
Example #2 1 A sprite in one movie targets a sprite which is embedded in a movie which is again embedded in another movie. You target a sprite named "Dude" in a Track of index one in a movie of ID 2 which is nested in a movie whose track name is "Rad" which is nested in a movie whose user data name is OuterExternalMovie. The OuterExternalMovie is an external movie to the one that is executing an action handler.
kActionTarget kTargetMovieName [name = "OuterExternalMovie"] kActionTarget kTargetChildMovieTrackName
New Features For Creating More Interactive Movies 53 RELEASE 1.0
What’s New in QuickTime 4.1
[name = "Rad"] kActionTarget kTargetChildMovieMovieID [ID = 2] kTargetTrackIndex [Index = 1] kTargetSpriteName [spriteName = "Dude"]
New Movie Property Atom Toolbox Routines 1
Similar to the GetMediaPropertyAtom and SetMediaPropertyAtom routines, QuickTime 4.1 introduces GetMoviePropertyAtom and SetMoviePropertyAtom routines. These routines allow an atom container of structured data to be associated with a movie. This information is saved in a movie resource. The kQTEventMovieLoaded looks for an atom of type kQTEventMovieLoaded in a movie's property atom container when a MovieTrack loads a new movie.
GetMoviePropertyAtom (Movie theMovie, QTAtomContainer * propertyAtom)
This routine allocates and returns in propertyAtom an atom container containing a copy of theMovie’s properties’ atom container.
SetMoviePropertyAtom (Movie theMovie, QTAtomContainer propertyAtom)
This routine sets the contents of theMovie’s property atom container to the contents of the propertyAtom atom container.
New Movie Controller Actions 1
mcActionDoScript allows a movie to send requests to execute scripts of various sorts to a host application. The parameter is a QTDoScriptPtr.
struct QTDoScriptRecord { long scriptTypeFlags; char *command; char *arguments; };
typedef QTDoScriptRecord *QTDoScriptPtr;
54 Apple New Features For Creating More Interactive Movies RELEASE 1.0
What’s New in QuickTime 4.1
The scriptTypeFlags currently defined are:
enum { kScriptIsUnknownType = 1L << 0 kScriptIsJavaScript = 1L << 1, kScriptIsLingoEvent = 1L << 2, kScriptIsVBEvent = 1L << 3, kScriptIsProjectorCommand = 1L << 4 };
For more information, see the explanation above of the new wired action kActionDoScript.
mcActionRestartAtTime
This allows a movie to be restarted at a particular time and rate. The parameter is a QTRestartAtTimePtr.
struct QTRestartAtTimeRecord { TimeValue startTime; /* time scale is the movie timescale*/ Fixed rate; /* if rate is zero, the movie's current rate is maintained*/ };
typedef struct QTRestartAtTimeRecord QTRestartAtTimeRecord; typedef QTRestartAtTimeRecord *QTRestartAtTimePtr;
For more information, see the explanation above of the new wired action kActionMovieRestartAtTime.
Custom Wired Actions 1
In QuickTime 3.5 and beyond, software developers using a plug-in mechanism may supplement the set of built-in wired actions. Custom Action Handler Components may be written to perform new types of actions. For example, a math library component could be written to perform complicated computations quickly, returning the result by setting a sprite track
Custom Wired Actions 55 RELEASE 1.0
What’s New in QuickTime 4.1
variable. Another use would be for allowing a custom media handler to be scripted using wired actions. Custom wired actions in a movie are routed to these components for handling. They are passed information about the current QTEvent, the movie element that is to be the target of the action, the default movie element that received the QTEvent and generated the action, the type of the action, and the parameters of the action. The wired action expression evaluation machinery has been exposed as a single API call, allowing general wired expressions to be passed as parameters.
Custom Action Handler Usage 1 Custom action handler usage falls into two categories: as a stateless subroutine library as an object that maintains state across multiple custom action executions When used as a subroutine library, the movie author simply scripts custom actions. QuickTime opens an instance of the specified custom action handler, passes it the action to execute, and then closes the component. When used as an object that maintains state, the movie author needs to open an instance of the handler with a unique instance ID. In this case, QuickTime keeps the action handler component open until the movie is closed. When making calls to an action handler that has been opened, the unique instance ID is specified, allowing QuickTime to route the request to the correct component instance. Note that there is currently no way to specify that the handler is a component that has already been opened by QuickTime, such as a media handler or codec that is in use. One special case has been included for developers authoring media handlers that support custom wired actions. If the component description of the custom action’s target matches that of the target media handler, then the custom action is sent to the instance of the media handler that already in use. This means that the movie author does not need to (and should not) open an instance of the component. When authoring a movie with a custom action, the type of component to use to execute it is specified, along with an instance ID. If the component is being used as a simple subroutine library, which does not need to keep track of any state, then the ID may be set to zero. If a particular instance of an open action-handling component is intended to be used, then the ID is used to refer to it. You may use the kActionOpenCustomHandler to open the component with a
56 Apple Custom Wired Actions RELEASE 1.0
What’s New in QuickTime 4.1 particular ID. This ID should be obtained by using the kOperandUniqueCustomHandlerID to ensure that your movie will work after edits are performed. After opening a custom action handler you may use kOperandCustomActionHandlerOpen to determine that the component was indeed found and opened successfully. If the instance ID is set to zero and the component description matches that of the media handler that is the target of the action, then the media handler is used to execute the custom action.
Authoring Custom Wired Actions 1 To specify that an action is to be handled by a custom handler, you add the kCustomActionHandler atom as a child of the kAction atom. You define which type of component is to handle the action by adding a kCustomHandlerDesc atom, and optionally specify a particular handler instance ID using the kCustomHandlerID atom.
Extension to Wired Movie Format: Executing Custom Actions 1
kActionAtom
You define parameter atoms as usual and have access to the parameters through an API for writing custom action handlers. This means that parameters may be wired expressions and your component may fetch the result of the evaluated expression.
New Wired Actions 1
kActionOpenCustomHandler Supported Flags: None Param 1: [long handlerID] Param 2: [QTCustomActionHandlerRecord
Custom Wired Actions 57 RELEASE 1.0
What’s New in QuickTime 4.1
Opens a custom action-handling component that may be referred to later by its handlerID. Typically, you will first use the kOperandUniqueCustomActionHandlerID operand to obtain a unique id. After storing this in a variable, you will use this action to open the handler. Then you may use kOperandCustomActionHandlerOpen to determine if the handler was found. How a custom action handler is specified to handle a given action in a movie is explained above in the section on “Authoring Custom Wired Actions”.
New Wired Operands 1
kOperandUniqueCustomActionHandlerID No Params
Returns a unique custom handler ID that may be used with kActionOpenCustomHandler.
kOperandCustomActionHandlerOpen Param 1: handlerID
Returns true if a handler with the specified ID is open, otherwise false. This may be used to determine if the component specified by kActionOpenCustomHandler was found and opened.
Writing a Custom Action Handler Component 1 Any component type, whether it is a media handler, a codec, or your own component type, may be extended to handle custom actions. To extend your component, you implement the ExecuteWiredAction routine described below. If you are writing a component that is being used only to handle custom actions, you should use the component type 'wire'.
EXTERN_API( ComponentResult ) CallComponentExecuteWiredAction (ComponentInstance ci, QTAtomContainer actionContainer, QTAtom actionAtom, QTCustomActionTargetPtr target, QTEventRecordPtr event);
58 Apple Custom Wired Actions RELEASE 1.0
What’s New in QuickTime 4.1
All the state passed to you in this routine is only valid for the duration of the execution of your custom action, which should be completed when you return from this routine. The actionContainer contains all of the actions that are being executed in response to the current QTEvent. This atom container should not be edited, only read from, since other actions that have yet to be executed may be contained within it. The actionAtom specifies the kActionAtom that concerns you, since it contains all of the atoms describing the action type and parameters to your components custom action that are to be executed. The target parameter specifies the movie elements that you need in order to execute your action.
struct QTCustomActionTargetRecord { Movie movie; DoMCActionUPP doMCActionCallbackProc; long callBackRefcon; Track track; long trackObjectRefCon; Track defaultTrack; long defaultObjectRefCon; long reserved1; long reserved2; }; typedef struct QTCustomActionTargetRecord QTCustomActionTargetRecord; typedef QTCustomActionTargetRecord * QTCustomActionTargetPtr;
The movie field is the movie that is or contains the movie element, which is the target of the action. The doMCActionCallbackProc and callBackRefcon specify the movie controller and refCon for the target movie’s movie controller. They may be used with the CallDoMCActionProc routine to invoke the movie controller functionality, including the new mcActionFetchParameterAs. The track field is the track that is or contains the movie element, which is the target of the action. The trackObjectRefCon field is the refCon or ID of the movie element that is the target of the action. If the target is a sprite, this will be the sprite ID.
Custom Wired Actions 59 RELEASE 1.0
What’s New in QuickTime 4.1
The defaultTrack is the track that contains the movie element that handled the QTEvent and generated the custom action. For example, if a hypertext element of a text track generated a SetSpriteVisible action for a sprite in a sprite track, the defaultTrack would be the Text track, while the Sprite Track would be the target track. The defaultObjectRefCon is the refCon or ID of the movie element that handled the QTEvent and generated the custom action. The event specifies information about what QTEvent generated the custom action.
The Action Being Executed 1 If your component defines multiple custom action types, then you may determine the action type by looking at the kWhichAction atom, which is a child atom of this kActionAtom. The data of this kWhichAction atom is a long defining the action (and needs byte flipping for Windows).
Fetching the Parameters 1 The parameters to your custom action may be the result of a wired expression. Don’t worry about analyzing the kActionParameter child atoms, the wired expression evaluation machinery has been made accessible via a movie controller action called mcActionFetchParameterAs. Fill out a QTFetchParameterAsRecord and pass it to mcActionFetchParameterAs as in:
CallDoMCActionProc(resolvedTarget->doMCActionCallbackProc, resolvedTarget->callBackRefcon, mcActionFetchParameterAs, &fetchAs, &handled );
struct QTFetchParameterAsRecord { QTAtomSpec paramListSpec; long paramIndex; long paramType; long allowedFlags; void * min; void * max; void * currentValue;
60 Apple Custom Wired Actions RELEASE 1.0
What’s New in QuickTime 4.1
void * newValue; Boolean isUnsignedValue; };
Set the container and atom of the paramListSpec to the actionContainer and actionAtom passed to ExecuteWiredAction(). Set the paramIndex to the index of the parameter you wish to fetch. If you allow a variable number of parameters, you may count how many child atoms of type kActionParameter the actionAtom has. Set the paramType to one of the parameter types from the following enumeration: enum { kFetchAsBooleanPtr = 1, kFetchAsShortPtr = 2, kFetchAsLongPtr = 3, kFetchAsMatrixRecordPtr = 4, kFetchAsModifierTrackGraphicsModeRecord = 5, kFetchAsHandle = 6, kFetchAsStr255 = 7, kFetchAsFloatPtr = 8, kFetchAsPointPtr = 9, kFetchAsNewAtomContainer = 10, kFetchAsQTEventRecordPtr = 11, kFetchAsFixedPtr = 12, kFetchAsSetControllerValuePtr = 13, kFetchAsRgnHandle = 14, /* flipped to native*/ kFetchAsComponentDescriptionPtr = 15, kFetchAsCString = 16 };
Set the allowedFlags to flags from the following enumeration, or zero fetching without constraints. enum { kActionFlagActionIsDelta = 1L << 1, kActionFlagParameterWrapsAround = 1L << 2, kActionFlagActionIsToggle = 1L << 3 };
Custom Wired Actions 61 RELEASE 1.0
What’s New in QuickTime 4.1
If allowedFlags is not set to zero, set the min, max, current, and isUnsignedValue fields to appropriate values based on the data type being fetched. The newValue field returns the result of the parameter. For scalar and structure types, pass a pointer to the appropriate data type and it will be filled in. For Handle, RgnHandle, and Cstring pass in a new empty handle that will be resized as needed, you are responsible for disposing the handle when done. For kFetchAsNewAtomContainer, pass in a pointer to a non-allocated QTAtomContainer. On return, this container will contain the contents of the single child atom of the parameter atom and all of its children. This lets you pass arbitrary data that is not evaluated in an atom container as a parameter. A sample custom wired action-handling component has been provided.
API Additions 1
This section discusses the API changes and additions to QuickTime 4.1.
Support for Playback of VBR Audio 1 QuickTime 4.1 and the Sound Manager introduce support for the playback of variable bitrate (VBR) audio. This new capability is discussed in detail in the section “Support for Playback of VBR Audio” beginning on page 82.
Changes to Graphics Importers 1
The Photoshop graphics importer now implements the GetDefaultMatrix call, so that applications can locate the position of individual layers in multi-layer files. The TIFF graphics importer now implements the GetDefaultMatrix call to help applications cope with TIFF fax images that have different horizontal and vertical resolutions.
62 Apple API Additions RELEASE 1.0
What’s New in QuickTime 4.1
New Anchor Data Reference 1 To resolve relative data references, a method was needed to determine the original location from which a movie was opened or imported. To address this, the concept of a movie’s anchor data reference is introduced in QuickTime 4.1. This data reference indicates from where the movie was originally opened or imported but still allows the movie’s default data reference to remain nil in the import-in-place case. Two new QuickTime Movie Toolbox routines are introduced:
pascal OSErr SetMovieAnchorDataRef ( Movie theMovie, Handle dataRef, OSType dataRefType);
This routine sets the movie’s anchor data reference. Pass nil to reset the anchor data reference to nothing. The routine copies the data reference.
pascal OSErr GetMovieAnchorDataRef ( Movie theMovie, Handle *dataRef, OSType *dataRefType, long *flags);
This routine retrieves a movie’s anchor data reference and type. If the movie has SetMovieAnchorDataRef called on it, the routine will return a copy of the data reference and type. If there is no anchor data reference associated with the movie, then this routine will return a copy of the default data reference and type along with setting the following bit of the long integer referenced through the flags parameter.
kMovieAnchorDataRefIsDefault = 1 << 0
If there is neither an anchor nor a default data reference, nil will be returned for the data reference and 0 for the type.
Note The caller should dispose of the data reference returned.
A New Data Handler Routine 1
In previous releases of QuickTime, when you used the DataHGetMovie routine, the data handler relied on whatever flags it thought appropriate. A new data
API Additions 63 RELEASE 1.0
What’s New in QuickTime 4.1
handler call, DataHGetMovieWithFlags, is introduced in QuickTime 4.1 to allow flags to be passed to a data handler capable of returning movies. These flags correspond to flags normally passed to NewMovie, NewMovieFromFile, and NewMovieFromDataRef, such as newMovieActive.
Support for M3U Playlists and .CEL Files 1
QuickTime 4.1 can import M3U playlists. This enables you to play the list of MP3 files in sequence. QuickTime can now recognize and import .CEL files. A .CEL file is virtually identical to a .FLC file. (A .FLC file is an Autodesk animator file.) The only difference between a .CEL file and a .FLC file is the extension, as far as QuickTime is concerned.
JavaScript Support 1
QuickTime 4.1 now enables JavaScript control of the QuickTime Plug-in. This works currently only in Netscape browsers. An example of JavaScript usage to play and stop a QuickTime movie is shown in Listing 6, “Sample JavaScript Usage” beginning on page 75. The browser will not recognize that the QuickTime Plug-in is JavaScriptable unless the movie’s embed statement includes “enablejavascript=true”. Technically, Netscape communicates from JavaScript to the plug-in through Java, which requires that Java is running. Rather than require that the browser be running Java to display any embedded movie, the QuickTime Plug-in does not ask the browser to start Java unless the embed statement or movie user data includes this tag. The following are the QuickTime Plug-in’s JavaScript methods. These allow you to query and control QuickTime movies within a browser page.
Movie Commands 1
void Play()
64 Apple Support for M3U Playlists and .CEL Files RELEASE 1.0
What’s New in QuickTime 4.1
The play command plays the movie at the default rate from the point (time) at which it receives the command.
void Stop()
This command stops the movie at the point in time at which the command is received.
void Rewind()
The rewind command sets the current time to the movie’s start time and pauses the movie.
void Step(int count)
This command steps the movie forward or backward the specified number of frames from the point at which the command is received. If the movie’s rate is non-zero, it is paused.
void ShowDefaultView()
This command displays a QuickTime VR movie’s default node, using the default pan angle, tilt angle, and field of view as set by the movie’s author.
void GoPreviousNode()
This command returns to the previous node in a QuickTime VR movie (equivalent to clicking the Back button on the VR movie controller).
Movie Properties 1
void SetRate(float rate) float GetRate()
Gets and sets the playback rate of the movie. A value of “1” indicates that the movie is playing in normally. A paused movie has a rate of “0”. Negative values indicate that the movie is playing in reverse. Setting the rate of a paused movie to a non-zero value starts the movie playing.
JavaScript Support 65 RELEASE 1.0
What’s New in QuickTime 4.1
void SetTime(int time) int GetTime()
Gets and sets the current time of the specified QuickTime movie. Setting this property causes the movie to go to that time in the movie and stop.
void SetVolume(int volume) int GetVolume()
Gets and sets the audio volume of the movie. A negative value mutes the movie.
void SetMovieName(string movieName) string GetMovieName()
Gets and sets the name optionally used by a wired sprite when targeting an external movie. This is the same as the “MOVIENAME” embed tag.
void SetMovieID(int movieID) int GetMovieID()
Gets and sets the ID optionally used by a wired sprite when targeting an external movie. This is the same as the “MOVIEID” embed tag.
void SetStartTime(int time) int GetStartTime()
Gets and sets the time at which it begins to play, and the time at which it loops when playing in reverse. Initially, the startTime of a movie is set to “0” unless specified in the “STARTTIME” embed tag. It cannot be set to a time greater than the endTime. This is the same as the “STARTTIME” embed tag.
void SetEndTime(int time) int GetEndTime()
Gets and sets the time at which the movie will loop or stop playing. Initially, the endTime of a movie is set to its duration unless specified in the “ENDTIME” embed tag. It cannot be set to a time less than the startTime, nor greater than the movie’s duration. This is the same as the “ENDTIME” embed tag.
66 Apple JavaScript Support RELEASE 1.0
What’s New in QuickTime 4.1
void SetBgColor(string color) string GetBgColor()
Gets and sets the color used to fill any space withing the embed region not covered by the movie. This is the same as the “BGCOLOR” embed tag and takes the same values. Regardless of how the color was specified, GetBgColor() always returns the color number, e.g., if the bgcolor was set to “Navy”, GetBgColor() will return “#000080”.
void SetIsLooping(boolean loop) boolean GetIsLooping()
Gets and sets whether or not a movie loops when it reaches its end. A movie loops in either reverse or forward play. This is the same as the “LOOP=TRUE” or “LOOP=FALSE” embed tag.
void SetLoopIsPalindrome(boolean loop) boolean GetLoopIsPalindrome()
Gets and sets whether or not a looping movie will reverse direction when it loops. The “LOOP” property must be true for this to have any effect. This is the same as the “LOOP=PALINDROME” embed tag.
boolean GetMute() void SetMute(boolean mute)
Gets and sets the audio mute of a movie while maintaining the magnitude of the volume, so turning mute off restores the volume.
void SetPlayEveryFrame(boolean playAll) boolean GetPlayEveryFrame()
This is the same as the PLAYEVERYFRAME embed tag.
void SetAutoPlay(boolean autoPlay) boolean GetAutoPlay()
This is the same as the AUTOPLAY embed tag.
void SetControllerVisible(boolean visible) boolean GetControllerVisible()
JavaScript Support 67 RELEASE 1.0
What’s New in QuickTime 4.1
Gets and sets the visibility of the movie controller. This is the same as the CONTROLLER embed tag.
void SetHREF(string url) string GetHREF()
Gets and sets the movie’s HREF url. This is the same as the “HREF” embed tag.
void SetTarget(string target) string GetTarget()
Gets and sets the movie’s HREF url target. This is the same as the “TARGET” embed tag.
void SetQTNEXTUrl(int index, string url) string GetQTNEXTUrl(int index)
Gets and sets the specified QTNEXT url and target. This is the same as the “QTNEXTnn” embed tag).
void SetHotspotUrl(int hotspotID, string url) string GetHotspotUrl(int hotspotID)
Gets and sets the specified VR movie hotspot url. This is the same as the “HOTSPOTnn” embed tag).
void SetHotspotTarget(int hotspotID, string target) string GetHotspotTarget(int hotspotID)
Gets and sets the specified VR movie hotspot url target. This is the same as the “TARGETnn” embed tag).
void SetURL(string url)
Replaces the movie with that specified by the parameter.
string GetURL()
Returns the movie’s fully specified URL.
void SetKioskMode(boolean kioskMode)
68 Apple JavaScript Support RELEASE 1.0
What’s New in QuickTime 4.1
This is the same as the KIOSKMODE embed tag.
Note If the movie’s embed tag or user data has “KIOSKMODE=TRUE”, SetKioskMode() does nothing.
boolean GetKioskMode()
Returns the current KIOSKMODE setting.
int GetDuration()
Returns the length of the movie (in the movie’s time scale).
int GetMaxTimeLoaded()
Returns the amount of the movie that has been downloaded (in the movie’s time scale).
int GetTimeScale()
Returns the number of units of time per second in the movie.
int GetMovieSize()
Returns the size of the movie in bytes.
int GetMaxBytesLoaded()
Returns the number of bytes of the movie that have been downloaded.
void SetMatrix(string matrix) string GetMatrix()
These allow you to get and set the movie’s transformation matrix. QuickTime uses a 3 x 3 transformation matrix, represented in JavaScript by three lines of three numbers separated by commas: a, b, u c, d, v
JavaScript Support 69 RELEASE 1.0
What’s New in QuickTime 4.1
h, k, w
Note Normally, the QuickTime Plug-in keeps the movie centered within the embed area, even if the embed area changes. Once a movie’s location is changed with SetRect or SetMatrix, the movie’s absolute location within the embed area is maintained rather than centering it.
void SetRectangle(string rect) string GetRectangle()
These allow you to get and set location and dimensions of the movie within the embed area.
Note Normally, the QuickTime Plug-in keeps the movie centered within the embed area, even if the embed area changes. Once a movie’s location is changed with SetRect or SetMatrix, the movie’s absolute location within the embed area is maintained rather than centering it.
void SetLanguage(string language)
Sets the movie’s current language. This causes the tracks associated with that language to be enabled and tracks associated with other languages to be disabled. If it cannot find an appropriate track for the specified language, the movie’s language is not changed.
string GetLanguage()
Returns the name of movie’s current language.
70 Apple JavaScript Support RELEASE 1.0
What’s New in QuickTime 4.1
Supported language names are shown in Table 1.
Table 1 Supported language names
Language Script system English Roman script French Roman script German Roman script Italian Roman script Dutch Roman script Swedish Roman script Spanish Roman script Danish Roman script Portuguese Roman script Norwegian Roman script Hebrew Hebrew script Japanese Japanese script Arabic Arabic script Finnish Roman script Greek Greek script using Roman script code Icelandic variant Roman script Maltese variant Roman script Turkish variant Roman script Croatian Serbo-Croatian in variant Roman script TradChinese Chinese (Mandarin) in traditional characters Urdu Arabic script
string GetMIMEType()
Returns the movie’s MIME type.
JavaScript Support 71 RELEASE 1.0
What’s New in QuickTime 4.1
string GetUserData(string type)
Returns the movie user data text with the specified tag. The tag is specified with a four character string, for example ‘@cpy’ returns a movie’s copyright string. For a more complete list of user data tags, see
Track Properties 1
int GetTrackCount()
Returns the number of tracks in the movie.
string GetTrackName(int index)
Returns the name of the specified track.
string GetTrackType(int index)
Returns the type of the specified track.
boolean GetTrackEnabled(int index)
void SetTrackEnabled(int index, boolean enabled)
These get and set the enabled state of a track.
Sprite Track Properties 1
void SetSpriteTrackVariable(int trackIndex, int variableIndex, string value) string GetSpriteTrackVariable(int trackIndex, int variableIndex)
These get and set the specified sprite track variable in the specified track.
72 Apple JavaScript Support RELEASE 1.0
What’s New in QuickTime 4.1
QuickTime VR Movie Properties 1
boolean GetIsVRMovie()
Returns true if the movie is a QuickTime VR movie, false otherwise.
void SetPanAngle(float angle) float GetPanAngle()
Gets and sets the QuickTime VR movie’s pan angle (in degrees).
void SetTiltAngle(float angle) float GetTiltAngle()
Gets and sets the QuickTime VR movie’s tilt angle (in degrees).
void SetFieldOfView(float fov) float GetFieldOfView()
Gets and sets the QuickTime VR movie’s field of view (in degrees).
int GetNodeCount()
Returns the number of nodes in a QuickTime VR movie.
int GetNodeID()
Returns the ID of the current node in a QuickTime VR movie.
void SetNodeID(int id)
Sets the current node (by ID) in a QuickTime VR movie (i.e., it goes to the node with the specified ID).
Plug-in Properties 1
string GetPluginVersion()
Returns the version of the QuickTime Plug-in.
JavaScript Support 73 RELEASE 1.0
What’s New in QuickTime 4.1
string GetPluginStatus()
Returns a string with the status of the current movie. Possible states are: “Waiting” - waiting for the movie data stream to begin “Loading” - data stream has begun, not able to play/display the movie yet “Playable” - movie is playable, although not all data has been downloaded “Complete” - all data has been downloaded “Error:
boolean GetResetPropertiesOnReload() void SetResetPropertiesOnReload(boolean reset)
By default, most movie and plug-in properies are reset when a new movie is loaded (QTSRC, target=”myself”, etc).
QuickTime Properties 1
string GetQuickTimeVersion()
Returns the version of QuickTime.
string GetQuickTimeLanguage()
Returns the user’s QuickTime language (set with the Plug-in’s “Set Language” dialog).
int GetQuickTimeConnectionSpeed()
Returns the connection speed setting from the users QuickTime preferences.
boolean GetIsQuickTimeRegistered()
Returns true if the user is registered for the Pro version of QuickTime, it otherwise returns false.
string GetComponentVersion(string type, string subType, string manufacturer)
74 Apple JavaScript Support RELEASE 1.0
What’s New in QuickTime 4.1
Returns the version of a specific QuickTime component. The component is specified using a four character string for the type, subType, and manufacturer. For example, to check the version of Apple’s JPEG graphics importer call
GetComponentVersion(‘grip’,’JPEG’, ‘appl’)
‘0’ is a wildcard for any field. If the component is not available, “0.0” is returned.
Sample JavaScript Usage 1
The following is a simple HTML file that shows four equivalent ways to specify the movie object. In Listing 6, a JavaScript function takes a QuickTime movie and calls its Play() and Stop() methods.
Listing 6 Using JavaScript functions to play and stop a QuickTime movie
This is a test of QuickTime embedded...
| this has the name "movie1" | this has the name "movie2" |
Calling a JavaScript function which takes an object referenced by name
javascript:PlayIt(document.movie1)
javascript:StopIt(document.movie1)
javascript:PlayIt(document.movie2)
javascript:StopIt(document.movie2)
Calling an object (referenced by name) method directly
javascript:document.movie1.Play()
javascript:document.movie1.Stop()
javascript:document.movie2.Play()
javascript:document.movie2.Stop()
76 Apple Sample JavaScript Usage RELEASE 1.0 What’s New in QuickTime 4.1 href="javascript:document.embeds[0].Stop();">javascript:document.embeds[0].Stop() javascript:document.embeds[1].Play() javascript:document.embeds[1].Stop() Introduction of Asynchronous Movie Loading 1 QuickTime 4.1 introduces asynchronous movie loading. There are a number of advantages to using this mechanism. With asynchronous movie loading, the QuickTime Player allows the command Open URL... to return immediately. Then, as the URL data becomes available, the movie becomes playable. To the user, the introduction of asynchronous movie loading can mean a more responsive system. To the developer, it can mean more time to do things while a movie loads in cases where it takes some time for data to arrive, e.g., a large file transfer or a slow network connection. With movies loading asynchronously, the difference in user experience centers on the time before the movie data has actually been located and processed. Instead of a fully formed movie being immediately available and playable, the Introduction of Asynchronous Movie Loading 77 RELEASE 1.0 What’s New in QuickTime 4.1 Player window displays the message Loading... until the movie resource is located or the file has been imported. At that point, the window can resize, auto play can occur if necessary, and other choices about the movie and the controller can be made. The Movie Media Handler also takes advantage of this feature. In the context of asynchronous movie loading, the following items should be noted: Only movies that are opened over slow connections will perform asynchronous loading. The user experience remains unchanged for completely local content or content over a sufficiently fast connection. Note that to enable this functionality, you have to pass newMovieAsyncOK. During the time that the movie is loading, the machine should remain responsive. This does not affect fast-starting a movie. This only affects the time period between when a movie is chosen and when the movie resource has been found or the movie is imported. It is possible to have local movies that are either data rate alternate or shortcut movies which themselves reference files over slow connections. While the loading of the local reference movie is quick, the total movie loading process will use asynchronous loading, since portions of the loading process require it. Aside from a more responsive system, the fundamental change for the developer that asynchronous loading brings is that the NewMovieFrom... function will return a valid movie, but that movie may be completely empty, i.e., it may contain no tracks, user data, and so on. At some point, when the movie resource is found or the file has been imported all of this information is then available. A developer may need to defer querying of the movie for properties, Userdata, and other characteristics until that time. To enable asynchronous loading when opening a movie, you pass the additional flag newMovieAsyncOK = 1 << 8 to NewMovieFromDataRef, NewMovieFromFile, and so on. Passing this flag does not require that the loading be performed asynchronously, but only allows it to be so. Without newMovieAsyncOK, calling one of the NewMovieFrom... calls either returns a fully formed movie or an error –– blocking until either can be satisfied. 78 Apple Introduction of Asynchronous Movie Loading RELEASE 1.0 What’s New in QuickTime 4.1 A Change in the Loading Model 1 The loading model has changed from this NewMovieFrom... pascal long GetMovieLoadState( Movie theMovie ); The GetMovieLoadState routine returns a value that indicates the state of the loading process. kMovieLoadStateLoading // searching for movie resource kMovieLoadStatePlayable // movie fully formed, fast-start would work kMovieLoadStateComplete // all media data is available These values are ordered so that the values treated as numbers conform to this rule: kMovieLoadStateLoading < kMovieLoadStatePlayable < kMovieLoadStateComplete This allows code to perform relative comparisons against these milestones to determine if certain operations make sense. There is also an additional state kMovieLoadStateError indicating that the loading of the movie failed. This typically means that a URL could not be found or loaded. This has a negative value, so that the above rule becomes: kMovieLoadStateError < kMovieLoadStateLoading < kMovieLoadStatePlayable < kMovieLoadStateComplete Introduction of Asynchronous Movie Loading 79 RELEASE 1.0 What’s New in QuickTime 4.1 If the value is less than complete, then you should not assume that you can save it. Note If the load state is negative, then this indicates an error has occurred. Not all states will be seen by a client. A completely local movie will transition directly to kMovieLoadStateComplete. A local movie with media stored on a slow connection will probably transition to kMovieLoadStatePlayable since fast-starting will occur. By way of a quick example of code using this new information, consider how the load state might be used by an application updated to recognize asynchronous movie loading. Assume that it called the NewMovieFromDataRef function to open a URL: err = NewMovieFromDataRef( &theMovie, newMovieActive | newMovieAsyncOK, nil, url, URLDataHandlerSubType ); and periodically it will check the movie to see if it has reached a particular state of interest: void checkOnMovie( MovieInfo movieInfo ) { long loadState; loadState = GetMovieLoadState(movieInfo->theMovie); if (movieInfo->loadState == loadState) // didn't change return; movieInfo->loadState = loadState; // new state if (loadState < 0) { // failed to load the movie so tell the user and dispose of movie } if (loadState < kMovieLoadStatePlayable) { // just keep tasking the movie so it gets time to load } if (loadState < kMovieLoadStateComplete) { 80 Apple Introduction of Asynchronous Movie Loading RELEASE 1.0 What’s New in QuickTime 4.1 // we just became playable // get movie box and size window // put a movie controller on this movie // update other UI appropriately // check for auto play } if (loadState >= kMovieLoadStateComplete) { // now we know all media data is available and we might // only now allow the user to perform a self-contained save // or an export } } Until the movie has reached its playable state, an application should not try to attach a movie controller, since the user data that allows the QuickTime Movie Toolbox to choose the type of movie controller will not be available. Also, the application should call the MoviesTask function to give it time to continue loading. This offers a way to detect the difference between when the movie is fast-starting and therefore its data is not all available and when it is fully loaded. This is useful in enabling certain menu items only appropriate when all media is accessible. In the future, it is expected that new and useful states will be added. However, it will be done in such a way that the above ordering still holds. GetMovieStatus Updated 1 Because the movie is loaded asynchronously, you can’t use the return value from NewMovieFrom... exclusively to detect errors in loading. Instead, the GetMovieStatus function has been updated, so that it can return errors reported from the asynchronous loading machinery. In this case, the problemTrack will be set to nil. You can use this error along with GetMovieLoadState to determine if loading failed. Note that you also need to call MoviesTask to make sure the movie state progresses. Introduction of Asynchronous Movie Loading 81 RELEASE 1.0 What’s New in QuickTime 4.1 Other API Additions 1 GetMovieLoadState doesn’t do all the work itself. Instead, it queries media handlers, checks if the movie is fast starting, and queries any idling importers associated with the movie. The minimum load state of all of these is then considered to be the load state of the movie. To check idling importers, the QuickTime Movie Toolbox calls the routine: pascal ComponentResult MovieImportGetLoadState( MovieImportComponent ci, long * loadState ); on all idling importers attached to the movie. Support for Playback of VBR Audio 1 QuickTime 4.1 and the Sound Manager introduce support for the playback of variable bitrate (VBR) audio. Prior to this release, QuickTime only supported constant bitrate (CBR) audio. However, a number of modern audio compression formats –– such as MP3 –– either support or require VBR encoding. This is provided in the current QuickTime 4.1 release. Background 1 The fundamental difference between constant bitrate (CBR) and variable bitrate (VBR) audio is related to the rate at which audio data is presented to the sound decoder to generate sound. In CBR audio, the rate is constant. If one second of audio requires 40 K bytes, then 5 seconds will require 200 K bytes (= 40 Kbytes/sec * 5 sec). Moreover, given a stream of 3 minutes of audio compressed like this, to start playing at 2:30, you would advance 6,000K into the stream. With VBR audio, the data rate varies depending upon the complexity of the encoded sound. For example, a very quiet passage of a score could be compressed much more than a very exciting passage. A VBR encoder will analyze the audio and use the appropriate number of bits, varying its usage in the process. This means that the amount of data for a complex passage is greater than for a less complex passage. This also complicates locating data in the stream because the “road map” is located within the stream. 82 Apple Support for Playback of VBR Audio RELEASE 1.0 What’s New in QuickTime 4.1 By way of analogy, video encoding formats are typically VBR in nature. A more complex image requires more bits than a less complex image. As different images are encoded, the number of bits required for each will vary. The analog to CBR audio in the video space is raw RGB or uncompressed YUV. VBR-Supported Features 1 The VBR-supported features in QuickTime 4.1 include: opening and importing of both CBR and VBR encoded MP3 files. editing of local movies containing MP3 VBR sound tracks, using standard cut, copy, and paste operations. saving movies containing VBR sound tracks, either as self-contained or non-self-contained QuickTime movie files. exporting from an MP3 VBR compressed sound track to any sound format for which QuickTime has a compressor. Exported data can be saved to WAV, AIFF, snd, .au, AVI, and any other file type format that supports sound. fast-starting of MP3 VBR files. There is also support of MP3 VBR audio for streaming. Features include: hinting of movies containing VBR sound tracks streaming of MP3 VBR sound data to VBR aware clients Note In the descriptions above, MP3 VBR should be considered to be interchangeable with “a VBR audio format.” Initially, MP3 will be the only decompressor that takes advantage of added VBR support. In future releases, additional decompressors/compressors will be provided for other VBR sound formats. New Sound Manager APIs 1 In addition to two new SoundManagerGetInfo and SoundManagerSetInfo calls, there is a new Sound Converter API in QuickTime 4.1, which is discussed in the New Sound Manager APIs 83 RELEASE 1.0 What’s New in QuickTime 4.1 next section. Note that this new API is now the recommended way to use the Sound Converter. SoundManagerGetInfo 1 pascal OSErr SoundManagerGetInfo(OSType selector, void* infoPtr); This routine retrieves global information about the Sound Manaager. Defined selectors: siSupportedExtendedFlags Retrieves which flags are supported in Extended sound data structures in an unsigned long. SoundManagerSetInfo 1 pascal OSErr SoundManagerSetInfo(OSType selector, void* infoPtr); This routine sets global information about the Sound Manager. Defined selectors: none SoundConverterFillBuffer 1 Provides an alternative method for converting data using the Sound Converter, which is both more predictable and more flexible than the SoundConverterConvertBuffer mechanism. The SoundConverterFillBuffer function can return any Sound Manager error. pascal OSErr SoundConverterFillBuffer( SoundConverter sc, SoundConverterFillBufferDataUPP fillBufferDataUPP, void* fillBufferDataRefCon, 84 Apple New Sound Manager APIs RELEASE 1.0 What’s New in QuickTime 4.1 void* outputBuffer, unsigned long outputBufferByteSize, unsigned long* bytesWritten, unsigned long* framesWritten, unsigned long* outputFlags ) sc The Sound Converter context to work with (created with SoundConverterOpen). fillBufferDataUPP A UPP that points to a routine that can provide data to the Sound Converter. fillBufferDataRefCon This value is passed to the SoundConverterFillBufferDataUPP. It can be used for any purpose the client wishes. outputBuffer The buffer to write the data into. outputBufferByteSize The size of outputBuffer in bytes. No more than this amount will ever be written during a single call to SoundConverterFillBuffer. bytesWritten Upon completion, the number of bytes that were written into outBuffer. framesWritten Upon completion, the number of sample frames written into outBuffer. outputFlags Upon completion, a set of bit flags that indicate the state of the conversion. These are the currently defined flags: kSoundConverterDidntFillBuffer Set if the converter didn’t completely fill the output buffer. New Sound Manager APIs 85 RELEASE 1.0 What’s New in QuickTime 4.1 kSoundConverterHasLeftOverData Set if the converter still has more data to deliver. This indicates that more calls to SoundConvertFillBuffer should be made to complete the conversion. A caveat: If this flag is not set, it doesn’t indicate there is necessarily more data in the pipeline. These are advisor flags only: they don’t guarantee any internal data. You need to keep track of your data. Working with SoundConverterFillBuffer 1 In general, working with the SoundConverterFillBuffer function is much like working with SoundConverterConvertBuffer. You still call the SoundConverterOpen, SoundConverterClose, SoundConverterBeginConversion and SoundConverterEndConversion routines just as you always have and you still typically perform the conversion in a loop. The differences begin with how the buffering is done. SoundConverterFillBuffer will do as much or as little work as is required to satisfy a given request. This means that you can pass in buffers of any size you like and expect that the Sound Converter will never overflow the output buffer. Moreover, the SoundConverterFillBufferDataProc function will be called as many times as necessary to fulfill a request. This means that the SoundConverterFillBufferDataProc routine is free to provide data in whatever chunk size it likes. Of course with both sides, the buffer sizes will control how many times you need to request data and there is a certain amount of overhead for each call. You will want to balance this against the performance you require. While a call to SoundConverterGetBufferSizes is not required by the SoundConverterFillBuffer function, it is useful as a guide for non-VBR formats. The following code snippet illustrates a typical use of SoundConverterFillBuffer. 86 Apple New Sound Manager APIs RELEASE 1.0 What’s New in QuickTime 4.1 Listing 7 A typical usage of the SoundConverterFillBuffer routine { SoundComponentData inputFormat, outputFormat; SoundConverter sc; Boolean hasLeftOverData = false; unsigned long totalBytesWritten = 0; unsigned long totalFramesWritten = 0; unsigned long bytesWritten = 0; unsigned long framesWritten = 0; unsigned long outputFlags = 0; unsigned long outputBufferByteSize = 0; void* outputBuffer = NULL; GetFormats(&inputFormat, &outputFormat); SoundConverterOpen(&inputFormat, outputFormat, &sc); SoundConverterBeginConversion(sc); while(HasMoreSourceData() || hasLeftOverData) { bytesWritten = 0; framesWritten = 0; outputFlags = 0; outputBufferByteSize = 0; outputBuffer = GetNextOutputBuffer(&outputBufferByteSize); SoundConverterFillBuffer(sc, MySoundConverterFillBufferDataUPP, NULL, outputBuffer, outputBufferByteSize, &bytesWritten, &framesWritten, &outputFlags); // advance whatever pointers we need to totalBytesWritten += bytesWritten; totalFramesWritten += framesWritten; // figure out if we have any data still stuck in the chain hasLeftOverData = outputFlags & kSoundConverterHasLeftOverData; } New Sound Manager APIs 87 RELEASE 1.0 What’s New in QuickTime 4.1 // get the left overs outputBuffer = GetNextOutputBuffer(&outputBufferByteSize); SoundConverterEndConversion(sc, outputBuffer, &bytesWritten, &framesWritten); // advance whatever pointers we need to totalBytesWritten += bytesWritten; totalFramesWritten += framesWritten; SoundConverterClose(sc); } The SoundConverterFillBufferDataProc could look something like this: pascal Boolean SoundConverterFillBufferDataProc( SoundComponentDataPtr* data, void* refCon) { *data = GetNextSourceBuffer(refCon); return *data != NULL; } Writing the SoundConverterFillBufferData Routine 1 If you call SoundConverterFillBuffer, you must provide a callback routine that provides the source data for the conversion. This is the SoundConverterFillBufferData routine whose prototype is: pascal Boolean SoundConverterFillBufferDataProc( SoundComponentDataPtr* data, void* refCon); The SoundConverterFillBufferDataProc call provides its data by setting the data argument to a pointer to a properly filled out SoundComponentData or ExtendedSoundComponentData structure. The refCon argument is the same fillbufferDataRefCon passed into SoundConverterFillBuffer. 88 Apple New Sound Manager APIs RELEASE 1.0 What’s New in QuickTime 4.1 The SoundConverterFillBufferDataProc tells its caller whether or not it provided any data through the Boolean return value. The data provided by the SoundConverterFillBufferDataProc is not considered consumed until either the SoundConverterFillBufferDataProc is called again or SoundConverterEndConversion is called. Until those times, the data should be considered “in use” and shouldn’t be modified. Because of the the way the Sound Converter works, the SoundConverterFillBufferDataProc routine may be called several times after returning no data from the previous call. Unless there is actually more data to provide, the SoundConverterFillBufferDataProc routine should continue to return no data. Note The SoundConverterFillBufferDataProc routine, like all Sound Converter-related routines, may be called at interrupt time (if the client of SoundConvertFillBuffer called it at interrupt time), so it should not move or allocate memory. Sound.h Updated 1 The Sound.h file contains new definitions for extended data types and associated flags in QuickTime 4.1. SoundMediaGetSource 1 This is another version of the Sound media handler that uses the extended form of scheduledSoundCmd to send the source buffer size (in bytes) to the decompressor. This implements the preferred approach. For more information, refer to the Sound Manager 3.3 Release Notes or the document Mac OS Sound available at API Changes 1 The changes from a decompressor’s (indeed, the entire sound chain’s) perspective include support for extended forms of the SoundComponentData and Sound.h Updated 89 RELEASE 1.0 What’s New in QuickTime 4.1 SoundParamBlock records. Additionally, a client can now pass this information to the sound channel by using an extended form of the ScheduledSoundHeader with the scheduledSoundCmd. This section describes each new structure that is available in Sound.h. ExtendedSoundComponentData 1 The ExtendedSoundComponentData structure is shown below. struct ExtendedSoundComponentData { SoundComponentData desc; /*description of sound buffer*/ long recordSize; /*size of this record in bytes*/ long extendedFlags; /*flags for extended record*/ long bufferSize; /*size of buffer in bytes*/ }; typedef struct ExtendedSoundComponentData ExtendedSoundComponentData; typedef ExtendedSoundComponentData * ExtendedSoundComponentDataPtr; Its first element is a classic SoundComponentData allowing a pointer to a SoundComponentData to also serve as a pointer to an ExtendedSoundComponentData. This means that in parts of the component API where a SoundComponentData was passed or retrieved, it is now possible to find an ExtendedSoundComponentData. To determine if the SoundComponentData is an ExtendedSoundComponentData, you can check the following flag in the flags field of a SoundComponentData: kExtendedSoundData = (1 << 14) If set, you know that the structure consists at least of the fields shown here –– namely, recordSize, extendedFlags and bufferSize. In the future, it is expected that the set of fields will be extended, so it is important to confirm that the fields you want to read are actually present. To that end, you should compare the recordSize field’s value to the size of a record containing the fields you need. If the record size is smaller, then you know the fields are missing. The bufferSize field holds the number of bytes in the buffer. This allows for cases where the number of bytes isn’t derivable directly from the number of samples. In the cases where it is derivable, this information is at worst redundant. The extendedFlags holds fields relating to the interpretation of the new fields and to the interpretation of the old fields. The fields defined currently are: 90 Apple Sound.h Updated RELEASE 1.0 What’s New in QuickTime 4.1 kExtendedSoundSampleCountNotValid = 1L << 0 kExtendedSoundBufferSizeValid = 1L << 1 The kExtendedSoundBufferSizeValid flag indicates if the bufferSize field is valid. If not set, then you shouldn’t use the bufferSize field’s value. In the case of the 4.1 sound media handler, the buffer size is now passed so this flag is set. The kExtendedSoundSampleCountNotValid is slightly more unusual. This allows a buffer of audio of bufferSize bytes to not declare the number of audio samples that it will generate. Note that if this flag is set, the bufferSize field must be valid and the kExtendedSoundBufferSizeValid flag must be set. While this ability to not specify the sample count is of little use in the sound media handler case where the sample references already describe the durations of all the samples, it may prove more useful in other cases. One such case involves sound conversion where the decompressor is asked to generate audio samples until a source buffer is exhausted. Instead of requiring that we know the number of source audio samples before decompression, this allows the client to just feed audio until there is no more. Another case involves playback where durations aren’t known. In both cases, it seems advantageous to not have to ask the decompressor to parse all the data just to determine the number of audio samples only to pass that number back to the decompressor so that it can parse and actually decode the data. From the sound decompressor’s point of view, this is the most important new structure and is available from the decompressor’s call to its source’s SoundComponentGetSourceData call. Keep in mind that the structure returned may not be an ExtendedSoundComponentData, so be careful to check. ExtendedSoundParamBlock 1 The ExtendedSoundParamBlock is an extended form of SoundParamBlock. Like ExtendedSoundComponentData, it consists of the unextended classic structure followed by new fields. struct ExtendedSoundParamBlock { SoundParamBlock pb; /*classic SoundParamBlock except recordSize == sizeof(ExtendedSoundParamBlock)*/ short reserved; long extendedFlags; /*flags*/ long bufferSize; /*size of buffer in bytes*/ Sound.h Updated 91 RELEASE 1.0 What’s New in QuickTime 4.1 }; typedef struct ExtendedSoundParamBlock ExtendedSoundParamBlock; typedef ExtendedSoundParamBlock * ExtendedSoundParamBlockPtr; Unlike SoundComponentData, however, the recordSize field of the SoundParamBlock is used to detect if this is an ExtendedSoundParamBlock. If the record size is greater than SoundParamBlock, then you know it has been extended. Also, in the future, it is expected that this structure will grow, so you want to check for a record of sufficient size to hold the fields you are seeking. The fields of ExtendedSoundParamBlock are: pb Classic SoundParamBlock record. Its recordSize field allows you to detect extended records. reserved Reserved. extendedFlags Same interpretation as extendedFlags in ExtendedSoundComponentData. bufferSize Size of buffer in bytes. Only valid if extendedFlags field has the kExtendedSoundBufferSizeValid flag set. Since the embedded SoundParamBlock contains a SoundComponentData, the kExtendedSoundSampleCountNotValid flag set refers to the sampleCount field of that record. Be aware that the embedded SoundComponentData’s flags field should never have its kExtendedSoundData flag set. This would mislead a client passed only a pointer to the SoundComponentData to misinterpet it as an extended record. An ExtendedSoundParamBlock can be passed to the sound component’s SoundComponentPlaySourceBuffer routine. Also, the moreRtn of the SoundParamBlock may return a reference to an ExtendedSoundParamBlock. In both cases, check that the record is extended before interpreting the extended fields. ExtendedScheduledSoundHeader 1 The extended forms of the SoundComponentData and SoundParamBlock records are all with which a sound decompressor implementer need be concerned. 92 Apple Sound.h Updated RELEASE 1.0 What’s New in QuickTime 4.1 However, to allow for the passing of these extended fields to the sound channel, a new flavor of ScheduledSoundHeader is introduced. This is called an ExtendedScheduledSoundHeader. Like the ScheduledSoundHeader, this record is passed as a parameter to the scheduledSoundCmd sound command. Note The ScheduledSoundHeader and scheduledSoundCmd are available with Sound Manager 3.3 or later and when QuickTime is installed. By way of quick review, ScheduledSoundHeader is defined like this: struct ScheduledSoundHeader { SoundHeaderUnion u; long flags; short reserved; short callBackParam1; long callBackParam2; TimeRecord startTime; }; typedef struct ScheduledSoundHeader ScheduledSoundHeader; typedef ScheduledSoundHeader * ScheduledSoundHeaderPtr; and consists of the following fields: u A SoundHeaderUnion used to pass the audio to the channel. flags A set of flags previously defined to be one of the following: kScheduledSoundDoScheduled = 1 << 0 If set, this indicates that the startTime field holds the time when this buffer should be played. kScheduledSoundDoCallBack = 1 << 1 If set, this means the callback should be called when the buffer completes. This typically is used to chain buffer playback together. reserved Reserved. Set to 0. callBackParam1 callBackParam2 Sound.h Updated 93 RELEASE 1.0 What’s New in QuickTime 4.1 These two fields are passed as the parameters to the sound callback associated with the channel. startTime A TimeRecord indicating the time that the sound buffer should play. Note that this TimeRecord describes a time in the future. The sound clock associated with the channel is used to determine when it should be played. To these fields, extended fields are added. The ExtendedScheduledSoundHeader definition including both older and newer fields is shown as follows: struct ExtendedScheduledSoundHeader { SoundHeaderUnion u; long flags; short reserved; short callBackParam1; long callBackParam2; TimeRecord startTime; long recordSize; long extendedFlags; long bufferSize; }; typedef struct ExtendedScheduledSoundHeader ExtendedScheduledSoundHeader; The extended fields consist of: recordSize Holds the size of the record in bytes. Again, in the future this may grow. extendedFlags Holds the same flags in the extendedFlags as the ExtendedSoundComponentData and ExtendedSoundParamBlock records already discussed. bufferSize The buffer size in bytes. This field is not valid if the extendedFlags field's kExtendedSoundBufferSizeValid flag is clear. Finally, to determine if a ScheduledSoundHeader is an ExtendedScheduledSoundHeader, you can check for this additional flag in its flags field. kScheduledSoundExtendedHdr = 1 << 2 94 Apple Sound.h Updated RELEASE 1.0 What’s New in QuickTime 4.1 If clear, this is a classic ScheduledSoundHeader. If set, this is an ExtendedScheduledSoundHeader and at least contains the recordSize and extendedFlags fields. (It includes a bufferSize field, since this is the first version of an ExtendedScheduledSoundHeader.) Changes to QuickTime for Java 1 There are a number of changes in this release of QuickTime for Java. The primary changes include: Deprecation of AWT dependencies The addition of two new packages in the app tree: quicktime.app.event –– a new event model for QuickTime for Java classes quicktime.app.ui –– which includes a button sprite For general information about QuickTime for Java, refer to Deprecation of AWT Dependencies 1 All usage of java.awt classes outside of QTCanvas, QTImageDrawer, QTImageProducer, FullScreenWindow has been deprecated. The reasons for this deprecation are various. It was decided to factor out QuickTime for Java’s dependencies on AWT to those classes that interact directly with it and to create an abstraction layer between the core QuickTime for Java classes and any environmental requirements. It is still possible to keep the AWT-dependent methods in those classes which have used them in the past, but still have those classes load and do their work if AWT classes are not present in the runtime system. These include constructors for QDRect, QDColor, QDPoint, Track.getDimensions, FullScreen methods, and getInitialSize() in a variety of classes in the app packages. Changes to QuickTime for Java 95 RELEASE 1.0 What’s New in QuickTime 4.1 A QDDimension class has been provided which is used in those situations instead and you are strongly encouraged to support usage of this class. The changed API calls should be used instead of these deprecated methods. The existing usage of java.awt.Dimension still remains, and will be supported. This is a deprecation, not a removal: if any problems arise, they should be reported to Apple. Changes to the QTPlayer are also in effect. QTPlayer no longer implements java.awt.event listeners –– it delegates handling of events to a QTPlayerEventHandler object. This object will construct an event handler based on selection criteria defined by a QTPlayerEventHandlerMaker class which an application can register. If there are no custom event handlers for the given QTPlayer instance and the source object (for instance, a java.awt.Component), then the system will use its default event handlers, i.e., QTPlayerAWTEventHandler. This event handler can be subclassed by applications to do any custom AWT event handling if this is desirable, and then the application should register this event handler. The event handler that is made can be controlled also by the application. A New Event Model and Suite of New Classes 1 The current MouseController (and its subclasses SWController and GroupController) have been deprecated, as has the MouseResponder and Dragger. This functionality has been replaced and extended with a suite of new classes in a new package: quicktime.app.event The event package includes an event model which will be used in the future as the primary mechanism for distributing events in QuickTime for Java. It is similar in spirit to the event model that Java 1.1 adopted and the event and listener classes subclass the java.util.* event classes. Two kinds of events are provided in this release: QTMouseEvent QTActionEvent Refer to the javadoc for explanations of their usage. There are four primary QTMouseListeners: MouseButtonListener, used for press, click, and release events MouseMoveListener, used for move and drag 96 Apple Changes to QuickTime for Java RELEASE 1.0 What’s New in QuickTime 4.1 MouseEnterExitListener, used for enter and exit events related to a quicktime.app.spaces.Space (not the awt.Component) MouseTargetListener, used for enter and exits of members of a space. New Mouse Controllers 1 There are two mouse controllers (which implement the ListenerController interface): QTMouseController. This controller dispatches mouse events that occur in relation to the space it is attached to. It has no concern about members or events associated with particular members in that space. QTMouseTargetController. This controller dispatches mouse events in relation to selected or targeted members in the space it is attached to. The application attaches a mouse controller to a space and then adds event listeners to the controller. Event listeners can be chained, and only those listeners that are attached will determine the kinds of events that the application is interested in. The QTMouseTargetController is also a collection. It either deals with all of the members of the space it is attached to (wholespace == true) or only those members that have been explicitly added to the controller itself (wholespace == false). As such, this controller represents a logical collection of members that the application wishes to control –– in a sense, as a group. Your application can add any number of listeners to such controllers and filter the activation of the listener based on the state of the modifier keys when the event was generated. If there are no particular logical groups of members, then a single target controller with alternate listeners that are activated appropriately for the different behaviors required can be created. New DragAdaptor and TranslateMatrix Classes 1 The DraggingSprites sample code has been rewritten to support the new controllers; other SDK examples will also be rewritten. There are new classes in the quicktime.app.actions package. To support the dragging behavior previously provided, a DragAdaptor class and a TranslateMatrix class are provided. The dragging support has been enhanced to support the new event model. Changes to QuickTime for Java 97 RELEASE 1.0 What’s New in QuickTime 4.1 DragAction is a new class that is a DragAdapter and uses TranslateMatrix, which is a subclass of a generic TransformMatrix class. TransformMatrix provides a general service to applications wishing to provide custom matrix manipulations. More specifically, TransformMatrix provides an uniform means of applying matrix transformations to a quicktime.app.image.Transformable object. It possesses a number of settings for constraints testing and provides a dual mechanism for usage in both a time-based repetitive transformation (such as the BounceAction usage) as well as user-based transformations (such as dragging). The DraggingSprites sample code in the SDK (which also defines a time-based RotateMatrix class as well as a user-based ScaleMatrix class) has been re-written to support this new mechanism and provides a useful service in applying matrix transformations. The quicktime.app.ui Package 1 The current offering in the quicktime.app.ui packages is minimal. More feedback is needed on the kinds of capabilities that would be useful for the framework to provide. The design philosophy of QuickTime for Java is to provide as much as possible with a well-factored and high-granularity object definition. This makes both the customization of different aspects of a process easier, as well as exposing the transparency of the process. New QTButton Sample Code 1 There is new sample code in the QuickTime for Java SDK QTButton, which demonstrates its usage. The main intention of this example, as with many of the SDK examples, is to demonstrate functionality and how-to-do things. Support for QuickTime 4 APIs 1 QuickTime for Java contains support for these APIs in QuickTime 4: FlashMedia extensions to GraphicsImporter and GraphicsExporter. With the exception of SoundManager APIs, this bring QuickTime for Java up to date with the QuickTime 4 API set. Completion of the Sound Manager representation will occur in the near future. There is a new StdQTConstants4 file, which contains new constants that have been added since QuickTime for Java 3. 98 Apple Changes to QuickTime for Java RELEASE 1.0 What’s New in QuickTime 4.1 There is a new API/Interface in the quicktime.qd package, and the SetGWorld class has been deprecated. SetGWorld was used to set a port as current for operations such as recording picts, polygons, and regions –– in a particular, QDGraphics (GWorld/CGrafPort). However, particularly on the Mac OS, there are some situations where this cannot be guaranteed for the duration (until the mySetGWorld.reset() method is called). Thus, a QDDrawer interface in the quicktime.qd package and QDGraphics.beginDraw (QDDrawer d) call has been added to QDGraphics. The port and device will remain set for the duration of the QDDrawer.draw call that is called by this begin draw method. In those recording operations, you must use this method to ensure correct and expected behaviour. For other operations where your code is doing a great deal of drawing on a given QDGraphics, this can also be an efficient way of doing this, as the global context of port and device remains set for the duration of this call. The createPict sample code in the QuickTime for Java SDK contains an example usage of this call. Note There is also an export call on the QTImageDrawer class, owing to recent developer feedback about translating a java.awt.Image to some kind of QT image (like a PICT). This method is provided as a means to accomplish this. New Additions 1 The following additions are new: setLabel (Sting) String getLabel() on the TwoDSprite class. The action command for the button will pass in the label of the button, but the label is also useful for more generic usage. Support for Text Drawing 1 There is now support for text drawing APIs on QDGraphics. This gives the capability to use some minimal but useful text drawing services from QuickTime on both platforms. There a few methods that have been added to the Changes to QuickTime for Java 99 RELEASE 1.0 What’s New in QuickTime 4.1 QDGraphics class that support simple text rendering. The SDK contains an example of the usage of these API services. There are miscellaneous additions to the ComponentDescription class to return more information about loaded components. Additions to the set and get info calls on the SPBDevice class in the quicktime.sound package, with provision of support for device selection in the SGSoundChannel of the sequence grabbing services. AppleScript Support 1 With QuickTime 4.1, you can use AppleScript to automate movie playback, conversion, and editing using QuickTime Player. This introduces a number of new capabilities. For example, using simple AppleScript commands you can open a movie and tell it to play for a specific duration automate the conversion of movies from one format to another batch process movie export (automate hinting of movies for streaming, for example) play a movie from a URL script playback of movies with control over size, rate, volume, balance, and looping. automate annotation of movies inventory movie contents (number of tracks, files used, annotations) adjust track playback properties such as start time, volume, and layer To learn more about AppleScript, refer to QuickTime Player Standard Suite terms 1 The Standard Suite of AppleScript terms are supported by most applications. With QuickTime Player, they function as described here. Each section below describes a command briefly, provides its dictionary entry, and gives a short example. 100 Apple AppleScript Support RELEASE 1.0 What’s New in QuickTime 4.1 Note AppleScript convention is that commands, classes, and parameter names are designated in bold. The close command 1 The close command, from the QuickTime Player dictionary, has two optional parameters: saving and saving in. Close with saving closes the object and automatically saves with the existing name ("yes"), ignores changes ("no"), or asks whether and where to save the changed object. Close with saving in closes the object and saves it with the supplied "alias". close: Close a movie or window close reference -- the movie or window to close [saving yes/no/ask] -- specifies whether changes should be saved before closing [saving in alias] -- the file in which to save the movie For example: tell application "QuickTime Player" close movie ¬ "Sample Movie" saving in ¬ "Macintosh HD:Desktop Folder:Sample Movie.mov" end tell The count command 1 The count command counts the number of elements in a QuickTime Player object. count: Return the number of elements of a particular class within an object count reference -- the object whose elements are to be counted each type class -- the class of the elements to be counted Result: integer -- the number of elements For example: AppleScript Support 101 RELEASE 1.0 What’s New in QuickTime 4.1 tell application "QuickTime Player" count every track of movie ¬ "Sample Movie" end tell Result: 2 The exists command 1 The exists command verifies that an object exists. exists: Verify if an object exists exists reference -- the object in question Result: boolean -- true if it exists, false if not For example: tell application "QuickTime Player" tell movie 1 if exists track "Video Track" then export to file¬ Macintosh HD:Desktop Folder:Sample Movie.pict" as¬ picture end tell end tell The open command 1 The open command opens a file or list of files. open: Open the specified file(s) open reference -- list of files to open For example: tell application "QuickTime Player" open file "Macintosh HD:QuickTime™ Folder:Sample Movie end tell 102 Apple AppleScript Support RELEASE 1.0 What’s New in QuickTime 4.1 Note If you specify a single file to open, it replaces the current movie within the window. In special cases, if you open multiple movies, the first movie respects that setting; all successive movies will open up in their own window. The print command 1 The print command sends a movie or list of movies to the printer for printing. print: Print the specified movie(s) print reference -- list of movies to print For example: tell application "QuickTime Player" print movie "Sample Movie" end tell The quit command 1 The quit command closes all open files and quits QuickTime Player. The quit command has an optional parameter saving that specifies whether and how changes should be saved prior to quitting. quit: Quit an application program quit [saving yes/no/ask] -- specifies whether changes should be saved before quitting For example: tell application "QuickTime Player" quit end tell The save command 1 The save command, from the QuickTime Player dictionary, has two optional parameters: "in" and "as." AppleScript Support 103 RELEASE 1.0 What’s New in QuickTime 4.1 save: Save a movie save reference -- the movie to save [in alias] -- the file in which to save the movie [as self contained] -- the desired type of the file For example: tell application "QuickTime Player" save movie ¬ "Sample Movie" in ¬ "Macintosh HD:DeskTop Folder:FileFlattened.mov" as¬ self contained end tell QuickTime Player Suite terms 1 The QuickTime Player Suite terms are unique AppleScript commands for operating on QuickTime movies. Each section below describes a command briefly, provides its AppleScript dictionary entry, and gives a short example. The can export command 1 The can export command determines whether a particular movie can be exported in a particular format. If a movie can be exported, the result is true. If the movie cannot be exported, the result is false. can export: Determine if a particular export can be performed can export reference -- the movie to export as AVI/BMP/DV Stream/FLC/hinted movie/image sequence/picture/QuickTime Movie/AIFF/System 7 sound/wave/MuLaw/standard MIDI/text file -- the desired file type Result: boolean -- is the export supported 104 Apple AppleScript Support RELEASE 1.0 What’s New in QuickTime 4.1 For example: tell application "QuickTime Player" tell movie "QuickTime 4 Sample Movie" if can export as AIFF then export to ¬ "Macintosh HD:Desktop Folder:Sample Movie.aiff" as AIFF end tell end tell Result: true The export command 1 The export command can be used in several different ways. For example: to save a movie to another file in a different format. to “mix down,” i.e., to combine multiple audio and video tracks into a single audio and video track, respectively. to hint a movie for streaming playback. Also, for example, if you need to stream a movie, you can automate the process of exporting a hinted movie using the export command. export: Export a movie to a file export reference -- the movie to export to alias -- the destination file as AVI/BMP/DV Stream/FLC/hinted movie/image sequence/picture/QuickTime movie/AIFF/System 7 sound/wave/MuLaw/standard MIDI/text file -- the desired file type [using default settings/most recent settings] -- the export settings to use [using settings preset string] -- the name of the export settings preset to use AppleScript Support 105 RELEASE 1.0 What’s New in QuickTime 4.1 For example: tell application "QuickTime Player" activate -- prompt the user to choose a movie file to open set this_movie to choose file of type ¬ "MooV" with prompt "Pick a movie to export as hinted:" -- open the chosen file open this_movie -- get the name of the movie set the movie_name to the name of movie 1 try -- check to see if the opened movie can be exported if (can export movie 1 as hinted movie) is true then -- prompt the user for a name and location set the new_file to ¬ new file with prompt "Enter a name and choose a¬ location for the new file:" default name ¬ movie_name -- export the movie as hinted movie export movie 1 to new_file as hinted movie ¬ with default settings -- close the movie close movie 1 else error "The movie “" & the movie_name & "”¬ cannot be exported as a hinted movie." end if on error error_msg 106 Apple AppleScript Support RELEASE 1.0 What’s New in QuickTime 4.1 beep display dialog error_msg buttons {"Cancel"}¬ default button 1 end try end tell The find command 1 The find command locates text strings inside movie files that have a text track. If "backwards" is not used, find assumes search is forward. find: find text in the movie find reference -- the movie to search [text string] -- The text to search for [backwards boolean] -- perform the search backwards? Result: integer -- the time at which the text is found For example: tell application "QuickTime Player" tell first movie find text "growth" find text "growth" with backwards end tell end tell The open location command 1 The open location command fetches and plays a movie or list of movies from the supplied URL. Note The getURL command performs the same function as "open location" and is supported for backward compatibility. AppleScript Support 107 RELEASE 1.0 What’s New in QuickTime 4.1 open location: Play the specified internet location(s) open location reference -- list of internet locations to open For example: tell application "QuickTime Player" open location¬ "rtsp://www.mywebsite.com/streamingmovie.mov" end tell The play command 1 The play command plays the movie supplied in the reference at the preferred rate. play: Play a movie play reference -- the movie to play For example: tell application "QuickTime Player" play first movie end tell The present command 1 The present command performs the same function as the Present Movie command in the File menu. present: Present a movie present reference -- the movie to present [scale half/normal/double/screen/current] -- the scale at which to present the movie For example: tell application "QuickTime Player" present movie "QuickTime 4 Sample Movie" scale double end tell 108 Apple AppleScript Support RELEASE 1.0 What’s New in QuickTime 4.1 The rewind command 1 The rewind command rewinds the movie back to the beginning. rewind: Rewind a movie to the beginning rewind reference -- the movie to rewind For example: tell application "QuickTime Player" rewind first movie end tell The select command 1 The select command selects a portion of the movie. select: Select a range of time select reference -- the movie whose selection is to be set [at integer] -- starting time of the selection [to integer] -- end time of the selection For example: tell application "QuickTime Player" select movie¬ "Sample Movie" at 500 to 1200 end tell The select all command 1 The select all command selects the entire movie from beginning to end. select all: Select the entire movie select all reference -- the movie to select For example: tell application "QuickTime Player" select all movie "Sample Movie" AppleScript Support 109 RELEASE 1.0 What’s New in QuickTime 4.1 end tell The select none command 1 The select none command causes no part of the movie to be selected. select all: Set the selection of the movie to nothing select none reference -- the movie to select For example: tell application "QuickTime Player" select none movie "Sample Movie" end tell The step backward command 1 The step backward command steps the movie backward by the increment specified. If no increment is specified, the movie is rewound one step. step backward: Move the current time backward step backward reference -- the movie to step [by small integer] -- number of steps For example: tell application "QuickTime Player" step backward movie "Sample Movie" by 10 end tell The step forward command 1 The step forward command steps the movie forward by the increment specified. If no increment is specified, the movie is advanced one step. step forward: Move the current time forward step forward reference -- the movie to step [by small integer] -- number of steps 110 Apple AppleScript Support RELEASE 1.0 What’s New in QuickTime 4.1 For example: tell application "QuickTime Player" step forward movie "Sample Movie" by 10 end tell The stop command 1 The stop command stops a movie that is playing. stop: Stop a movie stop reference -- the movie to stop For example: tell application "QuickTime Player" stop movie "Sample Movie" end tell QuickTime Player Classes 1 Each class represents a range of expressions for use as references with terms and commands. Note In the class dictionary definitions, "read-only" is expressed as [r/o]. The annotation class 1 Using the annotation class you can specify and retrieve information about the movie, such as its author, director, artist, comments, copyright information, sources, and playback requirements. An annotation can be specified by index, such as first annotation or annotation 3 name, such as "Author" or "Copyright" ID, such as ''©aut'' (author) or ''©cpy'' (copyright) Note: To produce the copyright (©) symbol, press option-G. AppleScript Support 111 RELEASE 1.0 What’s New in QuickTime 4.1 For the full list of standard annotations, see the annotation info panel in the Pro version of QuickTime Player. Only movie annotations are currently supported. Class annotation: An annotation in a QuickTime movie Plural form: annotations Properties: class type class [r/o] -- the class name international text [r/o] -- the name of the annotation ID string [r/o] -- the kind of the annotation full text international text -- the text of the annotation Some examples of how you would use various properties of the "annotation" class: -- get name of annotation -- get the name of the first annotation get the name of every annotation -- get full text of annotation get the full text of second annotation get the full text of annotation "Copyright" -- set full text of annotation set the full text of first annotation to "My first annotation" set the full text of annotation "Author" to "John Q. Author" -- count all annotations -- count every annotation 112 Apple AppleScript Support RELEASE 1.0 What’s New in QuickTime 4.1 Advanced Tip: To delete an annotation, set its ID text to an empty string (""). To create an annotation by name or id, simply set its full text to a non-empty string. The application class 1 The application class is your starting point for scripting movies with QuickTime Player. This class provides access to movies, windows, and favorites, user preferences, and basic information about current QuickTime settings. You can tell this class to open a movie file, ask how many movies are currently open, or request a particular movie by name or index. Class application: The QuickTime Player application program 1 Plural form: applications Elements: movie by numeric index, by name window by numeric index, by name favorite by numeric index, by name Properties: class type class [r/o] -- the class name string [r/o] -- the name frontmost boolean [r/o] -- Is this the frontmost application? version version [r/o] -- the version number of the application play sound in background boolean -- should sound of background movies be played? only front movie plays sound boolean AppleScript Support 113 RELEASE 1.0 What’s New in QuickTime 4.1 -- should only sound of front movie be played? play movie from beginning when opened boolean -- should movies auto-play when opened? ask before replacing items in drawer boolean -- Should alert be displayed when replacing a favorite? open movies in new player boolean -- Should movies be opened in separate windows? QuickTime version version [r/o] -- the version of the installed QuickTime QuickTime language international text [r/o] -- the language of the installed QuickTime QuickTime connection speed 14.4 Modem/28.8/33.6 Modem/56K Modem/ISDN/112K Dual ISDN/T1/Intranet/LAN [r/o] -- the current connection speed (set in the QuickTime Control Panel) QuickTime Pro installed boolean [r/o] -- is the pro version of QuickTime installed? Some examples of how you would use various properties of the application class: -- get all movies -- get every movie -- get all windows -- get every window -- get all favorites -- get every favorite -- get class of app -- get class of application "QuickTime Player" 114 Apple AppleScript Support RELEASE 1.0 What’s New in QuickTime 4.1 -- get app name -- get name of application "QuickTime Player" -- is app frontmost? -- get frontmost of application "QuickTime Player" -- get app version -- get version of application "QuickTime Player" -- setting preferences -- set play sound in background of application "QuickTime Player" to false set only front movie plays sound of application "QuickTime Player" to false set play movie from beginning when opened of application "QuickTime Player" to false set ask before replacing items in drawer of application "QuickTime Player" to false set open movie in new player of application "QuickTime Player" to false The favorite class 1 The favorite class provides access to the items in the favorites drawer. You can use this class to get the name of every favorite or open a particular favorite. Favorites can be specified by index or name. Class favorite: A reference to a QuickTime movie. Plural form: favorites Properties: class type class [r/o] -- the class name string -- the name of the favorite AppleScript Support 115 RELEASE 1.0 What’s New in QuickTime 4.1 kind file/internet location [r/o] -- the kind of the favorite. Some examples of how you would use various properties of the favorite class: -- opening favorites -- open favorite "Disney" open favorite 4 open fourth favorite -- get name of favorite -- get the name of the 3rd favorite in application "QuickTime Player" -- get favorite kind get the kind of the 3rd favorite in application "QuickTime Player" The file class 1 QuickTime movies stored on a local disk store their content in one or more files. If the movie uses more than one file, it may not play back correctly when it is copied to another computer unless its associated files––dependencies––are copied also. You can use the file class to determine which files a movie is dependent on. If the movie uses only one file and its name matches the filename of the open movie, the movie is self-contained (has no dependencies) and can be safely copied to other computers or the Internet for playback. Class file: A movie file Plural form: files Properties: class type class [r/o] -- the class name international text [r/o] -- the name of the file 116 Apple AppleScript Support RELEASE 1.0 What’s New in QuickTime 4.1 Some examples of how you would use various properties of the file class: -- get name of file -- get the name of the first file get the name of every file -- count all annotations -- count every file The internet location class 1 QuickTime movies intended for streaming or use on the Internet can have one or more internet locations or URLs. Some examples of internet locations are The movie class 1 The movie class is the central class in the QuickTime Player Suite. Most of the QuickTime Player suite events target a movie, including play, stop, save, export, AppleScript Support 117 RELEASE 1.0 What’s New in QuickTime 4.1 and find. Tracks, files, internet locations, windows, and annotations are all parts of a movie. This class provides access to many useful properties of a movie, such as name, current time, duration, volume, selection, and dimensions. Many of these properties can be set, such as current time, selection, volume, and dimension. Class movie: A QuickTime movie. Plural form: movies Elements: track by numeric index, by name file by numeric index, by name internet location by numeric index window by numeric index, by name annotation by numeric index, by name Properties: class type class [r/o] -- the class name international text [r/o] -- the name of the movie current time integer -- the current time (can be set by name as well as number) duration integer [r/o] -- the duration of the movie selection start integer -- the start of the movie selection selection end integer -- the end of the movie selection 118 Apple AppleScript Support RELEASE 1.0 What’s New in QuickTime 4.1 rate small real -- the rate at which the movie is currently playing playing boolean [r/o] -- is the movie playing? done boolean [r/o] -- is the movie done playing? auto play boolean [r/o] -- will the movie automatically start playing? sound volume small integer -- the sound volume of the movie. [0..384], where 256 is 100 percent. Note that a range of 0 to 150 percent is supported. muted boolean -- is the volume muted? dimensions point [r/o] -- the current dimensions of the movie, not including the controller natural dimensions point [r/o] -- the dimensions the movie has when it is not scaled looping boolean -- keep playing the movie in a loop? palindrome boolean -- loop back and forth? play selection only boolean -- whether to play the selection only? play all frames boolean -- play every frame? (no audio will play) scale half/normal/double/screen/current -- the current scale of the movie AppleScript Support 119 RELEASE 1.0 What’s New in QuickTime 4.1 poster frame time integer -- the time of the poster frame for the movie time scale integer [r/o] -- the time scale of the movie close when done boolean -- close the movie when it is done playing quit when done boolean -- quit the application when this movie is done playing? modified boolean [r/o] -- has the document been modified since the last save? language international text [r/o] -- the current language of the movie Some examples of how you would use various properties of the movie class: -- get class of movie -- get class of movie 1 -- get movie name -- get name of movie 1 -- get current time of movie -- set x to current time of movie 1 x / 600 -- in seconds if 600 is movie time scale -- get duration of movie -- set x to duration of first movie get duration of movie 1 -- get movie rate -- (movie has to be playing) get rate of movie 1 -- get playing of movie (is movie playing?) -- get playing of movie 1 120 Apple AppleScript Support RELEASE 1.0 What’s New in QuickTime 4.1 -- set the playing of movie -- set playing of movie 1 to true -- is movie done? -- get done of movie 1 -- is AutoPlay on? -- get auto play of movie 1 -- get volume of movie -- get volume of front movie -- is movie muted? -- get muted of front movie -- get movie data size (in kbytes) set x to movie data size of front movie x / 1024 -- get/set movie dimensions -- get dimensions of front movie set dimensions of movie 1 to {320,240} -- set looping of movie -- set looping of movie 1 to true -- set palindrome of movie -- set palindrome of movie 1 to true -- set 'Play Selection only' of movie -- set play selection only of movie 1 to true -- set 'Play all frames' of movie -- set play all frames of movie 1 to true -- set scale of movie -- set scale of movie 1 to double (half, screen) -- get/set poster frame of movie -- AppleScript Support 121 RELEASE 1.0 What’s New in QuickTime 4.1 set poster frame of movie 1 to 88 -- get time scale of movie -- get time scale of movie 1 -- set selection of movie -- tell first movie to select at 422 duration 800 -- select all of a movie -- tell first movie to select all -- has movie been modified? -- get modified of movie 1 The track class 1 QuickTime stores data separately in tracks. Tracks indicate what kind of data a movie contains. Examples of track types include video, audio, and text. The track class provides access to useful information about a track, such as name, kind, start time and duration. Some properties can be set, such as name, and enabled (which determines whether a specific track plays when the entire movie plays). Class track: A track in a QuickTime movie. Plural form: tracks Properties: class type class [r/o] -- the class name international text [r/o] -- the name of the track start time integer -- the time delay before this track starts playing duration integer [r/o] -- The duration of the track 122 Apple AppleScript Support RELEASE 1.0 What’s New in QuickTime 4.1 kind string [r/o] -- the kind of media in the track dimensions point -- the current dimensions of the track natural dimensions point [r/o] -- the dimensions the track has when it is not scaled enabled boolean -- should this track be used when the movie is playing? id integer [r/o] -- the unique identifier for this track layer small integer -- the layer of the track language international text -- the language of the track visual characteristic boolean [r/o] -- can the track be seen? audio characteristic boolean [r/o] -- can the track be heard? sound volume small integer -- the volume of the track [0..255], where 256 is 100 percent sound balance small integer -- the balance of the track [-127..128], where negative is left, 0 is center, and positive is right Some examples of how you would use various properties of the track class: -- set track name -- set name of track 1 of movie 1 to "hip cats" -- set enabled of track -- set enabled of track 1 of first movie to false AppleScript Support 123 RELEASE 1.0 What’s New in QuickTime 4.1 -- get enabled state of all tracks -- get enabled of tracks of movie 1 -- set track dimensions -- set dimensions of track 1 of movie 1 to {320, 240} -- get the track data size -- get the track data size of track 1 of movie 1 get the track data size of tracks of movie 1 -- get name of tracks -- get name of tracks of movie 1 -- get natural dimensions of track-- get the natural dimensions of track 1 of movie 1 -- get id of track -- get the id of track 2 of movie 1 -- get layer of track -- get the layer of track 2 of movie 1 -- get visual characteristic of track (is it visible)-- get the visual characteristic of track 2 of first movie -- get audio characteristic of track (is it audible)-- get the audio characteristic of track 2 of first movie -- if audio track, get balance if audio characteristic of track 2 of movie 1 is true then get the volume of track 2 of movie 1 -- set start time of track -- set start time of track 1 of movie 1 to 600 -- get track kind -- get track kind of track 2 of movie 1 -- get track duration (as seconds if time scale is 600) 124 Apple AppleScript Support RELEASE 1.0 What’s New in QuickTime 4.1 set x to duration of track 2 of movie 1 set result to x / (time scale of movie 1) Note that if you use (time scale of movie 1), then this becomes the generalized expression for time in seconds. The window class 1 A QuickTime movie is displayed in a window. You use the window class to set the location of the window in which a movie is displayed. Many operations that can be performed on a movie can also be performed on a window, such as save and close. Class window: A window Plural form: windows Elements: movie by numeric index, by name Properties: class type class [r/o] -- the class name international text [r/o] -- the title of the window bounds bounding rectangle [r/o] -- the boundary rectangle for the window position point -- the upper left coordinates of the window index integer [r/o] -- the number of the window Here are some examples of how you'd use various properties of the window class: -- set window position -- AppleScript Support 125 RELEASE 1.0 What’s New in QuickTime 4.1 set the position of the front window to {200, 222} -- get the windows bounds -- get the bounds of the front window -- get window index -- get the index of the second window -- get name window (all windows) -- get the name of the first window get the name of every window -- count all open movies -- count every movie 126 Apple AppleScript Support APPENDIX A Figure A-0 Listing A-0 Document Revision History A Table A-0 The following are changes from the Preliminary release of this document on January 14, 2000 to this current Release 1.0: Table A-1 QuickTime 4.1 revision history Version Notes January 2000 Added a description of "attach-timebase", (page 1-18) Added a new section on support for data URLs, (page 1-33) Added a new section on URLs in text tracks, (page 1-35) Added a new section on support for new embed tags, (page 1-35) Expanded section on cookie support, (page 1-42) Replaced Figure 3, (page 1-46) Added a new section on Custom Wired Actions, (page 1-55) Added a new section on sample JavaScript usage with code listing, (page 1-75) 127 APPENDIX A Document Revision History 128
Calling an object (indexed in the document "embeds" array by index) method directly
javascript:document.embeds[0].Play()
Calling an object (indexed in the document "embeds" array by name) method directly
javascript:document.embeds['movie1 ].Play()
javascript:document.embeds['movie1' ].Stop()
javascript:document.embeds['movie2' ].Play()
javascript:document.embeds['movie2' ].Stop()