Enhancements

• Support for ISO-compliant MPEG-4 video and audio, both encode and decode. Developers, authors, and multimedia producers can now create and play back MPEG-4 video content, as well as MPEG-4 audio encoded using Advanced Audio Coding (AAC). Discussed in the section Support for MPEG-4.

• QuickTime 6 also supports use of the MPEG-4 video and AAC audio codecs in QuickTime movies. In many cases, you can choose to create either a native .mp4 file or a QuickTime .mov file using MPEG-4 compression. This allows you to mix MPEG-4 audio and video with other QuickTime media, such as VR panoramas, sprites, or Flash tracks. Discussed in the section MPEG-4 and Web Developers.

• A new group of MPEG-4 settings dialogs in QuickTime Player that enable QuickTime Pro users who work with MP4 files to make a number of adjustments in video and audio tracks, streaming and compatibility. Discussed in the section Working with MPEG-4 Files.

• A new video codec for MPEG-4 video compression. The new codec is ISMA compliant and conforms to the Profile 0 standard of the MPEG-4 specification, with an extremely low data rate of 64 Kbits/second. The advantage that this new codec offers is interoperability with other systems. Interoperability is the primary goal of the new codec. Discussed in the section New Video Codec for MPEG-4.

• A new MPEG-4 audio codec that plays audio files of AAC and handles ISMA profile levels 0 and 1. In the current release both encode and decode are supported. Discussed in the section MPEG-4 Audio Support.

• Support for native MPEG-4 streaming. Standard hinted MPEG-4 files (.mp4) can be served directly, without converting to QuickTime Movie (.mov) files. Discussed in the section Native MPEG-4 Streaming.

• A new, RTSP Instant-On enhancement to QuickTime streaming that provides near instantaneous start of streamed movies when the available network bandwidth significantly exceeds the data rate of the target media. Discussed in the section RTSP Instant-On Enhancement to Streaming.

• Support for JPEG 2000, a high-quality, still-image compression and coding standard that uses state of the art compression techniques based on wavelet technology. Note that JPEG 2000 support is only provided on Mac OS X in the current release of QuickTime 6. Discussed in the section JPEG 2000 Support.

• New and updated components related to Macromedia Flash 5 support in QuickTime. The Flash media handler and the Flash movie importer have been updated, and a new Flash Properties panel has been added to the QuickTime Player info panels. Discussed in the section Flash 5 Support.

• A new QuickTime tasking mechanism and new APIs to handle idling of applications. Discussed in the section New APIs for Tasking QuickTime.

• A new Carbon Movie Control mechanism for Mac OS X that makes the process of using QuickTime within a Carbon Event-based application easier and faster. Discussed in the section New Carbon Movie Control.

• A new group of Sprite APIs, as well as a number of new wired actions and operands. Discussed in the section Sprite API Changes.

• Support for writing and using variable bitrate (VBR)-enabled sound compressor components. Both the QuickTime Movie exporter component available in the export dialog (also known as the ConvertMovieToFile API dialog) and the Standard Sound compression dialog component have been updated to use and recognize VBR compressor components. Discussed in the section VBR Sound Compression Support.

• A new API that provides tween components with an interrupt-safe interface. Discussed in the section New Tween Component API.

• New, enhanced effects dialogs. Effects may choose to implement custom controls to allow the user to more easily edit complex parameters that are ill-served by simple sliders or type in boxes. Effects may allow a custom control for either a single parameter, or for a group of parameters. Discussed in the section Changes to Effects Dialog.

• A new improved None codec (also known as the Raw codec) that replaces the previous None codec with a more complete implementation. Discussed in the section None Codec Enhancements.

• Support for Exif JPEGs and Exif TIFFs, including support for thumbnails, which was previously only available in QuickTime 5 on Mac OS X 10.1, and is now available for QuickTime on Mac OS 9 and Windows. Discussed in the section Additional Still Image Metadata Support in Mac OS 9 and Windows.

• New QuickTime data handler-aware APIs that make using Apple and custom data handlers easier for third-party developers. Discussed in the section Improved Movie Toolbox Support for Data Handlers.

• New UserData APIs that can be useful in copying information from one UserData container to another (page 152).

• Support for a number of new features and enhancements in QuickTime for Java, including support for JDK 1.4 (Windows only), and the introduction of the JQTCanvas class, a new lightweight version of the QTCanvas class which supports scaling of Flash content. Discussed in the section QuickTime for Java Enhancements.

• A new, improved sequence grabber user interface which includes new settings available on all platforms. A new group of Sequence Grabber APIs are also included in QuickTime 6. Discussed in the sections New Sequence Grabber User Interface and New Sequence Grabber APIs.

• New Image Compression APIs that allow compressors to supply the User Interface for their options within the compression dialog (page 183), as well as new Image Decompression Manager APIs (page 188).

• New media handler calls that developers can use to write media handlers that support keyboard focus. If you want to add interactive capabilities to your application, you need to use these media handler calls. Discussed in the section New Media Handler APIs For Keyboard Focus.

• New APIs that provide a mechanism for preflighting operations on QuickTime content that may be restricted. Discussed in the section New QuickTime Restrictions APIs.

• New APIs for better controlling memory usage in movies in Mac OS X (page 203).

• Miscellaneous enhancements to QuickTime VR, and an additional movie errors API (page 205).

• A new XML exporter––Export to QuickTime Media Link––which creates a small XML file that contains the URL of a movie, as well as other user settings. Discussed in the section New XML Exporter.

• JavaScript support for ActiveX controls, Netscape 6 and browsers based on Mozilla. This means you can now use JavaScript to control QuickTime when Web pages are viewed using Internet Explorer for Windows, or any other browser that supports the COM interface to ActiveX controls. Discussed in the section JavaScript Support for ActiveX, Netscape 6 and Mozilla.

• Support for DVCPro PAL (DV format 4:1:1) on Mac OS X (10.1.2).

Changes

• Changes to the QuickTime Player user interface. Notably, the Hot Picks movie and the Channel pane have a new layout, with channel categories on the left and a movie on the right. Discussed in the section User Interface Changes.

• Changes to AppleScript and AppleScript terminology that are new in QuickTime 6. Most notably, QuickTime Player is now a recordable application. There are also a number of new commands, classes, and properties, and well as modifications to existing terminology elements. Discussed in the section AppleScript Changes.

• Changes to the QuickTime menu in the Windows system tray, which includes a number of new menu items. Discussed in the section New QuickTime Menu in Windows.

Updates

• New documentation on how to deal with the ever-increasing number of effect components. This section documents atoms that can be used for tagging effects into useful categories. Two groupings for effects are defined here: Major Class and Minor Class. Discussed in the section QuickTime Effects Classes.

• Some effects with complex parameters would like to provide the user with groups of useful parameter values that can be easily selected. This section documents an optional mechanism that can be used by effects to define these “presets.” Discussed in the section QuickTime Effects Presets.

• New and updated documentation on QuickTime XML importers. These importers, introduced in QuickTime 5, create movies based on the contents of certain kinds of XML files saved with the .mov file extension. XML files with the .mov file extension are treated by networks and operating systems as QuickTime movies. There are importers for three XML types currently built into QuickTime: SMIL importer, QuickTime media link importer, and component preflight importer. Discussed in the section QuickTime XML Importers.

• QuickTime 6 allows you to play current Shoutcast or Icecast streams that use MP3 compression. This section Playing Shoutcast or Icecast Streams in QuickTime discusses the various features of Shoutcast and Icecast streams, as well as what you need to know in order to deliver these streams in real-time over a network.

For Web Developers

• Specific information about the different ways that you can use QuickTime 6 and MPEG-4, if you are a developer who creates websites, website authoring tools, or QuickTime movies that are intended for distribution over a network or the Internet. Discussed in the section MPEG-4 and Web Developers.

Background

In February 1998, the International Standards Organization (ISO) formally adopted the QuickTime file format as the starting point for the MPEG-4 file format, the latest in a series of standards for transmitting video and audio information. MPEG-4 differs from MPEG-1 and MPEG-2 by adopting a component-based architecture for multimedia, an approach similar to QuickTime’s architecture. Other existing standards have less flexibility and treat multimedia as just an array of picture elements.

MPEG-1 and QuickTime

MPEG-1, often simply called MPEG, is fairly common on the Web and CD-ROMs, typically with the .mpg file extension. MPEG-1 supports one kind of video compression and a few types of audio compression. MPEG-1 allows coding of moving pictures and associated audio for digital storage media at up to about 1.5 Mbit/second. The content of an MPEG file is one or more MPEG streams. Elementary audio and video streams can be multiplexed into a combined stream.

MPEG-1 was designed to provide VHS-quality video at T1 data rates (single speed, or 1x, CD-ROM). It is the basis for the video CD standard, which is little used in the United States or Europe but is popular in Asia. Most commercial DVD players can play video CDs, however, and the rapid spread of CD-R burners and DVD players is currently fueling renewed interest in this format.

QuickTime can open and play MPEG-1 video on both Windows and Macintosh (requires QuickTime 5 or later for Windows). It can then export the video to other formats using any of the QuickTime compressors. Currently, QuickTime treats the entire MPEG-1 stream as a single sample, so you cannot cut or copy part of an MPEG-1 video unless you convert it to a different compression format first.

MPEG-1 can also contain audio. The audio can be compressed in two different formats: layer 2 (often called MPEG-1 audio) and layer 3 (known as MP3). QuickTime plays both layer 2 and layer 3 audio without difficulty, including streaming MP3 such as ShoutCast. QuickTime can also play multiplexed layer 2 audio (audio and video streams combined), but it cannot export or extract layer 2 audio from a multiplexed MPEG-1 stream.

QuickTime Player does not export to MPEG-1 streams, nor does it compress audio or video using MPEG-1 compression. MPEG-1 compression can be added to QuickTime with the Heuris MPEG codec (www.heuris.com/) or with the MPEG-1 encoder included with Roxio Toast (www.roxio.com/).

MPEG-4 and QuickTime

The MPEG-4 standard was recently revised to MPEG-4 Version 2, which is the latest standardized version. (Note that amendments to Version 2 have already been added, as the standard grows and evolves.) In any case, the standard outlines file conventions and compression formats not only for audio and video, but for text and multimedia integration. Because the MPEG-4 file format is largely based on the QuickTime file format, MPEG-4 files are potentially as diverse in content as QuickTime movies. This is a rich and complex specification.

Software and hardware vendors will implement the MPEG-4 specification in stages. The parts of the specification that are implemented by a given MPEG-4 player are called a player profile.

A profile is, essentially, a grouping of technologies, defined as “tools” in MPEG terminology. Profiles are a “normative” part of the standard, in that an implementation must conform to a profile in order to claim conformance to the standard itself. Profiles are specified in such a way as to maximize interoperability.

A good example is the way in which this was applied to the MPEG-1 Audio standard. There are three layers in MPEG-1 Audio. Layer 1 has the least complexity but the lowest compression performance, while Layer 3 has the highest complexity but also the highest compression performance. Profiles that include layer 3 also typically include layers 1 and 2. In this case, interoperability is maximized because a terminal implementing a profile which includes layer 3 can decode layer 1, 2 and 3 bitstreams, while a layer 2 terminal can decode only layer 1 and 2 bitstreams and a layer 1 decoder only a layer 1 bitstream.

No one currently implements the full MPEG-4 specification. There are no widely distributed MPEG-4 video codecs. (There was a codec available for Windows Media Player called MS MPEG-4, but this was actually a proprietary Microsoft codec that was partly based on a draft specification for MPEG-4. The early version released by Microsoft was not compatible with the final standard, and has since been renamed. Microsoft has also released a standard MPEG-4 codec, but it is not in an interoperable file format.)

QuickTime’s MPEG-4 video codec focuses on low-bandwidth video for Internet delivery, with the goal of delivering near-television quality over DSL and cable modems, and reasonable quality over dialup modems.

QuickTime’s implementation of MPEG-4 is designed to be interoperable with products from other standards-compliant vendors.

A diagram of the MPEG-4 system architecture is shown in Figure 1-1. The items in bold in specific boxes indicate the various parts of the architecture that QuickTime currently supports.

MPEG-4 File Format and QuickTime

The MPEG-4 File Format (MP4), which is derived from the QuickTime File Format, is a format that is designed to store MPEG-4 data in a file. This process is outlined by Rob Koenen, chair of the MPEG-4 Requirements Group, in their document MPEG-4 Overview, which provides a brief overview of the MPEG-4 File Format, as follows:

“The MP4 file format is designed to contain the media information of an MPEG-4 presentation in a flexible, extensible format which facilitates interchange, management, editing, and presentation of the media. This presentation may be ‘local’ to the system containing the presentation, or may be via a network or other stream delivery mechanism. The file format is designed to be independent of any particular delivery protocol while enabling efficient support for delivery in general. The design is based on the QuickTime format from Apple Computer Inc.”

The diagram shown in Figure 1-2 gives an example of a simple interchange file. Note that BIFS, an acronym for Binary Format for Scene, specifies the Scene, and OD (Object Descriptor) specifies the Stream Management.

Inside the QuickTime File Format

The QuickTime file format is designed to accommodate the various kinds of data that need to be stored in order to work with digital media. Because the file format can be used to describe almost any media structure, it is an ideal format for the exchange of digital media between applications, regardless of the platform on which the application may be running.

