previous next

Chapter 6: RealText Markup

With RealText, you can create timed text presentations that can stream alone or in combination with other media such as audio or video. This makes RealText a handy means for adding text to SMIL presentations. Using RealText, you can add subtitles to a video, for example, or provide closed-captioning. This chapter explains the RealText markup. Appendix E provides a reference for RealText tags and attributes.

Understanding RealText

Using any text editor, you can create a RealText clip in a text file that uses the file extension .rt. The file includes the text you want to display, as well as the RealText markup that describes how to display and time the text. Like a RealVideo or Flash clip, a RealText clip has a height and width, as well as an intrinsic duration, from a few seconds to several hours. The following are some of the features that RealText provides:

RealText Language Support

RealText supports a number of languages, including English, Chinese, Korean, Japanese (Kanji), and many European languages. It can stream text in any language that can be written in one of its supported character sets, which are listed in the section "Specifying the Character Set". Each character set supports at least one font, as described in "Setting the Font".

Note: Character set and font support is built into RealText. Therefore, RealText does not necessarily support all character sets and fonts supported by various Web browsers.

Text Alternatives

In addition to RealText, RealPlayer can play plain text clips (.txt) and inline text, which is text written directly into a SMIL file. When you use plain text or inline text, all the text displays at once, and you cannot position text blocks at different parts of the screen, or apply styles such as bolding only to certain words. However, plain text and inline text support a wider range of fonts and character sets than RealText, and are well-suited to static text display. You can use inline text to label media clips, for example, or create interactive "buttons" through SMIL commands.

For More Information: To use plain text or inline text, refer to "Adding Text to a SMIL Presentation".

Structure of a RealText Clip

A RealText clip is a text file that uses the file extension .rt. At the top of the file you write a <window> tag that can include several attributes that set overall parameters, such as the window type, width, height, and duration. The file ends with a </window> tag. Between these tags, you add the text that you want to display in RealPlayer, using RealText tags and attributes to lay out and time the text. The following example is a simple RealText file that displays a new line of text every three seconds: 

<window height="250" width="300" duration="15" bgcolor="yellow">
Mary had a little lamb,
<br/><time begin="3"/>little lamb,
<br/><time begin="6"/>little lamb,
<br/><time begin="9"/>Mary had a little lamb
<br/><time begin="12"/>whose fleece was white as snow.
</window>

Rules for RealText Markup

The RealText markup is similar to SMIL, and follows the same basic rules described in "Creating a SMIL File". The following are the main points in mind when writing a RealText file:

RealText Bandwidth

Because a RealText clip is a simple text file, it consumes minimal bandwidth and streams quickly to RealPlayer. RealText presentations are therefore easily accessible to viewers with slow network connections. When combining RealText with other clips, you need to ensure that RealText has approximately 1 Kbps of available bandwidth.

Tip: If you have a large RealText file, you can compress it with GZIP when delivering the clip from many Web servers. For more information, see "GZIP Encoding for Large Text Files".

For More Information: For more on bandwidth allocation, see "Step 4: Develop a Bandwidth Strategy".

RealText in a SMIL Presentation

You can easily combine RealText with any other clip through a SMIL file. Chapter 8 explains the basics of SMIL. The section "Playing Clips in Parallel" explains how to display RealText along with other clips. You'll also need to understand SMIL layouts as described in Chapter 12. The section "RealText Window Size and SMIL Region Size" explains various ways to coordinate the RealText window size to its SMIL region size.

Tip: To see examples of RealText displayed with other clips, 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.

RealText Broadcast Application

RealText does not have to be created in a static file. A broadcast application can capture live text, add RealText markup to it, and send it to Helix Server. A sample broadcast application is included with the Software Development Kit (SDK), available for download at this Web page:

http://proforma.real.com/rnforms/resources/server/realsystemsdk/ind ex.html

Setting RealText Window Attributes

The <window> and </window> tags that begin and end a RealText file, respectively, set presentation attributes such as the window's height and width Here is an example of a <window> tag: 

<window type="marquee" duration="2:05:00.0" underline_hyperlinks="false">
...all text and RealText markup...
</window>

You specify attributes in the form attribute="value" within the <window> tag, much as you specify HTML table attributes within the HTML <TABLE> tag. No attributes are required for the <window> tag, however. If you do not specify an attribute, the attribute's default value applies. The following table summarizes the <window> tag attributes.

RealText <window> Tag Attributes
Attribute Value Function Reference
bgcolor name|#RRGGBB|transparent Sets the window color. click here
crawlrate pixels_per _second Sets the horizontal text speed. click here
duration hh:mm:ss.xy Specifies presentation length. click here
extraspaces use|ignore Recognizes or ignores extra spaces in text. click here
height pixel Sets the window pixel height. click here
link name|#RRGGBB Specifies the hyperlink color. click here
loop false|true Turns text looping on or off. click here
scrollrate pixels_per _second Sets the vertical text speed. click here
type generic|tickertape|
marquee|scrollingnews|
teleprompter		 Sets the window type. click here
underline_hyperlinks false|true Determines whether hyperlinks are underlined. click here
version 1.0|1.2|1.4|1.5 Specifies RealText version. Required for some character sets. click here
width pixels Sets the window pixel width. click here
wordwrap false|true Turns word wrap on or off. click here

