previous next

Chapter 9: Clip Source Tags

For every clip you play in your presentation, such as an audio clip, video clip, or text clip, you add a source tag to your SMIL file. This chapter explains the basics of clip source tags, explaining how to write URLs that tell RealOne Player where to find clips. It also tells how to modify certain characteristics, such as background transparency, when clips play.

Creating Clip Source Tags

Each time you want a clip to appear in a presentation, you write a clip source tag that tells RealOne Player where to find the clip. The source tag URL may point RealOne Player to a clip on Helix Universal Server, a Web server, or even the viewer's local computer. A typical clip tag looks like this:

<audio src="rtsp://helixserver.example.com:554/audio/song1.rm"/>

Within each clip source tag, a src attribute lists the clip location. The section "Writing Clip Source URLs" explains how to specify a URL with the src attribute. As described in subsequent chapters, clip source tags can also contain other attributes that control clip timing and layout. The following table lists the different clip source tags you can use in a presentation.

Clip Source Tags
Clip Tag Used For
<animation/> animation clips such as a Flash Player file (.swf)
<audio/> audio clips such as RealAudio (.rm)
<brush/> color block used in place of a clip
(See "Creating a Brush Object".)
<img/> JPEG (.jpg), GIF (.gif), or PNG images (.png)
(See "Setting a Clip's Streaming Speed".)
<ref/> miscellaneous clip type, such as RealPix (.rp) or Ram (.ram) file
<text/> static text clips (.txt) or inline SMIL text
(See "Adding Text to a SMIL Presentation".)
<textstream/> streaming RealText clips (.rt)
<video/> video clips such as RealVideo (.rm)

The particular clip source tag you choose does not affect clip playback because RealOne Player determines the actual clip type by other means. Specifying a video clip with an <audio/> tag, for example, does not prevent RealOne Player from recognizing that the clip contains video. Although using a tag appropriate to the clip's contents helps you keep track of clips, you could specify all clips with <ref/> tags, for example. Other clip tags cannot be used in place of the <brush/> tag, however.

Adding a Clip ID

RealNetworks recommends that every clip source tag include a user-defined ID in the form id="ID". Clip IDs are not always necessary, but you will need to use them when building complex presentations in which other SMIL elements refer to clips. Clicking a hyperlink, for example, can start a clip playing. In this case, the hyperlink uses the clip's ID to identify which clip to start. RealOne Player never displays IDs onscreen. Here is an example of a clip ID:

<video src="video1.rm" id="video1"/>

For More Information: For information about selecting ID values, see "SMIL Tag ID Values".

Setting a Clip's Streaming Speed

Clips such as audio, video, and animation have a streaming speed set by the tools used to encode or tune the clips. For these clips, never use SMIL to set a streaming speed. For static clips such as images (GIF, JPEG, or PNG) and text (static text files and streaming RealText files), however, you can use SMIL to change the clip's streaming bandwidth from the default of 12 Kilobits per second (approximately 12000 bits per second). This works only when streaming from Helix Universal Server. With Web server hosting, there is no way to set a static clip's streaming speed.

Tip: Small text files stream so quickly that they rarely interfere with other clips. Therefore, you generally do not need to set the streaming bandwidth for text files. You should set a streaming bandwidth for image files larger than 5 Kilobytes, if the 12 Kbps default value is too high or too low for your target audience.

For More Information: For background information on streaming speeds, see "Audience Bandwidth Targets" and "Clip Bandwidth Characteristics".

Using the bitrate Parameter

To set a static clip's streaming speed, you modify the clip source tag to use binary tags, as described in the section "Binary and Unary Tags". Within the binary clip tag, you add a <param/> tag with the name bitrate, specify the speed in bits per second, and include the customized attribute rn:delivery="server", which requires that you declare the following namespace in the <smil> tag:

xmlns:rn="http://features.real.com/2001/SMIL20/Extensions"

The following example sets an image to stream at approximately 5 Kilobits per second:

<img src="poster.jpg" region="image_region" dur="15s">
<param name="bitrate" value="5000" rn:delivery="server"/>
</img>

RealOne Player does not display an image clip until it has received all the clip's data, and the clip is scheduled to display according to the SMIL timeline. For clips that have no intrinsic duration, such as images and text files (though not RealText clips), you must specify a duration.

For More Information: For more on image durations, see "Setting Durations". For background on customized attributes, see "Using Customized SMIL Attributes".

Example of Streaming Images Slowly

Using the bitrate parameter, you can set a high streaming speed for a clip to take advantage of available bandwidth and stream the image quickly. Or you can set a low bit rate to ensure that streaming the image does not interfere with playing another clip at the same time. The following example shows three sequential image files set to stream at 1000 Kbps to ensure that a video playing in parallel does not stall:

<par>
<video src="video.rm" region="video_region"/>
<par>
<seq>
<img src="ad1.gif" begin="30s" dur="60s" region="ad_region">
<param name="bitrate" value="1000" rn:delivery="server"/>
</img>
<img src="ad2.gif" dur="120s" region="ad_region">
<param name="bitrate" value="1000" rn:delivery="server"/>
</img>
<img src="ad3.gif" dur="60s" region="ad_region">
<param name="bitrate" value="1000" rn:delivery="server"/>
</img>
</seq>
</par>
</par>

For More Information: For more on SMIL timing, see Chapter 13. Chapter 11 explains group tags such as <par> and <seq>.

Ensuring Reliable Clip Transmission

You can use the reliable value in a <param/> tag to indicate that a clip must be delivered to RealOne Player under any circumstances. During extremely adverse network conditions, Helix Universal Server will halt the presentation if necessary rather than drop the clip. The following example shows the reliable parameter set for an image. Note that this parameter also requires the customized attribute rn:delivery="server":

<img src="poster.jpg">
<param name="bitrate" value="5000" rn:delivery="server"/>
<param name="reliable" value="true" rn:delivery="server"/>
</img>

Tip: Use the reliable parameter sparingly, and only for small, important elements of your presentation. Even without this parameter, Helix Universal Server generally ensures that very little data loss occurs in transmission.

Warning! The reliable parameter is not for use with large clips such as videos. These clips are designed to play well even if some data is lost in transmission. Using the reliable parameter with these clips may cause your presentation to stall.

Creating a Brush Object

The <brush/> tag lets you create a colored rectangle that displays in a region. You can use it to paint over a clip, for example. You can also use it like a background color. You might display a series of differently colored brush objects in a region behind a video for example, introducing each new brush object with a transition effect. To the viewer, the brush objects look like a dynamically changing region background.

A brush object functions just like a clip source tag. For example, you can control when the brush object appears by using SMIL timing commands, and you can even change a brush object's size and color with SMIL animation tags. Because it does not link to an external clip, though, the <brush/> tag does not use a src attribute. Instead, it uses a color attribute to define the color used:

<brush color="blue" region="region_1" dur="5s"/>

Black is the default color for a brush object. To specify a different color, use a predefined color name, a hexadecimal color value, or an RGB value.

For More Information: Appendix C explains the types of color values that you can use with SMIL color attributes. For more on transition effects and animations, see Chapter 16 and Chapter 17, respectively.

View it now! (requirements for viewing this sample)
Click this sample to see a simple sequence of brush objects. The next samples use brush objects to change a background dynamically as a RealPix slideshow and a sequence of videos plays in the foreground. Another sample uses brush objects that overlay a video for creative effects.

Using a Ram File as a Source

A Ram file (.ram) is typically used to launch RealOne Player and give it the URL of the clip or SMIL presentation to play. But you can also use a Ram file as a source of content within a SMIL file. Because a Ram file can list several clips in sequence, you may find it useful to specify a Ram file (a different Ram file from the one used to launch the presentation) within your SMIL file.

To illustrate how a Ram file is useful, suppose that your main SMIL presentation defines an online radio application that plays a preset song list that changes daily. You could list all the songs within the SMIL file in a sequence, like this:

<seq>
<audio src="song1.rm"/>
<audio src="song2.rm"/>
...more songs...
</seq>

Each day, though, you'd need to modify your main SMIL file to update the playlist. It's easier in this case to have the SMIL file request a Ram file through a <ref/> tag:

<ref src="http://www.example.com/dailysongs.ram"/>

Note: Use an HTTP URL like that shown above when listing a Ram file as a source clip within a SMIL file. Helix Universal Server does not stream Ram files through RTSP.

You then modify the Ram file each day with your new playlist. The Ram file simply gives the full URL to each song in the order in which they play:

rtsp://helixserver.example.com/song1.rm
rtsp://helixserver.example.com/song2.rm
...more songs...

When you use a Ram file as a source, you can add SMIL timing and layout attributes to the <ref/> tag. In a playlist of videos, for example, you could assign all the videos to play in the same region, which your main SMIL presentation would define. Or you could use timing attributes to give the entire sequence of clips a maximum duration, for instance. You cannot use SMIL attributes within a Ram file, however.

View it now! (requirements for viewing this sample)
The first sample is a SMIL file that plays three audio clips listed in a Ram file. The SMIL file is used to open HTML pages in RealOne Player. The next sample plays three video clips listed in a Ram file. SMIL is used to center each video on top of a graphic image.

For More Information: For more on Ram files, see "Launching RealOne Player with a Ram File". Note that a Ram file can also list other Ram or SMIL files, as well as clips.

Using a SMIL File as a Source