The basic data unit in a QuickTime file is the atom. Each atom contains size and type information along with its data. The size field indicates the number of bytes in the atom, including the size and type fields. The type field specifies the type of data stored in the atom and, by implication, the format of that data.

Atom types are specified by a 32-bit integer, typically a four-character code. Apple Computer reserves all four-character codes consisting entirely of lowercase letters. Unless otherwise stated, all data in a QuickTime movie is stored in big-endian (network) byte ordering. All version fields must be set to 0, unless otherwise stated. Atoms are hierarchical in nature. That is, one atom can contain one or more other atoms of varying types.

For more detailed information, refer to the volume Inside QuickTime: QuickTime File Format (351 pp, 2.3 MB), which is available as a free download from Apple’s QuickTime API website in both HTML and PDF formats at

http://developer.apple.com/techpubs/quicktime/qtdevdocs/RM/frameset.htm

The book begins with an introduction to QuickTime atoms, then presents the structure of the QuickTime file format in detail. This is followed by a series of code examples for manipulating a QuickTime file using the QuickTime API. A series of appendixes describe some common file formats that can be contained within a QuickTime file as data. The book is intended primarily for developers who need to work with QuickTime files outside the context of the QuickTime environment.

MPEG-4 Web Resources

The home page of the Moving Picture Experts Group (MPEG), a working group of ISO/IEC in charge of the development of standards for coded representation of digital audio and video, can be found at

http://mpeg.telecomitalialab.com/

An in-depth presentation of MPEG-4 can be found at

http://www.cselt.it/mpeg/standards/mpeg-4/mpeg-4.htm

Answers to specific MPEG-4 questions can be found at

http://www.cselt.it/mpeg/faq.htm

MPEG-4 standards are in the 14496 series and the specifications can be purchased from ISO at

http://www.iso.ch

The MPEG-4 implementation forum promotes MPEG-4 and is spearheading licensing efforts at

http://www.m4if.org

The Internet Streaming Media Alliance (ISMA) is promoting a specification and integration of products around a subset of MPEG-4 over IP networks at

http://www.isma.tv

Acronyms and Terms for Understanding MPEG-4

A veritable alphabet soup of acronyms and terms has emerged in the MPEG-4 specification, a sampling of which is shown here.

How The Process Works

Typically, when you open a movie, QuickTime finds the movie atom in the file, processes it, and creates a movie object, i.e., instantiates it. When you use MP4, you have to invoke the importer. What the importer does is scan the file, find the 'moov' atom, and then conform the 'moov' atom––which is an MPEG-4-style movie atom––into a 'moov' atom that is QuickTime-style. QuickTime then creates the movie object.

In the case of exporting, where the data is already in MPEG-4 format––MPEG-4 video or audio––the exporter has QuickTime flatten the data to the file. This produces the movie atom, which points to the file. The exporter once again conforms the movie atom, which is QuickTime-style, into a movie atom which is MPEG-4-style. The exporter then writes this to the file. This is pass-thru.

For an encoding or re-encoding export, the exporter compresses and then writes the MPEG-4 data to a file, whose movie is subsequently made to conform to MPEG-4 style.

New Dialogs for Handling MP4 Files

QuickTime 6 introduces a new set of dialogs in QuickTime Player (illustrated in this section with examples from Mac OS 9 and Mac OS X) that enable end users to open MP4 files.

To work with MP4 files, end users or content authors need to perform a series of import-export operations, using QuickTime Pro. The steps are as follows:

1. Open a .mov file in QuickTime Player.

2. In the File menu, click Export.

3. A dialog appears with a list of export options. Choose Movie to MPEG-4.

4. Save the .mov to a .mp4 file.

5. The .mp4 file can now be played on any player that supports MPEG-4.

Figure 1-3 shows the dialog (in Mac OS 9) that appears when you want to save a QuickTime movie, in this case “cool sunset” to a .mp4 file. From the list of options in Export, you choose Movie to MPEG-4.

If you click the Options button in the dialog shown in Figure 1-3, the MPEG-4 Settings dialog appears, as shown in Figure 1-4. In this dialog, you can set the basic video track, the physical size of current movie, and the audio track as necessary. If Basic is selected, the video will make use of the basic settings for MPEG-4 and ensure the widest possible range of playback on MPEG-4 compatible devices.

Note that Profile 0, in the text of the dialog, is the ISMA-specified Profile 0, and not the MPEG-4 defined Profile 0. For more information about ISMA and Profile 0, refer to the section ISMA and Definitions of Profile 0.

Note that the lower portion of the dialog in Figure 1-4 contains additional description and explanation about the choices that are available to the user. Audio can be optimized for music––in this case, AAC. (Note AAC can handle a full range of music and other audio.)

In the Video settings dialog in Mac OS X shown in Figure 1-5, the end user can adjust specific settings for video, such as the number of kbits per second, or the frame rate––for example, 15 frames per second, if that is the rate desired.

Figure 1-6 shows the settings available for audio in Mac OS X––for stereo or mono encoding. If the user selects music in the basic panel, it automatically selects a high data rate and selects stereo.

Figure 1-7 shows the settings dialog for streaming, which enables the user to select the type of hinting required, as well as maximum packet size and maximum packet duration.

Figure 1-8 shows the Compatibility settings dialog in Mac OS X. By default, QuickTime produces a generic MPEG-4 stream. QuickTime does not check for any specific layer compatibility features that might be required by ISMA or other organizations. Nor does QuickTime check if the overall data rate of the MPEG-4 you’re producing is any particular data rate.

The user can select ISMA compliance, and also select the speed at which you want to stream the file––for example, at a medium data rate.

ISMA and Definitions of Profile 0

The Internet Streaming Media Alliance (ISMA) specification <http://www.isma.tv/> is aimed at producing a technical standard based on MPEG-4 for files and streaming MPEG-4 video and audio over IP networks. In that standard, a file will have one video track and one audio track, likewise for streaming tracks. The aggregate data rate cannot exceed the limit of 64 Kbits/second, which conforms to Profile 0.

As ISMA defines it:

“To be compliant with this specification a product must completely implement profile 0, and may implement additional profiles. For example, an on-demand video server would likely need to implement all possible profiles to address a wide client base. However a decoder/terminal may only support profile 0.

“This approach has been taken to ensure that any product certified as ISMA compliant, has the capability to minimally interoperate with any other ISMA compliant product.

“This is a definition of base interoperability. Vendors are still free to add additional functionality beyond that specified in this document. However that said, a conforming product cannot make any additional requirements beyond this specification to interoperate with another conforming system.”

In the specification, Profile 0 is defined this way:

“Rationale: This profile was selected to allow for video and audio at bitrates suitable that match capabilities of narrowband and mobile wireless infrastructures and to align with the patent pool work in M4IF.”

For video, this includes the following:

• REQUIRED - MPEG-4 ISO/IEC 14496-2:1999 + Cor 1:2000 + Cor 2:2001

• MPEG-4 Simple Profile @ Level 1

• Typical Visual Session Size is QCIF (176x144)

• Maximum bitrate is 64kbit/s

• ISMA Restriction: Profile 0 is limited to one (1) video object only.

Profiles and Levels Defined

A profile can be thought of as a grouping together of different algorithms, specifying what your video codec can and cannot do. A level, on the other hand, specifies how much your codec can do. A level, for example, may restrict the computational complexity within a profile, specifying the bitrate constraints on a video or audio stream. Both profiles and levels are stored within an MPEG-4 file, so that the playback device “knows” whether or not it can in fact play back the file.

Gamma Correction

In QuickTime 6, the MPEG-4 video codec performs gamma correction, so that MPEG-4 files look the same when they are displayed on both Macintosh and Windows computers. An MPEG-4 video stores both gamma and color space information, while the video codec performs per-platform gamma correction.

Additional Dialog for MPEG-4 Video Compression

Figure 1-9 shows a Compression Settings dialog in Mac OS X (available in QuickTime Player Pro) that provides MPEG-4 Video as a selectable choice for the content author or end user. The dialog also provides two selectable compression types: Faster and More Accurate.

Summary

For developers, some important points to keep in mind about QuickTime 6 support for MPEG-4:

• MP4 files can be opened by any application that uses the standard QuickTime calls.

• Any application can create MP4 files by using the standard QuickTime export calls.

• MPEG-4 codecs behave like other QuickTime codecs.

Defining AAC

The characteristics of AAC include

• Perceptual audio codec, similar to MP3

• Multichannel capability

• “Indistinguishable” audio quality––that is, you can take an encoded file and the source from the encoded file and you should not be able to tell the difference over a stereo system. From a CD source:

  • AAC Low Complexity requires 96 kbps per channel.

  • MP3 requires at least 128 kbps per channel.

QuickTime AAC Encoder

The characteristics of the QuickTime AAC encoder include

• AAC-Low Complexity

• Acceptable source

  • 44.1 kHz or 48 kHz. It is recommended that when encoding audio, your source should be an even multiple of those numbers.

  • Mono or stereo

• Output

  • Mono: 16 to 256 kbps

  • Stereo: 16 to 256 kbps

  • The sample rate is automatically scaled to the bitrate.

Table 1-1 is a mapping of the input sample rate + output bitrate + output number of channels to output sample rate.

You are best advised to provide content in these sample rates, regardless of the target bitrate. If you already have content in a different sample rate, however, it is not a problem. QuickTime will perform the necessary Sample Rate conversion.

Ways To Use MPEG-4 In QuickTime

There are three different ways you can use MPEG-4 in QuickTime.

1. You can create QuickTime movies (.mov) that use the MPEG-4 video and/or audio codecs. These are not .mp4 files, and MP4 players will not play them. They are QuickTime movies and they require QuickTime 6 or later to play.

2. You can create MPEG-4 files (.mp4) that are ISO-compliant. These are MP4 files. They are not QuickTime movies. All ISO-compliant players should be able to play these files with no difficulty. QuickTime Player is an ISO-compliant player and can play ISO-compliant MP4 files created on any platform.

3. You can create MPEG-4 files (.mp4) that are not ISO-compliant. These MP4 files may not play on other MP4 players, but they will play in QuickTime 6. (For more information about issues involving ISO compliance, see the section ISO Compliance.)

QuickTime 6 allows you to create both fast-start and streaming versions of your movies in both .mov and .mp4 format. Movies that use MPEG-4 codecs can be hinted for streaming, exported to .mp4 files, or both, without recompressing the audio or video.

Why Use MPEG-4 On The Web?

MPEG-4 is an ISO standard supported by a wide range of companies in a variety of industries, as discussed in the section Support for MPEG-4. This means that an MPEG-4 file can be played by many different players in addition to QuickTime, not only on personal computers, but also on cell phones, PDAs, and television set-top boxes. This is a huge step forward from the current proprietary environment, which may lead you to deliver your movies using different compressors and multiple formats––such as Real, Windows Media, and QuickTime––just to serve your Mac and Windows customers.

QuickTime movies compressed using MPEG-4 audio and video codecs can be exported to MPEG-4 file format without recompression, allowing you to serve your movies in multiple formats (.mov and .mp4) without sacrificing quality or time.

At typical Internet data rates, the MPEG-4 simple video codec is comparable to Sorenson3 video. This a good reason for using a codec in itself, but there are other advantages. The MPEG-4 video codec scales very well at extremely low bitrates, making it suitable for cell phones and PDAs with data rates even lower than dialup modems. In addition, MPEG-4 video compression can be very fast, making it suitable for live broadcasts and decreasing the time spent compressing movies.

MPEG-4 audio uses the Advanced Audio Codec (AAC), as discussed in the section MPEG-4 Audio Support. This codec provides better quality than mp3 audio at any given bitrate, or equivalent quality at a lower bitrate (typically about 30% lower). At higher bitrates, AAC supports multichannel surround-sound audio. Like MP3 before it, MP4 audio is a standard, so it is entirely possible that devices currently supporting MP3 (MP3 players, CD players, DVD players) will soon be available for MP4 as well. This is a premium quality audio codec for ISDN data rates and above.

For low bandwidth audio suitable to dialup modems or portable wireless connections, however, the QDesign2 music codec and Qualcomm Purevoice codecs remain better choices.

The MPEG-4 specification includes a low bandwidth audio codec based on CELP (codebook excited linear predictive) algorithms similar to the Purevoice codec.

Creating QuickTime Movies With MPEG-4 Compression

You can use the MPEG-4 audio and video compressors as you would any other QuickTime codecs, as explained in the section New Video Codec for MPEG-4. The MPEG-4 video and audio codecs are available in the standard QuickTime compression dialog box.

From QuickTime Player, choose Export (File menu), Movie to QuickTime Movie (pop-up menu), and click the Options button. Click the Settings button for audio or video and choose MPEG-4 from the compressor list. There are a variety of settings for audio and video, such as frame rate, quality, and data rate limit. Click the Size button to change the pixel dimensions of the video track. Click Okay, then Save.

Other applications that use the standard file compression dialog automatically gain the ability to use MPEG-4 compression when you install QuickTime 6.

Creating .mp4 Files

