Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

< Previous PageNext Page > Hide TOC

Getting Started With SMIL

This section shows you how to work with SMIL to create a basic layout, define display regions, create a timeline with sequential and parallel media elements, specify media elements and set their durations, and make an element into a clickable link. This section also illustrates a technique to show different elements to different viewers using a switch.

In this section:

Overview
SMIL Structure
Layout
The Body
Clickable Links
Throwing a Switch


Overview

Because SMIL presentations are described by text files, you can create or edit a SMIL presentation using a text editor, and automatically generate a SMIL document using any script language that creates text files. A SMIL document specifies what media elements to present, and where and when to present them. Each media element is specified by a URL.

A SMIL presentation can use any media elements that QuickTime can play, including still images, audio, text, QuickTime movies, sprite animations, live streams, VR panoramas and VR object movies. The URL of a media element can point to local or remote media, using any format that QuickTime supports, including file access, HTTP, and RTSP.

Like the tracks in a QuickTime movie, the media elements in a SMIL presentation can be sequenced, overlapped, or offset in time and space. In addition, SMIL lets you select from a set of elements based on things like the user’s language or Internet connection speed. A SMIL presentation is similar to a QuickTime movie that depends on external media files.

SMIL Structure

SMIL is based on XML, which is more rigidly structured that HTML, but it uses the same familiar <tag> and </tag> syntax.

SMIL is different from HTML in that all the tags are case-sensitive (always lowercase) and all tags have to be explicitly ended—either there are a pair of tags that enclose other elements (<tag parameters> elements </tag>) or a tag is self-contained and ends with “/>” (<tag parameters />).

SMIL also differs from HTML because HTML routinely mixes structure and content together in the same document, whereas SMIL normally does not. Where an HTML document contains text to be displayed, a SMIL document would contain the URL of a text file instead.

Like HTML, a SMIL document has a head and a body. The structure of a SMIL file is shown below.

<smil>
    <head>
        <layout>
            <!-- layout tags -->
        </layout>
    </head>
 
    <body>
        <!-- body tags -->
    </body>
</smil>

All the layout information is specified in the head. The head controls the physical layout, and where things are seen on screen. The media elements are listed in the body, which controls the temporal sequencing––that is, when, what, and where (region).

Layout

The layout specifies the whole display area for the presentation, then defines regions where individual media elements can be displayed.

Root Layout

A SMIL layout always starts with a <root-layout /> tag that gives the dimensions of the display area in pixels and assigns a background color.

<layout>
    <root-layout id="main" width="320" height="240"
    background-color="red" />
</layout>

The id parameter gives the presentation a name; it can be anything you like. The height and width parameters define the display area for the presentation in pixels. You can specify the background color using hexadecimal values ("#FF0000") or names ("red"). The following is a very simple SMIL document—it’s just a red rectangle, but you can play it using QuickTime Player:

<smil>
    <head>
        <layout>
            <root-layout id="main" width="320" height="240"
            background-color="red" />
        </layout>
    </head>
    <body> </body>
</smil>

Regions

The layout also defines regions within the display area (“Figure 9-1”). Regions themselves are invisible, but they define areas where visual media elements can be displayed. Regions can be positioned anywhere in the display area and can overlap.

A layout that specifies a root layout and two regions:

<head>
    <layout>
        <root-layout id="main" width="320" height="240"
            background-color="red"/>
 
        <region id="r1" width="160" height="120" />
        <region id="r2" width="50%" height="100%"
        left="100" top="0" />
    </layout>
</head>

The first region is named r1, and is 160 x 120 pixels, extending from the top left corner of the display area (the default position for a region).

