previous next

Chapter 15: Hyperlinks

A SMIL file can define links to other media. A video might link to a second video, for example, or to an HTML page that opens in a browsing window. 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. This chapter explains how to create hyperlinks that open HTML pages, as well as new streaming media presentations.

Understanding Hyperlinks

SMIL provides two hyperlink tags, both found in HTML. So if you are familiar with HTML linking, you'll pick up SMIL linking quickly. The SMIL <a> tag is the simpler means of creating links, but the <area/> tag is more powerful. The <area/> tag includes all of the features of <a>, and adds additional ones, such as the ability to define multiple links for each clip, and to create hot spots (image maps) and timed links. Using the <area/> tag for all hyperlinks is recommended, but the <a> tag is also available for basic linking functions.

For More Information: The two sections "Creating a Simple Link", and "Using the <area/> Tag", provide the basic instructions for using the two link tags.

Links to HTML Pages

Your SMIL file can link to HTML pages that open in a RealOne Player environment, or the viewer's default Web browser. As explained in "The Three- Pane Environment", RealOne Player offers three types of HTML windows: a related info pane, a media browser pane, and any number of secondary browser windows that pop up above the three-pane environment.

For More Information: The section "Selecting a Browsing Window" explains the attributes that target the RealOne Player panes.

Links to Streaming Media

A hyperlink can also open in the RealOne Player media playback pane, targeting an existing SMIL region, replacing the current presentation, or popping up a new media playback window. Note, though, that SMIL offers features that you can use in place of hyperlinking. For example, you can pop up a new window during the course of a presentation by using SMIL layout tags. With advanced timing, you can start or end a clip when the viewer clicks another clip. Neither of these features requires hyperlinks. So before you define hyperlinks, be sure that you understand the possibilities offered by SMIL.

For More Information: The section "Linking to Streaming Media" lists the attributes and values specific to streaming media links.

Linked Pop-Up Windows vs. Secondary Pop-Up Windows

A hyperlink can pop up a new RealOne Player media playback window when clicked, You can also pop up a window with a <topLayout> tag as described in "Secondary Media Playback Windows". Defining secondary media playback windows is appropriate when you want the new window to pop up at a predefined point in your presentation. Creating a hyperlink to a new RealOne Player media playback window is preferable when you want the new window to pop up based on viewer interaction, and the media you display in the window is not part of your main SMIL presentation.

Hyperlinks vs. Exclusive Groups

If you plan to create an interactive application, you need to consider carefully whether to provide interactivity through hyperlinks, exclusive groups, or both. Suppose that you plan to create a presentation that offers three different video clips that the viewer can select by clicking three buttons. You can author your SMIL presentation in different ways:

Methods of Activating a Link

The screen pointer turns into a hand icon when the viewer moves the pointer over an active link. Typically, the viewer opens the link by clicking it. SMIL lets you define other ways to open a link, too. You might specify a keyboard key that the viewer can press to open the link, for instance. Links can also open automatically, letting you display different Web pages as a presentation plays, for example.

For More Information: See "Defining Basic Hyperlink Properties" for more information about these features.

General Tips for Creating Hypertext Tags

Creating a Simple 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://helixserver.example.com/video2.rm"> 
<video src="video1.rm" region="video_region"/>
</a>

The preceding example links the source clip video1.rm to the target clip video2.rm. When the viewer clicks video1.rm as it plays, video2.rm replaces it. In an <a> tag, the href attribute is required. The URL begins with rtsp:// if the linked clip streams to RealOne Player from Helix Universal Server, or http:// if the file downloads from a Web server.

For More Information: For information on link attributes, see "Defining Basic Hyperlink Properties". See either "Linking to HTML Pages" or "Linking to Streaming Media" depending on your intended link target.

Using the <area/> Tag

The <area/> tag differs from the <a> tag in that you place it within the clip source tag rather than around it. This means that you must turn unary clip source tags such as <video/> into binary tags such as <video>...</video>, as described in "Binary and Unary Tags". The <area/> tag typically ends with a closing slash, but in some cases you need to use an <area>...</area> tag pair. The following is a basic <area/> tag that links one video clip to a second video clip:

<video src="video1.rm" region="video_region">
<area href="rtsp://helixserver.example.com/video2.rm"/>
</video>