A SMIL file can also use another SMIL file as a source. Unlike a Ram file, a SMIL file can do more than list a simple sequence of clips. A secondary SMIL file can play clips in parallel, for example, and use SMIL timing and layout attributes to organize its clips. Simply use a <ref/> tag to refer to the secondary SMIL file:

<ref src="rtsp://helixserver.example.com/presentation2.smil"/>

View it now! (requirements for viewing this sample)
This SMIL file plays two SMIL source files in sequence. Each SMIL source file plays a text clip and a video clip side-by-side.

Handling Layouts

When a primary and secondary SMIL file define layouts, you need to be careful that the layouts do not conflict. In some cases, you can define a layout only in your referenced SMIL file, not in the primary file. The section "Full SMIL File Switching" provides an example of this in the context of SMIL switching.

When a referenced SMIL file contains visual clips, you can assign the file to a single region defined in the primary SMIL file. For example, the following clip source tag assigns the referenced SMIL file to region_1, which is defined within the primary SMIL file:

<ref src="rtsp://helixserver.example.com/presentation2.smil" region="region_1"/>

In this case, it's best to define the playback region in the primary SMIL file (region_1) to be the same size as the root-layout area of the secondary SMIL file. If the playback region and the secondary SMIL presentation are different sizes, the playback region's fit attribute determines how the SMIL presentation fits the region.

For More Information: For information on defining layouts and assigning clips to play in regions, see Chapter 12.

Using Timing Attributes

Timing attributes in the primary SMIL file can override the timeline of the secondary SMIL file. Suppose that presentation2.smil lasts 10 minutes when played by itself, but you set a 5-minute duration in the <ref/> tag in the main SMIL file. In this case, the duration specified in the main SMIL file cuts off the last half of presentation2.smil:

<ref src="rtsp://helixserver.example.com/presentation2.smil" dur="5min"/>

For More Information: Timing attributes are described in Chapter 13.

Writing Clip Source URLs

Every clip source tag, except for a <brush/> tag, requires an src attribute that provides the URL for the clip. RealOne Player uses this URL to request the clip from a server. The URL you specify varies depending on whether the clip resides on Helix Universal Server, a Web server, or the viewer's local machine.

Tip: As you develop a presentation on your computer, use local URLs. Then put in a base URL, or specify full URLs for each clip, when you are ready to stream your presentation. Chapter 21 explains how to move clips to a server and write a Ram file to launch RealOne Player.

Linking to Local Clips

As you develop your presentation, it is easiest to keep your SMIL file and your clips in the same directory on your local computer. Within your SMIL file, the src parameter for each clip source tag can simply give the file name:

<audio src="song1.rm"/>

Creating Relative Links to Other Directories

RealOne Player can also follow the same relative links that you can use in a Web page. 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. 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 it includes three forward slashes in file:///, and uses forward slashes in path names as well:

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

Creating a Base URL

When you are ready to stream your presentation, you can add a base URL to your SMIL file. This is convenient if all or most of your clips reside on the same server. This preserves the local, relative syntax you used when developing your presentation, readying your presentation for streaming in a single step. You add the base URL to the file in the SMIL header section through a <meta/> tag as shown here:

<smil xmlns="http://www.w3.org/2001/SMIL20/Language">
<head>
<meta name="base" content="rtsp://helixserver.example.com/"/>
...layout information...
</head>
<body>
<par>
<audio src="song1.rm"/>
<textstream src="lyrics/words1.rt" .../>
<img src="http://www.example.com/images/album3.gif" .../>
</par>
</body>
</smil>

Because the third clip in this example uses a full URL, the base target is ignored. RealOne Player requests the image from the specified Web server using the HTTP protocol. For the first two clips, however, the src values are appended to the base target, effectively giving the clips the following URLs:

rtsp://helixserver.example.com/song1.rm
rtsp://helixserver.example.com/lyrics/words1.rt

Using a base target is highly recommended. If no target is given, RealOne Player assumes that the clip paths are relative to the location of the SMIL file. In the preceding example, for instance, RealOne Player would look for song1.rm in the same directory that holds the SMIL file, requesting the clip with the same protocol used to request the SMIL file.

Keep in mind that the base URL specifies both a location and a request protocol. If, for example, your SMIL presentation includes both streaming clips and HTML pages opened through SMIL, you can place your clips and HTML pages in the same directory on Helix Universal Server. However, if your base URL uses rtsp://, you can't use the base URL for the HTML pages, which require a URL that starts with http://. In this case, use a fully-qualified HTTP URL for each HTML page listed in your SMIL file.

Linking to Clips on Helix Universal Server

When clips reside on Helix Universal Server, use an RTSP URL in the base target. Or, you can specify an RTSP URL in each clip's src attribute. An RTSP URL in a clip source tag looks like this:

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

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

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

For More Information: For more information on RTSP, see "The Difference Between RTSP and HTTP".

Linking to Clips on a Web Server