To create .mp4 files from QuickTime Player, choose Export (File menu), Movie to MPEG-4, (pop-up menu), and click the Options button. This opens a dialog box with tabs for General, Video, Audio, Streaming, and Compatability. Use this dialog box to select your MPEG-4 compression settings. These panels are described and illustrated in the section New Dialogs for Handling MP4 Files.

The General settings allow you to export audio, video, or both. You can make some choices about audio and video compressor settings here as well.

One of your compression choices is Pass Through. Use this setting to export a QuickTime movie with MPEG-4 compression to the .mp4 file format without recompressing the data. This is a very fast operation and does not degrade audio or video quality.

The Size menu gives you three choices in the current release of QuickTime 6––Current, 320 x 240, and 160 x 120. If you need a different frame size, you can resize the movie and choose Current.

The Video settings allow you to set a video bitrate limit, frame rate, and keyframe rate.

The Audio settings allow you to set an audio bitrate limit and number of channels.

Text at the bottom of each pane changes as you choose settings to help you undertand the options and monitor ISO compliance. The Compatability pane lets you override audio and video settings to ensure ISO compliance. For more information, see the section ISO Compliance.

The Streaming pane lets you create a fast-start or streaming .mp4. If you choose streaming, QuickTime will add a hint track. You can choose this option with the codecs set to Pass Through to turn a fast-start movie with MPEG-4 compression into a hinted .mp4 without recompressing.

You can stream .mp4 files using the QuickTime Streaming Server (version 4 or later), the Darwin Streaming Server (version 4 or later), or any ISO-compliant streaming server. QuickTime 6 can also play MP4 streams from any ISO-compliant source.

Playing .mp4 Files in QuickTime

Double-clicking .mp4 files from the desktop may launch QuickTime Player, or it may launch some other application that is registered for .mp4 files on your computer.

Files created on the Mac OS have a creator code as well as a file type, so the operating system will usually call QuickTime Player for an .mp4 file created locally on a Mac. This creator code is normally lost, however, if a file is stored on Windows or Unix file systems, something which commonly occurs when a file is transferred over the Internet.

To deliver .mp4 files over the Internet, your Web server needs to be configured for the .mp4 MIME type (video/mp4). Once this is done, a browser will play .mp4 files using the plug-in or ActiveX control registered for video/mp4. If you post your .mp4 file to the Web and attempt to view it using QuickTime, an error stating that “This is not a file that QuickTime understands,” or an attempt to display the file as text, generally indicates that the Web server is not configured for the mp4 MIME type.

To embed an .mp4 file in a Web page so that it will be played only by QuickTime, use both the OBJECT tag––specifying the QuickTime ClassID and Codebase––and the EMBED tag, with SRC set to a QuickTime MIME type––such as .qtif or .pntg––and QTSRC set to the .mp4 file, as shown in the following example.

<OBJECT

CLASSID="clsid:02BF25D5-8C17-4B23-BC80-D3488ABDDC6B"

    CODEBASE="http://www.apple.com/qtactivex/qtplugin.cab"

    WIDTH="320" HEIGHT="256" >

    <PARAM NAME="src" VALUE="My.mp4" >

    <PARAM NAME="autoplay" VALUE="true" >

<EMBED  SRC="QTMimeType.pntg" TYPE="image/x-macpaint"

PLUGINSPAGE="http://www.apple.com/quicktime/download"

    QTSRC="My.mp4" WIDTH="320" HEIGHT="256"

    AUTOPLAY="true" >

</EMBED>

</OBJECT>

ISO Compliance

The MPEG-4 specification is more than just a video codec or an audio codec. It defines a rich set of multimedia, including such things as text and facial animation, as discussed in the section Support for MPEG-4.

