Chapter 19: Web Page Embedding

With embedded playback, you can weave your clips through your Web page's text and graphics, and add controls such as stop and start buttons. It's as if you took RealONE Player apart and placed its pieces at different spots on your page. This chapter explains how to add markup to a Web page so that people can view your streaming presentation directly through their Web browsers.

Understanding Web Page Embedding

To embed streaming media in your Web page, you first produce your clip or clips. You can even use SMIL to put together an entire presentation containing multiple clips. You then embed your presentation by adding <EMBED> tags to your Web page, and using HTML commands to place your clips and various RealONE Player controls on your page.

<EMBED> Tags

You add to your Web page one <EMBED> tag for each playback window you want in your page, and one <EMBED> tag for each control, such as a Stop button, that you want to include. When you use <EMBED>, your presentation will work in browsers that support the Netscape plug-in architecture, including the following:

• Netscape Navigator 3.0 and later.
• Microsoft Internet Explorer 3.0 and later.

Note: Even when you use the <EMBED> tag, RealONE Player communicates with the Internet Explorer browser using ActiveX technology. This makes the Netscape <EMBED> tag compatible with both major browsers.

<EMBED> Tag Syntax

<EMBED> tags are an extension of HTML. Because they are not SMIL tags, they do not use the same syntax rules as SMIL. The <EMBED> tag parameters are typically in this form:

PARAMETER=value

Parameter names can be any case, although this manual shows them uppercase. Except for file names, which typically must be lowercase, parameter values are not case-sensitive. Unless they are URLs, parameter values do not need to be enclosed in quotation marks.

Layout Possibilities

When you embed a presentation, you use HTML to structure your Web page and define where each streaming clip and RealONE Player control appears. A common practice is to define an HTML table, embedding clips and RealONE Player controls in various table cells. When you embed a SMIL presentation, you can define a layout using SMIL and HTML, or just HTML alone.

Defining a Layout with SMIL and HTML

As described in Chapter 11, you can use SMIL to define an overall media window size (the root-layout). You might create a layout that is 400 pixels wide by 300 pixels high, for example, and define smaller regions within that main area for clips. You then embed the entire playback area within your Web page using a single <EMBED> tag, adding RealONE Player controls around it with separate <EMBED> tags. All clips then appear within that 400-by-300 pixels area, just as they would when played in RealONE Player. In fact, your SMIL file can play in both your Web page and RealONE Player.

For More Information: See "Defining the Layout with SMIL".

Defining a Layout with HTML Alone

You can leave layout information out of your SMIL file, and use SMIL simply to define your presentation timing and other playback features. In your Web page, you then create a separate <EMBED> tag for each clip, placing each clip anywhere on your page. In this case, all clips do not need to appear within a rectangular root-layout area. This gives you more layout flexibility than when defining the overall clip layout through SMIL. However, because your SMIL file lacks layout information, it may have unexpected layout results if played directly in presentation.

For More Information: See "Defining the Layout with HTML".

RealONE Player Controls

In addition to clips, you can embed many different RealONE Player buttons, sliders, and information panels in your Web page. You might include separate start, stop, and pause buttons in your Web page, for example. Or, you could add entire control panels that contain multiple buttons and readouts. You can make these controls any size you want, too, giving you even more layout flexibility. The section "Adding RealONE Player Controls" explains all the available controls.

Javascript and ActiveX

RealONE Player supports Javascript, which enables you to extend the <EMBED> tag capabilities. You can use Javascript to turn your own graphic image into a RealONE Player Play button, for example. RealONE Player also includes an ActiveX control that provides playback capabilities for the following products:

• Microsoft Internet Explorer 3.0 and later.
• Any application that supports ActiveX controls, such as Microsoft Visual Basic, Microsoft Visual C++, Microsoft Access, and so on.

This production guide does not explain these capabilities. For information on using Javascript or ActiveX with an embedded presentation, see the RealPlayer Javascript and ActiveX Reference Guide, which is available for download from the following Web page:

http://service.real.com/help/library/encoders.html

Using <EMBED> Tags