To use a clip hosted on a Web server, use a standard HTTP URL in the base target, or in each clip's src attribute. Helix Universal Server also supports the HTTP protocol, but for clips streaming from Helix Universal Server, you typically use the RTSP protocol or the specialized CHTTP protocol, which is described in the following section. An HTTP URL in a clip source tag looks like this:

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

Warning! Although a Web server can host any clip, a Web server cannot perform all the functions of Helix Universal Server. For more information, see "Limitations on Web Server Playback".

Caching Clips on RealOne Player

RealOne Player does not cache clips that play in the media playback pane by default, but you can make it cache on disk any clips delivered through HTTP. You may want to cache images used in different SMIL presentations that site visitors play. An example is an Internet radio station that uses GIF logos and on-screen buttons. As long as the GIFs reside in the RealOne Player cache, the server does not have to resend the files if, for example, the user clicks a link that opens a new SMIL presentation containing the same images.

Caching works only for files delivered through HTTP. You should not try to cache large clips that would be served better through RTSP, such as video, audio, Flash, and RealPix clips. (RealOne Player caches RealPix images in memory, but not on disk, for the duration of the RealPix presentation.) Nor should you cache ads or images that do not appear repeatedly in your presentation.

For More Information: For information about the caching of content that displays in the related info pane, see "HTML Page Caching".

Using the CHTTP Caching Protocol

RealOne Player does not cache all items streamed by HTTP. Instead, you designate files to cache by using chttp:// instead of http:// in the file URLs. When RealOne Player reads a CHTTP URL in a SMIL file, it first checks its disk cache for the file. If the file is not present, RealOne Player requests the file through HTTP, storing the file in its cache. Because RealOne Player interprets a chttp:// URL as a special instance of HTTP, caching works for any file stored on an HTTP-compatible server.

If a file is stored in RealOne Player's cache, RealOne Player reuses the file instead of requesting it again from the server, as long as a CHTTP URL is used. The cached version is not used, though, if the URL starts with http:// or differs in any way from the original CHTTP URL. The following SMIL example indicates that the specified GIF image should be downloaded and cached for later use:

<img src="chttp://www.example.com/images/image1.gif" .../>

Example of Using CHTTP in a Presentation

When caching files, download the cached items before streaming other elements. You can do this by placing the cached elements in a SMIL <seq> group ahead of the streamed elements. In the following example, the two logos quickly download before the RealVideo and RealText clips play. If the visitor plays another presentation that also caches the two images, RealOne Player first checks its cache. If it finds the images, it skips directly to the streaming clips:

<smil xmlns="http://www.w3.org/2001/SMIL20/Language">
...header omitted...
<body>
<seq>
<!-- First, download and cache these two logos. -->
<img src="chttp://www.example.com/logo1.gif region="logo1" ...>
<param name="bitrate" value="20000" rn:delivery="server"/>
</img>
<img src="chttp://www.example.comlogo2.gif region="logo2" ...>
<param name="bitrate" value="20000" rn:delivery="server"/>
</img>
<par>
<!--Second, stream these 2 clips in parallel. -->
<textstream src="rtsp://helixserver.example.com/news.rt" region="news" .../>
<video src="rtsp://helixserver.example.com/newsvid.rm" region="video1" .../>
</par>
</seq>
</body>
</smil>

Controlling the RealOne Player Cache

Because RealOne Player supports the same HTTP header fields used to control file expiration in Web browser caches, it can carry out caching directives set by Web servers. Thus, you can reuse Web page images in RealOne Player presentations without losing control of how these images are cached. This section describes how to use HTTP headers to control the RealOne Player cache, and how RealOne Player manages its cache. Documentation for most Web servers includes information about how to set fields in HTTP header files.

Overriding Caching with Cache-Control

The Cache-Control command of an HTTP header file can override caching of a RealOne Player file requested through chttp://. A file requested through CHTTP is not cached if any of the following are present as meta-information in the HTTP header file:

Cache Size and Expiration Rules

RealOne Player caches files within its home directory in a folder named cache_db. This cache is independent of any Web browser cache. The default RealOne Player cache size is 4 MB. Unless an HTTP header sets a file lifetime, the cached file expires after 4 hours, although a subsequent request for a cached item restarts the item's expiration clock. As the cache fills, RealOne Player begins to delete unexpired items to reclaim needed disk space on a first- in, first-out basis.

Note: RealOne Player users can control some aspects of RealOne Player's cache by disabling the cache, setting the amount of disk space available for the cache, and emptying the cache. Users carry out these actions through the RealOne Player preferences. For more information, see the RealOne Player online help.

Changing the Lifetime of a Cached File

Within an HTTP header, you can have Cache-Control:max-age set the "time to live" (TTL) for a cached file, overriding the default expiration time. Expressed in seconds, the maximum age is added to the current time to yield the file's expiration time. This value must be between 60 seconds and one year. For example:

Cache-Control:max-age=172800

If you do not use the Cache-Control:max-age field, you can have the Expires field determine the file's expiration time. The Expires field takes as an attribute a date string that defines when the cached element expires, relative to the caching computer's clock. The date string is formatted as follows:

Expires= Wdy, DD Mon YYYY HH:MM:SS GMT

The weekday is optional. In the following two examples, the first example includes a weekday designation, the second one does not:

Expires= Fri, 17 Mar 2000 19:37:09 GMT
Expires= 17 Mar 2000 19:37:09 GMT

The weekday and month abbreviations are as follows:

Day of week: Mon, Tue, Wed, Thu, Fri, Sat, Sun
Month: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec

Note: The entry is not cached if the value in the Expires: field predates the current date and time.

Modifying Clip Colors

The clip color attributes summarized in the following table are primarily for images in the GIF, JPEG, or PNG format. They can also be used for dynamic clips, though, especially those that include transparency, such as Flash clips. They should not be used for streaming video, however. Note that because these attributes are specific to RealOne Player, other SMIL-based media players may not recognize them.

Clip Streaming and Color Attributes
Attribute Value Function Reference
rn:backgroundOpacity percentage Adjusts background transparency. click here
bgcolor nnnnnn Substitutes color for transparency. click here
rn:chromaKey color_value Turns selected color transparent. click here
rn:chromaKeyOpacity percentage Adds opacity to chromaKey. click here
rn:chromaKeyTolerance color_value Widens range of chromaKey. click here
rn:mediaOpacity percentage Makes opaque colors transparent. click here

For More Information: Appendix C explains the types of color values you can use with SMIL color attributes.

Adjusting Clip Transparency and Opacity

Two customized attributes let you add transparency to all opaque colors in a clip (rn:mediaOpacity), or adjust transparency in just the clip's background color (rn:backgroundOpacity). You can use these attributes separately or together. Using either of these attributes requires that you declare the following namespace in the <smil> tag:

xmlns:rn="http://features.real.com/2001/SMIL20/Extensions"

For More Information: For the basics of namespaces, see "Using Customized SMIL Attributes".

Adding Transparency to All Opaque Colors

The attribute rn:mediaOpacity in a clip source tag causes opaque areas in the clip to become transparent. The attribute takes a percentage value in the range from 0% (fully transparent) to 100% (fully opaque). In the following example, the opaque areas of a GIF image are rendered partially transparent, making them blend with a region's background color or an underlying clip:

<img src="button.gif" rn:mediaOpacity="50%" .../>

Note: If a clip is 50 percent or more transparent (that is, it has a value from 0 to 50 for rn:mediaOpacity), hyperlinks defined for the clip will not work. Clicking the clip will open hyperlinks on clips beneath the partially transparent clip, however. Chapter 15 explains SMIL hyperlinks.

View it now! (requirements for viewing this sample)
In RealOne Player, you can view how the mediaOpacity attribute affects an opaque clip.

Creating Transparency in a Clip's Background Color

Using the rn:backgroundOpacity attribute, you can modify the opacity of a clip's background, making the background color more transparent or more opaque. This attribute works only for clips that designate a specific background color, such as GIF, PNG, or RealText clips. It does not work for clips like JPEG images or RealVideo clips that do not explicitly specify a background color.

The rn:backgroundOpacity attribute takes a percentage value in the range from 0% (fully transparent) to 100% (fully opaque). In the following example, the background color specified in the image's palette, which may be fully opaque or fully transparent, is rendered partially opaque:

<img src="button.gif" rn:backgroundOpacity="50%" .../>

If the background color is partially transparent already, rn:backgroundOpacity increases the opacity. If a clip's background is 50 percent transparent already, for example, using rn:backgroundOpacity="50%" adds another 50 percent to the opacity, making the background 75 percent opaque.

Tip: If a clip's background is fully opaque, you can use just rn:mediaOpacity to render the background and all other colors transparent. If the clip's background is partially transparent already, rn:mediaOpacity will not affect the background, and you can use both rn:mediaOpacity and rn:backgroundOpacity in the same clip tag.

View it now! (requirements for viewing this sample)
In RealOne Player, you can view how the backgroundOpacity attribute adds opacity to a transparent background. You can also view semi- transparent RealText subtitles.

Substituting Transparency for a Specific Color

For clips that do not include native transparency, such as JPEG images and Flash clips, you can use three attributes to define a color (rn:chromaKey), or a range of colors (rn:chromaKeyTolerance), that RealOne Player renders transparent or partially transparent (rn:chromaKeyOpacity). Using these attributes requires that you declare the following namespace in the <smil> tag:

xmlns:rn="http://features.real.com/2001/SMIL20/Extensions"

For More Information: For background on customized attributes, see "Using Customized SMIL Attributes".

View it now! (requirements for viewing this sample)
With this sample, you can view how the chroma key attribute substitutes transparency for specified color ranges.

Selecting a Color to Render Transparent

You can use rn:chromaKey to specify one (and only one) color that RealOne Player will render transparent. In the following example, the hexadecimal color #808080 is made transparent in a JPEG clip:

<img src="picture.jpg" rn:chromaKey="#808080".../>

Tip: You can specify colors by using any color value described in Appendix C. For example, the preceding attribute could use the RGB value "rgb(128,128,128)" instead of the hexadecimal "#808080".

Using Partial Transparency

You can use the rn:chromaKeyOpacity attribute to make the color value selected by rn:chromaKey partially transparent instead of fully transparent. The chromaKeyOpacity attribute uses a percentage value from 0% (the default value of full transparency) to 100% (fully opaque). In the following example, the selected color is rendered 50 percent transparent instead of fully transparent:

<img src="picture.jpg" rn:chromaKey="#808080" rn:chromaKeyOpacity="50%"/>

Expanding the Transparency Range

To achieve the desired transparency effect, you may need to use the attribute rn:chromaKeyTolerance to widen the range of colors selected by rn:chromaKey. Although rn:chromaKeyTolerance uses a value that looks like a single color designation, the value actually specifies a range of colors around (both above and below) the rn:chromaKey value.

The following example uses rn:chromaKey to turn the hexadecimal color #808080 transparent. The rn:chromaKeyTolerance attribute specifies a 1-value tolerance both above and below the designated red value of 80. So in this case, the colors #7F8080 and #818080 are rendered transparent along with #808080:

<img rn:chromaKey="#808080" rn:chromaKeyTolerance="#010000".../>

Setting Red, Green, and Blue Tolerances

In most cases, you'll want to specify tolerance ranges for red, green, and blue. When you do this, only the colors that fall within the overall range set by all the designated tolerances are rendered transparent. For example, the following three attribute pairs are all equivalent, but use different color values, which are described in Appendix C:

rn:chromaKey="rgb(128,128,128)" rn:chromaKeyTolerance="rgb(1,2,3)"
rn:chromaKey="rgb(50%,50%,50%)" rn:chromaKeyTolerance="rgb(0.4%,0.8%,1.2%)"
rn:chromaKey="#808080" rn:chromaKeyTolerance="#010203"

All of the preceding examples define a 1-value tolerance around the specified red value, a 2-value tolerance around the designated green value, and a 3-value tolerance around the selected blue value. Therefore, the colors that have the following RGB values are rendered transparent:

So, for example, the following colors would be rendered transparent because they fall within the range specified by all three tolerance settings:

However, the following colors would not be rendered transparent because they fall outside the overall range defined by all the red, green, and blue tolerance values:

Tips for Expanding the Color Transparency Range

Substituting a Color for Transparency