Specifying the Window Type

The <window> tag's type="window type" attribute sets specific properties for the RealText clip: 

<window type="scrollingnews" ...>

Choose a window type depending on how you want to display text. Each window type has preset default values that make it easier to create certain types of text displays. You can create any type of RealText clip using just the default window type of generic, however. The following are the RealText window types. Click the link to see an example of each of these window types in RealPlayer:

Window Type Default Values

Each window type sets a number of default values for the RealText clip. The following table lists the attribute default values that differ based on the choice of window type. Keep in mind that you can change any default value for any window type through the <window> tag. If you want a marquee window to be 320 pixels wide instead of 500 pixels, for example, you add width="320" to the <window> tag to override the window type's default width value.

Default Values for RealText Window Types
Value generic scrollingnews teleprompter marquee tickertape
width in pixels (click here) 320 320 320 500 500
height in pixels (click here) 180 180 180 30 30
background (click here) white white white white black
horizontal crawl rate in
pixels per second (click here)		 0 0 0 20 20
vertical scroll rate in
pixels per second (click here)		 0 10 0 0 0
text looping (click here) no no no yes yes

Setting the Window Size and Color

The width and height attributes determine the RealText window's width and height in pixels, respectively. The bgcolor attribute determines the window's background color. "Specifying RealText Color Values" explains RealText color values. Here is an example that sets a window size and color: 

<window width="400" height="225" bgcolor="blue"...>

For More Information: Default values for size and background color are listed in the table "Default Values for RealText Window Types".

Creating a Transparent Window Background

Using the rn:backgroundOpacity attribute in SMIL, you can turn the RealText window's background color fully transparent or semi-transparent, which is useful when overlaying a video with RealText subtitles. Within the RealText file, you define an opaque color, such as black or white, as the value of the <window> tag's bgcolor attribute. In your SMIL file, you then specify a percentage value for rn:backgroundOpacity.

For More Information: For more information about rn:backgroundOpacity, see "Creating Transparency in a Clip's Background Color". For an example of using SMIL to display different RealText subtitles based on viewer language preferences, see "Subtitles and HTML Pages in Different Languages".

View it now! (requirements for viewing this sample)
This sample displays RealText subtitles with a semi-transparent background over a video clip.

RealText Window Size and SMIL Region Size

When you add RealText to a SMIL presentation, you display your RealText clip in a SMIL region. For best results, create a SMIL region that is the same height and width as the RealText clip. Displaying a RealText clip in a SMIL region that is larger or smaller than the clip may enlarge or shrink the text, depending on how you set the <region> tag's fit attribute. The sections below explain which fit values are best to use.

Note that enlarging or shrinking a RealText clip through SMIL does not affect line breaks. Line breaks are determined by the RealText window's width, font, and font size. You could place a RealText window that is 200 pixels wide in a SMIL region that is 150 pixels wide, for example, and scale the clip's width down by adding fit= "fill" to the SMIL <region> tag. This simply makes all the text smaller. It does not cause lines to break at different places within the text.

For More Information: SMIL regions are described in "Playback Regions". The section "Fitting Clips to Regions" explains the <region> tag's fit attribute. RealText word wrapping is described in "Wrapping Text to New Lines".

When a SMIL Region is Larger than the RealText Clip

When the SMIL region is larger than the RealText clip, the default value fit="hidden" is recommended for the <region> tag. This keeps the RealText clip as its specified size. You can then use a registration point, as described in "Positioning Clips in Regions", to position the clip within the region. The registration point might center the clip in the region, for example.

If you want to scale the RealText clip larger, using fit="meet" in the <region> tag typically gives the best results because it preserves the clip's aspect ratio. This scales the text larger but maintains the relative letter spacing. You can use fit="fill" to make the RealText clip the same size as the region, but distortion in letter spacing may make the clip unreadable if the region has a markedly different width-to-height ratio than the clip.

View it now! (requirements for viewing this sample)
In this sample, you can view the same RealText clip displayed in four larger SMIL regions that have different fit attributes.

When a SMIL Region is Smaller than the RealText Clip

When the SMIL region is smaller than the RealText clip, the default value fit="hidden" in the <region> tag may prevent some text from displaying. The value fit="meet" is generally the best choice, because it scales the clip smaller to fit completely inside the region while preserving the relative letter spacing. When displaying RealText in a smaller region, though, you need to be careful to keep the text from scaling down to an unreadable size.

View it now! (requirements for viewing this sample)
This sample lets you view the same RealText clip displayed in four smaller SMIL regions that have different fit attributes.

Setting the Clip Duration

The duration attribute specifies how long the RealText clip plays. The default is 60 seconds. RealText uses only the "normal play time" timing values of hh:mm:ss.xy, which are described in "Using the Normal Play Time Format". In this timing method, only the ss field is required. For example, the following duration attributes make the clip last 90 seconds: 

<window duration="90" ...>

5 and 1/2 minutes: 

<window duration="5:30" ...>

and 1 hour, 33 minutes, and 15 seconds: 

<window duration="1:33:15" ...>

RealText Durations and SMIL Durations

When you put RealText in a SMIL presentation, SMIL timing values can override the duration defined in the RealText clip. Suppose a RealText clip named marquee.rt has a duration of three minutes: 