Each <EMBED> tag has three required parameters, and can include many optional parameters, which are described throughout this chapter. The following table lists the parameters to include in every <EMBED> tag.

A basic <EMBED> tag looks like the following, which creates a playback area 320 pixels wide by 240 pixels high within the Web page:

<EMBED SRC="presentation.rpm" WIDTH=320 HEIGHT=240 NOJAVA=true>

Specifying the Source

You must include the SRC parameter in every <EMBED> tag, even when the tag embeds a RealONE Player control 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. This causes the browser to use RealONE Player as a helper, rather than 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.

For More Information: For background on Ram files, see "The Ram File".

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

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/sample.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 RealServer, 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 on URLs in .rpm files, see "Launching RealONE Player with a Ram File". The section "The Difference Between RTSP and HTTP" explains why RealServer uses the RTSP protocol instead of a Web server's HTTP protocol.

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\first.rpm

use this URL:

file://c:/media/first.rpm

Using RealServer's Ramgen to Eliminate the Ram File

When your embedded clips reside on a RealServer that uses the Ramgen feature, you can eliminate the .rpm file when you deliver your presentation. Your SRC parameter uses an HTTP URL to the clip or SMIL file on RealServer, and includes a /ramgen/ parameter along with the ?embed option:

SRC="http://realserver.example.com:8080/ramgen/sample.smil?embed"

The HTTP protocol is required because a browser cannot make an RTSP request. When /ramgen/ is used, though, RealServer causes the browser to start RealONE Player as a helper application, then streams the clip or SMIL file to RealONE Player using RTSP. Consult your RealServer administrator for the correct URL to your RealServer.

For More Information: For details on using the Ramgen option, see "Using Ramgen for Clips on RealServer".

Setting the Width and Height

Required for each <EMBED> tag, the WIDTH and HEIGHT parameters set the size of the playback area. If you omit these parameters, the playback area may appear as a tiny icon because streaming media presentations do not resize themselves automatically. The values for WIDTH and HEIGHT are in pixels by default, so a width of 300 creates a playback area 300 pixels wide. Setting WIDTH and HEIGHT to 0 (zero) hides the playback area.

You can also express WIDTH and HEIGHT as percentages of the browser window size. For example, a width of 50% makes the width of the presentation area half the width of the browser window. Keep in mind that different types of media scale with different results. For example, a video scaled larger than its encoded size may not look good. Vector-based clips such as Flash animations, on the other hand, scale more easily to fit different playback areas.

Turning off the Java Virtual Machine

Setting the NOJAVA parameter to true in every <EMBED> tag prevents the browser's Java Virtual Machine (JVM) from starting if it is not yet running:

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

This parameter primarily affects Netscape Navigator 4, which does not launch its JVM until it's needed. The parameter is recommended because starting the JVM delays presentation playback unnecessarily.

Note: The JVM is required only when you are extending plug-in functionality with Javascript. In this case, omit NOJAVA entirely from the <EMBED> tags. See "Javascript and ActiveX" for more information about using Javascript with the <EMBED> tag.

Supporting Other Browsers

To accommodate browsers that do not support the Netscape plug-in, use <NOEMBED> to define a standard hypertext link to your presentation. The unembedded link follows the <EMBED> tag:

<EMBED SRC="presentation.rpm" WIDTH=320 HEIGHT=240>
<NOEMBED><A HREF="presentation.ram">Play with RealONE Player. </A></NOEMBED>

In this example, browsers that can play the embedded presentation hide the text between <NOEMBED> and </NOEMBED>. Other browsers ignore the preceding <EMBED> tag and display only the hypertext link. The viewer then clicks the link to play the presentation in RealONE Player.

Adding RealONE Player Controls

With the CONTROLS parameter, you can add RealONE Player 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:

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

The following sections describe the embedded RealONE Player controls. You use an <EMBED> 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.

For More Information: When adding more than one control to your Web page, see also "Linking Multiple Controls".

Tip: Unless noted otherwise, all the 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.

Basic Controls

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. See also "Controlling Image Display".

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.

Individual Controls and Sliders

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.

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.

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 the PlayOnlyButton and the PauseButton controls.

StopButton

The CONTROLS=StopButton parameter displays a stop button.

FFCtrl

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

RWCtrl

The CONTROLS=RWCtrl parameter displays a rewind button.

MuteCtrl

The CONTROLS=MuteCtrl parameter displays a mute button.

MuteVolume

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

VolumeSlider

The CONTROLS=VolumeSlider parameter displays a volume slider.

PositionSlider

The CONTROLS=PositionSlider parameter displays a clip position slider.

TACCtrl

The CONTROLS=TACCtrl parameter displays a clip information field. 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.

For More Information: For instructions on formatting the clip playlist, see "Managing Presentation Information".

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.

Information Panels

InfoVolumePanel

Use CONTROLS=InfoVolumePanel to display presentation information along with the volume slider and mute button. For more on presentation information, see "Defining Information for the SMIL Presentation".

InfoPanel

The CONTROLS=InfoPanel parameter displays the presentation information panel. For more on presentation information, see "Defining Information for the SMIL Presentation".

Status Panels

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.

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.

PositionField

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

Linking Multiple Controls

The CONSOLE parameter defines a name that unifies <EMBED> tags so that multiple controls work together. For example, you could create three separate <EMBED> tags to define an image window, a play button, and a stop button. By using three tags, you can set the size of each control separately, and define the entire layout with HTML tags. You could put each control in a different HTML table cell, for example.

To tie controls together, define the same CONSOLE name within each <EMBED> tag, or use one of these predefined names:

_master links the control to all other embedded controls on the page.

_unique links the control to no other embedded controls on the page.

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, sample1.rm and sample2.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="presentation.rpm" WIDTH=176 HEIGHT=128 NOJAVA=true CONTROLS=ImageWindow CONSOLE=_master>

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

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

Controlling Image Display

The <EMBED> parameters summarized in the following table control aspects of how clips play back in an image window.

The following example shows two of these parameters used in an <EMBED> tag:

<EMBED SRC="presentation.rpm" WIDTH=50% HEIGHT=50% NOJAVA=true BACKGROUNDCOLOR=gray CENTER=true>

Setting a Background Color

The BACKGROUNDCOLOR parameter specifies a background color for the image window. The specified background color also shows through if a clip includes transparency. The background color is black by default. You can use an RGB hexadecimal color value (#RRGGBB) or the following color names, shown here with their corresponding RGB values:

Note: SMIL region background colors override this background color. For more on setting SMIL region colors, see "Adding Background Colors".

Tip: Appendix D provides background on hexadecimal color values. Note, though, that the <EMBED> tag does not support RGB color values used with SMIL.

Centering a Clip

The default value for CENTER is false, which causes the clip to fill the entire playback area. If you set CENTER to true, the clip is centered within the playback area and is displayed at its encoded size. So by setting CENTER to true, you can create a large playback area with WIDTH and HEIGHT and still have the clip play at its normal size. You cannot use CENTER along with MAINTAINASPECT.

Maintaining a Clip's Aspect Ratio

The MAINTAINASPECT parameter, which you cannot combine with CENTER, determines whether the clip's height-to-width ratio stays constant when the clip scales to fit the image window. The default value of false causes this ratio to change as necessary to fill the image window fully. This may distort the source image.

If you set MAINTAINASPECT to true, a clip's height-to-width ratio stays constant. For example, a clip's height-to-width ratio of 1:1 stays constant even if the image window's height-to-width ratio is 2:3. In these cases, 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. The following illustration shows how clips scale by default, with MAINTAINASPECT set to true, and with CENTER set to true.

Clip Scaling with MAINTAINASPECT and CENTER

Suppressing the Real Logo

When set to true, NOLOGO prevents the Real logo from displaying in the image window before clips play. When there are no clips playing, only the specified background color shows in the window. The parameter is false by default.

Setting Automatic Playback

The parameters listed in the following table can cause a presentation to start playing automatically, and to loop continuously or for a specified number of times.

The following example shows two of these parameters in an <EMBED> tag:

<EMBED SRC="presentation.rpm" WIDTH=50% HEIGHT=50% NOJAVA=true AUTOSTART=true LOOP=true>

Starting a Presentation Automatically

When set to true, the AUTOSTART parameter starts playback immediately. When you have multiple <EMBED> tags linked by a CONSOLE name, set AUTOSTART to true in just one tag. Leaving AUTOSTART out, or setting its value to false, means that the presentation will not start until the user starts it by clicking an embedded play button, for example.

Looping a Presentation Continuously

If the LOOP parameter is set to true, the presentation continuously loops until the viewer stops it. When you have multiple <EMBED> tags linked by a CONSOLE name, set LOOP to true in just one tag. If you leave LOOP out, the default value of false applies, and the presentation stops after the first playback. The user can play the presentation again by clicking a play button.

Note: The LOOP or NUMLOOP parameters will make an entire SMIL presentation repeat. Within a SMIL file, you can use the repeatDur and repeatCount attributes to repeat individual clips or groups. For more information, see "Repeating an Element".

Specifying a Number of Loops

If you specify a parameter such as NUMLOOP=2, the presentation plays the specified number of times and then stops. If you use both LOOP and NUMLOOP, the LOOP parameter is ignored.

Setting Shuffle Play

The SHUFFLE parameter is for use only with Ram or SMIL files that list a single sequence of clips. When set to true, SHUFFLE causes RealONE Player to play the clips in a random order. If you use this parameter with LOOP or NUMLOOP, each loop may use a different playback order.

For More Information: For information on SMIL sequences, see "Playing Clips in Sequence". For more on Ram file sequences, see "Writing a Ram File".

Laying Out SMIL Presentations

As explained in Chapter 11, you can use a SMIL file to define separate playback regions for different parts of a presentation. This lets you lay out two clips side-by-side, for example. When playing a presentation in a Web page, you can define the layout in SMIL or in HTML.

Defining the Layout with SMIL

To control the layout by using SMIL, you set up the regions and their relative placements in the SMIL file. You then create a Web page playback area large enough to accommodate all SMIL regions. The SMIL file then produces the same layout when played through the Web page or RealONE Player. For example, if your SMIL file creates a playback area 400 pixels wide by 300 pixels high, you define an image window at least as large as this with the <EMBED> tag, as shown in the following example:

<EMBED SRC="presentation.rpm" WIDTH=400 HEIGHT=300 NOJAVA=true CONTROLS=ImageWindow CONSOLE=one>

You can then use additional <EMBED> tags linked to the console named one to provide RealONE Player controls for the presentation.

Tip: Typically, your image window is the same size as your SMIL root-layout area, which is described in the section "Root- Layout Area".

View it now! (requirements for viewing this sample) Click this sample to see a presentation with a SMIL layout embedded in a Web page. You can also view the same presentation in RealONE Player.

Defining the Layout with HTML

The second method omits layout information in the SMIL file, defining the layout with HTML instead. You could place an image window and individual RealONE Player controls in separate cells of an HTML table, for example. Each <EMBED> tag then uses a REGION parameter to define a region name. The region each clip plays in is denoted by the region attribute in the SMIL clip source tag:

<textstream src="news.rt" region="newsregion"/>

Within the HTML page, the <EMBED> tag that plays news.rt would look like this:

<EMBED SRC="presentation.rpm" WIDTH=250 HEIGHT=144 NOJAVA=true 
CONTROLS=ImageWindow REGION=newsregion CONSOLE=one>

You define similar <EMBED> tags to create other regions for other clips listed in the SMIL file. The SRC parameter in each tag lists the same SMIL file. You can also use additional <EMBED> tags linked to the same console to provide RealONE Player controls for the presentation.

Tip: Because you must omit the SMIL layout information when laying out the presentation with HTML, you should not also provide viewers the option to play the same SMIL file directly in RealONE Player. When there is no SMIL layout, RealONE Player automatically creates a layout, but the results may not be what you expect.

View it now! (requirements for viewing this sample) Play this sample to see a SMIL presentation with an HTML layout.

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