Chapter 6: SMIL Hyperlinks

This chapter introduces you to SMIL, explaining how to write a SMIL file that plays a single clip and opens HTML pages at various points during the presentation. Later chapters explain how to use SMIL to play sequences of clips, and to play multiple clips at the same time.

For More Information: You should also read Appendix B, which provides important information about SMIL syntax. Appendix C summarizes the SMIL attributes and values described in this guide.

What is SMIL?

Pronounced "smile," SMIL is a markup language endorsed by the World Wide Web Consortium, which operates a Web site at http://www.w3c.org. SMIL lets you create simple to highly complex media presentations by coordinating any number of media clips. Using SMIL, you can replicate almost all of the features that you can set through the Ram file. Plus, SMIL offers some advanced capabilities for opening HTML pages at different points during a presentation. A SMIL presentation works in RealOne Player on any operating system.

Note: RealOne Player supports both SMIL 1.0 and SMIL 2.0. Only SMIL 2.0 can open URLs automatically in the RealOne Player HTML panes, though. Because earlier RealPlayers do not support SMIL 2.0, the SMIL authoring techniques described in this chapter work only in RealOne Player.

Writing a SMIL File

Just like a Ram file, a SMIL file is a simple text file that you can create with any text editor. As with a Ram file, make sure that you save your output as plain text. Your SMIL file should have a simple name without spaces, and end with the extension .smil, as in my_smilfile.smil.

How Does the SMIL File Fit In?

When you use a SMIL file, your presentation functions like this:

You link your Web page to a Ram file with a standard <a href> hypertext link and an HTTP URL.

In many cases, the SMIL file will give all the presentation information, and you will use the Ram file just to launch the presentation. You still need the Ram file because SMIL is a Web standard, so its .smil extension may be associated with more than one media player. When you produce a presentation specifically for RealOne Player, the Ram file's .ram extension ensures that RealOne Player launches for all viewers.

Your Ram file gives the full URL to the SMIL presentation.

Because the SMIL file gives full URLs to your clips, it can reside on your Web server or on Helix Universal Server. It may reside in the same server directory as the Ram file, or it may be on a different server entirely. For information about writing a Ram file, see Chapter 3.

The SMIL file gives the full URLs to your streaming clips.

Clips typically reside on Helix Universal Server, and stream over the RTSP protocol. "Clip Source Tags" explains how to request a clip through a SMIL file.

SMIL File Basics

The following is a simple SMIL file that plays a video and sets presentation information. Once you understand the basic structure of this SMIL sample as described in the following sections, you'll be ready to learn about the features that make SMIL so powerful:

<smil xmlns="http://www.w3.org/2001/SMIL20/Language"
xmlns:rn="http://features.real.com/2001/SMIL20/Extensions">
  <head>
    <meta name="title" content="My First SMIL File"/>
    <meta name="author" content="Pat Morales"/>
    <meta name="copyright" content="(c)2001 Spectacular Media Limited"/>
  </head>
  <body>
    <video src="rtsp://helixserver.example.com/video1.rm"/>
  </body>
</smil>

SMIL File Sections

A SMIL file starts with a <smil> tag and ends with a </smil> tag. The opening tag includes two xmlns attributes called namespaces. These attributes function to identify the file as SMIL 2.0, and also to indicate that the file uses the RealNetworks customizations. The section "The SMIL Tag" provides more detail about these namespaces. Just make sure that your <smil> tag contains these namespaces exactly as they are shown above.

Between the opening and closing tags, the SMIL file breaks down into two major sections, just like an HTML page. The optional header section, defined between <head> and </head> tags, provides presentation information and can define a layout, which this guide covers in Chapter 8. The mandatory body section, falling between <body> and </body> tags, lists all the clips that play in the presentation.

Presentation Information

The header section in the preceding example contains three <meta/> tags that are not necessary, but are highly recommended for every SMIL presentation. Just copy these tags to every SMIL file you write, changing the values for the content attributes as appropriate:

<head>
  <meta name="title" content="My First SMIL File"/>
  <meta name="author" content="Pat Morales"/>
  <meta name="copyright" content="(c)2001 Spectacular Media Limited"/>
</head>

The <meta/> tags give the presentation's title, author name, and copyright notice. They are known as "meta" tags, because their information does not display in the media playback pane along with your streaming clips, but shows up elsewhere in RealOne Player:

Title, author, and copyright information crawls horizontally along the title bar at the top of RealOne Player.

Title and author information appears in the "Now Playing" list, which is part of the RealOne Player media browser pane. For more on this list, see "Now Playing List".

Title, author, and copyright information displays when the viewer gives the File>Clip Properties>View Clip Info command, as illustrated in the following figure.

Presentation Information

Clip Source Tags

For each media clip in a presentation, you write a clip source tag. In the preceding sample, there is one source tag:

<video src="rtsp://helixserver.example.com/video1.rm"/>

Each clip source tag includes a src attribute that tells RealOne Player where to find the clip. As you'll see later in this guide, a clip source tag can include other attributes that affect the clip's timing, layout, and so on. Note that the preceding clip source tag closes with a slash:

<tag...attributes.../>

This is an important SMIL requirement. Leaving a closing slash out of tag that is not part of a tag pair causes an error. The following table lists some of the clip source tags that you can use.

Common Clip Source Tags
Clip Tag	Used For
`<audio/>`	audio clips, such as RealAudio (`.rm`)
`<img/>`	JPEG (`.jpg`), GIF (`.gif`), or PNG images (`.png`)
`<ref/>`	any other clip type, such as a Flash Player file (`.swf`)
`<video/>`	video clips, such as RealVideo (`.rm`)

Although SMIL includes other clip source tags, it actually doesn't matter which tags you use. RealOne Player never relies on a <video/> tag alone to determine that a certain clip contains video. It uses the file extension, such as .rm. And even if that extension is incorrect for some reason, RealOne Player can generally determine the clip type and play the clip properly. So although you could use <ref/> tags for all clips, using the appropriate clip tags for a certain type of media helps you to keep the structure of your SMIL file clear.

Clip URLs

As you develop your presentation, keep your clips in the same directory as your SMIL presentation. That way, you can simply use the clip name exactly as it appears in your operating system as the value for the src attribute:

<video src="video1.rm"/>

When you are ready to stream your presentation, you'll need to change the src value to give the location of the clip on a streaming server, and specify the protocol used to stream the clip:

<video src="rtsp://helixserver.example.com/video1.rm"/>

For More Information: See "What URLs Do You Use?" for more on streaming protocols.

Creating Relative Links to Other Directories

RealOne Player can also follow the same relative, local links that you can use in a Web page. This syntax can be useful as you develop your presentation on your desktop computer. For example, the following src attribute specifies a clip that resides one level below the SMIL file in the audio folder:

<audio src="audio/song1.rm"/>

The following example specifies a clip that resides one folder level above the SMIL file:

<audio src="../song1.rm"/>

The next example creates a link to a clip that resides in an audio folder that is at the same level as the folder that contains the SMIL file:

<audio src="../audio/song1.rm"/>

Tip: You can find additional information about relative directory syntax in an HTML reference guide.

Writing Absolute Links

Alternatively, you can use local, absolute links to specify exact locations on your computer. 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. Note that this URL includes three forward slashes in file:///, and uses forward slashes in path names as well:

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

Opening HTML Pages with SMIL

The following clip source tag demonstrates how to open an HTML page in the media browser pane when a clip starts:

<video src="rtsp://helixserver.example.com/video1.rm">
  <area href="http://www.example.com" external="true" alt="My Home Page" 
  actuate="onLoad" sourcePlaystate="play" rn:sendTo="_rpbrowser"/>
</video>

First, note that this clip source tag is different from the previous examples of clip source tags, which all closed with a slash:

<video.../>

Now, the clip source tag is a tag pair in which the first tag does not close with a slash:

<video...>
  ...other markup...
</video>

This is an important SMIL concept. Tags that are normally single tags can convert to tag pairs. This allows them to enclose other tags. In this case, the clip source tag encloses an <area/> tag that creates a hyperlink. A clip source tag can enclose any number of <area/> tags, letting you create more than one hyperlink associated with each clip.

How the <area/> Tag Works

An <area/> tag is always associated with a clip. As long as an <area/> tag is active, the viewer can click the clip to open the link URL. Typically, the <area/> tag becomes active as soon as the clip starts to play, and stays active as long as the clip appears onscreen. In other words, while the clip appears onscreen, the viewer can click the clip to open the URL. There are two important ways that you can modify this behavior:

You can set the link URL to open automatically. This lets you display an HTML page as soon as a clip starts to play, for example. See "Opening an HTML Page Automatically" for details.

You can use SMIL timing attributes to set how long an <area/> tag stays active, or to make it active after its associated clip starts playing. This lets you link to different HTML pages at different times, for example, or open an HTML page automatically at some point after a clip starts to play. "Using SMIL Timing Attributes" explains timing attributes. See also the examples at the end of this chapter.

View it now! (requirements for viewing this sample)
This sample provides an overview of RealOne Player linking, demonstrating how to use SMIL to open HTML pages in the RealOne Player related info and media browser windows.

Using Standard Link Attributes

A standard <area/> tag hypertext link to an HTML page includes the attributes listed in the following table.

Standard <area/> Tag Attributes
Attribute and Value	Purpose
`alt="text"`	Provides alternate text. When the viewer moves the screen pointer over the link, the `alt` text displays in the status line above the RealOne Player media playback pane.
`external="true"`	Opens the URL in an HTML pane. This attribute is required for opening HTML pages.
`href="URL"`	Gives the fully qualified HTTP URL to the HTML page.

Opening an HTML Page Automatically

Include actuate="onLoad" in the <area/> tag to open the link URL as soon as the <area/> tag becomes active. If the <area/> tag does not contain any SMIL timing attributes, it becomes active as soon as its associated clip starts to play. Hence, actuate="onLoad" can open an HTML page automatically whenever a clip starts to play. Without actuate="onLoad", the URL opens only when the viewer clicks the clip.

Tip: A link that uses actuate="onLoad" is still clickable, meaning that the viewer can reopen it after it opens automatically. If you want to prevent this, set a short link duration by using dur="1s", for example, in the <area/> tag.

Controlling the Media Playback State

By default, the RealOne Player presentation pauses while the browser opens the link. The viewer can resume the presentation by clicking the RealOne Player Play button. You can also make RealOne Player stop the presentation completely, or continue playing when the link opens, with a stop or play value, respectively, for the sourcePlaystate attribute. Use sourcePlaystate="play" in the <area/> tag, for example, to keep the media playing as the HTML page opens.

Selecting the HTML Pane

The following table lists the attributes that you can use to open an HTML URL in one of the RealOne Player panes. The external="true" attribute is always required. The attributes that specify a RealOne Player pane use the rn: prefix, indicating that they are RealNetworks customizations. Using these attributes requires that you declare the RealNetworks namespace, which is described in "RealNetworks Extension Namespace".

Attributes for Opening an HTML Link in RealOne Player
Attributes	Target
`external="true"`	A secondary media browser window that is detached from the three-pane environment.
`external="true" rn:sendTo="_rpbrowser"`	The media browser pane.
`external="true" rn:sendTo="_osdefaultbrowser"`	The viewer's default Web browser.
`external="true" rn:sendTo="_rpcontextwin"`	The related info pane.

Opening HTML Pages in the Related Info Pane

To open an HTML page in the RealOne Player related info pane, you can use rn:sendTo="_rpcontextwin" in the <area/> link tag:

<video src="rtsp://helixserver.example.com/video1.rm">
  <area href="http://www.example.com/info.htm" external="true" alt="More Info"
  actuate="onLoad" sourcePlaystate="play" rn:sendTo="_rpcontextwin"/>
</video>

You can set the related info pane's height and width in pixels by using <rn:param/> tags. To do this, turn the <area/> tag into a tag pair (<area> and </area>) that surrounds the <rn:param/> tags:

<video src="rtsp://helixserver.example.com/video1.rm">
  <area href="http://www.example.com/info.htm" external="true" alt="Related Info"
  actuate="onLoad" sourcePlaystate="play" rn:sendTo="_rpcontextwin">
    <rn:param name="width" value="300"/>
    <rn:param name="height" value="240"/>
  </area>
</video>

View it now! (requirements for viewing this sample)
This sample displays an HTML page in the related info window when a clip starts to play.

For More Information: See "Related Info Pane Sizing" for basic information about the related info pane size. "Making Room for the Related Info Pane" explains how to open the related info pane when a presentation starts, even when an HTML page does not display in that pane right away.

Hyperlinking Examples

Once you understand the basics of how a SMIL hypertext link works, you can apply some of SMIL's timing features to open HTML pages at various points as a clip plays. Remember, though, that opening a Web page requires some of the viewer's bandwidth. If your streaming media uses all of the viewer's available bandwidth, opening a Web page will be difficult. You may need to ensure that your streaming media uses less bandwidth than the maximum listed in the table "Maximum Streaming Rates".

Tip: Choose Sample Files from the pull-down menu to view all the playable sample files included in this guide.

Opening Several Web Pages During a Presentation

The following markup uses a series of <area/> tags to open three HTML pages in the related info pane at different times as a video plays. Note that only the first link tag sets the related info pane height and width. Because this size is set for the duration of a presentation, subsequent links do not need sizing information. Although all the following links open in the related info pane, you could also add <area/> tags that use rn:sendTo="_rpbrowser" to open HTML pages in the media browser pane as well:

<video src="rtsp://helixserver.example.com/video1.rm">
  <!-- First hypertext link, with related info pane sizing information. -->
  <area href="http://www.example.com/info1.html" external="true" begin="10s"
  actuate="onLoad" sourcePlaystate="play" rn:sendTo="_rpcontextwin">
    <rn:param name="width" value="300"/>
    <rn:param name="height" value="240"/>
  </area>
  <!-- Second hypertext link. -->
  <area href="http://www.example.com/info2.html" external="true" begin="1min"
  actuate="onLoad" sourcePlaystate="play" rn:sendTo="_rpcontextwin"/>
  <!-- Third hypertext link. -->
  <area href="http://www.example.com/info3.html" external="true" begin="1.75min"
  actuate="onLoad" sourcePlaystate="play" rn:sendTo="_rpcontextwin"/>
</video>

The SMIL begin attribute creates a timing offset. In the preceding sample, the first link tag uses begin="10s" to activate the link 10 seconds after the video starts to play. The second link uses begin="1min" to activate the link one minute after the video starts to play. (Note that each begin time is relative to the clip, not to the previous link time.) Because all links use actuate="onLoad", their HTML pages open automatically when the begin time is reached.

For More Information: See "Using SMIL Timing Attributes" for details about the possible timing values for a begin attribute.

View it now! (requirements for viewing this sample)
Play this sample to watch HTML pages open automatically as a clip plays.

Opening Pages on a Mouse Click

A link to an HTML page does not have to open automatically. If you leave out the actuate="onLoad" attribute, the link opens only when the viewer clicks the clip. In the following example, the video clip defines four timed hyperlinks. The begin and dur attributes make each link active for one minute at a different point in the presentation. Viewers therefore display different pages depending on when they click the video clip:

<video src="rtsp://helixserver.example.com/video1.rm">
  <area href="http://www.example.com/page1.htm" begin="0s" dur="1min"
    external="true" rn:sendTo="_rpbrowser" sourcePlaystate="pause" 
    alt="Go to Page 1"/>
  <area href="http://www.example.com/page2.htm" begin="1min" dur="1min"
    external="true" rn:sendTo="_rpbrowser" sourcePlaystate="pause"
    alt="Go to Page 2"/>
  <area href="http://www.example.com/page3.htm" begin="2min" dur="1min" 
    external="true" rn:sendTo="_rpbrowser" sourcePlaystate="pause" 
    alt="Go to Page 3"/>
  <area href="http://www.example.com/page4.htm" begin="3min"
    external="true" rn:sendTo="_rpbrowser" sourcePlaystate="pause"
    alt="Go to Page 4"/>
</video>

For More Information: See "Specifying a Duration" for details about the dur attribute.

View it now! (requirements for viewing this sample)
Play this sample see a clip that links to different HTML pages at different times.

Using Advanced Hyperlinking Features

RealNetworks Production Guide contains additional information about creating hyperlinks. You can download this guide from http://service.real.com/help/library/encoders.html. See the guide's hyperlinking chapter for instructions on carrying out the following functions:

Link media clips to other media clips. This lets you play a new clip or SMIL presentation in the media playback pane, or in a pop-up media window, when a hyperlink opens.

Create image maps. Using <area/> tags, you can create rectangular, circular, or polygonal hot spot links that overlay portions of a clip.

Open links on a keystroke. Keystroke access aids user accessibility, and gives all viewers an alternative to clicking a link.

Set the tabbing order for links. This defines the order in which RealOne Player highlights hyperlinks when the viewer presses Tab.

Adjust a clip's volume when a link opens. Using this feature, you can boost or reduce a clip's volume when a hyperlink opens.