<window duration="3:00.0" ...>

If you put this clip into a SMIL presentation with the following SMIL clip source tag, the dur="2min"attribute tells RealPlayer to stop playing this clip after two minutes regardless of the clip's internal timeline: 

<textstream src="rtsp://helixserver.example.com/marquee.rt dur="2min" .../>

If the SMIL duration is longer than the RealText duration, a fill attribute can specify how RealPlayer treats the clip once it has stopped playing: 

<textstream src="rtsp://helixserver.example.com/marquee.rt dur="4min" fill="freeze"/>

For More Information: For more on the SMIL fill attribute, see "Setting a Fill".

Tips for Setting RealText Clip Durations

Adding a Version Number

The <window> tag can include a version number, as shown in this example: 

<window version="1.5"...>

You typically do not have to specify a version number when using RealText in English. Properly displaying languages other than English may require that you specify a version number explicitly in the <window> tag, however. This chapter tells you when a version number is required to use a specific feature. The following paragraphs summarize the features that require you to add version numbers:

Specifying Hyperlink Appearance

The underline_hyperlinks="false|true" attribute determines whether hyperlinks are underlined. The default is true. The link="color" attribute, which defaults to blue, sets the color of hyperlinks within the text. Here is an example: 

<window underline_hyperlinks="false" link="red" ...>

For More Information: See "Specifying RealText Color Values" for color options.

Controlling Text Flow

As described in the following sections, several <window> tag attributes (scrollrate, crawlrate, wordwrap, loop, and extraspaces) affect how text displays in the RealText clip.

Setting a Scroll Rate or a Crawl Rate

The scrollrate attribute sets the number of pixels per second that the text scrolls from the bottom of the window to the top for the duration of the clip. It has no effect on tickertape and marquee windows. Here is an example: 

<window scrollrate="25" ...>

The crawlrate attribute specifies the number of pixels per second that the text moves horizontally from right to left for the duration of the clip. Here is an example: 

<window crawlrate="40" ...>

Tip: A RealText clip should not use both scrollrate and crawlrate. For best results, use a scrollrate or a crawlrate under 30. The best values are 25, 20, 10, 8, 5, 4, 2, and 1. For rates faster than 30, use multiples of 20 or 25, such as 40, 50, 60, 75, 80, and so on.

For More Information: The table "Default Values for RealText Window Types" lists the default values for scrollrate and crawlrate in the standard window types.

Wrapping Text to New Lines

The wordwrap="false|true" attribute, which defaults to true, specifies whether word wrap is performed. When word wrap is on, text lines longer than the specified window width wrap to the following line. If it is off, long lines are truncated by the window border. This attribute has no effect for windows that have horizontal text motion, such as a marquee window.

Looping Text

The loop="false|true" attribute is available only in tickertape and marquee windows, which have horizontal "crawling" motion. In these window types, the loop attribute defaults to true, which tells RealPlayer to redisplay ("loop") text under these circumstances:

Ignoring Extra Spaces

When set to its default value of use, the extraspaces="use|ignore" attribute makes RealText recognize all blank spaces between text chunks and markup tags. If three spaces occur between two words in the RealText file, for example, RealPlayer displays all three spaces. It treats each carriage return and tab as a space.

If you specify extraspaces="ignore", RealPlayer treats spaces, tabs, line feeds, and carriage returns as does a Web browser, except when they are between the <pre>...</pre> tags. When spaces or carriage returns occur contiguously in the text, RealPlayer interprets them as a single space, no matter how many of them are present. So in this case, three contiguous spaces display as one space in RealPlayer.

For More Information: The <pre>...</pre> tags are described in the section "Preformatting Text"

Timing and Positioning Text

The following sections explain the RealText tags you can use between the <window> and </window> tags to control when and where text appears within the RealText window. The following table summarizes the RealText timing and positioning tags.

RealText Time and Position Tags
Tag Attributes Function Reference
<clear/> (none) Clears all text. click here
<pos/> x="pixels"|y="pixels" Positions text. click here
<required>...
</required>		 (none) Ensures that text is delivered. click here
<time/> begin="hh:mm:ss.xy"|
end="hh:mm:ss.xy"		 Sets time when text appears or disappears. click here
<tl>...</tl> color="name|#RRGGBB" Puts text at bottom of ticker. click here
<tu>...</tu> color="name|#RRGGBB" Places text at top of ticker. click here

Controlling When Text Appears and Disappears

The <time/> tag controls the RealText presentation timeline by specifying when text blocks appear or disappear. The <time/> tag is useful primarily in RealText clips in which text does not scroll or crawl across the screen. In these clips, RealPlayer displays all text as quickly as it can if you do not time the text with <time/> tag.

The <time/> tag can have two attributes, begin and end. You can use one or both attributes in each <time/> tag. Each attribute specifies a time when the text appears or disappears, respectively. As with the <window> tag's duration attribute, a <time/> tag specifies a time in the "normal play time" format: 

<time begin="hh:mm:ss.xy"/>
<time end="hh:mm:ss.xy"/>

In the following sample text block, the first phrase appears at the start of the RealText presentation. The subsequent text blocks appear at three seconds into the timeline, and six seconds into the timeline, respectively: 

Mary had a little lamb, <time begin="3"/>little lamb, <time begin="6"/>little lamb.

