Chapter 7: Assembling a Presentation with SMIL

When your multimedia presentation contains multiple clips-such as two videos played together-you use Synchronized Multimedia Integration Language (SMIL) to coordinate the parts. Pronounced "smile," SMIL uses a simple but powerful mark-up language for specifying when and how clips play. After writing the SMIL file, you put it on RealServer and link your Web page to it as described in Chapter 10. A Web user then clicks the SMIL file link to view your presentation.

Tip
If you have just one clip in your presentation, such as a single RealVideo clip, you don't need to create a SMIL file. Just link your Web page to the media clip. See Chapter 10 for more information.

	Tip
If you have just one clip in your presentation, such as a single RealVideo clip, you don't need to create a SMIL file. Just link your Web page to the media clip. See Chapter 10 for more information.

Creating a SMIL File

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


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

SMIL General Rules

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

The SMIL file must start with a <smil> tag and end with the </smil> closing tag. All other mark-up appears between these two tags:
```
<smil>
 ...all other SMIL mark-up...
</smil>
```
The <body> and </body> tags are required, but <head> and </head> tags are optional.
SMIL tags and attributes must be lowercase.
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.ra"/>
```
Attribute values, such as "first.ra" shown above, must be enclosed in double quotation marks.
Save your file with the extension .smi. Do not include spaces in the file name. For example, you can have the file my_presentation.smi but not the file my presentation.smi.
You need to use codes to add quotation marks, apostrophes, ampersands, or angle brackets to a SMIL header. See "Using Coded Characters".
As in HTML, you can add a comment to a SMIL file like this:
```

```
This document indents tags to various levels to illustrate the SMIL structure, but this is not required. Indenting your own SMIL files like the examples here will help you keep track of the SMIL functions, though.

Adding a Header

The SMIL file can have a header section that defines aspects of the entire presentation:


<smil>
   <head>
     ...all header information...
   </head>
   <body>
     ...all body information...
   </body>
</smil>

In the SMIL file header, you typically provide author, title, and copyright information that shows up in the RealPlayer status panel. To do this, you use <meta> tags that have name and content attributes as shown here:


<head>
  <meta name="author" content="Jane Morales"/>
  <meta name="title" content="Multimedia My Way"/>
  <meta name="copyright" content="(c)1998 Jane Morales"/>
</head>

Within the body, you can override header elements as needed by adding author, title, and copyright attributes to source tags (for more on source tags, see "Specifying Clip Locations"):


<body>
  <video src="first.rm"/>
  <video src="second.rm" author="Sam Clark" title="Planning is the Key"/>
</body>

When the second clip in this example plays, the author and title displayed in RealPlayer change to new values, but the copyright stays the same. You can also specify values for groups of clips by including the author, title, and copyright attributes in <seq> and <par> tags. For more on these tags, see "Organizing a Presentation".

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 characters the same way as popular Web browsers.

SMIL Coded Characters
Code	Character	Example
`"`	quotation mark	"
`&`	ampersand	&
`'`	apostrophe	'
`<`	left angle bracket ("less than" sign)	<
`>`	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;"/>

Specifying Clip Locations

To specify a presentation file, you add to the SMIL body section a tag that describes the clip type and location:


<audio src="rtsp://realserver.company.com/audio/first.ra"/>

The tag begins with one of the clip type attributes listed in the following table.

Source Clip Attributes
Clip Attribute	Used For
`animation`	Animation clips, such as Shockwave Flash clips used in a RealFlash presentation.
`audio`	Audio clips.
`img`	Still images in JPEG (`.jpg`) or GIF (`.gif`) format.
`ref`	Any clip type not covered by other attributes.
`text`	Static text clips.
`textstream`	Streaming RealText clips.
`video`	Video or other clips that display continuous motion.

Although a source clip tag must start with a clip type attribute, attributes do not affect playback because RealPlayer determines the clip type through other means. Specifying a text clip as audio, for example, does not adversely affect playback.

After the clip type attribute, the src attribute lists the clip location. How you specify this location depends on whether you will stream the presentation over a network with RealServer or place the presentation clips on a local computer.

Linking to Clips on RealServer

When a RealSystem G2 presentation streams over a network, the media clips reside on RealServer. Each source clip's src attribute gives the clip's URL:


<audio src="rtsp://realserver.company.com:554/audio/first.ra"/>

The following table explains the URL components in the example above. Contact your RealServer administrator to get the RealServer address, RTSP port, and directory structure.