The second region, r2, is half as wide as the display area (width="50%) and fills it from top to bottom (height="100%"). Region r2 is offset 100 pixels from the left edge of the display area (left="100"). Since the first region is 160 pixels wide, the two regions overlap by 60 pixels.


Figure 9-1  Defining first and second regions

Defining first and second regions

The <region /> tag accepts the following parameters:

If you want to set the top or left parameter, you must specify both top and left as a pair, even if one of them is zero.

By default, a region extends from the top-left corner of the display area. You can change this by specifying a top and left offset. For example, top="50%" left="100" creates a region whose top-left corner is halfway down and 100 pixels from the left edge of the display area.

When regions overlap, one lies on top of the other. By default, a region defined later in the layout is on top of any regions defined earlier. You can set the layering explicitly using the z-index parameter. The layer with the highest z-index value is on top. (Note that in QuickTime movies, the layer with the lowest value is on top.) For example, the following layout defines three regions.

<region id="r1" width="160" height="120" z-index="3" />
<region id="r2" width="160" height="120" z-index="2" />
<region id="r3" width="160" height="120" z-index="1" />

The three regions overlap completely, with r1 on top, r2 in the middle, and r3 at the bottom of the pile. If no z-index values had been specified, the layering would be reversed, with the last-defined region on top.

The following is a SMIL document with two overlapping regions. It looks like a red rectangle when you play it using QuickTime Player. Because regions are invisible, they just define areas where media elements can be displayed.

<smil>
    <head>
        <layout>
            <root-layout id="main" width="320" height="240"
            background-color="red"/>
 
            <region id="r1" width="160" height="120" />
            <region id="r2" width="50%" height="100%" left="100"
            top="0" fit="fill" />
        </layout>
    </head>
    <body> </body>
</smil>

The Body

The body of a SMIL document specifies what media elements to present, which regions to display the visual elements in, and a timeline for the presentation.

The timeline groups media elements in two ways: things that happen in sequence and things that happen in parallel. If you don’t specify whether elements should be played sequentially or in parallel, QuickTime plays them in sequence. Sequences are surrounded by the <seq> and </seq> tags. Media elements in a sequence are presented one after the other—each element is presented after the previous element ends. There are different ways to determine when an element should end.

Media elements such as audio and video have an inherent duration, so they end when you would expect them to. For example:

<seq>
    <audio src="audio1.mp3" />
    <audio src="audio2.aiff" />
    <audio src="audio3.wav" />
</seq>

Note that audio components have no visual part, so a region is not defined.

This sequence plays three audio files in a row. Each element ends when the audio has played all the way through. As soon as one element ends, the next begins. Media elements such as still images and text have no inherent duration, so they’re usually assigned explicit durations:

<seq>
    <image src="image1.jpg" region="r1" dur="5 sec" />
    <image src="image2.gif" region="r1" dur="7 sec" />
</seq>

In this example, the first image ends after being displayed for 5 seconds, then the second image appears and is displayed for 7 seconds. If you specify an explicit duration for an element that has its own inherent duration, it either ends when it normally would or after the duration you specify, whichever comes first.

Media elements that are displayed at the same time are surrounded by the <par> and </par> tags. Parallel elements are presented starting at the same time, but they don’t necessarily end at the same time. For example: 

<par>
    <audio src="themesong.mp3" />
    <image src="poster.jpg" region="r1" dur="30 sec" />
    <text src="lyrics.txt" region="r2" dur="30 sec" />
</par>

This example plays an MP3 audio file while simultaneously displaying a JPEG image in one region and some text in another. The image and the text are displayed for 30 seconds; the audio element ends whenever the MP3 finishes playing.

Combining Sequences and Parallel Groups

You can put a group of parallel elements into a sequence. The parallel group is treated as a single element in the sequence. All the elements in the parallel group start together at the appropriate point in the sequence. When the last element in the parallel group ends, the sequence continues.

An example:

<seq>
    <video src="Intro.mov" region="r1" />
    <par>
        <audio src="narration.aiff" />
        <video src="slides.mov" region="r1" />
    </par>
    <text src="credits.txt" dur="20 sec" region="r1" />
</seq>

In this example, Intro.mov plays first. The narration and the slides start together as soon as Intro.mov ends. When both the narration and the slides have ended, the credits are displayed.

SMIL Media Elements

SMIL media elements are classified by type and specified by URL. Each visual media element is assigned to a region defined in the layout. The media type, the URL, and the region for visual media must be specified. All other parameters are optional.

There are currently six defined media types:

You use the media type that most closely describes a given media element. For a sound-only QuickTime movie, for example, you use the <audio/> media type. SMIL isn’t terribly strict about this, so you can specify a FLIC animation file, for example, using <animation /> or <video />. Each media element is specified by a src parameter whose value is a URL. The URL can be absolute or relative and can use any protocol that QuickTime understands, including HTTP and RTSP.

Some example media types and URLs:

<audio src="http://www.myserver.com/path/myaudio.mp3" />
<video src="rtsp://streamserver.com/VideoOnDemand.mov"/>
<image src="slides/slide01.jpg" />
<text src="subtitles.txt" />
<textstream src="rtsp://streamserver.com/streamtext.mov" />
<animation "http://www.myserver.com/myanim.flc" />

If the URL is specified as a local file, it would be file:///.

Important: The QuickTime plug-in can resolve absolute or relative URLs, and QuickTime Player can resolve absolute URLs, but as of this writing, QuickTime Player cannot resolve relative URLs unless they refer to documents in the same folder as the SMIL document itself. In other words, if you’re targeting QuickTime Player, you can specify a relative URL such as src="movie.mov", but not src="../movie.mov" or src="subfolder/movie.mov".

One URL protocol you may not be familiar with is data:, which lets you embed a media element inside your SMIL document. It’s normally used to embed small amounts of text that would otherwise require a separate file. Here’s an example of a data: URL:

<text region="aregion" dur="1:30" src="data:text/plain,Copyright Apple Computer, 2000" />

Note: The data: protocol identifier is followed immediately by the data format and a comma, then the actual data. Images can be embedded using the Base64 data format.

Region

Every visual media element needs to be assigned to a display region defined in the layout. Only one element can be displayed in a region at any time (but you can have multiple regions covering the same screen area).

If the media element contains an image that is larger or smaller than its assigned display region, the image can be scaled, clipped, or both scaled and clipped, depending on the fit parameter for that region.

Note: Clipping and scaling are attributes of a region, not a media element. To use different scaling or cropping guidelines for different images, create multiple regions covering the same area but with different fit parameters.

A SMIL document that displays a series of JPEG images:

<smil>
<head>
    <layout>
        <root-layout id="slideshow" width="320" height="240"
            background-color="black"/>
        <region id="r1" width="100%" height="100%" fit="meet" />
    </layout>
</head>
 
<body>
    <seq>
    <image src="http://www.myserver.com/ourlogo.jpg"
        region="r1" dur="5sec" />
    <image src="slide1.jpg" region="r1" dur="5sec" />
    <image src="slide2.jpg" region="r1" dur="5sec" />
    </seq>
</body>
</smil>

This example displays a sequence of three JPEG images. All the images are displayed in the same region and are automatically scaled to fill the region as completely as possible without clipping or changing their aspect ratios. Each image has a duration of 5 seconds.

Duration

Some media elements, such as audio and video, have inherent duration. Text and still images, however, have no inherent duration. The easiest way to assign a duration is with the dur parameter. For example:

<image src="slide1.jpg" region="r1" dur="30sec" />

You can assign an explicit duration to override an element’s inherent duration. For example, if you specify

<audio src="sound1.wav" dur="1:05" />

the audio file sound1.wav ends after 1 minute 5 seconds, or when the audio finishes naturally, whichever comes first.

Duration is specified in Hours:Minutes:Seconds.DecimalFractions. You can leave off the hours, or the hours and minutes, or the fractions. You can add the “sec” identifier to make things more readable. These are all equivalent:

dur="00:00:05.000"
dur="00:05.000"
dur="05.000"
dur="05"
dur="5 Sec"

Another way to explicitly set an element’s duration is to specify an end time or an end event. An element ends when its duration is exceeded, its end time or end event occurs, or it reaches its inherent end, whichever comes first. Setting begin and end parameters are discussed next.

Begin and End

You can specify an explicit start time and end time, or an event that triggers an element’s start or end, using the begin and end parameters. The time value that you specify is relative to when the element would normally begin.

For example, when you specify

<image src="slide1.jpg" region="r1" begin="5sec"/>

you get this timing:

If you specify an end time, the element ends that amount of time after it would naturally begin. For example:

<image src="slide1.jpg" region="r1" begin="5sec" end="35sec" />

In this example, the image begins 5 seconds after its natural start time, and it ends 35 seconds after its natural start time, giving it a duration of 30 seconds. The element’s duration is equal to its end time minus its start time. If no begin value is specified, an end value is the equivalent of a dur value.

Alternately, you can specify that an element should begin or end when another element begins, ends, or reaches a specified duration. Instead of using a time as the value of the begin or end parameter, use the string 

"id(idname)(event)"

where idname is the id value of another element, and event is either begin, end, or a time value. For example:

<par>
    <audio src="themesong.mp3" id="x" />
    <image src="poster.jpg" region="r1" end="id(x)(end)" />
    <text src="lyrics.txt" region="r2" end="id(x)(end)" />
</par>

This example assigns an id of x to the audio and sets the end of the image and text elements to synchronize with the end of element x.

Another example:

<par>
    <audio src="Sound1.aif" id="master" />
    <audio src="Sound2.aif" begin="id(master)(5sec)" />
    <audio src="Sound3.aif" end="id(master)(end)" />
</par>

In this example, the element Sound1.aif begins normally and has the id of "master". Sound2.aif begins 5 seconds after master begins. Sound3.aif begins normally, but ends when master ends.

Clickable Links

You can make any visual media element in a SMIL document into a clickable link by using the <a> </a> tags. You can direct the URL to load in a browser window or to replace the current SMIL presentation.

To make a visual element into a link, you

  1. precede the element with the <a> tag.

  2. put the URL of the link in the href parameter.

  3. set the show parameter to "new" or "replace".

  4. follow the element with the </a> tag.

The end result looks like this:

<a href="http://www.apple.com/" show="new" >
    <image src="poster.jpg" region="r1" dur="00:05" />
</a>

In this example, if the user clicks in region r1 while poster.jpg is being displayed there, the Apple website loads in the default browser window.

The show parameter can have two possible values:

You can use show="new" to target a specific browser frame, specific browser window, or QuickTime Player, using the target SMIL extension. Refer to the section “QuickTime SMIL Extensions,” for more information. If you use the chapter SMIL extension, you can jump to a named point in the current presentation by specifying show="replace" href="#chapname".

QuickTime doesn’t currently allow you to jump to a named point in another SMIL presentation—you can’t use URLs of the form href=fname.smi#name.

Throwing a Switch

You can automatically present different elements to different viewers using the <switch> </switch> tags.

SMIL supports a set of user attributes, such as screen resolution, color depth, maximum data rate, and language. Groups of elements can be listed between <switch> and </switch> tags. QuickTime selects one element from the list based on user attributes, much like QuickTime’s alternate track and alternate movie mechanism.

This can be used to select an audio track based on language, for example:

        <switch>
            <audio src="french.aif" system-language="fr"/>
            <audio src="german.aif" system-language="de"/>
            <audio src="english.aif" system-language="en"/>
        </switch>

This example selects french.aif for French speakers, german.aif for German speakers, and english.aif for English speakers.

The <switch> element selects the first item in the list that matches the user’s system attributes. If you’re selecting an item based on connection speed, list the elements from highest speed to lowest speed—QuickTime loads the first element the viewer’s connection speed can handle:

<switch>
    <audio src="192k.mp3" system-bitrate=192000"/>
    <audio src="128k.mp3" system-bitrate="128000"/>
    <audio src="qdesign.mov" system-bitrate="28800"/>
</switch>

This example plays 192k.mp3 for people with high-speed connections, 128k.mp3 for people with connections slower than 192 Kbits/sec, but as fast or faster than 128 Kbits/sec, and qdesign.mov for people with connections slower than 128 Kbits/sec, but at least 28.8 Kbits/sec.

To provide a default, make the default the last item in the list and don’t specify any required attributes. For example:

        <switch>
            <audio src="french.aif" system-language="fr"/>
            <audio src="german.aif" system-language="de"/>
            <audio src="english.aif"/>
        </switch>

This example selects french.aif for French speakers, german.aif for German speakers, and english.aif for all others. It’s almost always a good idea to include a default.

QuickTime supports the following user attributes:

For additional language codes, refer to

http://www.oasis-open.org/cover/iso639a.html

Note: For selections based on bit rate, screen size, or screen depth, always list the elements from most demanding to least demanding, and always include a default element with no required attributes as the last item in the list.

The next section discusses using SMIL in QuickTime.



< Previous PageNext Page > Hide TOC

Last updated: 2002-10-01

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