previous   next   contents  

6. SMIL 3.0 Content Control

Editor for SMIL 3.0
Dick Bulterman, CWI.
Editors for earlier versions of SMIL
Dick Bulterman, Oratrix/CWI
Jeffrey Ayars, RealNetworks
Thierry Michel, W3C.

Table of contents

6.1 Summary of Changes for SMIL 3.0

This section is informative.

The SMIL 3.0 specification extends the functionality SMIL 2.1 Content Control Modules [SMIL21-content-control] by introducing three new attributes: allowReorder, systemBaseProfile, and systemVersion. In addition, the new module RequiredContentControl has been defined that allows the systemRequired attribute to be specified in profiles that do not otherwise use SMIL content control. There are no new elements or other attributes provided in this version because, with the introduction of SMIL State functionality in SMIL 3.0, it is expected that new developments for managing control of content and control flow will migrate to the State-based notation. The editorial changes for SMIL 3.0 are (1) a clarification in a Normative section on expected behaviour for user agents that support dynamic evaluation and system- and/or custom-test variables, and (2) a repartitioning of the content control module structure in order to support the SMIL Tiny profile.

6.2 Introduction

This section is normative.

This section defines the SMIL 3.0 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 five modules:

Since all of the content control elements and attributes are defined in modules, designers of other markup languages may reuse this functionality on a module by module basis when they wish 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 and RequiredContentControl modules. The PrefetchControl and SkipContentControl modules have no prerequisites.

This section is informative.

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. When dynamic reevaluation is supported by a user agent, it is expected that any system- or custom-test variable will be evaluated at the beginning of a node's execution (either at its initial begin time or each time a repeated element restarts). For situations in which more explicit control over reevaluation is required, the use of the SMIL 3.0 State modules is encouraged.

6.3 The SMIL 3.0 BasicContentControl Module

This section is normative.

6.3.1 SMIL 3.0 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 3.0 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.

Predefined System Test Attributes

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 3.0 supports the full set of SMIL 2.1 system attributes. The SMIL 2.1 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 3.0's camelCase conventions. The SMIL 1.0 hyphenated names are deprecated in this release.

SMIL 3.0 also supports system test attributes that define additional characteristics of the system environment. These are:

Finally, SMIL 3.0 supports system test attributes that define characteristics of the SMIL version (starting with version 3.0) and base profile supported by the system environment. These are:

The complete definition of each attribute is given in the attributes definition section.

The switch element

The switch element allows an author to specify a set of alternative elements from which only the first acceptable element is chosen.

This section is informative.

An example of the use of the switch is:

  ...
  <par>
    <video src="anchor.mpg" ... />
    <switch>
      <audio src="dutchHQ.aiff" systemBitrate="56000" ... />
      <audio src="dutchMQ.aiff" systemBitrate="28800" ... />
      <audio src="dutchLQ.aiff" ... />
    </switch>
  </par> 
  ...

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). If all alternatives are equivalent an author should signal this through the allowReorder attribute on the switch, this gives the user agent the freedom to pick the best match (as opposed to the first match).

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 user agent 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. When dynamic reevaluation is supported by a user agent, it is expected that any system- or custom-test variable will be evaluated at the beginning of a nodes execution (either at its initial begin time or each time a repeated element restarts). For situations in which more explicit control over reevaluation is required, the use of the SMIL 3.0 State modules is encouraged. 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.

This section is informative.

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

 ...
 <par>
    <audio src="audio.rm"/>
    <video src="video.rm"/>
    <textstream src="stockticker.rt"/>
    <textstream src="closed-caps.rt" systemCaptions="on"/>
 </par>
 ...

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.

This section is informative.

