Advanced Search

Log In | Not a Member?

Contact ADC

< Previous PageNext Page > Hide TOC

Media Skins

QuickTime Player normally displays movies in a rectangular display area within a draggable window frame. The frame has a brushed-metal appearance and rounded control buttons. The exact controls vary depending on the movie’s controller type, with most movies having the standard Movie Controller, and VR movies having the VR Controller.

If the movie’s controller is set to the None Controller, QuickTime Player displays the movie in a very narrow frame with no control buttons. This allows you to display a movie without controls, or to create your own controls using a Flash track or wired sprites.

Until now, however, QuickTime Player always displayed your movie in a rectangular display area surrounded by a frame of some kind, with the frame providing a draggable area for the viewer to relocate the movie on the desktop.

In QuickTime 5, you can customize the appearance of QuickTime Player by adding a media skin to your movie. A media skin specifies the size and shape of the window that the movie is displayed in. A media skin also specifies which part of the window is draggable. Your movie is not surrounded by a frame. No controls are displayed, except those that you may have embedded in the movie using Flash or wired sprites.

For example, suppose you’ve created a movie with a curved frame and wired sprite controls, as shown in Figure 1-8.

Figure 1-8  A QuickTime movie with custom frame and wired sprite controls

Now suppose you want to add a media skin that specifies a window the size and shape of your curved frame, and a draggable area that corresponds to the frame itself.

If the movie is then played in QuickTime 5, your movie appears in a curved window, as shown in Figure 1-9, with the areas that you have specified acting as a draggable frame, as if you had created a custom movie player application.

Figure 1-9  A skinned movie in QuickTime 5, which appears as if you had created a custom movie player application

Note that you don’t need to assign the None Controller to a movie with a media skin (although you can). If the VR Controller or Movie Controller is assigned to your movie, the controller’s keyboard equivalents operate when your window is active, even though the controller is not displayed. The space bar starts and stops a linear movie, for example, while the shift key zooms in on a VR panorama. You can disable this feature by assigning the None Controller.

Media skins have no effect when a movie is played by the QuickTime browser plugin or other QuickTime-aware applications, such as Adobe Acrobat. However, developers can modify their applications to recognize movies that contain Media Skins, and to retrieve the shape information.

In this section:

Creating Media Skins
Current Limitations
Adding Media Skins Using the QuickTime API
Adding Custom Media Skins with AppleScript
Media Skin Droplet
Running the Script

Creating Media Skins

A media skin can be added to a movie using a text editor, a graphics program such as Adobe Photoshop, and QuickTime Player (Pro version).

In a typical case, you might want to replace QuickTime Player’s brushed-metal frame with one of your own design, as shown in Figure 1-10. Here are the steps that you would follow:

1. Create an image of your new frame using a graphics program, or perhaps scan in a photo of an actual device.

Figure 1-10  A newly created frame with space for controls and movie playback that replaces QuickTime Player’s brushed-metal frame

1. Open this image in QuickTime Player and add it to an existing movie as a background image, as shown in Figure 1-11.

Figure 1-11  A new frame image added to an existing QuickTime movie as a background image

1. You would also typically create your own movie controls, using Flash or wired sprites (and a wired sprite editor such as LiveStage Pro or Adobe’s GoLive), and add these as a Flash track or sprite track on top of your frame image, as shown in Figure 1-12. Call this Framed.mov.

Figure 1-12  Movie controls added as a Flash track or wired sprite track on top of your frame image

1. Create a mask image the size and shape of your frame (Figure 1-13). This image defines the window created when your movie plays. The image should be black where you want your window, and white elsewhere. The image can be a BMP, GIF, PICT, or any other format that QuickTime understands. Call this WinMask.pct.

Figure 1-13  A mask image which is the size and shape of your frame

1. Create a second mask image the size and shape of the draggable part of your frame (Figure 1-14). Typically, this would be the same as your first mask, with white areas where your text, video, and controls will appear. Again, this should be saved as a black-and-white image in a format that QuickTime can display. Call this DragMask.pct.

Figure 1-14  A second mask image which is the size and shape of the draggable part of your frame

1. Using a text editor, create a small file with the following syntax:

   <?xml version="1.0"?>

   <?quicktime type="application/x-qtskin"?>

   <skin>

   <movie src="Framed.mov"/>

   <contentregion src="WinMask.pct"/>

   <dragregion src="DragMask.pct"/>

   </skin>

2. Save as plain text, with the .mov file extension. Call this SkinXML.mov.

3. Open SkinXML.mov using QuickTime Player. Save as a self-contained movie. Call this Finished.mov.

   Important:  Be sure to save your movie, in this case Finished.mov, as a self-contained movie, and distribute the self-contained version, not the XML text file. The XML text file is dependent on external files and will not Fast Start over the Internet. The self-contained version will Fast Start.

