Chapter 4: Embedded Environment

By embedding RealPlayer or RealOne Player controls in a Web page, you can incorporate streaming media directly into the page. The embedded player environment lets you place presentations in a Web page using only a simple embedding markup. But you can also extend that functionality through Javascript or VBScript, using methods that set and retrieve presentation attributes, control the clip playback, and handle user interactions.

Understanding Presentation Embedding

The following sections provide an overview to help you decide whether to embed your presentation, and, if so, which markup and scripting languages to use.

Embedded Environment vs. RealOne Environment

Before you begin embedding presentations in Web pages, read Chapter 1 to determine if using the native RealOne Player environment, which requires less work than embedding a presentation, suits your needs better. RealOne Player can natively display HTML pages without the overhead of having to include the embedding markup. You may find that developing presentations in the native RealOne Player environment saves you considerable time and effort.

How Embedding Works

To embed a streaming media presentation in a Web page, you add <EMBED> or <OBJECT> tags to your Web page markup, depending on whether you want to use the Netscape plug-in method, or the ActiveX embedding method (for more information, see "The Two Embedding Methods"). These tags allow you to add media windows and RealPlayer controls, such as Stop and Start buttons, directly to your Web page. Additionally, you can use Javascript or VBScript to extend the functionality of the embedded components.

The Embedded Player

When a viewer surfs to your Web page, the viewer's browser launches RealOne Player's embedded player (or the embedded player of an earlier RealPlayer if that software is installed on the viewer's machine). The embedded player, which is always installed with RealOne Player, handles media playback as a browser helper application, without launching RealOne Player as a separate application. If the viewer does not have RealOne Player installed, the browser typically prompts the viewer to download and install the application.

Tip: It's also a good idea to include a RealOne Player download icon on your Web page. You can find these icons at http://www.realnetworks.com/company/logos/index.html.

Backwards Compatibility

The embedding markup and methods described in this guide are geared for RealOne Player. Most markup and methods are backwards compatible with RealPlayer G2, RealPlayer 7, and RealPlayer 8. Some methods are even compatible with RealPlayer 5. RealOne Player's embedded controls have a different look from earlier players, however. Hence, a Stop button embedded in your Web page will look different for a viewer who has RealOne Player installed, than for a viewer who has RealPlayer 8 installed. The buttons will function the same way, though.

For More Information: The section "Embedded Controls" illustrates the RealOne Player embedded controls.

SMIL in Embedded Presentations

In a Web page, you can embed a single clip, a sequence of clips, or a SMIL presentation, which can coordinate many clips to a single timeline. You can play an entire SMIL presentation in a single image window in your Web page, or you can display each clip within the presentation in a separate window. RealOne Player supports SMIL 2.0 and 1.0, whereas RealPlayer G2, RealPlayer 7, and RealPlayer 8 support only SMIL 1.0. Therefore, if you embed a SMIL 2.0 presentation, viewers who have RealPlayer G2 through RealPlayer 8 installed are prompted to upgrade to RealOne Player.

Media Preparation

Before you create an embedded presentation, you'll need to create your media. RealSystem supports a wide range of streaming media clip types, including RealAudio, RealVideo, RealText (streaming, timed text), RealPix (streaming still images), Flash animation, and MPEG video and audio. You'll also need to decide which bandwidth targets you want to meet, whether dial-up modems, fast connections such as cable modems, or both.

For More Information: See RealSystem iQ Production Guide for basic information about clip types and bandwidth management. If you plan to use RealAudio or RealVideo, you'll need RealSystem Producer, which you can download from http://www.realnetworks.com/products/producer/index.h tml.

The Two Embedding Methods

The embedded player supports two types of markup that allow you to add streaming media to your Web page. The first method uses the Netscape plug- in architecture, which adds <EMBED> tags to your Web page and allows you to control playback with Javascript commands. Any browser that supports this plug-in architecture will be able to play your embedded presentation. Major browser support includes the following:

• Netscape Navigator 4.0 and higher.

There are known compatibility issues with some versions of Netscape Navigator 6.0, although versions 6.1 and 6.2 work properly. However, always be sure to test for compatibility.

• Microsoft Internet Explorer 5.0 and higher.

Even when you use the <EMBED> tag, RealOne Player communicates with the Internet Explorer browser using ActiveX technology. This makes the <EMBED> tag compatible with all versions of Internet Explorer, including version 6.

Using the Netscape plug-in method allows you to reach the widest Internet audience. However, the embedded player's ActiveX control lets you use a second method, which adds <OBJECT> tags to your Web page and allows the use of VBSript. This method provides playback capabilities within these products:

• Microsoft Internet Explorer 4.0 and higher on Microsoft Windows.
• Most applications that support ActiveX controls, such as Visual Basic and Visual C++.

Both embedding methods support the same tag parameters. Plus, the Javascript and VBScript methods are virtually identical. Because they both have the same capabilities, you can use either the Netscape plug-in or the ActiveX control depending on which products you need to support, and the audience you wish to reach.

Javascript and VBScript

Once you embed a presentation, you can use a scripting language such as Javascript or VBScript to extend the presentation's functionality. Scripting lets you add functions like stop, play, and volume control to elements such as forms, HTML buttons, or graphic images. For example, you can use your own graphic image for a Stop button, capturing mouse clicks to stop the clip playback. While the methods are most commonly accessed from Java, Javascript, or VBScript, they can also be developed using C++ and other programming languages.

Tip: If you decide not to use scripting, you may find the Web page embedding chapter of the RealSystem iQ Production Guide easier to use than this guide. That chapter covers basic embedding without scripting. You can download this guide from http://service.real.com/help/library/encoders.html.

Methods

Both the Netscape plug-in and ActiveX embedding methods support the same methods that allow you to issue commands and receive information about the viewer's embedded player, such as its version. Chapter 5 introduces you to these methods according to functional category. Chapter 6 is a reference for all available methods.

Callback Events

In addition to scripting methods that let you issue commands to the embedded player, the player supports callback methods that report events. You can use these callback methods to intercept and interpret RealOne Player events. This lets you track mouse movement, capture user interactions with the application controls, and monitor the progress of your presentation, for example. Chapter 7 is a reference for all available callbacks.

Using the Netscape Plug-in

To use the Netscape plug-in, you add <EMBED> tags to your Web page HTML. A typical <EMBED> tag has three necessary parameters (SRC, WIDTH, and HEIGHT) that are used to identify your presentation and the dimensions of the playback area. Many other optional parameters are also available. The syntax for a typical <EMBED> tag looks like the following:

<EMBED SRC="presentation.rpm" WIDTH=300 HEIGHT=134 PARAMETER=value>

The preceding sample tag creates a playback area 300 pixels wide by 134 pixels high within your Web page, and displays the contents of presentation.rpm within the playback area. Typically, your Web page will contain multiple <EMBED> tags, each of which embeds a different RealOne Player control. You link all of these tags together using the CONSOLE parameter.

All parameters typically have the form PARAMETER=value. The parameter names can be any letter case, although this manual depicts them in uppercase. Except for file names, which must typically be lowercase, parameter values are not case-sensitive. Unless they are URLs, parameter values do not need to be inside quotation marks.

For More Information: For a list of all <EMBED> parameters, see "Tag Parameters". The section on the SRC parameter contains information about linking your Netscape plugin to your media. Available controls are described in "Embedded Controls".

Extending Embedded Controls Through Javascript

To extend RealPlayer's Netscape plug-in functionality with Javascript, you first embed the source file in an HTML page with the <EMBED> tag as described above. The following example shows an <EMBED> tag with the required SRC, WIDTH, and HEIGHT parameters, as well as several additional parameters described in "Tag Parameters":

<EMBED NAME=javademo
    SRC="demo.rpm"
    WIDTH=220 HEIGHT=180
    CONSOLE=one
    CONTROLS=ImageWindow
    BACKGROUNDCOLOR=white
    CENTER=true
    >

In the <EMBED> tag, the NAME parameter provides the name used by the Javascript functions. For Javascript to work with RealPlayer, the <EMBED> tag must not contain the parameter NOJAVA=true. This parameter prevents the Java Virtual Machine from starting up in Netscape version 4.x, but it has no effect on Netscape 6.0 or Internet Explorer browsers.

Once you create your tag or tags, you can use Javascript to issue commands to control the embedded presentation. The following example shows a simple form that provides a Play, Pause, and Stop button for the embedded presentation:

<FORM>
<INPUT TYPE="button" VALUE="Play" onClick="document.javademo.DoPlay()">
<INPUT TYPE="button" VALUE="Pause" onClick="document.javademo.DoPause()">
<INPUT TYPE="button" VALUE="Stop" onClick="document.javademo.DoStop()">
</FORM>

View it now! (requirements for viewing this sample) This sample demonstates buttons linked through Javascript.

If you include more than one instance of a single type of embedded control, or a variety of different embedded controls in your HTML document, give each instance a unique NAME. This ensures that you can use Javascript to manage each embedded control individually, if necessary.

Receiving Callbacks Through Javascript

RealPlayer communicates the events that occur in a Netscape plug-in through a set of internal callback routines. Depending on the platform and version of Netscape you are targeting, however, the embedded player supports the handling of these events using different mechanisms.

If you are developing a plug-in for Netscape version 6.0 running on Windows, UNIX, or Macintosh, the mechanism consists of including a new <EMBED> tag in your Javascript and specifying which events to receive. When targeting older versions of Netscape, use LiveConnect to receive the callbacks.

Handling Events in Netscape Navigator 6

Netscape Navigator version 6.0 does not support callback event handling in the same manner as previous versions. For this reason, the embedded player build number 6.0.8.1024 (RealPlayer 8 embedded player, update 3) introduces a new mechanism for event handling involving the use of Javascript and callback methods in a Netscape plug-in. The procedure is available for development using Javascript in the configurations listed in the following table. It is not available with C++ or ActiveX.

* Unix does not currently support callback event handling.

To use the new mechanism in your Javascript plug-in, add the SCRIPTCALLBACKS parameter to your <EMBED> tag defintion. Identify the events to handle by providing a comma-separated list of callback methods, or by specifying All to capture all events. For example:

<EMBED SCRIPTCALLBACKS=OnPresentationOpened,OnPositionChange,OnPresentationClosed>

- OR -

<EMBED SCRIPTCALLBACKS=All>

Do not worry about backward compatibility: all versions of the embedded player ignore unrecognized tags. However, you may detect the player version, and, if it is earlier than build 6.0.8.1024, inform the user that their RealPlayer version does not support the new event handling features.

For More Information: The GetVersionInfo method detects the player version. Version numbers are described in "Obtaining RealOne Player Version Information".

Handling Events in Netscape Navigator 4.x

When developing for Netscape versions 4.x, you must use LiveConnect to receive the callbacks sent by RealOne Player. LiveConnect is described in Netscape documentation available at the following Web address:

http://home.netscape.com/eng/mozilla/3.0/handbook/plugins/

To receive callbacks, you must embed a Java <APPLET> tag in your HTML code. This tag should include a reference to an event interface class file (for example, CODE="callback.class"), and have the MAYSCRIPT attribute set. In addition, you must also provide a NAME attribute (such as NAME="MyName") to identify the applet instance, as shown here:

<APPLET CODE="callback.class" WIDTH=1 HEIGHT=1 NAME="MyName" MAYSCRIPT>
</APPLET>

You can then use the <APPLET> tag name to receive callbacks. For example, you could use the following line to determine when a clip has closed:

if(document.MyName.OnClipClosed())

The HTML+Javascript version of this guide contains a rudimentary callback Java applet in the samples directory (callback.class and callback.java) for testing the callback methods of the embedded player. You can use this applet to exercise your callback routines, or modify the callback.java file and compile your own class file to more fully meet the needs of your application.

Class Files

To provide backward compatibility, the RealPlayer installation includes the following classes for event notification:

• RMObserver.class

RMObserver is a Java interface for events coming from RealPlayer 7 or later. Any object implementing this interface can register itself into RealPlayer 7 or later to get the full set of callback notifications.

• G2Observer.class

G2Observer is a Java interface for events coming from RealPlayer G2. Any object implementing this interface can register itself into RealPlayer G2 to get the set of RealPlayer G2 callback notifications.

• RAObserver.class

RAObserver is a Java interface for events coming from RealPlayer 5.0. Any object implementing this interface can register itself into RealPlayer 5.0 to get the set of RealPlayer 5.0 callback notifications.

On Linux, the RMObserver.class file is found in the raplayer.zip file in the /RealPlayer9 directory. On Windows, this class file is found in the rpcl3260.zip file in the \Program Files\Netscape\Communicator\Program\Plugins directory.

Using the ActiveX Control

To use the embedded ActiveX control, you add <OBJECT> tags to your Web page HTML. The tag definition must include the RealPlayer classID value:

CLASSID="clsid:CFCDAA03-8BE4-11cf-B84B-0020AFBBCCFA"

It must also specify the width and height of the playback area. When you intend to use scripting with the control, you must also give a user-defined value for the ID parameter, such as ID=RVOCX. The syntax for a typical <OBJECT> tag looks like the following:

<OBJECT ID=RVOCX CLASSID="clsid:CFCDAA03-8BE4-11cf-B84B-0020AFBBCCFA"
WIDTH=300 HEIGHT=134>
...parameters...
</OBJECT>

This example tag creates a playback area 300 pixels wide by 134 pixels high within your Web page. Typically, your Web page will contain multiple <OBJECT> tags, each of which embeds a different RealOne Player control. You link all of these tags together using the CONSOLE parameter.

Between <OBJECT> and </OBJECT>, you can define any number of additional parameters using this syntax:

<PARAM NAME="name" VALUE="value">

PARAM, NAME, and VALUE markers can be any letter case, although this manual depicts them in uppercase. Except for file names, which are typically lowercase, parameter values are not case-sensitive. Always enclose parameter values in double quotation marks.

For More Information: For a list of all <OBJECT> parameters, see "Tag Parameters". The section on the SRC parameter contains information about linking your ActiveX control to your media. Available controls are described in "Embedded Controls".

Extending Embedded Controls Through VBScript

To extend RealPlayer's ActiveX functionality on Internet Explorer, you first embed the source file in an HTML page with the <OBJECT> tag:

<OBJECT ID=RVOCX CLASSID="clsid:CFCDAA03-8BE4-11cf-B84B-0020AFBBCCFA" WIDTH=220 HEIGHT=180>
<PARAM NAME="SRC" VALUE="rtsp://realserver.example.com/video1.rm">
<PARAM NAME="CONSOLE" VALUE="one">
<PARAM NAME="CONTROLS" VALUE="ImageWindow">
<PARAM NAME="BACKGROUNDCOLOR" VALUE="white">
<PARAM NAME="CENTER" VALUE="true">
</OBJECT>

In the <OBJECT> tag, the ID parameter identifies the embedded clip for reference by VBScript parameters. You can then use VBScript, or any programming language supported by the browser, to issue commands to control the embedded presentation. The following example shows a simple form that provides a Play, Pause, and Stop button for the embedded presentation:

<FORM>
<input TYPE="button" VALUE="Play" NAME="doplay">
  <script LANGUAGE="VBScript" FOR="doplay" EVENT="onClick">
  RVOCX.DoPlay
  </script>
<input TYPE="button" VALUE="Pause" NAME="pause">
  <script LANGUAGE="VBScript" FOR="pause" EVENT="onClick">
  RVOCX.DoPause
  </script>
<input TYPE="button" VALUE="Stop" NAME="stop">
  <script LANGUAGE="VBScript" FOR="stop" EVENT="onClick">
  RVOCX.DoStop
  </script>
</FORM>

View it now! (requirements for viewing this sample) This sample, which plays only in Internet Explorer, demonstates buttons linked through VBScript.

Receiving Callbacks Through VBScript

To receive callbacks through VBScript, you use the <OBJECT> tag ID, shown here set to RVOCX:

<OBJECT ID=RVOCX HEIGHT=256 WIDTH=256>
  CLASSID="clsid:CFCDAA03-8BE4-11cf-B84B-0020AFBBCCFA"
<PARAM NAME="controls" VALUE="all">
<PARAM NAME="SRC" VALUE="http://www.example.com/video1.rm">
</OBJECT>

You then use a <SCRIPT> tag to receive a VBScript callback. The following example shows a callback for OnShowStatus:

<P>
Status Text:
<input type="text" name="statusText" size=100><br>
</P>
<SCRIPT language="VBS">
Sub RVOCX_OnShowStatus(byVal text)
  statusText.Value=text
End Sub
</SCRIPT>

Tag Parameters

This section describes, in alphabetical order, the parameters that you can add to an <EMBED> or <OBJECT> tag. In an <EMBED> tag, parameters take the following form:

<EMBED SRC="..." WIDTH=... HEIGHT=... PARAMETER=value ... PARAMETER=value>

In an <OBJECT> tag, parameters take this form:

<OBJECT ID=... CLASSID="..." WIDTH=... HEIGHT=...>
<PARAM NAME="name" VALUE="value">
<PARAM NAME="name" VALUE="value">
...
</OBJECT>

AUTOGOTOURL

Specifies how to handle URLs embedded in a presentation.

When set to true, AUTOGOTOURL passes all URLs embedded in your presentation to the browser. When set to false, RealOne Player sends the URLs to a Java applet or other application through the OnGotoURL callback. If you do not include this parameter in your tag definition, and your presentation contains embedded URLs, the URLs are not passed to the browser.

Tip: Beginning with RealPlayer G2, you can also use the SetAutoGoToURL method to dynamically change how embedded URLs are handled at any time.

AUTOSTART

Specifies whether to automatically play a presentation

When set to true, AUTOSTART starts the clip playing as soon as the clip's preroll has been streamed. The viewer does not need to press a Play button. If multiple controls are linked together with the CONSOLE parameter, AUTOSTART needs to be set in just one control. With the default value of false, the presentation, the viewer must press a Play button to start the presentation.

Tip: If you are developing a Netscape plug-in in RealPlayer version 5.0 or later, you can also use the SetAutoStart method to dynamically control automatic playback at any time.

BACKGROUNDCOLOR

Sets the background color for the image window.

The background color is specified using an RGB hexadecimal color value (#RRGGBB) or a color name. When a clip includes transparent regions, the background color shows through these areas. If you do not include the BACKGROUNDCOLOR parameter in your tag definition, the background color for the image window is set to black (default). The following table lists the valid background color values:

Tip: You can also use the SetBackgroundColor method to dynamically change the background color of the image window at any time.

CENTER

Specifies whether the presentation should be centered in the image window and displayed in its original, encoded size.

When the CENTER parameter is set to true, the presentation is centered in the image window, and the height and width of the presentation are reset to the original dimensions (specified by the WIDTH and HEIGHT parameters when the embedded presentation was encoded). When CENTER is omitted or set to false, the presentation is not centered and the presentation expands to fill the image window.

Tip: You can also use the SetCenter method to dynamically center the presentation in the image window at any time.

Warning! The CENTER and MAINTAINASPECT parameters cannot both be set to true. In addition, the set methods for these parameters (SetCenter and SetMaintainAspect) cannot also both be true. When one parameter or set method is set to true, the other parameter and set method are considered to be false.

CLASSID

Identifies an ActiveX control as belonging to the RealPlayer class.

An embedded player ActiveX control must include the RealPlayer classID value in the <OBJECT> tag definition, and the value must be enclosed in double quotation marks:

<OBJECT ID=... CLASSID="clsid:CFCDAA03-8BE4-11cf-B84B-0020AFBBCCFA" ... >

If you do not include this parameter in your tag definition, or you specify an invalid value, the browser will not load your presentation and may issue an error message.

For More Information: For more information about creating an embedded presentation using an ActiveX control, see "Using the ActiveX Control".

CONSOLE

Specifies whether multiple controls should be linked together to manage playback of a single embedded presentation.

When there are multiple controls on the same page, a shared console name links the controls into a single embedded presentation. For example, if you have multiple Play and Stop buttons on the same page, a shared console name enables them to control the same presentation. The following valid console names are valid:

Tip: You can also use the SetConsole method to dynamically specify whether your controls are linked at any time.

You can have multiple console names for separate presentations. For a page showing two video clips, for example, you can define the console names video1 and video2. All controls linked by video1 interoperate, as do all controls linked by video2. But a video1 volume slider, for example, will not affect the volume of a video2 clip.

Tips for Using Consoles

• Every <EMBED> tag must have a SRC attribute. Tags linked by a console name should have the same SRC value.
• If the <EMBED> tags in a console group have different SRC values, the first valid source that RealOne Player finds among those choices becomes the console source. This may not always be the first source listed.
• Clicking a play button for one console stops playback for other consoles. This allows multiple consoles to play separate audio tracks or to use the same image window.

Multiple Controls Example

The following example sets up an image window and two sets of controls (a play button and stop button) for two separate videos, video1.rm and video2.rm. The predefined console name _master links the image window to both control sets. The control sets use different console names, however, so they do not link to each other. Clicking each play button therefore starts a different video.

Because each <EMBED> tag must have a SRC value, the image window in the following example uses the same source as the first play button. The viewer simply clicks either play button to start a video. Clicking the other play button stops the first video and plays the second one:

<EMBED SRC="video1.rpm" CONSOLE=_master WIDTH=176 HEIGHT=128 NOJAVA=true CONTROLS=ImageWindow>

<H4>Video 1</H4>
<EMBED SRC="video1.rpm" CONSOLE=video1 WIDTH=44 HEIGHT=26 NOJAVA=true CONTROLS=PlayButton> 
<EMBED SRC="video1.rpm" CONSOLE=video1 WIDTH=26 HEIGHT=26 NOJAVA=true CONTROLS=StopButton>

<H4>Video 2</H4>
<EMBED SRC="video2.rpm" CONSOLE=video2 WIDTH=44 HEIGHT=26 NOJAVA=true CONTROLS=PlayButton> 
<EMBED SRC="video2.rpm" CONSOLE=video2 WIDTH=26 HEIGHT=26 NOJAVA=true CONTROLS=StopButton>

View it now! (requirements for viewing this sample) This sample lets you play two videos linked to different controls, but displaying in the same image window.

CONTROLS

Embeds the specified RealPlayer control on your Web page.

The embedded player includes many controls that you can add to your Web page or application, including an image window, a full control panel, individual buttons, sliders, and status panels. For a complete listing of controls, see "Embedded Controls".

Tip: You can also use the SetControls method to dynamically add controls to your Web page at any time.

HEIGHT

Sets the height of the image window or a specified embedded control.

This parameter sets the height of the control in pixels, or as a percentage of the displayed browser window. Setting the WIDTH and HEIGHT parameters to zero causes the control to be hidden. If you do not include this parameter in your image window tag definition, the window may appear as a tiny icon because streaming media presentations do not size automatically.

Note: All embedded controls have a recommended width and height. For a complete listing of controls, see "Embedded Controls".

ID

Identifies the embedded presentation for reference by VBScript.

When you intend to use scripting to control your presentation, you must specify a unique value for the ID parameter, such as ID=RVOCX. After you have identified your presentation in an <OBJECT> tag:

<OBJECT ID=RVOCX CLASSID="clsid:CFCDAA03-8BE4-11cf-B84B-0020AFBBCCFA">
<PARAM NAME="SRC" VALUE="file:/presentation.rpm">
<PARAM NAME="CONTROLS" VALUE="ImageWindow">
...
</OBJECT>

you can use VBScript, or any programming language supported by the browser, to issue RealPlayer commands to control the presentation:

<FORM>
<input TYPE="button" VALUE="Play" NAME="doplay">
  <script LANGUAGE="VBScript" FOR="doplay" EVENT="onClick">
  RVOCX.DoPlay
  </script>
</FORM>

For More Information: For more information about creating an embedded presentation using an ActiveX control, see "Using the ActiveX Control".

IMAGESTATUS

Specifies whether the status information should be written along the bottom of the image window.

When set to true, or if the parameter is not included in the tag definition, the status information is written along the bottom of the image window. When set to false, the status information is not displayed.

Tip: You can also use the SetImageStatus method to dynamically change whether the status information is displayed at any time.

LOOP

Specifies whether playback of the clip should continue, or loop, indefinitely.

When set to true, playback of the clip continues to loop until the user stops the presentation. If multiple controls have been linked together using the CONSOLE parameter, LOOP needs to be be set to true in only one tag definition. When LOOP is set to false, or if the parameter is not included in the tag definition, then the presentation stops after the first playback.

Tip: You can also use the SetLoop method to dynamically change whether the clip should loop at any time.

MAINTAINASPECT

Specifies whether the height-to-width (aspect) ratio of the clip should stay constant when the clip scales to fit the image window.

If the MAINTAINASPECT parameter is set to true, the aspect ratio of the clip remains constant when the image window is resized. When this occurs, the clip is centered in the image window and scaled until one dimension reaches the window's boundaries and the other dimension is within the boundaries. If multiple controls have been linked together using the CONSOLE parameter, MAINTAINASPECT needs to be set to true in only one tag definition.

If the MAINTAINASPECT parameter is set to false, or if it is not included in the tag definition, the clip scales as necessary to allow it to fill the image window completely. When the dimensions of the clip are allowed to change in this manner, the source image may appear distorted.

Warning! The MAINTAINASPECT and CENTER parameters cannot both be set to true. In addition, the set methods for these parameters (SetMaintainAspect and SetCenter) also cannot both be true. When one parameter or set method is set to true, the other parameter and set method are considered to be false.

Tip: You can also use the SetMaintainAspect method to dynamically change whether the correct aspect ratio should be maintained at any time.

NAME

Specifies the name to associate with an embedded RealPlayer control, to enable Javascript to refer to the control.

To refer to an embedded control from Javascript, you must specify a name for the control in the NAME parameter in the <EMBED> tag definition. For example:

<EMBED NAME=my_name SRC="..." WIDTH=176 HEIGHT=132>

A Javascript command can then refer to the control like this:

<Input Type="button" Value="play" onClick="document.my_name.DoPlay()">

When using more than one instance of a single type of embedded control, or a variety of different embedded controls in your Web page, each instance must have a unique NAME value. Using different names for each instance ensures that you can use Javascript to manage each embedded control individually, if necessary.

Warning! In Netscape versions 4.x, you can only refer to named controls only when the NOJAVA parameter is not set to true. If NOJAVA=true is included in your <EMBED> tag, the browser's Java Virtual Machine (JVM) is prevented from starting if it is not yet running. Control referencing from Javascript may therefore be unavailable.

NOJAVA

Prevents the Java Virtual Machine (JVM) from starting if it is not yet running, making the use of Javascript impossible.

Setting NOJAVA=true in every tag linked by the same console name prevents the JVM from starting, if it is not yet running, thus prohibiting NAMED controls from being referenced using Javascript.

When NOJAVA is set to false, or if the parameter is not included in your control tag definition, the JVM is started and NAMED controls can be referenced from Javascript (default). However, because the other parameters described in this chapter do not require the JVM, and starting the JVM delays presentation playback, it is highly recommended that you specify NOJAVA=true in the tag definition for every control, if you do not intend to use scripting.

Note: Although you can specify NOJAVA in an ActiveX <OBJECT> tag or in a Netscape 6.0 plug-in, doing so has no effect because Internet Explorer and Netscape Navigator 6.0 launch the JVM on browser start-up.

NUMLOOP

Specifies the number of the times the presentation should loop during playback.

When the NUMLOOP parameter has been set to a number value, such as 2, the presentation loops (plays from beginning to end) the specified number of times and then stops. When you have multiple, linked controls, you need to set NUMLOOP in one tag only. If you do not include the NUMLOOP parameter in your tag definition (default), then the presentation only loops if the LOOP parameter has been specified.

Note: If both the NUMLOOP and LOOP parameters have been specified, or both of the set methods for these parameters (SetLoop and SetNumLoop) have been used, the LOOP parameter or method is ignored. This condition still applies even if NUMLOOP has been set to zero.

Tip: You can also use the SetNumLoop method to dynamically specify the number of times the presentation should loop at any time.

PARAM

Used to specify additional parameters in an ActiveX control <OBJECT> tag definition.

Additional parameters are specified through the PARAM parameter, using this syntax:

<PARAM NAME="name" VALUE="value">

The NAME variable can be assigned any of the parameters described in this chapter, except for the NAME parameter. (To specify a name for a control in your ActiveX control <OBJECT> tag defintion, use the ID parameter instead.) The VALUE variable should be assigned the appropriate value for the parameter specified in NAME.

For More Information: For more information about including additional parameters in your ActiveX control, see "Using the ActiveX Control".

PREFETCH

Enables or disables PREFETCH playback mode, which causes RealPlayer to get the stream description information from a presentation before playback begins.

By setting PREFETCH to true, you can obtain information about a presentation before it begins playing, and use that information to change playback characteristics. When an embedded player detects that prefetch playback mode is enabled, it obtains the the presentation's stream description information. After the information has been captured, OnPreFetchComplete is returned to the plug-in or control, and the presentation is paused.

For example, after the description information has been fetched, you could find out the size and width of an embedded clip using GetClipWidth and GetClipHeight. You could then dynamically create the <EMBED> or <OBJECT> tag for the image window using the clip's native size for the WIDTH and HEIGHT parameters.

Tip: You can also use the SetPreFetch method to dynamically specify whether prefetch playback mode is enabled at any time.

Note: SMIL 2.0 includes a <prefetch/> tag, which is unrelated to this PREFETCH parameter. The SMIL tag lets you download all or part of a clip's stream data before the clip plays, whereas the PREFETCH parameter obtains just the stream description. For more on SMIL prefetching, see the RealSystem iQ Production Guide.

REGION

Defines the ImageWindow control in which a specific clip from a SMIL presentation plays.

This parameter is for use only when you embed a SMIL presentation, and you want to play clips from the presentation in separate image windows on your Web page. This parameter is not necessary if you want to embed an entire SMIL presentation in a single image window. In this case, you just treat the SMIL presentation like a clip, embedding it in a single image window set to the same size (or larger) as the SMIL presentation's width and height, which is set in the SMIL file's <root-layout/> tag.

Clips in a SMIL presentation normally play in SMIL regions that are defined within the SMIL file header. When you embed the presentation's clips in different image windows, though, you omit the SMIL layout information. But you still include in the SMIL source tag for each visual clip a region attribute that ostensibly assigns the clip to a SMIL region. For example, a RealText clip included in a SMIL presentation might have a source tag that looks like this:

<textstream src="newsarticle.rt" region="article_region " .../>

To embed newsarticle.rt in a specific image window, you create the image window with CONTROLS=ImageWindow, and use the REGION parameter to identify the playback region. Here is an example using the Netscape plugin:

<EMBED SRC="http://realserver.example.com:8080/ramgen/newspaper.smil?embed"
           WIDTH=176 HEIGHT=132 NOJAVA=true CONTROLS=ImageWindow
             REGION=article_region>

The next example is for the ActiveX control:

<OBJECT ID=RVOCX CLASSID="clsid:CFCDAA03-8BE4-11cf-B84B-0020AFBBCCFA"
            WIDTH=176 HEIGHT=132>
<PARAM NAME="SRC"
           VALUE="http://realserver.example.com:8080/ramgen/newspaper.smil">
<PARAM NAME="CONTROLS" VALUE="ImageWindow">
<PARAM NAME="REGION" VALUE="article_region">
</OBJECT>

You can define similar <EMBED> or <OBJECT> tags to create other regions for other clips in the SMIL file. In this case, each <EMBED> tag lists the same SMIL file in the SRC parameter.

For More Information: For more information on SMIL, see the latest RealSystem iQ Production Guide. That guide's Web page embedding chapter contains more information on this topic, and includes sample files of embedded SMIL presentations.

SCRIPTCALLBACKS

Specifies the callback events to handle in a comma-separated list.

The SCRIPTCALLBACKS parameter can be used by Netscape version 6.0 plug-ins to specify the set of callback events you would like to capture and handle. The events are assigned to the parameter via a comma separated list, such as:

SCRIPTCALLBACKS=OnPresentationOpened,OnPresentationClosed

You can include any of the callbacks described in Chapter 7 in the list, or you can specify All to capture all events.

For More Information: For more information about setting up event handling in your Netscape plug-in, see "Handling Events in Netscape Navigator 6".

SHUFFLE

Specifies whether all unplayed clips in a presentation, should be played back in a random order

When the SHUFFLE parameter is set to true, all unplayed clips in a presentation are played back in a random order, rather than in the order in which they appear in the file. This parameter can be used with multiclip RAM files (.ram or .rpm), or with SMIL files that contain only a sequence of clips. When SHUFFLE is set to false, or if you do not include the parameter in your tag definition, the clips are played back in the order in which they appear in the multiclip file.

Tip: You can also use the SetShuffle method to dynamically specify whether clip playback should be randomized at any time.

SRC

Specifies the URL of the .rpm file or presentation to be played.

The URL can begin with rtsp://, http://, pnm://, or file://, and the entire URL string must be enclosed in double quotation marks. Any directories or files specified in the URL cannot contain spaces in their names, that is, they need to be properly URL encoded. For example, use %20 for a space character.

Using the TYPE Parameter

The SRC parameter may be omitted from the tag definition when the content mime TYPE parameter is specified similar to:

<EMBED WIDTH=176 HEIGHT=132 TYPE="audio/x-pn-realaudio-plugin">

However, doing this may produce unexpected results. Therefore, it is strongly recommended that you always include the SRC parameter and, minimally, supply the name of an empty presentation file.

Tip: You can also use the SetSource method to dynamically specify the URL of the presentation at any time.

Specifying a Source With the Netscape Plugin

You must include the SRC parameter in every <EMBED> tag, even when the tag embeds a RealOne Player control, such as a Play button, instead of a clip. However, you don't specify a clip or SMIL file directly with SRC. Instead, you specify a Ram file that has a .rpm extension:

<EMBED SRC="http://www.example.com/presentation.rpm" WIDTH=176 HEIGHT=132>

The .rpm extension causes the browser to use RealOne Player as a helper application, rather than to launch it as a separate application. The .rpm file is a simple text file that gives the full URL to your clip or SMIL file:

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

For More Information: For full information about the Ram file syntax, see the presentation delivery chapter of the RealSystem iQ Production Guide.

Developing Your Presentation

The easiest means for developing your embedded presentation is to keep your clips in the same folder as your Web page on your desktop computer. Your <EMBED> tag can then link to a .rpm file in that folder:

<EMBED SRC="presentation.rpm" WIDTH=300 HEIGHT=134>

To embed a single video, for example, the .rpm file simply contains a local file URL to the clip (the file:// protocol designation is required):

file://video.rm

Warning! For embedded playback to work with Netscape Navigator 6, the path to the .rpm file on a server or your local computer cannot contain spaces or even escape codes for spaces (%20). This causes Navigator 6 to search for a missing plug-in.

Delivering Your Presentation

When you are ready to deliver your presentation to your audience, move your files to their respective servers and change the URLs in your files:

• Keeping the .rpm File and the Web Page Together

If you plan to keep the .rpm file with the Web page, you do not need to change the SRC values in your <EMBED> tags. You can simply transfer your .rpm file and your Web page to the same directory on your Web server.

• Putting the .rpm File and the Web Page in Different Locations

If you move the .rpm file to a different directory than that Web page, link each <EMBED> tag's SRC parameter to the .rpm file with a full HTTP URL:

SRC="http://www.example.com/media/presentation.rpm"

• Linking to Streaming Clips

No matter where you put your .rpm file and your clips, modify the .rpm file to give the fully-qualified URL to the embedded clip or SMIL file. If the clip or SMIL file is on a Web server, use an HTTP URL. If the clip or SMIL file is on RealSystem Server, use an RTSP URL.

Tip: Always use a full URL in the .rpm file, even if all files and clips are in the same directory on a Web server. RealOne Player uses the .rpm file to locate the clip or presentation. Without a fully-qualified URL, RealOne Player must construct the location from the original Web page URL and the information in the .rpm file. This creates more possibility for errors.

For More Information: For more information about the RTSP protocol, as well as the RealServer Ramgen feature, which lets you eliminate the .rpm file, see the presentation delivery chapter of RealSystem iQ Production Guide.

• Linking to Local Clips

If you will make your presentation available to people on their local machines (through a download or a CD, for instance), you do not need to change any URLs from those described in "Developing Your Presentation". In rare cases, though, you may want to use an absolute link, rather than a relative link, in the .rpm file. When using absolute links, use forward slashes in paths to create "Web style" paths. For example, instead of this URL:

file://c:\media\presentation.rpm

use this URL:

file://c:/media/presentation.rpm

Specifying a Source with ActiveX

For the ActiveX control, the <OBJECT> tag's CLASSID parameter causes the presentation to play in the Web page, so you can simply link to the SMIL file or clip within a single <OBJECT> tag. It is not necessary to use a Ram file with the .rpm extension:

<OBJECT ID=RVOCX CLASSID="clsid:CFCDAA03-8BE4-11cf-B84B-0020AFBBCCFA"...>
<PARAM NAME="SRC" VALUE="rtsp://realserver.example.com/video1.rm">
...
</OBJECT>

TYPE

Identifies the MIME type of the presentation specifed in the SRC parameter.

The typical syntax for the MIME type looks like the following:

<EMBED SRC="http://.../.../presentation.rpm" WIDTH=176 HEIGHT=132 
TYPE="audio/x-pn-realaudio-plugin">

The browser first reads the MIME type value, then embeds the appropriate plug-in for the presentation. If you do not include this parameter in your tag definition, the browser may not load the ideal plug-in for your presentation.

Note: When the TYPE parameter is specified, the SRC parameter may be omitted from the tag definition. However, doing so may produce unexpected results. Therefore, it is strongly recommended that you always include the SRC parameter and, minimally, supply the name of an empty presentation file.

WIDTH

Sets the width of the image window or a specified embedded control.

Setting the HEIGHT and WIDTH parameters to zero causes the control to be hidden. If you do not include this parameter in your image window tag definition, the window may appear as a tiny icon because streaming media presentations do not size automatically.

Note: All embedded controls have a recommended width and height. For a complete listing of controls, see "Embedded Controls".

Embedded Controls

With the CONTROLS parameter, you can add controls such as a play/pause button to your Web page. Viewers can then control playback as if they were using RealOne Player as a separate application. For example, the following tag displays the play/pause button in your Web page using an <EMBED> tag:

<EMBED SRC="presentation.rpm" WIDTH=26 HEIGHT=26 NOJAVA=true CONTROLS=PlayButton CONSOLE="one">

For the ActiveX control, the <OBJECT> tag would look like this:

<OBJECT ID=RVOCX CLASSID="clsid:CFCDAA03-8BE4-11cf-B84B-0020AFBBCCFA"
WIDTH=26 HEIGHT=26>
<PARAM NAME="CONTROLS" VALUE="PlayButton">
<PARAM NAME="CONSOLE" VALUE="one">
</OBJECT>

Note: When adding more than one control to your Web page, link the controls together with the CONSOLE parameter.

The following sections list and describe the embedded controls in alphabetical order by control name. You use an <EMBED> or <OBJECT> tag's WIDTH and HEIGHT parameters to set the control's size. Specifying different pixel sizes other than the suggested values scales the controls larger or smaller. You can also use percentage values for sizes, but this is recommended only for the image window.

Tip: Unless noted otherwise, all the RealOne Player controls listed below are compatible with RealPlayer G2, RealPlayer 7, and RealPlayer 8. With those versions of RealPlayer, however, the controls take on a different appearance.

View it now! (requirements for viewing this sample) Play this sample to view all the embedded controls using just <EMBED> tags. The next sample displays all of the embedded controls using combined <OBJECT> and <EMBED> tags.

All

The CONTROLS=All parameter displays the basic RealOne Player control panel. The control name "default" also works. Functions include play/pause, stop, fast-forward, and rewind. Sliders include a position slider and a volume slider with a mute button that pops up when the speaker button is clicked. Below the buttons are a clip information field, a status panel, a network congestion indicator, and a clip timing field.

If you set the size of this control panel to less than the recommended width or height, the panel drops certain controls instead of squeezing all of the controls down to a smaller size. This lets you add the control panel to small pop-up windows, for example, without the controls becoming difficult to use. This works for RealOne Player, but not earlier versions of RealPlayer.

View it now! (requirements for viewing this sample) This sample lets you see the full control panel at different sizes.

ControlPanel

Use CONTROLS=ControlPanel to display a compact RealOne Player control panel. Functions include play/pause, stop, fast-forward and rewind. There's also a position slider, along with a volume slider and mute button that pops up when the speaker button is clicked.

If you set the size of this control to less than the recommended width, the panel drops certain buttons instead of squeezing all of the buttons down to a smaller size. This works for RealOne Player, but not earlier versions of RealPlayer.

View it now! (requirements for viewing this sample) This sample lets you see this control panel at smaller sizes.

FFCtrl

The CONTROLS=FFCtrl parameter displays a fast-forward button.

HomeCtrl

The CONTROLS=HomeCtrl parameter displays the RealOne Player logo, which is linked to the RealNetworks Web site. In earlier versions of RealPlayer, this control displays the Real™ logo.

ImageWindow

The CONTROLS=ImageWindow parameter displays a playback window. This control is not required for audio-only presentations. Even if no other controls are visible on the page, the user can typically right-click (on Windows) or hold down the mouse button (on the Macintosh) in the playback area to display a menu of choices such as Play and Stop.

InfoPanel

The CONTROLS=InfoPanel parameter displays the presentation information panel. For more on presentation information, see the RealSystem iQ Production Guide.

InfoVolumePanel

Use CONTROLS=InfoVolumePanel to display presentation information along with the volume slider and mute button. For more on presentation information, see the RealSystem iQ Production Guide.

MuteCtrl

The CONTROLS=MuteCtrl parameter displays a mute button.

MuteVolume

The CONTROLS=MuteVolume parameter displays a mute button and volume slider.

PauseButton

The CONTROLS=PauseButton parameter displays a pause button. Because the PlayButton control turns into a pause button as a presentation plays, the PauseButton control is generally not necessary with the RealOne Player. To ensure backwards compatibility with earlier versions of RealPlayer, however, use both the PlayOnlyButton and the PauseButton controls.

PlayButton (also PlayOnlyButton)

The CONTROLS=PlayButton parameter displays a play button. This turns into a pause button when the presentation plays. If your presentation is accessible to RealPlayers earlier than the RealOne Player, use CONTROLS=PlayOnlyButton instead. In earlier RealPlayers, the PlayButton control includes both play and pause buttons, whereas the PlayOnlyButton control includes just the play button as shown here. Using PlayOnlyButton therefore ensures backwards compatibility.

PositionField

The CONTROLS=PositionField parameter displays the position field, which shows the clip's current place in the presentation timeline, along with the total clip length.

PositionSlider

The CONTROLS=PositionSlider parameter displays a clip position slider.

RWCtrl

The CONTROLS=RWCtrl parameter displays a rewind button.

StatusBar

The CONTROLS=StatusBar parameter displays the status panel, which shows informational messages. It also includes the network congestion LED and the position field, which shows the clip's current place in the presentation timeline, along with the total clip length.

If you set the width of the status bar lower than the recommended width, the panel drops fields instead of squeezing all of the fields down to a smaller size. This works for RealOne Player, but not earlier versions of RealPlayer.

View it now! (requirements for viewing this sample) This sample lets you see the status bar at smaller sizes.

Note: The status bar is included in the All control. If you do not embed a status bar or status field in your page, error messages display in the browser's status bar.

StatusField

The CONTROLS=StatusField parameter displays the message text area of the status bar. If you do not embed a status field or status bar in your page, error messages display in the browser's status bar.

StopButton

The CONTROLS=StopButton parameter displays a stop button.

TACCtrl

The CONTROLS=TACCtrl parameter displays an information field. Clip or presentation information scrolls vertically through this field when the clip first plays. The viewer can redisplay this information by clicking the arrow button. Clicking the "i" button displays the full presentation information in a pop-up window. With RealOne Player, if you set the width of the TACCtrl to less than 220 pixels, the Clip Info field is dropped.

For More Information: For instructions on defining clip or presentation information, see the RealSystem iQ Production Guide.

View it now! (requirements for viewing this sample) This sample lets you see this information field at a smaller size.

VolumeSlider

The CONTROLS=VolumeSlider parameter displays a volume slider.

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