If the <area/> tag includes no spatial coordinates, the entire clip becomes a link, making the <area/> tag function just like the <a> tag. A clip source tag can include any number of <area/> tags. When you define multiple <area/> links for a single clip, however, you need to do one or both of the following:

Creating a Timed Link

An <area/> tag can include temporal attributes that specify when the link is active, relative to the start of clip playback. If you do not include temporal attributes, the link stays active as long as the source clip appears onscreen. To add timing attributes, use the SMIL begin and end values. You cannot use dur, clipBegin, or clipEnd, however.

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

<video src="video1.rm" region="video_region">
<area href="http://www.real.com" begin="0s" end="30s".../>
<area href="http://www.realnetworks.com" begin="30s" end="60s".../>
</video>

Tip: An active link is one that the viewer can open, whether by clicking it or pressing the link's access key. The link does not open automatically, however, unless you use actuate="onLoad". For more information, see "Opening a URL Automatically".

For More Information: For more on the begin and end attributes, see "Setting Begin and End Times". These attributes use the SMIL timing values described in "Specifying Time Values". See "Opening Pages on a Mouse Click" for an example of hyperlinks that vary over time.

Defining Hot Spots

To create a hot spot with an <area/> tag, you use the shape attribute to define the hot spot's shape, and a coords attribute to define the hot spot's size and placement. You define the shape and coords attributes in SMIL just as you do in HTML 4.0. You can use either pixel measurements or percentages to define any hot spot. The following example shows two hot spots created for a clip:

<video src="video1.rm" region="video_region">
<area href="..." shape="rect" coords="20,40,80,120" .../>
<area href="..." shape="circle" coords="70%,20%,10%" .../>
</video>

How you specify the coordinate values depends on what shape (rectangle, circle, or polygon) you want, as explained in the following sections. In all hot spots, the coordinates are measured from the media clip's upper-left corner regardless of where you place the clip in a region.

Creating a Rectangular Hot Spot

Use shape="rect" to create a rectangular hot spot. You then specify four coords values in pixels or percentages to set the hot spot's size and placement, measured from the upper-left corner of the source clip in the following order:

  1. distance of the hot spot rectangle's left edge from the clip's left edge
    (left-x)
  2. distance of the hot spot rectangle's top edge from the clip's top edge
    (top-y)
  3. distance of the hot spot rectangle's right edge from the clip's left edge
    (right-x)
  4. distance of the hot spot rectangle's bottom edge from the clip's top edge
    (bottom-y)

Coordinate values are separated by commas, as shown in the following example:

<video src="video1.rm" region="video_region">
<area href="..." shape="rect" coords="20,40,80,120"/>
</video>

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

Rectangular Hot Spot

Rectangular Hot Spot

Tip: Think of the first pair of values as defining the x and y coordinates of the hot spot's upper-left corner, and the second pair of values as defining the x and y coordinates of the hot spot's lower-right corner.

Defining a Circular Hot Spot

You can use shape="circle" to create a circular hot spot. Three coords values then specify in pixels or percentages the circle's center placement and radius in the following order:

  1. distance of the hot spot circle's center from clip's left edge (center-x)
  2. distance of the hot spot circle's center from the clip's top edge (center-y)
  3. the hot spot circle's radius

The coordinate values are separated by commas, as shown in the following example:

<video src="video1.rm" region="video_region">
<area href="..." shape="circle" coords="100,120,50"/>
</video>

The preceding example uses pixel values to place the circular hot spot's center 100 pixels in from the clip's left edge, and 120 pixels down from the clip's top edge. The hot spot has a radius of 50 pixels. The following figure illustrates this example.

Circular Hot Spot

Circular Hot Spot

Tip: The last value, which sets the circle's radius, should not be more than the smaller of the other two values. If the first two values are 40 and 20, for example, the third value should not be more than 20. Otherwise, part of the circle extends beyond the clip boundaries and is cut off.

Making a Polygonal Hot Spot

Use shape="poly" to make a polygonal hot spot with any number of sides. You might create a triangle or an octagon, for example. For every n sides of the polygon you want to create, you must specify 2n values in the coords attribute. To create a triangle, for example, you need to specify six coords values. Each pair of coordinate values indicates the placement of a corner of the polygon in this order:

  1. distance of the polygon corner from the clip's left edge (corner-x)
  2. distance of the polygon corner from the clip's top edge (corner-y)

The following example defines a triangular hot spot:

<video src="video1.rm" region="video_region">
<area href="..." shape="poly" coords="40,150,120,30,200,150"/>
</video>

The following figure illustrates the preceding example. The first value pair for the coords attribute defines the triangle's lower-left corner. The coords value pairs then proceed clockwise, defining the top corner, followed by the lower- right corner.

Polygonal Hot Spot

Polygonal Hot Spot

Tip: When defining a polygon, you can start with any corner, specifying the placement of additional corners by going around the polygon either clockwise or counter-clockwise.

Tips for Defining Hot Spots

Defining Basic Hyperlink Properties

The hyperlink attributes summarized in the following table affect link properties in <a> and <area/> tags whether the link opens an HTML page or a media presentation.

Basic Hyperlink Attributes
Attribute Value Function Reference
accesskey key_name Defines a key stroke that opens the link. click here
actuate onLoad|onRequest Opens the link automatically or on request. click here
alt text Supplies alternate text. click here
href URL Provides the link URL. click here
nohref (none) Indicates no URL (<area/> tag only). click here
tabindex integer Sets a tabbing order for links. click here

Tip: The accesskey, alt, and tabindex attributes are defined the same in SMIL 2.0 as they are in HTML 4.0.

Specifying the Link URL

As with an HTML hyperlink, the SMIL href attribute specifies the URL to open. This should be an HTTP URL for items opened in a browser window, whether those items reside on a Web server or Helix Universal Server. SMIL files or clips opened in RealOne Player should generally have an RTSP URL if they reside on Helix Universal Server. They must have an HTTP URL if they reside on a Web server, however. See the following sections for more information:

Leaving Out a URL Reference for Hot Spots

Note: The nohref attribute is not currently functional in RealOne Player.

The nohref attribute, which can be used only in <area/> tags, indicates that the hot spot has no URL associated with it. You can use nohref with interactive timing commands to start another clip when the hot spot is clicked, for example, without activating a hyperlink to an external file. The nohref attribute does not take a value.

Opening a Link on a Keystroke

The accesskey attribute defines a keyboard key that the viewer can press to open the link. The viewer presses just the defined key, and does not need to press a helper key such as Alt to open the link. You can define any number of access keys for a link. In the following example, the viewer could press the keyboard letter m to open the link:

<area href="http://www.example.com" accesskey="m" .../>

Note: The SMIL playback area does not receive the keyboard focus by default. Therefore, the viewer must first click the SMIL playback area before pressing an access key.

View it now! (requirements for viewing this sample)
This sample demonstrates access key hyperlinks.

Tips for Defining Access Keys

Opening a URL Automatically

The actuate attribute has a default value of onRequest, which makes the link open only when the viewer clicks the link, or presses the link's access key. If you set actuate="onLoad", however, the link opens as soon as the link tag becomes active in the SMIL presentation timeline, without requiring any user input. For example, the following link opens when the video clip begins to play:

<video src="video1.rm" region="video_region">
<area href="http://www.example.com" actuate="onLoad".../>
</video>

As described in "Creating a Timed Link", you can use a begin attribute in the <area/> tag to cause the link to become active after its associated clip starts to play. This lets you open a link at some point after a clip begins to play.

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.

Displaying Alternate Link Text

A hyperlink can include an alt attribute that uses short, descriptive text as its value. It is good practice always to include an alt attribute in hyperlinks. 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, indicating what the link will open. In the following example, the text "Visit RealNetworks" is used for the alt value:

<area href="http://www.realnetworks.com" alt="Visit RealNetworks" .../>

If the clip that includes the link also has an alt value, the link's alt value displays instead of the clip's. If the link has no alt value, its URL displays in place of the clip's alt value. In short, a link always overrides the clip's alt value.

For More Information: The section "Including an Alternate Clip Description" covers the alt attribute in clip source tags. See "Coded Characters" for information on including special characters in alt text.

Setting a Tab Index for Multiple Links

When multiple links appear onscreen, the viewer can press Tab to cycle between the links, then press Enter to open a link. Using the tabindex attribute, you can specify the tabbing order. This attribute, which has a default value of 0, takes a positive integer as a value. RealOne Player highlights the clip with the lowest tabindex value first. It highlights the clip with the next higher tabindex value each time the viewer presses Tab. The following is an example of two clips playing in parallel, each of which has a hyperlink:

<par>
<img src="..." region="ad_region"...>
<area href="..." tabindex="2" .../>
</img>
<video src="..." region="video_region"... >
<area href="..." tabindex="1" .../>
</video>
</par>

In the preceding example, the link for the video clip has the lower tabindex value, so RealOne Player highlights it first when the viewer presses Tab. RealOne Player highlights the image clip next when the viewer presses Tab again.

Tip: If two or more <area/> tags have the same tabindex value, the tabbing order follows the order in which the clip source tags appear in the SMIL file. This also occurs if you leave tabindex out of all <area/> tags.

Linking to HTML Pages

The attributes summarized in the following table allow you to open HTML pages from your SMIL presentation. You can use these attributes to open a Web page while a presentation plays, for example. Web page links open by default in a RealOne Player browsing pane, though you can also open them in the viewer's default browser.

Attributes for Opening a Link in a Web Browser
Attribute Value Default Function Reference
rn:contextWindow auto|openAtStart auto Sets when related info pane opens. click here
external false|true false Opens link in a browser when true. click here
height pixels media height Sets related info pane height in <param> tag. click here
rn:sendTo _osdefaultbrowser|
_rpbrowser|
_rpcontextwin
(none) Specifies window that opens the HTML page. click here
click here
sourceLevel percentage 100% Sets audio level. click here
sourcePlaystate pause|play|stop pause Changes source state. click here
target name current window Targets window or frame. click here
width pixels 330 Sets related info pane width in <param> tag. click here

Tip: You can also open an HTML URL through a Ram file. This is useful for presentations that consist of a single clip, and do not require the advanced features that SMIL provides. For instructions on this, see "Opening a URL in an HTML Pane".

Selecting a Browsing Window

