Chapter 1: RealOne Player Environment

This chapter introduces you to the RealOne Player media and browsing environment, explaining the various authoring techniques you can use to create compelling media presentations. It also covers the functional areas in which you can use Javascript or ActiveX to create innovative Web presentations.

The Three-Pane Environment

RealOne Player integrates streaming media with HTML pages simply and effectively. Because previous versions of RealPlayer did not natively display HTML pages, linked pages opened in the viewer's default Web browser, which split the presentation between separate applications. RealOne Player closes this divide, benefitting both the viewer, who does not have to switch between applications to watch an integrated presentation, and the presentation author, who can more easily coordinate streaming media with Web pages.

As with past RealPlayers, you can still embed streaming media in any Web page that viewers display in their favorite Web browsers. Although embedding is a widely used means of integrating streaming media with HTML content, the required embedding markup can be cumbersome. With RealOne Player, you can keep your streaming media and HTML pages separate, coordinating the two with simple production techniques. This reduces the work required to stream media and display HTML pages simultaneously.

The following figure illustrates the three-pane environment of RealOne Player, which is based on the metaphor of "play/more/explore." Here, the Media Playback pane plays streamed or downloaded clips. The Related Info pane gives the viewer more information about the presentation. And the detachable Media Browser pane lets the viewer explore the World Wide Web. This design gives you one pane for playing media, one pane for displaying small HTML pages related to the media, and one pane for showing large Web pages, such as your home page.

RealOne Player Three-Pane Environment with a Secondary Browsing Window

For More Information: The presentation planning chapter of RealNetworks Production Guide contains a more in-depth overview of the RealOne Player panes.

The Media Playback Pane

The media playback pane hosts media clips and includes buttons for play, pause, rewind, volume control, and so on. Any streaming or downloaded media playable in RealOne Player can display in this pane. This includes the core RealOne Player clip types and markup languages:

RealAudio® for audio

RealVideo® for video

RealText® for timed text

RealPix™ for still-image slideshows

Macromedia Flash for animation

SMIL for creating an integrated presentation from multiple clips

In addition, RealOne Player can play many other media types, including MPEG audio and video.

The Related Info Pane

The related info pane, which is also called the "context pane," appears to the right of the media playback pane. It's designed to display small HTML pages that supplement media clips. These pages might contain album cover art, copyright information, advertisements, and so on. Although using the related info pane is not required, displaying supplemental HTML pages in this pane greatly enhances the viewing experience. The related info pane can display any HTML page content supported by Microsoft Internet Explorer version 4.

Because the media playback and related info panes are separate, you can easily open multiple HTML pages as a presentation plays, displaying each page at a specific point in the media timeline. You can thereby update the related info pane simply by opening a new HTML page. RealOne Player thereby lets you focus on your media, and display any number of supplemental HTML pages by using simple production techniques.

The Media Browser Pane

The media browser pane can attach to, or detach from, the media playback pane and related info pane. When attached, it appears below the two other panes. Detached, it appears as a stand-alone window that the viewer can close independently of the media playback and related info panes. Sending an HTML page URL to a closed media browser pane reopens the pane, however.

Through the media browser pane, RealOne Player users can surf the Web, play CDs, access their personal media libraries, transfer clips to portable players, and so on. Presentation authors can also use this pane to display Web pages associated with a streaming presentation. The pane can display any content supported in Microsoft Internet Explorer version 4, including Javascript. You might use this pane to display your home page after a media presentation plays, for example.

Now Playing List

In the left side of the media browser pane, viewers can display a clickable "Now Playing" list. When the viewer plays a streaming media clip or presentation, the clip or presentation title displays in this list. Additionally, the viewer can build a clip list by dragging media links from an HTML page displayed in the related info or media browser pane.

