previous next

Chapter 5: Embedded Method Overviews

The embedded RealOne Player contains methods that control the playback of embedded presentations. This chapter introduces these method by category, describing how you can use groups of related methods to enhance embedded presentations.

View it now! (requirements for viewing this sample)
The Javascript samples and VBScript samples in this guide demonstrate the methods described in this chapter.

Controlling Playback

The following methods let you play, pause, and stop the clip using your own controls, as well as determine a clip's playback status:

If you want to supply your own play, pause, and stop controls instead of using the built-in controls, use the DoPlay, DoPause, and DoStop playback methods. The following example shows one simple way to add your own controls: 

<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()">

These methods can also determine the playback status of the clip. The CanPlay, CanPause, and CanStop playback methods indicate whether the clip can be played, paused, or stopped. For example, if CanPlay returns true, the clip is either paused or stopped, and is ready to play. If CanPlay returns false, the clip is already playing, and is not ready to begin playing again.

View it now! (requirements for viewing this sample)
Click this sample for a simple embedding demonstration using Javascript. Click this sample for a simple embedding demonstration using VBScript. Click this sample for a demonstration of embedded player controls using Javascript. Click this sample for a demonstration of embedded player controls using VBScript.

Obtaining Play State Information

The following methods get the presentation's current play state, or determine the elapsed and remaining buffering times of a presentation:

GetPlayState returns an integer that indicates the current state of RealOne Player. The possible play states denoted by the returned integer include the following:

Knowledge of the current presentation state can be very useful. For example, you could disable the image status text written along the bottom of the image window, and replace it with the current presentation state in a custom display panel.

Note: The image status text appears along the bottom of the image window only when no other control, such as a status panel or status field, is available to display the status text.

Like the information returned from GetPlayState, the information displayed along the bottom of the image window indicates whether the playback is contacting, buffering, and so on. To disable this text, set the SetImageStatus method's parameter to false. To determine whether the status text is currently enabled or disabled, use the GetImageStatus method.

Another possibility is determining the amount of time that has elapsed since buffering began for a requested presentation. After the embedded player has contacted the host for the requested presentation, the player buffers the content to provide smooth playback. You can obtain the elapsed time using the GetBufferingTimeElapsed method, or determine the amount of buffering time remaining using the GetBufferingTimeRemaining method.

View it now! (requirements for viewing this sample)
Click this sample to obtain play state information using Javascript. Click this sample to obtain play state information using VBScript.

Specifying Control Attributes

Several methods allow you to get or set the current state of the embedded controls on your Web page. They supply information about the current state of the embedded controls, along with a means of dynamically changing the controls' states. You can also use these methods in programming languages such as C++.

The set methods allow you to change the attributes of the embedded player. Many of these methods mirror the the <EMBED> or <OBJECT> tag parameters, and can dynamically change the state of an embedded control. For example, you can use SetBackgroundColor to alter the BACKGROUNDCOLOR parameter of the <EMBED> or <OBJECT> tag, changing the ImageWindow background color dynamically.

The following are the methods associated with parameters (listed in parentheses) used with the <EMBED> or <OBJECT> tag:

Additional methods let you get the current state of the attributes of the embedded player. For example, GetBackgroundColor returns a hexadecimal value for the current background color:

Seeking Through a Clip

The embedded player provides several methods that obtain information about the currently-playing clip. This includes determining the present clip position, total length, and whether one can seek through the presentation:

During playback, use GetCanSeek to verify whether you can seek through the clip. If the method returns true, you can use GetLength and GetPosition to obtain the clip length (total milliseconds) and current position (milliseconds already played). You can use the value returned from GetLength to ensure that the value used with SetPosition does not exceed the total clip length.

You can also use SetCanSeek when GetCanSeek returns true. This method allows you to specify whether the viewer can seek through the clip. However, if you attempt to use SetCanSeek to allow seeking through an inherently unsearchable clip, such as a live broadcast, the set method has no affect.