For a SMIL hyperlink to open in a Web browser, the external attribute must be set to true. (The external attribute's default value is false, however, which opens the link in the RealOne Player media playback pane.) The link must also use an HTTP URL that the browser can request. Minimally, a SMIL link for content played in a Web browser looks like the following example:

<area href="http://www.example.com" external="true"/>

Using external="true" is the only requirement for opening an HTML page in a Web browser. As described in "Links to HTML Pages", however, RealOne Player offers several browsing panes. The following table lists the attributes required to open an HTML URL in one of these panes.

Attributes for HTML Page Hyperlinks
Attributes Target Reference
external="true" A secondary browsing window that does not attach to the media playback and related info panes. click here
external="true"
rn:sendTo="_rpbrowser"
The media browser pane, which can attach to, or detach from, the media and related info panes. click here
external="true"
rn:sendTo="_osdefaultbrowser"
The viewer's default Web browser. click here
external="true"
rn:sendTo="_rpcontextwin"
The related info pane, which appears to the right of the media playback pane. click here

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

Note the following important points about using the rn:sendTo attribute:

Targeting the Media Browser Pane

RealOne Player's media browser pane can attach to, or detach from, the media playback and related info panes. This is the recommended pane for displaying Web pages along with your presentation. To target this pane, declare the RealNetworks extensions namespace in your <smil> tag as described above, and use a hyperlink that looks like the following:

<area href="http://www.example.com" external="true" rn:sendTo="_rpbrowser" .../>

Tip: To target this pane from an HTML page displaying in the related info pane or a secondary browsing window within the RealOne Player environment, use <a href="URL" target="_rpbrowser">.

Using the Viewer's Default Browser

Web page links open in a RealOne Player media browser pane by default. Although this is preferred means for displaying these pages, you can also open these links in the viewer's default Web browser. To do this, declare the RealNetworks extensions namespace in your <smil> tag as described above, and create a link that looks like the following:

<area href="http://www.example.com" external="true" rn:sendTo="_osdefaultbrowser" .../>

Opening HTML Pages in the Related Info Pane

Appearing to the right of the media playback pane, the related info pane can display HTML pages that supplement your SMIL presentation. It might display title and copyright information about clips as they play, for example. Using the SMIL timing features described in Chapter 13 and Chapter 14, as well as the hyperlinking features described in this chapter, you can open a URL in the related info pane at any time during the presentation.

To open an HTML page in the related info pane, declare the extensions namespace (xmlns:rn="http://features.real.com/2001/SMIL20/Extensions") in your <smil> tag, and add rn:sendTo="_rpcontextwin" to the <area/> link tag:

<area href="http://www.example.com/context.html" external="true" rn:sendTo="_rpcontextwin" sourcePlaystate="play"/>

Setting the Related Info Pane Size

Through <rn:param/> tags, you can extend an <area/> tag link to include sizing information for the RealOne Player related info pane. This requires that you turn your <area/> tag into a binary tag as described in "Binary and Unary Tags". To specify the related info pane width and height in pixels, you then add <param/> tags to the link, as shown in the following example:

<area href="..." external="true" rn:sendTo="_rpcontextwin" ...>
<rn:param name="width" value="320"/>
<rn:param name="height" value="240"/>
</area>

View it now! (requirements for viewing this sample)
This sample automatically opens a series of HTML pages in the RealOne Player related info pane.

Making Room for the Related Info Pane

When the media browser pane is attached, a SMIL presentation that plays without an HTML page for the related info pane appears centered above the media browser pane. If an HTML page later opens in the related info pane, the SMIL presentation jumps to the left. To prevent this effect, which can be jarring for the viewer, include rn:contextWindow="openAtStart" in the <root- layout/> tag (not the <area/> tag):

<root-layout width="320" height="240" rn:contextWindow="openAtStart"/>

When you use this attribute, the SMIL presentation appears at the left side of the top two panes. Any HTML pages then sent to the related info pane appear at the right side. To prevent height resizing when an HTML page appears, specify the same height for the related info pane that you use in the <root- layout/> area. The rn:contextWindow attribute has no visible effect when the media browser pane is detached.

View it now! (requirements for viewing this sample)
In RealOne Player, make sure that the media browser pane is attached. Then, play the first sample, which makes room for the related info pane when the presentation starts, placing the video flush left. The second sample does not use rn:contextWindow, so the video appears centered at first, moving to the left when the related info pane opens.

Tips for Using the Related Info Pane

Targeting a Frame or Named Window

Note: HTML frame and window targeting is not currently functional in RealOne Player.

When you use SMIL to open an HTML page, the SMIL target attribute works much the same as the HTML target attribute. When a hyperlink targets a RealOne Player secondary browsing window (using just external="true") or the default browser (using rn:sendTo="_osdefaultbrowser"), the target attribute can do one of the following:

When a link specifies the media browser pane (with rn:sendTo="_rpbrowser") or the related info pane (using rn:sendTo="_rpcontextwin"), the target attribute can select an existing frame. The following example shows how to open a link in the frame named rightpane within the media browser pane:

<area href="http://www.example.com" external="true" 
rn:sendTo="_rpbrowser" target="rightpane".../>

Tip: The HTML values _new and _top are not supported in the RealOne Player environment. Use actual window names instead.

Controlling the Media Playback State

By default, the SMIL presentation pauses while an HTML page link opens. The viewer can resume the presentation by clicking the RealOne Player Play button. RealOne Player typically needs to rebuffer the presentation briefly before continuing playback. 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:

<area href="http://www.example.com" external="true" sourcePlaystate="play".../>

Tips for Opening HTML Page Links

Linking to Streaming Media

When you link to another streaming media presentation, whether a SMIL file or a single clip, you can open the link URL in the existing RealOne Player media playback pane, or pop up a new media playback window. The following table summarizes the attributes that you use to link to streaming media.

Attributes for Streaming Media Hyperlinks
Attribute Value Default Function Reference
href="command:
openwindow()"
(name, URL) (none) Opens media from Flash, RealPix, or RealText. click here
destinationLevel percentage 100% Sets audio level of target. click here
destinationPlaystate pause|play play Sets play state of target. click here
show new|replace replace Opens link in a new or the current window. click here
sourceLevel percentage 100% Sets audio level of source. click here
sourcePlaystate pause|play|stop pause|play Sets play state of source depending on show. click here
target ID (none) Links to a specific window or region. click here

Replacing the Source Presentation

A link that does not include the external="true" attribute (which opens the link in a Web browser) replaces the current presentation in the RealOne Player media playback pane. The source presentation is only paused, however, so the viewer can return to it by clicking RealOne Player's Play>Previous Clip command. Hence, an RTSP link like the following:

<area href="rtsp://helixserver.example.com/video2.rm"/>

is equivalent to the following link, in which the show, destinationPlaystate, and sourcePlaystate attributes are explicitly set to their default values:

<area href="rtsp://helixserver.example.com/video2.rm" show="replace" 
destinationPlaystate="play" sourcePlaystate="pause"/>

Note: Currently, the source clip always stops, rather than pauses, when the destination clip replaces it.

In some cases, you may want to set destinationPlaystate="pause" to keep the new presentation from playing until the viewer clicks the RealOne Player Play button. It's not necessary ever to include the sourcePlaystate attribute when replacing a presentation in RealOne Player. Its value of pause is always used with show="replace", so specifying play or stop for sourcePlaystate has no effect.

The following table summarizes the possible hyperlink attribute values for replacing a presentation in the existing RealOne Player pane. The first option listed in the table is the default.

Hyperlink Attributes for Replacing a Presentation in RealOne Player
Source Destination Attributes
pause play show="replace" sourcePlaystate="pause" destinationPlaystate="play"
pause pause show="replace" sourcePlaystate="pause" destinationPlaystate="pause"
stop play or pause Not allowed. The source state is always pause.

View it now! (requirements for viewing this sample)
In this sample, click the playing clip to replace it with a new clip in the same media playback pane.

Opening a New Media Playback Window with SMIL

You can use either the show or the target attribute to open a new media playback window. The basic means for doing this is to set show="new" in the link tag. You can open any number of new windows this way. Using show="new" does not create a named window that you can target with another hyperlink, however:

<area href="rtsp://helixserver.example.com/video2.rm" show="new".../>

By default, the current window containing the link and the new window with the target media are both set to play. Therefore, the preceding example is equivalent to the following example:

<area href="rtsp://helixserver.example.com/video2.rm" show="new" 
sourcePlaystate="play" destinationPlaystate="play".../>

Depending on how you want linking to operate, you can change the setting for sourcePlaystate to pause or stop. You can also set destinationPlaystate to pause. A common scenario is to pause the source presentation when the viewer opens the new window. The viewer can restart the source presentation by clicking the RealOne Player Play button. The following example illustrates this markup:

<area href="rtsp://helixserver.example.com/video2.rm" show="new" 
sourcePlaystate="pause" destinationPlaystate="play"/>

View it now! (requirements for viewing this sample)
In these samples, you can click the playing clip to open a new clip in a new window and pause the first clip, or keep the first clip playing.

Targeting a Specific Window or Region

Note: Targeting a named media window or region is not currently functional in RealOne Player.

Whereas show="new" opens a link in a new, unnamed media playback window, target="name" creates a named window that you can select through subsequent hyperlinks. It also lets you open linked media in a specific SMIL region of an existing window, rather than in a new window. The show="new" attribute does not include these two capabilities.

The target attribute takes a user-defined name as its value. As with show="new", you can set sourcePlaystate to play, pause, or stop. You can also set destinationPlaystate to play or pause. The following example defines a link that opens in a SMIL region or a new window named play3:

<area href="rtsp://helixserver.example.com/video2.rm" target="play3" 
sourcePlaystate="pause" destinationPlaystate="play".../>

When RealOne Player opens the link in preceding example, it displays the linked media in the following way:

  1. RealOne Player displays the linked media in the existing SMIL region named play3. That is, it looks for a SMIL region in any open window that has the play3 ID:
  2. <region id="play3" .../>
    

  3. If no SMIL region named play3 exists, RealOne Player displays the linked media in the window named play3. That is, it looks for a window created through a previous hyperlink that used a target="play3" attribute.
  4. If no window named play3 exists, RealOne Player creates a new window with the play3 name, displaying the linked media in that window.
  5. View it now! (requirements for viewing this sample)
    These two samples each display two images linked to two separate videos. The first sample uses the target attribute to open each video in the same media playback window. The second sample uses the target attribute to open each video in a different media playback window.

Tips for Opening Streaming Media in New Windows

Linking to a SMIL Fragment

A SMIL file hyperlink can target a specific place in another SMIL file, or another part of itself. To create a link of this type, you include the appropriate SMIL ID in the href attribute after the URL and a pound sign (#), just as if linking to an HTML fragment:

<area href="rtsp://helixserver.example.com/movie2.smil#text_and_video" .../>

The preceding link opens the designated SMIL file, and starts playback at the clip or group that includes the text_and_video ID:

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

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

View it now! (requirements for viewing this sample)
In this sample, a sequence of three videos plays. Each numbered button links to a separate video through a SMIL fragment. You can thereby use the buttons to skip to any part of the presentation.

Linking to a Clip with a Timeline Offset

Note: Linking to a clip with a timeline offset is not currently functional in RealOne Player.

You can use the <area> tag's time coordinates to create a timeline offset in a linked clip. Suppose that 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 a link from the first video to a SMIL file that contains the second video. In the second SMIL file, the video's <area> tag defines the timeline offset using SMIL timing parameters.

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

<video src="video1.rm" region="video_region">
<area href="rtsp://helixserver.example.com/newmedia.smil#vid2"/>
</video>

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

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

For More Information: "Specifying Time Values" describes the SMIL timing values.

Tips for Linking to SMIL Fragments

Adjusting Audio Volumes in Linked Presentations

Two attributes in a hyperlink tag, sourceLevel and destinationLevel, can adjust the volume of the source player and the destination player when a link opens. If the source clip does not stop or pause when the link opens, for example, you can use sourceLevel to turn down the source player's volume and boost the destination player's volume:

<area href="..." sourceLevel="35%" destinationLevel="125%".../>

The audio level attributes always use a percentage value. The default value of 100% keeps the player at its current volume setting. A 50% value, for example, turns the player's audio volume down to half of its current setting, whereas a value of 200% doubles the audio volume.

Note that the sourceLevel and destinationLevel attributes control only the relative volume of the audio stream sent to the speakers. They do not change the general sound level setting on the viewer's computer, which remains entirely under the viewer's control. All sound level adjustments are subject to limitations in the computer hardware.

Tip: When displaying a Web page, as described in "Linking to HTML Pages", you can use sourceLevel to turn down or boost RealOne Player's volume as appropriate. The destinationLevel attribute will not affect any audio elements, such as an embedded WAV file played by the browser, though.

View it now! (requirements for viewing this sample)
This sample displays two hypertext links that play a video at half or double volume.

Opening a Media Playback Window with a Clip Link

A RealText, RealPix, or a Flash clip, playing alone or as part of a SMIL presentation, can define a hyperlink that opens another clip in a new media playback window, and stops the original presentation, on a click. This type of link uses a proprietary parameter, command:openwindow(name,URL), as the value of the href attribute. This is not a SMIL feature, and you write this parameter directly into the RealText or RealPix markup, or encode it in the Flash Player file with the Get URL command.

The hypertext reference for this type of link has the following structure:

href="command:openwindow(name, URL, [zoomlevel=double|full|normal])"

The command:openwindow parameter requires two arguments, name and URL. The zoomlevel argument is optional. You can separate arguments with a comma, but this is not required. A space may precede or follow a comma. If an argument contains characters such as commas or parentheses, enclose it in single quotation marks.

Window Names

The required name argument, which supplies a predefined or user-defined name for the new media playback window, is the first parameter listed for command:openwindow. The following table describes the parameter values.

name Parameter
Value Action
_new or
_blank
Opens a new media playback window each time the viewer clicks the link. Each subsequent link named _new or _blank opens a new window as well.
_self or
_current
Opens the URL in the current media playback window.
name Creates a new media playback window with the user-defined name. A subsequent openwindow command using the same name opens the given URL in the same window.

Target URL

Following the name argument, the required URL argument gives the fully qualified URL to the clip or SMIL presentation to play in the new window. You must include the protocol (rtsp://, http://, chttp://, or file://) in the URL. Relative URLs do not work.

For testing, or if developing a presentation that plays back locally for all viewers, you can use absolute, local URLs in the following format, which includes three forward slashes in file:///, and uses forward slashes in path names as well:

file:///C:/My Documents/videos/video1.rm

Zoom Level

The optional zoomlevel=double|full|normal argument sets the new media playback window to open in double-size or full-screen mode respectively. The normal value is the default. If the operating system does not support full- screen mode, normal mode is used instead.

For More Information: You can also open the initial presentation in double or full-screen mode by using a Ram file. For details on doing this, as well as guidelines for using double and full- screen modes, see "Controlling How a Presentation Initially Displays".

Note: Earlier versions of RealPlayer support additional parameters, such as autosize and ontopwhileplaying, that RealOne Player ignores. RealOne Player is therefore backwards- compatible with presentations developed for earlier versions of RealPlayer. These additional parameters are obsolete, however.

Examples

The following examples show how to target various windows with the command:openwindow hyperlink syntax inRealText and Flash clips. These examples link to single RealVideo clips, but you can link to any streaming clip or SMIL presentation.

Targeting the Same Window with Multiple Links

The following RealText link opens a URL in a new media playback window named feature:

<a href="command:openwindow(feature, rtsp://helixserver.example.com/comedy.rm)">Comedy Hour</a>

The syntax in RealPix is the following:

url="command:openwindow(feature, rtsp://helixserver.example.com/comedy.rm)"

In Flash, the Get URL command looks like this:

command:openwindow(feature, rtsp://helixserver.example.com/comedy.rm)

When first clicked, this link creates a media playback window named feature. If another link also targets the feature window, clicking that link starts the new URL in the feature window. Clicking the link in the following example starts an animal program in the window running the comedy program:

<a href="command:openwindow(feature, rtsp://helixserver.example.com/animals.rm)">Sharks!</a>

The RealPix markup is this:

url="command:openwindow(feature, rtsp://helixserver.example.com/animals.rm)"

The Flash Get URL version looks like this:

command:openwindow(feature, rtsp://helixserver.example.com/animals.rm)

Opening Separate Windows

Each link opens a separate window if the window names are different, or you use the predefined name _new or _blank. The following RealText links open separate windows:

<a href="command:openwindow(_new, rtsp://helixserver.example.com/comedy.rm)">Comedy Hour</a>
<a href="command:openwindow(_blank, rtsp://helixserver.example.com/animals.rm)">Sharks!</a>

The following are the corresponding RealPix links:

url="command:openwindow(_new, rtsp://helixserver.example.com/comedy.rm)"
url="command:openwindow(_blank, rtsp://helixserver.example.com/animals.rm)"

In Flash, the Get URL commands look like these:

command:openwindow(_new, rtsp://helixserver.example.com/comedy.rm)
command:openwindow(_blank, rtsp://helixserver.example.com/animals.rm)

Launching Clips in the Current Window

Use either _current or _self to open the URL in the current window. The following example is for RealText:

<a href="command:openwindow(_self, rtsp://helixserver.example.com/comedy.rm)">Comedy Hour</a>

The next RealText link plays the clip at double its encoded size:

<a href="command:openwindow(_current, rtsp://helixserver.example.com/animals.rm, zoomlevel=double)">Sharks!</a>

The following are the same commands given through RealPix:

url="command:openwindow(_self, rtsp://helixserver.example.com/comedy.rm)"
url="command:openwindow(_current,  rtsp://helixserver.example.com/animals.rm, zoomlevel=double)"

The following are the same commands issued through Get URL in Flash:

command:openwindow(_self, rtsp://helixserver.example.com/comedy.rm)
command:openwindow(_current, rtsp://helixserver.example.com/animals.rm, zoomlevel=double)

Tips for Opening Media Windows with RealText, ReaPix, or Flash

Hyperlink Examples

The following examples show different applications of hyperlinking. To see more examples, get the zipped HTML version of this guide as described in "How to Download This Guide to Your Computer", and view the Sample Files page.

Opening Web Pages During a Presentation

The following markup uses a series of <area/> tags with different begin times to open four Web pages at different points as an audio clip plays. The actuate="onLoad" attribute causes each link to open its Web page as soon as the link becomes active. Because the links do not use rn:sendTo="_rpbrowser", the pages open in secondary browsing windows. The sourcePlaystate="play" attribute keeps the clip playing as each page opens:

<audio src="audio1.rm">
<area href="http://www.example.com/page1.htm" begin="30s" external="true"
actuate="onLoad" sourcePlaystate="play"/>
<area href="http://www.example.com/page2.htm" begin="1min" external="true"
actuate="onLoad" sourcePlaystate="play"/>
<area href="http://www.example.com/page3.htm" begin="2min" external="true"
actuate="onLoad" sourcePlaystate="play"/>
<area href="http://www.example.com/page4.htm" begin="3min" external="true"
actuate="onLoad" sourcePlaystate="play"/>
</audio>

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

Tip: Opening a Web page requires bandwidth. If your streaming media uses all of the viewer's available bandwidth, opening a Web page may cause the presentation to stall. When opening Web pages during a presentation, be sure that your streaming media uses less bandwidth than the maximum listed in the table "Maximum Streaming Rates".

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>

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


RealNetworks, Inc. ©2002 RealNetworks, Inc. All rights reserved.
For more information, visit RealNetworks
Click here if the Table of Contents frame is not visible at the left side of your screen.
previous next