For More Information: See "Using the Normal Play Time Format" for more on <begin> tag timing values.

Using an End Time

Text with an end time is erased when the specified end value is reached. Otherwise it stays active until the presentation ends or the entire window is erased with <clear/>. In the following example, text blocks begin at different times, but all end at the same time. Note that just as with a begin time, an end time must appear before the text block in the file: 

<time end="25"/><time begin="5"/>This text starts to display at 5 seconds.
<time begin="10"/>A new line appears each additional 5 seconds.
<time begin="15"/>But all this text disappears ...
<time begin="20"/>at 25 seconds into the clip.

You can also combine the begin and end attributes in a single <time/> tag as shown here: 

<time begin="23" end="55.5"/>This text displays 23 seconds into the presentation and disappears at 55.5 seconds.

It's important to note that text following a <time/> tag has the specified begin or end value until a new value is given. Therefore, once you specify an end time for a text block, you must specify an end time for all following blocks. For example, the following text would not display properly: 

<time begin="23" end="55.5"/>Display at 23 seconds in.
<time begin="56"/>Display at 56 seconds in.

Because the second line in the preceding example does not include an end time, the previous end time of 55.5 still applies. The second line cannot be displayed, however, because its begin time is later than its end time.

Tips for Using <time/> Tags

Clearing Text from the Window

The <clear/> tag removes all text from the window. The text that follows this tag then displays at the window's normal starting point, which is typically the window's top or right edge, unless you position the text elsewhere. You can add <clear/> after <time begin="..."/> to erase text before displaying new text. This is often an easier method of removing text than using <time end="..."/> tags. In the following example, each new line erases the preceding line: 

<time begin="5"/>This line displays at 5 seconds.
<time begin="10"/><clear/>This line erases the previous line at 10 seconds.
<time begin="15"/><clear/>This line erases the previous line at 15 seconds.
<time begin="20"/><clear/>This line erases the previous line at 20 seconds.

A <clear/> tag removes all preceding text, even text that has an end time that has not yet elapsed. In the following example, the second line of text is set to end at 20 seconds. However, the <clear/> tag appears at 15 seconds into the presentation and clears this line, eliminating the end time for all following text: 

<time begin="5"/>They all lived happily.
<time begin="10" time end="20"/>And so our story ends.
<time begin="15"/><clear/>Goodbye!

Note: The <clear/> tag does not reset text appearance. For example, if text appears bolded before the <clear/> tag, it remains bolded after the <clear/> tag.

Positioning Text in a Window

These <pos/> tag can position text anywhere in the RealText window. You can use its x attribute for horizontal positioning, and its y attribute for vertical positioning. Each attribute takes a value in pixels, as shown in these examples: 

<pos x="10"/>
<pos y="25"/>

A <pos y="pixels"/> tag moves the upper, left corner of the subsequent text block the specified number of pixels down from the window's top edge. A <pos x="pixels"/> tag indents the text block the specified number of pixels in addition to the two-pixel default padding that applies to all text blocks. You can combine both tags in a single tag like this: 

<pos x="10" y="25"/>

Note: These tags work only if scrollrate and crawlrate are both 0 (zero). For more on these attributes, see "Setting a Scroll Rate or a Crawl Rate".

Aligning Text in a Tickertape Window

Th <tu>...</tu> and <tl>...</tl> tag sets function only with tickertape windows. They display the enclosed text at the window's upper (<tu>...</tu>) or lower (<tu>...</tu>) edge. Optionally, they can include a color attribute that specifies the color for the text, as shown in this example: 

<tu color="blue">...text to display at tickertape window's upper edge...</tu>
<tl color="yellow">...text to display at tickertape window's lower edge...</tl>

When a tag specifies a color with the color attribute, the color applies to text enclosed by all subsequent tags of that type until another tag of that type changes the color. However, color specified for <tu> elements does not affect color for <tl> elements, and vice versa. The default color for <tu> elements is white, the default for <tl> elements is green.

For More Information: Refer to "Specifying RealText Color Values" for information about choosing colors.

Ensuring Text Delivery

Use the <required> and </required> tags to enclose text that must be delivered to RealPlayer under any circumstance. During extremely adverse network conditions, Helix Server will halt the presentation if necessary rather than drop the text. You can use these tags sparingly, though, because Helix Server normally ensures that very little data loss occurs in transmission.

Note: Although Helix Server provides reliable streaming, packets not marked as required may be lost occasionally. If a block of text does not get through, RealPlayer displays a red ellipsis (...) to indicate missing text.

Specifying Languages, Fonts, and Text Colors

The RealText <font> tag controls the text font and color. Because it also specifies the character set, it determines which languages you can write in. As shown in the following example, the <font> tag can take multiple attributes, and it always uses an end tag: 

<font size="+2" face="Courier New" color="red">...text...</font>

Multiple <font> tags can also be nested to turn various font features on and off: 

<font attribute="A">...turn on font attribute "A"...
<font attribute="B">...turn on font attribute "B"...
</font>...turn off font attribute "B"...
</font >...turn off font attribute "A"...

The following table summarizes the RealText <font> tag attributes.

