previous next

Chapter 6: Assembling a Presentation with SMIL

When your streaming presentation contains multiple clips—such as a slideshow and a video played together—you use Synchronized Multimedia Integration Language (SMIL) to coordinate the parts. Pronounced "smile," SMIL is a simple but powerful markup language for specifying how and when clips play. After writing the SMIL file, you put it on RealServer and link your Web page to it as described in Chapter 10.

Additional Information
Once you are familiar with SMIL, refer to "Appendix D: SMIL Quick Reference".

Understanding SMIL

With your clips in their streaming formats, you put your presentation together with SMIL. A SMIL file is not required to stream just one clip. But when you have multiple clips, SMIL's simple markup language specifies how and when the clips play. There are many advantages to using SMIL:

Advantages of Using SMIL

Creating a SMIL File

You can create a SMIL file (extension .smil) by using any text editor or word processor that can save output as plain text. If you are familiar with HTML markup, you will pick up SMIL quickly. In its simplest form, a SMIL file lists multiple clips played in sequence:


<smil>
<body>
<audio src="rtsp://realserver.example.com/one.rm"/>
<audio src="rtsp://realserver.example.com/two.rm"/>
<audio src="rtsp://realserver.example.com/three.rm"/>
</body>
</smil>

General SMIL Rules

SMIL has many similarities to HTML, but also some important differences. When you create a SMIL file, keep the following general rules in mind.

Markup Starts with <smil> and Ends with </smil>

The SMIL markup must start with a <smil> tag and end with the </smil> closing tag. All other markup appears between these two tags:


<smil>
...all other SMIL markup...
</smil>

Body Section Is Required but Header Section Is Optional

A SMIL file can include an optional header section defined by <head> and </head> tags. It requires a body section defined by <body> and </body> tags:


<smil>
<head>
...optional section with all header markup...
</head>
<body>
...required section with all body markup...
</body>
</smil>

The header section is used to specify presentation information, as explained in "Adding Presentation Information", and to define clip layout, as described in "Laying Out Multiple Clips".

Lowercase Text is Required for Tags and Attributes

SMIL tags and attributes must be lowercase.

Some Tags Must Close with a Forward Slash

A tag that does not have a corresponding end tag (for example, the <smil> tag has the end tag </smil>) must close with a forward slash. For example:


<audio src="first.rm"/>

Attribute Values Are Enclosed in Double Quotation Marks

Attribute values, such as "first.rm" in the preceding paragraph, must be enclosed in double quotation marks. Each file name in SMIL must reflect the file name exactly as it appears on the server. File names can use uppercase, lowercase, or mixed case.

SMIL Files Use the Extension .smil or .smi

Save your SMIL file with the extension .smil or .smi. The .smil extension is preferable, as it reduces the potential for conflict with other files. Do not include spaces in the file name. For example, you can have the file my_presentation.smil but not the file my presentation.smil.

Coded Characters Are Used in Headers

You need to use codes to add quotation marks, apostrophes, ampersands, or angle brackets to content in a SMIL header, such as a presentation title. See "Using Coded Characters".

HTML-Style Comments Are Allowed

As in HTML, the SMIL comment tag starts with <!-- and ends with -->. The ending does not include a forward slash:


<!-- This is a comment -->

Indentation Is Recommended

Although examples in this chapter indent SMIL tags to various levels to illustrate the SMIL structure, indentation is not required. Indenting your SMIL files as in the examples in this chapter will help you keep track of the SMIL functions, though.

Specifying Clip Locations

To add a clip to a presentation, you include in the SMIL body section a clip source tag that describes the clip type and location:


<audio src="rtsp://realserver.example.com:554/audio/first.rm"/>

There are several clip source tags, as described in the following table.

Clip Source Tags
Clip Tag Used For
animation Animation clips such as a Flash Player file (.swf).
audio Audio clips such as RealAudio (.rm).
img JPEG (.jpg), GIF (.gif), or PNG images (.png). See also "Defining Image Options".
ref Any clip type not covered by other attributes, such as a RealPix file (.rp).
text Static text clips (.txt).
textstream Streaming RealText clips (.rt).
video Video or other clips that display continuous motion, such as RealVideo (.rm).

Within each clip source tag, a mandatory src attribute lists the clip location. How you specify this location depends on whether you will stream the presentation with RealServer, download the clip from a Web server, or play clips back from a local computer, as described in the following sections.

Note
The particular clip source tag you use does not affect clip playback because RealPlayer determines the actual clip type by other means. Specifying a video clip with an <audio.../> tag, for example, does not prevent RealPlayer from recognizing that the clip contains video. Although using a tag appropriate to the clip's contents helps you keep track of clips, you could specify all clips with <ref.../> tags, for example.

Linking to Clips on RealServer

When clips reside on RealServer, each clip's src attribute gives the clip's URL like this:


<audio src="rtsp://realserver.example.com:554/audio/first.rm"/>

The following table explains the URL components. Your RealServer administrator can give you the RealServer address, RTSP port, and directory structure.

RealServer URL Components
Component Specifies
rtsp:// RTSP. Although RealServer also supports HTTP, streaming clips typically use RTSP.
realserver.example.com RealServer address. This varies with each RealServer. It typically uses an identifier such as realserver instead of www. Or it may use a TCP/IP address (such as 172.2.16.230) instead of a name.
:554 RealServer port for RTSP connections. Port 554 is the default, so you can leave this out of URLs unless the RealServer administrator chose a different port for RTSP communication. If the port number is required, separate it from the address with a colon.
/audio/ RealServer directory that holds the clip. The directory structure may be several levels deep. RealServer also uses "mount points" that invoke certain features, such as password authentication. Because these mount points appear to be directories in the URL, the request path does not mirror the actual directory path on the RealServer computer. The RealServer administrator can tell you the mount points and directories in the path.
first.rm Clip file name.

Additional Information
For more information on RTSP, see "RTSP and HTTP".

Creating Relative URLs

If your presentation includes many clips that reside on the same server, you can make each URL relative to a base target that you define in the header. Here is an example:


<head>
<meta name="base" content="rtsp://realserver.example.com/"/>
</head>
<body>
<audio src="audio/first.rm"/>
<audio src="audio/second.rm"/>
<audio src="rtsp://realserver.real.com/media/third.rm"/>
</body>

Because the third clip in this example uses a full URL, the base target is ignored. For the first two clips, however, the src values are appended to the base target, effectively giving the clips the following URLs:


rtsp://realserver.example.com/audio/first.rm
rtsp://realserver.example.com/audio/second.rm

If no base target is given, RealPlayer assumes that the clip paths are relative to the location of the SMIL file. In the preceding example, therefore, you could leave the base target out if the SMIL file itself resides in a directory that contains the audio subdirectory that in turn holds the RealAudio clips. RealPlayer requests the clips with the same protocol it used to request the SMIL file.

Tip
The relative syntax for SMIL files works like relative links in HTML, so you can use directory notation such as "../". You can find additional information about this topic in an HTML reference guide.

Linking to Clips on a Web Server

To use a clip hosted on a Web server, use a standard HTTP URL such as the following in a clip source tag:


<img src="http://www.example.com/images/logo.gif"/>

URLs to clips on a Web server can also be relative to a base target, as described in the preceding section. Keep in mind that although a Web server can host any clip, a Web server cannot perform all the functions of RealServer.

Additional Information
See "Limitations on Web Server Playback".

Linking to Local Clips

If your presentation clips will reside on the user's local computer, you need to include the SMIL file locally as well. The src attributes in the SMIL file list presentation clips in the following format:


src="audio/first.rm"

This example is a local relative link to a clip that resides one level below the SMIL file in the audio directory. For local access, you typically want to use relative links because you cannot be sure where users will place clips on their computers.

Alternately, you can use local absolute links to specify exact locations. The syntax for absolute links is the same as with HTML. It varies with operating systems, however, and you should be familiar with the directory syntax for the system you are using. For example, the following absolute link syntax works for Windows computers, but not on UNIX or the Macintosh:


src="file://c:\audio\first.rm"

Warning
Microsoft Internet Explorer 3.0 version tries to display local SMIL files as HTML. To support this browser, start the presentation through a Ram file, as explained in "Creating a Ram File Manually".

Grouping Clips

With the SMIL <seq> and <par> tags, you can create groups to structure your presentation. This section explains how to play clips in sequence or in parallel, as well as how to repeat groups or clips within groups.

Playing Clips in Sequence

Use the <seq> tag to play clips in sequence. In the following example, the second clip begins when the first clip finishes:


<seq>
<audio src="audio/newsong.rm"/>
<audio src="audio/oldsong.rm"/>
</seq>

If your presentation included just these clips, though, you would not need to use a <seq> tag. You could simply list the clips in order, and RealPlayer would play them in sequence. The <seq> tag is most commonly combined with <par> to create combinations of sequential and parallel groups.

Playing Clips in Parallel

You can play two or more clips at the same time by using the <par> tag. When RealServer streams parallel groups, it ensures that the clips stay synchronized. If some clip data does not arrive, RealServer either drops that data or halts the presentation playback until the data arrives. The following example combines a RealVideo clip with a RealText clip:


<par>
<audio src="music/newsong.rm"/>
<textstream src="lyrics/newsong.rt"/>
</par>

When multiple visual clips play in parallel, you need to define each clip's playback region. For more information, see "Laying Out Multiple Clips". Also, be sure that clips playing in parallel do not exceed the audience connection's maximum bandwidth, which is described in "Audience Bandwidth Targets".

Ending a Parallel Group on a Specific Clip

By default, a <par> group ends as soon as all clips finish playing back. You can modify this with an end attribute, as described in "Setting Begin and End Times". Or you can use the endsync attribute to stop the group when a specific clip finishes playing:


<par endsync="first">
...
</par>

endsync="first"

Use the attribute endsync="first" to stop the <par> group when the clip with the shortest timeline finishes playing. All other clips in the group stop playing at that point, regardless of their playback status or any timing parameters specified for them.

endsync="last"

The attribute endsync="last" causes the <par> group to conclude when all clips have finished playing. Because this is the default value, you can omit the endsync attribute from the <par> tag to achieve this effect.

endsync="id(clip ID)"

The attribute endsync="id(clip ID)" causes the <par> group to conclude when a designated clip reaches its end. All other clips in the group stop playing at that point, regardless of their playback status or any timing parameters used with them. The designated clip must have a corresponding id value in its source tag:


<par endsync="id(vid)">
<video id="vid" src="videos/newsong.rm" region="video"/>
<textstream src="lyrics/newsong.rt" region="text"/>
</par>

Combining <seq> and <par> Tags

You can combine and nest <seq> and <par> tags as needed. The organization of these tags greatly affects the presentation playback, though. In the following example, clip 1 plays first. When it finishes, clip 2 and clip 3 play together. When both clip 2 and clip 3 have finished playing, clip 4 plays:


<seq>
clip 1
<par>
clip 2
clip 3
</par>
clip 4
</seq>

You get very different results, though, if you switch the <seq> and <par> groupings. In the next example, clips 1, 2, and 4 all begin at the same time. When clip 2 finishes, clip 3 starts:


<par>
clip 1
<seq>
clip 2
clip 3
</seq>
clip 4
</par>

The following illustration shows the difference between these groupings.

Different Playback Results with <seq> and <par> Groups

Specifying Timing

Using SMIL timing attributes, you can specify when a clip or group starts playing and how long it plays. All timing attributes are optional. If you do not use timing attributes, clips start and stop according to their normal timelines and their positions within <par> and <seq> groups. The easiest way to designate a time is with shorthand markers of h, min, s, and ms, as listed in the following table.

Timing Shorthand Markers and Examples
Timing Marker Specifies Example Example Value
h Hours 2.5h 2 hours, 30 minutes
min Minutes 2.75min 2 minutes, 45 seconds
s Seconds 15.55s 15 seconds, 550 milliseconds
ms Milliseconds 670.2ms 670.2 milliseconds

Tip
Decimal values are not required. You can express two seconds as "2s" or "2.0s", for example.

Normal Play Time Format

You can also express time attributes in a hh:mm:ss.xy format. Here, hh is hours, mm is minutes, ss is seconds, x is tenths of seconds, and y is hundredths of seconds. In this example:


begin="02:34.0"

the time value is 2 minutes, 34 seconds. If the value does not include a decimal point, RealPlayer interprets the last value as seconds. For example, RealPlayer would read the following value as 2 minutes, 34 seconds rather than as 2 hours, 34 minutes:


begin="02:34"

Setting Begin and End Times

The begin attribute works for any clip or group. You can use it to start a clip at a specific point within a presentation's timeline:


<video src="videos/newsong.rm" begin="20.5s"/>

Were this clip in a <par> group, the begin attribute would start the clip playing back 20.5 seconds after the group becomes active. If the clip were in a <seq> group, the attribute would delay the clip's normal playback by inserting 20.5 seconds of blank time before the clip starts. Hence, timing is relative to the start of the <seq> or <par> group, not the start of the overall presentation.

Additionally, you can set an end attribute alone or in combination with a begin attribute as shown here:


<video src="videos/newsong.rm" begin="20.5s" end="62.7s"/>

In this example, the clip ends 62.7 seconds into its part of the presentation timeline, playing a total of 42.2 seconds regardless of the length of its internal timeline. If the video's internal timeline is shorter (30 seconds, for example), the fill attribute described in "Setting a Fill" determines what happens on-screen after the video stops playing but before the end time is reached.

Using Begin and End Times with Groups

You can use the begin or end attributes with a <par> or <seq> group:


<par begin= "5s" end= "3.5min">
...
</par>

This begin value delays group playback until 5 seconds after the preceding group or clip finishes. The end time sets all clips in the group to stop playing after 3.5 minutes, regardless of their playback statuses. If all clips reach their normal conclusions by 3 minutes and 20 seconds after the group starts, for example, the next group or clip starts after 10 seconds of blank playback time.

Warning
Do not set an end time along with an endsync attribute in a <par> group, as this sets up conflicting end times. For more on endsync, see "Ending a Parallel Group on a Specific Clip".

Setting Internal Clip Begin and End Times

The clip-begin and clip-end attributes specify a clip's internal timing marks where playback begins and ends. You can use them with clips that have internal timelines, such as audio, video, and animation. Do not use them with groups or static clips such as still images. The following example is for a video clip:


<video src="videos/newsong.rm" clip-begin="10.5s" clip-end="50.7s"/>

Here, the clip starts playing at its internal 10.5-second mark rather than at its actual beginning. It stops when it reaches its 50.7-second mark, having played for a total of 40.2 seconds.

Note
Do not use clip-begin and clip-end for a live broadcast or when playing clips back from a Web server. For more information, see "Limitations on Web Server Playback" and "Using SMIL with a Broadcast".

Combining clip-begin and clip-end with the begin and end Attributes

You can combine clip-begin and clip-end attributes with begin and end attributes. Here, a begin time has been added to the preceding example:


<video src="videos/newsong.rm" clip-begin="10.5s" clip-end="50.7s" begin="5s"/>

The begin time delays the clip's normal starting point by 5 seconds. When this time elapses, the clip starts at its 10.5-second internal timeline marker and plays for 40.2 seconds. In this case, the clip-end attribute determines how long the video is active. But you could also add an end attribute to modify this behavior, as shown in the following example:


<video src="videos/newsong.rm" clip-begin="10.5s" clip-end="50.7s" begin="5s"
end="50s"/>

Combined with the begin value, the end value of 50 means that the clip's "window of activity" within the presentation is 45 seconds. Because the clip stops playing after 40.2 seconds, there is an extra 4.8 seconds during which the clip does not play but remains active. How the video window appears during these final seconds depends on the fill attribute, as described in "Setting a Fill".

Setting Durations

The dur attribute controls how long a clip or group stays active after it starts to play back. You may want to use it in place of the end attribute. For example, in the following clip:


<video src="videos/newsong.rm" begin="20.5s" end="62.7s"/>

you can substitute a dur attribute for the end attribute to achieve the same result:


<video src="videos/newsong.rm" begin="20.5s" dur="42.2s"/>

In both examples, the clips stop 42.2 seconds after starting to play back. With the end attribute, the total playing time is the end value minus the begin value. The dur attribute ignores the begin value, stopping the clip 42.2 seconds after it starts. Use either end or dur, therefore, depending on how you want to measure time. Do not use both attributes in the same tag, however.

Note
The dur attribute can function like end in a group, too. For more information, see "Using Begin and End Times with Groups".

The dur attribute is useful for determining how long graphic images are displayed. In the following example, the image disappears 14.5 seconds after it appears:


<img src="graphics/poster.jpg" dur="14.5s"/>

Indefinite Durations

In RealPlayer 8 or later, you can use dur="indefinite" with a clip to make the presentation appear to be a live broadcast. Although a visual clip stops playing at its normal end or its clip-end time, its last frame stays frozen on-screen while the presentation timeline continues to advance. As with a live broadcast, the RealPlayer timeline slider is disabled, so viewers cannot seek through the presentation.

Tip
For image clips in <par> groups, use fill="freeze" instead of dur="indefinite" to display the image on-screen as long as the group is active.

Setting a Fill

Use the fill attribute to determine what happens to a given clip immediately after it plays to its actual ending or its specified end time, or as soon as its duration elapses. The fill value can be either remove or freeze.

fill="remove"

The default value fill="remove" removes the clip. When this attribute is used with a still image, the image disappears as soon as the end time has been reached.

fill="freeze"

Use fill="freeze" to freeze a clip on its last frame. When you use fill="freeze" with a video, the video's last frame stays on the screen. Suppose that you have a 20-second video and specify a 30-second duration with freeze:


<video src="videos/newsong.rm" dur="30s" fill="freeze"/>

When the video finishes playing, its last frame displays for an additional 10 seconds. The video disappears when the end time is reached. The fill="freeze" attribute has no effect on audio. Do not use fill="freeze" for a graphic image that also uses a dur attribute.

Clip Timing Example

The following example shows two audio clips with different timing options:


<par>
<audio src="song1.rm" clip-begin="30.4s" dur="30s"/>
<audio src="song2.rm" begin="28s" clip-begin="2.4s"clip-end="13.7s"/>
</par>

The timing options modify the <par> tag so that the two clips start at different times. The first clip begins to play immediately, but starts at 30.4 seconds into its timeline, playing for exactly 30 seconds.

The second clip is delayed for 28 seconds. That means it overlaps the first clip by 2 seconds. It starts at 2.4 seconds into its timeline and ends at 13.7 seconds into its timeline, playing for 11.3 seconds. The total playing time for this group is 30 seconds for the first clip, plus 11.3 seconds for the second clip, minus the 2 second overlap: 39.3 seconds. The following illustration shows how the clip timelines relate to the overall presentation timeline.

Clip Timing Example

Repeating a Clip or Group

A repeat attribute in a clip source tag or group tag repeats the clip's or group's playback. You can specify the number of times that the clip or group plays, or you can make the clip or group repeat indefinitely. During each playback, RealPlayer "prebuffers" each subsequent repetition to keep the presentation from halting when the clip replays. Note, however, that when you stream a clip with RTSP or HTTP, each repetition consumes bandwidth because RealPlayer does not cache the clip.

Tip
If you use CHTTP to cache a repeating clip on RealPlayer, the clip consumes bandwidth only the first time it plays. The clip must be smaller than RealPlayer's cache size of 4 MB, however. For more information, see "Caching Files on RealPlayer".

Repeating Playback a Specific Number of Times

The repeat="n" attribute plays a clip or group a specified number of times. You can add it to a clip source tag, as in the following example:

<video src="videos/newsong.rm" repeat="4"/>

An end or a dur attribute can modify clip repetition. Suppose that the following video has a 3-minute internal timeline. The end and fill attributes freeze the clip on-screen for 30 seconds before playback repeats:

<video src="videos/newsong.rm" repeat="4" end="3.5min" fill="freeze"/>

Repeating Clips in Groups

When adding a repeating clip to a group, pay close attention to how the clip repetition affects the group timeline. In the following example, an audio clip within a <par> group plays twice. Assuming that the audio clip lasts longer than the text stream, the <par> group ends when the audio clip concludes its second playback:


<par>
<audio src="music/newsong.rm" repeat="2"/>
<textstream src="lyrics/newsong.rt"/>
</par>

In the following <seq> group, the second video plays only after the first video plays twice:


<seq>
<video src="videos/newsong.rm" repeat="2"/>
<video src="videos/newsong2.rm"/>
</seq>

Repeating Groups of Clips

You can add a repeat="n" attribute to a <seq> or <par> tag to make the entire group repeat. As with an individual clip, including an end or dur attribute causes repetition to occur only when the specified time is reached. In the following example, the group repeats after 4 minutes, regardless of where the clips are in their timelines:


<par repeat="2" dur="4min">
<audio src="music/newsong.rm"/>
<textstream src="lyrics/newsong.rt"/>
</par>

Looping Playback Indefinitely

The repeat="indefinite" attribute causes a clip or group to repeat until another SMIL attribute or user event stops the playback loop. It works only with RealPlayer 8 or later, and has no effect on earlier RealPlayers. In the following example, the audio clips repeats continuously until the viewer clicks the RealPlayer Stop button:

<audio src="music/newsong.rm" repeat="indefinite"/>

You can specify how long each loop lasts by using an end or dur attribute. In the next example, each loop lasts for 1.5 minutes:

<audio src="music/newsong.rm" end="1.5min" repeat="indefinite"/>

You can also use repeat="indefinite" in a <seq> or <par> tag. In the following example, the first video plays again every time the third video stops:


<seq repeat="indefinite">
<video src="videos/newsong.rm"/>
<video src="videos/newsong2.rm"/>
<video src="videos/newsong3.rm"/>
</seq>

Looping Clips in Groups

In a sequence of clips, using repeat="indefinite" for a clip prevents the sequence from ending unless the <seq> tag itself specifies the end time. In the following example, the first two clips play, and then the last clip loops indefinitely until the 30-minute sequence duration elapses:


<seq dur="30min">
<video src="videos/newsong.rm"/>
<video src="videos/newsong2.rm"/>
<video src="videos/newsong3.rm" repeat="indefinite"/>
</seq>

In a <par> group, you can use dur to end playback at a specified time, or you can include endsync="id(clip ID)" to stop the group when a clip other than the looping clip finishes. In the following example, the audio loop stops when the RealPix slideshow concludes:


<par endsync="id(pix)">
<audio src="music/background.rm" repeat="indefinite"/>
<ref src="pictures/promo.rp" id="pix"/>
</par>

Additional Information
See "Ending a Parallel Group on a Specific Clip" for more information on endsync.

Laying Out Multiple Clips

If your presentation plays only one clip at a time, you do not need to create a layout. Each clip automatically plays in the main RealPlayer window, the window resizing automatically for each new clip. If you want to keep the playback area the same size as successive clips play, or if your presentation displays several clips at a time, you need to define SMIL regions.

To define SMIL regions:

  1. In the SMIL file header, define the layout between <layout> and </layout> tags.

  2. In the layout section, define a root-layout region that sets the overall size of the RealPlayer main window.

  3. Define the sizes and locations of any number of named playback regions.

  4. In the SMIL file body, use region attributes to assign source clips to the named playback regions.

A SMIL file that includes a layout therefore takes the following form:


<smil>
<head>
<layout>
<root-layout ...defines the overall window size... />
<region id="name1" ...defines a named playback region within root-layout... />
<region id="name2" ...defines a named playback region within root-layout... />
...
</layout>
</head>
<body>
<ref src="..." region="name1" ...assigns a clip to a region by name... />
<ref src="..." region="name2" ...assigns a clip to a region by name... />
...
</body>
</smil>

