Chapter 13: Defining Events and Image Maps

When you produce RealAudio or RealVideo clips using RealProducer, you can use a utility that embeds clip information and HTML URLs directly in the clip. For RealVideo clips, you can also create clickable image maps. This chapter explains how to write markup that creates these features, and how to run the utility that merges the markup with the encoded clips.

Understanding Events and Maps

Event files and map files are text files that use a simple markup language. An event file defines URLs that open automatically in a the viewer's browser as the audio or video clip plays. This allows you to create a presentation in which HTML pages are timed to display at certain points as the clip plays. The events file can also encode extended clip information beyond the standard title, author, and copyright.

The map file can define image maps that overlay a RealVideo clip and open when the viewer clicks a predefined hot spot. These hot spots can be the entire video, or a smaller area in the shape of a circle, rectangle, or irregular polygon. So whereas the event file URLs open automatically, the map file URLs open only on user interaction.

Once you define your event file or map file, you merge the file with your encoded clip using the RMEvents utility. This creates a copy of your clip that has the event or map information permanently encoded into it. To change the events or maps, you must create a new version of the clip by merging the original clip with a new event file or map file.

Tip: Using a map file or event file is just one way to open URLs and add extended clip information. Ram files and SMIL files also provide these capabilities. Because these latter techniques do not encode information directly into the clip, they allow you to change the information more readily. For a comparison of all available production techniques, refer to the first chapter of Introduction to Streaming Media.

Writing an Events File

The events file is a plain text file that uses the standard extension of .txt. Within this file, you describe events that will occur as the clip plays. You write each event on a separate line, and you can use a pound sign (#) to start a comment line. Each event line follows this format:

flag start_time end_time event_syntax

The flag indicates the type of event, which can be either to display clip information, or to open a URL in an HTML pane automatically. The following table summarizes the possible flags.

The starting time and ending time are relative to the start of clip playback. You indicate the time value with the following format, in which only the seconds field is required:

dd:hh:mm:ss.xyz

After you create your event file, you encode it into the clip as described in "Running the RMEvents Utility".

Note: Define each event on a single line within the events text file. Do not press Enter to wrap long lines manually.

Specifying URL Events

When opening a URL automatically in an HTML pane, you use the u event flag. The event syntax looks like this:

u start_time end_time &&target&&URL?parameters

Browser Target

The URL must be a fully qualified HTTP URL. For target, you specify one of the HTML panes found in RealOne Player through RealPlayer 10. Earlier versions of RealPlayer, which do not handle HTML pages natively, display the URL in the viewer's default browser. If you plan to embed the clip in a Web page, you can specify an HTML frame name. You can use one of the following values.

For More Information: If you are unfamiliar with the RealPlayer HTML windows, refer to the first chapter of Introduction to Streaming Media.For information about playing a clip in a Web page, refer to the web page embedding chapter of RealNetworks Production Guide.

Related Info Pane Sizing

If you use _rpcontextwin to open the URL in the related info pane, you can use either of the following parameters to set the size of the pane:

Events File URL Examples

The following is a sample events file that opens two URLs in the related info pane at different times, and two URLs in the media browser pane at different times:

# Open a URL in the related info pane when the clip starts, and size the pane.
u 00:00:00.0 00:01:59.9 &&_rpcontextwin&&http://www.example.com/info1.html?rpcontextheight=250&rpcontextwidth=280
#
# Open a URL in the media browser pane at the 1-minute mark.
u 00:01:00.0 00:01:59.9 &&_rpbrowser&&http://www.example.com/index.html
#
# Open a second URL in the related info pane at the 2-minute mark.
u 00:02:00.0 00:04:00.0 &&_rpcontextwin&&http://www.example.com/info2.html
#
# Open a second URL in the media browser pane at the 3-minute mark.
u 00:03:00.0 00:04:00.0 &&_rpbrowser&&http://www.example.com/index2.html

Note the following about this sample:

• When you open multiple URLs, list the events in ascending order according to the start times.
• The related info pane size is set for the duration of the clip by the first URL that opens in that pane. Any subsequent URLs that target the related info pane therefore do not require sizing information.
• The end times indicate a point past which the URL should not open. In the second event defined above, the URL is scheduled to open at 1:00 minutes, but no later than 1:59.9 minutes. If a viewer starts the clip and immediately seeks to its 3-minute mark, for example, the URL doesn't display because the clip never plays at any point between the URL's start and end times.

Adding a Title, Author, and Copyright

When you encode a clip, you have the option of including clip information values as described in "Adding Clip Information". Using the events file, you can override the existing title, author, and copyright values, or add them if you did not include them during the encoding process. The events file does not allow you to add other values such as keywords and a description, however.

To add the title, author, or copyright, you include the i, a, or c event flag in the events file, respectively. The format is the same for specifying URLs:

flag start_time end_time value

Values do not need to be quoted. The following are examples:

i 00:00:00.0 00:00:10.0 2004 Music Awards
a 00:00:00.0 00:00:10.0 Brilliant Media Limited
c 00:00:00.0 00:00:10.0 2004 Brilliant Media Limited

For clip information flags, you can specify the start time as the clip's starting time (00:00:00.0). Specifying an end time is required, but the actual end time doesn't matter because the clip information will display throughout the length of the clip playback. In the example above, the end times are set to 10 seconds after the clip starts.

Adding Extended Clip Information

Using an events file, you can also encode several clipinfo parameters. Geared for online music, these parameters allow you to add information such as the artist name, album, genre, and so on, which displays when the viewer chooses the File>Clip Properties>View Clip Info command, or presses Ctrl+i. This information displays in RealOne Player or later, and is ignored by earlier RealPlayers. It can include the title, author, and copyright, so you do not need to include those separately, as described in "Adding a Title, Author, and Copyright".

The clipinfo parameter uses the i event flag and one long value surrounded by double quotation marks. Within the quotes, you separate the subvalues with vertical lines, or "pipes," as shown here:

i 00:00:00.0 00:00:10.0 clipinfo:title=My Presentation|artist name=Pat Morales|...

For clip information, you can specify the start time as the clip's starting time (00:00:00.0). Specifying an end time is required, but the actual end time doesn't matter because the clip information will display throughout the length of the clip playback. In the example above, the end time is set to 10 seconds after the clip starts.

Clip Information Parameters

The following table describes the name and value pairs that you can use with clipinfo. You can use any set of values, and list them in any order. Most text values can be over 100 characters long.

Text Escape Characters

To use certain text characters in a value for the clipinfo parameter, you must use the character's corresponding escape code. This is because certain characters represent syntax components. A pipe (|) represents the start of a new value, for example, so to use a pipe within a value, you must use the escape code %7C. The following table lists some common text characters that you can add through escape codes.

You can enter other common text characters, such as commas, periods, and colons directly into clipinfo parameter. Conversely, you can display any text character, including letters and numbers, by using an escape code that starts with % followed by the character's ASCII hexadecimal value. You can create an asterisk (*) with the escape code %2A, for example.

For More Information: Visit http://www.asciitable.com for a full list of ASCII codes.

Clip Information Example

This example sets the clipinfo parameter for an audio clip:

i 00:00:00.0 00:00:10.0 clipinfo:title=Artist of the Year|
artist name=Your Name Here|album name=My Debut|genre=Rock|
copyright=2001|year=2001|comments=This one really knows how to rock!

The following figure illustrates how this information appears in the clip information panel (Ctrl+i).

Clip Information

Creating Image Maps

For a RealVideo clip, you can write a map file to create image maps that open a URL or issue a RealPlayer command when clicked. The image map can provide one or more clickable hot spots that are active for the entire duration of the clip, or only during certain periods. You can create these hot spots in the shapes of rectangles, circles, or polygons. Clicking the left half of a video might take the viewer to one Web page, for example, while clicking the right half opens a different page.

You can create a map file using any text editor that can save output as plain text. The map file uses a simple markup similar to HTML that defines the hot spot locations, durations, and actions. Once you define your map file, you merge the map coordinates into the RealVideo clip using the RMevents utility, as described in "Running the RMEvents Utility".

Tip: You can also use SMIL to create clickable image maps that overlay a video or multiclip presentation. The advantage to using SMIL is that the map coordinates are not merged into the clip, and are therefore easier to change. However, you must always stream the clip through the SMIL file to make the hot spots available. For more information, see the hyperlinking chapter of RealNetworks Production Guide.

Setting a Duration

The map file begins with a mandatory DURATION parameter that defines the total amount of time that the hot spots are active, using a time value in the following format:

dd:hh:mm:ss:xxx

In this time format, you must specify all fields. The last field, which indicates milliseconds, is separated from the seconds field by a colon, not a period as in other time formats. The following example sets the entire duration of the hot spots to five minutes, 30 seconds:

DURATION=0:0:5:30:0

Creating the Overall Map

Following the DURATION parameter, you define the overall area that can contain a hot spot between <MAP> and </MAP> tags. The <MAP> tag uses START and END parameters that define when the map area is active, relative to the start of clip playback. Like DURATION, the START and END parameters have values in the following format:

dd:hh:mm:ss:xxx

The following map area becomes active 30 seconds after the start of the clip, and stays active for one minute:

<MAP START=0:0:0:30:0 END=0:0:1:30:0 ...>...</MAP>

The COORDS parameter, which must follow the START and END parameters, defines a rectangle for the map. It uses four values, separated by commas, that set the map's size and placement, measured from the upper-left corner of the clip in the following order:

1. distance of the map's left edge from the clip's left edge (left-x)
2. distance of the map's top edge from the clip's top edge (top-y)
3. distance of the map's right edge from the clip's left edge (right-x)
4. distance of the map's bottom edge from the clip's top edge (bottom-y)

The COORDS parameters allows you to create a map area from any rectangular portion of the clip area. The simplest way to define the map is to create it at the same size as the clip. If the clip is 360 pixels wide by 240 pixels high, for example, you use a map tag such as the following:

<MAP START=0:0:0:30:0 END=0:0:1:30:0 COORDS=0,0,360,240>...</MAP>

Tip: You can define more than one map area. Typically, each map area is active at a different point during the clip timeline. If map areas are active at the same time, the map areas or the hot spots that each map defines should not overlap.

Defining Hot Spot Areas

To create a hot spot, you use an <AREA> tag with a SHAPE attribute that defines the hot spot's shape, and a COORDS attribute to define the hot spot's size and placement. You define the SHAPE and COORDS attributes just as you do in HTML 4.0. The following example defines a rectangular hot spot:

<AREA SHAPE=RECTANGLE COORDS=20,40,80,120 ...>

How you specify the coordinate values depends on what shape—rectangle, circle, or polygon—you want, as explained in the following sections. In all hot spots, the coordinates are measured from the upper-left corner of the area defined by the <MAP> tag.

Creating a Rectangular Hot Spot

Use SHAPE=RECTANGLE to create a rectangular hot spot. You then specify four COORDS pixel values to set the hot spot's size and placement, measured from the upper-left corner of the map in the following order:

1. distance of the hot spot rectangle's left edge from the map's left edge
   (left-x)
2. distance of the hot spot rectangle's top edge from the map's top edge
   (top-y)
3. distance of the hot spot rectangle's right edge from the map's left edge
   (right-x)
4. distance of the hot spot rectangle's bottom edge from the map's top edge
   (bottom-y)

Coordinate values are separated by commas, as shown in the following example:

<AREA SHAPE=RECTANGLE COORDS=20,40,80,120 ...>

The preceding example defines a hot spot 60 pixels wide (80 pixels minus 20 pixels) and 80 pixels high (120 pixels minus 40 pixels). It creates a hot spot like that shown in the following illustration.

Rectangular Hot Spot

Tip: Think of the first pair of values as defining the x and y coordinates of the hot spot's upper-left corner, and the second pair of values as defining the x and y coordinates of the hot spot's lower-right corner.

Defining a Circular Hot Spot

You can use SHAPE=CIRCLE to create a circular hot spot. Three COORDS pixel values specify the circle's center placement and radius in the following order:

1. distance of the hot spot circle's center from map's left edge (center-x)
2. distance of the hot spot circle's center from the map's top edge (center-y)
3. the hot spot circle's radius

The coordinate values are separated by commas, as shown in the following example:

<AREA SHAPE=CIRCLE COORDS=100,120,50 ...>

The preceding example places the circular hot spot's center 100 pixels in from the clip's left edge, and 120 pixels down from the clip's top edge. The hot spot has a radius of 50 pixels. The following figure illustrates this example.

Circular Hot Spot

Tip: The last value, which sets the circle's radius, should not be more than the smaller of the other two values. If the first two values are 40 and 20, for example, the third value should not be more than 20. Otherwise, part of the circle extends beyond the clip boundaries and is cut off.

Making a Polygonal Hot Spot

Use SHAPE=POLYGON to make a polygonal hot spot with any number of sides. You might create a triangle or an octagon, for example. For every n sides of the polygon you want to create, you must specify 2n values in the COORDS attribute. To create a triangle, for example, you need to specify six COORDS values. Each pair of coordinate values indicates the placement of a corner of the polygon in this order:

1. distance of the polygon corner from the map's left edge (corner-x)
2. distance of the polygon corner from the map's top edge (corner-y)

The following example defines a triangular hot spot:

<AREA SHAPE=POLYGON COORDS=40,150,120,30,200,150 ...>

The following figure illustrates the preceding example. The first value pair for the COORDS attribute defines the triangle's lower-left corner. The COORDS value pairs then proceed clockwise, defining the top corner, followed by the lower- right corner.

Polygonal Hot Spot

Tip: When defining a polygon, you can start with any corner, specifying the placement of additional corners by going around the polygon either clockwise or counter-clockwise.

Tips for Defining Hot Spots

• A viewer may resize a presentation manually by, for example, clicking and dragging a RealPlayer corner. In these cases, hot spots scale with clips.
• Values such as COORDS=30,30,10,10 for a rectangular hot spot are ignored, and the hot spot will not function. Here, the hot spot's left side is defined as being farther to the right than its right side. As well, the top is defined to be below the bottom.
• A hot spot defined to extend beyond the source clip is cropped at the clip's edge. For example, if a rectangular hot spot uses COORDS=50,50,300,300 but the source clip is 200 by 200 pixels, the hot spot's effective coordinates are 50,50,200,200.
• If multiple hot spots overlap on a clip, the link for the hot spot defined first in the file is used when the viewer clicks the overlapping area.
• Many programs, including shareware and freeware, can generate HTML image maps. You can use one of these programs to define the coordinates for a hot spot. Simply create an HTML image map over an image that is the same size as your clip, view the HTML source, and copy the image map coordinates into your <AREA> tag.

Setting the Action

The <AREA> tag for a hot spot can define one of three actions that occur when the viewer clicks the hot spot. The action parameter should follow the COORDS parameter in the <AREA> tag:

The following are examples:

<AREA ... PLAYER="rtsp://helixserver.example.com/movie2.rm" ...>
<AREA ... SEEK=0:0:2:15:0 ...>
<AREA ... URL="http://www.example.com/page2.html" ...>

Defining Alternate Text

The last parameter in the <AREA> tag must be an ALT attribute that uses short, descriptive text as its value. When the viewer moves the screen pointer over the hot spot, the alt text displays in the status line above the RealPlayer media playback pane, indicating what action clicking the hot spot will perform. In the following example, the text "Visit RealNetworks" is used for the ALT value:

<AREA ... URL="http://www.realnetworks.com" ALT="Visit RealNetworks">

Map File Example

The following example defines an image map that is active for five minutes. The map creates two clickable map areas, each of which covers the entire, 360- pixel-by-240-pixel video. The first map area is active for the first half of the clip. Clicking it fast-forwards to the second half of the clip's timeline. As the second half of the timeline plays, clicking the image map displays a Web page in the viewer's browser.

DURATION=0:0:5:0:0

<MAP START=0:0:0:0:0 END=0:0:2:30:0 COORDS=0,0,360,240>
<AREA SHAPE=RECTANGLE COORDS=0,0,360,240 SEEK=0:0:2:30:0 
ALT="Click to fast-forward to part 2.">
</MAP>

<MAP START=0:0:2:30:1 END=0:0:5:0:0 COORDS=0,0,360,240>
<AREA SHAPE=RECTANGLE COORDS=0,0,360,240 URL="http://www.example.com" 
ALT="Visit our Web site.">
</MAP>

Running the RMEvents Utility

After you write your event or image file, you use the RMEvents utility to merge the file with your clip. This creates a new clip that includes the events or maps. The utility is named rmevents.exe on Windows and rmevents on Linux. You can find it in the RealMediaEditor subdirectory of the RealProducer installation directory.

Tip: The utility needs access to the libraries in its directory, so you should run it from this directory, or add its directory to your PATH environment variable.

For More Information: You can also use the graphical RealMedia editor to merge event and image files with your clip. See "Merging Image Maps or Events".

Using RMEvents Option Flags

The following table describes the options that you use on the command line when running RMEvents.

Merging an Event or Map File with the Clip

When your event and map files are complete, you use RMEvents to merge them with your encoded RealAudio or RealVideo clip. Open a command-line prompt and navigate to the directory that holds the RMEvents utility. Then give the following command, which uses four flags to indicate the input clip, output clip, events file, and map file. If you are not encoding a map file, for instance, leave out the -m command and value:

rmevents -i input.rm -o output.rm -e events.txt -m maps.txt

where:

• input.rm is the path and name of the input clip
• output.rm is the path and name of the output clip
• events.txt is the path and name of the events file
• maps.txt is the path and name of the map file

Tip: Always choose a new output name so that you can save your original clip without any encoded events or maps. You cannot delete image map or events information once you have encoded it into a clip. You can override the information with new information, however.

Extracting Map and Events Information

Using the -d flag, you can extract map and event file information encoded into a clip, writing it to text files. This action does not remove the information from the clip, however. You specify the input clip with the -i option and a dump file base name along with the -d option:

rmevents -i movie.rm -d movie

In this example, event information is written to the file movie_evt.txt. Map information is written to the file movie_imap.txt.

©2004 RealNetworks, Inc. For more information, visit RealNetworks Click here if the Table of Contents frame is not visible at the left side of your screen.