Appendix C: Tag Parameters

This appendix identifies the parameters that can be included in the tag definition of your RealPlayer Netscape plug-in or ActiveX control.

Using Netscape Plug-in <EMBED> Tag Parameters

You can include parameters in a Netscape plug-in <EMBED> tag definition using this syntax:

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

and by following these guidelines:

• Parameter names can be any case,
  although this manual depicts them in uppercase.
• Parameter values are not case-sensitive, however,
  file names are typically lowercase.
• Parameter values do not need to be enclosed in quotation marks,
  except when the value is a URL.

Using ActiveX Control <OBJECT> Tag Parameters

You can include parameters in an ActiveX control <OBJECT> tag definition using this syntax:

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

and by following these guidelines:

• The PARAM, NAME, and VALUE markers can be any case.
• Parameter names can be any case,
  although this manual depicts them in uppercase.
• Parameter values are not case-sensitive, however,
  file names are typically lowercase.
• Parameter values must always be enclosed in double quotation marks.

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, RealPlayer sends the URLs to a Java applet or other application via the OnGotoURL callback.

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

If you do not include this parameter in your tag definition and your presentation contains embedded URLs, then the URLs are not passed to the browser (default).

AUTOSTART

Specifies whether to automatically play a presentation.

When set to true, AUTOSTART instructs the Embedded RealPlayer to automatically begin playing the presentation once the source content is available. If multiple controls have been linked together using the CONSOLE parameter, AUTOSTART can be set to true in one or more tag definitions. When set to false, the presentation is not automatically played back.

For More Information: 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.

If you do not include this parameter in your tag definition, then your presentation will not automatically start (default).

BACKGROUNDCOLOR

Sets the background color for the image window. When a clip includes transparent regions, the background color also shows through these areas.

The background color is specified using an RGB hexadecimal color value (#RRGGBB) or a color name. The following table lists the valid background color values:

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

If you do not include the BACKGROUNDCOLOR parameter in your tag definition, the background color for the image window is set to black (default).

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 set to false, the presentation is not centered and the height and width of the presentation are allowed to expand and fill the image window.

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

If you do not include the CENTER parameter in your tag definition, then the presentation is not centered or resized to its original dimensions (default).

Warning! The CENTER and MAINTAINASPECT parameters cannot both be set to true. In addition, the set methods for these parameters (SetCenter and SetMaintainAspect) 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.

CLASSID

Identifies an ActiveX control as belonging to the RealPlayer class.

An Embedded RealPlayer 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 <OBJECT> Tags for the ActiveX Control".

CONSOLE

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

When the same console name is specified for multiple control on a Web page, this parameter can be used to enable these controls to manage playback of 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 clip. The following table lists the valid console name values:

For More Information: You can also use the SetConsole method to dynamically specify whether your controls are linked at any time. For more information about linking multiple controls, see the RealSystem Production Guide.

If you do not include this parameter in your tag definition, then the console name of the control is considered to be _unique (default).

CONTROLS

Embeds the specified RealPlayer control on your Web page.

For a complete listing of valid control name values, see "Appendix D: RealPlayer Controls".

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

If you do not include this parameter in your tag definition, then the basic RealPlayer control panel is added to your Web page (default - All).

HEIGHT

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

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.

ID

Identifies the embedded presentation for referencing in 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 your presentation has been identified in an <OBJECT> tag similar to the following:

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

you can then 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 <OBJECT> Tags for 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, then the status information is written along the bottom of the image window (default). When set to false, the status information is not displayed.

For More Information: 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 can be set to true in one or more tag definitions.

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

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 (default).

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 can be set to true in one or more tag definitions.

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

If the MAINTAINASPECT parameter is set to false, or if it is not included in the tag definition, then the dimensions of the clip scale as necessary to allow the clip to completely fill the image window (default). 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.

NAME

Specifies the name to associate with an embedded RealPlayer control, to enable the control to be referenced using JavaScript.

In order to refer to an embedded RealPlayer 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>

The control can then be referenced by a JavaScript command, such as the following:

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

If you are using more than one instance of a single type of embedded control or a variety of different embedded controls in your Web page, then each instance must have a unique NAME. 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 reference named controls from JavaScript, 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, and control referencing from JavaScript is not available.

NOJAVA

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

Setting NOJAVA=true 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, when 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.

NOLABELS

Specifies whether the title, author, and copyright information for a presentation should be displayed in RealPlayer. This parameter is obsolete and should only be used to provide backward compatibility with RealPlayer 5.

When the NOLABELS parameter is set to true, the title, author, and copyright information is not displayed. When NOLABELS is set to false, or if you do not include the parameter in your tag definition, the presentation information is displayed in RealPlayer (default).

For More Information: You can also use the SetNoLabels method to dynamically specify whether the presentation information should be displayed at any time.

NOLOGO

Specifies whether the RealNetworks logo should be displayed in the image window when no clip is playing.

When the NOLOGO parameter is set to true, the RealNetworks logo is not displayed in the image window when no clip is playing. The image window then defaults to black unless a BACKGROUNDCOLOR has been specified.

For More Information: You can also use the SetNoLogo method to dynamically specify whether the logo should be displayed at any time.

When NOLOGO is set to false, or if you do not include the parameter in your tag definition, the RealNetworks logo is displayed in the image window when no clip is playing (default).

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.

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

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.

Warning! 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 / method is ignored. This condition still applies even if NUMLOOP has been set to zero.

PARAM

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

Additional parameters are specified via 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 ActiveX Control <OBJECT> Tag Parameters".

PREFETCH

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

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

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.

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

When PREFETCH is set to false, or if you do not include the parameter in your tag definition, then prefetch playback mode is disabled (default).

REGION

Defines the Web page playback region for a SMIL clip.

Clips listed in a SMIL file include specifications in their tags, which indicate where the clip should be played back in a Web page. For example, if the newsarticle.rt file should be displayed in the article playback region of a newspaper Web page, it is listed in the newspaper.smil file as:

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

In order to view newsarticle.rt on the newspaper Web page, an image window control has to be created and it's playback region has to be set to article using the REGION parameter using a Netscape plug-in:

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

or an 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">
</OBJECT>

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

Warning! When the layout of a presentation is defined using HTML, the <layout> section of the SMIL file header must be omitted.

SCRIPTCALLBACKS

Specifies the callback events to handle via 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>

Any of the callbacks described in Appendix B can be included 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 Version 6.0".

SHUFFLE

Specifies whether all unplayed clips in a presentation, should be played back in a random order. This parameter can be used for multiclip RAM files (.ram or .rpm) or SMIL files that contain only a sequence of clips.

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.

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

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 RAM file or SMIL file (default).

SRC

Specifies the URL of the 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. The URL source content is specified such as:

<EMBED SRC="http://.../.../my_content.rpm" WIDTH=176 HEIGHT=132>

Any directories or file specified in the URL cannot contain spaces in their names.

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

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 so may produce unexpected results. Therefore, it is strongly recommended that you always include the SRC parameter and at least supply the name of an empty presentation file.

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://.../.../my_content.rpm" WIDTH=176 HEIGHT=132
             TYPE="audio/x-pn-realaudio-plugin">

The browser reads the MIME type value and 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.

Tip: 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 at least 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.

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