previous   next   contents  

13. SMIL 3.0 State

Editors for SMIL 3.0
Jack Jansen, CWI
Julien Quint, DAISY Consortium

Table of contents

13.1 Overview and Summary of Changes for SMIL 3.0

This section is informative.

The modules defined in this chapter are all new modules which were not part of the SMIL 2.1 specification.

13.2 Introduction

This section is informative.

A SMIL 2.1 presentation has a lot of state that influences how the presentation runs. Or, to rephrase that in a procedural way, state that influences decisions that the SMIL scheduler makes. All this state is either implicit in the presentation (what nodes are active and how long into their duration they are, how many iterations of a repeat we have done, which nodes in an excl are paused because a higher priority node has preempted them, etc.), or completely external to the presentation (system tests and custom tests).

This has the effect that the only control flow that the SMIL author has at his/her disposal is that which is built in to the language, unless the SMIL engine includes some scripting language component and a DOM interface to the document that the author can use to create more complex logic.

The modules in this section provide a mechanism whereby the document author can create more complex control flow than what SMIL provides through the timing and content control modules, without having to go all the way of using a scripting language. One way to provide this is to allow a document to have some explicit state (think: variables) along with ways to modify, use and save this state.

In addition, the mechanisms that the SMIL BasicContentControl and CustomTestAttributes modules provide for testing values are limited: basically one can only test for predefined conditions being true (not for them being false) and there is a limited form of testing for multiple conditions with "and" being the only boolean operator.

Application areas include things like quizzes, interactive adaptation of presentations to user preferences, computer-aided instruction and distant learning.

This section is informative.

The design of these modules was done after meeting with the W3C Backplane Group (part of the Hypertext Coordination Group) and various choices were influenced by the direction that group is taking.

These modules therefore borrow heavily from work done by other W3C working groups:

The intention of these modules it to provide authors with the minimum functionality required to create compelling presentations, not to import all functionality from the standards they were lifted from, and concentrate on the timing integration issues. Applications requiring a richer set of primitives should import, for example, the XForms data model through the XML namespace mechanism.

13.4 Module Overview

This section is normative.

This chapter defines the following modules:

13.5 The SMIL StateTest Module

13.5.1 Changes for SMIL 3.0

This section is informative.

The SMIL 3.0 StateTest Module defined in this document is a new module which was not part of the SMIL 2.1 specification.

13.5.2 Overview

This section is informative.

The mechanisms that the BasicContentControl and CustomTestAttributes modules provide for testing values are limited: basically one can only test for predefined conditions being true (not for them being false) and by specifying multiple system test attributes an author has a way to simulate an and operator but that is all.

This module introduces a generalized expr attribute that contains an expression. If the expression evaluates to false the element carrying the attribute is ignored. If the expression evaluates to true or if there is any error (this ranges from expression syntax errors and type errors to unavailability of the expression language engine) the element is treated normally.

13.5.3 Elements and Attributes

This section is normative.

The expr Attribute

expr
This attribute contains an expression that is evaluated at runtime, i.e. each time the element becomes active. If the expression evaluates to false the element is ignored (including its hierarchy of descendants). If the expression specified in the expr attribute cannot be resolved to a boolean, user-agents must ignore the expr attribute.
Any profile using this module needs to define the language used to specify the expression.

This section is informative.

The SMIL 3.0 Language Profile specifies that XPath 1.0 is used as the default expression language, and the context in which the expressions are evaluated is as follows:

Alternative expression languages that could be used are a scaled down form of XPath as used by DI, or EcmaScript, Python, Lua or any other language suitable for the application domain of the profile. Need to add references.

Note that there is a slight but important semantic difference between using content control attributes and using expr: the latter is guaranteed to be dynamically evaluated at runtime and can therefore be used for more dynamic control whereas there is no such guarantee for the former.

13.5.4 Functions

This section is normative.

This module defines a set of functions for use in the expr attribute (possibly in addition to functions already defined in the expression language). The naming convention used for the functions is compatible with XPath 1.0 expressions, a profile using this module with another expression language must specify a transformation that needs to be applied to these function names to make them compatible with the expression language specified.

boolean smil-audioDesc()
Corresponds to systemAudioDesc.
number smil-bitrate()
Corresponds to systemBitrate.
boolean smil-captions()
Corresponds to systemCaptions.
boolean smil-component(string uri)
Corresponds to systemComponent, checks for availability of a single playback component.
boolean smil-customTest(string name)
Corresponds to customTest, checks the current state of the given custom test.
string smil-CPU()
Related to systemCPU. This function returns the CPU on which the user agent runs.
number smil-language(string lang)
Related to systemLanguage. The string argument should be a BCP47 [BCP47] language tag. If the language does not match any language range in the users' preferences the function returns 0. If the tag does match the function returns a positive number, such that languages that match higher in the language priority list return a higher number.
string smil-operatingSystem()
Related to systemOperatingSystem. This function returns the operating system on which the user agent runs.
string smil-overdubOrSubtitle()
Values: overdub or subtitle
Corresponds to systemOverdubOrSubtitle.
boolean smil-required(string uri)
Corresponds to systemRequired.
number smil-screenDepth()
Corresponds to systemScreenDepth.
number smil-screenHeight()
Related to systemScreenSize, returns the height of the screen in pixels.
number smil-screenWidth()
Related to systemScreenSize, returns the width of the screen in pixels.

13.5.5 Examples

This section is informative.

Here is a SMIL 3.0 Language Profile example of an audio element that is only played if audio descriptions are off and the internet connection is faster than 1Mbps. Think of using it for playing background music only when this will not interfere too much with the real presentation:

   <audio src="background.mp3" 
             expr="not(smil-audioDesc()) and smil-bitrate() &gt; 1000000" />
   

Here is an example that will show the image colour.jpg to most english-speaking people. However, people preferring American English over other variants of english will see color.jpg. Non-english speaking people will see couleur.jpg.

    <switch>
      <img src="color.jpg" expr="smil-systemLanguage('en-us') &gt;= smil-systemLanguage('en')" />
      <img src="colour.jpg" expr="smil-systemLanguage('en')" />
      <img src="couleur.jpg" />
    </switch>
   

13.6 The SMIL UserState Module

13.6.1 Changes for SMIL 3.0

This section is informative.

The SMIL 3.0 UserState Module defined in this document is a new module which was not part of the SMIL 2.1 specification.

13.6.2 Overview

This section is informative.

This section introduces a data model that document authors can refer to in the context of the expr attribute, allowing elements to be rendered depending on author-defined values. A mechanism to change values in the data model is also included.

The actual choice of the expression language is made in the language profile. The SMIL 3.0 Language Profile requires support for the XPath 1.0 expression language (but allows use of other languages as well).

13.6.3 Elements and Attributes

This section is normative.

The UserState module defines the elements state, setvalue, newvalue and delvalue and the attributes language, ref, where, name and value.

The state Element

The state element sets global, document-wide, information for the other elements and attributes in this module. It selects the expression language to use and it may also be used to initialize the data model.

Initialization of the data model may be done in-line, through the contents of the state element, or from an external source through the src attribute (defined in the Media Object Modules section).

Element Attributes

The state element accepts the language and src attributes.

The setvalue Element

The setvalue element modifies the value of an item in the data model, similar to the corresponding element from XForms, but it takes its time behaviour from the SMIL ref element.

Note that setvalue only modifies existing items, it is therefore an error to specify a non-existing item, depending on the expression language semantics. In case of such an error SMIL Timing semantics of the element are not affected.

The setvalue supports all timing attributes, and participates normally in timing computations. The effect of setvalue happens when it becomes active.

Element Attributes

The setvalue element accepts the ref and value attributes. Both of these are required attributes.

The newvalue Element

The newvalue element introduces a new, named, item into the data model.

The newvalue supports all timing attributes, and participates normally in timing computations. The effect of newvalue happens at the beginning of its simple duration. Depending on the semantics of the expression language it may be an error to execute the newvalue element more than once. In case of such an error SMIL Timing semantics of the element are not affected.

The ref and where determine where in the data model the new item is introduced. If the expression language does not support a hierarchical namespace these attributes are ignored. The name attribute determines the name for the new item.

Element Attributes

The newvalue element accepts the ref, where, name and value attributes. Which of these are required depends on the expression language.

The delvalue Element

The delvalue element deletes a named item from the data model.

The delvalue supports all timing attributes, and participates normally in timing computations. The effect of delvalue happens at the beginning of its simple duration. Depending on the semantics of the expression language deletion of variables may not be supported, or it may be an error to execute the delvalue element on a non-existing item. In case of such errors SMIL Timing semantics of the element are not affected.

Element Attributes

The delvalue element accepts the ref attribute.

The language Attribute

The language attribute selects the expression language to use. Its value should be a URI defining that language. The default value for this attribute is defined in the profile.

SMIL implementations should allow expression language availability to be tested through the systemComponent attribute.

The ref Attribute

The ref attribute indicates which item in the data model will be changed. The language used to specify this, plus any additional constraints on the attribute value, depend on the expression language used.

This section is informative.

The reason that newvalue has both a ref and a name attribute is that some languages, notably XPath 1.0, do not support ref referring to a non-existing named item in the data model. Therefore, name is used to give the name for the new item and ref and where specify where it is inserted. For expression languages without a hierarchical namespace ref and where should be omitted and only name is needed.

This section is informative.

For the SMIL 3.0 Language Profile the value of the ref attribute is an XPath expression that must evaluate to a node-set. It is an error if the node-set does not refer to exactly one node.

The where Attribute

The where attribute indicates where in the data model the new item will be inserted, if the expression language supports a hierarchical data model. The allowed values are before, after and child, the default.

The name Attribute

The name attribute specifies the name for the new data model item. This name must adhere to constraints set by the expression language used.

The value Attribute

The value attribute specifies the new value of the data model item referred to by the ref element. How the new value is specified in the value attribute is defined in the profile that includes this module. This specification also states whether only simple values are allowed or also expressions, and when those expressions are evaluated.

If a statically-typed language is used as the data model language it is an error if the type of the value expression cannot be coerced to the type of the item referred to by the ref.

13.6.4 Examples

This section is informative.

Here is a SMIL 3.0 Language Profile example of a sequence of audio clips that remembers the last audio clip played, omitting the state declaration in the head for brevity:

   <seq>
       <audio src="chapter1.mp3" />
       <setvalue ref="lastPlayed" value="1" />
       <audio src="chapter2.mp3" />
       <setvalue ref="lastPlayed" value="2" />
       <audio src="chapter3.mp3" />
       <setvalue ref="lastPlayed" value="3" />
   </seq>
   

Here is an extension of the previous example: not only is the last clip remembered but if this sequence is played again, later during the presentation, any audio clips played previously are skipped:

   <seq>
       <seq expr="lastPlayed &lt; 1">
           <audio src="chapter1.mp3" />
           <setvalue ref="lastPlayed" value="1" />
       </seq>
       <seq expr="lastPlayed &lt; 2">
           <audio src="chapter2.mp3" />
           <setvalue ref="lastPlayed" value="2" />
       </seq>
       <seq expr="lastPlayed &lt; 3">
           <audio src="chapter3.mp3" />
           <setvalue ref="lastPlayed" value="3" />
       </seq>
   </seq>
   

13.6.5 Data Model

This section is informative.

As stated before, the actual choice of an expression language and data model is made in the profile that includes this module, but for ease of reading this section describes the choices in the SMIL 3.0 Language Profile: XPath 1.0 operating on a simple XML document contained in the state element.

It is important to note that the data model is an XML document. This is not to be confused with the variable bindings in the expression context, another namespace that XPath has. These variable bindings are not supported through SMIL State. Therefore references to state elements are node-set expressions, not $name-style variable references. This usage allows for nested variables and more complex data structures than the flat namespace of the variable bindings provides. SMIL follows the lead of XForms here.

The state element, of which at most one may occur, in the head section, should either be empty or contain a valid XML document. Therefore it should have at most one child element. Alternatively, if the src attribute is used to specify an external XML document the state element itself should be empty.

The XPath context in which the expressions are evaluated is as follows:

This context means that an expression of the form count has the same meaning as one of the form /data/count. Moreover, the XPath type conversion rules result in count + 1 in meaning the exact same things as number(/data/count) + 1.

Data Model Examples

Here is the minimal state section that corresponds to the audio clip example above:

    <smil>
     <head>
      <state>
         <data xmlns="">
          <lastPlayed>0</lastPlayed>
         </data>
      </state>
      ...
  

Expression Constraints

The UserState module does not constrain the data model and expressions of the underlying language, unless specifically done so in a profile. For ease of reading most examples in this document use simple variable-style names, but richer constructs, such as setting attribute values with XPath or using compound values in Python, are allowed.

13.6.6 Data Model Events

This section is informative.

Supported events for event-based timing are formally specified in the profile. For ease of reading we include the relevant event defined in the SMIL 3.0 Language Profile here as well. The purpose of these events is to allow document authors to create documents (or sections of documents) that restart and re-evaluate conditional expressions whenever the values underlying the expressions have changed.

stateChange(ref)
Raised by the state element. The parameter is a reference to an item in the data model. whenever the referenced data model item or any of its descendants is changed this event is raised. The event does not bubble.
contentControlChange(attrname)
Raised by the root of the SMIL document (is this a good idea?) when the named Content Control test values has changed. The list of allowed values for attrname is taken from the Content Control Module attribute names. The event does not bubble.
contentControlChange
Raised by the root of the SMIL document (is this a good idea?) when any Content Control test value has changed. The event does not bubble.

Raising the stateChange event on the state element instead of on the data model element itself allows for external data models (which have a distinct xmlid-space) and on non-XML data models (depending on the expression language).

If any of the Content Control test values changes both the specific event and the general event are raised. This is because for some documents the author will want to react to a change in a specific parameter (bandwidth, screensize) only, whereas for other use cases the author may want to reconfigure the whole presentation on any change.

13.7 The SMIL StateSubmission Module

13.7.1 Changes for SMIL 3.0

This section is informative.

The SMIL 3.0 UserState Module defined in this document is a new module which was not part of the SMIL 2.1 specification.

13.7.2 Overview

This section is informative.

This section introduces a method to save author defined state or to transmit it to an external server.

13.7.3 Elements and Attributes

This section is normative.

The StateSubmission module defines two elements, submission and send, and the attributes submission, action, method, replace and target.

The submission Element

The submission element carries the information needed to determine which parts of the data model should be sent, where it should be sent and what to do with any data returned. The ref attribute selects the portion of the data model to transmit and in case of XPath should be a node-set expression. The default is to transmit the whole data model (in case of xpath: "/"). The other attributes are explained below.

Element Attributes

The submission element accepts the ref, action, method, replace and target attributes.

This section is informative

This element was lifted straight from XForms, with the accompanying attributes. Support for asynchronous submission and the corresponding events are not needed because of SMIL's inherent parallelism.

The send Element

The send element causes the data model, or some part of the data model, to be submitted to server, saved to disk or transmitted externally through some other method. It does not specify any of this directly but contains only a reference to such submission instructions.

The send supports all timing attributes, and participates normally in timing computations. The effect of send happens at the beginning of its simple duration.

Element Attributes

The send element accepts the submission attribute.

The submission Attribute

The submission attribute is an IDREF that should refer to a submission element.

The action Attribute

A URL specifying where to transmit or save the nodeset. Which URLs are allowable must take security and privacy considerations into account. We need to follow the XForms lead here. Add some references.

The method Attribute

How to serialize and transmit the data. Allowed values are at least post and get but may be extended by the profile.

The replace Attribute

What to replace with the reply. Allowed values are all for the whole SMIL presentation, instance for the instance data, none for nothing.

The target Attribute

If the value of replace is instance, the optional target attribute specifies which part of the data model to replace. The default is to replace the whole instance.

This section is informative.

The SMIL 3.0 Language Profile includes the StateSubmission module, and it defines that the submission element must occur in the head section.