You can now put Finished.mov on a CD, email it to a friend, or embed a link to it in a Web page. You can target the link to open your movie in QuickTime Player using the EMBED tag. For example:

<EMBED SRC="poster.qtif" TYPE="image/x-quicktime" HEIGHT=120 WIDTH=160  HREF="Finished.mov" TARGET="quicktimeplayer" >

This tag would embed a QuickTime image file named poster.qtif in a Web page. If the viewer clicks the image, QuickTime will launch Finished.mov in the QuickTime Player application.

To launch Finished.mov automatically, without the viewer clicking anything, you add AUTOHREF="true" to the EMBED tag.

The example just given uses a static image as a custom frame, but remember: a media skin just provides masks to use when displaying your movie. Any visual media type can show through the masks, including motion video and special effects, such as those possible with the QuickTime cloud or fire effects.

Any part of your movie can be made into a draggable region. However, tracks that respond to mouse events, such as VR panorama tracks or wired sprite tracks, should not be covered by a drag mask — the drag behavior prevents mouse events from reaching underlying tracks.

Current Limitations

Currently, a movie can have only one skin track. You cannot dynamically enable or disable skin tracks. The skin track’s masks are stored in the movie file as 1-bit pixel depth PICTs and cannot be changed dynamically.

Note that skins are not available in the current release of Mac OS X.

Adding Media Skins Using the QuickTime API

You can also add a media skin to a movie programatically –– for example, to enhance a movie editing application.

You could do this by mimicking the steps just described in the section “Creating Media Skins.” That is, you can generate a movie file, a pair of black-and-white image files, and a small XML text file that points to them, then call a movie importer to put them all together, flatten and save.

But it’s simpler to add a media skin to a movie in memory without going through an XML skin importer. The process is as follows:

1. Locate two black-and-white PICT files, or create two PICT images in RAM, to act as a window region mask and a drag region mask (You can use graphic importer and exporter components to convert a BMP or GIF to a PICT). See Figure 1-13 and Figure 1-14 for examples of these kinds of images.

2. Create a PicHandle that points to each mask image.

3. Add a new track to the movie.

4. Add a media of type 'skin' to the new track.

5. Tell the media handler to put the masks in a public resource.

6. Flatten and save.

The code snippet shown in Listing 1-2 provides a general outline of how you can add a media skin programmatically to a QuickTime movie, and is intended primarily as a guide to the process –– not as actual working code.

Listing 1-3, however, is working code that walks you through the various steps you need to follow in order to add media skins programmatically to a QuickTime movie.

Listing 1-2  A general outline of how you add a media skin to a QuickTime movie

//Adding a skin without using the importer

// Somehow create a picture handle:

    PicHandle winRgnHndl = nil;

    PicHandle dragRgnHndl = nil;

    winRgnHndl = MyMagicalCode();

    dragRgnHndl = MyMagicalCode();

    // create a new track

    theTrack = NewMovieTrack(myMovie, ((Fixed)movieBox.right) <<

                            ((Fixed)16, movieBox.bottom) << 16, 0);

    // must have someplace for the sample data to go

    // could use BeginMediaEdits, or...

    // create a cool handle that the HandleDataHandler can deal with,

    // so I can add this stuff in ram without needing a file

    dataRef = NewHandleClear(5);

    atomHeader[0] = EndianU32_NtoB(8);

    atomHeader[1] = EndianU32_NtoB('data');

    PtrAndHand(atomHeader, dataRef, 8);

    // add a skin media structure to the movie track

    theMedia = NewTrackMedia(theTrack, 'skin', movieTimeScale, dataRef,

                             HandleDataHandlerSubType);

    // retrieve media handler reference so we can call it

    mh = GetMediaHandler(theMedia);

    // tell the media handler to add the masks

        // 'skcr' is skin content region

        // 'skdr' is skin drag region

        // final parameter is length -- set to 0 for an allocated handle

    err = MediaSetPublicInfo(mh, 'skcr', winRgnHndl, 0);

        if (err) goto bail;

    err = MediaSetPublicInfo(mh, 'skdr', dragRgnHndl, 0);

        if (err) goto bail;

    // dispose of the Handle when done

    DisposeHandle(dataRef);

    dataRef = nil

Listing 1-3  Adding media skins programmatically to a QuickTime movie