Examples of Switch and Test Attribute Use

  1. Choosing between content with different total bitrates

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

     ...
     <par>
        <text .../>
        <switch>
           <par systemBitrate="40000">
           ...
           </par>
           <par systemBitrate="24000">
           ...
           </par> 
           <par systemBitrate="10000">
           ... 
           </par> 
        </switch> 
     </par> 
     ...

    In this example, if the system bitrate has been determined to be less than 10000 (in mobile telephone cases, for example), then none of the par constructs would be included.

  2. Choosing between audio resources with different bitrates

    The elements within the switch may be any combination of elements. For instance, one could specify an alternate audio track:

     ...
     <switch>
        <audio src="joe-audio-better-quality" systemBitrate="16000" /> 
        <audio src="joe-audio" />
     </switch>
     ... 

    If the system bitrate was less than 16000, the standard-quality audio would be presented by default.

  3. Choosing between audio resources in different languages

    In the following example, an audio resource is available both in Dutch and in English. Based on the user's preferred language, the player can choose one of these audio resources.

     ...
     <switch>
        <audio src="joe-audio-nederlands" systemLanguage="nl"/>
        <audio src="joe-audio-english" systemLanguage="en"/>
     </switch>
     ... 

    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:

     ...
     <switch>
        <audio src="joe-audio-nederlands" systemLanguage="nl"/>
        <audio src="joe-audio-english" />
     </switch>
     ... 

    If the alternatives are equivalent an author may specify this through the allowReorder attribute, which gives the user agent the freedom to select the second alternative for someone who speaks both German and Dutch but prefers German:

     ...
     <switch allowReorder="yes">
        <audio src="joe-audio-nederlands" systemLanguage="nl"/>
        <audio src="joe-audio-deutsch" systemLanguage="de"/>
        <audio src="joe-audio-english" />
     </switch>
     ... 

    Note that none of these examples show the full power of language tag matching, please refer to BCP47 [BCP47] for more elaborate examples.

  4. Choosing between content written for different screens

    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.

     ...
     <par>
        <text .../>
        <switch>
           <par systemScreenSize="1024X1280" systemScreenDepth="16">
           ...
           </par>
           <par systemScreenSize="480X640" systemScreenDepth="32">
           ...
           </par> 
           <par systemScreenSize="480X640" systemScreenDepth="16"> 
           ... 
           </par> 
        </switch> 
     </par> 
     ...
  5. Supporting multiple options via in-line use

    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.

      ...
      <par>
        <video src="anchor.mpg" ... />
        <audio src="dutch.aiff"   systemLanguage="nl"  ... />
        <audio src="english.aiff" systemLanguage="en" ... />
        <text  src="dutch.html"   systemLanguage="nl" systemCaption="on"... />
        <text  src="english.html" systemLanguage="en" systemCaption="on"... />
      </par> 
      ...

    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.

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

     ...
     <par>
        <switch>
           <audio src="movie-aud-en.rm" systemLanguage="en"
                 systemOverdubOrSubtitle="overdub"/>
           <audio src="movie-aud-de.rm" systemLanguage="de"
                 systemOverdubOrSubtitle="overdub"/>
           <audio src="movie-aud-nl.rm" systemLanguage="nl"
                 systemOverdubOrSubtitle="overdub"/>
           <!-- French for everyone else --> 
           <audio src="movie-aud-fr.rm"/>
        </switch> 
        <video src="movie-vid.rm"/>
        <switch> 
           <textstream src="movie-sub-en.rt" systemLanguage="en" 
                 systemOverdubOrSubtitle="subtitle"/>
           <textstream src="movie-sub-de.rt" systemLanguage="de"
                 systemOverdubOrSubtitle="subtitle"/> 
           <textstream src="movie-sub-nl.rt" systemLanguage="nl"
                 systemOverdubOrSubtitle="subtitle"/> 
           <!-- French captions for those that really want them --> 
           <textstream src="movie-caps-fr.rt" systemCaptions="on"/>
        </switch> 
     </par> 
     ...

6.3.2 Elements and Attributes

SMIL 3.0 BasicContentControl defines the switch element, the allowReorder attribute and a set of predefined system test attributes.

The switch element

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.

Element attributes

This element allows the allowReorder attribute, in addition to those required of all elements in the profile.

Element content

The content of the element is language implementation dependent.

In the SMIL 3.0 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.

The allowReorder Attribute

The allowReorder attribute signals whether a user agent may reorder the direct descendents of the switch element, based on user preferences, if it thinks this could lead to a better user experience.

The possible values are no, the default, disallowing reordering and yes, allowing reordering.

This section is informative.

User agents are free to ignore the allowReorder attribute, but if they implement prioritized language ranges as defined in BCP47 [BCP47] they are expected to use that prioritization to reorder children with systemLanguage attributes. The effect should be that the users are presented with the alternative that best matches their language preferences. Any final child without systemLanguage attribute should retain its place as the default item to present.

Authors should add the allowReorder attribute if all items in the switch are equivalent.

Predefined Test Attributes

SMIL 3.0 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.