RealText <font> Tag Attributes
Attribute Value Function Reference
bgcolor name|#RRGGBB Sets a background color. click here
charset us-ascii|iso-8859-1|
mac-roman|x-sjis|
gb2312|big5|iso-2022-kr		 Specifies character set used to display text. click here
color name|#RRGGBB Controls font color. click here
face (see font tables) Sets the text face. click here
size -2|-1|+0|+1|+2|+3|+4
or
1|2|3|4|5|6|7		 Sets the font size. click here

Specifying the Character Set

With the <font> tag's charset attribute, you can control the character set used to display the text. You do not need to specify the character set explicitly to write text in English. However, you may need to specify the character set to write text in other supported languages. You can set the character set as well as the font face immediately after the <window> tag within a RealText file, as shown in the following example: 

<window version="1.4"...>
<font charset="iso-2022-kr" face="Batang">
...Korean text that uses the iso-2022-kr character set and Batang font...
</font>
</window>

You can also use multiple <font> tags to change character sets within a RealText file and display text in different languages: 

<font charset="iso-2022-kr" face="Batang">
...Korean text that uses the iso-2022-kr character set and Batang font...
</font>
<font charset="x-sjis" face="Osaka">
...Kanji text that uses the x-sjis character set and Osaka font...
</font>

It is important to note that RealText always uses its specified character set, not the default character set of the computer playing the clip. In RealText version 1.2 and higher, the default character set is iso-8859-1. To display Korean text on a machine that uses the iso-2022-kr character set by default, for instance, you must explicitly set charset="iso-2022-kr" in the RealText <window> tag. If you do not, RealText will use its default iso-8859-1 character set, even though iso-2022-kr is the machine's default.

Note: If the computer does not recognize the character set specified in the RealText clip, it displays the text in its default character set. The result is typically unreadable.

For More Information: As noted in the following sections, using some character sets requires you to include a version number in the <window> tag. For more on version numbers, see "Adding a Version Number".

us-ascii

The us-ascii character set is the default character set used with most RealText fonts when no version number is specified in the <window> tag.

iso-8859-1

The iso-8859-1 character set is identical to us-ascii, but includes support for accented characters (upper 128 characters) used in many European languages. This is the default character set used when you specify version="1.2" or higher in the <window> tag. Use it when writing accented European languages on a Windows or Unix computer. You can represent the following languages with the iso-8859-1 character set:

Afrikaans Basque Catalan Danish Dutch English
Faeroese Finnish French Galician German Icelandic
Irish Italian Norwegian Portuguese Spanish Swedish

Note: The ISO-8859 standard specifies several additional character sets, such as iso-8859-2 and iso-8859-3. RealText supports only iso-8859-1, however, meaning that Cyrillic, Arabic, Greek, Hebrew, and several Eastern European languages are not supported in RealText.

mac-roman

Use the mac-roman character set when writing in an accented European language on a Macintosh computer. Using this character set ensures that marks such as umlauts (for example, "ü") display properly when the RealText clip plays on a Windows or Unix computer. Use version="1.2" or higher in the <window> tag to handle this character set correctly.

Note: You do not need to use the mac-roman character set when writing in English. When writing in accented languages on a Windows or Unix machine, use the iso-8859-1 character set instead.

x-sjis

The x-sjis character set is for Kanji and the Osaka font. Use version="1.2" or higher in the <window> tag to handle this character set correctly.

gb2312

The gb2312 character set is for Simplified Chinese.

big5

The big5 character set is for Traditional Chinese.

iso-2022-kr

The iso-2022-kr character set is for Korean. Use version="1.4" or higher in the <window> tag to handle Korean text correctly.

Setting the Font

This <font> tag attribute face="font name" controls the font use. You can use any number of fonts in the same RealText clip. When switching fonts, be sure to turn off the preceding font with a </font> tag, as shown in this example: 

<font face="Arial">
...Text in the Arial font...
</font>
<font face="Garamond">
...Text in the Garamond font...
</font>

Font faces correspond to character sets as described in the section "Specifying the Character Set". For non-Western fonts, you must specify the correct character set for the font to display properly. If you specify no font, RealText uses the Times New Roman or Times font regardless of the character set specified.

English and European Language Fonts

When writing in English or European languages, use a font name from the "Windows Font Name" column of the following table, which lists fonts that use the us-ascii or iso-8859-1 character set. You can also view how these fonts appear. If the specified font isn't available on a Macintosh or Unix computer, RealText uses a system font as indicated in the table below. For example, RealPlayer on a Macintosh displays text in Courier if the Algerian font is not available. The notation "(always)" indicates cases where RealText always defaults to a system font. For example, the Fixedsys font always displays as Courier on a Macintosh.

