4.2 Introduction

This section is informative.

This section defines the SMIL 2.1 content control modules. These modules
contain elements and attributes which provide for runtime content choices and
optimized content delivery. SMIL content control functionality is partitioned
across four modules:

Since all of the content control elements and attributes are defined in
modules, designers of other markup languages can reuse this functionality on
a module by module basis when they need to include media content control in
their language.

The functionality in the CustomTestAttributes module builds on the
functionality of the BasicContentControl module; profiles implementing the
CustomTestAttributes module must also implement the BasicContentControl
module. The PrefetchControl and SkipContentControl modules have no
prerequisites.

In some of the module descriptions for content control, the concept of
"user preference" may be present. User preferences are usually set by the
playback engine using a preferences dialog box, but this specification does
not place any restrictions on how such preferences are communicated from the
user to the SMIL player.

It is implementation dependent when content control attributes are
evaluated. Attributes may be evaluated multiple times. Dynamic reevaluation
is allowed but not required.

4.3 The SMIL 2.1
BasicContentControl Module

4.3.1 SMIL 2.1
BasicContentControl Module Overview

SMIL 1.0 provides a "test-attribute" mechanism to process an element only
when certain conditions are true, for example when the language preference
specified by the user matches that of a media object. One or more test
attributes may appear on media object references or timing structure
elements; if the attribute evaluates to true, the
containing element is played, and if the attribute evaluates to false the containing element is ignored. SMIL 1.0 also
provides the switch element for
expressing that a set of document parts are alternatives, and that the first
one fulfilling certain conditions should be chosen. This is useful to express
that different language versions of an audio file are available, and that the
client may select one of them.

The SMIL 2.1 BasicContent module includes the test attribute functionality
from SMIL 1.0 and extends it by supporting new system test attributes. This
section will describe the use of the predefined system test attributes, the
switch element and test attribute
in-line placement. A mechanism for extending test attributes is presented in
the CustomTestAttributes
module.

This specification defines a list of test attributes that can be added to
language elements, as allowed by the language designer. In SMIL 1.0, these
elements are synchronization and media elements. Conceptually, these
attributes represent Boolean tests. When any of the test attributes specified
for an element evaluates to false, the element
carrying this attribute is ignored.

SMIL 2.1 supports the full set of SMIL 1.0 system attributes. The SMIL 1.0
compatible system test attributes are:

Note that, with the exception of system-overdub-or-caption,
the names of these attributes have been changed to reflect SMIL 2.1's
camelCase conventions. The SMIL 1.0 hyphenated names are deprecated in
this release.

New to SMIL 2.1 are system test attributes that define additional
characteristics of the system environment. These are:

In this example, one audio object is selected to accompany the video
object. If the system bitrate is 56000 or higher, the object
dutchHQ.aiff is selected. If the system bitrate is at least 28800 but
less than 56000, the object dutchMQ.aiff is selected. If no other
objects are selected, the alternative dutchLQ.aiff is selected, since
it has no test attribute (thus is always acceptable) and no other test
attributes evaluated to true.

Authors should order the alternatives from the most desirable to the least
desirable. Furthermore, authors may wish to place a relatively fail-safe
alternative as the last item in the switch so that at least one item within the
switch is chosen (unless this is
explicitly not desired).

Note that some network protocols, e.g. HTTP and RTSP, support
content-negotiation, which may be an alternative to using the switch element in some cases.

It is the responsibility of the SMIL 2.1 player to determine the setting
for system test attribute values. Such settings may be determined statically
based on configuration settings, or they may be determined (and re-evaluated)
dynamically, depending on the player implementation. Players may not select
members of a switch at random.

System Test Attribute
In-Line Use

To allow more flexibility in element selection, test attributes may also
be used outside of the switch
element.

In the following example of in-line test attribute use, captions are shown
only if the user wants captions on.

