Chapter 3: The Ram File

The Ram file is the basic means for launching a clip or a simple sequence of clips that plays in RealOne Player. You can also use the Ram file to open an HTML page in the media browser or related info pane. This chapter explains the Ram file syntax, covers the URLs to use with streaming clips, and shows you how to pass basic parameters to RealOne Player.

Launching Clips with a Ram File

When your presentation is ready to stream, you write a Ram file, which is so- named because it uses the file extension .ram, as in my_presentation.ram. Also known as a metafile, the Ram file links your Web page to your clip. Your Web page links to the Ram file with a standard <a href> tag, and your Ram file contains the full URL to your streaming presentation. So instead of linking directly to your clip, your Web page links to the Ram file, which, in turn, links to the clip.

Is a Ram File Necessary?

The Ram file may seem like an unnecessary middle step, but it's important for the following reasons:

1. The Ram file launches RealOne Player.

The file extension .ram causes a Web browser to launch RealOne Player to play the presentation. RealOne Player might not launch when you link directly to a clip. When you link your Web page directly to a Flash Player file (extension .swf), for example, the browser launches Macromedia's Flash Player. If you intend to stream your Flash clip, you need to use a Ram file to launch RealOne Player instead.

2. The Ram file provides an RTSP URL for clips on Helix Universal Server.

Clips on Helix Universal Server stream over the RTSP protocol, rather than HTTP. This means that the URL used to request the clips must start with rtsp:// rather than with http://. Because browsers cannot make RTSP requests, you link your Web page to a Ram file with an HTTP URL. The Ram file then gives RealOne Player the RTSP URL to your presentation.

3. The Ram file can pass parameters to RealOne Player.

Through these parameters, you can specify the HTML page or pages you want to display in RealOne Player's HTML panes as the clip plays.

The only time you shouldn't use a Ram file to launch RealOne Player is when you're using the Ramgen feature of Helix Universal Server, which lets you link your Web page directly to a streaming media clip. Even though your Web page link uses HTTP, the clip will stream to RealOne Player using RTSP. Ramgen doesn't offer all of the features of a Ram file, but it provides a simple way to link clips directly to your Web page.

For More Information: For more information about using Ramgen, see the presentation delivery chapter of RealNetworks Production Guide. Your Helix Universal Server Administration Guide explains how to set up Ramgen.

Writing a Ram File

The most basic Ram file has only one line: the full URL to a clip. You can write a Ram file with any text editor, word processor, or HTML editor that can save output as plain text. On Windows, you can use Notepad. On the Macintosh, Simple Text will work fine.

To write a Ram file:

1. Open a new, blank file in your text editor. On the top line, enter the full URL to your media clip or SMIL presentation. The following are some sample URLs depending on the type of server used to deliver the clip:

   Helix Universal Server:	rtsp://helixserver.example.com/my_video.rm
   Web server:	http://www.example.com/my_video.rm
   local:	file://my_video.rm

For More Information: For more about URLs, see "What URLs Do You Use?".

Tip: Don't use spaces in clip file names or the Ram file name. Although many servers can stream files that include spaces in their names, excluding spaces can help prevent problems during streaming.

2. If you want to stream a series of clips or SMIL presentations in sequence, simply list the URL to each clip on a separate line. Here's an example:

rtsp://helixserver.example.com/video1.rm rtsp://helixserver.example.com/video2.rm rtsp://helixserver.example.com/video3.rm

Warning! Press Enter only to create a new line on which you want to enter a new URL. Do not press Enter when typing in a long URL. It's OK if your text editor wraps the URL to a new line automatically, though. Only a line break you enter yourself will cause an error.

3. Save the Ram file as plain text with a .ram extension.

Windows text editors such as Notepad automatically apply the .txt extension to files. To avoid this, choose "All Files" as the file type in the File>Save As dialog. To edit your Ram file later, you must first open the text editor, then use the editor's Open command to open the Ram file because double-clicking the file launches RealOne Player

Tip: If your file is saved with a .txt extension, you can remove the extension or change it to .ram on your computer desktop.

What URLs Do You Use?

Although the Ram file is simple to write, it's often the source of the biggest problem people face with streaming: using an incorrect URL. There are two important things to keep in mind when writing a Ram file:

1. The protocol must match the server.

1. A Web server uses the HTTP protocol, so URLs to clips on it must start with:

http://

2. Helix Universal Server uses the RTSP protocol, so URLs to clips on it must start with:

rtsp://

3. To test the clip on your computer first, place the Ram file in the same directory as the clip. In the Ram file, use just the clip name preceded by the local URL indicator:

file://

2. The URL must indicate the correct path to the clip. If you are not running the Web server or Helix Universal Server yourself, you'll need to get the path to the clip from the server administrator. Keep in mind that the path in the URL typically does not reflect the actual operating system path on the server machine.

Why Does Helix Universal Server Use RTSP?

To deliver HTML pages and graphics, a Web server uses Hyper Text Transport Protocol (HTTP), which downloads files without regard to timelines, making clips with timelines more likely to stall. Although Helix Universal Server can also use HTTP, it generally uses Real-Time Streaming Protocol (RTSP) to deliver streaming clips. RTSP is an Internet standard set forth by the Internet Engineering Task Force (http://www.ietf.org/).

Designed for streaming, RTSP enables Helix Universal Server to keep clips playing smoothly. As a clip streams, RealOne Player communicates with Helix Universal Server about the clip's progress, indicating how much data it needs to keep playback flowing smoothly. Helix Universal Server can then adjust the data flow to compensate for changing network conditions, reducing low priority data if necessary to ensure that crucial data gets through. Communication like this is not possible through HTTP.

Putting Comments In a Ram File

You can place a comment to a Ram file by using a pound sign (#) as the first character on a line. The following example shows a Ram file with two comment lines:

# Three videos that play in sequence.
# Total playing time is 10 minutes, 40 seconds.
rtsp://helixserver.example.com/video1.rm
rtsp://helixserver.example.com/video2.rm
rtsp://helixserver.example.com/video3.rm

Adding Parameters to Your Ram File

A Ram file provides a simple and convenient way to set parameters that open HTML pages in the RealOne Player related info and media browser panes. Ram file parameters can also affect the media by shortening a clip's playback time, for instance. In the Ram file, separate the first parameter from the clip URL with a question mark (?), as shown here:

URL?parameter=value

To set two or more parameters for the same clip, precede the second and all subsequent parameters with ampersands (&) instead of question marks:

URL?parameter=value&parameter=value&parameter=value...

Note the following about Ram file parameters:

• Parameter values that contain spaces need to be enclosed in double quotation marks. Single values do not require quotation marks, though.
• Do not press Enter to create a line break when adding parameters to a clip URL. The presentation URL and all parameters must be on a single line. You can turn your text editor's word wrap feature on, though, so that the line wraps automatically.
• Previous versions of RealPlayer that do not support a specific parameter will ignore the parameter and still play the media.

Tip: Appendix D summarizes the Ram file parameters that the following sections describe in detail.

Opening an HTML Page as a Clip Plays

For each clip in the Ram file, you can provide the URL to one HTML page that opens in the RealOne Player related info pane. You can also provide a URL to an HTML page that opens in the media browser pane. The following table lists the Ram file HTML page parameters.

Tip: To open more than one HTML page for a clip in the related info pane or media browser pane at any point during the presentation, you can write a SMIL file as described in Chapter 6.

Background Color Values

For rpvideofillcolor, you can use one of 16 predefined color names, an RGB value, or a six-digit hexadecimal value. Illustration programs typically define colors using the RGB scheme, while the hexadecimal scheme is common to HTML markup programs. The following table lists the predefined names, along with that color's corresponding hexadecimal and RGB values.

With a hexadecimal color value, substitute the escape character %23 for the pound sign (#), which, in a Ram file, signifies the start of a comment. For example, suppose that you want to match the following hexadecimal color used in a related info HTML page:

<BODY BGCOLOR="#FF5A4E">

You would add the following to your Ram file:

rpvideofillcolor=%23FF5A4E

Examples of Opening HTML Pages

Opening a Page in the Related Info Pane

The following example plays a clip and opens an HTML page in a related info pane that is 250 pixels high and 280 pixels wide:

rtsp://helixserver.example.com/video1.rm?rpcontextheight=250
&rpcontextwidth=280&rpcontexturl="http://www.example.com/relatedinfo1.html"

Opening a Page in the Media Browser Pane

The next example opens an HTML page in the media browser pane when the clip begins to play:

rtsp://helixserver.example.com/video2.rm?rpurl="http://www.example.com/index.html"

Keeping the Same Context Pane, But Changing Background Colors

The following sample Ram file plays two clips in sequence. After the first clip plays for 5.5 seconds, the Ram parameters open an HTML page in a related info pane that is 350 pixels high by 300 pixels wide. The media playback pane's background color is set to rgb(30,60,200). When the second clip plays, the same related info pane is kept onscreen, but the media playback pane's background changes to red:

# First URL that opens a related info pane.
rtsp://helixserver.example.com/video3.rm?rpcontextheight=350
&rpcontextwidth=300&rpcontexturl="http://www.example.com/relatedinfo2.html"
&rpcontexttime=5.5&rpvideofillcolor=rgb(30,60,200)
#
# Second URL that keeps the same related info pane, 
# but changes the media playback pane's background color.
rtsp://helixserver.example.com/video4.rm?rpcontexturl=_keep
&rpvideofillcolor=red

Controlling How a Presentation Initially Displays

In the Ram file, you can set several parameters that control how RealOne Player initially displays a clip or SMIL presentation. You can play a clip at double its normal size, for example, play part of a clip, or open the RealOne Player at full-screen size. To control these characteristics, add one or more of the following parameters to the Ram file URL.

View it now! (requirements for viewing this sample) The first sample plays a clip at normal size, then at double-size. The second sample plays a clip in full-screen mode. The third sample uses start and end to play a portion of a clip. You can also open clips in theater mode or, for subscribers to premium services, toolbarmode.

Examples of Setting a Clip's Initial Display

Opening a Clip in Full-Screen Mode

The following example opens a SMIL presentation in full-screen mode:

rtsp://helixserver.example.com/sample1.smil?screensize=full

Opening a Clip at Normal Size in Theater Mode

The next example opens a video clip at double its normal size, and sets RealOne Player to its theater mode:

rtsp://helixserver.example.com/video1.rm?screensize=double&mode=theater

Playing a Clip Excerpt

The final example plays a 30-second excerpt from the middle of a clip:

rtsp://helixserver.example.com/audio1.rm?start=55&end=1:25

Tips for Setting the Initial Display

• HTML panes do not display when the media plays at full-screen size. Therefore, you should not open an HTML page when also using screensize=full.
• You do not need to specify a mode parameter when using screensize=full.
• RealOne Player may not offer full-screen mode on all operating systems. If RealOne Player for a given operating system does not offer full-screen mode, it plays the presentation at its normal size.
• If RealOne Player offers full-screen mode but has not yet played a clip full-screen, it may first perform a test of this playback mode.
• The double-size and full-screen modes work best for high-speed clips. They are not recommended for presentations delivered through modems.
• Always test playback when using double and full-screen modes to ensure that the visual quality is acceptable. Some types of clips may not scale well.
• In full-screen mode, the viewer can control RealOne Player through a contextual menu displayed by right-clicking (on Windows) or holding down the mouse button (on Macintosh).
• RealOne Player displays a presentation's elapsed time in one-second increments. You can click the time-elapsed field to display time values to 1/10th of a second, however. This can help you decide what start and end timing values you want to use in a Ram file.
• For a SMIL presentation, use clipBegin and clipEnd in the clip source tag, rather than start and end in the Ram file, to play an excerpt from a clip. For more information, see "Using Internal Clip Begin and End Times".
• The showvideocontrolsoverlay parameter is intended primarily for media presentations that include interactive elements, such as Flash clips or SMIL presentations. It allows you to hide the overlay so that it does not interfere with buttons or controls that are part of the media.

Overriding Title, Author, and Copyright Information

A streaming clip often encodes title, author, and copyright information. When you encode a RealAudio or RealVideo clip, for example, you can add this information to the clip through Helix Producer. Through the Ram file, you can override this title, author, and copyright information. These parameters are compatible with earlier versions of RealPlayer.

View it now! (requirements for viewing this sample) This sample uses title, author, and copyright parameters in a Ram file to override information encoded in a clip. You can view the information supplied by the Ram file by pressing Ctrl+i.

Example of Setting Title, Author, and Copyright Information

The following example sets title, author, and copyright information for a video clip:

rtsp://helixserver.example.com/introvid.rm?title="Introduction to Streaming 
Production"&author="RealNetworks, Inc."&copyright="©2001, 
RealNetworks, Inc."

Tips for Using Title, Author, and Copyright Parameters

• Whether information is encoded in the clip, or added through a Ram file, it appears in the following areas of RealOne Player:

• Title, author, and copyright information displays when the viewer chooses the File>Clip Properties>View Clip Info command, or presses Ctrl+i.
• Title, author, and copyright information crawls horizontally along the title bar at the top of RealOne Player, unless the SMIL file also uses presentation information as described in "Presentation Information". In this case, only the presentation information appears in the title bar.
• Title and author information appears in the "Now Playing" list, which is part of the RealOne Player media browser pane. Viewers can double-click a clip listing to play that clip. See "Now Playing List" for more information.
• Title information appears in the recent clips list under the RealOne Player File menu, unless the SMIL file also includes a presentation title. In this case, only the presentation title appears in the list.

• You can use any combination of title, author, and copyright parameters in a Ram file, but RealNetworks highly recommends that you always include title parameters for clips that have no encoded titles. If no title is available, a clip's file name displays in place of the title.
• There are similar attributes that you can set within a SMIL file instead of the Ram file. See "Adding Clip or Group Information" for more information.

Setting Clip Information

The clipinfo parameter is new with RealOne Player, and is ignored by earlier RealPlayers. Geared for online music, it allows you to encode information such as the artist name, album, genre, and so on, which displays when the viewer chooses the File>Clip Properties>View Clip Info command, or presses Ctrl+i. The clipinfo parameter uses one long value surrounded by double quotation marks. Within the quotes, you separate the subvalues with vertical lines, or "pipes," as shown here:

clipinfo="name=value|name=value|name=value..."

The following table describes the name and value pairs that you can use with clipinfo. You can use any set of values, and list them in any order. Most text values can be over 100 characters long.

Note: Do not use the title, author, and copyright parameters described in "Overriding Title, Author, and Copyright Information" along with clipinfo.

View it now! (requirements for viewing this sample) This sample demonstrates how the clipinfo parameter in a Ram file can set clip information, which you can view by pressing Ctrl+i.

Using Text Escape Characters

To use certain text characters in a value for the clipinfo parameter, you must use the character's corresponding escape code. This is because certain characters represent syntax components. A pipe (|) represents the start of a new value, for example, so to use a pipe within a value, you must use the escape code %7C. The following table lists some common text characters that you can add through escape codes.

You can enter other common text characters, such as commas, periods, and colons directly into clipinfo parameter. 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.

Example of Setting Clip Information

This example sets the clipinfo parameter for an audio clip:

rtsp://helixserver.example.com/song1.rm?clipinfo="title=Artist of the Year|
artist name=Your Name Here|album name=My Debut|genre=Rock|
copyright=2001|year=2001|comments=This one really knows how to rock!"

The following figure illustrates how this information appears in the clip information panel (Ctrl+i).

Clip Information

Moving Files to a Server

When your media clips, Web pages, and Ram file are ready for delivery, transfer them to your Web server and Helix Universal Server, placing them in the directories prepared by the server administrators. If a server is on the same local area network (LAN) as your computer, you can often just copy the files to the server over the network. Otherwise, you can usually transfer files to a server over the Internet using FTP (file transfer protocol).

Using FTP to Transfer Clips

The FTP protocol is designed to copy files from one computer to another. Many computers have an FTP application preinstalled. FTP applications are also available for download from many Internet software archives. Your Helix Universal Server or Web server administrator will have to set up FTP access to the server machine for you, as well as give you an FTP user name and password.

FTP distinguishes between a "text" mode for transferring text-only files, and a "binary" mode for transferring non-text files such as streaming media clips. Some FTP programs can set this mode automatically. With other programs, though, you must set the transfer mode yourself. If you transfer streaming clips in text mode, the clip may become corrupt. Fortunately, FTP never modifies the original clips on your computer, so you can simply transfer the clips again using the binary mode.

Tip: Helix Producer and RealSlideshow can transfer files to a server automatically. Refer to their user manuals or online help for more information.

Where Does the Ram File Go?

Move your Ram file to Helix Universal Server or your Web server. Even if all of your media clips are on Helix Universal Server, you can place the Ram file on your Web server or any other server. Your Web page, Ram file, and media clips do not have to reside together. If you keep the Ram file in the same directory as your main Web page, you can use a relative link like the following:

<a href="play_video1.ram">Play the video!</a>

If the Ram file is in a different location, use a full HTTP URL in the link to the Ram file:

<a href="http://www.example.com/play_video1.ram">Play the video!</a>

Then, make sure that the Ram file gives RealOne Player either the full RTSP URL to the clip on Helix Universal Server:

rtsp://helixserver.example.com/video1.rm

or the full HTTP URL to the clip on a Web server:

http://www.example.com/video1.rm

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