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

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.

Figure 6-1  Flash interactivity in a QuickTime movie
Flash interactivity in a QuickTime 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:

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.

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