OSErr QTSkin_AddSkinTrack (Movie theMovie){

        Track myTrack = NULL; // the skin track

        Media myMedia = NULL; // the skin track's media

        Rect myRect;

        MediaHandler myHandler = NULL;

        PicHandle myContentPic = NULL; // window mask

        PicHandle myDragPic = NULL; // drag mask

        OSErr myErr = paramErr;

        if (theMovie == NULL)

            goto bail;

// elicit the two pictures we need from the user

        myContentPic = QTSkin_GetPicHandleFromFile();

        if (myContentPic == NULL)

            goto bail;

        myDragPic = QTSkin_GetPicHandleFromFile();

        if (myDragPic == NULL)

            goto bail;

// get the movie's dimensions

        GetMovieBox(theMovie, &myRect);

        MacOffsetRect(&myRect, -myRect.left, -myRect.top);

// create the skin track and media

        myTrack = NewMovieTrack(theMovie, FixRatio(myRect.right, 1),

                                FixRatio(myRect.bottom, 1), kNoVolume);

        if (myTrack == NULL)

            goto bail;

        myMedia = NewTrackMedia(myTrack, FOUR_CHAR_CODE('skin'),

                                GetMovieTimeScale(theMovie), NULL, 0);

        if (myMedia == NULL)

            goto bail;

// find a media handler that understands skins

        myHandler = GetMediaHandler(myMedia);

        if (myHandler == NULL)

            goto bail;

// tell the media handler to add

// the skin content picture

        myErr = MediaSetPublicInfo(myHandler, FOUR_CHAR_CODE('skcr'),

                                    (void *)myContentPic, 0);

        if (myErr != noErr)

            goto bail;

// now add the skin drag picture

        myErr = MediaSetPublicInfo(myHandler, FOUR_CHAR_CODE('skdr'),

                                    (void *)myDragPic, 0);

        if (myErr != noErr)

            goto bail;

// note: the last parameter passed to

// MediaSetPublicInfo is the data size;

// pass 0 for an allocated handle

// add the media to the track

        myErr = InsertMediaIntoTrack(myTrack, 0, 0,

                GetMediaDuration(myMedia), fixed1);

// skin tracks should be disabled...

        SetTrackEnabled(myTrack, false);

bail:

    if (myContentPic != NULL)

            KillPicture(myContentPic);

    if (myDragPic != NULL)

            KillPicture(myDragPic);

    return(myErr);

}

Adding Custom Media Skins with AppleScript

QuickTime 5 provides additional AppleScript support in the QuickTime Player application, which is discussed in the section “AppleScript Changes and Additions.” The QuickTime Player scripting dictionary, for example, contains new commands and properties that can be used to automate many movie-editing and playback tasks.

This section describes how you can create an AppleScript droplet with a custom media skin (the code for this droplet is already supplied). Droplets are special AppleScript applications that respond to files and folders dragged onto their icon. Each droplet has properties and parameters that can be set by double-clicking the droplet and clicking the “Set Prefs” button in the main dialog.

In this example, the droplet automates the process of creating a QuickTime movie with a media skin.

Refer to <http://www.apple.com/applescript/qtas5/qtas5p2.htm> for a collection of example scripts that are available in QuickTime 5.

Media Skin Droplet

The script of the media skin droplet assembles the components of a media skin movie and saves the results as a self-contained QuickTime movie file. This section describes how the script works and the steps required to use the example files included with the script. Note that this script only processes standard QuickTime movie files of file type “MooV”.

Creating the Media Skin Image Files

To create a custom media skin for your movies, you need to create three specific image files:

• The media skin. This image (Figure 1-15) will be the window in which the movie is played. It can be of nearly any shape or size.

In the example included with this script, there is a simple media skin file that adds a standard border and title bar to the movie. This image is designed to display a movie having a width of 240 pixels and a height of 180 pixels. The blue region defines the area to display the video content of the movie.

Note that the offset of the top left of the blue region is 6 pixels horizontally and 22 pixels vertically from the top left of the media skin image. The script uses these measurements in order to place the video track in the corrext position over the media skin background. Note also that the size and offset info has been overlaid on the media skin image.

Figure 1-15  The media skin image with size and offset information overlay

• The drag mask image. This image (Figure 1-16) defines the areas of the window that can be clicked by the user to drag the window. The black regions of the image will be the clickable areas of the finished window. In this example, the title bar and sides of the movie will be the drag regions.

Figure 1-16  The drag mask image with black region specified as clickable areas

• The window mask image. This image (Figure 1-17) defines the visible area of the media skin window. Black regions will be visible to the user, white areas will be invisible. In this example, the entire area defined by the media skin image will be visible.

Figure 1-17  The window mask image

Transparent Overlay Media Skins

If you want the media skin to partially cover the source video, you need to fill the area to be transparent with a solid color of a specific RGB value, such as White, Black, %50 Gray, or 100% Blue.