Additional Information
For instructions on using RealPlayer's Netscape plug-in or ActiveX control to lay out a presentation in a Web page instead of in RealPlayer, see "Laying Out SMIL Presentations".

Creating the Root Layout Region

Using the <root-layout.../> tag, you specify the width and height of the overall playback area in pixels. The following example creates a root-layout region 250 pixels wide by 230 pixels high. When the presentation begins, the RealPlayer window expands to this size. Other regions measure their top and left offsets from the upper-left corner of this root-layout region:


<head>
<layout>
<root-layout width="250" height="230"/>
...other regions defined after root-layout...
</layout>
</head>

Note
Although you can omit root-layout to have RealPlayer calculate the playback area based on the sizes of the other regions, it is better to define root-layout to avoid unexpected results. Keep in mind that you cannot play clips in the root-layout region.

Defining Playback Regions

You create playback regions for clips by defining <region> tags in the layout section. All playback regions must lay within the root-layout region. Any part of a playback region that lays outside the root-layout region is cut off. You define the playback regions by using a simple coordinate system measured across and down from the upper-left corner of the root-layout region. All measurements are in pixels or percentages, with zero pixels as the default. Each <region.../> tag must define top, left, width, and height attributes, as described in the following table.

Region Size and Placement Attributes
Attribute Sets Pixel Example Percentage Example
top Offset from top of root-layout top="60" top="10%"
left Offset from left side of root-layout left="120" left="20%"
width Region width width="240" width="40%"
height Region height height="180" height="30%"

The following illustration shows a playback region laid out within a root-layout region, based on the pixel measurement examples in the preceding table.

Basic Region Layout

In addition to its region measurements, each playback region must have an id="name" attribute that identifies it. You assign clips to a region based on the region's name. The following SMIL example defines two regions named "videoregion" and "textregion":


<head>
<layout>
<root-layout background-color="maroon" width="250" height="230"/>
<region id="videoregion" top="5" left="5" width="240" height="180"/>
<region id="textregion" top="200" left="5" width="240" height="20"/>
</layout>
</head>

In this example, both regions are offset 5 pixels to the right of the root-layout region's left edge. The video region displays 5 pixels down from the top of the root-layout region, and the text region displays 200 pixels down. The following illustration shows this placement.

SMIL Sample Layout with Video and Text Windows

Using Percentages for Region Layout

For a region's height, width, and offset measurements, you can use percentages that reflect a fraction of the root-layout region's size. The following example uses percentages to define playback areas similar to those defined in the preceding example:


<head>
<layout>
<root-layout background-color="maroon" width="250" height="230"/>
<region id="videoregion" top="2%" left="2%" width="96%" height="78%"/>
<region id="textregion" top="80%" left="2%" width="96%" height="18%"/>
</layout>
</head>

Tips for Defining Regions

Note the following about SMIL regions:

Keep in mind the following when using percentage values to define regions:

Adding Background Colors

By default, the root-layout region is black. All other regions use transparency as their default. In the SMIL layout, you can specify a different background color for any region, as in the following example:


<layout>
<root-layout background-color="maroon"/>
<region id="videoregion" background-color="silver".../>
<region id="textregion" background-color="#C2EBD7".../>
</layout>