RealOne Player `Now Playing' List

Secondary Browsing Windows

Like most Web browsers, RealOne Player can display any number of additional browsing windows, which are always detached from the three-pane environment. You can display Web pages associated with your presentation in secondary browsing windows, for example. Displaying full Web pages in the media browser pane is preferable in most cases, though, because many viewers are likely to have that pane already attached to the media playback and related info panes. Additionally, only the media browser pane includes the "Now Playing" list.

Controlling Interactions Between RealOne Player Panes

RealOne Player supports a variety of authoring languages and techniques that allow content in one pane to control content in another pane. The following sections describe these languages and techniques, helping you to decide how to create a presentation based on how you want the presentation to function.

Displaying HTML Pages Through Streaming Media

With your streaming media, you can use three techniques to open URLs in the related info or media browser pane. Although these techniques do not involve scripting, they are compatible with the scripting methods covered later in this guide. They allow you to create "media-driven" presentations, in which supplemental information displays in the HTML panes based on the media timeline, or viewer interaction with media clips.

Note: Although RealOne Player can play proprietary formats used by other media players, such as Windows Media and QuickTime, it does not support the use of a Ram file or SMIL with these formats. When streaming one of these formats to RealOne Player, you must author presentations using the markup conventions supported by Windows Media Player or QuickTime Player, respectively.

Appending HTML URLs to Media URLs in a Ram File

You typically launch media clips that play in RealOne Player with a Ram file, which uses the extension .ram. The plain text Ram file, which you can link to any Web page with a standard <a href> tag, launches RealOne Player, and gives it the full HTTP or RTSP URL to a media clip or SMIL presentation. Within the Ram file, you can append URLs that open HTML pages in the related info or media browser pane. This Ram file method is easy to use, and is well-suited for simple presentations, such as a single RealVideo clip that displays an HTML page as it plays.

For More Information: For full information about the Ram file syntax, see the presentation delivery chapter of the RealNetworks Production Guide. Introduction to Streaming Media with RealOne Player also covers this topic in its Ram file chapter.

Embedding HTML URLs In a RealVideo or RealAudio Clip

When you create a RealVideo or RealAudio clip with Helix Producer, you can write an events file that defines one or more URLs that open in a RealOne Player HTML pane at certain points as the clip plays. You then use a utility that embeds the events file into the clip. Whenever you stream the clip, the encoded URLs open automatically. This technique works only with RealAudio and RealVideo clips. Because it encodes URLs directly into the clip, it is not recommended if you want the HTML pages associated with clips to change over time, or you want to stream the clip without opening the URLs.

For More Information: For information about merging an events file with a clip through the rmevents.exe utility, see Introduction to Streaming Media with RealOne Player.

Using SMIL to Display HTML Pages

To lay out and synchronize multiple media clips, you use Synchronized Multimedia Integration Language (SMIL) to create simple to highly complex media presentations. A SMIL presentation always plays in the media playback pane, but it can also open HTML pages in the other panes. Using SMIL gives you far more control over HTML display than using a Ram file or encoding URLs directly into clips. The following are some of the capabilities that SMIL gives you in the RealOne Player environment:

Open any number of HTML pages automatically at any point.

Open HTML pages interactively, such as when the viewer clicks a graphic image displayed in the media playback pane.

Use a powerful timing model to define exactly when HTML pages open. For example, SMIL lets you open a page whenever a clip finishes playing. You do not need to know how long the clip lasts.

Manage bandwidth for complex presentations. SMIL lets you "prefetch" clip and HTML page data before the pages display.

Display different HTML pages based on the viewer's preferred language, available bandwidth, monitor color depth, or many other criteria.

Note: RealOne Player supports both SMIL 1.0 and SMIL 2.0. Only SMIL 2.0 lets you open URLs automatically in the RealOne Player HTML panes, though.

For More Information: For full information about SMIL and RealOne Player, see RealNetworks Production Guide. For a basic introduction to SMIL, see Introduction to Streaming Media with RealOne Player.

Controlling Content Through the HTML Panes

Through HTML pages displaying in the related info or media browser, you can control the media displaying in the media playback pane, as well as open new HTML pages. These methods, which you can mix with the media-based techniques described above, allow you to create "user-driven" presentations, in which clips and supplemental information display according to viewer interaction within the HTML panes.

Opening URLs with Simple Links

Because the related info or media browser pane display any HTML content, the most basic way to control the presentation is to add simple hypertext links in the form <a href> to the HTML pages that display within these windows:

A simple HTML hypertext link can open a new page in the media browser pane from the related info pane. You simply need to add the correct target attribute to the <a href> tag:

<a href="URL" target="_rpbrowser">

Any other target name will open the HTML page in a secondary window that is detached from the basic three-pane environment. You should not attempt to open an HTML page in the related info pane with a simple link in the media browser pane, however, because the related info pane URL requires sizing information that you cannot pass in the link. The Javascript/ActiveX methods let you pass this information, though.

If you link to a Ram file with a simple <a href> link, the clip or SMIL presentation given in the Ram file URL automatically plays in the media playback pane. You do not need to use any additional pane targeting method.

Tip: To avoid a file downloading dialog, you can use the Javascript/ActiveX methods for playing clips when the viewer clicks certain links.

Javascript and ActiveX Methods

RealOne Player supports several methods that work with both Javascript and ActiveX. These give you the most control over the presentation through the HTML pages displaying in the related info or media browser pane. The remainder of this chapter describes how to use these methods.

Using Javascript and ActiveX in the RealOne Player Environment

The Javascript and ActiveX methods available in the RealOne environment are superior to simple hypertext links for opening media in the media playback pane, or for displaying HTML pages. Additionally, these methods let you build an interactive application that lets viewers perform functions such as adding clips to the "Now Playing" list, adding clips to the favorites list, and displaying RealOne Player dialog boxes.

Note: These extensions are customized for the RealOne Player media environment, and will not work in external Web pages. In addition, the environment itself depends upon the client- installed version of Internet Explorer. RealOne Player requires Internet Explorer v4.0 or later to run optimally.

The RealOne Player environment can be accessed from within the player itself, or from Web pages external to the player. Use the Javascript methods and events to perform functions from within the player environment. Use the RealOne Player ActiveX control to provide content to the RealOne Player environment from Web pages external to the player.

Using Javascript Methods and Events

To use the available Javascript methods and events, you must declare them in the script section of a Web page displayed in the media browser pane or the related info pane.

When using the Javascript methods and events from within the RealOne Player environment, all methods are in the "external" container of the document object model (DOM), that is, they are appended to window.parent.external. Therefore, a call to PlayClip in RealOne Player would look like the following:

window.parent.external.PlayClip(...)

Using ActiveX Controls

The ActiveX controls provided with RealOne Player are similar in scope to the Javascript methods and events, with some limitations, such as no ability to preload URLs. However, these controls let you target and, to a great degree, control RealOne Player from an external browser as you would from within the RealOne Player environment. To use the ActiveX control, declare it in the body of your Web page with the following class ID:

CLSID:FDC7A535-4070-4B92-A0EA-D9994BCC0DC5

for example:

<OBJECT ID="RealOneActiveXObject" WIDTH=0 HEIGHT=0 CLASSID="CLSID:FDC7A535-4070-4B92-A0EA-D9994BCC0DC5">
</OBJECT>

In script code, you can then call methods on this object using its object ID:

RealOneActiveXObject.PlayClip(…)

View it now! (requirements for viewing this sample)
The Active X samples in this guide demonstrate using various methods described in this chapter from an external browser.

Using RealOne Player Methods

The RealOne Player methods provide a means of directly accessing the player and modifying content through your web page. These methods are broken down into basically two categories, those that customize playback and dynamically open URLs, and those that retrieve information.

Customizing Playback and Dynamically Opening URLs

The RealOne Player environment can synchronize the display of associated URLs with a playing clip. Several methods allow you to play a clip in the media browser pane and simultaneously display a URL in the related info pane when playback begins. In addition, you can specify the height and width of the related info pane as you want it to appear when the clip plays.

Specifying a URL for the related info pane is optional in all of these methods. If you do not specify a URL with the related info pane as the target, the specified clip will play in the media playback pane and the related info pane will not open. If a URL is specified without a target listed, it will automatically display in the media browser pane.

Because the related info pane is cleared each time a new presentation begins, the related info pane is automatically closed by default if you play a new presentation without specifying a new related info pane.

Methods for Custom Playback and Opening URLs
Method	Description	Reference
`AddToNowPlaying`	Adds a clip URL to the clip list.	click here
`ClearNowPlaying`	Clears the current playlist.	click here
`HandleAction`	Performs a specified action.	click here
`OpenURLInPlayerBrowser`	Opens a URL in the media browser pane.	click here
`PlayClip`	Sends a URL to the media playback pane.	click here
`PreLoadURL`	Called before playback begins.	click here
`SetVideoBackgroundColor`	Sets the video background color to the specified value.	click here

Playing a Clip

Because of the diversity of the RealOne Player environment, there are numerous ways of playing a clip. Clips can be played from an existing web page, or you can devise elaborate combinations of URLs and related information that can be displayed while the clip plays.

The simplest means of playing a clip in the RealOne Player enviroment is to add a single Javascript line to a web page that is to be run in the player's media browser pane or related info pane. This line automatically begins playing a clip you have selected. For example, the following line would play the welcome.rm file:

window.parent.external.PlayClip("rtsp://helixserver.example.com/welcome.rm")

Note: The zipped HTML+Javascript version of this guide, which you can download from http://service.real.com/help/library/encoders.html, contains several sample files. Because some of these files use absolute, local paths, you must copy the entire samples directory to your C: drive (c:\samples) before playing them.

View it now! (requirements for viewing this sample)
This sample demonstrates how to play a simple clip.

You can also open the RealOne Player and play a clip from an external web page. To do this, you must use an ActiveX control that provides a class identifier that lets you target and control the RealOne Player (using an ActiveX control is described in "Using ActiveX Controls"). For example, the following line in an external web page would play the welcome.rm file in RealOne Player:

RealOneActiveXObject.PlayClip("rtsp://helixserver.example.com/welcome.rm")

View it now! (requirements for viewing this sample)
This sample lets you open the RealOne Player environment from an external web page and play a simple clip.

The PlayClip method also contains many options for customizing your presentation in the RealOne Player environment. Each of these options can be used indivdually, or in any combination, whatever is required to enhance your presentation.

While your clip is playing, the status display at the top of the RealOne Player contains information provided with each clip that is played. This information can also be obtained using the GetClipInfo method. In some cases, you might want to replace this material with alternative information. The PlayClip method contains a set of optional parameters that modify the information used in the clip. For example, the following code would change the title and artist name:

// Play a clip and show new status display
function clipPlay() {
    window.parent.external.PlayClip(
        "rtsp://helixserver.example.com/welcome.rm",
        "Title=Glorious Day|Artist name=Me Alone")
}

View it now! (requirements for viewing this sample)
This sample demonstrates how to change the clip information.

Note: For more information on using the GetClipInfo method to display all of the information associated with a clip, see "Displaying Clip Information"

RealOne Player is more than just a player. The RealOne Player environment can also display information related to the clip being played, or let you browse a web page in the media browser. All of these capabilities can be controlled while playing a clip. The PlayClip method includes parameters to add content to the related info pane, which appears beside the current playing clip, and browsing capabilitis in the media browser pane. Both of these capabilities can be used individually, or all at once. For example, the following code displays information in the related info pane, and displays content from a URL in the media browser pane:

// Play a clip, display related info, and load URL in media browser
function clipPlay() {
    window.parent.external.PlayClip(
        "rtsp://helixserver.example.com/welcome.rm","",
        "http://www.example.com/welcome.htm", 300, 220,
        "http://www.real.com", "_rpbrowser")
}

The size of the related info pane is automatically set by the size of the media clip being played in the media playback pane. However, you can alter the size of the related info pane (along with the height of the media playback pane) by setting the width and height parameters in the PlayClip method, as was done in the previous example.

The previous example also displays the www.real.com web site in the media browser pane. If you would prefer to open a separate window for this URL, replace the _rpbrowser string in the previous example with any other target name, and the URL will be displayed in a secondary window.

Once you have opened a URL in the related info pane, you can continue to use the information supplied by that URL during playback of other clips. A reserved value, _keep, preserves the last URL loaded in the related info pane without having to reload the URL when another clip begins playing.

// Play a clip and keep previous related info URL
function clipPlay() {
    window.parent.external.PlayClip(
        "rtsp://helixserver.example.com/welcome.rm","",
        "_keep", 300, 220)
}

The next sample shows how to play a clip in the media playback pane and display a URL in the media browser pane, but because no related information is supplied, no related info pane is displayed:

// Play a clip and load URL in media browser
function clipPlay() {
    window.parent.external.PlayClip(
        "rtsp://helixserver.example.com/welcome.rm","",
        "", 0, 0, "http://www.real.com", "_rpbrowser")
}

The RealOne Player media browser pane contains a "Now Playing" list on the left side. When you play a clip using the PlayClip method, you can specify whether the clip is added to the "Now Playing" list. By default, the clip is added. To prevent the clip from being added, set the bnow_playing parameter to false, as shown in the following example:

// Play a clip, don't add to Now Playing list
function clipPlay() {
    window.parent.external.PlayClip(
        "rtsp://helixserver.example.com/welcome.rm","",
        "", 0, 0, "", "", false)
}

The PlayClip method contains one required parameter and seven optional parameters. You do not need to type out all of the optional parameters when you use this method. However, if any optional parameter is used, all optional parameters up to the one being used must contain an entry. For a string parameter, this entry must be a pair of empty quotes. For the integer width and height parameters, you must enter a zero (0) when they are not used.

Using the Now Playing List

The Now Playing list, located on the left side of the media browser pane, shows what clips are currently queued to play and what clips have most recently been played. The AddToNowPlaying method opens the Now Playing list (if it is currently closed) and adds a clip to the play list. You can add multiple clips to the play list using AddToNowPlaying as many times as required since this method does not initiate playback. The only required parameter is the URL for the clip to be added.

This method also contains several optional parameters for loading URLs and displaying clip information. These optional parameters work in the same way as the optional parameters in the PlayClip method. For more information on these optional parameters, see "Playing a Clip".

It is a good idea to clear the Now Playing list of any clips that may already be listed before adding any new clips. That way you can create a list that does not contain any clips that may have prevously been included in the clip list. To clear the clip list in the Now Playing list, use the ClearNowPlaying method. This method removes all of the clips currently listed in the Now Playing list.

parent.window.external.ClearNowPlaying()

View it now! (requirements for viewing this sample)
This sample demonstrates how to add entries to and clear the Now Playing list.

Opening a URL in the Media Browser Pane

The PlayClip method lets you open a URL in the media browser pane whenever you start playing a clip in the media playback pane. However, you might want to open a URL in the media browser pane before or after the clip begins playing. To do this, use the OpenURLInPlayerBrowser method. For example, the following code demonstrates how to open a URL in the media browser pane five seconds after a clip has begun playing:

// Open URL five seconds into playback
function RPOnPositionLengthChange(position, length)
{
    if ( position == 5000) {
        parent.window.external.OpenURLInPlayerBrowser("http://www.real.com")
    }
}

View it now! (requirements for viewing this sample)
This sample demonstrates how to open a URL in the media browser pane after the clip plays five seconds.

Caching URLs to Enhance Playback Performance

RealOne Player provides an event handler (RPOnPreLoad) and method (PreloadURL) to cache URLs before a presentation begins playing. While not required, caching URLs locally improves playback quality because RealOne Player does not have to sacrifice bandwidth to retrieve the URLs from a remote location during playback.

The PreloadURL method can be used at any time (even outside of an RPOnPreload event) to load a URL in the browser's cache. However, care should be taken when using this outside of the RPOnPreload event in that referencing a Web page during content playback could appreciably slow the bandwidth from the media stream. You could, for example, use the GetPlayerState method to determine if the user is currently playing a clip and, if not, begin preloading more URLs.

Note: You should test your presentation when preloading numerous URLs to ensure that playback bandwidth is not adversely affected.

The following example shows one possible method of using the PreloadURL method to load URLs in the browser cache before media playback begins:

// Preload web pages before media playback begins.
function RPOnPreload()
{
        parent.window.external.PreloadURL("http://server/slide1.html")
        parent.window.external.PreloadURL("http://server/slide2.html")
        parent.window.external.PreloadURL("http://server/slide3.html")
}

Handling Actions

The RealOne Player environment includes a method that handles a variety of actions. The HandleAction method provides a means of moving the user about in the RealOne Player environment, opening various dialogs, and navigating to specific URLs in the media browser pane or a secondary window.

During your presentation, you might want to move the user around various tabs in the media browser pane, or open the "Now Playing" list to display the clips that are set to play. The HandleAction method can open the Web, My Library, CD, Devices, and Radio panes to display whatever information the user requires. In addition, the HandleAction method can open the "Now Playing" list to display the current clip list. For example, the following line opens the My Library tab in the media browser pane:

parent.window.external.HandleAction("MyLibrary")

In some cases, you may need the display the player's Preferences or Equalizer dialogs. The HandleAction method can open either of these dialog boxes. In addition, you can open the Preferences dialog box to any individual category or page. For example, the following line opens the Preferences dialog box in the Playback Settings page of the Connection category:

parent.window.external.HandleAction("ShowPreferences(Connection,Playback Settings)")

The HandleAction method also provides a means of navigating to a specified URL, which is displayed in either the media browser pane, or a secondary pane. For example, the following line opens a URL in a secondary window:

parent.window.external.HandleAction("NavigateToURL(www.real.com, '_rpexternal')")

You can also use the HandleAction method to show or hide the artist information in the current clip. For example, the following line hides the artist information in the current clip:

parent.window.external.HandleAction("ShowArtistInfo(0)")

View it now! (requirements for viewing this sample)
This sample demonstrates how to handle various actions in RealOne Player.

Setting the Background Color

By default, the background color for the media playback pane is set to black. If the media playback pane size is changed so that it is larger than the media playing in the pane, the background color shows around the edges of the media.

To change the background color, use the SetVideoBackgroundColor method. This method takes a string value consisting of one of two formats. The first format type consists of a sting containing the RGB hexadecimal value of the color you want to use in the form #RRGGBB, where RR represents the red value, GG represents the green value, and BB represents the blue value. Each of the color values can be set from 00 to FF in hexadecimal. For example, to set the background color to red:

parent.window.external.SetVideoBackgroundColor("#FF0000")

The second format type consists of a string containing the red, green, and blue values in an array of the form rgb(x,x,x), where x is a decimal value from 0 to 255. For example, to set the background color to blue:

parent.window.external.SetVideoBackgroundColor("rgb(0,0,255)")

View it now! (requirements for viewing this sample)
This sample demonstrates how to set the background color of the media playback pane.

Retrieving RealOne Player Information

The following table summarizes the methods that you can use to retrieve RealOne Player information.

Methods for Retrieving RealOne Player Information
Method	Description	Reference
`ComponentVersion`	Retrieves the version of an updated component.	click here
`GetClipInfo`	Returns desired clip information as a string.	click here
`GetPlayerState`	Returns the player's current state.	click here
`InstalledComponents`	Retrieves a list of DLLs that have been installed by RealOne Player.	click here
`PlayerProperty`	Retrieves the value of a specified RealOne Player property, such as the language preference or the operating system name.	click here
`RealPlayerVersion`	Detects the RealOne Player version and returns it in packed form.	click here

Retrieving Version Information

If you are preparing new content for your web page, it might be necessary to determine the version of the user's player and its components before attempting to run updated material. RealOne Player contains two methods that retrieve information about the player version and about individual components of the player.

The RealPlayerVersion method returns the version information about the user's installed player as an integer value in a packed format. You can use this information to determine if the user is running a version of the player that is capable of playing back your web content. If not, you can either run only those parts of your content that the user's player is capable of running, or you can advise the user to update their player. For example, the following code retrieves the RealOne Player version number and prints it on the browser:

// Get RealOne Player version
function playerVersion() {
    var vers=window.parent.external.RealPlayerVersion()
    document.write("The version of RealPlayer is " + vers)
}

Note: Currently, the RealPlayerVersion method must be used without parenthesis at the end of the method name.

View it now! (requirements for viewing this sample)
This sample demonstrates how to get and unpack the RealOne Player version.

Sometimes it may be necessary to get the version information for an individual component in the player. If an individual codec has been updated, for instance to a new build your code requires, but the version of RealOne Player remains the same, use the ComponentVersion method to get the version information for the individual component. This method takes as an argument the individual codec version for which you are trying to retrieve information. For example, the following code demonstrates how to retrieve the version information for the Flash 6.0 codec:

// Get packed component version number 
function CompVersion() {
    var vers=RealOneActiveXObject.ComponentVersion("Flash:6.0")
    document.write("The Flash plugin version is " + vers)
}

View it now! (requirements for viewing this sample)
This sample demonstrates how to get and unpack component versions.

The version information returned by ComponentVersion and RealPlayerVersion is an integer value in a packed format. To unpack the information into a readable format, use the UnpackVersionNumber function discussed in "Unpacking Version Information".

Unpacking Version Information

Both the ComponentVersion and RealPlayerVersion methods return version information as an integer value in a packed format. This integer value is useful if you are going to compare other version information against the value returned by these methods.

The version information can also be viewed as an unpacked string. This unpacked string provides the version information in a readable format composed of the major version, minor version, and build number, with each number separated by a period. This format is consistant with the player's version information as presented in the About RealOne Player dialog box. For example:

6.0.10.290

The Javascript version of the UnpackVersionNumber function listed below takes the integer value returned by either ComponentVersion or RealPlayerVersion and unpacks it into a readable string. The entire UnpackVersionNumber function must be used as shown below in any page or script to invoke it properly.

function UnpackVersionNumber(n)
 {
   return "" + (n >> 28) + "." +
   ((n & 0xFF00000) >> 20) + "." + 
   ((n & 0xFF000) >> 12) + "." + 
   ( n & 0xFFF);
 }

You can also use the UnpackVersionNumber function in VBScript with the following code:

Function UnpackVersionNumber(n)
    UnpackVersionNumber = (((n And &HF0000000) / &H10000000) & "." & _
        ((n And &HFF00000) / &H100000) & "." & _
        ((n And &HFF000) / &H1000) & "." & _
        (n And &HFFF))
End Function

The following Javascript example demonstrates how to use the UnpackVersionNumber function. The first part of the example declares the function as part of the page, though this could be done in an external script as well. The second part invokes the function on a version number retrieved using RealPlayerVersion, then assigns the resulting string to the variable szPlayerVersion.

// Unpack the version number
function UnpackVersionNumber(n)
{
     return "" + (n >> 28) + "." + ((n & 0xFF00000) >> 20) + "." + 
          ((n & 0xFF000) >> 12) + "." + ( n & 0xFFF);
}
     ...
{
     var nRPVersion = window.parent.external.RealPlayerVersion
{
     szPlayerVersion= UnpackVersionNumber(nRPVersion)
}

View it now! (requirements for viewing this sample)
This sample gets the RealOne Player version information from an external browser and displays the information in packed and unpacked format.

Getting Player Information

When the RealOne Player is installed on a user's system, it saves a set of properties that describe the user's operating system, and information about the player that was installed. You can retrieve this information using the PlayerProperty method. The PlayerProperty method takes a single parameter that describes the type of property for which you want information returned. For example, the following code returns the user's operating system, the version of the player that is installed, and the bandwidth setting chosen by the user:

// Get player property information
function getProperty() {
    document.write("Operating system: " +
        parent.write.external.PlayerProperty("OSNAME") + "<BR>")
    document.write("Product version: " +
        parent.write.external.PlayerProperty("PRODUCTVERSION") + "<BR>")
    document.write("Player bandwidth: " +
        parent.write.external.PlayerProperty("BANDWIDTH"))
}

View it now! (requirements for viewing this sample)
This sample demonstrates how to get the player properties of the RealOne Player.

Displaying Clip Information

RealOne Player contains two methods that can retrieve information about the clip in the clip in the media playback pane. The first, GetClipInfo, returns information about the clip. The second, GetPlayerState, returns the current state of the clip.

Clips loaded in the media playback pane usually contain a set of information that describes the composition of the clip. Many clips, for instance, contain the album name and the name of the artist. Other possible information contained in the clip could be the genre of the clip, the language in which the clip is recorded, the year the clip was recorded, and so on. Use the GetClipInfo method to retrieve this information. The GetClipInfo method takes as an argument the type of information you want returned, such as the author name, and returns that information from the clip. For example, the following code returns the album name and the name of the artist:

// Get the album name and artist
function getInfo() {
    document.write("Album name: " + 
        parent.window.external.GetClipInfo("Album name")
    document.write("Artist name: " + 
        parent.window.external.GetClipInfo("Artist name")
}

View it now! (requirements for viewing this sample)
This sample demonstrates how to retrieve the clip information.

Once a clip is loaded in the media playback pane, you can retrieve the current state of the clip. Once you get the state of the clip, you can use this information to determine what actions you take. If the user is listening to the clip, for instance, you could choose to add a new clip to the Now Playing list. Use the GetPlayerState method to retrieve the state of the clip. The GetPlayerState method can determine if the clip is stopped, contacting a URL, buffering, playing, pausing, or seeking in the clip. For example, the following code detects a change in the state of the playback, and displayes the new state:

// Get the new state
function getPlayerState() {
    document.write("The player is currently " +
        parent.window.external.GetPlayerState( ))
}

View it now! (requirements for viewing this sample)
This sample demonstrates how to get the current player state.

Determining Installed Player Components

Before you begin a presentation on RealOne Player, you should check to ensure the player contains all of the components required to display your work. The InstalledComponents method can be used to retrieve the list of DLLs that are currently installed on the user's player. This list can then be compared to the required components for your presentation.

The following example shows how to check the player's installed components. The information returned by InstalledComponents includes the name of each component, along with the version number of that component. The component name and version number are separated by a colon ( : ), and each component name and version number pair are separated by a pipe symbol ( | ). This example takes the returned list of components and uses the pipe symbol to parse each component to a separate line.

// Parse the installed components
function installComp(){
       var install=RealOneActiveXObject.InstalledComponents()
       document.write("The following components are currently installed:<BR><BR>")
       while(install.indexOf("|")>0){
               component = install.substring(0,install.indexOf("|"));
               document.write(component + "<BR>");
               install = install.substring(install.indexOf("|") + 1, install.length);
       };
       document.write(install)
}

Note: Currently, this method must be used without parenthesis at the end of the method name.

View it now! (requirements for viewing this sample)
This sample demonstrates how to retrieve information on the installed components in the RealOne Player.

Using RealOne Player Event Handlers

RealOne Player reports the events that occur within the application using a set of predefined functions known as event handlers. You can use the event handlers presented here on your Web page to intercept and interpret RealOne Player events, such as capturing user interactions with the application controls, or monitoring the progress of your presentation. The following table summarizes the available events.

Events for Retrieving RealOne Player Information
Method or Event Name	Description	Reference
`RPOnBuffering`	Called when RealOne Player buffers a clip.	click here
`RPOnPositionLengthChange`	Called at regular intervals as the clip position changes.	click here
`RPOnPreLoad`	Called before playback begins.	click here
`RPOnStateChange`	Called when the RealOne Player state changes.	click here

View it now! (requirements for viewing this sample)
This sample demonstrates how to retrieve callbacks returned from the RealOne Player.

Handling Media Clip Buffering

The RPOnBuffering event handler returns information about the buffering event while the media clip is buffering. In addition, it returns a value that represents the percentage of buffering that has completed.

The following example displays in the current pane any buffering state that is occurring, along with the percentage of buffering that has completed:

// Display the current buffering state and percentage
function RPOnBuffering(flags, percent)
{
    buffer = "Buffering: " + flags + ", " + percent + "%<BR>"
    document.write(buffer)
}

Determining the Current Time Position

Whenever a media clip is playing in the media playback pane, the position of the clip is automatically updated every half second. You can use this information to schedule events at a specific time during the clip, such as loading URLs in the related info pane or the media browser pane.

The RPOnPositionLengthChange event handler returns the current time position within the clip during playback, along with the total duration of the clip. The current position is returned in as the number of milliseconds in half second increments (that is 500 for the first half second, 1000 as the second half second, and so on).

The following example displays a URL in the current pane after the clip has played for five seconds:

// Synchronize HTML with your presentation
function RPOnPositionLengthChange(position, length)
{
    if ( postion == 5000 ) {
        flag = 1
        document.location = "http://www.real.com"
    }
}

Performing Tasks Before Playing a Clip

Before you begin playing a clip, you can perform tasks that might affect the bandwidth of the clip if the task was performed during playback. This is especially important for users with a low-bandwidth connection, such as a 56K modem.

The RPOnPreload event handler processes events that occur before a clip is played. For example, you could use this time to preload URLs destined for the related info pane or the media browser pane. Preloading URLs allows for faster display later on during media playback, especially when synchronizing URLs with the media being played.

An RPOnPreload event occurs whenever the player encounters a ?rpcontexturl query string in a .RAM, .RM, or .SMI file. In general, the first HTML related info URL should preload all the related info URLs used in the presentation. You should test your presentation, however, to ensure the number of related info URLs you are preloading does not delay the beginning of the playback too long, and that the presentation works as expected.

The following example preloads two URLs that will be used later during playback:

// Preload the required URLs
function RPOnPreload()
{
    window.parent.PreloadURL("http://www.real.com")
    window.parent.PreloadURL("http://service.real.com")
}

Detecting a State Change

Sometimes it might be necessary to determine the current state of the player. For example, you might want to know if the user is currently playing back a clip and, if so, you can add a clip to the Now Playing list rather than using the PlayClip method, which would be more intrusive

The RPOnStateChange event handler returns the state of the clip being played whenever the state changes. The value returned by this event handler is an integer that indicates whether the clip has stopped, has started playing, has been paused, and so on.

The following sample performs a specific task depending on the state that is returned:

// Display the current state of the clip
function RPOnStateChange(newstate)
{
    var statestring=""
    switch(newstate) {
        case 0:
            statestring += "Stopped"
            break
        case 1:
            statestring += "Contacting"
            break
        case 2:
            statestring += "Buffering"
            break
        case 3:
            statestring += "Playing"
            break
        case 4:
            statestring += "Paused"
            break
        case 5:
            statestring += "Seeking"
            break
        default:
            break
    }
    document.write("The player is currently " + statestring)
}