URL Components
URL Component	Meaning
`rtsp://`	This designates RealServer's RTSP streaming protocol. In contrast, URLs in Web pages start with `http://`.
`realserver.company.com`	The address varies for 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`	This is the port RealServer uses for RTSP connections. Although `554` is the default, the administrator can change it. If the port number is required, separate it from the address with a colon.
`/audio/`	This is the directory that holds the clip. The directory structure may be more than one level deep as shown in this example.
`first.ra`	This is the clip's file name.

Creating Relative URLs

If your presentation includes many clips that are on the same RealServer, you can make each URL relative to a base target that you define in the header:


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

Because the third clip has a full URL specified for it, the base target is ignored. For the first two clips, however, the src values are appended to the base target, effectively giving the clips these URLs:


rtsp://realserver.company.com/audio/first.ra
rtsp://realserver.company.com/audio/second.ra

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.

	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.

Linking to Clips on a Web Server

Because each media source clip has a separate URL, you can include in the presentation clips downloaded from a Web server. Simply include a standard HTTP URL such as this:


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

RealServer can also use HTTP, but when streaming clips from RealServer-even clips that do not have internal timelines-RealNetworks recommends that you use RTSP.

Note
You can also download clips such as RealVideo from a Web server. There are many limitations on Web server playback, however. For more information, see "Playing Clips from a Web Server".

	Note
You can also download clips such as RealVideo from a Web server. There are many limitations on Web server playback, however. For more information, see "Playing Clips from a Web Server".

Linking to Local Clips

If your presentation clips will reside on the user's local computer (as with a multimedia tutorial included with a software application, for example), you include the SMIL file locally as well. The src attributes in the SMIL file list presentation clips in this format:


src="audio/first.ra"

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 machines.

Alternately, you can use absolute, local 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're using. For example, the following absolute link syntax works for Windows machines, but not UNIX or Macintosh:


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

Warning
Microsoft Internet Explorer 3.0 tries to display local SMIL files as HTML. To support this browser, omit the <head> tag. This problem does not occur with Netscape Navigator or Internet Explorer 4.0. Nor does it occur when you stream clips from RealServer to Internet Explorer 3.0.

	Warning
Microsoft Internet Explorer 3.0 tries to display local SMIL files as HTML. To support this browser, omit the `<head>` tag. This problem does not occur with Netscape Navigator or Internet Explorer 4.0. Nor does it occur when you stream clips from RealServer to Internet Explorer 3.0.

Organizing a Presentation

With the SMIL <seq> and <par> tags, you can specify how and when each clip plays. The following sections explain how to play clips in sequence or parallel, as well as how to add timing information to tune the presentation.

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.ra"/>
  <audio src="audio/oldsong.ra"/>
</seq>

If your presentation included just the clips above, you wouldn't need to use the <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 clips.

Playing Clips in Parallel

You can play two or more clips at the same time through the <par> ("parallel") tag. For example, the following combines a RealVideo clip with a RealText clip:


<par>
  <video src="videos/newsong.rm"/>
  <textstream src="lyrics/newsong.rt"/>
</par>

RealSystem ensures that clips stay synchronized. If some video frames don't arrive, for example, RealSystem either drops those frames or halts the presentation playback until the frames arrive.

Additional Information
When multiple display clips such as RealVideo and RealText play in parallel, you also need to define each clip's playback region. For more information, see "Laying Out Multiple Clips".

	Additional Information
When multiple display clips such as RealVideo and RealText play in parallel, you also need to define each clip's playback region. For more information, see "Laying Out Multiple Clips".

Setting an End for a <par> Group

By default, a <par> group ends once all clips have finished playing back. You can modify this with the endsync attribute:


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

first

Use the attribute endsync="first"to stop the <par> group the first time a clip in the group ends playback. All other clips in the group stop playing at that point regardless of their playback status and any timing parameters specified for them.

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.

id(clip id) (end)

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


<par endsynch="id(vid) (end)">
  <video id="vid" src="videos/newsong.rm"/>
  <textstream src="lyrics/newsong.rt"/>
</par>

id(clip id) (time)

The attribute endsync="id(clip id) (time)" makes the <par> group conclude at a given time after the specified clip reaches its end. The clip must have a corresponding ID value in its source tag. The following example ends the <par> group 12 seconds after the text stream finishes:


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

Additional Information
"Specifying Timing" gives the timing shorthand values you can use.

	Additional Information
"Specifying Timing" gives the timing shorthand values you can use.

Repeating a Clip or Group

The repeat="n" attribute makes a clip or group play a specified number of times. You can add it to a clip source tag, for example:

You can also add it to a <seq> or <par> group to make the entire group repeat:


<par repeat="3">
  <video src="videos/newsong.rm"/>
  <textstream src="lyrics/newsong.rt"/>
</par>

In the following example, a video clip within a <par> group plays twice. Assuming the video lasts longer than the text stream, the <par> group ends when the video concludes its second playback:


<par>
  <video src="videos/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>

Combining <seq> and <par> Tags

You can combine and nest <seq> and <par> tags as needed. Note that the organization of these tags greatly affects the presentation playback.


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

In the example above, clip 1 plays first. When it finishes, clip 2 and clip 3 play together. When both clip 2 and clip 3 have finished, clip 4 plays. You get very different results, though, if you switch the <seq> and <par> groupings:


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

In this example, clip 1, clip 2, and clip 4 all begin at the same time. When clip 2 finishes, clip 3 starts. The following figure illustrates the difference between these different groupings.

Specifying Timing

Timing elements let you specify when a clip starts playing and how long it plays. All timing elements are optional. If you do not set them, 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 illustrated in the following table.

Timing Shorthand Examples
Shorthand Example	Value
`2.5h`	2 hours, 30 minutes
`2.75min`	2 minutes, 45 seconds
`15.55s`	15 seconds, 550 milliseconds
`670.2ms`	670.2 milliseconds

You can also express time elements in a "normal play time" format that includes an npt: prefix:


"npt=hh:mm:ss.xy"

Here, hh is hours, mm is minutes, ss is seconds, x is tenths of seconds, and y is hundredths of seconds. In this example:


"npt=02:34.0"

the time value is 2 minutes, 34 seconds. If the value does not include a decimal point, RealPlayer takes the last value to be seconds. So it reads the following value as 2 minutes, 34 seconds rather than 2 hours, 34 minutes:


"npt=02:34"

Setting Begin and End Times

The begin attribute works for images, audio, video, or any other clip type. You can use a begin attribute like the following to start a clip at a specific point within the presentation timeline:


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

If the clip above were in a <par> group, the begin attribute would start the clip 20.5 seconds after the group becomes active. If the clip were in a <seq> group, the attribute would insert 20.5 seconds of blank time before the clip started to play back.

Additionally, you can set an end time that specifies when the clip ends within the presentation timeline. You can use the end attribute alone or combined with a begin attribute as shown here:


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

Setting Durations

The dur attribute controls how long the clip appears in the presentation:


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

Applying a begin time of 20.5s and a duration of 14.5s to a graphic image, for example, makes the image appear 20.5 seconds after its part of the presentation begins. The graphic disappears 14.5 seconds later.

Note
The dur and end attributes have the same effect. You can use either to specify when a clip ends, but do not use both attributes in the same tag.

	Note
The `dur` and `end` attributes have the same effect. You can use either to specify when a clip ends, but do not use both attributes in the same tag.

Setting a Fill

The fill attribute determines what happens to the clip immediately after it plays to its normal end point, or its specified end time or duration elapses. The fill value can be remove or freeze.

remove

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

freeze

Freeze the clip on its last frame. When used with a video, the video's last frame freezes on the screen. Suppose that you have a 20-second video and specify a 30-second end time with freeze:


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

After the video plays, its last frame displays for 10 seconds. The video disappears when the end time elapses. The fill="freeze" attribute has no effect on audio.

Setting Internal Clip Begin and End Times

The clip-begin and clip-end attributes are for clips that have internal timelines, such as audio and video clips. They specify a clip's internal timing marks where playback begins and ends:


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

In this example, the clip starts playing at its internal 10.5-second mark rather than at its normal beginning. It stops playback when it reaches its 50.7-second mark, having played for 40.2 seconds.

Clip Timing Example

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


<par>
  <audio src="song1.ra" clip-begin="30.4s" clip-end="60.4s"/>
  <audio src="song2.ra" 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. Because it ends at 60.4 seconds into its timeline, it plays 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, thus 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.

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:


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

RealPlayer looks at choices in order, evaluating the test attribute and its value to determine which clip to choose.

Setting Language Choices

When the <switch> group test attribute is system-language, each source clip is for a different language. The following example shows a video slide show with separate audio narrations in English, French, and German. Based on its language preference setting and the system-language code in the SMIL file, RealPlayer selects a clip to play:


<par>
  <video src="slides/seattle.rm"/>
  <!-- select audio based on RealPlayer language preference setting -->
  <switch>
    <audio src="english/seattle.ra" system-language="en"/>
    <audio src="french/seattle.ra" system-language="fr"/>
    <audio src="german/seattle.ra" system-language="gr"/>
  </switch>
</par>

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

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

Setting Bandwidth Choices

To take advantage of high bandwidth connections, you can encode different versions of your clips for different bit rates. You then use the <switch> tag to define the choices RealPlayer can make based on its available bandwidth. As shown below, you can group clips with <par> tags, using the system-bitrate attribute to list the approximate bandwidth (in Kbps) each group consumes:


<switch>
  <par system-bitrate="75000">
    <!--for dual isdn and faster-->
    <audio src="audio/newsong1.ra"/>
    <video src="video/newsong1.rm"/>
    <textstream src="lyrics/newsong1.rt"/>
  </par>
  <par system-bitrate="47000">
    <!--for single isdn-->
    <audio src="audio/newsong2.ra"/>
    <video src="video/newsong2.rm"/>
    <textstream src="lyrics/newsong2.rt"/>
  </par>
  <par system-bitrate="20000">
    <!--for 28.8 modems-->
    <audio src="audio/newsong3.ra"/>
    <video src="video/newsong3.rm"/>
    <textstream src="lyrics/newsong3.rt"/>
  </par>
</switch>

Always list system bandwidth options from highest to lowest. RealPlayer evaluates options in the order listed, selecting the first viable option even if subsequent options suit it better. So if the 28.8 Kbps option is first, a RealPlayer with a dual-ISDN connection will choose that option because it is the first viable option listed.

Also ensure that the last option satisfies the lowest bandwidth connection you want to support. If you do not list an option suitable for 28.8 Kbps modems, for example, RealPlayers connected through those modems will not play the presentation.

Using Multiply Encoded Clips

With RealAudio or RealVideo clips encoded for multiple bit rates with SureStream codecs, you may or may not need to use the <switch> tag:

When the presentation consists solely of a SureStream clip, simply link to that clip within the SMIL file. The clip then streams at the rate appropriate for RealPlayer's connection speed. You do not need to specify bandwidth choices with a <switch> group.

Use the <switch> tag when combining a SureStream clip with other clips encoded for single bandwidths. The SureStream clip is always used, but the <switch> group gives RealPlayer options for other clips. The following example illustrates a RealAudio SureStream clip and a choice between two RealPix presentations built for different bandwidths:


<par>
  <audio src="audio/newsong2.ra"/>
  <switch>
    <ref src="image/slideshow1.rp" system-bitrate="47000"/>
    <ref src="image/slideshow2.rp" system-bitrate="20000"/>
  </switch>
</par>

Additional Information
For more on SureStream codecs, see "Choosing RealAudio Codecs" and "Choosing RealVideo Codecs". Refer to "Supporting Multiple Bandwidth Connections" for more on developing presentations for multiple bandwidths.

	Additional Information
For more on SureStream codecs, see "Choosing RealAudio Codecs" and "Choosing RealVideo Codecs". Refer to "Supporting Multiple Bandwidth Connections" for more on developing presentations for multiple bandwidths.

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 stable in size as different clips play back, or if your presentation displays several clips at a time, you can define playback areas called "regions" within the main RealPlayer window:

In the SMIL file header, you create a <layout> group and use <region> tags to name each playback region and define its size and location within RealPlayer. See "Defining the Layout" below.

In the SMIL file body, you use region attributes to specify which source clips play in which regions. See "Assigning Clips to Regions".

Additional Information
See "Working with SMIL Layouts" for instructions on using SMIL and RealPlayer's Netscape plug-in or ActiveX control to lay out your presentation in a Web page instead of in RealPlayer.

	Additional Information
See "Working with SMIL Layouts" for instructions on using SMIL and RealPlayer's Netscape plug-in or ActiveX control to lay out your presentation in a Web page instead of in RealPlayer.

Defining the Layout

When you lay out regions, you use a simple coordinate system measured across and down from the top, left-hand corner of RealPlayer's main window. Measurements are in pixels or percentages, with zero pixels as the default. The following example defines a root-layout region that sets the overall window size. It also defines two regions for displaying video and text:


<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>

Setting the Root Layout Region

With root-layout, you specify the size of the entire playback area in pixels. You cannot display images or play clips in the root-layout region, however. The example shown above creates a root-layout region 230 pixels high by 250 pixels wide. When the presentation begins, the RealPlayer window expands to this size. Other regions measure their top and left offsets from the upper, left-hand corner of this root-layout region.

Note
You can omit root-layout to have RealPlayer calculate the playback area size based on the pixel sizes and offsets of the other defined regions. But to avoid unexpected results, always define root-layout.

	Note
You can omit `root-layout` to have RealPlayer calculate the playback area size based on the pixel sizes and offsets of the other defined regions. But to avoid unexpected results, always define `root-layout`.

Tip
To use a graphic image such as a GIF or a JPEG as a background, define a playback region the same size as the root-layout region. Display the image in this region and use the z-index attribute to make it display behind other regions. See "Ordering Overlapping Clips with z- index".

	Tip
To use a graphic image such as a GIF or a JPEG as a background, define a playback region the same size as the root-layout region. Display the image in this region and use the `z-index` attribute to make it display behind other regions. See "Ordering Overlapping Clips with z- index".

Defining Playback Regions

You create playback regions for media clips with <region> tags. These regions must lay within the root-layout region. Any part of a region that lays outside the root-layout region is cut off. The example tags above define two regions named "videoregion." and "textregion." 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 figure illustrates this placement.

Each region must specify a height and width. For a region's height, width, and offset measurements, you can also 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 shown in the sample above:


<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 with Percentage Values

Note the following when using percentage values to define regions:

You must include a root-layout region defined in pixels when specifying region measurements in percentages.
You can mix pixels and percentages. You could define the top and left offset measurements in percentages, for example, while specifying the width and height measurements in pixels.
You can use whole and decimal values for percentages. For example, the values "4%" and "4.5%" are both valid.
Because a region is clipped at the boundary of the root-layout region, no percentage value can effectively be more than 100%.

Fitting a Clip to a Region

When a media clip is encoded at a size different from the playback region's defined size, the 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 media display outside the playback region's boundaries.

Region Fit Attributes
Attribute	Action
`fill`	Scale the clip's height and width so that it fills the region exactly.
`hidden`(default)	Place the clip at the region's upper, left-hand 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 doesn't fit.
`meet`	Place the clip at the region's upper, left-hand 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.
`slice`	Place the clip at the region's upper, left-hand 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 figure illustrates the effect that fit attributes have on a source clip that plays in windows with different sizes and aspect ratios.

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

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

Adding a Background Color

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


<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)`	`fuschia (#FF00FF)`	`red (#FF0000)`	`maroon (#800000)`
`lime (#00FF00)`	`olive (#808000)`	`green (#008000)`	`purple (#800080)`
`aqua (#00FFFF)`	`teal (#008080)`	`blue (#0000FF)`	`navy (#000080)`