systemAudioDesc
values: on | off
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.
systemBaseProfile
value: profile-name
Profile-name ::= "Language" | "UnifiedMobile" | "Daisy" | "Tiny" | "smilText" |User-defined-profile-name
User-defined-profile-name ::= "x-" NMTOKEN
This attribute may be used to test the base profile used by the SMIL player to execute the document. The profile name may be used to determine the presence of a set of profile-specific features. Note that since this attribute was introduced in SMIL version 3.0, only the profiles supported in that version and later may be tested with this attribute.
systemBitrate (system-bitrate)
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.
systemCaptions (system-captions)
values: on | off
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.
systemComponent
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 may 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.
systemCPU
value: an XML NMTOKEN([[XML11]).
This test attribute specifies the CPU on which a user agent may be running. An implementation must allow the user the ability to set the system value to unknown for privacy.
The following list contains the suggested values for this test attribute (additional names may be supported by an implementation): alpha, arm, arm32, hppa1.1, m68k, mips, ppc, rs6000, vax, x86, unknown.

These values come from the _PR_SI_ARCHITECTURE constants defined by the mozilla project.

Evaluates to true if the user preference matches this attribute value. Evaluates to false if they do not match. The value is case-sensitive.
systemLanguage (system-language)
values: a comma-separated list of language tags as defined in BCP47 [BCP47], or an empty/null string
Each of the language tags is matched against the users' language preferences according to the BCP47 Basic Filtering matching algorithm [BCP47]. If any language tag matches the test attribute evaluates to true, else it evaluates to false.
If a null or empty string is specified, the test attribute evaluates to false.

The syntax of the systemLanguage and the deprecated system-language attributes are defined using EBNF notation (as defined in [XML11]) as list of XML namespace prefixes [XML-NS], separated by the ',' character:

SystemLanguageArgumentValue ::= (LanguageTag (S? "," S? LanguageTag)*)?
      

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

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

This section is informative.

BCP47: This is actually an active document that can, over time, refer to newer RFCs as technology progresses. As of this writing BCP47 consists of RFC4646 for defining language tags and RFC4647 for defining the matching algorithm.

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 RFC4647 language matching, 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.

systemOperatingSystem
value: an XML NMTOKEN ([XML11])
This test attribute specifies the operating system on which a user agent may be running. An implementation must allow the user the ability to set the user preference to unknown for privacy.
The following list contains the suggested values for this test attribute (additional names may be supported by an implementation): aix, beos, bsdi, dgux, freebsd, hpux, irix, linux, macos, ncr, nec, netbsd, nextstep, nto, openbsd, openvms, os2, osf, palmos, qnx, sinix, rhapsody, sco, solaris, sonly, sunos, unixware, win16, win32, win9x, winnt, wince, unknown.

This section is informative.

These values come from the _PR_SI_SYSNAME constants defined by the mozilla project.

Evaluates to true if the user preference matches this attribute value. Evaluates to false if they do not match. The value is case-sensitive.
systemOverdubOrSubtitle
values: overdub | subtitle
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.
system-overdub-or-caption
values: caption | overdub
This test attribute has been deprecated in favor of using systemOverdubOrSubtitle and systemCaptions.
This attribute is a setting which determines if users prefer overdubbing or captioning when the option is available.
Evaluates to true if the user preference matches this attribute value. Evaluates to false if they do not match.
systemScreenDepth (system-screen-depth)
values: a number greater than 0
This attribute specifies the depth of the screen color palette in bits required for displaying the element. Typical values are 1 | 4 | 8 | 24 | 32.
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.
systemScreenSize (system-screen-size)
value: Screen-size
Attribute values have the following syntax:
Screen-size ::= Screen-height S? "X" S? 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.
systemVersion
value: 3.0 .
This attribute may be used to test the version number of the SMIL player executing the document. The number may be used to determine the presence of a set of specification-specific features. Since this attribute was introduced in SMIL version 3.0, only values of 3.0 and later may be tested with this attribute.

It is the responsibility of the SMIL 3.0 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. When dynamic reevaluation is supported by a user agent, it is expected that any system- or custom-test variable will be evaluated at the beginning of a nodes execution (either at its initial begin time or each time a repeated element restarts). For situations in which more explicit control over reevaluation is required, the use of the SMIL 3.0 State modules is encouraged.

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 3.0 Language profile, timing attributes that reference invalid IDs are treated as being indefinite.

This section is informative.

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.

6.3.3 Integration Requirements for the BasicContentControl Module

The functionality in this module does not build on functionality defined in other SMIL 3.0 modules.

6.3.4 Document Type Definition (DTD) for the BasicContentControl Module

See the full DTD for the SMIL Content Control modules.

6.4 The SMIL 3.0 CustomTestAttributes Module

This section is normative.

6.4.1 SMIL 3.0 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 may 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 may 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:

  1. by modifying the value of the default state attribute in the document source before delivery to the player;
  2. by using the unique identifier given in the uid attribute to dereference a runtime value for the customTest; or
  3. 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.

This section is informative.

Example Use

The following example shows one way in which custom test attributes may be applied within a SMIL 3.0 Language profile document:

<smil>
  <head>
    <layout>
       <!-- define projection regions -->
    </layout>
    <customAttributes>
      <customTest xml:id="west-coast" title="West Coast Edition" 
        defaultState="false" override="visible"  
        uid="http://defs.example.org/user-settings/west-coast" />
      <customTest xml:id="east-coast" title="East Coast Edition" 
        defaultState="false" override="visible" 
        uid="http://defs.example.org/user-settings/east-coast" />
      <customTest xml:id="far-north"  title="Northern Edition"
        defaultState="false" override="visible"
        uid="http://defs.example.org/user-settings/far-north" />
      <customTest xml:id="the-rest"   title="National Edition"
        defaultState="true"  override="hidden" />
    </customAttributes>
  </head>
  <body>
    ...
    <par>
      <img src="background.png" region="a"/>
      <video src="story_1v.rm" region="b" />
      <switch>
        <audio src="story_1w.rm" region="c" customTest="west-coast"/>
        <audio src="story_1e.rm" region="c" customTest="east-coast"/>
        <audio src="story_1n.rm" region="c" customTest="far-north"/>
        <audio src="story_1r.rm" region="c" customTest="the-rest"/>
      </switch>
    </par>
    ...
  </body>
</smil>

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 may 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:

  1. 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.
  2. 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.
  3. 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. When dynamic reevaluation is supported by a user agent, it is expected that any system- or custom-test variable will be evaluated at the beginning of a nodes execution (either at its initial begin time or each time a repeated element restarts). For situations in which more explicit control over reevaluation is required, the use of the SMIL 3.0 State modules is encouraged. Note also that not all implementations need support uid or UI setting of attributes.

6.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 may be used in switch statements or as in-line test attributes in the document.

Element attributes

This element does not have attributes beyond those required of all elements in the profile.

Element content

The customAttributes element may contain one or more customTest elements.

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.

Element attributes
defaultState
values: true | false
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 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.

This section is informative.

The actual evaluation mechanism associated with the URI is implementation dependent. It may 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.

Element content

None.

The customTest attribute

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 BasicContentControl 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)*
Idref ::= Name

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

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

and Idref is a Name as defined in [XML11] is a reference to a customTest element.

6.4.3 Integration Requirements for the CustomTestAttribute Module

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 3.0 Language Profile, the element's id and title attributes serve this purpose.

6.4.4 Document Type Definition (DTD) for the CustomTestAttribute Module

See the full DTD for the SMIL Content Control modules.

6.5 The SMIL 3.0 PrefetchControl Module

This section is normative.

6.5.1 SMIL 3.0 PrefetchControl Module Overview

This module defines an element and attributes that may 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 may 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.

This section is informative.

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

  1. Prefetch an image so it can be displayed immediately after a video ends:
     <smil xmlns="http://www.w3.org/ns/SMIL" version="3.0" baseProfile="Language"> 
       <body> 
         <seq>
           <par>
             <prefetch xml:id="endimage"
                src="http://www.example.org/logo.gif"/>
             <text xml:id="interlude"
                src="http://www.example.org/pleasewait.html" fill="freeze"/>
           </par>
           <video xml:id="main-event" src="rtsp://www.example.org/video.mpg"/> 
           <img src="http://www.example.org/logo.gif" dur="5s"/>  
        </seq> 
       </body> 
     </smil> 

    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.

  2. Prefetch the images for a button so that rollover occurs quickly for the end user:
     <html>
     <body>
         <prefetch xml:id="upimage" src="http://www.example.org/up.gif"/>
         <prefetch xml:id="downimage" src="http://www.example.org/down.gif"/>
         ....
         <!-- script will change the graphic on rollover -->
         <img src="http://www.example.org/up.gif"/>
       </body>
     </html>
        

6.5.2 Elements and Attributes

The prefetch element

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.

Element attributes

The prefetch element supports the following attributes:

mediaSize
values: Bytes-value | Percent-value
Defines how much of the resource to fetch as a function of the file size of the resource. To fetch the entire resource without knowing its size, specify 100%. The default is 100%.
mediaTime
values: Clock-value | Percent-value
Defines how much of the resource to fetch as a function of the duration of the resource. To fetch the entire resource without knowing its duration, specify 100%. The default is 100%.
For discrete media (non-time based media like text/html or image/png) using this attribute causes the entire resource to be fetched.
bandwidth
values: Bitrate-value | Percent-value
Defines how much network bandwidth the user agent should use when doing the prefetch. To use all that is available, specify 100%. The default is 100%.

Any attribute with a value of "0%" is ignored and treated as if the attribute wasn't specified.

If both mediaSize and mediaTime are specified, mediaSize is used and mediaTime is ignored.

If the clipBegin or clipEnd in the media object are different from the prefetch, an implementation can use any data that was fetched but the result may not be optimal.

Attribute value syntax
Bytes-value
The Bytes-value value has the following syntax:

Bytes-value ::= DIGIT+ /* any positive number */

Percent-value
The percent-val value has the following syntax:

Percent-value ::= DIGIT+ "%" /* any positive number in the range 0 to 100 */

Clock-value
The Clock-value value has the following syntax:
Clock-value       ::= ( Hms-val | Smpte-val )
Smpte-val         ::= ( Smpte-type )? Hours ":" Minutes ":" Seconds 
                      ( ":" Frames ( "." Subframes )? )?
Smpte-type        ::= "smpte" | "smpte-30-drop" | "smpte-25"
Hms-val           ::= ( "npt=" )? (Full-clock-val | Partial-clock-val 
                      | Timecount-val)
Full-clock-val    ::= Hours ":" Minutes ":" Seconds ("." Fraction)?
Partial-clock-val ::= Minutes ":" Seconds ("." Fraction)?
Timecount-val     ::= Timecount ("." Fraction)? (Metric)?
Metric            ::= "h" | "min" | "s" | "ms"
Hours             ::= DIGIT+ /* any positive number */
Minutes           ::= 2DIGIT /* range from 00 to 59 */
Seconds           ::= 2DIGIT /* range from 00 to 59 */
Frames            ::= 2DIGIT /* smpte range = 00-29, smpte-30-drop range = 00-29, smpte-25 range = 00-24 */
Subframes         ::= 2DIGIT /* smpte range = 00-01, smpte-30-drop range = 00-01, smpte-25 range = 00-01 */
Fraction          ::= DIGIT+
Timecount         ::= DIGIT+
2DIGIT            ::= DIGIT DIGIT
DIGIT             ::= [0-9]

For Timecount values, the default metric suffix is "s" (for seconds).

This note is informative

A value of three sets of colon-separated digits can be produced both by Hms-val and Smpte-val. This is however not aproblem since in both cases the values are interpreted as Hours, Minutes and Seconds.

Bitrate-value
The Bitrate-value value specifies a number of bits per second. It has the following syntax:

Bitrate-value ::= DIGIT+ /* any positive number */

6.5.3 Integration Requirements for the PrefetchControl Module

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.

6.5.4 Document Type Definition (DTD) for the PrefetchControl Module

See the full DTD for the SMIL Content Control modules.

6.6 The SMIL 3.0 SkipContentControl Module

This section is normative.

6.6.1 SMIL 3.0 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.

6.6.2 Elements and Attributes

Element definition

The SkipContentControl module does not contain any element definitions.

The skip-content attribute

skip-content
value: true | false
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.
The default value for skip-content is true.

6.6.3 Integration Requirements for the SkipContentControl Module

It is the responsibility of the language profile to specify which elements have skip-content attributes to enable this expansion mechanism.

6.7 The SMIL 3.0 RequiredContentControl Module

This section is normative.

6.7.1 SMIL 3.0 RequiredContentControl Module Overview

This module contains one attribute, systemRequired, which is used to identify one or more namespace prefixes. These prefixes may be used to define a minimum set of modules that a user agent must support to process a given SMIL file. This attribute is a critical component of the SMIL Scalability Framework.

6.7.2 Elements and Attributes

Element definition

The RequiredContentControl module does not contain any element definitions.

The systemRequired attribute

systemRequired (system-required)
value: list of namespace prefix language extensions
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'):

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

6.7.3 Integration Requirements for the RequiredContentControl Module

It is the responsibility of the language profile to specify which elements support the systemRequired attribute. In order to support the SMIL Scalability Framework, all profiles are expect to at least support this attribute on the top-level SMIL element.


previous   next   contents