No software is currently able to display all the different media described in the MPEG-4 specification. Consequently, MPEG-4 defines profiles (discussed in the section Profiles and Levels Defined, which describe the subset of MPEG-4 features a particular player supports, and the feature set a particular movie requires.

A Profile 0 player, for example, can play simple MPEG-4 video at speeds up to 64 kbit/second, and AAC audio at 44.1 and 48 kHz in mono or stereo. A Profile 0 movie does not require any other features for correct playback. A Profile 0 player can play any Profile 0 movie.

A Profile 1 player has a larger required feature set that includes everything in Profile 0 as well as features such as multichannel sound and higher bitrate video.

If an MP4 movie uses even one feature of theProfile 1 set (that is not also part of the Profile 0 set), it is a Profile 1 movie, because it requires a Profile 1 player for reliable playback.

If an MP4 player is missing even one feature required for Profile 1, it is a Profile 0 player, even though it may be able to play many Profile 1 movies.

QuickTime 6 is a Profile 0 player. It can play any Profile 0 movie. QuickTime 6 also has some features of a Profile 1 player, such as the ability to handle higher bitrate video, but it does not have the full Profile 1 feature set and cannot play all Profile 1 movies.

QuickTime can create and play Profile 0 movies that use video at higher bitrates than 64 kbit/second. If you know your movie will be played by QuickTime, you may want to take advantage of the higher bitrates available, but be aware that this produces files which are not ISO-compliant. Other Profile 0 players may not be able to play these files, even though QuickTime can.

To ensure interoperability with other players, use only ISO-compliant MP4 files.

New Flash Media Handler

The new Flash media handler supports Macromedia Flash files (also known as SWF files) that conform to Flash 5 versions and earlier of the SWF specification. (Previous releases of QuickTime supported files that conformed to Flash 4 and earlier.) You should refer to Macromedia’s documentation for a complete listing of the features added to Flash 5. The most significant additions include

• greatly expanded ActionScript capabilities

• HTML text rendering

• XML data exchange

All these features work properly under the new Flash media handler––with a few limitations. (Refer to the QuickTime 6 Release Notes, which specify those limitations.)

SWF files opened by QuickTime-savvy applications are converted to QuickTime movie files by the Flash movie importer, discussed in the next section. These movie files consist of a single Flash track, whose media data is simply the data in the original SWF file. Virtually all of these movie files play back in QuickTime Player, in other QuickTime-savvy applications, or in the QuickTime browser plug-in exactly as if the original SWF file had been opened using the Flash Player application or the Flash browser plug-in.

Flash Movie Importer

The new Flash movie importer is “smarter” than the previous importer in several ways. The principal change is that the new importer scans some or all of the Flash file being imported to try to determine whether the file is set to automatically start playing when it is opened. (Previous importers assumed that all imported SWF files should be autoplayed.) Several other settings are unchanged from earlier versions of the Flash importer: the play-all-frames option is set to TRUE and the looping flag is set to FALSE.

New Flash Properties Info Panel

Flash tracks can be combined with other kinds of tracks in a QuickTime movie file. This is especially useful when using controls in the Flash track (buttons, sliders, etc.) to control the playback and settings of other tracks (video tracks, sound tracks, VR tracks, etc.)

In this situation, the content author needs to be aware of a new consideration that did not arise in earlier versions of the Flash media handler: version 5 ActionScripts can read the position of the cursor and/or the state of the mouse button at any time. This means that some ActionScripts may respond to mouse button clicks even if those clicks do not occur on some interactive element in the Flash track. If the Flash media handler accepts and processes all clicks in the track rectangle, then those clicks cannot be passed to tracks layered behind the Flash track. This effectively prevents the user from interacting with sprite tracks and QuickTime VR tracks layered behind the Flash track.

The new Flash media handler allows a movie author to decide on a per-track basis whether all mouse button clicks are accepted and handled by that particular instance of the Flash track or whether clicks that are not on an interactive element in the track are passed to tracks layered behind it. The setting for a specific Flash track can be adjusted using the new “Flash Properties” info panel in QuickTime Player, shown in Figure 1-10.

This panel contains a single check box labeled “Mouse Capture Enabled”. If the box is checked, then all mouse clicks are directed to the Flash track (unless some track in front of the Flash track processes the click); if the box is unchecked, only mouse button clicks on interactive elements in the Flash track are processed.

When a Flash file is imported as a movie with a single Flash track, mouse-capturing is enabled for that track. If you combine that track with other tracks, you may need to adjust the mouse capture setting to achieve the proper user experience.

Controlling Mouse Capturing Setting

The mouse capture setting of a Flash track is stored in the media properties atom of the track.

The Movies.h header file contains the constant kFlashTrackPropertyAcceptAllClicks to identify the atom type; the atom data is a Boolean value, where TRUE means to accept all mouse button clicks and FALSE means to accept only those mouse button clicks on an interactive element in the Flash track.

The following snippet of code sets a Flash track to accept all clicks:

QTAtomContainer trackProperties = NULL;

    Boolean     acceptAllClicks = true;

GetMediaPropertyAtom(flashMedia, &trackProperties);

    if (trackProperties != NULL) {

        QTInsertChild(trackProperties, 0,

        kFlashTrackPropertyAcceptAllClicks, 1, 1,

        sizeof(acceptAllClicks), &acceptAllClicks, nil);

SetMediaPropertyAtom(flashMedia, trackProperties);

QTDisposeAtomContainer(trackProperties);

}

Derived Media Handlers

Derived media handlers are so called because they derive much of their functionality from the base (or generic) media handler. Historically, derived media handlers have requested idles from the generic media handler by means of flags passed to MediaSetHandlerCapabilities. There are three basic modes the derived media handler can request:

1. Don’t idle me (noIdle).

2. Idle me once per sample in my track (0). No flags are set.

3. Idle me all the time (noScheduler, wantsTime, or both).

These modes can be changed at any time by calling MediaSetHandlerCapabilities again.

Derived media handlers that only use modes 1 and 2 don’t need to do anything with Idle Management. All their Idle Management will be handled for them by the generic media handler. They should not implement MediaGSetIdleManager or MediaGGetIdleManager.

Derived media handlers that currently use mode 3, but would like the ability to throttle back the idle rate, should implement MediaGSetIdleManager and MediaGGetIdleManager. They can then use various Idle Manager routines to tell QuickTime when they would like to be idled next.

MediaGGetIdleManager

Retrieves the Idle Manager object from a derived media handler.

MediaGGetIdleManager (MediaHandler mh,
   IdleManager * pim);

MediaGSetIdleManager

Gives an Idle Manager object to a derived media handler, so it can report its idling needs.

MediaGSetIdleManager (MediaHandler mh,
   IdleManager im);

What To Do Next

After receiving an idle manager by means of the above calls, a data handler can call the following routines to tell QuickTime when they need to be idled next:

• QTIdleManagerSetNextIdleTime

• QTIdleManagerSetNextIdleTimeNever

• QTIdleManagerSetNextIdleTimeNow

• QTIdleManagerSetNextIdleTimeDelta

Background

QuickTime movie playback APIs have traditionally been dependent on the classic Macintosh application paradigm, i.e., the WaitNextEvent() loop. In this loop, an application delegates events to a movie’s Movie Controller (if present) and shares some of its idle time with QuickTime, which results in “idling” of movies. In the cooperatively scheduled world of Mac OS 9 and earlier versions of the Macintosh operating system, this scheme worked well.

In Mac OS X, however, a new application paradigm was introduced. This paradigm depends on Carbon Events and associated handlers to communicate user events to the application. Older models that rely on periodic polling are replaced by the more “tunable” event loop timer mechanism, which enables an application to have greater precision over the frequency of idling.

As a consequence, application developers may need to construct event handlers for their windows to funnel events to their Movie Controllers and create event loop timers to “idle” their movies.

How It Works––An Event Target

The Carbon Movie Control is implemented as a custom control, which installs an event handler to handle the Carbon Events sent to controls. When a Carbon Movie Control is created for a movie, a movie controller is also created. The movie control then directs User Interface events to this movie controller.

The application can install event handlers on the Carbon Movie Control to handle such things as contextual menu clicks or to intercept events to do special processing. Control Manager calls can be made as well. For example, the GetControlBounds() and SetControlBounds() functions can be used to obtain or modify the control’s size and location.

Providing Time to Movies

The Carbon Movie Control’s custom control implementation takes care of all event routing to the movie. In order to distribute time to these movies, an event loop timer is set up which “idles” all movie controllers associated with Carbon Movie Controls within the application. The frequency of this timer is set using information it gets from the QuickTime Task Management APIs, discussed in the section New APIs for Tasking QuickTime. Thus, the amount of time devoted to movie processing is minimized.

Support for Editing

The Carbon Movie Control also supports basic movie editing features, such as cut, copy, paste, and clear, and performs the work of updating the Edit menu, enabling or disabling editing command items as appropriate.

Interface

The interface for the Carbon Movie Control feature is a single API routine:

CreateMovieControl

OSErr CreateMovieControl (
   WindowRef theWindow,
   Rect *localRect,
   Movie theMovie,
   UInt32 options,
   ControlRef *returnedControl);

Supported on Mac OS X

Loading Images into a Sprite Track

Each sprite in a sprite track has an image associated to it. Typically, that image is visible to the user when the movie is presented. A Sprite track can have a number of images in it and you can assign another image to a sprite by setting its image index.

In general, many of the images that could be used in interactive Web content are simultaneously being integrated into HTML, perhaps updated by server-side scripts, created by art departments in larger production teams, or are simply not available during the Movie authorship process. In earlier versions of QuickTime, it was not possible for a movie author to manage the dynamic loading and processing of sprite images. Images had to be integrated into the movie when it was generated.

Now, in QuickTime 6, with two simple sprite track wired actions (discussed in the section New Sprite Actions), the movie author can load any image format supported by QuickTime, either from a local or remote source, and manage its display and persistence during the playback of a movie. Sprite images, like sprites before them, now have two unique identifiers associated with them to help movie creators manage many images over the course of a movie’s lifetime, index and ID.

New Sprite APIs

The following APIs, discussed in this section, are new in QuickTime 6.

SpriteMediaNewImage

Creates a new sprite image.

ComponentResult  SpriteMediaNewImage (                     // IV-2677
   MediaHandler   mh,   // IV-2677
   Handle dataRef,      // IV-2683
   OSType dataRefType,  // IV-2695
   QTATomID desiredID );// IV-2675

SpriteMediaDisposeImage

Frees the memory allocated for a new sprite image, and removes that image from the track.

ComponentResult  SpriteMediaDisposeImage (                   // IV-2677
   MediaHandler mh,   // IV-2677
   short imageIndex );// IV-2687

Function Result: The image disposed of is no longer available to the sprite track, and the image index location will remain “empty” for the duration of the current key sample.

Introduced in QuickTime 6.

C interface file: Movies.h

SpriteMediaImageIndexToID

Returns the ID of a particular image given the index of that image.

ComponentResult  SpriteMediaImage  (                         // IV-2677
   MediaHandler mh,         // IV-2677
   short imageIndex,
   QTAtomID *imageID );     // IV-2687

Introduced in QuickTime 6.

SpriteMediaImageIDToIndex

Returns the index of a particular image, given the ID of that image.

ComponentResult  SpriteMediaImage  (                         // IV-2677
   MediaHandler mh,         // IV-2677
   QTAtomID imageID,        // IV-2687
   short *imageIndex );

Function Result: If no image is found with a corresponding ID, the image index returned will be 0.

Introduced in QuickTime 6.

Controlling Hit-Testing Mode of an Individual Sprite

In QuickTime 6, each sprite has a property:

canBeHitTested

This property can have a Boolean value of either TRUE or FALSE.

When a sprite is created, this property is defaulted to TRUE. The property is an actual property of sprites within a sprite world. Thus, this property can be set and retrieved by means of sprite world calls directly: SetSpriteProperty and GetSpriteProperty, using the kSpritePropertyCanBeHitTested (defined in Movies.h) constant and passing and receiving the property value of TRUE or FALSE. Further, when calling a sprite world’s SpriteHitTest or SpriteWorldHitTest routines, you can pass the new flag spriteHitTestTreatAllSpritesAsHitTestable to have SpriteWorld’s hit testing ignore the individual sprites’ own canBeHitTested property and make all sprites hit testable. Note there is no flag for making all sprites not hit testable.

Since sprite media uses sprite world, this property can also be manipulated by means of SpriteMedia calls: SpriteSetSpriteProperty and SpriteGetSpriteProperty, passing kSpritePropertyCanBeHitTested and passing/receiving the property value of TRUE or FALSE.

Finally, this property can be manipulated by means of non-primary source data using the kTrackModifierObjectCanBeHitTested (also defined in Movies.h) constant.

Controlling Hit-Testing Mode of a Sprite Track

Sprite Tracks in QuickTime have a property:

allSpritesHitTestingMode

It can have three values, as defined in MovieToolbox.h:

kSpriteHitTestUseSpritesOwnPropertiesMode = 0,

kSpriteHitTestTreatAllSpritesAsHitTestableMode = 1,

kSpriteHitTestTreatAllSpritesAsNotHitTestableMode = 2

When a sprite track is created, this property defaults to kSpriteHitTestUseSpritesOwnPropertiesMode.

This property can be specified in the media by having a QTAtom of type kSpriteTrackPropertyAllSpritesHitTestingMode, a size of short, and a value of 0, 1 or 2.

Also, this property can be set at runtime by means of SpriteSetSpriteProperty, which normally is used to set properties of sprites, but has been overloaded to now be able to set track properties. To do so, the spriteID should be equal to FOUR_CHAR_CODE('Trck'), the property type should be kSpriteTrackPropertyAllSpritesHitTestingMode and then the property value should be 0, 1, or 2.

Correspondingly, the track property can be retrieved via SpriteGetSpriteProperty with a sprite ID of FOUR_CHAR_CODE('Trck') and a property type of kSpriteTrackPropertyAllSpritesHitTestingMode.

Handling Mouse Clicks

When a mouse click occurs within a sprite track, the sprite media handler will first examine its kSpriteTrackPropertyAllSpritesHitTestingMode property to see how to handle the click.

If the property is set to kSpriteHitTestUseSpritesOwnPropertiesMode, the sprite media handler will then use the individual hit testing property kSpritePropertyCanBeHitTested of the sprite clicked on to determine if the sprite will “receive” the click or not. If not (i.e., the sprite’s kSpritePropertyCanBeHitTested property is FALSE), and the mouse click is over another sprite, the media handler will then consider that sprite’s kSpritePropertyCanBeHitTested property and, if TRUE, will have that sprite receive the mouse click. If FALSE, then the process continues with other sprites under the mouse until one receives it or there are no further sprites at the location of the mouse click. If none, the sprite media handler will inform QuickTime it does not wish to handle the mouse click at all, which will then propagate the mouse click to the Track underneath it in the movie.

If the kSpriteTrackPropertyAllSpritesHitTestingMode property of a Sprite Track is set to kSpriteHitTestTreatAllSpritesAsHitTestableMode, then the sprite media handler will ignore the kSpritePropertyCanBeHitTested sprite properties of all sprites within the track and instead consider all the sprites as being able to receive mouse clicks.

If the kSpriteTrackPropertyAllSpritesHitTestingMode property of a Sprite Track is set to kSpriteHitTestTreatAllSpritesAsNotHitTestableMode, then the sprite media handler will ignore the kSpritePropertyCanBeHitTested sprite properties of all sprites within the track and instead consider all the sprites as being unable to receive mouse clicks.

Sprite Track Setting Enhancements

A Sprite Track enhancement is provided in QuickTime 6 that gives content creators, primarily, and users, secondarily, greater flexibility and control over the pixel depth of the offscreen Graphics World (GWorld) that a Sprite Track utilizes for the composition and management of its sprites.

Limited Control of Offscreen Bit Depth

In earlier versions of QuickTime, there was a limited amount of control a content creator or user had over the offscreen bit depth. In the QuickTime Player Properties 2 Info Panel of a Sprite Track, you could choose one of these options:

• Best Depth. (Have the Sprite Track determine empirically the best depth for the track)

• 256. (8-bit Pixels)

• Thousands. (16-bit Pixels

• Millions+. (32-bit Pixels)

Each option is at best a suggestion to the Sprite Track as to what the offscreen bit depth should be. Even though, for example, 256 is selected, the Sprite Track might, depending on various parameters––such as monitor bit depth, memory constraints, track or sprite graphics modes––create an 8-bit offscreen, a 16-bit offscreen or even a 32-bit offscreen graphics world.

While this may at times yield better visual results, it also may result in poor memory usage, degraded performance, or even worse––a visual result not intended by the content creator.

Although such a suggestive approach makes sense for the Best Depth setting where the user is explicitly asking the Sprite Track to make such a decision, it may be counter-productive for the other three available choices.

New Preferred Bit Depth Info Panel

QuickTime 6 now provides users with greater control and flexibility over the depth of the Sprite Track offscreen graphics world. To accomplish this, QuickTime 6 has added a new mode, called Actual Depth, that has the same four options as Best Depth, 256, Thousands and Millions+.

Note that for purposes of backward compatibility, QuickTime also maintains the old method, which is called Preferred Mode.

The difference between Actual and Preferred modes is that in Actual Mode, a choice of 256, Thousands or Millions+ dictates that the Sprite Track offscreen depth be exactly as chosen. This provides explicit choice and control over image quality, performance and memory usage.

The option of Best Depth under Actual Mode is analogous to Best Depth under preferred Mode: although the algorithms differ slightly, both modes allow the Sprite Track to determine the offscreen bit depth according to what is best under the current circumstances.

Switching Between Modes

A user can switch any sprite movie from Preferred Mode to Actual Mode and from Actual Mode to Preferred Mode by holding down the Option Key on Mac OS 9 or Mac OS X, or the Alt Key on Windows while clicking the Set button in the Properties 2 Info Panel and subsequently clicking the OK button in the dialog that comes up and allows you to choose a setting. If you choose Cancel in the dialog, there is no change in mode.

The user can tell if a Sprite Track is in Actual or Preferred mode, as the label in the Info Panel switches on the fly between “Actual Depth:” and “Preferred Depth:”.

A New Sprite Track Property

In order to support the new Actual Depth mode, a new Sprite Track Property has been added:

kSpriteTrackPropertyPreferredDepthInterpretationMode = 109

This property is optional. If the property is absent, the Sprite Track operates in Preferred Depth mode.

If this property is present, it has a single value, of size short, that can be one of these values:

• kSpriteTrackPreferredDepthCompatibilityMode = 0

• kSpriteTrackPreferredDepthModernMode = 1

If the value of this property is kSpriteTrackPreferredDepthCompatibilityMode, then the Sprite Track operates in Preferred Depth mode. However, if the value is kSpriteTrackPreferredDepthModernMode, then the Sprite Track operates in the new Actual Depth Mode.

Using the SpriteSetSpriteProperty API

To programmatically set the Sprite Track depth mode, you use the SpriteSetSpriteProperty call of the Sprite Media Handler:

pascal ComponentResult SpriteSetSpriteProperty(Media media,

                                                QTAtomID spriteID,

                                                long propertyType,

                                                void *propertyValue);

Pass a four character code of ‘Trck’ for the spriteID and specify kSpriteTrackPropertyPreferredDepthInterpretationMode as the property type. Finally, pass a value of kSpriteTrackPreferredDepthCompatibilityMode or KSpriteTrackPreferredDepthModernMode directly as the propertyValue.

For example, to Set a Sprite Track to use the Actual Depth mode:

    error = SpriteSetSpriteProperty(SpriteMedia,

                ‘Trck’,

                kSpriteTrackPropertyPreferredDepthInterpretationMode

                kSpriteTrackPreferredDepthModernMode,);

New Wired Actions and Operands

The following wired actions and operands are new in QuickTime 6.

kActionSpriteTrackNewImage  = 7182, /* ( C string imageURL, QTAtomID

                                         desiredID) */

kActionSpriteTrackDisposeImage = 7183, /* (short imageIndex) */

Going To a Chapter by Index

The following actions go to the time associated to a chapter. The chapter is specified relative to the current chapter or by index.

kActionMovieGotoNextChapter = 1039, /* no params */

Changes the movie time to the start of the next chapter.

kActionMovieGotoPreviousChapter = 1040, /* no params */

Changes the movie time to the start of the previous chapter.

kActionMovieGotoFirstChapter = 1041, /* no params */

Changes the movie time to the start of the first chapter.

kActionMovieGotoLastChapter = 1042, /* no params */

Changes the movie time to the start of the last chapter.

kActionMovieGotoChapterByIndex = 1043, /* ( short index ) */

Changes the movie time to the start of the nth chapter

kQTEventKeyUp Event Type Added

QuickTime 6 adds the kQTEventKeyUp event type that can be used in wired actions. It corresponds to key-up events on the keyboard. Applications may need to take special actions in order to receive key-up events (which are then passed to a movie controller using MCIsPlayerEvent). For example, Carbon applications that use the classic event model may need to call:

SetEventMask(everyEvent);

since by default the OS does not report key-up events to an application. Similarly, Carbon-event-based applications may need to register a handler for kEventRawKeyUp.

The movie controller also now supports the mcActionKeyUp action.

Random Seed

The following action can be used in conjunction with kOperandRandom.

kActionSetRandomSeed = 6164, /* long randomSeed */

Sets the QuickDraw seed value which is starting point for any subsequent kOperandRandom calls.

Background

QuickTime 4.1 and the Sound Manager introduced support for the playback of VBR audio––in particular, VBR support for the decoding and playback of MP3 audio. A number of modern audio compression formats, such as MP3, either support or require VBR decoding.

Versions of QuickTime prior to QuickTime 4.1 provided support only for constant bitrate (CBR) audio. The fundamental difference between constant bitrate and variable bitrate 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.

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.

QuickTime 6 VBR Support

As discussed, QuickTime and the Sound Manager have been able to decode self-framed, variable bitrate formats such as MP3 since QuickTime 4.1. In addition, the QuickTime Movie file format has been able to carry variable bitrate audio.

With QuickTime 6, QuickTime and the Sound Manager add much richer and more comprehensive support for VBR audio, including support for both compression of VBR audio and decompression of non-self-framed VBR audio formats. An example of a non-self-framed audio format is AAC, described in the section Defining AAC. Table 1-2 shows the audio support available since QuickTime 4.1.

Some Techniques For Compressing VBR Audio

This section discusses some of the techniques you can use if you need to compress VBR audio.

Because variable bitrate audio may contain audio frames of different sizes, it is important that an application use the appropriate APIs to generate the compressed audio. If, for example, your application receives a -213 (siVBRCompressionNotSupported) error from QuickTime or the Sound Manager, it indicates either QuickTime or the Sound Manager doesn’t “know” about VBR compression, or doesn’t believe your application understands VBR compression.

To inform QuickTime that your application understands the details of VBR compression, here are some steps that you should consider:

1. To begin with, you must use the SoundConverterFillBuffer() API. If you are using the SoundConverterFillBuffer() API, you’ve already done most of the work. Although SoundConverterConvertBuffer() cannot be used for VBR compression, you can configure the SoundConverter without making a decision as to using FillBuffer or ConvertBuffer yet, in case you want to continue using the SoundConverterConvertBuffer() routine for fixed compression audio. There is no good reason to do so, but it may be important in your current implementation.

2. Your application must inform the SoundConverter that it can handle VBR audio. To do this, immediately after opening the SoundConverter with SoundConverterOpen(), make a call to SoundConverterSetInfo(), passing the siClientAcceptsVBR selector like the following:

   SoundConverterSetInfo(theSoundConverter, siClientAcceptsVBR,(void*)true);

This lets the sound converter know that you are VBR compression-aware.

1. After configuring the sound converter with compression parameters (if present), request the compressor’s compression information, so you know how many PCM samples are generated per audio frame.

2. Ask for siCompressionFactor and look at the resulting CompressionInfo. If the compInfo.compressionID field is set to variableCompression, then the codec is configured to generate VBR audio. If it has another value, the codec is configured for a fixed bitrate––just as it would in versions of QuickTime prior to QuickTime 6. Remember that a single codec can support fixed and variable compression, so don’t assume its capabilities from its codec type.

Just as before, samplesPerPacket holds the PCM sample count per audio frame (packet). For VBR audio, you can ignore bytesPerFrame/bytesPerPacket, since the sizes aren’t constant.

1. For variable compression codecs, you need to know the worst case size of a single audio frame (packet). You can then allocate the output buffer for use with the SoundConverterFillBuffer() routine, based on a multiple of this size. Failing to do this might result in SoundConverterFillBuffer() not being able to generate even a single audio frame. If you spin on SoundConverterFillBuffer() waiting for it to generate at least one audio frame before continuing but don’t provide a large enough output buffer, you have the makings of a really cool and involved infinite loop.

Use the new selector siCompressionMaxPacketSize to retrieve the worst case packet size. The following code shows an example:

    UInt32 maxPacketSize = 0;

    err = SoundConverterGetInfo( theSoundConverter,

                                siCompressionMaxPacketSize,

                                &maxPacketSize );

If a VBR codec doesn’t support this selector, you may want to use a worst case output buffer size such as 32K.

1. Use SoundConvertFillBuffer() to perform the encoding, as shown in the code below. The value should be tied to the codec’s current configuration.

   err = SoundConverterFillBuffer(theSoundConverter, //a sound converter

   fillBufferUPP, // proc

   fillBufferRefCon, // refCon passed to FillDataProc

   soundOutputBuffer, // compressed audio buffer

   soundOutputBufferSize, // size of compressed audio buffer

   &actualOutputBytes, // number of output bytes

   &outputFrames, // number of output frames

   &outputFlags); // fillbuffer returned advisory flags

The difference with VBR compression is that each call only returns audio, where all the frames have the same size in bytes. This is necessary because the SoundConverterFillBuffer() API returns the number of bytes it wrote and the number of frames but doesn’t return any kind of array indicating the boundaries between frames. If you divide actualOutputBytes by outputFrames, you can determine how large each audio frame is.

As an example, if the audio frames have the following sizes in bytes

[  40  ] [   40  ] [    50    ] [    50   ] [    50    ] [ 30 ] [  40  ]

at least four calls to SoundConverterFillBuffer will be necessary in order to encode these frames. This call would return the following values:

actualOutputBytes        outputFrames

-----------------       ------------

    80                      2

    150                     3

    30                      1

    40                      1

Using the Standard Sound Compression Component and VBR Compression

Like the SoundConverter, QuickTime doesn’t want to offer VBR sound compressors to applications that cannot support them. This means that if your application uses the Standard Sound Compression dialog to select and configure sound compressors, you should pass the new (in QuickTime 6) scSoundVBRCompressionOK selector to SCSetInfo() as in the following code example:

    ComponentInstance ci = OpenDefaultComponent(StandardCompressionType,

                                        StandardCompressionSubTypeSound);

    if (ci ) {

                Boolean doVBR = true;

                SCSetInfo (ci, scSoundVBRCompressionOK, &doVBR);

                . . .

If you don’t pass the new scSoundVBRCompressionOK selector to SCSetInfo(), only fixed compression codecs will be presented in the list.

In fact, compressors that perform fixed and variable compression will be presented if this selector is not called, but those compressors will only offer their fixedCompression options. Since AAC only performs variable compression, it will not appear in the dialog unless you call SCSetInfo with scSoundVBRCompressionOK.

In QuickTime 6, a new Standard Compression selector is provided in QuickTimeComponents.h that returns a list of available codecs. The selector, a pointer to a handle, is defined as follows:

scAvailableCompressionListType = FOUR_CHAR_CODE('avai')

This is the same kind of handle as the existing scCompressionListType selector. Applications that need to build lists of codecs (compressors) for their user interface should adopt this API. If the scAvailableCompressionListType selector is not recognized, use the previous code.

Audio File Formats and VBR Compression

Not all audio file formats can hold variable compression audio, since the information about framing isn’t always available in every format.

QuickTime Movies provide a format that can hold the information, just as MPEG-4 files can. AIFF and WAVE, however, are formats that do not carry such information.

This explains why you see the MPEG-4 audio codec available in the QuickTime Movie exporter’s sound options––but not in the AIFF options. Not surprisingly, these exporters use the Standard Sound Compression dialog as above. Because VBR compression is opted in by the client, only the QuickTime Movie exporter passes the scSoundVBRCompressionOK selector.

Doing Something with VBR Audio Data

At this point in the process, your application is either generating VBR audio to be stored in a QuickTime Movie for playback later, or you want to play or decode the audio directly. Of course, you may be using your own format to store the audio, but remember, you need to store the framing information yourself.

If you store the data in the QuickTime Movie, you need to store the generated audio frames in a way that is compatible with how QuickTime stores VBR audio in sound tracks.

To play or decode the audio, you need to use the additional fields in the ExtendedSoundComponentData, ExtendedScheduledSoundHeader, or ExtendedSoundParamBlock, depending on how you are playing the data. Fortunately, they are the same fields.

The following fields are introduced in QuickTime 6:

    long frameCount;        // number of audio frames

    long * frameSizesArray; // pointer to array of longs with frame sizes

                                // in bytes

    long commonFrameSize;   // size of each frame if common

Specifically, frameCount, frameSizesArray and commonFrameSize are relevant for playback and decoding of AAC audio, as well as for other non-self-framed audio VBR audio formats.

As discussed earlier, QuickTime versions prior to QuickTime 6 could handle self-framed VBR audio. This is why the existing extended bufferSize field is sufficient for MP3 audio. AAC audio, though, doesn’t have information within it to indicate framing, and depends upon out-of-band data to carry that information. In the case of QuickTime and MPEG-4 movies, that information is in the sample tables.

The fields just described (new in QuickTime 6) are used to convey the information to the audio decoder (or sound decompressor in Sound Manager parlance) and are necessary for use with AAC audio. In all cases, these fields all describe a single buffer of audio. The existing sampleCount, buffer and bufferSizes fields all must be valid.

In addition, either frameCount and frameSizesArray or commonFrameSize must be valid (indicated by extendedFlags) in order to decode AAC data. (Note that frameCount and frameSizesArray must be valid as a unit because they work together, not as separate fields.)

The flags for extendedFlags are in the header file Sound.h as follows:

    kExtendedSoundFrameSizesValid = 1L << 2,

                        // set if frameSizesArray is valid

                        // (this will be nil if all sizes are common and

                        // kExtendedSoundCommonFrameSizeValid is set)

    kExtendedSoundCommonFrameSizeValid = 1L << 3,

                        // set if all audio frames have the same size and

                        // the commonFrameSize field is valid

If commonFrameSize is set, this means that all audio frames in the VBR buffer have exactly the same size in bytes. There is no frame count, since bufferSize divided by commonFrameSize is the frame count.

If frameCount and frameSizesArray are valid (remember, these fields must be considered as a unit), then frameCount holds a count of the number of elements in the frameSizesArray array. This array is a set of 32-bit values holding the size of each audio frame. In the above example, the fields would look like this:

    frameCount = 7;

    frameSizeArray = -->   { 40, 40, 50, 50, 50, 30, 40 }

Just as you can use the SoundConverterFillBuffer() routine to encode VBR audio, you can also use it to decode AAC audio. However, the SoundConverterFillBufferDataProc’s returned ExtendedSoundComponentData must set the appropriate flags, including the fields described above.

New Tween Component API

In QuickTime 6, tween components now provide an interrupt-safe interface using a new API routine, QTDoTweenPtr. This new call provides for return values in a pointer rather than a handle. Some specific tweens implemented as components required changes to ensure their interrupt safeness. Not all Apple-defined tween components support this new API. However, all of those needed for effects have been so revised.

QTDoTweenPtr

Runs a tween component, providing for return values in a pointer rather than a handle.

OSErr QTDoTweenPtr (QTTweener tween,
TimeValue atTime,
Ptr result,
long resultSize) ;

C interface file: Movies.h

Changes to Effects Dialog

In QuickTime 6, the effects dialog has been revised and enhanced. The new features include

• Grouping into types within the scrolling list on the left side of the dialog. In this new design, each effect defines what subgroup it belongs to, as shown in Figure 1-11. Any third-party effects installed appear under “Misc” until they are revised to include their subgroup information.

• Resizability of the dialog and split bars to control the list vs. preview vs. effect-specific areas. Note that the resize control is only drawn in Mac OS 8.1 and later.

• Providing a widget for picking points, which can be used in any effect that allows the selection of points (that is, x and y values). Notice that such items have turned from a multitude of sliders into this point-picking widget.

• Allowing effect components to specify custom “picking interfaces” for parts of their user interface, while allowing the Generic effect to handle the remainder.

• Providing a way to set slider values by typing. Any slider within the effects dialog will now allow this. Command-clicking any slider brings up a modal dialog. The dialog is centered below the control to edit. The dialog is sized appropriately for name and length of number edit. The dialog contains a type-in field, parameter name label, and OK and Cancel buttons.

• A knob control that provides a way to set angles greater than 360 degrees. This is used in the Slide effect. Knob control now has an inner section that serves as an hour hand. When the knob is manipulated beyond one rotation, the hour hand increments. This wraps properly both forward and backward over the 12 o’clock position.

• Effects may now specify some common “presets” that the user can easily select. These are used in the Slide effect. When such an effect is selected, the first subpanel is a list of presets, each with a name and preview. The pane scales to the available space, and implements a scroll bar if needed.

  • The subgroup pop-up menu at the top of the screen will read Easy and Custom if there are no additional subpanes. If there are, the pop-up menu reads Easy and the names of the other subpanes.

• A new effect called Channel Composite provides a way to create a bitmap whose color components are a combination of source A and B color components, reshuffled, and inverted as desired.

• The Color Tint effect now allows user to specify an amount of tinting to allow a gradual transition to a particular color, such as Sepia. A new pair of sliders controls this. Tweening is allowed. The default value is to tint fully (for backwards compatibility) for the entire duration of the effect.

• Effects may now have tween values when filtering during export, that is, Movie to QuickTime Movies. Some effects, such as Lens Flare and RGB Balance, now have a starting and ending value that you can set. Some (such as RGB Balance) display this information only if the Option key is pressed when selecting the Filter button. This is because tweening these values is uncommon.

Custom Effect Controls

Effects may choose to implement custom controls to allow the user to more easily edit complex parameters that are ill-served by simple sliders or type in boxes. Effects may allow a custom control for either a single parameter, or for a group of parameters.

Parameter(s) for a custom control must still be data types defined by the standard set, or for complex records of data, must be defined within a group as individual parameters made up from base data types (for example, a point is a group containing two Fixed point numbers).

This is to allow applications that do not wish to use the custom control for the effect to set values themselves.

Effects should be aware that these custom controls may be deployed by the application in either a dialog or a window, with application-defined background colors or patterns, along with application-defined font characteristics for the window.

It is recommended that an effect implement custom controls only when needed, and that custom controls be used for specific types of parameters (i.e., point, rectangle, polygon, path) rather than the entire user interface for the effect. Effects may choose to implement multiple custom controls that combine with standard controls to present the total user interface.

For effects that have very complex user interfaces not well suited for inclusion within a single window, it is recommended to use kParameterImageIsPreset––which allows the effect to have an external editing application for parameters that may then be set within the standard User Interface via the open file dialog or drag and drop. The Lens Flare (shown in Figure 1-12) effect’s “Flare Type” is an example of such a preset.

New Behavior Flag kCustomControl Added

For parameters that use a custom control to control a single parameter value, a new behavior flag has been added (kCustomControl), and the behavior for the parameter should be kParameterItemControl.

For parameters that are groups, the same flag (kCustomControl) should be used, and the behavior should be kParameterItemGroupDivider. Groups with the kCustomControl bit set will be implemented by calling the custom control for that group––the parameters within that group will not be processed in the normal manner.

In both cases, the new customType and customID fields of the behavior must be filled in. These are used in order to allow your custom control to determine which parameter is being edited in the case where the custom control is used for the editing of multiple parameters. These values are passed into the pdActionCustomNewControl call. Since the custom control mechanism is also used by QuickTime’s default effect dialogs, you should be prepared to pass onto the base effect any pdActionCustomNewControl calls for type/id pairs that you do not handle yourself. When pdActionCustomNewControl is called for controls of types handled by QuickTime, customType is kParameterAtomTypeAndID and customID is the ID of the parameter atom.

Using pdActionCustomNewControlControl to Create New Custom Controls

pdActionCustomNewControlControl is called by the application to create a new custom control or set of controls for an effect parameter. When pdActionCustomNewControl is called, the effect should perform any basic allocation it needs for storage and return the result in storage. The options parameter tells the control if the application wishes to support interpolated, optionally interpolated, or a single value parameter.

Since pdActionCustomNewControlControl may call upon your effect for other items within the dialog, it is recommended that your effect have an easy way to determine which controls it implements by using one of these two techniques:

• by having storage be a pointer with an OSType at the beginning to mark controls implemented by your code

• keeping track in your component globals those custom controls that you have created

When pdActionCustomDisposeControl is called, any allocation done by the control should be disposed of. In addition, pdActionCustomDisposeControl is the last chance the control has to commit any user changes into the sample.

Controls that implement type-in fields typically need to commit any final user edits at this time.

struct QTCustomControlNewRecord {

void * storage; /* storage allocated/disposed by the control*/

QTParameterDialogOptions options; /* options used to control

interpolation/not*/

QTAtomContainer sample; /* sample that holds the data to be edited*/

long customType; /* custom type and ID specified by effect for

creation of this control*/

long customID;

};

typedef struct QTCustomControlNewRecord QTCustomControlNewRecord;

typedef QTCustomControlNewRecord * QTCustomControlNewPtr;

pdActionCustomPositionControl is called by the application to position the control within a window or dialog.

The control should determine if it will fit in the allotted area and position itself there. It should also return the space taken up by the control. Note you are free to implement controls which are variable in size depending upon which parameter you are editing. You don’t need to scale your control to the requested size. If the area presented to your control is too small, set didFit to FALSE. You should still return in used the size you would have liked to use for the control. The application will then try again with a new size. Note that all controls must be able to fit within a minimum of 300 by 250 pixels.

Displaying Text Properly in Application Windows

Custom controls that draw text should make note of the text font, size, and style at this time in order to properly display within application windows.

Note that the default state for the control is hidden. You will receive a pdActionCustomShowHideControl in order to enable your control. You should not draw your control in response to pdActionCustomPositionControl.

struct QTCustomControlPositionControlRecord {

void * storage; /* storage for the control*/

WindowPtr window; /* window to be used by the control*/

Rect location; /* location within the window the control may use*/

Rect used; /* returned by the control to indicate size it actually

used*/

Boolean didFit; /* did the control fit in the specified area?*/

Boolean pad[3];

};

typedef struct QTCustomControlPositionControlRecord QTCustomControlPositionControlRecord;

typedef QTCustomControlPositionControlRecord * QTCustomControlPositionControlPtr;

pdActionCustomShowHideControl is called when the application wishes to enable/disable your control, or completely disable drawing of the control.

Your control should make note of the new state (if different from the last) and perform an InvalRect() on your drawing area, or you may draw your control’s initial state in the case of show. You should not attempt to erase your control as the result of a hide. Instead, call InvalRect() and allow the application to process the resulting event as appropriate.

struct QTCustomControlShowHideControlRecord {

void * storage; /* storage for the control*/

Boolean show; /* display the control?*/

Boolean enable; /* enable the control (ie, black vs gray display)*/

Boolean pad[2];

};

typedef struct QTCustomControlShowHideControlRecord QTCustomControlShowHideControlRecord;

typedef QTCustomControlShowHideControlRecord * QTCustomControlShowHideControlPtr;

Using pdActionCustomHandleEvent To Process Events

pdActionCustomHandleEvent is called to allow your custom control to process events.

Typical controls handle the following events:

• activate to draw your control in normal/gray mode

• update to draw your control

• mouseDown to handle clicks

• keyDown to handle typing when you have focus

• idle to perform idle drawing (if applicable)

If your control handles the entire event, set didProcess to TRUE. If you handled the event, but other controls still need the event, set didProcess to FALSE.

If your control supports the concept of focus for the purposes of typing (such as by having a type-in box for the parameter), then you set the tookFocus Boolean as part of your processing of the event. It is assumed that your control will draw the appropriate focus user interface as a result, and the calling application will disable any focus drawing within the remainder of the user interface.

By default, custom controls are not given idle time. If you need idle time, set needIdle to TRUE in response to the event that causes you to need idle (typically the taking of focus, or the first draw).

Your control will continue to be given idle events until you set needIdle to FALSE in response to a nullEvent.

struct QTCustomControlHandleEventRecord {

void * storage; /* storage for the control*/

EventRecord * pEvent; /* event to process*/

Boolean didProcess; /* did we process entire event?*/

Boolean tookFocus; /* did we take focus as a result of this event

(typically mouseDowns)*/

Boolean needIdle; /* does this control need idle events?*/

Boolean didEdit; /* did we edit the samples?*/

};

typedef struct QTCustomControlHandleEventRecord QTCustomControlHandleEventRecord;

typedef QTCustomControlHandleEventRecord * QTCustomControlHandleEventPtr;

Using pdActionCustomSetFocus to Set or Advance Current Focus

pdActionCustomSetFocus is called in order to set or advance the current focus of the user interface, typically because the user has pressed the tab or shift-tab keys, or because the user clicked within the area defined by your control.

Your control will be called with pdActionFocusFirst, pdActionFocusLast, or pdActionFocusOff to set or clear focus on your control. Your control will be called with pdActionFocusForward or pdActionFocusBackward to cycle focus within your control (if your control has multiple focus). If your control does not support focus, or the focus request results in focus moving beyond your supported range, return pdActionFocusOff in the focus parameter. Otherwise, return the focus that you set.

Controls which have no focus would always set focus to be pdActionFocusOff.

Controls with a single focus would set pdActionFocusFirst when requested to set either pdActionFocusFirst or pdActionFocusLast, and would set pdActionFocusOff for either pdActionFocusForward or pdActionFocusBackward.

enum { pdActionFocusOff = 0, /* no focus */ pdActionFocusFirst = 1, /* focus on first element */ pdActionFocusLast = 2, /* focus on last element */ pdActionFocusForward = 3, /* focus on next element */ pdActionFocusBackward = 4 /* focus on previous element */ }; struct QTCustomControlSetFocusRecord { void * storage; /* storage for the control*/ long focus; /* focus to set, return resulting focus*/ }; typedef struct QTCustomControlSetFocusRecord QTCustomControlSetFocusRecord; typedef QTCustomControlSetFocusRecord * QTCustomControlSetFocusPtr;

Using pdActionCustomSetEditMenu To Locate The Edit Menu

pdActionCustomSetEditMenu will be called to inform your custom control of the location of the edit menu.

If your control has editing boxes, this is useful in order to allow the user to perform cut, copy, and paste operations when focus is on one of these boxes.

struct QTCustomControlSetEditMenuRecord {

void * storage; /* storage for the control*/

MenuHandle editMenu; /* edit menu, or NIL*/

};

typedef struct QTCustomControlSetEditMenuRecord QTCustomControlSetEditMenuRecord;

typedef QTCustomControlSetEditMenuRecord * QTCustomControlSetEditMenuPtr;

Using pdActionCustomSetPreviewPicture To Preview Information

pdActionCustomSetPreviewPicture is called to inform your custom control of preview information that you may wish to use in the drawing of your user interface.

struct QTCustomControlSetPreviewPictureRecord {

void * storage; /* storage for the control*/

QTParamPreviewPtr preview; /* preview to set*/

};

typedef struct QTCustomControlSetPreviewPictureRecord QTCustomControlSetPreviewPictureRecord;

typedef QTCustomControlSetPreviewPictureRecord * QTCustomControlSetPreviewPicturePtr;

pdActionCustomSetEditCallout tells your control of the need by the application to be informed of changes to the parameter values (typically for the purposes of updating previews).

If a callout is available, your custom control should call it whenever a change has been made to the parameter(s) that your control is editing (as a result of user actions, most typically). If you choose not to implement this, live dragging or updating of values will not work.

struct QTCustomControlSetEditCalloutRecord {

void * storage; /* storage for the control*/

QTParamPreviewCalloutPtr callout; /* requested callout, or NIL to

disable*/

};

typedef struct QTCustomControlSetEditCalloutRecord QTCustomControlSetEditCalloutRecord;

typedef QTCustomControlSetEditCalloutRecord * QTCustomControlSetEditCalloutPtr;

Using pdActionCustomGetEnableValue to Enable or Disable Other Controls

pdActionCustomGetEnableValue allows you to return a value for the purposes of enabling or disabling other controls.

Most custom controls do not need to implement this call.

If your control is able to control the enabling and disabling of other parameter controls (such as is done by standard pop up or enumerated type controls), you need to supply a value that can be use for greater than or less than types of comparisons.

struct QTCustomControlGetEnableValueRecord {

void * storage; /* storage for the control*/

long currentValue; /* value to compare against for enable/disable

purposes*/

};

typedef struct QTCustomControlGetEnableValueRecord QTCustomControlGetEnableValueRecord;

typedef QTCustomControlGetEnableValueRecord * QTCustomControlGetEnableValuePtr;

Using pdActionCustomSetSampleTime to Specify Duration and Start Time

pdActionCustomSetSampleTime tells your control information from the application about the duration and start time for the sample being edited.

Most controls do not need this information, but some may choose to use it in the interface they present the user. However, this call need not be made by applications, so the custom control should be prepared to run when the sample time information is not available.

struct QTCustomControlSetSampleTimeRecord {

void * storage; /* storage for the control*/

QTParamSampleTimePtr sampleTime; /* sample time information or NIL*/

};

typedef struct QTCustomControlSetSampleTimeRecord QTCustomControlSetSampleTimeRecord;

typedef QTCustomControlSetSampleTimeRecord * QTCustomControlSetSampleTimePtr;

pdActionCustomGetValue tells your control to store any value(s) into the specified atom container.

All custom controls must implement this call.

struct QTCustomControlGetValueRecord {

void * storage; /* storage for the control*/

QTAtomContainer sample; /* sample to store into*/

};

typedef struct QTCustomControlGetValueRecord QTCustomControlGetValueRecord;

typedef QTCustomControlGetValueRecord * QTCustomControlGetValuePtr;

Using pdActionCustomDoEditCommand to Handle Edit Commands

pdActionCustomDoEditCommand tells your control to handle edit commands if it allow focus and type in boxes.

All custom controls must implement this call if they support edit boxes.

struct QTCustomControlDoEditCommandRecord {

void * storage; /* storage for the control*/

long command; /* command to execute, return 0 here if processed*/

};

typedef struct QTCustomControlDoEditCommandRecord QTCustomControlDoEditCommandRecord;

typedef QTCustomControlDoEditCommandRecord * QTCustomControlDoEditCommandPtr;

typedef long QTParameterDialog;

enum {

elOptionsIncludeNoneInList = 0x00000001 /* "None" effect is included

in list */

};

typedef long QTEffectListOptions;

enum {

pdOptionsCollectOneValue = 0x00000001, /* should collect a single

value only*/

pdOptionsAllowOptionalInterpolations = 0x00000002, /* non-novice

interpolation options are shown */

pdOptionsModalDialogBox = 0x00000004, /* dialog box should be modal */

pdOptionsEditCurrentEffectOnly = 0x00000008, /* List of effects will not

be shown */

pdOptionsHidePreview = 0x00000010 /* Preview item will not be shown */

enum {

effectIsRealtime = 0 /* effect can be rendered in real time */

};

The following is a new API introduced in QuickTime 6.

QTGetEffectsListExtended

Provides for more advanced filtering of effects to be placed into the effect list.

QTGetEffectsListExtended (QTAtomContainer * list,
   long minSources,
   long maxSources,
   QTEffectListOptions getOptions,
   OSType majorClass,
   OSType minorClass,
   QTEffectListFilterUPP filterProc,
   void * filterRefCon);

Parameters

list

The effect list returned here.

minSources

The minimum number of sources that an effect must have to be added to the list. Pass –1 as this parameter to specify no minimum.

maxSources

The maximum number of sources that an effect can have to be added to the list. Pass –1 as this parameter to specify no maximum. The minSources and maxSources parameters allow you to restrict which effects are returned in the list, by specifying the minimum and maximum number of sources that qualifying effects can have.

getOptions

The options for populating the list.

majorClass

The major class to include, 0 for all.

minorClass

The minor class to include, 0 for all.

filterPro

Additional client filtering.

filterRefCon

A reference constant for the filter proc.

Discussion

This routine provides for more advanced filtering of effects to be placed into the effect list. Applications can filter on:

• the number of input sources

• effect major or minor class

• custom filtering through a callback

The callback is called for each effect which passes the other criteria for inclusion. If the callback returns a TRUE result, the effect is included in the list.

Note that your filter proc may receive multiple effects from various manufacturers. If you return TRUE for multiple effects of a given type, only the one with the higher parameter version number will be included.

If you wish other filtering such as effects from a given manufacturer, you can do this by returning FALSE for the other effects and TRUE for those that you prefer.

typedef CALLBACK_API( Boolean, QTEffectListFilterProcPtr )(Component

effect, long effectMinSource, long effectMaxSource, OSType majorClass, OSType minorClass, void *refcon);

typedef STACK_UPP_TYPE(QTEffectListFilterProcPtr) QTEffectListFilterUPP;

Introduced in QuickTime 6.

QTGetEffectsList, which returns a QT atom container holding a list of the currently installed effects components.

C interface file: Movies.h

QuickTime Effects Classes

With an ever-increasing number of effect components, it has become difficult for applications and users to navigate through the list. This section documents upcoming atoms that can be used for tagging effects into useful categories.

This will be of use to developers of applications that supply custom effect picking UI. It will also be of use for developers of effect components. Two groupings for effects are here defined: Major Class and Minor Class.

    #define kEffectMajorClassType       'clsa'

    #define kEffectMajorClassID         (1)

    #define kGeneratorMajorClass        'genr'  // zero source effects

    #define kFilterMajorClass           'filt'  // one source effects

    #define kTransitionMajorClass       'tran'  // multisource morph

                                                // effects

    #define kCompositorMajorClass       'comp'  // multisource layer

                                                // effects

    #define kMiscMajorClass             'misc'  // all other effects

    #define kEffectMinorClassType       'clsi'

    #define kEffectMinorClassID         (1)

    #define kGeneratorMinorClass        'genr'  // "Generators"

    #define kRenderMinorClass           'rend'  // "Render"

    #define kFilterMinorClass           'filt'  // "Filters"

    #define kArtisticMinorClass         'arts'  // "Artistic

    #define kBlurMinorClass             'blur'  // "Blur"

    #define kSharpenMinorClass          'shrp'  // "Sharpen"

    #define kDistortMinorClass          'dist'  // "Distort"

    #define kNoiseMinorClass            'nois'  // "Noise"

    #define kAdjustmentMinorClass       'adst'  // "Adjustments"

    #define kTransitionMinorClass       'tran'  // "Transitions"

    #define kWipeMinorClass             'wipe'  // "Wipes"

    #define k3DMinorClass               'pzre'  // "3D Transitions"

    #define kCompositorMinorClass       'comp'  // "Compositors"

    #define kEffectsMinorClass          'fxfx'  // "Special Effects"

    #define kMiscMinorClass             'misc'  // "Miscellaneous"

    #define kEffectMinorClassNameType   'clsn'

    #define kEffectMinorClassNameID     (1)

QuickTime Effects Presets

Some effects with complex parameters would like to provide the user with groups of useful parameter values that can be easily selected. This section documents an optional mechanism that can be used by effects to define these “presets.” Applications may also use these presets to present to the user a list of selectable effect parameters.

    #define kPresetNameType                 'pnam'

    #define kPresetNameID                   (1)

    #define kPresetPreviewPictureType       'ppct'

    #define kPresetPreviewPictureID         (1)

    #define kPresetSettingsType             'psst'

    #define kPresetSettingsID               (1)

// atom type       ID Child count

kEffectPresetType, 1, 3,

    {

    };

    kPresetNameType, kPresetNameID, noChildren,

        {

        string { "Top" };

        };

    kPresetPreviewPictureType, kPresetPreviewPictureID, noChildren,

        {

        lstring {

            $"08A0 0000 0000 0040 0056 0011 02FF 0C00"

            /* MORE PICTURE DATA HERE */

            $"7FE0 03AB 7FE0 03AB 7FE0 03AB 7FE0 00FF"

            };

        };

    kPresetSettingsType, kPresetSettingsID, 2,

        {

        };

        'pcnt', 1, 2,

            {

            };

            'twnt', 1, noChildren,

                {

                kParameterTypeDataFixed;

                };

            'data', 1, noChildren,

                {

                long { "0" };

                long { "65536" };

                };

        'angl', 1, noChildren,

            {

            Fixed { "0.0" };

            };

// atom type       ID Child count

kEffectPresetType, 2, 3,

    {

    };

    kPresetNameType, kPresetNameID, noChildren,

        {

        string { "Bottom" };

        };

    kPresetPreviewPictureType, kPresetPreviewPictureID, noChildren,

        {

        lstring {

        $"083C 0000 0000 0040 0056 0011 02FF 0C00"

        /* MORE PICTURE DATA HERE */

        $"0277 BF42 1F08 5FE8 001F 00FF"

            };

        };

    kPresetSettingsType, kPresetSettingsID, 2,

        {

        };

        'pcnt', 1, 2,

            {

            };

            'twnt', 1, noChildren,

                {

                kParameterTypeDataFixed;

                };

            'data', 1, noChildren,

                {

                long { "0" };

                long { "65536" };

                };

        'angl', 1, noChildren,

            {

            Fixed { "180.0" };

            };

None Codec Enhancements

QuickTime 6 includes an improved None codec (also known as the Raw codec because it deals with manipulations of uncompressed pixels). The new version provides the following enhancements:

• improved quality

• increased speed

• greater robustness

• significantly decreased memory usage, with little increase in code size.

In QuickTime 5.0.x and before, the None codec would always use point sampling. The new version uses point sampling in the fastest, lowest-quality mode, bilinear interpolation in a slower, medium-quality mode, and bicubic anti-aliasing in the slowest, highest-quality mode.

The enhanced None codec introduces two new quality levels beyond the point-sampling quality provided in the previous None codec:

• bilinear interpolation

• bicubic anti-aliasing

This quality is especially apparent in

(1) rotation,

(2) perspective,

(3) image size reduction, and

(4) image size zooming.

Bilinear interpolation is available with codecHighQuality.

codecMaxQuality yields either bicubic anti-aliasing or bicubic interpolation, depending on the complexity of the transformation: anti-aliasing is currently only available with pure scaling operations, not rotation or perspective. The anti-aliasing is designed to meet or exceed the quality produced by Adobe PhotoShop. When specifying codecNormalQuality, point-sampling is used.

When doing minor size changes or phase changes, there is little apparent difference in quality between bilinear and bicubic interpolation: the primary difference is in sharpness and contrast. This is especially noticeable after multiple generations of processing, where bilinear processing will lose sharpness and contrast, whereas bicubic interpolation tends to preserve it.

When zooming up by a factor of 4 or more, bilinear interpolation suffers from “stellation”: where stars are superimposed on the pixels. Bicubic interpolation yields more natural, rounded, smooth features without artifacts.

When decimating an image (that is, reducing its size), bicubic anti-aliasing produces the best possible quality. Bilinear interpolation can yield acceptable quality if only shrinking a small amount, but decimation by greater than a factor of 2 will cause aliasing, which is manifested as jaggies, disappearing detail, and “popping pixels.”

As expected, higher quality comes at a price. With point-sampling (codecNormalQuality) taking 1 T seconds, the others take approximately:

• 1 T: codecNormalQuality = point-sampling

• 3 T: codecHighQuality = bilinear interpolation

• 10 T: codecMaxQuality = bicubic interpolation or anti-aliasing

Using a higher quality may have a negative effect on frame rate, especially on older machines. Typically, codecMaxQuality is to be used for off-line, non-real-time applications, whereas codecHighQuality can be used successfully for real-time applications on faster machines. You might want to check the frame rate and throttle the quality as appropriate. Even faster machines can benefit from this throttling, because their frame rate can suffer on higher resolution images.

The new enhanced None codec is a complete implementation of its component interface. Complete implementation is defined as:

• 11 pixel formats for the source

• 11 pixel formats for the destination

• 8 transfer modes

• 3 quality levels

• full 3x3 matrix transformations, including rotation and perspective

Pixel formats:

• 8 bit color mapped

• 8 bit grayscale

• 16 bit BE555

• 16 bit LE555*

• 16 bit LE565*

• 24 bit RGB

• 24 bit BGR*

• 32 bit ARGB

• 32 bit ABGR*

• 32 bit BGRA*

• 32 bit RGBA*

(Note that formats flagged with an asterisk (*) are only available on Windows).

Transfer modes:

• Copy

• Dither Copy

• Transparent (chroma-key)

• Blend

• Straight alpha

• Alpha premultiplied to black

• Alpha premultiplied to white

• Straight alpha blend

Alpha-premultiplied-to-black is the fastest of the alpha compositing modes. For example, it is possible to transform a 32 bit ARGB PixMap by a 3x3 perspective transformation, interpolating it with bicubic interpolation, and alpha-compositing it to an 8-bit color-mapped PixMap––directly––one-pass.

More pixel formats (1, 2 and 4 bits) are supported, but in a less than desirable way, by relying on CopyBits and multiple instantiations of the enhanced None codec. Other transfer modes (for example, XOR) are feebly supported in the same manner.

Alpha is a first class component of 32 bit pixels. The previous None codec sometimes behaved badly with the alpha component, but the enhanced None codec preserves it and involves it in computations. The result of an alpha composition has a meaningful alpha component, which can then be used as a source for a subsequent alpha composition; using this, rendering can be optimized by caching partial composites of the static portions of scenes, requiring only the dynamic portions to be composited individually. From an architectural viewpoint, these alpha operations lend themselves then to a composition tree or DAG (directed acyclic graph), rather than a simple composition pipeline as limited in the previous None codec. This comes at no additional computational cost.

The enhanced None codec in QuickTime 6 is typically invoked using:

• MakeImageDescriptionForPixMap()

• DecompressSequenceBegin()

• SetDSequenceTransferMode()

• DecompressSequenceFrameS()

• CDSequenceEnd()

and other calls.

Unlike the previous None codec, there is a negligible penalty for startup, and matrix changes. In particular, the matrix can be changed every frame with no degradation of the frame rate. Thus, it can be used for immersive imaging applications, where a series of images are embedded in 3D.

For more information, see Ice Floe Note #23 at

http://developer.apple.com/quicktime/icefloe/dispatch023.html

The new enhanced None codec can be used as a general texture-mapped rendering and compositing engine, when accessed directly through the API. However, it is also invoked automatically by the Image Compression Manager (ICM) to assist other codecs, by the Sprite Media to implement animation, and by others.

Additional Still Image Metadata Support in Mac OS 9 and Windows

The JPEG and TIFF graphics exporters should be able to create Exif files containing application-specified metadata and thumbnail images. QuickTime for Mac OS X (10.1) provided this support, which is now also available in Mac OS 9 and Windows.

Boolean IsSecondImageThumbnail( GraphicsImportComponent gi )

{

    OSErr err;

    unsigned long saveIndex = 1;

    UserData userData = nil;

    Handle h = nil;

    Boolean isThumbnail = false;

    long count, i;

    GraphicsImportGetImageIndex( gi, &saveIndex );

    err = GraphicsImportSetImageIndex( gi, 2 );

    if( err ) goto bail;

    err = NewUserData( &userData );

    if( err ) goto bail;

    err = GraphicsImportGetMetaData( gi, userData );

    if( err ) goto bail;

    h = NewHandle( 0 );

    err = MemError();

    if( err ) goto bail;

    err = GetUserData( userData, h, kQTIndexedImageType, 1 );

    if( err ) goto bail;

    // Is kQTIndexedImageIsThumbnail present in the list?

    count = GetHandleSize( h ) / sizeof( OSType );

    for( i = 0; i < count; i++ ) {

        if( EndianU32_NtoB(kQTIndexedImageIsThumbnail) == ((OSType *)*h)[ i ] ) {

            isThumbnail = true;

            break;

        }

    }

bail:

    if( userData ) DisposeUserData( userData );

    if( h ) DisposeHandle( h );

    GraphicsImportSetImageIndex( gi, saveIndex );

    return isThumbnail;

}

New APIs For Creating Exif Files

The following are a group of new APIs available on Mac OS X, Mac OS 9, and Windows for creating Exif files.

GraphicsExportSetExifEnabled

Sets whether or not the graphics exporter component should create Exif files.

ComponentResult GraphicsExportSetExifEnabled (GraphicsExportComponent ci,
   Boolean enableExif );

GraphicsExportGetExifEnabled

Returns the current Exif export setting.

ComponentResult GraphicsExportGetExifEnabled (
   GraphicsExportComponent  ci,
   Boolean * exifEnabled );

GraphicsExportSetThumbnailEnabled

Sets whether or not the graphics exporter component should create an embedded thumbnail inside the exported file.

ComponentResult GraphicsExportSetThumbnailEnabled (
   GraphicsExportComponent  ci,
   Boolean                enableThumbnail,
   long                   maxThumbnailWidth,
   long                   maxThumbnailHeight );

GraphicsExportGetThumbnailEnabled

Returns the current thumbnail export settings.

ComponentResult GraphicsExportGetThumbnailEnabled (
   GraphicsExportComponent  ci,
   Boolean *              thumbnailEnabled,
   long *                 maxThumbnailWidth,
   long *                 maxThumbnailHeight );

Improved Movie Toolbox Support for Data Handlers

QuickTime 6 enhances the ability of third-party developers to add new types of data references through the introduction of QuickTime data handler components. These are called custom data handlers.

OSErr PutMovieIntoStorage ( Movie theMovie,
DataHandler dh,
const wide *offset,
unsigned long maxSize );

   
CreateMovieStorage (Handle dataRef,
OSType dataRefType,
OSType creator,
ScriptCode scriptTag,
long createMovieFileFlags,
DataHandler * outDataHandler,
Movie * newmovie);

OpenMovieStorage (Handle dataRef,
OSType dataRefType,
long flags,
DataHandler * outDataHandler);

CloseMovieStorage (DataHandler dh);

DeleteMovieStorage (Handle dataRef,
OSType dataRefType);

AddMovieToStorage (Movie theMovie,
DataHandler dh);

UpdateMovieInStorage (Movie theMovie,
DataHandler dh);

Movie FlattenMovieDataToDataRef (Movie theMovie,
long movieFlattenFlags,
Handle dataRef,
OSType dataRefType,
OSType creator,
ScriptCode scriptTag,
long createMovieFileFlags);

NewMovieFromStorageOffset (
Movie * theMovie,
DataHandler dh,
const wide * fileOffset,
short newMovieFlags,
Boolean * dataRefWasChanged);

void ChooseMovieClock (Movie m,
   long flags);

http://developer.apple.com/technotes/tn/tn2052.html

ComponentResult DataHGetInfo(DataHandler dh,
OSType what,
void *info);

ComponentResult DataHDeleteFile(DataHandler dh);

ComponentResult DataHSetMovieUsageFlags(
DataHandler dh,
long flags);

OpenADataHandler Extended

Predictably, you cannot use the OpenADataHandler (II-1159) routine to open data handlers to non-existent files. Attempting to do results in the function returning the error couldNotResolveDataRef and setting the returned data handler to NIL.

In QuickTime 6, this is still the case for requests to open data handlers for read-only access. However, if you make a request to open a data handler for write access (by passing kDataHCanWrite), OpenADataHandler will now return a configured data handler instead of NIL and an error, if the file doesn’t exist.

If you pass a kDataHCanWrite, a data handler will be created which you can use with DataHCreateFileWithFlags or with DataHCreateFile.

Advanced APIs

Two additional APIs have been introduced in QuickTime 6. Although their usage by developers may be rare, they are discussed here for the sake of completeness.

PutMovieForDataRefIntoHandle and NewMovieForDataRefFromHandle can be used by applications that directly read and write 'moov' atoms (also known as movie resources or public movies) containing data references that are self-references to the files read or written.

By way of quick review, data references within the media of movies may refer to either external files through full data references or to the file containing the ‘moov’ through a shorthand self-reference technique. This self-reference involves setting a data reference attribute to include the following flags:

kDataRefIsSelfContained     = (1 << 0)

and not including the full data reference. All such references are resolved to the file originally containing the 'moov' atom or public movie.

The already available PutMovieIntoHandle (II-1183) routine will create public movies but cannot update data references to be self-references. Also, NewMovieFromHandle can create a Movie from a public movie but cannot do so for public movie handles, including self-references. These limitations mean that these APIs cannot be used by applications that

(1) want to perform the direct reading of 'moov' resources from a file and then create a Movie or

(2) create a public movie containing self-references and then write that public movie to a file.

PutMovieForDataRefIntoHandle and NewMovieFroDataRefFromHandle accommodate the passing of the data reference that should be interpreted as the location of the 'moov' atom.

PutMovieForDataRefIntoHandle

This routine is roughly equivalent to the PutMovieIntoHandle API (II-1183)––but with one important difference. If the data reference and data reference type is passed, all media references to the same storage are converted to self-references in the resulting public movie handle. This ‘moov’ atom can be then written to the storage.

   
OSErr PutMovieForDataRefIntoHandle (
Movie theMovie,
Handle dataRef,
OSType dataRefType,
Handle publicMovie );

Introduced in QuickTime 6.

C interface file: Movies.h

NewMovieForDataRefFromHandle

This routine creates a Movie from the public movie handle in the same way as NewMovieFromHandle does––but with one important difference. If the public handle contains media data references that are self-references, NewMovieForDataRefFromHandle can convert self-references to references to the reference specified by dataRef and dataRefType. All other data references are not changed.

OSErr NewMovieForDataRefFromHandle ( Movie *theMovie,
Handle h,
short newMovieFlags,
Boolean *dataRefWasChanged,
Handle dataRef,
OSType dataRefType );

Introduced in QuickTime 6.

C interface file: Movies.h

MovieImportSetNewMovieFlags

Implemented by a movie import component to determine the flags originally passed to NewMovieFromDataRef and from a file.

   
ComponentResult MovieImportSetNewMovieFlags(
MovieImportComponent ci,
long newMovieFlags );

Introduced in QuickTime 6.

C interface file: QuickTimeComponents.h

Support for JDK 1.4

QuickTime for Java now includes support for JDK 1.4 (Windows only). These are internal changes that should be transparent to your application.

New JQTCanvas

JQTCanvas, a new class that has been added to the quicktime.app.display package, is a lightweight version of the QTCanvas class. It is intended to behave in exactly the same way as QTCanvas, but with the following enhancement: the JQTCanvas class supports scaling of Flash content that is added to it via a moviePlayer. You may use the setFlashScaling(boolean) method to turn this feature on and off. If you use this new feature, you may need to allocate extra memory, since an offscreen buffer must be created that is the size of the onscreen image.

New QTVR Authoring Classes

A number of new QuickTime VR classes have been added in this release of QuickTime for Java. These classes encapsulate the various VR atom types, and are designed to help developers who are doing QuickTime VR work. They include

• QTVRAtom

• QTVRAngleRange

• QTVRCubicFace

• QTVRCubicView

• QTVRHotSpotInfo

• QTVRLinkHotSpot

• QTVRWorldHeader

• QTVRNodeHeader

• QTVRNodeLocation

• QTVRObjectSample

• QTVRPanoImaging

• QTVRPanoSample

• QTVRString

• QTVRTrackRefEntry

For more information on these new VR classes, refer to the JavaDocs accompanying this release.

Improved QuickTime Client Streaming Support

A number of new classes have been added that extend QuickTime for Java client streaming functionality to include support for stored movies. This support is provided via the Sourcer object. These new classes include

• Sourcer

• SourcerCallbackParams

• SourcerInitParams

• SourcerLoopParams

• SourcerTrackParams

• SourcerTimingParams

Note that the QuickTime for Java Client Streaming API is currently not available on the Windows platform.

For more information on these new classes, refer to the JavaDocs accompanying this release.

New Sprite Handler APIs

The following new sprite handler APIs have been added to this release of QuickTime for Java:

• Flashmediahandler.java

  private static native int FlashMediaGetSupportedSwfVersion (

  int mh,

  byte[] path);

• Movie.java

  private static native short NewMovieForDataRefFromHandle (

  int[] theMovie,

  int publicMovieHandle,

  short newMovieFlags,

  byte[] dataRefWasChanged,

  int dataRef,

  int dataRefType);

  private static native int FlattenMovieDataToDataRef (

  int theMovie,

  int movieFlattenFlags,

  int dataRef,

  int dataRefType,

  int creator,

  short scriptTag,

  int createMovieFileFlags);

• SpriteMediaHandler.java

  private static native int SpriteMediaDisposeImage(int mh,

  int imageIndex);

  private static native int SpriteMediaNewImage (int mh,

  byte[] imageURL);

Recordability

QuickTime Player is now a recordable application. To take advantage of this new capability, you must use QuickTime Player in conjunction with an application that supports AppleEvent recording, such as Script Editor.

Using Script Editor to record a script, you need to make sure that both QuickTime Player and Script Editor are running. Then you click the record button in a script window. Any operation you perform in QuickTime Player will be recorded in the open script document.

Most features of QuickTime Player are recordable with the following exceptions:

• Import and Export are not recordable

• Sprite-related property panels are not recordable

• Music Track Instruments property panel is not recordable

• Printing operations are not recordable

The result of a AppleEvent recording session is rarely a finished script, but rather more like a summary of the operations you would like performed. A recorded script will have no error checking code nor if/then/else or repeat/until structures. Quite often, a recorded script will merely demonstrate the correct syntax for an operation and little more.

Terminology Changes

QuickTime Player introduces a number of new commands, classes, and properties, and well as modifications to existing terminology elements, discussed in this section.

    enter full screen  reference  -- display

        [bounds  point]  -- the desired target dimensions of the display

                            (height, width)

        [background color  rgb color]  -- the background color

    exit full screen  reference  -- display

    tell display 1 to enter full screen

    tell movie 1 to play

    tell movie 2 to play

    tell movie 3 to play

    tell display 1 to exit full screen

flip horizontal: Flip an object along the horizontal axis

    flip horizontal  reference  -- the object to flip

flip vertical: Flip an object along the vertical axis

    flip vertical  reference  -- the object to flip

resize: Scale an object

    resize  reference  -- the object to scale

        [by  small real]  -- the percent of current size

        [around  fixed point]  -- the point to resize around

rotate: Rotate an object by an arbitrary amount

    rotate  reference  -- the object to rotate

        by  small real  -- the amount of rotation (in degrees)

        [around  fixed point]  -- the point to rotate around

rotate left: Rotate an object 90 left

    rotate left  reference  -- the object to rotate

rotate right: Rotate an object 90 right

    rotate right  reference  -- the object to rotate

skew: Skew an object by an arbitrary amount

    skew  reference  -- the object to skew

        by  fixed point  -- the amount of skew

        [around  fixed point]  -- the point to skew around

translate: Translate the object some distance

    translate  reference  -- the object to translate

        by  fixed point  -- the distance to translate

replace: Replace the current selection with an object from the clipboard

    replace  reference  -- movie

invert: Invert an object

    invert  reference  -- the object to invert

save export settings: Save an exporters settings

    save export settings

        for  AVI/BMP/DV stream/Fast Start QTVR Movie/FLC/hinted movie/image sequence/interframe

 compressed VR object movie/MPEG4/picture/QuickTime media link/QuickTime movie/AIFF/System 7 sound/

wave/MuLaw/standard MIDI/text file  -- the desired file type

        [to  alias]  -- the destination file

        [replacing  boolean]  -- should the original file be deleted

first?

export: Export a movie or track to a file

    export  reference  -- the movie or track to export

        to  alias  -- the destination file

        as  AVI/BMP/DV stream/Fast Start QTVR Movie/FLC/hinted movie/image sequence/interframe

 compressed VR object movie/MPEG4/picture/QuickTime media link/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

        [using settings  alias]  -- the file containing the export settings

        [replacing  boolean]  -- should the original file be deleted first?

    make new movie with data {frame 6 of track "Video Track" of movie "QuickTime Sample Movie"}

    make new movie with data {track "Video Track" of movie "QuickTime Sample Movie"}

    make new track at first movie with data alias "myharddrive.myimage.jpeg"

    make new favorite with data "http://stream.qtv.apple.com/myevent.mov"

    make new favorite with file "myharddrive:mymovie.mov"

    show favorites window  boolean  -- show the favorites window

    show movie info window  boolean  -- show the movie info window

    show welcome movie automatically  boolean  [r/o]  -- always show the hot picks movie when the application launches

    bass gain  small integer  -- the bass setting for the track (-256..256) (not saved with the movie)

    sound balance  small integer  -- the balance of the movie (-128..128), where negative is left, 0 is center, and positive  is right

    treble gain  small integer  -- the treble setting for the movie (-256..256) (not saved with movie)

    preferred audio balance track  track  [r/o]  -- the preferred track to use for balance settings

    preferred audio gain track  track  [r/o]  -- the preferred track to use for bass and treble gain settings

    color table  palette  -- palette for the movie

    current chapter track  track  [r/o]  -- the currently active chapter track (may differ by language)

    current matrix  matrix  -- the matrix of the movie

    show detailed movie info window  boolean  -- show the movie property window

    show sound controls  boolean  -- show the sound controls in the LCD

    show video controls  boolean  -- show the video controls

    video brightness adjustment  small real  [r/o]  -- the adjustment to the video brightness (range is -1.0 to 1.0)

    video contrast adjustment  small real  [r/o]  -- the adjustment to the video contrast (range is -1.0 to 1.0)

    video tint adjustment  small real  [r/o]  -- the adjustment to the video tint (range is -0.25 to 0.25)

    video color adjustment  small real  [r/o]  -- the adjustment to the video color

    alternate  track  [r/o]  -- the alternate for this track

    bass gain  small integer  -- the bass setting for the track (-256..256) (not saved with movie)

    treble gain  small integer  -- the treble setting for the track (-256..256) (not saved with movie)

    mask  image  -- the mask of the track

    current matrix  matrix  -- the matrix of the track

    transfer mode  transfer mode unknown/dither copy/no dither copy/blend/transparent/straight alpha/premul

 white alpha/premul black alpha/straight alpha blend/composition  -- the transfer mode of the track

    class  type class  [r/o]  -- the class

    contents  type class  -- the contents of the matrix

    rgb color by numeric index

    class  type class  [r/o]  -- the class

    contents  type class  -- the contents of the matrix

    class  type class  [r/o]  -- the class

    contents  type class  -- the contents of the rgb color

    red  small integer  -- the mangnitude of the red component

    green  small integer  -- the mangnitude of the green component

    blue  small integer  -- the mangnitude of the blue component