Retired Document
Important: Apple recommends that developers explore QTKit and Core Video for new development in this technology area. See QTKit Framework Reference and Core Video Programming Guide for more information.
Flash Media Handler
This chapter describes the Flash media handler, which was introduced in QuickTime 4. The Flash media handler allows a Macromedia Flash SWF 3.0 file to be treated as a track within a QuickTime movie. If you are a content author or developer and need to create interactive vector animations on the Web using QuickTime and Flash, you should read this chapter.
QuickTime 4 extended the SWF file format to allow the execution of any of its wired actions. QuickTime 5 includes support for the interactive playback of SWF 4.0 files by extending the existing SWF importer, as well as the Flash media handler.
The chapter includes the following major sections:
Flash Media describes Flash, Macromedia’s popular authoring tool that lets content authors and developers create interactive vector animations. The section also discusses the Flash media handler, introduced in QuickTime 4, which allows a Macromedia Flash SWF 3.0 or SWF 4.0 file to be treated as a track within a QuickTime movie.
Flash Support in QuickTime discusses support for the interactive playback of SWF 4.0 files by extending the existing SWF importer and the Flash media handler.
Adding Wired Actions To a Flash Track discusses the code you need to add wired actions to a Flash track.
Flash Media
Flash is a vector-based graphics and animation technology designed for the Internet. As an authoring tool, Flash lets content authors and developers create a wide range of interactive vector animations. The files exported by this tool are called SWF (pronounced “swiff”) files. SWF files are commonly played back using Macromedia’s ShockWave plug-in. In an effort to establish Flash as an industry-wide standard, Macromedia has published the SWF File Format and made the specification publicly available on its website at
http://www.macromedia.com/software/flash/open/spec/ |
The Flash media handler, introduced in QuickTime 4, allows a Macromedia Flash SWF 3.0 or SWF 4.0 file to be treated as a track within a QuickTime movie. Thus, QuickTime extends the SWF file format, enabling the execution of any of its wired actions.
Because a QuickTime movie may contain any number of tracks, multiple SWF tracks may be added to the same movie. The Flash media handler also provides support for an optimized case using the alpha channel graphics mode, which allows a Flash track to be composited cleanly over other tracks.
QuickTime supports all Flash actions except for the Flash load movie action. For example, when a Flash track in a QuickTime movie contains an action that goes to a particular Flash frame, QuickTime converts this to a wired action that goes to the QuickTime movie time in the corresponding Flash frame.
QuickTime support for Flash 3.0 also includes the DoFSCommand
mechanism. This allows JavaScript routines with a specific function prototype to be invoked with parameters passed from the Flash track.
Figure 6-1 shows a screenshot from the QTFlashDemo.mov
, which demonstrates QuickTime 4 support for Flash files using Macromedia Flash interface elements. The movie includes an introductory animation, navigation linking to bookmarks in the movie, semi-transparent control interface, and titles layered over the movie.
Flash Support in QuickTime
QuickTime 5 includes support for the interactive playback of SWF 4.0 files by extending the existing SWF importer and the Flash media handler. This support is compatible with SWF 3.0 files supported in QuickTime 4.x.
Major features of Flash 4 include the following:
Text input through text fields
New Actions such as Set Property, Set Variable, If, Loop, etc
Action expressions
Dragging graphic
The following wired actions and an operand targeting a Flash track are added. These allow you to access data in a Flash track from wired actions.
kActionFlashTrackSetFlashVariable
kActionFlashTrackDoButtonActions
kOperandFlashTrackVariable
Two new QT events, kQTEventKey
and kQTEventMouseMoved
, are added to support keyboard input and mouse events in the Flash media handler. In addition, the QTEventRecord
structure is extended to accommodate additional parameters for those events.
For more details about Flash 4 features, refer to the Flash documentation available from Macromedia at
http://www.macromedia.com/software/flash/ |
Wired Actions and Operands
The following wired actions and operand let you target a Flash track and access data in a Flash track from wired actions.
kActionFlashTrackSetFlashVariable
Sets the specified Flash action variable to a value. Parameters are:
- path(cstring)
Specifies the path to the Flash button to which the variable is attached.
- name(cstring)
Specifies the name of the Flash variable.
- value(cstring)
Specifies the new value of the Flash variable.
- updateFocus(Boolean)
True if the focus is to be changed.
kActionFlashTrackDoButtonActions
Performs action(s) attached to the specified button.
- Path(cstring)
Specifies the path to the button to which the action is attached.
- ButtonID(long)
The ID of the button.
- Transition(long)
Sends a mouse transition message to the object and whatever Flash actions are associated with that transition on the object that should be performed. The values are specific Flash transition constants.
kOperandFlashTrackVariable
Returns the value of the specified Flash action variable. Parameters are:
- path(cstring)
Specifies the path to the Flash button to which the variable is attached.
- name(cstring)
The name of the Flash variable.
QT Events
The first new QT Event is
kQTEventKey = FOUR_CHAR_CODE('key ') |
The key event parameters are as follows:
qtevent.param1: key |
qtevent.param2: modifiers |
qtEvent.param3: scanCode |
The second new QT Event is
kQTEventMouseMoved = FOUR_CHAR_CODE('move'), |
which indicates that the mouse has moved. There are no parameters other than the location.
The new version 2 format of the QT Event record is shown next:
struct QTEventRecord { |
long version; /* version is 2 for the new format */ |
OSType eventType; |
Point where; |
long flags; |
long payloadRefcon; /* fields from here down only present |
if version >= 2*/ |
long param1; |
long param2; |
long param3; |
}; |
Note that the value of the version field indicates the format of the record. If it is 2, then the record is in the new format.
Importing a Flash Movie
The Flash importer sets the following settings by default in order to simulate the playback experience in the Flash player. This should work for most of the time, but it may be necessary to change some of them to suit your needs. It is recommended to review these options before you save your imported Flash movie as a QuickTime movie.
The Auto Play flag is on, meaning the movie will play as soon as it is opened (same as in QuickTime 4).
The Loop flag is on, meaning the movie will play repeatedly (same as in QuickTime 4).
The Play All Frames is on in QuickTime Player. With this option on, QuickTime Player renders every frame of the Flash movie with the rate of the movie set to zero (same as in QuickTime 4).
Also, if the Flash movie contains “streaming sound” (Macromedia’s term for running sound as opposed to short sound triggered by an event), the Flash media handler drops frames in order to catch up with the sound playback, even if the Play All Frame is on (new to QuickTime 5.)
Apple has addressed the issue of having multiple Flash tracks with text fields. The effects of the change are:
You can navigate through text fields not only in a single Flash track, which you can do now.
In addition, if you have more than one Flash tracks with a text field, hitting the Tab key will take you to the next Flash track instead of rotating over to the first field in the same track. Shift-tab works as well but goes backward.
Adding Wired Actions To a Flash Track
The sample code on the QuickTime SDK, AddFlashActions
, provides the code you need to add wired actions to a Flash track. It may also be useful to download the Macromedia SWF File Format Specification at http://www.macromedia.com/software/flash/open/spec/
, as well as the SWF File Parser code at the Macromedia Web site.
This section explains the steps you need to follow in order to add wired actions to a SWF 3.0 file.
Extending the SWF Format
QuickTime 4 extends the SWF file format to allow the execution of any of its wired actions, in addition to the much smaller set of Flash actions. For example, you may use a SWF file as a user interface element in a QuickTime movie, controlling properties of the movie and other tracks. QuickTime also allows SWF files to be compressed using the zlib data compressor. This can significantly lower the bandwidth required when downloading a SWF file when it is in a QuickTime movie.
By using wired actions within a Flash track, compressing your Flash tracks, and combining Flash tracks with other types of QuickTime media, you can create compact and sophisticated multimedia content.
The SWF File Format Specification consists of a header followed by a series of tagged data blocks. The types of tagged data blocks you need to use are the DefineButton2
and DoAction
. The DefineButton2
block allows Flash actions to be associated with a mouse state transition. DoAction
allows actions to be executed when the tag is encountered. These are analogous to mouse-related QT event handlers and the frame loaded event in wired movies.
Flash actions are stored in an action record. Each Flash action has its own tag, such as ActionPlay
and ActionNextFrame
. QuickTime defines one new tag: QuickTimeActions
, which is 0xAA
. The data for the QuickTime actions tag is simply a QT atom container with the QuickTime wired actions to execute in it.
There are also fields you need to change in order to add wired actions to a SWF file. Additionally, there is one tag missing from the SWF file format that is described below.
What You Need to Modify
For defineButton2
, you need to modify or add the following fields: file length, action records offset, the action offset, the condition, the record header size portion, and add action record.
File Length
A 32-bit field in the SWF file header.
RecordHeader
for the defineButton2
RecordHeader
contains the tag ID and length. You need to update the length. Note that there are short and long formats for record headers, depending on the size of the record. The tag ID for defineButton2
is 34.
ActionRecordsOffset
The action records offset, a 16-bit field, is missing from the SWF File Format Specification. It occurs between the flags and buttons fields. It is initially set to 0 if there are no actions for the button. If there are actions for the button, then it must contain the offset from the point in the SWF file following this 16-bit value to the beginning of the action offset field.
DefineButton2 = |
Header |
ButtonID |
Flags |
ActionRecordsOffset (this is missing from the spec) |
Buttons |
ButtonEndFlag |
Button2ActionCode |
ActionOffset |
Condition |
Action [ActionRecords] |
ActionEndFlag |
ActionOffset
There is one action offset per condition (mouse overDownToIdle
). This is the offset used to skip over the condition and the following actions (the ActionRecord
) for the condition. You need to update this value when adding actions.
Condition
The condition field is roughly equivalent to a wired movie event. The actions associated with button state transition condition are triggered when the transition occurs. You need to add or edit this field.
Actions
Flash actions each have their own action tag code. QuickTime actions use a single QuickTime actions code: 'AA'
. You may add a list of actions to a single QuickTime actions tag.
The format of the QuickTime actions tag is as follows:
1 byte: // Tag = 'AA' |
2 bytes: // data length (size of the QTAtomContainer) |
n bytes // the data which is the QTAtomContainer holding the |
// wired actions |
DoAction
For DoAction
, you need to modify a subset of the defineButton2
fields in the same manner as described above. These fields are file length, the record header size portion, and the action record.
Note that you need to write the length fields in little-endian format.
Copyright © 2003, 2009 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2009-06-01