RealText Font Support for us-ascii and iso-8859-1 Character Sets
Windows Font Name Macintosh Default
if Font not Available		 Unix Default
if Font not Available
Algerian Courier Courier
Arial Helvetica Helvetica
Arial Black Helvetica Helvetica
Arial Narrow Helvetica Helvetica
Arial Rounded Mt Bold Helvetica Helvetica
Book Antiqua Helvetica Helvetica
Bookman Old Style Helvetica Helvetica
Braggadocio Helvetica Helvetica
Britannic Bold Helvetica Helvetica
Brush Script Times Times
Century Gothic Helvetica Helvetica
Century Schoolbook Helvetica Helvetica
Colonna Mt Times Times
Comic Sans Ms Times Times
Courier New Courier Courier
Desdemona Helvetica Helvetica
Fixedsys Courier (always) Courier
Footlight Mt Light Helvetica Helvetica
Garamond Times Times
Haettenschweiler Helvetica Helvetica
Helvetica (Arial is used if Helvetica is not found.) Helvetica Helvetica
Impact Helvetica Helvetica
Kino Mt Times Times
Matura Mt Script Capitals Times Times
Modern Helvetica Helvetica
Ms Dialog Times Times
Ms Dialog Light Times Times
Ms Linedraw Helvetica Helvetica
Ms Sans Serif Helvetica Helvetica
Ms Serif Helvetica Helvetica
Ms Systemex Times Times
Playbill Times Times
Small Fonts Times Times
System Geneva (always) Times
Terminal Geneva Times
Times New Roman Times (always) Times
Verdana Helvetica Helvetica
Wide Latin Helvetica Helvetica

Tip: A Macintosh that has Microsoft Internet Explorer 4.0 or later installed should have most of the Windows fonts.

Asian Language Fonts

RealText also supports the following fonts that use character sets other than us-ascii and iso-8859-1.

RealText Font Support for Non-Western Character Sets
Font Name Characters RealText Font Face Tag charset
AppleGothic Korean <font face="AppleGothic"> iso-2022-kr
Batang Korean <font face="Batang"> iso-2022-kr
BatangChe Korean <font face="BatangChe"> iso-2022-kr
Gothic Korean <font face="Gothic"> iso-2022-kr
Gulim Korean <font face="Gulim"> iso-2022-kr
GulimChe Korean <font face="GulimChe"> iso-2022-kr
Osaka Kanji <font face="Osaka"> x-sjis
Seoul Korean <font face="Seoul"> iso-2022-kr
Simplified Chinese <font face="'ËÎÌå">
(The face name displays as gibberish without the gb2312 character set.)		 gb2312
Traditional Chinese <font face="²Ó©úÅé">
(The face name displays as gibberish without the big5 character set.)		 big5

Note: Korean and Japanese are supported in RealPlayer for Windows and Macintosh, but not for Unix.

Setting the Text Size

The <font> tag attribute size="n" lets you control the font size, as shown in this example: 

<font size="+1">...text that is one size larger...</font>

You can use relative sizes or absolute sizes as shown in the table below. This table also lists the height in pixels for each size. The pixel sizes are for reference only. You cannot specify a pixel size directly in RealText.

RealText Font Sizes
Relative Size Absolute Size Pixel Size Reference
-2 1 12 pixels
-1 2 14 pixels
+0 (default) 3 16 pixels
+1 4 20 pixels
+2 5 24 pixels
+3 6 36 pixels
+4 7 48 pixels

Note: You can also specify relative sizes smaller than -2 or larger than +4, but they are treated as -2 and +4, respectively.

Controlling Text Colors

Two attributes of the <font> tag, color and bgcolor, let you set the color for the text letters, and the background against which the text appears. The section "Setting the Window Size and Color" explains how to set the RealText window's background color.

Setting Text Letter Colors

The color attribute of the <font> tag lets you control the text color. It has no effect on tickertape windows because the <tu> and <tl> tags, which are described in "Aligning Text in a Tickertape Window", set the tickertape text colors. The following example shows the text color set to red: 

<font color="red">...red text...</font>

Creating Text Background Colors

Use the bgcolor attribute to the <font> tag to set the text background color. The default background color for text is "transparent", making the text background the same color as the window. The following example sets the text background to yellow: 

<font bgcolor="yellow">...text with yellow background...</font>

Note that the text background color is independent of the window background color. If the window background color is blue, for example, and the text background color is yellow, a stripe of yellow appears in front of the blue window wherever the affected text displays. Within that yellow stripe, the text appears in the color set by the color attribute.

Specifying RealText Color Values