For the color value, use any RGB hexadecimal value (#RRGGBB) supported by HTML, or one of the following predefined color names, listed here with their corresponding hexadecimal values:

white (#FFFFFF)silver (#C0C0C0)gray (#808080)black (#000000)
yellow (#FFFF00)fuchsia (#FF00FF)red (#FF0000)maroon (#800000)
lime (#00FF00)olive (#808000)green (#008000)purple (#800080)
aqua (#00FFFF)teal (#008080)blue (#0000FF)navy (#000080)

Transparency in SMIL Regions

A SMIL region is transparent if you do not define its background color. You can also explicitly specify "transparent" as its background color. Transparency means that the region is not visible until a clip starts to play in it. Note, however, that if a clip that contains transparency (such as a GIF image) plays in a transparent region, you cannot see through the clip's transparent areas to underlying regions or clips.

Defining How Clips Fit Regions

When a clip is encoded at a size different from the playback region's defined size, the <region.../> tag's fit attribute determines how the clip fits the region:


<region id="videoregion" width="128" height="64" fit="meet"/>

The fit attribute uses one of the values described in the following table. If you do not specify a fit attribute, the clip uses the default value hidden. In no case will a clip display outside the boundaries of its region.

Region Fit Attributes
Attribute Action
fill Scale the clip so that it fills the region exactly. Image distortion occurs if the encoded clip and playback region have different height/width ratios.
hidden(default) Keep the clip at its encoded size, and place it in the region's upper-left corner. If the clip is smaller than the region, fill remaining space with the region's background color. If the clip is larger than the region, crop out the area that does not fit.
meet Place the clip at the region's upper-left corner. Scale the clip and preserve its height/width ratio until one dimension is equal to the region's size and the other dimension is within the region's boundaries. Fill empty space with the region's background color.
scroll Place the clip at the region's upper-left corner. Display the clip as its normal size, adding horizontal or vertical scroll bars if the clip extends beyond the region's boundaries. (RealPlayers earlier than RealPlayer 8 display clips as the default "hidden" instead.)
slice Place the clip at the region's upper-left corner. Scale the clip and preserve its height/width ratio until one dimension is equal to the region's size and the other dimension overflows the region's boundaries. Crop the overflow.

The following illustration shows the effects that particular fit attributes have on a source clip played in windows with different sizes and aspect ratios.

Different Clip Scaling Results Based on the fit Attribute

Tip
When scaling clips inside a region, keep in mind that different types of media scale with different results. A video scaled larger than its encoded size may not look good. Vector-based media such as Flash animation, on the other hand, scale more easily to fit different region sizes. Also, remember that scaling a clip consumes CPU power on the RealPlayer computer.

Ordering Overlapping Regions with z-index

If regions overlap, you can use the z-index attribute in <region.../> tags to determine which regions appear in front. The following example creates a video region that overlaps an image region:


<layout>
<root-layout background-color="gray" width="280" height="220"/>
<region id="image" top="10" left="10" width="260" height="200" z-index="0"/>
<region id="video" top="20" left="20" width="240" height="180" z-index="1"/>
</layout>

This example defines a gray root-layout region 220 pixels high by 280 pixels wide. A smaller image region is centered within this gray background. Its z-index value of 0 makes it display behind all other regions, but not behind the root-layout region. The video region centered in the image region appears on top of that region because of its higher value for z-index. You could have another region overlap the video region by setting z-index to 2, 5, or 29, for instance. The following illustration shows these regions.

Regions Overlapping Through z-index

Tips for Defining Z-Index Values

The following are points to observe when using z-index:

Assigning Clips to Regions

After you define the SMIL layout in the header section, you use region attributes within source tags to assign each clip to a region based on the region's id attribute value. In the following example, the video and text clips are assigned to the video and text regions defined in the header:


<smil>
<head>
<layout>
<root-layout background-color="maroon" width="250" height="230"/>
<region id="videoregion" top="5" left="5" width="240" height="180"/>
<region id="textregion" top="200" left="5" width="240" height="20"/>
</layout>
</head>
<body>
<par>
<video src="video.rm" region="videoregion"/>
<audio src="audio.rm"/>
<textstream src="text.rt" region="textregion"/>
</par>
</body>
</smil>

You can reuse regions by assigning sequential clips to them. For example, you can play a video clip in a region, then display another clip in that region after the first clip finishes. Don't assign the same region to two clips that play at the same time, however. You don't assign audio clips to regions at all because audio does display on the screen.

SMIL Layout Example

The following example displays three regions: a news region, a video region, and a stock ticker region. The news and video regions are arranged side by side at the top of the RealPlayer display window. The stock ticker region appears below them.


<smil>
<head>
<!--presentation with 2 text clips and 1 video clip-->
<meta name="title" content="News of the Week"/>
<layout>
<root-layout width="430" height="165"/>
<region id="newsregion" top="0" left="0" width="250" height="144"/>
<region id="videoregion" top="0" left="250" width="180" height="144"/>
<region id="stockregion" top="145" left="0" width="430" height="20"/>
</layout>
</head>
<body>
<par>
<!--play these 3 clips simultaneously-->
<textstream src="news.rt" region="newsregion"/>
<video src="newsvid.rm" region="videoregion"/>
<textstream src="stocks.rt" region="stockregion"/>
</par>
</body>
</smil>

The following illustration shows the design of these regions.

SMIL Sample Layout with Text, Video, and Stock Ticker Windows

Switching Between Alternate Choices

With the <switch> tag, you can specify multiple options that RealPlayer can choose between. The <switch> group specifies any number of choices in this form:


<switch>
<choice1 test-attribute="value1"/>
<choice2 test-attribute="value2"/>
...
</switch>

RealPlayer looks at choices in order, evaluating each test attribute and its value to determine which clip to choose. The choices are typically clip source tags such as <video test-attribute="value"/>, but RealPlayer can also choose between groups when test attributes appear in <par> or <seq> tags.

Note
Every RealPlayer must have a viable choice within a <switch> statement. RealPlayer will not play any clip in the <switch> group if it finds no satisfactory test attribute. The next sections explain how to guarantee that every RealPlayer has a viable option.

Setting Language Choices

When source clips are in different languages, use a <switch> test attribute of system-language. The following example shows a video slideshow with separate audio narrations in French, German, Spanish, Portuguese, Japanese, Korean, and English. Each RealPlayer would request the same slideshow (seattle.rp), but choose an audio clip based on its language preference and its evaluation of the system-language codes:


<par>
<ref src="slides/seattle.rp"/>
<!-- select audio based on RealPlayer language preference setting -->
<switch>
<audio src="french/seattle.rm" system-language="fr"/>
<audio src="german/seattle.rm" system-language="de"/>
<audio src="spanish/seattle.rm" system-language="es"/>
<audio src="portuguese/seattle.rm" system-language="pt"/>
<audio src="japanese/seattle.rm" system-language="ja"/>
<audio src="korean/seattle.rm" system-language="ko"/>
<audio src="english/seattle.rm"/>
</switch>
</par>

Because the last option does not have a test attribute, a RealPlayer that does not have French, German, Spanish, Portuguese, Japanese, or Korean explicitly set as its preferred language chooses the English clip, regardless of its actual language setting. RealPlayer evaluates options in order, so the last option should be, as shown in this example, a default language that applies if no other option is viable. If you list no default option and certain RealPlayers prefer languages other than the ones you list, those RealPlayers will not play any of the clips.

Additional Information
Appendix E lists the system-language codes such as "fr" you use to designate content in different languages.

Setting Bandwidth Choices

To stream different clips to viewers at different connection speeds, use the <switch> tag to define options each RealPlayer can choose based on its connection bandwidth. Within the <switch> tag, system-bitrate attributes for clips or groups give the approximate bits per second each clip or group uses. The following sample <switch> tag lists two different RealPix presentations. The first is for connections that have at least 80 Kbps of bandwidth. The second is for slower connections, down to 28.8 Kbps modems:


<switch>
<ref src="pix/slides1.rp" system-bitrate="80000"/>
<ref src="pix/slides2.rp" system-bitrate="20000"/>
</switch>

As shown above, list the bandwidth choices from fastest to slowest. RealPlayer evaluates options in order, selecting the first option it can play. If the 20,000 bps option were first, a RealPlayer with a high-speed connection would choose it because it is the first viable option. Also ensure that the last option satisfies the slowest connection speed you want to support. If the last choice is system-bitrate="60000", for example, RealPlayers on modems will not play the presentation because its bandwidth requirement is too high.

The more complex example below shows three sets of clips. Each <par> tag has a system-bitrate attribute that lists the approximate bandwidth the clips as a whole consume. Note that each group uses the same RealText clip, but has different RealAudio and RealPix clips created for its bandwidth:


<switch>
<par system-bitrate="225000">
<!--RealPlayers with 225 Kbps or faster connections will choose this group-->
<audio src="audio/music1.rm"/>
<ref src="pix/slides1.rp" region="images"/>
<textstream src="words/narration.rt" region="text"/>
</par>
<par system-bitrate="80000">
<!--RealPlayers with connections between 80 and 225 Kbps get this group-->
<audio src="audio/music2.rm"/>
<ref src="pix/slides2.rp" region="images"/>
<textstream src="words/narration.rt" region="text"/>
</par>
<par system-bitrate="20000">
<!--RealPlayers with connections between 20 and 80 Kbps get this group-->
<audio src="audio/music3.rm"/>
<ref src="pix/slides3.rp" region="images"/>
<textstream src="words/narration.rt" region="text"/>
</par>
</switch>

Additional Information
The table "Maximum Streaming Rates" gives bandwidth guidelines for various network connections. "Writing Complex SMIL Switch Statements" gives several examples of <switch> statements.

Linking to Other Media

A SMIL file can define links to other media. A video might link to a second video, for example. When the viewer clicks the link, the second video replaces the first. Or the video could link to an HTML page that opens in the viewer's browser. You can even define areas as hot spots with links that vary over time. The bottom corner of a video can link to a different URL every ten seconds, for instance.

Note
Some clips can also define hyperlinks. A RealText clip, for example, can define hyperlinks for portions of text. When a viewer clicks an area where a clip link and a SMIL file link overlap, the SMIL link is used.

Making a Source Clip a Link

The simplest type of link connects an entire source clip to another clip. As in HTML, you define the link with <a> and </a> tags. But whereas you enclose text between <a> and </a> in HTML, you enclose a clip source tag between <a> and </a> in SMIL:


<a href="rtsp://realserver.example.com/video2.rm"> 
<video src="video.rm" region="videoregion"/>
</a>

This example links the source clip video.rm to the target clip video2.rm. When a viewer moves the cursor over the source clip as it plays, the cursor turns to a hand icon to indicate that the clip is a link. When the viewer clicks video.rm as it plays, video2.rm replaces it. The URL begins with rtsp:// if the linked clip streams to RealPlayer from RealServer, or http:// if the file downloads to the browser from a Web server. When targeting a browser, include the show attribute as described below.

Targeting RealPlayer or a Browser

An <a> tag or <anchor> tag (see "Defining Hot Spot Links") can include a show attribute that determines where a linked clip displays:


<a href="http://www.example.com/index.htm" show="new"> 
<video src="video.rm" region="videoregion"/>
</a>

show="replace"

The default attribute show="replace" causes the linked clip to replace the source clip in RealPlayer. This default behavior also occurs if you do not include the show attribute in the link. The following are important differences between RealPlayer and Web browsers to keep in mind when creating links:

show="new" and show="pause"

The values new and pause both open the linked clip in the viewer's default browser. The source clip continues to play in RealPlayer if you use show="new". With show="pause", the source clip pauses in RealPlayer. The viewer can restart playback at any time, though, by clicking RealPlayer's Play button.

Use either show="new" or show="pause" to open a Web page or another clip viewable within a browser. You can use these attributes to link a RealSystem presentation to your home page, for example. Do not use them to link to another clip played in RealPlayer, however, such as a SMIL file or a RealVideo clip.

Defining Hot Spot Links

Within a SMIL file you can define hot spots using an <anchor> tag. Whereas the <a> tag turns the entire source clip into a link, the <anchor> tag turns only a defined area into a link. With <anchor> tags you can create links similar to those in HTML image maps. But SMIL links can be temporal as well as spatial. A link might be valid for just ten seconds during a source clip's timeline, for instance.

Setting an Anchor

The <anchor> tag differs from the <a> tag in that you place it within the clip source tag rather than before it:


<video src="video.rm" region="videoregion">
<anchor href="rtsp://realserver.example.com/video2.rm" .../>
</video>

An <anchor> tag ends with a closing slash. But the clip source tag does not end with a closing slash as it normally would. Instead, the source tag and its subsequent <anchor> tags are followed by a closing source tag, such as </video>. The <anchor> tag includes an href attribute that uses rtsp:// if the linked clip streams from RealServer, or http:// if the file downloads to the browser from a Web server

Additional Information
For information on RTSP URLs, see "Linking to Clips on RealServer". To target a browser with a link, see "Targeting RealPlayer or a Browser".

Defining Spatial Coordinates

The <anchor> tag's coords attribute defines spatial coordinates for the hot spot rectangle. Coordinate values in pixels or percentages define the rectangle's offset from the upper-left corner of the source clip as shown in this example:


<video src="video.rm" region="videoregion">
<anchor href="..." coords="20,40,80,120"/>
</video>

The coordinate values for the hot spot rectangle follow this order:

  1. left side pixel or percentage value

  2. top pixel or percentage value

  3. right side pixel or percentage value

  4. bottom pixel or percentage value

The preceding example uses pixel values to define a hot spot 60 pixels wide (80 pixels minus 20 pixels) 80 pixels high (120 pixels minus 40 pixels). It produces a hot spot like that shown in the following illustration.

Hot Spot (Hyperlink) Defined with SMIL

Percentage Values

The coords attribute can also use percentage values to create hot spots relative to the source clip's size. The following sample places in the center of the source clip a hot spot that is a quarter the size of the source clip:


<video src="video.rm" region="videoregion">
<anchor href="..." coords="25%,25%,75%,75%"/>
</video>

The following table lists sample percentage coordinates that define hot spots for a source clip. Each hot spot is a quarter the size of the source clip.

Sample Hot Spot Percentage Coordinates
Hot Spot Rectangle Position Coordinate Attribute
Upper-left quadrant coords="0,0,50%,50%"
Upper-right quadrant coords="50%,0,100%,50%"
Lower-left quadrant coords="0,50%,50%,100%"
Lower-right quadrant coords="50%,50%,100%,100%"
Center coords="25%,25%,75%,75%"

Tips for Defining Anchor Coordinates

Note the following when defining hot spots:

Setting Temporal Coordinates

In addition to defining spatial coordinates, the <anchor> tag can set temporal attributes that specify when the link is active. If you do not include temporal attributes, the link stays active as long as the source clip appears on-screen. To add timing attributes, use the SMIL begin and end values. (You cannot use dur, clip-begin, or clip-end.)

The following example creates two temporal links for the clip video.rm. The first link is active for the first five seconds of playback. The second link is active for the next five seconds. Because no spatial coordinates are given, the entire video is a link:


<video src="video.rm" region="videoregion">
<anchor href="rtsp://.../video2.rm" begin="0s" end="5s"/>
<anchor href="rtsp://.../video3.rm" begin="5s" end="10s"/>
</video>

Additional Information
See "Setting Begin and End Times". The attributes use the SMIL timing values described in "Specifying Timing".

Linking to a SMIL File

A SMIL file can define a link to another SMIL file or another part of itself. For example, a video played through a SMIL file may link to another SMIL file so that when a viewer clicks the video, a new presentation starts up in RealPlayer. To do this, you simply set the href attribute for the <a> or <anchor> tag to the new SMIL file's URL.

You can also link to portions of a SMIL file. The following example from a target SMIL file uses id attributes (such as those used in regions to create region names) to define a target name for a <par> tag that groups a video and a text clip. This id attribute functions like a name attribute in an HTML <a> tag:


<par id="text_and_video">
<video src="video2.rm" region="newsregion"/>
<textstream src="text.rt" region="textregion"/>
</par>

You then link the source SMIL file to the named target by including a pound sign ("#") and the target name within the link URL. Assuming the target SMIL file is named newmedia.smil, the source file's link to the <par> group looks like this:


<a href="rtsp://realserver.example.com/newmedia.smil#text_and_video"> 
<video src="video.rm" region="videoregion"/>
</a>

Note that the target SMIL file defines two regions, newsregion and textregion. When RealPlayer receives the new SMIL file, it creates those regions as specified in the file's header.

Tips for Linking to a SMIL File

Note the following when linking to another SMIL file:

Linking with a Timeline Offset

You can use the <anchor> tag's time coordinates to create a timeline offset in a linked clip. Suppose you want to link a video to another video at 30 seconds into the second video's timeline. In the source SMIL file, you define an <a> or <anchor> link from the first video to a SMIL file that contains the second video. In the second SMIL file, the video's <anchor> tag defines the timeline offset using SMIL timing parameters.

Here is a sample of the link in the first SMIL file:


<a href="rtsp://realserver.example.com/newmedia.smil#vid2"> 
<video src="video.rm" region="videoregion"/>
</a>

The following is the linked video clip in the second SMIL file, newmedia.smil:


<video src="video2.rm" region="newsregion">
<anchor id="vid2" begin="30s"/>
</video>

Additional Information
"Specifying Timing" describes the SMIL timing values.

Adding Presentation Information

The SMIL file header can use <meta> tags to list presentation information such as title, author, and copyright:


<head>
<meta name="title" content="Bob and Susan Discuss Streaming Media"/>
<meta name="author" content="RealNetworks Media Productions"/>
<meta name="copyright" content="(c)1998 RealNetworks"/>
<meta name="abstract" content="Bob and Susan, two Internet technology
experts, discuss the future of streaming media."/>
</head>

This example defines a title, author, copyright, and abstract. You can define other values as well, such as an e-mail address, simply by adding an attribute such as name="email". This information displays when the user gives the RealPlayer Help>About this Presentation command. In addition, the title displays at the top of the RealPlayer window and in the run list under the RealPlayer File menu.

Tip
Name values, as in name="title", must be lowercase. When defining long content such as an abstract, don't use line breaks or tabs within a content value.

Managing the Playlist

In addition to the presentation information, RealPlayer keeps a playlist of clip titles. Through this playlist, users can play different parts of the SMIL presentation. The following example shows the same header information as shown previously, but adds titles for each video clip in the body section:


<smil>
<head>
<meta name="title" content="Bob and Susan Discuss Streaming Media"/>
<meta name="author" content="RealNetworks Media Productions"/>
<meta name="copyright" content="(c)2000 RealNetworks"/>
<meta name="abstract" content="Bob and Susan, two Internet technology
experts, discuss the future of streaming media."/>
</head>
<body>
<seq>
<video src="clip1.rm" title="Bob Expounds his View"/>
<video src="clip2.rm" title="Susan Responds with Another Perspective"/>
<video src="clip3.rm" title="Summary: A Look at the Future"/>
</seq>
</body>
</smil>

The titles for the individual clips appear in RealPlayer's pull-down playlist as shown in the following illustration. The user can also view the playlist with RealPlayer's View>Playlist command.

RealPlayer's Pull-Down Playlist Showing Clip Titles

Only the clip titles affect the playlist, but you can also define an author, copyright, and abstract for each clip. As illustrated below, clip information appears when the RealPlayer user gives the Help>About this Presentation command while the clip plays.

Presentation and Clip Information

Note that in this illustration, the clip information section shows the clip title defined in the SMIL file, but also includes author and copyright information not defined through SMIL. The author and copyright information is encoded in the clip.

Tips for Defining Clip Information

The following points explain the relationship between clip information set through SMIL and information encoded in a clip.

Using Coded Characters

In a header, SMIL interprets quotation marks, apostrophes, ampersands, and angle brackets as syntax markers. To have these characters show up as text in RealPlayer, you use codes in the header. As shown in the following table, codes begin with an ampersand ("&") and end with a semicolon (";"). SMIL interprets these codes the same way as popular Web browsers.

SMIL Coded Characters
Code Character Example
&quot; quotation mark "
&amp; ampersand &
&apos; apostrophe '
&lt; left angle bracket ("less than" sign) <
&gt; right angle bracket ("greater than" sign) >

For example, to add the following as a title:


  "Multimedia's <smil> & you"

You enter this in the SMIL file header:


<meta name="title" content=
"&quot;Multimedia&apos;s &lt;smil&gt; &amp; you&quot;"/>


Copyright © 1998-2000 RealNetworks
For information on RealNetworks' technical support, click here.
Comments on this document? Click here.
This file last updated on 12/12/00 at 15:34:08.
previous next