In the following example image (Figure 1-18), the QuickTime Q has been filled with %50 Gray. The script preferences can be set to adjust the track’s operation color and transfer mode for this value, and the center of the Q image will become transparent when the skinned movie is created.

Figure 1-18  The QuickTime Q filled with 50% gray

Setting the Script Preferences

The script droplet relies on preferences, set by the user, to locate and manipulate the essential files. This particular script is designed to look for the various image files in the same folder as the droplet. If the essential image files are not in the same folder as the script, the script will not execute.

You can make copies of this droplet to be placed in other folders containing your various media skin files. You set the preferences for each droplet to work with its neighbor files.

To set the preferences for the droplet, you double-click its icon in the Finder to summon the status dialog (Figure 1-19). The dialog shows the current settings for the various script preferences. Click the “Set Prefs” button to set each of the script preferences.

Figure 1-19  The status dialog to set preferences

The first three preferences are for identifying the image files to be used by the script when constructing the media skin movie.

In the first dialog (Figure 1-20), enter the name of the image file which will be used as the media skin background. You may either enter the name in the input field or click the “Choose File” button to locate the appropriate file. The script will then place the name of the chosen file in the input field for you.

Figure 1-20  The name of the image file dialog

After you have entered the name of the appropriate media skin image file (Figure 1-21), click the “OK” button to proceed.

Figure 1-21  Entering the name of the appropriate media skin image file

You repeat this process in the forthcoming dialogs for identifying the window mask image and the drag mask image.

After inputting the names of the other files, two successive dialogs appear, asking you to enter the offset to be used to position the video track against the chosen media skin background. These measurements depend on the design of your media skin.

In the first dialog (Figure 1-22), you enter the horizontal offset (in pixels) from the left of the media skin image to the left of the video display area.

Figure 1-22  The horizontal offset dialog

In the second dialog (Figure 1-23), you enter enter the vertical offset (in pixels) from the top of the media skin image to the top of the video display area.

Figure 1-23  The vertical offset dialog

The next dialog (Figure 1-24) determines if you want the media skin image to be placed behind the source video or in front of the source video. Media skin images placed over the source video must have areas of a solid color that will be made transparent during the creation of the skinned movie.

Figure 1-24  The dialog that asks if you want the media skin placed behind the source video or in front of it

If you clicked the “Yes” button, a list dialog (Figure 1-25) appears from which you can choose the color which the script will make transparent. If your overlay color is not in the list, you may enter its RGB values individually by clicking the “Other” button at the bottom of the list dialog.

Figure 1-25  A list dialog that lets you choose the color that script makes transparent

If you clicked the “Other” button, a series of three dialogs will prompt you for each of the RGB values for the color to be made transparent. Each color is specified as a list of individual Red, Green, and Blue values: {Red value, Green value, Blue value}. Each individual RGB color component is an integer between 0 and 65535, with 0 being the minimum and 65535 being the maximun value.

For example, White is {65535, 65535, 65535}, Black is {0, 0, 0}, 100% Red is {65535, 0, 0}, 50% Gray is {32768, 32768, 32768}, etc. Note that the values you enter in these dialogs must exactly match those of the area in the overlay image that is meant to be transparent.

Figure 1-26  One of three dialogs that prompt you for each of the RGB values for the color to be made transparent, in this case the Red component

The final two preference dialogs are for setting the playback properties.

Click the “Yes” button if you want the movie to automatically start playing when opened.

Figure 1-27  Preference dialog

Click the “Yes” button if you want the movie to automatically close when it has finished playing.

Figure 1-28  Another preference dialog

After setting the property, the script will return to the status dialog (Figure 1-29). Click the “Done” button to exit the script.

Figure 1-29  The status dialog

If the media skin image is set to overlay, the operation color name or value will be displayed in the status dialog (Figure 1-30).

Figure 1-30  The color name or value displayed in the status dialog

Running the Script

To use the script, you drag a movie file, or multiple files, or folders of movie files onto the droplet. A dialog (Figure 1-31) appears prompting you for the destination folder for the finished files.

Figure 1-31  Specifying the destination folder for finished files

Once chosen, a media skin copy of each dragged-on movie is created and placed into this folder.

Completed Examples

Figure 1-32 (top) shows a completed example of a basic 240 x 180 skinned QuickTime movie, with standard border and title. In this case, the airplane is shown flying diagonally from the lower portion of the screen to the upper. Figure 1-32 (bottom) shows a completed example of a 144 x 108 overlaid skinned Q with the airplane flying inside the Q.

Figure 1-32  Two examples of skinned movies, one (top) with a standard border and title bar, the other (bottom) with a QuickTime Q overlaid

< Previous PageNext Page > Hide TOC

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice