Metafiles

RealMedia material is reached via links, just as HTML documents use hyperlinks to connect Web pages. However, the RealMedia links you put into your HTML pages are not direct references to the RealAudio or RealVideo files. Instead they are references to text files which contain information needed to establish a connection between your RealServer and the user's RealPlayer and to initiate playback. These files are called metafiles.

Metafiles contain the URL of the file (or files) you want associated with the hyperlink. The visitor's browser passes the URLs to RealPlayer, which retrieves .ra or .rm files from your RealServer.

Metafiles contain the addresses of RealAudio (.ra), RealVideo (.rm) and RealFlash (.swf) files. These addresses are in the form of URLs. The URLs used to establish a direct connection between a RealPlayer and your RealServer begin with "pnm://" (RealNetworks Metafile). Once in place, this direct connection is used to stream to the Player and to carry commands (such as seek or pause) back to your RealServer.

With certain browsers, when a Web page points to a local .ram file that in turn points to a local clip, the Player displays the following error message: "The requested URL is not valid." Some versions of some browsers require that ram files include an absolute path when pointing to local files.


Creating Metafiles

Your Web pages will link to metafiles, which in turn give the DNS names or IP addresses of your RealAudio, RealVideo, and RealFlash files.

If you are using RealFlash Animation, you'll include that information in the metafiles.

To create a metafile:

  1. Use a text editor (such as Notepad) to create a file containing the RealAudio or RealVideo URL(s). The contents of your file should be in the following form:
    pnm://hostname/path/filename
    where hostname is the name of your Web server, path is the path to the file (relative to the BasePath of the RealServer), and filename is the name of the file ending with .rm, .ra, or +.swf.
    For example, to provide access to a RealVideo file called hello.rm, the text of your metafile would be:
    pnm://www.server1.com/hello.rm
    where www.server1.com is the DNS name of the machine running your RealServer, on which you store your RealAudio or RealVideo files.
    If you want more than one file to play in sequence when the user clicks your link, create a metafile containing several URLs (on separate lines with no intervening blank lines). For example, if your metafile contains:
    pnm://www.server1.com/hello.rm
    pnm://www.server1.com/welcome.rm
    pnm://www.server1.com/coolstuff.rm

    the Player automatically plays your three files in sequence. A listener can use the Clip menu on the Player to move forward and backward between clips.
    If you are using RealFlash Animation, combine the audio file name with the RealFlash file name using the plus (+) sign:
    pnm://www.server1.com/hello.rm+hello.swf
    pnm://www.server1.com/welcome.rm
    pnm://www.server1.com/coolstuff.rm
  2. Save your metafile in the "All files (*.*)" format, using a .ram file name extension.
    For example, you could save the three lines shown above in a file named welcome.ram on your Web server.
  3. In your HTML document, reference the metafile in a hyperlink, followed by a reference to the RealAudio or RealVideo icon (so that the icon is displayed to the left of the file):
    <A HREF="http://www.real.com/welcome.ram"> <IMG SRC="http://www.real.com/pics/rvfile.gif" align=left border=0> Welcome!</A>
    where welcome.ram is the metafile.


File Name Extensions

Each metafile that you create must be given a file name extension. This extension tells your Web server what the metafile is, to ensure that the enclosed URL is handled properly.

There are two metafile types: .ram and .rpm. These different file name extensions are passed on by your Web server and tell the user's Web browser which application to launch to play the referenced file:

.ram file - Web browser launches RealPlayer
.rpm file - Web browser launches RealPlayer Plug-in (see below)

You must configure your Web server to understand that the extension .ram refers to the MIME type x-pn-realaudio and that the extension .rpm refers to the MIME type x-pn-realaudio-plugin.


Customizing Calls to Video and Audio Content

Optional arguments may be added to metafiles to finesse what is seen and heard by users when they click your RealMedia link. You may alter the point in a clip at which play starts or ends, or the Title, Author, and Copyright information is displayed by RealPlayer.

Add the options to your metafile following the URL to which they apply. Options must be preceded by a ? (question mark) and separated from each other by an & (ampersand). The syntax is as follows:

pnm://www.real.com/test.rm?[opt1]&[opt2]

where opt is a name/value pair separated by an equal sign (=). For example,

title="mymovie"


Changing Start and Stop Times

To create a link that starts playing a clip from a point other than the beginning of the file, use the start command. Specify the time into the clip at which play should begin. For example:

pnm://www.real.com/test.rm?start="30"

would result in playback starting thirty seconds into the file.

The format for the start time is as follows:

start="dd:hh:mm:ss.ss"

Tenths of seconds are separated from seconds by a decimal point; the other units of time are separated by colons. The time is interpreted from right to left, and it is not necessary to specify days, hours, or minutes if these are not relevant.

Similar to the start option is the end option. For example, the metafile text:

pnm://www.real.com/test.rm?end="5:30"

is used to provide for playback of test.rm that terminates five minutes and thirty seconds from the start of the clip.

The end time is always measured from the actual start of the data in the file, even in the case where playback begins elsewhere. For example, the line:

pnm://www.real.com/test.rm?start="30"&end="5:30"

is used to start play of test.rm from the thirty-second mark and to stop play five minutes later.


Changing Title, Author, or Copyright Information

The following options exist to change the descriptive information from within the metafile:

title="new title"
author="new author"
copyright="new copyright"

Strings can be changed independently or in combination.

Changing information in this manner does not change what is stored in your file-only what is displayed when it is accessed through this particular metafile. This functionality is especially useful if, for example, you have one large file that contains your band's entire CD, and you want to credit the author of each song as it plays. You could create a multi-clip .ram file as follows:

pnm://www.server/band.rm?end="5:30"&title="Song1"
pnm://www.server/band.rm?start="5:31"&end="7:45"&title="song2"&author="Joe Smith"
pnm://www.server/band.rm?start="7:46"&end="15:01"&title="song3"&author="Jane Smith"&copyright="My Music, 1996"

© 1997 RealNetworks, Inc.