Chapter 13: Advanced Timing

Once you have mastered the basic timing attributes described in Chapter 12, you are ready to tackle SMIL's advanced timing features. Using these features, you can develop interactive presentations that play clips when viewers click icons, for example. You can also use advanced timing to create effects similar to those found in Web pages, such as starting a SMIL animation when the viewer moves the screen pointer over an image.

Tip: Be sure to familiarize yourself with "Conventions Used in this Guide". That section lists the typographical conventions used in this chapter to explain event timing syntax.

Understanding Advanced Timing

Chapter 12 explains the basic timing attributes: begin, end, and dur. Although this chapter introduces some new timing attributes, it primarily shows you how to expand the power of the begin and end attributes through complex timing values. This chapter describes many different ways to start or stop an element besides using basic timing attributes such as begin="5s".

Advanced Timing Syntax

The key to advanced SMIL timing is the event. Although not always the case, an advanced timing command typically starts or stops a SMIL element when an event occurs. So you generally have two elements that you work with: the element that triggers the event, and the element that the triggered event starts or stops. For the element that provides the event trigger, you must define an ID:

<element_tag1 id="ID" .../>

In the second element's tag, you create a begin or end value that refers to the first element's ID, specifies the triggering event, and, optionally, adds a timing offset:

<element_tag2 begin|end="ID.event[+|-time_value]" .../>

To make these abstract examples more concrete, suppose that your triggering element is a video clip:

<video src="video1.rm" id="intro" region="video_region"/>

Your triggered element might be a graphic image that begins 10 seconds after the video starts:

<img src="picture.jpg" begin="intro.begin+10s" region="image_region" .../>

In simple cases, advanced timing commands may not be needed. If the two preceding clips were in the same <par> group, for example, you could achieve the desired 10-second delay with simple timing commands:

<par>
  <video src="video1.rm" id="intro" region="video_region"/>
  <img src="picture.jpg" region="img_region" begin="10s" .../>
</par>

The advanced timing commands let you tie elements together when they are not in the same group, however. As well, the advanced timing commands let you start or stop clips on many kinds of events, such as mouseclicks.

Event Types

Events that can start or stop an element fall into two categories:

scheduled events

RealONE Player can determine that a scheduled event will happen before the event occurs. The end of a certain clip's playback is a scheduled event, for example, because RealONE Player can determine when the clip will stop based on the clip's internal timeline and the presence of SMIL timing attributes.

interactive events

Interactive events let you base SMIL actions on user input. But unlike a scheduled event, an interactive event such as a mouseclick cannot be known before it occurs. Some interactive events mirror scheduled events, too. The end of a clip's playback can trigger an interactive or a scheduled event, for instance.

The following table summarizes the event values you can use with the begin and end attributes. Most event values require an ID value that identifies the element that triggers the event.

begin and end Attribute Event Values
Value	Event Type	Event Trigger	Reference
`accesskey(key)`	interactive	keypress	click here
`ID.activateEvent`	interactive	mouseclick	click here
`ID.begin`	scheduled	beginning of element	click here
`ID.beginEvent`	interactive	beginning of element	click here
`ID.end`	scheduled	end of element	click here
`ID.endEvent`	interactive	end of element	click here
`ID.focusInEvent`	interactive	keyboard focus on element	click here
`ID.focusOutEvent`	interactive	keyboard focus off element	click here
`ID.inBoundsEvent`	interactive	pointer moving over element	click here
`ID.marker(name)`	scheduled	marker reached for element	click here
`ID.outOfBoundsEvent`	interactive	pointer moving off element	click here
`ID.repeat(integer)`	scheduled	specific iteration of element	click here
`ID.repeatEvent`	interactive	each iteration of element	click here
`ID.topLayoutCloseEvent`	interactive or scheduled	secondary media window closing	click here
`ID.topLayoutOpenEvent`	interactive or scheduled	secondary media window opening	click here
`ID.wallclock(time)`	scheduled	external clock value reached	click here

Positive Offset Times

Most of the begin and end attribute values described in this chapter can take a positive offset timing value, which adds a delay between an event and the action that the event triggers. For example, a begin attribute might have the following syntax, which sets the element to start at five seconds after the event (left unspecified here) occurs:

begin="ID.event+5s"

Interactive Events with Positive Offset Times

A positive offset is useful when starting a clip based on an interactive event. Because it cannot anticipate interactive events, RealONE Player does not request clips from the server until the interactive event occurs. If you do not add a positive offset, RealONE Player may need to pause the presentation while it requests and buffers the clip's preroll. An offset such as +15s, on the other hand, enables RealONE Player to request the clip when the event occurs, then buffer the clip for up to 15 seconds before playing it.

Tip: Instead of using a timing offset value, you can use <prefetch/> to request a clip's preroll in advance. For more information, see Chapter 18.

How Much of a Positive Offset Do You Need?

If you plan to start a clip on an interactive event, open the clip in RealONE Player, and use the View>Clip Source command to display the clip's required preroll. You'll also need to add a few seconds for RealONE Player to request the clip from the server, and to begin receiving the streamed data. If a clip's preroll is 10 seconds, for example, you may want to use positive offset of 15 seconds to ensure that the clip's preroll has streamed to RealONE Player by the time the clip begins to play.

Note: Static clips such as images do not have a preroll. RealONE Player must receive all the clip data before playing the clip. The time required to display the clip is the clip size divided by the available streaming bandwidth.

Interactive Events that Do Not Require Positive Offsets

A positive offset value isn't necessary when starting or stopping elements on interactive events if those elements do not need to be streamed from a server. For example, you can use an interactive event such as a mouseclick to trigger a SMIL animation that shrinks a clip already received by RealONE Player. Because the SMIL animation is defined within the SMIL file, RealONE Player has all the data it needs to start the animation when the event occurs.

Scheduled Events with Positive Offset Times

When you start clips on scheduled events, a positive offset time is generally not required to keep the presentation flowing smoothly. RealONE Player can anticipate scheduled events and request a new clip's preroll far enough in advance to prevent presentation rebuffering. You may want to use positive offset times with scheduled events to manage the presentation timeline, though. You might want to start a clip five seconds after another clip repeats for the second time, for example. You can do that easily by adding +5s to the clip's begin time.

Negative Offset Times

SMIL elements within a <par> or <excl> group (but not a <seq> group) can use negative timing offsets with advanced begin and end values. You can also use a negative offset value with an event, as shown in the following example:

begin="ID.event-5s"

Simple Negative Offset Times

You can use negative timing offsets in basic begin and end attributes, as well as with advanced timing commands. In the following example, the video is set to begin one minute before the group becomes active:

<par>
  <textstream src="credits.rt" id="credits" region="credits_region"/>
  <video src="video1.rm" region="video_region" begin="-1min"/>
</par>

Although the negative offset time in the preceding example is valid, a clip never plays before the group that contains it becomes active. This is because all timing attributes are relative to the group that contains the timed element. Instead of making the video clip play one minute before the parallel group becomes active, the negative offset shown above functions like clipBegin. This means that the video starts playing at its one-minute mark once the group becomes active.

For More Information: The clipBegin attribute is described in "Setting Internal Clip Begin and End Times".

Interactive Events with Negative Offset Times

Because RealONE Player cannot anticipate an interactive event, there is no way to use a negative offset time to make a clip start or stop before an interactive event happens. If you use a negative offset to start a clip 20 seconds before an interactive event occurs, the clip begins when the event occurs, yet appears to have played for 20 seconds already. In other words, the clip acts as if clipBegin="20s" were included in its source tag.

Scheduled Events with Negative Offset Times

Negative offset values are most useful with scheduled events because RealONE Player can determine when scheduled events will occur. RealONE Player can determine when a clip is scheduled to end, for instance. You can therefore use a negative offset time to end a clip ten seconds before another clip's scheduled end time, for example.

Multiple Timing Values

For any SMIL element that uses begin or end attributes, you can define any number of timing values by separating the values with semicolons:

"time1; time2; time3;..."

In the following example, the clip begins when the first of two possible events occurs: either one minute elapses after the clip's group becomes active, or event1 occurs. The clip ends either two minutes after the group starts, or when event2 occurs:

<ref src="..." begin="1min; event1" end="2min; event2"/>

Tips for Specifying Multiple Time Values

The order that you list time values does not matter. The time value listed third can occur before the time value listed second or first, for example.

The entire value string must be enclosed in double quotation marks.

You can include spaces before or after a semicolon that separates time values, but spaces are not necessary.

Do not add a semicolon after the last value.

The restart attribute can prevent a clip or group from restarting due to multiple begin values. See "Controlling Whether an Element Restarts" for more information.

Defining an Element Start or Stop Event

The following four event values work with either the begin or the end attribute, letting you start or stop an element when another element begins or ends:

ID.begin[+|-time_value]

This scheduled event occurs when the element with the given ID begins, plus or minus any offset time. If the element repeats, this event does not occur at the start of any repeated cycles.

ID.beginEvent[+|-time_value]

This interactive event occurs when the element with the given ID begins, plus or minus any offset time. If the element repeats, this event occurs at the start of every cycle.

ID.end[+|-time_value]

This scheduled event occurs when the element with the given ID ends, plus or minus any offset time. If the element repeats, this event occurs at the end of all repeated cycles. This event does not occur if, for example, a user action stops the element before its scheduled end time.

ID.endEvent[+|-time_value]

This interactive event occurs when the element with the given ID ends, plus or minus any offset time. If the element repeats, this event occurs at the end of all repeated cycles. This event will not occur if the viewer stops the element by clicking the RealONE Player Stop button.

Sample Values

The following are samples of begin and end values that start or stop an event relative to an element with a certain ID value:


`begin="ID.end"`	Start the element when the element with the given ID is scheduled to end.
`end="ID.begin-5s"`	Stop the element five seconds before the element with the given ID is scheduled to begin.
`begin="ID.beginEvent+5s"`	Start the element five seconds after the element with the given ID actually begins.
`end="ID.endEvent"`	Stop the element when the element with the given ID actually ends.

Example

As an example of using a begin event, suppose you want to start a clip two seconds after another clip begins. You first add an ID to the element that provides the basis for starting or stopping the second element:

<video src="video1.rm" id="intro" region="video_region"/>

Next, you define the begin or end time for the second element, using the ID of the first element:

<img src="picture.jpg" region="img_region" dur="20s" begin="intro.begin+2s"/>

Keep in mind that SMIL timing values can affect when your second element begins. Suppose that the video in the preceding example has an internal timeline of two minutes, but you specify a three-minute duration as shown here:

<video src="video1.rm" id="intro" region="video_region" dur="3min"/>

If the second element uses begin="intro.end" or begin="intro.endEvent", for example, it will start to play when the video's dur time expires, which is one minute after the video displays its last frame.

Defining a Repeat Event

Two event timing values for the begin and end attributes let you start or stop a clip or group when another element repeats. You might target a specific repetition, such as the third time the element repeats. Or you can restart the clip or group on each of the element's repeating cycles:

ID.repeat(n)[+|-time_value]

This scheduled event occurs when the element with the given ID starts its specified repeating cycle, plus or minus any offset time. For example, ID.repeat(1) specifies the first iteration after the element has already played once.

ID.repeatEvent[+|-time_value]

This interactive event occurs when the element with the given ID starts its first repeated, and any subsequent, cycle.

Tip: The beginEvent value occurs on every repeating cycle, including the first. See "Defining an Element Start or Stop Event" for more information.

Sample Values

The following are samples of begin and end values that start or stop an element relative to the repetitions of another element:


`begin="ID.repeat(3)"`	Start the element when the element with the given ID begins its third repetition (that is, when it starts to play for the fourth time).
`end="ID.repeat(2)-5s"`	Stop the element five seconds before the element with the given ID begins its second repetition.
`begin="ID.repeatEvent+10s"`	Start the element ten seconds after the second and each subsequent time the element with the given ID repeats.

Example

To use a repeat timing value, you first add an ID to the clip that will provide the basis for starting or stopping the second clip. This clip must also have a repeatCount or repeatDur attribute that causes it to repeat. In the following example, the video clip repeats three times:

<video src="video1.rm" id="main" repeatCount="3" region="video_region"/>

Next, you define the begin or end time for the second clip, using the ID of the first clip:

<img src="picture.jpg" region="img_region" dur="20s" begin="main.repeat(2)"/>

For More Information: For details on the repeatCount and repeatDur attributes, see "Repeating an Element".

Note: If an element repeats and has a negative timing offset, only the first cycle shows the effect of a clipBegin. All subsequent cycles play for their full duration.

Defining a Mouse Event

Starting or stopping an clip when a viewer clicks another clip is a common means of adding interactivity to a streaming presentation. You can also start or stop an element such as an animation when the viewer moves the screen pointer over a clip, creating an effect similar to a Javascript mouseover in a Web page. The following are the mouse-related event values that you can use with a begin or end attribute:

ID.activateEvent[+|-time_value]

This interactive event occurs when the viewer clicks on the clip with the specified ID. The target ID must be that of a clip, not a group or a region. The clip will not register the mouse click if it is rendered more than 50 percent transparent with a value from 0 to 50 for rn:mediaOpacity. See "Adding Transparency to All Opaque Colors" for more information on this attribute.

ID.inBoundsEvent[+|-time_value]

This interactive event occurs when the viewer moves the screen pointer over the clip. The "in bounds" area is the part of the clip that displays in the region. Portions of the clip cut off at the region boundaries are not affected. The event occurs even if the clip has finished playing and appears frozen onscreen. The target ID must be that of a clip, not a group or a region.

ID.outOfBoundsEvent[+|-time_value]

This interactive event occurs when the viewer moves the screen pointer off of the clip's "in bounds" area. The event occurs even if the clip has finished playing and appears frozen onscreen. The target ID must be that of a clip, not a group or a region.

The inBoundsEvent and outOfBoundsEvent values can occur for multiple clips simultaneously if clips are stacked on top of each other. The z-index value of the clips does not matter, and an event can still occur even if the clip is completely obscured by another clip.

For More Information: For details on z-index, see "Stacking Regions That Overlap".

Sample Values

The following are samples of begin and end values that start or stop an element relative to a mouse event:


begin="`ID.activateEvent"`	Start the element when the clip with the given ID is clicked.
`begin="ID.inBoundsEvent"`	Start the element when the cursor moves over the clip with the given ID.
`end="ID.outOfBoundsEvent+1s"`	Stop the element one second after the cursor moves off the clip with the given ID.

Example

Suppose that you want to start a video when an image button is clicked. You first add an ID to the clip source tag of the image:

<img src="button1.gif" id="button" dur="5s" fill="freeze" region="button_1"/>

Next, you define the begin and end times for the video, using activateEvent and the image clip's ID:

<video src="video1.rm" region="video_region" begin="button.activateEvent"/>

View it now! (requirements for viewing this sample)
The first example starts different videos when an image is clicked. The second example changes a background color when the screen pointer moves over an image.

Defining a Keyboard Event

In addition to mouse events, you can use keyboard events to start or stop elements. A keyboard event can occur when a viewer presses a key, or it can occur when a clip gains or loses the keyboard focus. When a clip has the keyboard focus, it captures all subsequent keystrokes. When a viewer clicks a form created in Flash, for example, the Flash form receives the focus. The following are begin or end event values associated with keyboard activity:

accesskey(key)[+|-time_value]

This interactive event occurs when the viewer presses the designated keyboard key. The key designation is case-sensitive. This value can be used along with activateEvent to provide multiple ways to start an element, either by mouseclick or keystroke.

ID.focusInEvent[+|-time_value]

This interactive event occurs when the clip with the designated ID receives the keyboard focus and captures subsequent keystrokes. The focus typically occurs when the viewer clicks the clip or tabs into it. The target ID must be that of a clip, not a group or a region.

ID.focusOutEvent[+|-time_value]

This interactive event occurs when the clip with the designated ID loses the keyboard focus. This typically occurs when the viewer clicks or tabs out of the clip. The target ID must be that of a clip, not a group or a region.

Sample Values

The following are samples of begin and end values that start or stop an element relative to a keyboard event:


`begin="accesskey(g)"`	Start the element when the keyboard letter "g" is pressed.
`end="ID.focusInEvent+2s"`	Stop the element two seconds after the clip with the given ID loses the keyboard focus.

Example

In the following example, the video starts playing when the keyboard letter "g" is pressed. It stops playing when the letter "h" is pressed:

<video src="video1.rm" region="video_region" begin="accesskey(g)" end="accesskey(h)"/>

Tips for Defining Keyboard Events

The access key value is case-sensitive, so the viewer cannot press g (lowercase "g") to activate the event if you specify an uppercase "G" with accesskey(G), for example. You can specify both the lowercase and uppercase versions of the same key, though, to ensure that letter case does not matter.

Access keys can be letters or numbers, but not function keys or command keys such as Alt, Esc, or F5.

Mention the access key in a longdesc attribute in the clip source tag. See "Using a Long Description" for more information.

Your presentation should indicate which access keys the viewer can use. You can do this with RealText, which is described in Chapter 6. You can also display this information in the context window, as described in "Opening HTML Pages in the Context Window".

If the same access key is encoded into a clip to perform some function, the SMIL access key overrides the encoded key's functionality.

You can also define access keys to open hyperlinks as described in "Opening a Link on a Keystroke". To avoid conflicts, do not define the same key for an event and a hyperlink.

Unlike the inBoundsEvent and outOfBoundsEvent values, which can occur for multiple clips simultaneously, only one clip at a time can have the keyboard focus at a time. Therefore, only one focusInEvent or focusOutEvent can occur at a time.

Defining a Secondary Window Event

The section "Creating Secondary Media Windows" explains how to create a layout in which a secondary media window pops up from the main media window. The following values for the begin and end attributes allow you to start or stop an element when a secondary media window opens or closes:

ID.topLayoutOpenEvent[+|-time_value]

This event occurs when the secondary media window with the designated ID opens. The event is scheduled if the <topLayout> tag for the secondary media window uses open="onStart". If the tag uses open="whenActive", the window event is scheduled if the element that plays in the window has a scheduled begin time.

The window event is interactive, though, if the element begins because of another interactive event. If clicking a clip in the main media window begins a clip that launches and plays in the secondary media window, for example, topLayoutOpenEvent is interactive.

ID.topLayoutCloseEvent[+|-time_value]

This event occurs when the window with the designated ID closes. The event is interactive if the <topLayout> tag for the secondary media window uses close="onRequest". If the tag uses close="whenNotActive", the window event is scheduled if the element that plays in the window has a scheduled end time.

The window event is interactive, though, if the element ends because of another interactive event. If clicking a clip in the main media window stops the clip or clips playing in the secondary media window, for example, topLayoutCloseEvent is interactive.

Sample Values

The following are samples of begin and end values that start or stop an element relative to a secondary media window event:


`begin="ID.topLayoutOpenEvent"`	Start the element when the secondary media window opens.
`end="ID.topLayoutCloseEvent+2s"`	Stop the element two seconds after the secondary media window closes.

Example

The following example defines a secondary media window that opens when the first clip displays in it, and closes when all clips assigned to it finish playing:

<topLayout width="180" height="120" id="popup1" open="whenActive" close="whenNotActive">

The following clip then starts three seconds after the window closes:

<video src="video1.rm" region="vid" begin="popup1.topLayoutCloseEvent+3s"/>

Using Media Markers

This section to be added.

Coordinating Clips to an External Clock

This section to be added.

Setting Minimum and Maximum Times

This section to be added.

Controlling Whether an Element Restarts

The restart attribute governs whether an element can play more than once. A clip might have multiple begin times that specify when it plays, for example, or start on an interactive event such as a mouse click. The restart attribute can prevent an element from restarting, or place restrictions on the restart. The following table summarizes the restart values.

restart Attribute Values
Value	Function
`always`	Allows the element to restart at any time, even while playing. This is the effective value that is used if the element has no `restart` value, and no `restartDefault` values are specified in any groups of which the element is a member.
`default`	Sets the `restart` value to that specified by `restartDefault`. This is the default value that is used if no `restart` value is specified, but a containing group has a `restartDefault` value.
`never`	Prevents the element from restarting after it completes its first playback.
`whenNotActive`	Allows the element to restart only after it has completed playing. The element can then restart any number of times. The restart occurs only after the element plays to completion, its `dur` or `end` time is reached, or it finishes all of its specified repeat cycles.

In the following example, a video clip starts when a button is clicked, as described in "Defining a Mouse Event". It uses the whenNotActive value to allow it to restart after it finishes playing. Nothing happens if the viewer clicks the activation button while the video plays. The viewer must wait for the video to stop, then click the button to restart the video:

<video src="video1.rm" region="video_region" begin="button.activateEvent"
restart="whenNotActive"/>

Tip: Although the restart attribute is most commonly used with clips, you can also use it in group tags and other elements, such as SMIL animations. Keep in mind, though, that an element can restart only while its containing group is active.

Setting a Default Restart Value

You can use the restartDefault attribute in a group tag to set a restart value for the group and all of the elements it contains. All elements within the group receive the default restart value unless they have another restart value explicitly set. The following table lists the possible restartDefault values.

restartDefault Attribute Values
Value	Function
`always`	Allows elements within the group to restart at any time, even while playing.
`inherit`	Sets the `restart` value for elements in the group to the `restartDefault` value of the group's containing group. This is the default value, meaning that a group without a `restartDefault` value inherits the `restartDefault` value from its containing group.
`never`	Prevents elements within the group from restarting after they complete their first playback.
`whenNotActive`	Allows group elements to restart any number of times, but only after they have completed playing. Restart attempts are recognized only after the elements have played to completion.

The following example shows an exclusive group of video clips in which the first two clips receive the restartDefault value of whenNotActive. The last clip, however, overrides that value with its own restart value:

<excl restartDefault="whenNotActive">
  <video src="video1.rm" begin="button1.activateEvent" .../>
  <video src="video2.rm" begin="button2.activateEvent" .../>
  <video src="video3.rm" begin="button3.activateEvent" restart="never" .../>
</excl>

Nested Group Interactions with Restart Values

If several levels of nested groups use restart and restartDefault, it's important to understand how the groups and their elements interact. Because elements inherit a restartDefault value by default, the interactions can be difficult to grasp unless you look at all levels of the nested groups. Consider the following abstract example:

<par id="master_group" restartDefault="whenNotActive">
  <par id="group_X" restartDefault="inherit">
    <ref id="clip_A" .../>
    <ref id="clip_B" restart="always" .../>
  </par>
  <par id="group_Y" restart="always">
    <ref id="clip_C" .../>
    <ref id="clip_D" .../>
  </par>
  <par id="group_Z" restartDefault="always">
    <ref id="clip_E" .../>
    <ref id="clip_F" restart="always" .../>
  </par>
</par>

The master group sets a restartDefault value of whenNotActive. The elements within this master group have the following restart values:

group_X set to whenNotActive

group_X inherits the default value of whenNotActive from master_group, and passes that value to the clips it contains, one of which overrides the value:

clip_A set to whenNotActive

clip_B set to always

group_Y set to always

group_Y sets its own behavior to always. However, it inherits the default value of whenNotActive from master_group, and passes that value to both clips it contains:

clip_C set to whenNotActive

clip_D set to whenNotActive

group_Z set to whenNotActive

group_Z inherits the default value of whenNotActive from master_group. However, it changes the default value for the elements it contains to always. One of the clips overrides that value:

clip_E set to always

clip_F set to whenNotActive