View it now! (requirements for viewing this sample)
Click this sample to seek through a clip using Javascript. Click this sample to seek through a clip using VBScript.

Accessing Clip Title, Author, and Copyright Information

The following methods allow you to get or set a clip's title, author, and copyright information:

When title, author, and copyright information has been encoded in a clip, use GetTitle, GetAuthor, and GetCopyright to retrieve the information. In multiclip presentations, these methods return the information associated with the currently-playing clip.

The SetTitle, SetAuthor, and SetCopyright methods dynamically change whether the title, author, and copyright information displays for a clip. Normally, this information displays when the viewer clicks the "i" button on an embedded control panel. In multi-clip presentations, these methods override the clip information for the entire presentation, not just the currently-playing clip. These methods are useful for multiclip presentations in which you want to supply a title, author, and copyright information for the entire presentation.

View it now! (requirements for viewing this sample)
Click this sample to change title, author, and copyright information using Javascript. Click this sample to change title, author, and copyright information using VBScript.

Directing a Playlist in a Multi-clip Presentation

Multi-clip presentations are made up of playlists that contain useful information about each of the clips. You can use the following methods to move from clip to clip in the playlist, or acquire content information about any clip in the presentation:

To get the number of entries in the playlist, use GetNumEntries. In this method, a single entry is always returned as the number 1. You can also retrieve the entry number of the clip that is currently playing using GetCurrentEntry. Note, however, that this method begins counting at zero, the third entry in a playlist therefore returns the number 2. While playing a multi-clip presentation, use HasNextEntry to determine if there is another entry in the playlist. You can then use DoNextEntry to jump to the next clip. Use HasPrevEntry to determine if a previous entry exists in the playlist. If so, you can use DoPrevEntry to jump back to the beginning of the previous clip.

After you have determined the number of entries in a playlist, you can use GetEntryAbstract, GetEntryAuthor, GetEntryCopyright, and GetEntryTitle to retrieve the abstract, author, copyright, and title information for any clip in the presentation. Simply supply the number of the playlist entry for which you want information as the parameter for these methods. These methods return a string that contains the information for the specified entry.

View it now! (requirements for viewing this sample)
Click this sample to move about entries in a multi-clip presentation using Javascript. Click this sample to move about entries in a multi-clip presentation using VBScript.

Determining Live Broadcast

The GetLiveState method indicates whether the current stream is live. This information is useful, for instance, if you want to know whether to use the clip positioning methods. If GetLiveState returns true, the current stream is part of a live presentation, and you cannot use the clip positioning methods.

View it now! (requirements for viewing this sample)
Click this sample to determine live broadcasts using Javascript. Click this sample to determine live broadcasts using VBScript.

Display User Interface Dialogs

RealOne Player contains several menus and dialogs that let the viewer set various player preferences, view the playback statistics, and view information about the player. The following methods can set RealOne Player preferences, as well as view player information and statistics:

You can access preferences using SetShowPreferences. Setting this method's parameter to true brings up an abbreviated version of the RealOne Player Preferences dialog box. To determine if this dialog box is already displayed, use GetShowPreferences, which returns true if the dialog box is already displayed.

Use SetShowStatistics to view playback statistics. Setting this methods's parameter to true brings up the standard RealOne Player statistics dialog box. To determine if this dialog box is already displayed, use GetShowStatistics, which returns true when the statistics dialog box is displayed.

RealOne Player's "about" dialog box contains information about the player version and the individual player components. To view this dialog, set the SetShowAbout parameter to true. To determine if this dialog box is already being displayed, use the GetShowAbout method. If this method returns true, the dialog is already displayed.

View it now! (requirements for viewing this sample)
Click this sample to view RealOne Player dialog boxes using Javascript. Click this sample to view RealOne Player dialog boxes using VBScript.

Error Handling

You can designate whether or not the RealOne Player embedded in your Web page displays error dialogs by using the following methods:

If the SetWantErrors method is set to true, error messages from the player are trapped, and not displayed in an error dialog box. If SetWantErrors is set to false, error messages are displayed in an error dialog box. You can use the GetWantErrors method to determine if error messages are being trapped. If GetWantErrors returns true, error messages are being trapped. If GetWantErrors returns true, error message will be displayed when they occur.

When a player error occurs, the GetLastErrorMoreInfoURL method supplies a URL that can provide more information than is provided by the standard error string. If no URL is available to supply more information, this method returns nothing.

The GetLastErrorRMACode method returns a value that represents the error code returned by RealOne Player. The values of the error codes and their descriptions can be found in the RealSystem SDK rmaerror.h file and in the RealSystem SDK Developer's Guide.

Other RealOne Player error methods include GetLastErrorSeverity, which responds with the severity of the error, and GetLastStatus, which responds with the text of the last status message returned by the OnShowStatus callback.

Also included are two user-defined error methods: GetLastErrorUserCode and GetLastErrorUserString. The GetLastErrorUserCode returns a user-defined error code, and GetLastErrorUserString returns a user-defined string that describes the last error that occurred. If you have designed a custom plug-in for RealOne Player, you can use both of these methods to return your own error codes and error strings for your plug-in. If you are not providing a custom plug-in for RealOne Player, both of these methods return nothing.

View it now! (requirements for viewing this sample)
Click this sample to view RealOne Player error handlers using Javascript. Click this sample to view RealOne Player error handlers using VBScript.

Setting the Display Size

You can change the size of the image window on your Web page to either the original size you specified in the <EMBED> or <OBJECT> tag, or to full screen with the following methods:

To set the image window to full screen, use the SetFullScreen method with its parameter set to true. To determine if the image window is set to full screen, use the GetFullScreen method. If this method returns true, the image window is set to full screen.

To set an image window to the original size specified in the <EMBED> or <OBJECT> tag on your Web page, use the SetOriginalSize method with its parameter set to true. To determine if the image window is currently set to its original size, use the GetOriginalSize method. If this method returns true, the image window is set to its original size.

View it now! (requirements for viewing this sample)
Click this sample to change the display size using Javascript. Click this sample to change the display size using VBScript.

Controlling Audio

Using the following methods, you can embed various audio controls in your Web page to get and set the volume of the presentation, mute the presentation, and determine if the presentation is being played in stereo or monaural:

To set the volume of the presentation, use SetVolume. The parameter you enter for this method is a percentage of the total volume. That is, if you want the volume to be set to 50%, use the number 50 as this method's parameter. To determine the current volume of the presentation, use the GetVolume method. This method returns the current volume setting as a percentage of the total volume.

To mute the presentation, use the SetMute method. Set this method's parameter to true to mute the presentation, and false to return the sound volume to its previous level. To determine if the presentation is currently muted, use the GetMute method. This method returns true if the presentation is muted and false if it is not.

To determine if the current presentation is stereo or monaural, use the GetStereoState method. This method returns true if the presentation is stereo, and false if the presentation is monaural.

View it now! (requirements for viewing this sample)
Click this sample to observe and change audio settings using Javascript. Click this sample to observe and change audio settings using VBScript.

Getting Network Information

Using the following methods, you can obtain information to determine how your embedded presentation reacts to the user's network capabilities.

Two methods provide playback bandwidth information from the user's RealOne Player. The first, GetBandwidthAverage, returns the average playback bandwidth of the user's RealOne Player, in bits per second, from the beginning of playback to the time when this method is called. The second, GetBandwidthCurrent, returns the current playback bandwidth in bits per second.

The GetNumSources method returns the number of sources in the presentation, where a source is a piece of media or an entry in a playlist or .rpm file.

Several methods are provided that let your Web page monitor the network activity of the user's RealOne Player. GetPacketsReceived indicates the total number of packets that the player received correctly from the RealSystem Server, and GetPacketsTotal indicates the total number of packets that should have been received by the player up to the point at which this method was called, including the packets that were lost. If no packets were lost, GetPacketsTotal returns the same number as GetPacketsReceived.

You can also monitor how well the user's RealOne Player is receiving packets:

Obtaining RealOne Player Version Information

The GetVersionInfo method returns the version of the RealOne Player plug-in running on the user's machine (in period-delineated form, such as "6.0.7.788", which is the embedded RealPlayer build for RealPlayer 8). With this information, your Web page can provide different options for different versions of the player.

The following table lists the equivalent RealPlayer releases, stand-alone builds, and embedded player builds. Use this information to differentiate between versions.

Version Compatibility Table
Release Version Standalone Build Number Embedded Player Build Number
8 Update 3 6.09.584 6.0.8.1024
8 Update 2 6.0.9.450 6.0.7.881
8 Gold 6.0.9.357 6.0.7.788
7 Update 1 6.0.8.122 6.0.7.529
7 Gold 6.0.7.380 6.0.7.407
G2 Update 3 6.0.6.99 6.0.6.98
G2 Update 2 6.0.6.33 6.0.6.33
G2 Update 1 6.0.5.27 6.0.5.27
G2 Gold 6.0.3.128 6.0.6.131

Note: If you use JavaScript to get the version information, the GetVersionInfo may not function on some versions of Internet Explorer 5. In this case, use VBScript to ensure the GetVersionInfo method functions properly.

View it now! (requirements for viewing this sample)
Click this sample to get RealPlayer version information using Javascript. Click this sample to get version information using VBScript.

Event Handling

RealOne Player includes methods for enabling or disabling keyboard and mouse events on your Web page. Also included is a method that can be used in plug-ins to make event handling act more like event handling in ActiveX controls:

Available Methods

The SetWantKeyboardEvents method sets whether or not keyboard events are returned from the user's RealOne Player. If SetWantKeyboardEvents is set to true, the keyboard event callbacks, OnKeyDown, OnKeyPress, and OnKeyUp, are sent from RealOne Player when a keyboard event occurs. If this method is set to false, keyboard events are not sent. You can use the GetWantKeyboardEvents method to determine if keyboard events have been requested from the user's RealOne Player.

The SetWantMouseEvents method works in much the same way. If SetWantMouseEvents is set to true, the mouse event callbacks, OnLButtonDown, OnLButtonUp, OnMouseMove, OnRButtonDown, and OnRButtonUp, are sent from RealOne Player when a mouse event occurs. If this method is set to false, mouse events are not sent. You can use the GetWantMouseEvents method to determine if mouse events have been requested from the user's RealOne Player.

The SetConsoleEvents method is provided to let plug-in designers make their plug-ins behave more like the ActiveX control. By setting the value parameter of the SetConsoleEvents method to false, only the plug-in to which the console connects will send events.

How Event Handling Works

In ActiveX, you specify the particular ActiveX control for which your function is handling events. Thus any event that occurs in reference to a specific ActiveX control is always handled only by that single control.

If, however, you are using multiple plug-ins on a page and an event occurs on that page, a Java applet cannot determine from which plug-in the event was sent. (Although you could add multiple Java applets to the page to handle each individual plug-in, in general all events for all plug-ins that share the same console name are sent to a single applet.) For example, if you have two plug-ins on a page and generate a mouse or button event in either of the plug- ins, the event goes to the applet, but the applet cannot determine which plug- in generated the event.

You can use the GetConsoleEvents method to determine whether console events are enabled. If GetConsoleEvents is true, then console events are enabled and events from any applet will be sent to the plug-in. If this method is set to false, console events are disabled and only the plug-in to which the console connects will send events. The SetConsoleEvents method does not affect ActiveX controls.

RealNetworks, Inc. ©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.
previous next