For clips that include transparency, such as GIF and PNG images, you can use bgcolor to substitute a color for the transparency. This attribute uses a <param/> tag, requiring the use of binary clip source tags. The value must be a hexadecimal color value without a leading pound sign (#), as shown in this example:

<img src="button.gif"...>
<param name="bgcolor" value="BB21AA"/>
</img>

For More Information: For background information on binary tags, see "Binary and Unary Tags".

Adding Text to a SMIL Presentation

Within the RealOne Player media playback pane, a SMIL presentation can display text in three different ways:

Displaying a Plain Text File

To add a plain text file to a SMIL presentation, you refer to the file in a clip source tag, as shown here:

<text src="http://www.example.com/textfile.txt" region="region2" dur="40s".../>

As with any other type of clip, you can assign a text file to a SMIL region and use SMIL timing commands to control when the text file displays. By default, a text file appears as black text on a white background, using the default text font, size, and character set for the computer running RealOne Player.

View it now! (requirements for viewing this sample)
Play this sample to view a text file displaying in a SMIL presentation.

For More Information: See "Changing Text Characteristics" for information about changing the font, color, size, and character set of a plain text clip.

Tips for Using a Plain Text File

Writing Inline Text

Inline text, which is defined within the SMIL file, is useful for short text blocks that annotate the SMIL presentation. You can also combine inline text with advanced SMIL timing commands to create interactive buttons. For long text, however, it is easier to use either a plain text file as described above, or a RealText clip as described in Chapter 6. Inline text appears as black text on a white background, using the default text font, size, and character set for the computer running RealOne Player. You can change these characteristics, however, as described in "Changing Text Characteristics".

You create inline text with a <text/> tag, specifying the text through the tag's src attribute. Two formats for the src parameter are acceptable. The first format is the following:

src="data:text/plain,...text here..."

The second, shorter format, which you can use because the SMIL 2.0 default MIME type for data URLs is text/plain, is used for examples in this guide:

src="data:,...text here..."

Note that both formats start with data: and must include a comma before the actual text. For example, to display the following text in the SMIL file:

This is Inline Text

you would create the following <text/> tag, assigning the inline text to a SMIL region and adding SMIL timing commands:

<text src="data:,This%20is%20Inline%20Text" region="text_region" .../>

Note that you must use the escape character %20 to represent a space. As explained below, you must use additional escape characters to represent other characters within inline text.

View it now! (requirements for viewing this sample)
Play this sample to view inline text clips that use advanced SMIL features, including animations and transition effects.

Using Inline Text Escape Characters

The following table lists the text characters that you can add to inline text only through their corresponding escape codes. Entering one of these characters directly in the inline text string creates an error in RealOne Player.

Text Characters Requiring Escape Codes
Name Character Escape Code
ampersand & %26
backslash \ %5C
carat ^ %5E
carriage return   %0D
double quote " %22
greater than sign > %3E
left bracket [ %5B
less than sign < %3C
line feed   %0A
percent sign % %25
plus sign + %2B
pound sign # %23
right bracket ] %5D
space   %20
tab   %09

You can enter other common text characters, such as commas, periods, and colons directly into the src value of the inline text. Conversely, you can display any text character, including letters and numbers, by using an escape code that starts with % followed by the character's ASCII hexadecimal value. You can create an asterisk (*) with the escape code %2A, for example.

For More Information: Visit http://www.asciitable.com/ for a full list of ASCII codes.

Tips for Using Inline Text

Changing Text Characteristics

Plain text files and inline text clips use the computer's default character set and font. Text is black on a white background. Using <param/> tags, however you can change the fonts, colors, character sets, and other characteristics. This requires that you turn your <text/> tag into a binary tag as described in "Binary and Unary Tags". You can then use the name and value pairs listed in the following table.

<param/> Tag Names and Values for Plain Text and Inline Text
Name Values Function Reference
backgroundColor name|#RRGGBB Sets the background color. click here
charset character_set Defines the character set. click here
expandTabs true|false Replaces tabs with spaces. click here
fontBackgroundColor name|#RRGGBB Sets the color behind the text. click here
fontColor name|#RRGGBB Selects the font color. click here
fontFace font_name Determines the font used. click here
fontPtSize point_size Sets a specific point size. click here
fontSize -2|-1|+0|+1|+2|+3|+4
or
1|2|3|4|5|6|7
Sets the font relative or absolute size. click here
fontStyle italic|normal Italicizes text. click here
fontWeight 100-900|bold|normal Turns text bold. click here
hAlign left|center|right Aligns text horizontally. click here
vAlign top|center|bottom Aligns text vertically. click here
wordWrap true|false Turns off word wrapping. click here

Note: Text characteristics appear only with RealOne Player version 2 and higher. Version 1 of RealOne Player ignores the <param/> tags, but displays the text clip with its default characteristics. Text characteristics set through <param/> tags cannot be modified by SMIL animations.

Tip: Text characteristics such as the font choice, bolding, text size, and so on apply to the entire text clip. To change characteristics for text blocks, by italicizing some words but not others, for example, you need to use RealText as described in Chapter 6.

Choosing a Character Set

Using plain text files and inline text, you can write in many European, Middle Eastern, and Asian languages. To do so, you may need to use the charset parameter to specify a character set listed in the following table. The character set must be installed on the viewer's computer for text to display properly. For example, Japanese text will not display on computers that do not have the x- sjis character set installed.

Plain Text and Inline Text Character Sets
Character Set Language Support
iso-8859-1 Western European languages, including English, Spanish, French, German, Dutch, Italian, and Scandinavian languages (for more information, see "iso-8859-1")
iso-8859-2 Eastern European languages, including Czech, Hungarian, Polish, and Romanian
iso-8859-5 Cyrillic text for languages including Russian, Bulgarian, Serbian, and Ukrainian
iso-8859-6 Arabic alphabet
iso-8859-7 Modern Greek
iso-8859-8 Hebrew and Yiddish
iso-8859-9 Turkish
iso-8859-11 Thai
iso-8859-13 Baltic languages, including Latvian and Estonian
us-ascii American English (you can also use iso-8859-1)
mac-roman Accented European characters entered on a Macintosh (for more information, see "mac-roman")
x-sjis Japanese
hangeul Korean
ksc5601 Korean (identical to hangeul)
johab Korean
big5 Traditional Chinese
gb2312 Simplified Chinese
windows-1251 Cyrillic text
koi8-r Cyrillic text
iso-ir-166 Thai

Using the Viewer's Default Character Set

If you do not specify the character set, the text file or clip uses the default character set installed on the viewer's machine. You can often leave the character set unspecified if you and your audience speak the same language. For example, most English-speaking audiences have us-ascii or iso-8859-1 installed as their default character set.

Multilingual audiences may use multiple character sets, however, which can cause problems if you do not specify the character set. For example, some viewers may have both iso-8859-1 and iso-8859-2 installed. If iso-8859-2 is the default, Western European languages will not display correctly if you do not explicitly specify iso-8859-1 as the character set.

Selecting a Font

Using the fontFace parameter, you can specify any screen font on the viewer's machine. Some fonts require specific character sets. The Osaka font for Kanji characters requires the x-sjis character set, for example. If you do not set the font, the text clip uses the default font on the viewer's computer. If the viewer does not have the specified font installed, the computer substitutes a font (typically the default display font). The following example shows inline text specifying a character set and font:

<text src="data:,This%20is%20inline%20text." region="text_region" dur="8s">
<param name="charset" value="iso-8859-1"/>
<param name="fontFace" value="System"/>
</text>

Tip: For samples of fonts used with RealText, see "Setting the Font". Keep in mind, though, that RealText uses only a predefined set of fonts, whereas plain text files and inline text clips can use any screen font installed on the viewer's computer.

Choosing Font Colors

By default, text displays in black on a white background. Within separate <param/> tags, you can use fontColor to set the font letter color, and backgroundColor to specify the clip's background color. You can also use fontBackgroundColor to create a third color that appears behind the text, but does not fill the entire window, as does backgroundColor. For all color values, choose color names or hexadecimal values as described in Appendix C. The following example shows a plain text file that displays in a yellow font on a blue background:

<text src="plain.txt" region="text_region" dur="8s">
<param name="fontColor" value="yellow"/>
<param name="backgroundColor" value="blue"/>
</text>

Tip: To place text on top of a graphic image, render the text background transparent with rn:backgroundOpacity="0%" in the <text/> tag. For more information, see "Creating Transparency in a Clip's Background Color".

Note: The fontBackgroundColor parameter does not currently work with RealOne Player on the Macintosh.

View it now! (requirements for viewing this sample)
The first sample shows various fonts, sizes, and colors for a plain text file. The next sample does the same for inline text.

Setting Font Sizes

Two <param/> tag attributes, fontPtSize, and fontSize, let you set the text size. For fontPtSize you specify an exact point size, such as 36. The fontSize attribute uses the same size indicators used in RealText, which are listed in the table "RealText Font Sizes". Use either fontPtSize or fontSize for a text clip, but not both. Here are two examples:

<text src="data:,This%20is%20inline%20text." region="text_region1" dur="8s">
<param name="fontPtSize" value="36"/>
</text>
<text src="data:,This%20is%20inline%20text." region="text_region2" dur="8s">
<param name="fontSize" value="+2"/>
</text>

Bolding or Italicizing Text

For fontWeight, you can specify normal (the default), bold, or a value from 100 to 900, in which 100 is thin text, 400 is normal text, 700 is bold, and 900 is thick, dark text. For fontStyle, you can use normal (the default) or italic. Note that you cannot bold or italicize just parts of a text clip. Here is an example of a bolded plain text file:

<text src="plain.txt" region="text_region" dur="8s">
<param name="fontWeight" value="bold"/>
</text>

Note: Not all numeric values affect all fonts. Some fonts support only normal and bold appearances. In this case, you won't see a difference between the values 100 and 400, or the values 700 and 900. With other fonts, though, the differences may be pronounced.

Turning off Word Wrap

By default, a plain text file or inline clip automatically wraps to fit its assigned SMIL region so that no text is cut off at the region's right edge. The text may be truncated at the region's bottom edge, though, if there is too much text, or its font size is too large to fit inside the region. You can turn off word wrapping by adding a wordWrap parameter with the value false:

<text src="plain.txt" region="text_region" dur="8s">
<param name="wordWrap" value="false"/>
</text>

Ignoring Tabs

RealOne Player recognizes tabs in the text clip. To turn off tabbing, use the expandTabs parameter with a value of false. Each tab is then rendered as a single space:

<text src="plain.txt" region="text_region" dur="8s">
<param name="expandTabs" value="false"/>
</text>

Aligning Text

The hAlign parameter aligns an inline text clip or text file horiziontally. It can use the value left (the default), center, or right to align the text flush-left, center, or flush-right within its SMIL region, respectively. The vAlign parameter uses the value top (the default), center, or bottom to align the text vertically. Using vAlign requires that you set wordWrap to false. You cannot use both hAlign and vAlign with a single text clip.

Note: Currently, vertically aligned text does not recognize carriage returns in plain text clips, or carriage return and line feed escape codes (%0D%0A) in inline text. You can therefore align only a single line of text.

View it now! (requirements for viewing this sample)
This sample shows horizontal and vertical alignment for inline text.


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