Using Transparency

A region is transparent if you do not define its background color. You cannot explicitly specify transparency as a region color, however. Default transparency means that the region is not visible until a clip starts to play in it. This is not true transparency, though. If the media clip contains transparency too, you will not see through the clip and region transparency to an underlying region.

Ordering Overlapping Clips with z-index

If regions overlap, you can use the z-index attribute 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 zero 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. Another region could overlap the video region with z-index set, for instance, to 2 or 5, or 29.

Tips for Defining Z-Index Values

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

The root-layout region is always behind all other regions and does not use z-index.
The z-index values start at 0 (zero) and proceed through the positive integers without limit. You cannot use a negative value such as -4.
The default value of 0 (zero) applies if you don't specify z-index.
Using strictly sequential values such as 0, 1, 2, 3, 4 helps you keep track of the layers, but is not necessary. A sequence such as 0, 1, 6, 19, 34 works just as well, and leaving gaps in the sequence makes it easier to insert layers later.
Nonoverlapping clips can have the same values. Side-by-side videos can both have z-index="3", for example.
When overlapping clips have the same value, the clip that starts later in the presentation appears in front.

Additional Information
"Hiding Regions with z-index".

	Additional Information
"Hiding Regions with z-index".

Assigning Clips to Regions

After you define the layout in the header section, you use region attributes within source tags to attach each source to a region:


<body>
  <par>
    <video src="video.rm" region="videoregion"/>
    <audio src="audio.ra"/>
    <textstream src="text.rt" region="textregion"/>
  </par>
</body>

In this example, the video and text clips are assigned to the video and text regions defined in the header. 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 not require a display region.

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="Music 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 figure illustrates the design of these regions.

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 media 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 media clip link and a SMIL file link overlap, the SMIL link is used.

	Note
Some media 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 media 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 a whole media 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 media source tag between <a> and </a> in SMIL:


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

The example above 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.

Additional Information
For information on RTSP URLs, see "Linking to Clips on RealServer". For more on URLs using HTTP, see "Linking your Web Page to RealServer".

	Additional Information
For information on RTSP URLs, see "Linking to Clips on RealServer". For more on URLs using HTTP, see "Linking your Web Page to RealServer".

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.company.com/index.htm" show="new"> 
  <video src="video.rm" region="videoregion"/>
</a>

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:

RealPlayer does not include a Back button that allows the viewer to return to the link source clip after clicking the link.
Only one instance of RealPlayer can run at a time. You therefore cannot open a SMIL link in a new RealPlayer window the way you can open an HTML link in a new browser window.
Clicking the link removes any existing regions. If you have three regions defined and the viewer clicks a link in one region, for example, the target clip replaces all media clips in all regions. You can preserve regions by targeting a SMIL file that defines the same set of regions. You cannot preserve the timeline positions of clips playing in those regions when the viewer clicks the link, however.