13.7.4 Examples

This section is informative.

Here is an example of asynchronous submission: whenever the lastPlayed item changes because another clip has been played this fact is communicated to some server.

      <smil>
       <head>
        <state xml:id="stateid">
           <data xmlns="">
            <lastPlayed>0</lastPlayed>
           </data>
        </state>
        <submission xml:id="subid" action="http://www.example.com/savexmldoc" >
       </head>
       <body>
        <par>
         <send submission="subid" begin="stateid.stateChange(/)" restart="always" replace="none"/>
         ...
         <seq end="... some interactive end condition ..." >
          <seq expr="lastPlayed &lt; 1">
           <audio src="chapter1.mp3" />
           <setvalue ref="lastPlayed" value="1" />
          </seq>
          <seq expr="lastPlayed &lt; 2">
           <audio src="chapter2.mp3" />
           <setvalue ref="lastPlayed" value="2" />
          </seq>
          <seq expr="lastPlayed &lt; 3">
           <audio src="chapter3.mp3" />
           <setvalue ref="lastPlayed" value="3" />
          </seq>
         </seq>
        </par>
  

In another presentation we could pick this value up again synchronously and use it.

    <smil>
     <head>
      <state>
      </state>
      <send xml:id="subid" action="http://www.example.com/loadxmldoc" replace="instance">
     </head>
       <body>
      <par>
       ...
       <seq >
        <submit submission="subid" />
        <seq expr="lastPlayed &lt; 1">
         <audio src="chapter1.mp3" />
         <setvalue ref="lastPlayed" value="1" />
        </seq>
        <seq expr="lastPlayed &lt; 2">
         <audio src="chapter2.mp3" />
         <setvalue ref="lastPlayed" value="2" />
        </seq>
        <seq expr="lastPlayed &lt; 3">
         <audio src="chapter3.mp3" />
         <setvalue ref="lastPlayed" value="3" />
        </seq>
       </seq>
      </par>
  

That last example is actually a procedural roundabout way to get the same effect as using <state src="http://www.example.com/loadxmldoc" /> without submissions.

13.8 The SMIL StateInterpolation Module

13.8.1 Changes for SMIL 3.0

This section is informative.

The SMIL 3.0 StateInterpolation Module defined in this document is a new module which was not part of the SMIL 2.1 specification.

13.8.2 Overview

This section is normative.

This section introduces a mechanism whereby document authors can use values from the data model to construct attribute values at runtime. The mechanism has been borrowed from XSLT attribute value templates.

Substitution is triggered by using the construct {expression} anywhere inside an attribute value. The expression is evaluated, converted to a string value and substituted into the attribute value.

This substitution happens when the element containing the attribute with the {expression} attribute becomes active.

If any error occurs during the evaluation of the expression no substitution takes place, and the {expression} construct appears verbatim in the attribute value.

If a profile includes this module it must list all attributes for which this substitution is allowed. It must use the same expression language for interpolation as the one used for StateTest expressions.

13.8.3 Elements and Attributes

This section is normative.

This module does not define any new elements or attributes.

This section is informative

The SMIL 3.0 Language Profile includes the StateInterpolation module. It allows its use in the same set of attributes for which SMIL animation is allowed plus the src, href, clipBegin, clipEnd and clipBegin attributes. It disallows its use on the Timing and Synchronization attributes. Its use on other attributes is implementation-dependent.

13.8.4 Examples

This section is informative.

This SMIL 3.0 Language Profile example shows an icon corresponding to the current CPU on which the user views the presentation, or a default icon for an unknown CPU:

   <switch>
    <img src="cpu-icons/{smil-CPU()}.png" />
    <img src="cpu-icons/unknown.png" />
   </switch>
  

13.8.5 StateInterpolation, Animation and DOM access

This section is normative.

Because StateInterpolation can also change attribute values its interaction with animation and DOM access needs to be defined, the so-called "sandwich model". StateInterpolation sits between DOM access and animation, i.e. DOM access will see the {expression} strings verbatim and it may set these values too. SMIL animation will operate on the value of the expression.


previous   next   contents