The alternatives indicated by the in-line construct could be represented
as a set of switch statements,
although the resulting switch could
become explosive in size. Use of an in-line test mechanism significantly
simplifies the specification of adaptive content, especially in those cases
where many independent alternatives exist. Note, however, that there is no
fail-safe alternative mechanism (such as defining an element without a test
attribute inside of a switch) when
using test attributes in-line.

In a common scenario, implementations may wish to allow for selection
via a systemBitrate
attribute on elements. The SMIL 2.1 player evaluates each of the elements
within the switch one at a time,
looking for an acceptable bitrate value.

In this example, if the system language setting was anything other
than Dutch or English, no audio would be presented. To make a choice the
default, it should appear as the last item in the list and not contain a
test attribute. In the following fragment, English is used as the
default:

In the following example, the presentation contains alternative parts
designed for screens with different resolutions and bit-depths. Depending
on the particular characteristics of the screen, the player must use the
first alternative in which all of the test attributes evaluate to true.

This example shows a video that is accompanied by zero or more media
objects. If the system language has been set to either Dutch or English,
then the appropriate audio object will play. In addition, if the system
language has been set to either Dutch or English and systemCaptions has also been
set to on, the appropriate text files will
also be displayed.

If system language is set to something other than Dutch or English, no
objects will be rendered (except the video). Note that there is no
catch-all default mechanism when using test attributes for in-line
evaluation.

Choosing the language of overdub and subtitle tracks

In the following example, a French-language movie is available with
English, German, and Dutch overdub and subtitle tracks. The following
SMIL segment expresses this, and switches on the alternatives that the
user prefers.

4.3.2 Elements and
Attributes

The switch element allows an
author to specify a set of alternative elements. An element is selected as
follows: the player evaluates the elements in the order in which they occur
in the switch element. The first
acceptable element is selected at the exclusion of all other elements within
the switch. Implementations must NOT
arbitrarily pick an object within a switch when test attributes for all child
elements fail.

In the SMIL 2.1 language profile, if the switch is used as a direct or indirect
child of a body element, it may contain
any media object or timing structure container, or it may contain nested
switch elements. All of these
elements may appear multiple times inside the switch. If the switch is used as a direct or indirect
child of a head element, it may contain
one or more layout elements.

Predefined Test
Attributes

SMIL 2.1 defines the following system test attributes. When any of the
test attributes specified for an element evaluates to false, the element carrying this attribute is ignored.
Note that most hyphenated test attribute names from SMIL 1.0 have been
deprecated in favor of names using the current SMIL camelCase
convention. For these, the deprecated SMIL 1.0 name is shown in parentheses
after the preferred name.

This test attribute specifies whether or not closed audio
descriptions should be rendered. This is intended to provide authors
with the ability to support audio descriptions in the same way that
systemCaptions provides
text captions. The value of systemAudioDesc is used to
control object rendering in conjunction with the user's preference for
receiving audio descriptions of a media object if and when these are
available. A value of on indicates a
preference to have such descriptions rendered when available. A value
of off indicates a preference not to render
such descriptions.

Authors should place systemAudioDesc = on only on elements that they wish to render when
the user has indicated they want audio descriptions. Authors should
place systemAudioDesc
= off only on elements that they wish to
render when the user has indicated they DON'T want audio
descriptions.

Evaluates to true if the user preference
matches this attribute value. Evaluates to false if they do not match.

value: the approximate bandwidth, in
bits-per-second, available to the system.

The measurement of bandwidth is application specific, meaning that
applications may use sophisticated measurement of end-to-end
connectivity, or a simple static setting controlled by the user. In the
latter case, this could for instance be used to make a choice based on
the user's connection to the network. Typical values for modem users
would be 14400, 28800, 56000 bit/s etc. Evaluates to true if the available system bitrate is equal to
or greater than the given value. Evaluates to false if the available system bitrate is less
than the given value.
The attribute can assume any integer value greater than 0. If the value
exceeds an implementation-defined maximum bandwidth value, the
attribute always evaluates to false.

This attribute allows authors to specify a redundant text equivalent
of the audio portion of the presentation. Examples of intended use are:
audiences with hearing disabilities, those learning to read, or anyone
who wants or needs this information.

Evaluates to true if the user preference
matches this attribute value. Evaluates to false if they do not match.

value: an XML CDATA string containing one
or more white-space separated URI's.

Each URI identifies a component of the playback system, e.g. user
agent component/feature, number of audio channels, codec, HW MPEG
decoder, etc. The URI is implementation dependent. Each implementation
is encouraged to publish a list of component URIs which can be used to
identify and resolve the presence of implementation-dependent
components.

Evaluates to true if all URI's match one
of the URI's that the user agent recognizes. Evaluates to false otherwise.

values: a comma-separated list of language names
as defined in [RFC1766], or an empty/null string

This attribute evaluates to true (1) if
one of the languages indicated by user preferences exactly equals one
of the languages given in the value of this parameter, or (2) if one of
the languages indicated by user preferences exactly matches a prefix of
one of the languages given in the value of this parameter such that the
first tag character following the prefix is "-". Evaluates to false otherwise. For example, if generic English
is specified in the user preferences, it will match both "en" by case
(1) and "en-gb" (British English) by case (2), but if British English
is specified in the user preferences, it will match only "en-gb" by
case (1).
If a null or empty string is specified, the test attribute evaluates to
false.

Where allowed white space is indicated as "S", defined as follows
(taken from the [XML11] definition for 'S'):

S ::= (#x20 | #x9 | #xD | #xA)+

Implementation: When making the choice of linguistic
preference available to the user, implementers should take into account
the fact that most users are not familiar with the details of language
matching as described above, and should provide appropriate guidance.
As an example, users may mistakenly assume that on selecting "en-gb",
they will be served any kind of English document if British English is
not available. The user interface for setting user preferences should
guide the user to add "en" to get the best matching behavior.

This attribute specifies whether subtitles or overdub is rendered.
overdub selects for substitution of one
voice track for another, and subtitle means
that the user prefers the display of text in a language other than that
which is being used in the audio track.

Evaluates to true if the user preference
matches this attribute value. Evaluates to false if they do not match.

This attributes provides an extension mechanism for new elements or
attributes. Evaluates to true if all of the
extensions in the list are supported by the implementation, otherwise,
this evaluates to false. The syntax of the
systemRequired and the
deprecated system-required attributes
are defined using EBNF notation (as defined in [XML11]) as list of
XML namespace prefixes [XML-NS],
separated by the '+' character:

systemRequiredArgumentValue := NMTOKEN (S? '+' S? NMTOKEN)*

Where allowed white space is indicated as "S", defined as follows
(taken from the [XML11] definition for 'S'):

Evaluates to true if the playback engine
is capable of displaying images or video with the given color depth.
Evaluates to false if the playback engine
is only capable of displaying images or video with a smaller color
depth.

Attribute values have the following syntax:screen size ::=
screen-height"X"screen-width

Each of these is a pixel value, and must be an integer value greater
than 0.

Evaluates to true if the playback engine
is capable of displaying a presentation of the given size. Evaluates to
false if the playback engine is only
capable of displaying smaller presentations.

It is the responsibility of the SMIL 2.1 Player to determine the settings
for each predefined test variable. These values may be determined by static
configuration settings, or they may be evaluated dynamically during runtime.
Such setting and (re)evaluation behavior is implementation dependent.

For this version of SMIL elements with specified test attributes that
evaluate to false, or elements within a switch that are not selected, are
considered to be ignored and will behave as though they were not specified in
the document. Any references to these elements will be as if the elements
were not in the document. In particular, any ID references to the element
will act as if there was no element with that ID. Languages that integrate
this module must specify any additional behavior related to these ignored
elements. In the SMIL 2.1 Language profile, timing attributes that reference
invalid IDs are treated as being indefinite.

Authors should be aware that this model for handling ignored
elements may be revised in a future version of SMIL, and the related
semantics may well change. These changes should not affect implementations
that only support parse-time (or equivalent) evaluation of test attributes
and/or the switch element. However, the semantics of dynamic
re-evaluation (i.e. re-evaluation during document presentation) of test
attributes and/or switch elements are not defined in this version of SMIL;
this will be addressed in a future version.

Authors should realize that if several alternative elements
are enclosed in a switch, and none of
them evaluate to true, this may lead to situations such as a media object
being shown without one or more companion objects. It is thus recommended to
include a "catch-all" choice at the end of a switch which is acceptable in all cases.

4.4 The SMIL 2.1
CustomTestAttributes Module

4.4.1 SMIL 2.1
CustomTestAttributes Module Overview

The use of predefined system test attributes in the SMIL
BasicContentControl module provides a selection mechanism based on attributes
that are fixed within the module's definition. The CustomTestAttribute module
extends this facility with the definition of author-defined custom test
attributes. Custom test attributes allow presentation authors to define their
own test attributes for use in a specific document. Custom test attributes
may be shared among application documents using the uid attribute.

As with system test attributes, custom test attributes can be used within
timing structure and media object elements; if they evaluate to true, the containing element is activated and if they
evaluate to false, the containing element is
ignored. In this version of SMIL, an ignored element will be treated as if it
were not part of the source document. As a result, any element referencing
the ID of the ignored node will, in effect, reference an invalid ID.
Languages that integrate this module must specify any additional behavior
related to these ignored elements.

Since custom test attributes are application/document specific, they need
a mechanism to allow attribute definition and attribute setting. Attribute
definition is done via the customAttributes and customTest elements. The initial state
of any custom test attribute can be set at author-time with the defaultState attribute, which takes a
value of either true or false. This module provides an override attribute with a value hidden that gives an author the ability to discourage
runtime resetting of any attributes using these mechanisms.

The state of the attribute can be changed in one of three ways:

by modifying the value of the default state attribute in the document
source before delivery to the player;

by using the unique identifier given in the uid attribute to
dereference a runtime value for the customTest; or

by an interface presented to the user (or the user agent) through the
document player at runtime.

The exact rules for setting and modifying the values associated with
custom test attributes are given below.

An implementation may support either, both, or none of methods 2 and 3. If
method 2 is supported, the URI value in uid is simply a unique identifier and does not
imply that the runtime value must be fetched over the Web. The value may be
stored and retrieved locally, and simply identified by the uid. The precise
manner in which this is done is implementation dependent. If method 3 is
supported, the custom test attribute facility does not require any specific
UI support for direct user manipulation of the custom test attributes.

The customAttributes
element in the header contains the definition of the available custom test
attributes. Each custom test attribute, defined by the customTest element, contains an
identifier and a title (which can be used by a user agent, if available, to
label the attribute), as well as an (optional) initial state definition, a
UID that contains a unique identifier for the value setting for this
attribute and an override flag.

The custom test variables named "west-coast", "east-coast" and "far-north"
are defined with a default rendering state of false. They each contain a reference to a URI which is
used to define local settings for the respective variables.

The custom test variable "the-rest" is defined with a default rendering
setting of true.

Inside the body, a SMIL switch construct is used to select media
objects for inclusion in a presentation depending on the values of the
various custom test attributes. The first object that contains a value of
true will be rendered, and since in this example
the last option will always resolve true, it will
be rendered if no other objects resolve to true.

While this example shows switch-based use of custom test attributes,
the facility could also be applied as test attributes in in-line use.

Rules for Setting
Values

The setting of the value associated with a custom test attribute proceeds
as follows:

The initial setting is taken from the value of the defaultState attribute, if
present. If no default state is explicitly defined, a value of false is used.

Next, if a URI mechanism is supported by the implementation, the URI
defined by the uid attribute is
checked to see if a persistent value has been defined for the custom test
attribute with the associated id. If such a value is present, it is used
instead of the default state defined in the document (if any). Otherwise,
the existing initial state is maintained.

Next, if a UI-based mechanism (either via the SMIL DOM, a player GUI or
some other means) is available and a value has been set by the user, the
value associated with the custom test attribute is set to the
user-specified value. If no user preference has been defined, either the
UID-based value or the default value from the document text (in that
order) is used.

Note that a user setting of the custom test attribute will take precedence
over a URI setting. If the user has not specified a value for the attribute
then the URI setting takes precedence. As with predefined system test
attributes, this evaluation will occur in an implementation-defined manner.
The value may be (re)evaluated dynamically, but this is not required. Note
also that not all implementations need support uid or UI setting of attributes.

4.4.2 Elements and
Attributes

This section defines the elements and attributes that make up the
functionality in the SMIL CustomTestAttributes module. The customAttributes and customTest elements are used to define
custom test attribute variables and the customTest attribute is used in-line on
media object and timing structure references to control evaluation of the
containing elements.

The customAttributes element

The customAttributes
element contains definitions of each of the custom test attributes. The
contained elements define a collection of author-specified test attributes
that can be used in switch statements
or as in-line test attributes in the document.

The customTest
element

The customTest element defines
an author-specified name that will be used as the test argument in the switch element or in-line on media object
and timing structure elements. The customTest elements are defined within
the section delineated by the customAttributes elements that
make up part of the document header.

The initial state for the named custom test variable is given in the
value of this attribute. If unspecified, it defaults to false.

The run-time state for the named custom test variable may be set
according to the rules for uid
and/or override attribute
processing, if present. The values are not case-sensitive.

override

values: visible | hidden

This attribute allows the author to choose whether the ability to
override the initial state of a custom test variable should be
presented to the typical user, or whether that choice should be
reserved for users that specifically express a preference for this
access. If the value of the override attribute is visible, then the user agent should make
available to the user a means to set the custom test variable value in
its default configuration either directly, via the SMIL DOM, or by some
other mechanism. If the value of the override attribute is hidden, then the user agent should not present to
the user a means to set the custom attribute value unless the user has
expressed a preference for this access. The values are not
case-sensitive. The default value is hidden.

uid

values: A URI

The URI identifies the associated custom test for persistent use. The
user agent should use this as the key to store and retrieve values
associated with the custom test attribute, and take care that privacy
and security issues are regarded. If the permitted by the override attribute, a resolved
reference to a setting via the uid
attribute defines the initial setting of the custom test value; this
value may be overridden by the user/user-agent if permitted by the
override attribute. It is up
to the runtime environment to enforce this attribute.

The actual evaluation mechanism associated with the URI
is implementation dependent. It can vary from a simple lookup in a
local file or registry, to a secure reference via a capabilities
database, and may be influenced by other configuration settings
provided by the implementation.

In addition to the customAttributes and customTest elements, this module
provides a customTest attribute
that can be applied by language designers to media objects and timing
structure elements requiring selection. In all operational aspects, the
custom test attribute is similar to the predefined system test attribute
facility of the Basic Content Control module.

customTest

value: a list of XML identifiers

The identifiers, defined in the customTest elements, define
variables that are evaluated as test attributes. If the variables all
evaluate to true, the associated element is
evaluated, otherwise it and its content are skipped. customTest attributes whose
values don't match the identifier of a customTest element evaluate to
false.

The syntax of the customTest is defined using EBNF
notation (as defined in [XML11]) as list
of customTest element
identifier references, separated by the '+' character:

CustomTestArgumentValue := IDREF (S? '+' S? IDREF)*

Where allowed white space is indicated as "S", defined as follows
(taken from the [XML11] definition for 'S'):

The functionality in this module builds on functionality defined in the
BasicContentControl module, which is a required prerequisite for inclusion of
the CustomTestAttribute module.

The profile implementing the custom test elements and attributes must
provide a means of associating a unique XML identifier with a customTest
element, so that it can be used by the customTest attribute. And the profile
should provide a means of associating descriptive text with a customTest
element, which may be used in a GUI or other selection mechanism that may be
presented to the user. For the SMIL 2.1 Language Profile, the element's id
and title attributes serve this purpose.

4.5 The SMIL 2.1
PrefetchControl Module

4.5.1 SMIL 2.1
PrefetchControl Module Overview

This module defines an element and attributes that can be used to control
the fetching of content from a server in a manner that will improve the
rendering performance of the document.

This element will give a suggestion or hint to a user agent that a media
resource will be used in the future and the author would like part or all of
the resource fetched ahead of time to make the document playback smoother.
User-agents can ignore prefetch
elements, though doing so may cause an interruption in the document playback
when the resource is needed. It gives authoring tools or savvy authors the
ability to schedule retrieval of resources when they think that there is
available bandwidth or time to do it. A prefetch element is contained within the
body of an XML document, and its scheduling is based on its lexical order
unless explicit timing is present.

Prefetching data from a URL that changes the content
dynamically is potentially dangerous: if the entire resource isn't
prefetched, a subsequent request for the remaining data may yield data from a
newer resource. A user agent should respect any appropriate caching
directives applied to the content, e.g. no-cache 822 headers in HTTP. More
specifically, content marked as non-cacheable would have to be refetched each
time it was played, where content that is cacheable could be prefetched once,
with the results of the prefetch cached for future use.

Examples

Prefetch an image so it can be displayed immediately after a video ends:

The example starts with a prefetch in parallel with the rendering of a
text object. The text is discrete media so it ends immediately, the
prefetch is defaulted to prefetch the entire image at full available
bandwidth and the prefetch element ends when the image is downloaded.
That ends the <par> and the
video begins playing. When the video ends the image is shown.

Prefetch the images for a button so that rollover occurs quickly for
the end user:

4.5.2 Elements and
Attributes

The prefetch gives authors a
mechanism to influence the scheduling of media object transfers from a server
to the player.

Documents must still playback even when the prefetch elements are ignored, although
rebuffering or pauses in presentation of the document may occur. If the
prefetch for a prefetch element is
ignored, any timing on the element is still respected, e.g. if a prefetch element has a dur="5s", elements that depend on the prefetch element's timing behave as if
the prefetch took 5 seconds.

The intrinsic duration of a prefetch element is either the duration
of the media fetch, if the prefetch operation is supported by the
implementation, or zero if prefetch is not supported.

If a prefetch element is
repeated, due to restart or repeat on a parent element the prefetch operation
should occur again. This insures appropriately "fresh" data is displayed if,
for example, the prefetch is for a banner ad to a URL whose content changes
with each request.

A profile integrating the PrefetchControl module must add the attributes
necessary to specify the media to be fetched. In general, these will be the
same resource specifying attributes as those on the media elements
themselves. In addition, the profile must add any necessary attributes to
control the timing of the prefetch
element.

4.6 The SMIL 2.1
SkipContentControl Module

4.6.1 SMIL 2.1
SkipContentControl Module Overview

This module contains one attribute, skip-content attribute, that can be
used to selectively control the evaluation of the element on which this
attribute appears. This attribute is introduced for future extensibility of
SMIL. The functionality is unchanged from SMIL 1.0.

4.6.2 Elements and
Attributes

Element definition

The SkipContentControl module does not contain any element definitions.

This attribute controls whether the content of an element is
evaluated or should be skipped.

If a new element is introduced in a future version of language
allowing markup from a previous version of the language as element
content, the skip-content attribute
controls whether this content is processed by the user agent.

If an empty element in a version of a language becomes non-empty
in a future SMIL version, the skip-content attribute
controls whether this content is ignored by a user agent, or
results in a syntax error.

If the value of the skip-content attribute is true, and one of the cases above apply, the
content of the element is ignored. If the value is false, the content of the element is
processed.