Additional Information
"Linking to a SMIL File".

	Additional Information
"Linking to a SMIL File".

new, 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 media 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 media 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 media source tag rather than before it:


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

An <anchor> tag ends with a closing slash. But the media 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 typically uses rtsp:// if the linked clip streams to RealPlayer 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". For more on URLs using HTTP, see "Linking your Web Page to RealServer". To target a browser with a link, see "Targeting RealPlayer or a Browser".

	Additional Information
For information on RTSP URLs, see "Linking to Clips on RealServer". For more on URLs using HTTP, see "Linking your Web Page to 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-hand corner of the media 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:

left side pixel or percentage value
top pixel or percentage value
right side pixel or percentage value
bottom pixel or percentage value

The sample above 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 figure:

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-hand quadrant	`coords="0,0,50%,50%"`
Upper, right-hand quadrant	`coords="50%,0,100%,50%"`
Lower, left-hand quadrant	`coords="0,50%,50%,100%"`
Lower, right-hand quadrant	`coords="50%,50%,100%,100%"`
Center	`coords="25%,25%,75%,75%"`

Tips for Defining Anchor Coordinates

Note the following when defining hot spots:

You can mix pixels and percentages. For example, the coordinates "50,50,100%,100%" place the hot spot's left and top boundaries in and down 50 pixels from the source clip's upper, left-hand corner, respectively. But the hot spot's right and bottom boundaries extend to the source clip's right and bottom edges, respectively, no matter the source clip's size.
Values such as "30,30,10,10" are ignored. Here, the hot spot's left side is defined as farther to the right than its right side. As well, the top is defined to be below the bottom.
You can use whole and decimal values for percentages. For example, the values "4%" and "4.5%" are both valid.
A hot spot defined to extend beyond the source clip is clipped at the clip's edge. For example, if the hot spot has coordinates "50,50,300,300" but the source clip is 200 by 200 pixels, the hot spot's effective coordinates are "50,50,200,200". For this reason, no percentage value can effectively be more than 100%.

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 clip-begin or clip-end, however.)

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".

	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.smi, the source file's link to the <par> group looks like this:


<a href="rtsp://realserver.company.com/newmedia.smi#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:

You can link to any media clip or <par> or <seq> group by defining an id attribute for the clip or group. Do not link to an element in a SMIL file header, however, or to a <switch> group.
You cannot link to a media clip in a <par> group and exclude the other clips in that group. All clips in the group will play in their designated regions.
If additional clips follow the target clip in the SMIL file, those clips play when the target clip finishes playback.

Tip
To link to the single media clip, link to it directly instead of through a SMIL file. Or create a new SMIL file that lists only the target media clip.
To link to a target within the same SMIL file, simply set the href attribute value to the target id, such as <a href="#text_and_video">. Be sure to include the pound sign before the id value.

	Tip
To link to the single media clip, link to it directly instead of through a SMIL file. Or create a new SMIL file that lists only the target media clip.

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.company.com/newmedia.smi#vid2"> 
  <video src="video.rm" region="videoregion"/>
</a>

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


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

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