For RealText window backgrounds and fonts, you can use red/green/blue hexadecimal values (#RRGGBB), as well as the following color names, listed here with their corresponding hexadecimal values:

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

Tip: Appendix C provides background on hexadecimal color values. Note, though, that RealText does not support RGB color values used with SMIL.

Using Transparency as a Color

For text backgrounds, you can use bgcolor="transparent". This is the default for text backgrounds, meaning that the words following the tag do not have a colored rectangle drawn behind them, so the window background color shows around the letters. This lets you draw text over previous text (using the <pos/> tags) without "erasing" the previous text.

Controlling Text Layout and Appearance

The following tags let you lay out text in the RealText clip. Many of these tags are similar to HTML tags, and are provided for compatibility. However, unlike in HTML, RealText tags are case sensitive and a closing tag is always required. You cannot use a <p> tag without a </p> tag, for example, or use capital letters as in <P> and </P>. The following table summarizes the RealText layout and appearance tags.

RealText Layout and Apperance Tags
Tag Function Reference
<b>...</b> Bolds the enclosed text. click here
<br/> Creates a line break. click here
<center>...</center> Centers the enclosed text. click here
<hr/> Acts like two <br/> tags. click here
<i>...</i> Italicizes the enclosed text. click here
<li>...</li> Acts like a <br/> tag. click here
<ol>...</ol> Indents text, but does not number it. click here
<p>...</p> Creates a text paragraph. click here
<pre>...</pre> Displays text in a monospace font and preserves extra spaces. Works the same as in HTML. click here
<s>...</s> Strikes through the enclosed text. click here
<u>...</u> Underlines the enclosed text. click here
<ul>...</ul> Indents text, but does not add bullets to it. click here

Adding Space Between Text Blocks

The following tags add space between text blocks. If text flows across the screen horizontally, however, line breaks are not created.

<p>...</p>

The <p>...</p> tags turn the enclosed text into a pargraph. In tickertape and marquee windows, it causes the text that follows it to display at the window's right edge. In all other window types, the <p> and </p> each cause the next text block to display two lines down.

<br/>

The <br/> tag adds space between text. In tickertape and marquee windows, it causes the text that follows it to display at the window's right edge. In all other window types, this tag causes the text that follows to display on the next line.

Centering Text

The <center>...</center> tags center the enclosed text. These tags behave the same as HTML centering tags, but they have no effect in windows with horizontal motion, such as tickertape and marquee windows. The <center> tag forces a line break if and only if a line break caused by a tag such as <br/>, <p>, or <hr/> does not immediately precede it. The </center> tag always causes a line break.

Note: RealText does not center text until it has determined the line length. In rare instances, one streamed packet may contain the first part of the line while another packet received several seconds later contains the end of the line. In this case, the first part displays flush left, and the entire line is centered and redisplayed when the second packet arrives.

Preformatting Text

The <pre>...</pre> tags work the same as in HTML. Text tagged with <pre> uses the Courier font at the current size. To change the font size, precede the preformatted block with a <font size="n"> tag. Line breaks, spaces, and tabs are preserved, with tabs defaulting to 64 pixels for 16 point text (the normal point size). Tab spaces are determined by dividing the text height by 2, then multiplying by 8.

For More Information: For information on text heights, see the table "RealText Font Sizes". See also "Ignoring Extra Spaces".

Using HTML-Compatible Tags

The following RealText tags are provided for HTML compatibility, allowing you to convert HTML to RealText more easily, and vice versa. These tags do not function the same in RealText as they do in HTML, however.

<ol>...</ol>

The <ol>...</ol> tags are for compatibility with HTML lists. Text between these tags is indented, but not numbered.

<ul>...</ul>

The <ul>...</ul> tags are for compatibility with HTML lists. Text between these tags is indented, but not bulleted.

<li>...</li>

The <li>...</li> tags are for compatibility with HTML lists. They act like a <br/> tag.

<hr/>

The <hr/> tag is for compatibility with HTML horizontal rules. It acts like two <br/> tags.

Emphasizing Text

The following RealText tags let you add emphasis to text.

<b>...</b>

The <b>...</b> tags display the enclosed text bolded.

<i>...</i>

The <i>...</i> tags display the enclosed text italicized.

<s>...</s>

The <s>...</a> tags strike through the enclosed text.

<u>...</u>

The <u>...</u> tags display the enclosed text underlined.

Creating Links and Issuing Commands

The following sections describe tags you can use to launch URLs through RealText. You can also use tags to issue RealPlayer commands such as Pause and Play. The following table summarizes link and command syntax.

RealText <a> Tag Attributes
Attribute Value Function Reference
href="command"
target="_player"		 command:seek(time)|
command:pause()|
command:play()		 Issues a command. click here
href="command:openwindow()" name|URL|
zoomlevel		 Opens new windows click here
href="mailto:address" email_address Opens e-mail message. click here
href="URL" target="_player" Links to URL. click here

Tip: Text in a link uses the color specified in the link attribute of the <window> tag. The link is underlined unless the <window> tag includes underline_hyperlinks="false".

For More Information: SMIL files can also define hypertext links that may override the link you set here. For more information, see Chapter 15.

View it now! (requirements for viewing this sample)
Display this scrolling RealText clip to view several hyperlinking possibilities.

Creating a Mail Link

This tag turns the enclosed text into an e-mail hyperlink: 

<a href="mailto:address">...</a>

When the viewer clicks the link, RealText opens the viewer's default mail application. Use an address in the standard form, such as name@company.com. In most cases, the e-mail application opens a new message with the defined address in the "to" line.

Opening Media or HTML Pages

The following RealText tag turns the text enclosed between <a href...> and </a> into a hyperlink that opens an HTML page or a media clip: 

<a href="URL" [target="_player"]>...</a>

The specified URL should begin with a protocol designation such as http:// or rtsp://. The optional target="_player" attribute launches the new stream in the media playback pane. If you do not use the target attribute, or you specify target="_browser", the linked URL opens in RealPlayer's media browser pane, or in the viewer's default Web browser with earlier versions of RealPlayer.

Example 1: Opening a Streaming Media URL

The following example launches a new SMIL Presentation in RealPlayer, replacing the currently playing presentation: 

<a href="rtsp://helixserver.example.com/video2.smil target="_player">Play Next</a>

You can also open a link in a new media window that pops up above the media playback pane. This lets you keep navigation information visible in the media playback pane, for example, while content plays in a new window. For more about this, see "Opening a Media Playback Window with a Clip Link".

Example 2: Opening an HTML Page

This example opens a URL in the media browser pane of RealPlayer, or in the viewer's default Web browser with earlier versions of RealPlayer: 

<a href="http://realguide.real.com">Visit RealGuide</a>

You can also specify URLs relative to the location of the RealText source file. For example, the link <a href="more.htm">...</a> opens the file more.htm in the same directory as the RealText file. Relative links follow the standard HTML directory syntax.

Note: With RealOne Player or later, you cannot target the related info pane or a secondary browsing window.

Example 3: Opening a URL in the Form protocol:path

If you include version="1.5" (or higher if using a newer version of RealText) in the <window> tag, you can open a URL in the form protocol:path instead of protocol://path. Protocols using this format include those for Telnet and AOL Instant Messenger. For example, here is a RealText link that launches AOL Instant Messenger: 

<window version="1.5"...>
...<a href="aim:goim?screenname=[name]">Send Me an Instant Message</a>...
</window>

Issuing RealPlayer Commands

The following tag makes the enclosed text a hyperlink that, when clicked, executes a RealPlayer command: 

<a href="command" target="_player">...</a>

The commands are case-sensitive and must be enclosed in double quotes. The target="_player" attribute is required.

Seeking Into a Presentation

The following command instructs RealPlayer to seek to the specified time in the current text stream: 

<a href="command:seek(time)" target="_player">Seek</a>

For example, the following instructs RealPlayer to seek to 1:35.4 in the stream: 

<a href="command:seek(1:35.4)" target="_player">Seek</a>

Pausing a Presentation

When clicked, the following link causes RealPlayer to pause the stream: 

<a href="command:pause()" target="_player">Pause</a>

Resuming Playback

Clicking the next link causes RealPlayer to begin or resume playing the stream: 

<a href="command:play()" target="_player">Resume</a>

Using Coded Characters

The following table lists the character codes you can include in a RealText source file. Codes begin with an ampersand ("&") and end with a semicolon (";"). RealText interprets these characters the same way as popular Web browsers.

RealText Coded Character Set
Code Displays as
&lt; <
&gt; >
&amp; &
&nbsp; (nonbreaking space)
&#32;
to
&#255; 		Characters taken from the active character set as specified by the active <font charset="..."> tag. The default character set is iso-8859-1, which is also known as ISO Latin 1. For a list of these characters, see the W3C reference at http://www.w3.org/MarkUp/html-spec/html-spec_13.html. Or click here to generate a list. See below, however, if you're using the mac-roman character set.

For example, the following RealText source text: 

This is a bold tag: "&lt;b&gt;".

is displayed in a RealText window as: 

This is a bold tag: "<b>".

Using Coded Characters with the mac-roman Character Set

Unlike HTML, RealText allows you to change character sets within a document. It then takes coded characters from the active character set. Generally, character codes 128 and lower are the same in all Western-language character sets. Those higher than 128 may differ, though. In the mac-roman character set, for example, &#166; is a paragraph symbol. But in iso-8859-1, this symbol is &#182;.

See http://czyborra.com/charsets/mac-roman.gif for a GIF chart of the mac-roman upper character set. Go by this chart, rather than the W3C reference or JavaScript list provided above if you've set <font charset="mac-roman"> and are entering coded characters of &#129; or higher. The values in the chart are in hexadecimal (base 16). The chart cell in the upper, left-hand corner equals 128 in decimal (base 10), so you can count across from there. To make a paragraph symbol when using mac-roman, for instance, you use &#166; in the RealText file because hexadecimal A6 on the chart is decimal 166.

RealText Examples

This following sections provide examples of how to create various types of RealText clips.

Generic Window

The following sample RealText markup creates a generic RealText window: 

<window duration="30" bgcolor="yellow"> 
<br/>Mary had a little lamb, 
<br/><time begin="3"/>little lamb, 
<br/><time begin="6"/>little lamb. 
<br/><time begin="9"/>Mary had a little lamb, 
<br/><time begin="12"/>whose fleece was white as snow. 
<br/><time begin="15"/><clear/><br/>Everywhere that Mary went, 
<br/><time begin="18"/>Mary went, 
<br/><time begin="21"/>Mary went, 
<br/><time begin="24"/>Everywhere that Mary went, 
<br/><time begin="27"/>That lamb was sure to go. 
</window>

When RealPlayer processes this file, it displays only the first line of the text from zero to three seconds into the stream:


Every three seconds after the first line displays, a new line appears as specified by <time begin="n"/>. At 15 seconds, <clear/> clears the displayed text and resets the text "cursor" to the upper-left corner of the window. When the stream finishes, all lines of text following the last <clear/> tag appear in the window:


View it now! (requirements for viewing this sample)
Display this sample of a generic window.

Note the following about this sample clip:

Tickertape Window

The following example shows the RealText markup for a tickertape window. This is the RealText (.rt) source file: 

<window type="tickertape" duration="1:00" width="500" loop="true" underline_hyperlinks="false" link="white"> 
<br/>
<b>
<tu><a href="http://www.dowjones.com/">DJIA</a></tu>
<tl>7168.35 +36.5 </tl>
<tu>NIKEI 225 Index</tu>
<tl>20603.71 +203.11</tl>
</b> 
</window>

This source file produces the following window in RealPlayer:

View it now! (requirements for viewing this sample)
Display this sample of a tickertape window.

Note the following about this sample clip: