W3C

Synchronized Multimedia Integration Language (SMIL 3.0)

W3C Working Draft 20 December 2006

This version:
http://www.w3.org/TR/2006/WD-SMIL3-20061220/
Latest SMIL 3 version:
http://www.w3.org/TR/SMIL3/
Latest SMIL Recommendation:
http://www.w3.org/TR/SMIL/
Previous version:
(this is the first publication)
Editors:
Dick Bulterman, CWI - Pablo Cesar, CWI - Samuel Cruz-Lara, INRIA - Marisa DeMeglio, DAISY Consortium - Xabiel García Pañeda, Universidad de Oviedo - Luiz Fernando Gomes Soares, PUC-RIO - Jack Jansen, CWI - Hiroshi Kawamura, NRCD - David Melendi, Universidad de Oviedo - Thierry Michel, W3C - Sjoerd Mullender, CWI - Julien Quint, DAISY Consortium - Petri Vuorimaa, HUT - Daniel Weck, NRCD - Daniel F. Zucker, ACCESS Co., Ltd.

This document is also available in a non-normative format. single HTML file.


Abstract

This document specifies the third version of the Synchronized Multimedia Integration Language (SMIL, pronounced "smile"). SMIL 3.0 has the following design goals:

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document is a First Public Working Draft of the W3C. This document has been produced by the SYMM Working Group as part of the W3C Synchronized Multimedia Activity. The goals of the SYMM Working Group are discussed in the SYMM Working Group Charter. The authors of this document are the SYMM Working Group members. Different parts of the document have different editors.

This SMIL 3.0 edition is a new version, it extends the functionalities contained in SMIL 2.1 [SMIL21], incorporating new features useful within the industry.

Comments on this document are welcome. Please send them to the public mailing www-smil@w3.org - (public archives) including the prefix'[SMIL30 FWD]' in the subject line.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Quick Table of Contents

Full Table of Contents

1. About SMIL 3.0

Editor
Thierry Michel, W3C.

1.1 Introduction

This section is informative.

This document specifies the third version of the Synchronized Multimedia Integration Language (SMIL, pronounced "smile"). SMIL 3.0 has the following design goals:

SMIL 3.0 is defined as a set of markup modules, which define the semantics and an XML syntax for certain areas of SMIL functionality.

1.2 Content of this Specification

This section is informative.

This specification is structured as a set of sections, each defining one or more modules:

This specification also defines seven Profiles that are built using the above SMIL 3.0 modules.

1.3 Relation to SMIL 2.1

This section is informative.

SMIL 3.0 is a new version. It is build on top of SMIL 2.1.
A large number of SMIL 2.1 Modules [SMIL21-modules] remain the same in SMIL 3.0.
SMIL 3.0 introduces new SMIL 3.0 Modules with extented functionalities.

SMIL 3.0 also defines three new profiles that are built using the SMIL 3.0 modules specified in this specification.

If this specification is approved as a W3C Recommendation, it will supersede the 13 December 2005 version of the SMIL 2.1 Recommendation [SMIL21].

Note: SMIL document players, those applications that support playback of "application/smil+xml" documents, and host language conformant document profiles must support the deprecated SMIL 2.1 functionalities as well as the new SMIL 3.0 functionalities.

1.4 Summary of Changes for SMIL 3.0

This section is informative.

1- The following sections remain unchanged from SMIL 2.1 [SMIL21].

The modules, elements and attributes semantics in the following sections remain the same as in SMIL2.1.
The following sections links are the equivalent sections of the SMIL 2.1 Recommendation [SMIL21].

2- The following sections are updated from SMIL 2.1 [SMIL21].

In these sections, updated or new modules are introduced where new and updated elements or attributes semantics are specified. The Language Profile has also been updated:

3- The following sections are new in SMIL 3.0.

1.5 Acknowledgements

This document has been prepared by the Synchronized Multimedia Working Group (SYMM WG) of the World Wide Web Consortium.
The SYMM WG which specified SMIL 3.0 included the following individuals:

Dick Bulterman, CWI - Pablo Cesar, CWI - Ioannis Christou, AIT - Samuel Cruz-Lara, INRIA - Marisa DeMeglio, DAISY Consortium - Xabiel García Pañeda, Universidad de Oviedo - Luiz Fernando Gomes Soares (Invited Experts) - Eric Hyche, RealNetworks - Jack Jansen, CWI - Hiroshi Kawamura, NRCD - Nabil Layaïda, INRIA - David Melendi, Universidad de Oviedo, Thierry Michel, W3C - Sjoerd Mullender, CWI - Julien Quint, DAISY Consortium - Petri Vuorimaa, Helsinki University of Technology - Daniel Weck, NRCD - Daniel Zucker, Access Co., Ltd.

The former SYMM WG which specified the previous SMIL versions included the following individuals:

Kazuhide Tanaka, ACCESS Co., Ltd. - Hanan Rosenthal, Canon - Jin Yu, Compaq - Pietro Marchisio, CSELT - Lynda Hardman, CWI - Jacco van Ossenbruggen, CWI - Lloyd Rutledge, CWI - Ishan Vaishnavi, CWI - Markku Hakkinen, DAISY Consortium - Olivier Avaro, France Telecom - Vincent Mahe, France Telecom - Ted Wugofski, Gateway (Invited Expert) - Masayuki Hiyama, Glocomm - Keisuke Kamimura, Glocomm - Michelle Y. Kim, IBM - Steve Wood, IBM - Jeff Boston, IBM - Nabil Layaïda, INRIA - Muriel Jourdan, INRIA - Aaron Cohen, Intel - Wayne Carr, Intel - Masaru Sugano, KDDI Corporation - Tomoyuki Shimizu, KDDI Corporation - Marcel Wong, Ericsson - Ken Day, Macromedia - Daniel Weber, Panasonic - Patrick Schmitz, Microsoft - Debbie Newman, Microsoft - Pablo Fernicola, Microsoft - Aaron Patterson, Microsoft - Kevin Gallo, Microsoft - Paul David, Microsoft - Don Cone, Netscape/AOL - Wo Chang, NIST - Guido Grassel, Nokia - Didier Chanut, Nokia - Antti Koivisto, Nokia - Andrei Popescu, Nokia - Roberto Castagno, Nokia - Jack Jansen, Oratrix - Sjoerd Mullender, Oratrix - Dick Bulterman, Oratrix - Kenichi Kubota, Panasonic - Warner ten Kate, Philips - Ramon Clout, Philips - Jeff Ayars, RealNetworks - Erik Hodge, RealNetworks - Rob Lanphier, RealNetworks - Bridie Saccocio, RealNetworks - Eric Hyche, RealNetworks - Robin Haglund, RealNetworks - Yoshihisa Gonno, Sony Corporation - Geoff Freed, WGBH - Philipp Hoschka, W3C - Philippe Le Hégaret, W3C - Thierry Michel, W3C.

2. The SMIL 3.0 Modules

Editor:
Thierry MICHEL, W3C.

2.1 Introduction

This section is informative.

Since the publication of SMIL 1.0 [SMIL10], interest in the integration of SMIL concepts with the HTML, the HyperText Markup Language [HTML4], and other XML languages, has grown. Likewise, the W3C HTML Working Group has specified XHTML, the Extensible HyperText Markup Language [XHTML10], in preparation to subset, extend, and integrate it with other languages. The strategy considered for integrating respective functionality with other XML-based languages is based on the concepts of modularization and profiling [SMIL-MOD], [XMOD].

Modularization is an approach in which markup functionality is specified as a set of modules that contain semantically-related XML elements, attributes, and attribute values. Profiling is the creation of an XML-based language through combining these modules, in order to provide the functionality required by a particular application.

Profiling introduces the ability to tailor an XML-based language to specific needs, e.g. to optimize presentation and interaction for the client's capabilities. Profiling also adds the ability for integrating functionality from other markup languages, releasing the language designer from specifying that functionality. Moreover, it provides for consistency in markup through the use of the same model to incorporate a function. Identical constructs ease authoring, while at the user agent side there is a potential for re-use of code. For example, a scheduler supporting SMIL timing and synchronization functionality could be used for SMIL documents, XHTML+SMIL documents, and SVG documents.

Modularization enables language designers to specify dedicated markup intended for integration with other, existing, language profiles. Examples of specifications intended for such integration are MathML and XForms [MathML], [XFORMS].

Modularization and profiling use the extensibility properties of XML, and related technology like XML namespaces and XML Schema [XML11], [XML-NS], [XSCHEMA].

This part of the SMIL 3.0 specification describes the framework on which SMIL modularization and profiling is based, and specifies the SMIL 3.0 Modules, their identifiers, and the requirements for conformance within this framework.

2.1.1 Modularization and Profiling

This section is informative.

The modularization approach used in this specification derives from that set forth in XHTML Modularization [XMOD]. The framework on which SMIL modularization and profiling is based, is informally described here.

A Module is a collection of semantically-related XML elements, attributes, and attribute values that represents a unit of functionality. Modules are defined in coherent sets. This coherency is expressed in that the elements of these modules are associated with the same namespace.

A Language Profile is a combination of modules. Modules are atomic, i.e. they cannot be subset when included in a language profile. Furthermore, a module specification may include a set of integration requirements, to which language profiles that include the module must comply.

Commonly, there is a main language profile that incorporates nearly all the modules associated with a single namespace. For example, the SMIL 3.0 Language Profile uses most of the SMIL 3.0 modules. Usually, the same name is used to loosely reference both - "SMIL 3.0" in the example. Also, the name "profile" is used to mean "language profile".

Other language profiles can be specified that are subsets of the larger one, or that incorporate a mixture of modules associated with different namespaces. SMIL 3.0 Basic is an example of the first, XHTML+SMIL of the latter.

A special module in a language profile is the so-called Structure Module, in that it contains the root element of the language profile, e.g. <smil> or <html>. Any language profile that incorporates modules associated with a single namespace will include the Structure module associated with that namespace.

Other modules that require special mention are those that characterize the core of the functionality provided by the namespace. This is expressed by the notions of host language and integration set. Both of them relate to a set of conformance requirements for language profiles, which includes the requirement to incorporate at least the core set of modules. The set may be different for a host language and an integration set. A host language must incorporate the Structure module; an integration set need not. There may be other differences as well.

The main purpose of language profile conformance is to enhance interoperability. Preferably, the mandatory modules for host language conformance are defined in such a way that any document interchanged in a conforming language profile will yield a reasonable presentation when the document renderer, while supporting the associated mandatory module set, would ignore all other (unknown) elements and attributes. Here, "reasonable presentation" is to be understood as something intelligible, which is not necessarily a close reflection of the author's original intentions. To achieve the latter, a negotiation would have to be conducted to agree on the specific language profile to be used for the document interchange.

2.2 Summary of Changes for SMIL 3.0

This section is informative.

SMIL 3.0 specification provides two classes of changes to the SMIL 2.1 Recommendation, among the functional areas;

  1. New Modules are introduced (e.g. the MediaPanZoom module, BasicText, TextStyling, TextFlow modules and StateTest, UserState, StateSubmission, StateInterpolation modules and BasicTimesheets module)
  2. Former SMIL Modules are revised allowing extended functionalities (example are Metainformation, BasicLayout, MediaParam modules)

The following functional areas are affected by SMIL 3.0:

Content Control

Layout

SMIL 3.0 extends the Layout capabilities as follows:

Linking

SMIL 3.0 linking integrates the general features of the XHTML-2 access and role attributes as an extension and replacement for the accessKey attribute. This is expected to result in the deprecation or removal of the accesskey attribute and the accesskey event from the SMIL 2.1 language.

Media Object

Text

This new SMILtext functionality provides a new media type for use in SMIL presentations. The SMILtext modules provide a text container element with an explicit content model for defining in-line text, and a set of additional elements and attributes to control explicit in-line text rendering.

The following 3 modules are introduced in the new Text functional area allowing use of in-line text content:

Metainformation

Timing

The SMIL 3.0 specification leaves the basic syntax and semantics of the SMIL 2.1 timing model unchanged apart from the following changes:

External Timing

This functional area defines an XML timing language that makes SMIL 3.0 element and attribute timing control available to a wide range of other XML languages. It allows SMIL timing to be integrated in to a wide variety of a-temporal languages, even when several such languages are combined in a compound document. Because of its similarity with external style and positioning descriptions in the cascading style sheet language CSS, this functionality has been termed SMIL timesheets.

State

The new modules in this section provide a mechanism whereby the document author can create more complex controlflow 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.

The following 4 modules are introduced in the State functional areas:

2.3 SMIL 3.0 Modules

This section is normative.

SMIL functionality is partitioned into 13 functional areas. Within each functional area a further partitioning is applied into modules. All of these modules, and only these modules, are associated with the SMIL namespace.

The functional areas and their corresponding modules are:

Note: Modules marked with (**) are new Modules added in SMIL 3.0. Modules marked with (*) are revised modules from SMIL

  1. Animation
    1. BasicAnimation
    2. SplineAnimation
  2. Content Control
    1. BasicContentControl
    2. CustomTestAttributes
    3. PrefetchControl
    4. SkipContentControl
  3. Layout
    1. AlignmentLayout
    2. AudioLayout
    3. BackgroundTilingLayout
    4. BasicLayout (*)
    5. MotionLayout (**)
    6. MultiWindowLayout
    7. OverrideLayout
    8. SubRegionLayout
  4. Linking
    1. BasicLinking
    2. LinkingAttributes
    3. ObjectLinking
  5. Media Objects
    1. BasicMedia
    2. BrushMedia
    3. MediaAccessibility
    4. MediaClipping
    5. MediaClipMarkers
    6. MediaDescription
    7. MediaPanZoom (**)
    8. MediaParam (*)
  6. Text
    1. BasicText (**)
    2. TextStyling(**)
    3. TextFlow (**)
  7. Metainformation
    1. Metainformation (*)
  8. Structure
    1. Structure
  9. Timing
    1. AccessKeyTiming
    2. BasicInlineTiming
    3. BasicTimeContainers
    4. BasicExclTimeContainers
    5. BasicPriorityClassContainers
    6. DOMTimingMethods (**)
    7. EventTiming
    8. FillDefault
    9. MediaMarkerTiming
    10. MinMaxTiming
    11. MultiArcTiming
    12. RepeatTiming
    13. RepeatValueTiming
    14. RestartDefault
    15. RestartTiming
    16. SyncbaseTiming
    17. SyncBehavior
    18. SyncBehaviorDefault
    19. SyncMaster
    20. TimeContainerAttributes
    21. WallclockTiming
  10. Time Manipulations
    1. TimeManipulations
  11. External Timing
    1. BasicTimesheets (**)
  12. State
    1. StateTest (**)
    2. UserState (**)
    3. StateSubmission (**)
    4. StateInterpolation (**)
  13. Transitions
    1. BasicTransitions
    2. InlineTransitions
    3. TransitionModifiers
    4. FullScreenTransitionEffects

Each of these modules introduces a set of semantically-related elements, properties, and attributes. Each functional area has a corresponding section in this specification document. Further details on each of the modules is specified within those sections.

The modules may be independent or complementary. For example, the SyncMaster module requires and builds upon the SyncBehavior module, but the PrefetchControl and SkipContentControl modules are independent from each other. In addition, some modules require modules from other functional areas.

Modules specify their integration requirements. When one module requires another module for basic features and as a prerequisite for integration, a language profile must include the second module in order to include the first. The first module is said to be a dependent of the second module. Dependency may be nested, in that a module may be dependent on a module that is a dependent itself.

Table 1 presents the SMIL 3.0 modules and the modules they depend on.

Table 1: The SMIL 3.0 Modules and their Dependencies.
Module Dependencies
AccessKeyTiming NONE
AlignmentLayout BasicLayout
AudioLayout BasicLayout
BackgroundTilingLayout BasicLayout
BasicAnimation BasicInlineTiming
BasicContentControl NONE
BasicInlineTiming NONE
BasicExclTimeContainers NONE
BasicLayout NONE
BasicLinking NONE
BasicMedia NONE
BasicPriorityClassContainers BasicExclTimeContiners
BasicText NONE
BasicTimeContainers NONE
BasicTimesheets NONE
BasicTransitions NONE
BrushMedia NONE
CustomTestAttributes BasicContentControl
DOMTimingMethods NONE @@@
EventTiming NONE
ExclTimeContainers former SMIL module REMOVED in SMIL2.1
FillDefault BasicTimeContainers, and/or BasicExclTimeContainers, BasicPriorityClassContainers,

and/or TimeContainerAttributes

FullScreenTransitionEffects BasicTransitions
HierarchicalLayout former SMIL module REMOVED in SMIL2.1
InlineTransitions NONE
LinkingAttributes NONE
MediaAccessibility MediaDescription
MediaClipMarkers MediaClipping
MediaClipping BasicMedia
MediaDescription NONE
MediaMarkerTiming NONE
MediaPanZoom BasicMedia
MediaParam BasicMedia
MetaInformation NONE
MinMaxTiming NONE
MotionLayout BasicLayout
MultiArcTiming AccessKeyTiming, and/or BasicInlineTiming, and/or EventTiming, and/or
MediaMarkerTiming, and/or RepeatValueTiming, and/or
SyncbaseTiming, and/or WallclockTiming
MultiWindowLayout BasicLayout
ObjectLinking BasicLinking
OverrideLayout BasicLayout
PrefetchControl NONE
RepeatTiming NONE
RepeatValueTiming NONE
RestartDefault RestartTiming
RestartTiming NONE
SkipContentControl NONE
SplineAnimation BasicAnimation
StateTest NONE @@
StateInterpolation NONE @@
StateSubmission NONE @@
Structure BasicContentControl, and BasicInlineTiming, and BasicLayout, and
BasicLinking, and BasicMedia, and BasicTimeContainers, and
SkipContentControl, and SyncbaseTiming
SubRegionLayout BasicLayout
SyncbaseTiming NONE
SyncBehavior BasicTimeContainers, and/or
BasicExclTimeContainers, BasicPriorityClassContainers, and/or
TimeContainerAttributes
SyncBehaviorDefault SyncBehavior
SyncMaster SyncBehavior
TextFlow BasicText
TextStyling BasicText
TimeContainerAttributes NONE
TimeManipulations NONE
TransitionModifiers BasicTransitions, and/or InlineTransitions
UserState StateTest @@
WallclockTiming NONE

2.3.1 SMIL DOM

This section is informative.

SMIL is an XML-based language and conforms to the (XML) DOM Core [DOM1], [DOM2]. In  the future, a SMIL-specific DOM recommendation may specify support for timing and synchronization, media integration, and other synchronized multimedia functionality. A language profile may include DOM support. The granularity of DOM being supported corresponds to the modules being selected in that language profile. As with all modules, required support for the DOM is an option of the language profile.

2.4 Identifiers for SMIL 3.0 Modules and Language Profiles

This section is normative.

This section specifies the identifiers for the SMIL 3.0 namespace and the SMIL 3.0 modules. Each SMIL host language conformant language profile should explicitly state the namespace URI that is to be used to identify it. That namespace URI must comply with the "Requirements on Identifiers for SMIL Host Language Conformant Language Profiles", defined below.

2.4.1 The SMIL Mime Type

Documents authored in language profiles that include the SMIL Structure module can be associated with the "application/smil+xml" mime type. Documents using the "application/smil+xml" mime type are required to be host language conformant. This Recommendation obsoletes the former "application/smil" mime type as specified in SMIL 2.0 [SMIL20].

2.4.2 XML Namespace Identifier for the SMIL 3.0 Modules

The XML namespace identifier for the complete set of SMIL 3.0 modules, elements and attributes, are contained within the following namespace:

http://www.w3.org/2006/SMIL30/WD/

2.4.3 Identifiers for SMIL 3.0 Modules

Each module in this specification has a unique identifier associated with it. They are intended to uniquely and consistently identify each of them. They should be used as values in a test for whether an implementation includes a specific module, as well as in other circumstances where a need to refer to a specific SMIL 3.0 module is necessary.

Table 2 summarizes the identifiers for SMIL 3.0 modules.

Table 2: The SMIL 3.0 Module Identifiers.
Module name Identifier
AccessKeyTiming http://www.w3.org/2006/SMIL30/WD/AccessKeyTiming
AudioLayout http://www.w3.org/2006/SMIL30/WD/AudioLayout
BackgroundTilingLayout http://www.w3.org/2006/SMIL30/WD/BackgroundTilingLayout
AlignmentLayout http://www.w3.org/2006/SMIL30/WD/AlignmentLayout
BasicAnimation http://www.w3.org/2006/SMIL30/WD/BasicAnimation
BasicContentControl http://www.w3.org/2006/SMIL30/WD/BasicContentControl
BasicInlineTiming http://www.w3.org/2006/SMIL30/WD/BasicInlineTiming
BasicExclTimeContainers http://www.w3.org/2006/SMIL30/WD/BasicExclTimeContainers
BasicLayout http://www.w3.org/2006/SMIL30/WD/BasicLayout
BasicLinking http://www.w3.org/2006/SMIL30/WD/BasicLinking
BasicMedia http://www.w3.org/2006/SMIL30/WD/BasicMedia
BasicPriorityClassContainers http://www.w3.org/2006/SMIL30/WD/BasicPriorityClassContainers
BasicText http://www.w3.org/2006/SMIL30/WD/BasicText
BasicTimeContainers http://www.w3.org/2006/SMIL30/WD/BasicTimeContainers
BasicTimesheets http://www.w3.org/2006/SMIL30/WD/BasicTimesheets
BasicTransitions http://www.w3.org/2006/SMIL30/WD/BasicTransitions
BrushMedia http://www.w3.org/2006/SMIL30/WD/BrushMedia
CustomTestAttributes http://www.w3.org/2006/SMIL30/WD/CustomTestAttributes
DOMTimingMethods http://www.w3.org/2006/SMIL30/WD/DOMTimingMethods
EventTiming http://www.w3.org/2006/SMIL30/WD/EventTiming
ExclTimeContainers former SMIL module removed in SMIL21
FillDefault http://www.w3.org/2006/SMIL30/WD/FillDefault
FullScreenTransitionEffects http://www.w3.org/2006/SMIL30/WD/FullScreenTransitionEffects
HierarchicalLayout former SMIL module removed in SMIL21
InlineTransitions http://www.w3.org/2006/SMIL30/WD/InlineTransitions
LinkingAttributes http://www.w3.org/2006/SMIL30/WD/LinkingAttributes
MediaAccessibility http://www.w3.org/2006/SMIL30/WD/MediaAccessibility
MediaClipMarkers http://www.w3.org/2006/SMIL30/WD/MediaClipMarkers
MediaClipping http://www.w3.org/2006/SMIL30/WD/MediaClipping
MediaDescription http://www.w3.org/2006/SMIL30/WD/MediaDescription
MediaMarkerTiming http://www.w3.org/2006/SMIL30/WD/MediaMarkerTiming
MediaPanZoom http://www.w3.org/2006/SMIL30/WD/MediaPanZoom
MediaParam http://www.w3.org/2006/SMIL30/WD/MediaParam
Metainformation http://www.w3.org/2006/SMIL30/WD/Metainformation
MinMaxTiming http://www.w3.org/2006/SMIL30/WD/MinMaxTiming
MotionLayout http://www.w3.org/2006/SMIL30/WD/MotionLayout
MultiArcTiming http://www.w3.org/2006/SMIL30/WD/MultiArcTiming
MultiWindowLayout http://www.w3.org/2006/SMIL30/WD/MultiWindowLayout
ObjectLinking http://www.w3.org/2006/SMIL30/WD/ObjectLinking
OverrideLayout http://www.w3.org/2006/SMIL30/WD/OverrideLayout
PrefetchControl http://www.w3.org/2006/SMIL30/WD/PrefetchControl
RepeatTiming http://www.w3.org/2006/SMIL30/WD/RepeatTiming
RepeatValueTiming http://www.w3.org/2006/SMIL30/WD/RepeatValueTiming
RestartDefault http://www.w3.org/2006/SMIL30/WD/RestartDefault
RestartTiming http://www.w3.org/2006/SMIL30/WD/RestartTiming
SkipContentControl http://www.w3.org/2006/SMIL30/WD/SkipContentControl
SplineAnimation http://www.w3.org/2006/SMIL30/WD/SplineAnimation
StateTest http://www.w3.org/2006/SMIL30/WD/StateTest
StateInterpolation http://www.w3.org/2006/SMIL30/WD/StateInterpolation
StateSubmission http://www.w3.org/2006/SMIL30/WD/StateSubmission
Structure http://www.w3.org/2006/SMIL30/WD/Structure
SubRegionLayout http://www.w3.org/2006/SMIL30/WD/SubRegionLayout
SyncbaseTiming http://www.w3.org/2006/SMIL30/WD/SyncbaseTiming
SyncBehavior http://www.w3.org/2006/SMIL30/WD/SyncBehavior
SyncBehaviorDefault http://www.w3.org/2006/SMIL30/WD/SyncBehaviorDefault
SyncMaster http://www.w3.org/2006/SMIL30/WD/SyncMaster
TextFlow http://www.w3.org/2006/SMIL30/WD/TextFlow
TextStyling http://www.w3.org/2006/SMIL30/WD/TextStyling
TimeContainerAttributes http://www.w3.org/2006/SMIL30/WD/TimeContainerAttributes
TimeManipulations http://www.w3.org/2006/SMIL30/WD/TimeManipulations
TransitionModifiers http://www.w3.org/2006/SMIL30/WD/TransitionModifiers
UserState http://www.w3.org/2006/SMIL30/WD/UserState
WallclockTiming http://www.w3.org/2006/SMIL30/WD/WallclockTiming

2.4.4 Identifiers for SMIL 3.0 Profiles and Features

In addition to the module identifiers above, there may be different features and variances from one language profile to another that may not be expressed as the support or non-support of a particular module. These features may be expressed using the following identifiers:

http://www.w3.org/2006/SMIL30/WD/NestedTimeContainers
Profile allows nesting of the par and seq time containers.
http://www.w3.org/2006/SMIL30/WD/SMIL20DeprecatedFeatures
Profile supports deprecated SMIL  features. .
http://www.w3.org/2006/SMIL30/WD/SMIL10DeprecatedFeatures
Profile supports deprecated SMIL 1.0 features.

Implementations that support the SMIL BasicContentControl module must allow these as identifiers for use with the XML namespace mechanism, and must allow the associated namespace identifier to be used with the systemRequired test attribute. Profiles must identify those attributes for which an implementation must return "true" (this is an integration requirement). Implementations must return "false" for modules or features which are not fully supported.

This section is informative.

Modules can also be identified collectively. The following module collections are defined:

http://www.w3.org/2006/SMIL30/WD/
All the modules specified by the SMIL 3.0 specification.
http://www.w3.org/2006/SMIL30/WD/Language
The modules used by the SMIL 3.0 Language profile.
http://www.w3.org/2006/SMIL30/WD/Mobile
The modules used by the SMIL 3.0 Mobile profile.
http://www.w3.org/2006/SMIL30/WD/ExtendedMobile
The modules used by the SMIL 3.0 Extended Mobile profile.
http://www.w3.org/2006/SMIL30/WD/Daisy
The modules used by the SMIL 3.0 Daisy profile.
http://www.w3.org/2006/SMIL30/WD/ServerPlaylist
The modules used by the SMIL 3.0 ServerPlaylist profile.
http://www.w3.org/2006/SMIL30/WD/SetTopBox
The modules used by the SMIL 3.0 Set-top Box profile.
http://www.w3.org/2006/SMIL30/WD/HostLanguage
The modules required for SMIL Host Language Conformance.
http://www.w3.org/2006/SMIL30/WD/IntegrationSet
The modules required for SMIL Integration Set Conformance.

2.5 SMIL Conformance

This section is informative.

In this section we specify the rules for SMIL host language and SMIL integration set conformance. First, the conformance requirements for host language conformance and integration set conformance are given. The requirements are similar to those set forth for XHTML host language document type conformance and XHTML integration set document type conformance [XMOD]. In a final section the requirements on identifiers for host language conformant language profiles are given.

Currently, there exist seven language profiles using SMIL 3.0 Modules. They are the SMIL 3.0 Language Profile, the SMIL 3.0 Extended Mobile Profile, the SMIL 3.0 Mobile Profile, the SMIL 3.0 Daisy Profile, the SMIL 3.0 ServerPlaylist profile, SMIL 3.0 Set-top Box profile and the SMIL 3.0 Basic Language Profile. All seven profiles are SMIL host language conformant.

This section is normative.

This section is not fully updated

The following two tables list names used to collectively reference certain sets of SMIL 3.0 elements and attributes. These are used in the definitions of the minimum support in the two sections below on SMIL host language conformance and SMIL integration set conformance. The term "minimum support" is used to refer to the minimum set of elements that an element can contain, and the minimum set of attributes that can be used on an element.

Table 3: Names of SMIL 3.0 Element Collections.
Element Set Name Elements
TIMING-ELMS par, seq
MEDIA-ELMS ref, animation, audio, img, video, text, textstream
EMPTY no elements are required as a minimum
Table 4: Names of SMIL 3.0 Attribute Collections.
Attribute Set Name Attributes
TIMING-ATTRS begin, end, dur, repeatDur, repeatCount, max, min, fill, endsync
CONTCTRL-ATTRS systemBitrate, systemCaptions, systemLanguage, systemRequired, systemSize, systemDepth, systemOverdubOrSubtitle, systemAudioDesc, systemOperatingSystem, systemCPU, systemComponent
MEDIA-ATTRS src, type
LINKING-ATTRS href, sourceLevel, destinationLevel, sourcePlaystate, destinationPlaystate, show, accesskey, tabindex, target, external, actuate, alt
COMMON-ATTRS id, class, xml:lang, title

2.5.1 SMIL Host Language Conformance

A language profile is said to be SMIL 3.0 host language conformant if it includes the following modules:

  1. Structure
  2. BasicContentControl
  3. BasicInlineTiming
  4. BasicLayout
  5. BasicLinking
  6. BasicMedia
  7. BasicTimeContainers
  8. MinMaxTiming
  9. RepeatTiming
  10. SkipContentControl
  11. SyncbaseTiming

In addition, the following requirements must be satisfied:

  1. The language profile defines what modules it collects.
  2. The language profile includes all elements, attributes, and attribute values specified by the collected modules.
  3. The language profile fulfills the "minimum support" requirements for elements and attributes as listed in Table 5 below.
  4. The language profile complies with the integration requirements set forth by the modules it collects.
  5. The language profile specifies the semantics related to the integration of the modules.
  6. The language profile defines its DTD or XML Schema.
  7. The language profile defines a unique identifier conforming to the requirements set forth in Requirements on Identifiers for SMIL Host Language Conformant Language Profiles.
  8. The SyncbaseTiming module should be included in Host Language conformant profiles, although it is not strictly required. We strongly recommend inclusion of this module in Host Language conformant profiles to maintain a high level of consistency and interoperability with other languages that have integrated SMIL modules including the SMIL Language, XHTML+SMIL, and SVG. Only profiles designed to operate on severely constrained devices may omit the SyncbaseTiming module.
Table 5: Minimum Support for SMIL Host Language Conformance.
Element Minimum Support
Elements Attributes
smil head, body COMMON-ATTRS, CONTCTRL-ATTRS, xmlns
head layout, switch COMMON-ATTRS
body TIMING-ELMS, MEDIA-ELMS, switch, a COMMON-ATTRS
layout region, root-layout COMMON-ATTRS, CONTCTRL-ATTRS, type
root-layout EMPTY COMMON-ATTRS, backgroundColor, height, width
region EMPTY COMMON-ATTRS, backgroundColor, bottom, fit, height, left, regionName, right, showBackground, top, width, z-index, skip-content
ref, animation, audio, img, video, text, textstream area COMMON-ATTRS, CONTCTRL-ATTRS, TIMING-ATTRS, repeat, MEDIA-ATTRS, region
a MEDIA-ELMS COMMON-ATTRS, LINKING-ATTRS
area EMPTY COMMON-ATTRS, LINKING-ATTRS, TIMING-ATTRS, repeat, shape, coords, nohref
par, seq TIMING-ELMS, MEDIA-ELMS, switch, a COMMON-ATTRS, CONTCTRL-ATTRS, TIMING-ATTRS, repeat
switch TIMING-ELMS, MEDIA-ELMS, a, layout COMMON-ATTRS, CONTCTRL-ATTRS

Support of deprecated elements and attributes is no longer required for SMIL 3.0 host language conformance but it is highly recommended for all modules the given language supports. Support of deprecated elements and attributes can only be left out in cases where interoperability with SMIL 1.0 implementations is not an issue. For example, if a SMIL 3.0 host language supports the MultiArcTiming module, it is highly recommended that it support the deprecated syntax defined in the MultiArcTiming module.

Since the SMIL 3.0 Structure module may only be used in a profile that is SMIL host language conformant, this implies that the SMIL 3.0 Structure module must at least be accompanied with the nine other modules required for host language conformance that were named above. Those modules themselves can still be used in other, non SMIL host language conformant, language profiles.

2.5.2 SMIL Integration Set Conformance

A language profile is said to be SMIL 3.0 integration set conformant if it includes the following modules:

  1. BasicContentControl
  2. BasicInlineTiming
  3. BasicMedia
  4. BasicTimeContainers
  5. MinMaxTiming
  6. RepeatTiming
  7. SyncbaseTiming

In addition, the following requirements must be satisfied:

  1. The language profile defines what modules it collects.
  2. The language profile includes all elements, attributes, and attribute values specified by the collected SMIL 3.0 modules.
  3. The language profile fulfills the "minimum support" requirements for elements and attributes as listed in Table 6 below.
  4. The language profile complies with the integration requirements set forth by the SMIL 3.0 modules it collects.
  5. The SyncbaseTiming module should be included in Integration Set conformant profiles, although it is not strictly required. We strongly recommend inclusion of this module in Integration Set conformant profiles to maintain a high level of consistency and interoperability with other languages that have integrated SMIL modules including the SMIL 3.0 Language, XHTML+SMIL [XHTMLplusSMIL], and SVG [SVG]. Only profiles designed to operate on severely constrained devices may omit the SyncbaseTiming module.
Table 6: Minimum Support for SMIL Integration Set Conformance.
Element Minimum Support
Elements Attributes
ref, animation, audio, img, video, text, textstream   CONTCTRL-ATTRS, TIMING-ATTRS, MEDIA-ATTRS
par, seq TIMING-ELMS, MEDIA-ELMS, switch CONTCTRL-ATTRS, TIMING-ATTRS
switch TIMING-ELMS, MEDIA-ELMS CONTCTRL-ATTRS

Support of deprecated elements and attributes is not required for SMIL 3.0 integration set conformance. However, when included, the above requirements also apply to these elements and attributes. Also, when supported, it is required that all the deprecated elements and attributes from all the included modules are supported as a whole.

2.5.3 Requirements on Identifiers for SMIL Host Language Conformant Language Profiles

This section is informative.

A language profile is specified through its DTD or XML Schema. The identifier of these can be used to identify the language profile. SMIL 1.0 has specified the default namespace declaration on its root element, smil, as the decisive identifier for distinguishing it from other language profiles [SMIL10]. For that purpose SMIL 1.0 has specified

http://www.w3.org/TR/REC-smil

as the namespace identifier for SMIL 1.0

This section is normative.

For the purpose of identifying the version and the language profile used, SMIL host language conformant documents must satisfy the following requirements:

  1. The document should declare a default namespace [XML-NS].
  2. The default namespace must be declared on the smil root element.
  3. In case the SMIL host language conformant language profile has been issued as a W3C Recommendation, the default namespace identifier must satisfy the following requirements:
    1. The URI is constructed conformant to the requirements set forth by the W3C [W3C-NSURI].
    2. The default namespace identifier should identify the language profile.
      In case the language profile is a subset of a larger one, the default namespace identifier may also identify that larger language profile. The module collection that is required to be supported in the subset language profile may be indicated through the systemRequired attribute on the smil element.
      See the SMIL Basic Language Profile specification for an example.

2.5.4 Error Handling in SMIL Host Language Conformant Documents

Syntax errors in a SMIL Host Language conformant document are handled according to the XML rules for well-formed or valid XML [XML11].

Semantic errors can arise at various levels. One is where the declared attribute values are of unknown value. Another is where the assembled presentation is (possibly) conflicting, as in a case where media objects are competing for display space or where they are synchronized ambiguously. These latter types, although maybe an error according to the author's intentions, are not considered an error and the user agent will present according to the resolution rules defined in this specification.

2.5.5 Handling of Syntax errors in Attribute Values

Errors in attribute values might remain undetectable to the parser, because the value type is declared as CDATA, or because the value range is open ended, as in the case of events, for example. However, errors in attribute values can be detected within a given language profile, where that language profile specifies the supported value set. Specifications of language profiles are required to specify the error handling that is required when such an attribute value error occurs.

2.6 Creating a DTD for a Language Profile

This section is informative.

This section describes how language profiles could be defined using the SMIL 3.0 modular DTDs. The reader is assumed to be familiar with the mechanisms defined in "Modularization of XHTML" [XMOD], in particular Appendix D [XMOD-APPD] and Appendix E [XMOD-APPE]. In general, the SMIL 3.0 modular DTDs use the same mechanisms as the XHTML modular DTDs use. Exceptions to this are:

  1. SMIL supports qualified attribute names for SMIL attributes that can appear on non-SMIL elements. This enables these attributes to use prefixes to indicate that they belong to the SMIL 3.0 namespace.
  2. SMIL supports module level INCLUDE/IGNORE instead of XHTML's element/attlist level. Similar to XHTML Modularization, this prohibits profiles from importing only part of a module -- they have to support either all the elements and attributes or none.

Below, we give a short description of the files that are used to define the SMIL 3.0 modular DTDs. See the table and the end of the section for a complete list of the filenames involved.

Following the same mechanisms as the XHTML modular DTDs, the SMIL 3.0 specification places the XML element declarations (e.g. <!ELEMENT...>) and attribute list declarations (e.g. <!ATTLIST...>) of all SMIL 3.0 elements in separate files, the SMIL module files. A SMIL module file is provided for each functional area in the SMIL 3.0 specification (that is, there is a SMIL module file for animation, layout, timing, etc).

The SMIL module files are used in the normative definitions of the specification of the SMIL 3.0 Language Profile. Usage of the same module files for defining other SMIL profiles is recommended, but not required. The requirements that SMIL language profiles must follow are stated in the SMIL 3.0 specification, not in the DTD code.

To make the SMIL module files independent of each other, and independent of the language profiles, the element and attribute declarations make heavy use of XML entities. This provides profiles with the necessary hooks to define the actual content models and attributes of the SMIL elements.

The SMIL 3.0 Language Profile provides examples of how the SMIL module files can be used. Most of the DTD files are reused across the different profiles. Reused are the SMIL module files, the files that define the data types and the common attributes, the "qname" file that takes care of adding namespace prefixes if necessary, and the framework file, which takes care of including files in the appropriate order.

The files that are different for each profile are the driver file and document model file. This would, in general, also apply to new profiles: to define a new language profile, one has to write the extension module(s), the driver file that defines which modules are used, and a document model file that defines the extended document model. The driver file and document model file are described in more detail below.

The driver file.

This is the file that would be referenced by a document's DOCTYPE declaration. Its main job is to define which document model file and which of the SMIL module files the profile is using. It may also define an optional namespace to be used in all namespace prefixes. For example, to prefix all SMIL element names with "foobar", the following can be added to the start of the profile:

<!ENTITY % SMIL.prefixed "INCLUDE" >
<!ENTITY % SMIL.prefix "foobar" >

Elements defined in their modules as, for example, <video> will become parsed as <foobar:video>. This also applies for SMIL attributes that appear on other elements, so, for example, "begin" becomes "foobar:begin". The default is that the qname prefix is empty -- that is, it is effectively turned off by default.

After these definitions, the driver file includes the framework file (which will subsequently include the data type, common attributes, qname and document model file), after which the SMIL module files are included that are used by this profile.

The document model file.

The document model file contains the XML entities that are used by the SMIL module files to define the content models and attribute lists of the elements in that profile.

Content models generally differ from profile to profile, or contain elements from other modules. To avoid these dependencies in the SMIL module files, content models need to be defined in the document model file. The (dummy) default content model as defined in the SMIL module files is "EMPTY" for all SMIL 3.0 elements.

For the same reasons, the SMIL module files only define a default attribute list for their elements. This default list only contains the SMIL 3.0 core attributes and the attributes that are defined in the same SMIL module file. All other attributes need to be added to this default list by defining the appropriate XML entities. For example, the Media Objects Module file only adds the core and media related attributes on the media objects; other attributes, such as the timing attributes, are added to this list by the document model file.

Table 7: Formal public identifiers and system identifiers of all files used in the SMIL 3.0 modular DTDs.
Driver files for the predefined profiles
-//W3C//DTD SMIL 3.0 Language //EN http://www.w3.org/2006/SMIL30/WD/SMIL30.dtd
-//W3C//DTD SMIL 3.0 Extended Mobile//EN http://www.w3.org/2006/SMIL30/WD/SMIL30ExtendedMobile.dtd
-//W3C//DTD SMIL 3.0 Mobile //EN http://www.w3.org/2006/SMIL30/WD/SMIL30Mobile.dtd
-//W3C//DTD SMIL 3.0 Daisy //EN http://www.w3.org/2006/SMIL30/WD/SMIL30Daisy.dtd
-//W3C//DTD SMIL 3.0 ServerPlaylist //EN http://www.w3.org/2006/SMIL30/WD/SMIL30ServerPlaylist.dtd
-//W3C//DTD SMIL 3.0 SetTopBox //EN http://www.w3.org/2006/SMIL30/WD/SMIL30SetTopBox.dtd
Document model files for the predefined profiles
-//W3C//ENTITIES SMIL 3.0 Language Profile Document Model 1.0//EN http://www.w3.org/2006/SMIL30/WD/smil-language-profile-model-1.mod
-//W3C//ENTITIES SMIL 3.0 Extended Mobile Profile Document Model 1.0//EN http://www.w3.org/2006/SMIL30/WD/smil-extended-mobile-profile-model-1.mod
-//W3C//ENTITIES SMIL 3.0 Mobile Profile Document Model 1.0//EN http://www.w3.org/2006/SMIL30/WD/smil-mobile-profile-model-1.mod
-//W3C//ENTITIES SMIL 3.0 Daisy Profile Document Model 1.0//EN http://www.w3.org/2006/SMIL30/WD/smil-daisy-profile-model-1.mod
-//W3C//ENTITIES SMIL 3.0 ServerPlaylist Profile Document Model 1.0//EN http://www.w3.org/2006/SMIL30/WD/smil-serverplaylist-profile-model-1.mod
-//W3C//ENTITIES SMIL 3.0 SetTopBox Profile Document Model 1.0//EN http://www.w3.org/2006/SMIL30/WD/smil-set-topbox-profile-model-1.mod
SMIL 3.0 module files
-//W3C//ELEMENTS SMIL 3.0 Animation//EN http://www.w3.org/2006/SMIL30/WD/SMIL-anim.mod
-//W3C//ELEMENTS SMIL 3.0 Content Control//EN http://www.w3.org/2006/SMIL30/WD/SMIL-control.mod
-//W3C//ELEMENTS SMIL 3.0 Layout//EN http://www.w3.org/2006/SMIL30/WD/SMIL-layout.mod
-//W3C//ELEMENTS SMIL 3.0 Linking//EN http://www.w3.org/2006/SMIL30/WD/SMIL-link.mod
-//W3C//ELEMENTS SMIL 3.0 Media Objects//EN http://www.w3.org/2006/SMIL30/WD/SMIL-media.mod
-//W3C//ELEMENTS SMIL 3.0 Document Text//EN http://www.w3.org/2006/SMIL30/WD/SMIL-text.mod
-//W3C//ELEMENTS SMIL 3.0 Document Metainformation//EN http://www.w3.org/2006/SMIL30/WD/SMIL-metainformation.mod
-//W3C//ELEMENTS SMIL 3.0 Document Structure//EN http://www.w3.org/2006/SMIL30/WD/SMIL-struct.mod
-//W3C//ELEMENTS SMIL 3.0 Timing//EN http://www.w3.org/2006/SMIL30/WD/SMIL-timing.mod
-//W3C//ELEMENTS SMIL 3.0 External Timing//EN http://www.w3.org/2006/SMIL30/WD/SMIL-external-timing.mod
-//W3C//ELEMENTS SMIL 3.0 State//EN http://www.w3.org/2006/SMIL30/WD/SMIL-state.mod
-//W3C//ELEMENTS SMIL 3.0 Transition//EN http://www.w3.org/2006/SMIL30/WD/SMIL-transition.mod
Other utilities: data types, common attributes, qname and frame work files
-//W3C//ENTITIES SMIL 3.0 Datatypes 1.0//EN http://www.w3.org/2006/SMIL30/WD/smil-datatypes-1.mod
-//W3C//ENTITIES SMIL 3.0 Common Attributes 1.0//EN http://www.w3.org/2006/SMIL30/WD/smil-attribs-1.mod
-//W3C//ENTITIES SMIL 3.0 Qualified Names 1.0//EN http://www.w3.org/2006/SMIL30/WD/smil-qname-1.mod
-//W3C//ENTITIES SMIL 3.0 Modular Framework 1.0//EN http://www.w3.org/2006/SMIL30/WD/smil-framework-1.mod

3. The SMIL 3.0 Animation Modules

Editor for SMIL 3.0
Thierry MICHEL, W3C
Editors for Earlier Versions of SMIL
Dick Bulterman, CWI/Amsterdam
Patrick Schmitz , Microsoft
Aaron Cohen), Intel
Ken Day, Macromedia

3.1 Overview and Summary of Changes for SMIL 3.0

This section is informative.

The SMIL 3.0 specification leaves the SMIL 2.1 Animation Modules [SMIL21-animation] unchanged, with the exception that normative text is added that clarifies the ability of a host language designer to override the event base default element.

3.2 Introduction

This section is informative.

This section defines the SMIL 3.0 Animation Modules, which are composed of a BasicAnimation module and a SplineAnimation module. These modules contain elements and attributes for incorporating animation onto a time line, and a mechanism for composing the effects of multiple animations. Since these elements and attributes are defined in modules, designers of other markup languages can choose whether or not to include this functionality in their languages. Language designers incorporating other SMIL modules do not need to include the animation modules if animation functionality is not needed.

The examples in this document that include syntax for a host language use [SMIL10], [SVG], [HTML4] and [CSS2]. These are provided as an indication of possible integrations with various host languages.

While this document defines a base set of animation capabilities, it is assumed that host languages may build upon the support to define additional or more specialized animation elements.  Animation only manipulates attributes and properties of the target elements, and so does not require any knowledge of the target element semantics beyond basic type information.

This module depends on the SMIL 3.0 BasicInlineTiming module, using elements and attributes from the Timing module for its time line. The BasicInlineTiming module is a prerequisite for any profile using SMIL Animation. The reader is presumed to have read and be familiar with the SMIL 3.0 Timing modules. 

This section first presents the underlying principals of animation in SMIL 3.0, then the elements and attributes of the BasicAnimation module and of the SplineAnimation module.

3.3 Module Overview

This section is normative.

SMIL 3.0 Animation functionality is partitioned across the following 2 modules:

BasicAnimation
The BasicLayout module defines simple animation functions defined by sets of points to be visited in sequence, with the function defined between those using discrete, linear or paced interpolation.
SplineAnimation
The SplineAnimation module extends the discrete, linear and paced calculation modes of the BasicAnimation module, providing additional control over interpolation and timing.

3.4 Animation Model

This section is informative.

This section describes the semantics underlying the SMIL 3.0 animation modules. The specific elements are not described here, but rather the common concepts and syntax that comprise the model for animation.  Document issues are described, as well as the means to target an element for animation. The animation model is then defined by building up from the simplest to the most complex concepts: first the simple duration and simple animation function f(t), and then the overall effect F(t,u)

3.4.1 The simple animation function f(t)

This section is normative.

Animation is defined as a time-based function of a target element (or more specifically of some attribute of the target element, the target attribute). The animation defines a mapping of time to values for the target attribute. This mapping takes into account all aspects of timing, as well as animation-specific semantics.  The overall mapping is based on a simple animation function f(t) which describes the animation over the simple duration of the element. Every animation defines a simple animation function which produces a value for the target attribute for any time within the simple duration.

A target attribute is the name of a feature of a target element as defined in a host language document.

This may be (e.g.) an XML attribute contained in the element or a CSS property that applies to the element.  By default, the target element of an animation will be the parent of the animation element (an animation element is typically a child of the target element). However, the target may be any element in the document, identified either by an XML ID reference or via an XLink [XLINK] locator reference.

This section is informative.

As a simple example, the following defines an animation of an SVG rectangle shape.  The rectangle will change from being tall and thin to being short and wide.

<rect ...>
   <animate attributeName="width"  from="10px"  to="100px" 
            begin="0s" dur="10s" />
   <animate attributeName="height" from="100px" to="10px"
            begin="0s" dur="10s" />
</rect>

The rectangle begins with a width of 10 pixels and increases to a width of 100 pixels over the course of 10 seconds. Over the same ten seconds, the height of the rectangle changes from 100 pixels to 10 pixels.

When an animation is running, it should not actually change the attribute values in the DOM [DOM2].  The animation runtime should maintain a presentation value for each animated attribute, separate from the DOM or CSS Object Model (OM). If an implementation does not support an object model, it should maintain the original value as defined by the document as well as the presentation value. The presentation value is reflected in the displayed form of the document. Animations thus manipulate the presentation value, and should not affect the base value exposed by DOM or CSS OM. This is detailed in The animation sandwich model.

This section is normative.

Normative

The base value of a target attribute a at time t is the value of a to which animation is applied at time t.

The presentation value of a target attribute a at time t is the value of a resulting from the application of animation at time t.

The presentation value reflects the effect of animation on the base value. The effect is the change to the base value of the target attribute at any given time. When an animation completes, the effect of the animation is no longer applied, and the presentation value reverts to the base value by default. The animation effect can also be extended to freeze the last value for the length of time determined by the semantics of the fill attribute.

An animation element defines a simple animation function which is evaluated as needed over time by the implementation. The resulting values are applied to the presentation value for the target attribute. Animation functions are continuous in time and can be sampled at whatever frame rate is appropriate for the rendering system. The syntactic representation of the simple animation function is independent of this model, and may be described in a variety of ways. The animation elements in this specification support syntax for a set of discrete or interpolated values, a path syntax for motion based upon SVG paths, keyframe based timing, evenly paced interpolation, and variants on these features.

In the example immediately above, the simple animation function for the width attribute, specified by 'from="10px" to="100px" ... dur="10s"' is

f(t) = (10 + 90*t/10) px, where t is given in seconds.

Simple animation functions may be defined which have additional parameters, or that are purely or partially algorithmic. For example, a "to" animation interpolates from the current value to the "to" value:

<animate attributeName="top" to="10" dur="2.5s" />

The animation function is a function of the current position, as well as of time:

f(t,u) = (u*(2.5s-t)/2.5s) + 10*(t/2.5s)

In all cases, the animation exposes this as a function of time.

Normative

The simple animation function defined by an animation element is a function of time, f(t), defined for times t, 0<=t<=d, where d is the simple duration of the element.

The simple animation function may be defined as a function which depends on factors in addition to time. This does not affect the model of animation, beyond the trivial addition of additional parameters to f(t), such as f(t,u) used in the "to" animation example immediately above.

Animations can be defined to either override or add to the base value of an attribute. In this context, the base value may be the DOM value, or the result of other animations that also target the same attribute. This more general concept of a base value is termed the underlying value. Animations that add to the underlying value are described as additive animations. Animations that override the underlying value are referred to as non-additive animations. The animation effect function of an element is the function which includes the affect of the underlying value and accounts for repeating and freezing of the element. Because the animation effect can be affected by repeating and freezing, it is defined over the active duration of the element rather than its simple duration.

Animations can be combined in ways which produce intermediate values outside of the domain of the target attribute, but where the presentation value produced is valid. The type of a target attribute is this larger set. This is detailed in The animation sandwich model.

Normative

The type of a target attribute a is the base type of which the domain of a is a subset.

The animation effect function, F(t,u), of an animation element with active duration AD is a function mapping times t: 0<=t<AD and values u of the type of the target attribute a into values of the type of a.

The underlying value u of a target attribute a of an animation element at time t is the value of a to which the animation effect is applied at time t.

The animation effect function F(t,u) is usually defined as a function of the simple animation function f(t). f(t) must be defined in such a manner that F(t,u) produces values of the correct type.

3.4.2 Summary of symbols used in the semantic descriptions

This section is informative.

a
The target attribute of an animation element.
d
The simple duration of the element.
AD
The active duration of the element.
t
A time. Depending on the context, t may be in user-perceived time, an element's active duration, or its simple duration.
u
The underlying value of the target attribute a, generally at a specific time t.
f(t)
The simple animation function of times within the simple duration. This is defined for t: 0<=t<d.

Note that while F(t,u) defines the mapping for the entire animation, f(t) has a simplified model that just handles the simple duration.

f(d)
While f(t) is not defined for the value t=d, the expression f(d) is used as a shorthand to refer to the last value defined for the animation function.
F(t,u)
The effect of an animation for any point in the active duration of the animation. This maps times within the active duration (t: 0<=t<AD) and an underlying value to a value for the target attribute. A time value of 0 corresponds to the time at which the animation begins. F(t,u) combines the simple animation function f(t) with all the other aspects of animation and timing controls.

3.4.3 The animation sandwich model

This section is informative.

When an animation is running, it does not actually change the attribute values in the DOM.  The animation runtime should ideally maintain a presentation value for any target attribute, separate from the DOM, CSS, or other object model (OM) in which the target attribute is defined. The presentation value is reflected in the display form of the document. The effect of animations is to manipulate this presentation value, and not to affect the underlying DOM or CSS OM values.

The remainder of this discussion uses the generic term OM for both the XML DOM [DOM2] as well as the CSS-OM. If an implementation does not support an object model, it should ideally maintain the original value as defined by the document as well as the presentation value; for the purposes of this section, we will consider this original value to be equivalent to the value in the OM.

In some implementations of DOM, it may be difficult or impractical to main a presentation value as described. CSS values should always be supported as described, as the CSS-OM provides a mechanism to do so. In implementations that do not support separate presentation values for general XML DOM properties, the implementation must at least restore the original value when animations no longer have an effect. 

The rest of this discussion assumes the recommended approach using a separate presentation value.

The model accounting for the OM and concurrently active or frozen animations for a given attribute is described as a "sandwich", a loose analogy to the layers of meat and cheeses in a "submarine sandwich" (a long sandwich made with many pieces of meats and cheese layered along the length of the bread). In the analogy, time is associated with the length of the sandwich, and each animation has its duration represented by the length of bread that the layer covers. On the bottom of the sandwich is the base value taken from the OM. Each active (or frozen) animation is a layer above this. The layers (i.e. the animations) are placed on the sandwich both in time along the length of the bread, as well as in order according to priority, with higher priority animations placed above (i.e. on top of) lower priority animations. At any given point in time, you can take a slice of the sandwich and see how the animation layers stack up.

Note that animations manipulate the presentation value coming out of the OM in which the attribute is defined, and pass the resulting value on to the next layer of document processing. This does not replace or override any of the normal document OM processing cascade. 

Specifically, animating an attribute defined in XML will modify the presentation value before it is passed through the style sheet cascade, using the XML DOM value as its base. Animating an attribute defined in a style sheet language will modify the presentation value passed through the remainder of the cascade. 

In CSS2 and the DOM 2 CSS-OM, the terms "specified", "computed" and "actual" are used to describe the results of evaluating the syntax, the cascade and the presentation rendering. When animation is applied to CSS properties of a particular element, the base value to be animated is read using the (readonly) getComputedStyle() method on that element. The values produced by the animation are written into an override stylesheet for that element, which may be obtained using the getOverrideStyle() method. These new values then affect the cascade and are reflected in a new computed value (and thus, modified presentation). This means that the effect of animation overrides all style sheet rules, except for user rules with the !important property. This enables !important user style settings to have priority over animations, an important requirement for accessibility. Note that the animation may have side effects upon the document layout. See also section 6.1, "Specified, computed, and actual values," of [CSS2] and section 5.2.1, "Override and computed style sheet," of [DOM2CSS].

Within an OM, animations are prioritized according to when each begins. The animation first begun has lowest priority and the most recently begun animation has highest priority. When two animations start at the same moment in time, the activation order is resolved as follows:

Note that if an animation is restarted (see also Restarting animations), it will always move to the top of the priority list, as it becomes the most recently activated animation. That is, when an animation restarts, its layer is pulled out of the sandwich, and added back on the very top.  In contrast, when an element repeats the priority is not affected (repeat behavior is not defined as restarting).

Each additive animation adds its effect to the result of all sandwich layers below. A non-additive animation simply overrides the result of all lower sandwich layers. The end result at the top of the sandwich is the presentation value that must be reflected in the document view.

Some attributes that support additive animation have a defined legal range for values (e.g. an opacity attribute may allow values between 0 and 1). In some cases, an animation function may yield out of range values. It is recommended that implementations clamp the results to the legal range as late as possible, before applying them to the presentation value. Ideally, the effect of all the animations active or frozen at a given point should be combined, before any clamping is performed. Although individual animation functions may yield out of range values, the combination of additive animations may still be legal. Clamping only the final result and not the effect of the individual animation functions provides support for these cases. Intermediate results may be clamped when necessary although this is not optimal. The host language must define the clamping semantics for each attribute that can be animated. As an example, this is defined for animateColor element.

Initially, before any animations for a given attribute are active, the presentation value will be identical to the original value specified in the document (the OM value).

When all animations for a given attribute have completed and the associated animation effects are no longer applied, the presentation value will again be equal to the OM value. Note that if any animation is defined with fill="freeze", the effect of the animation will be applied as long as the animation element remains in the frozen state, and so the presentation value will continue to reflect the animation effect. Refer also to the section "Freezing animations".

Some animations (e.g. animateMotion) will implicitly target an attribute, or possibly several attributes (e.g. the "posX" and "posY" attributes of some layout model). These animations must be combined with any other animations for each attribute that is affected. Thus, e.g. an animateMotion animation may be in more than one animation sandwich (depending upon the layout model of the host language). For animation elements that implicitly target attributes, the host language designer must specify which attributes are implicitly targeted, and the runtime must accordingly combine animations for the respective attributes.

Note that any queries (via DOM interfaces) on the target attribute will reflect the OM value, and will not reflect the effect of animations. Note also that the OM value may still be changed via the OM interfaces (e.g. using script). While it may be useful or desired to provide access to the final presentation value after all animation effects have been applied, such an interface is not provided as part of SMIL Animation. A future version may address this.

Although animation does not manipulate the OM values, the document display must reflect changes to the OM values. Host languages can support script languages that can manipulate attribute values directly in the OM. If an animation is active or frozen while a change to the OM value is made, the behavior is dependent upon whether the animation is defined to be additive or not, as follows: (see also the section Additive animation). 

3.4.4 Animation elements as "continuous media"

This section is informative.

Within the timing model, animation is considered to be "continuous" media. The animation elements defined in SMIL Animation do not have a natural intrinsic duration, so they are assigned an intrinsic duration of indefinite.

This has several consequences, which are noted in various sections below. In particular, most animation elements will have an explicit duration set with the dur attribute, since a finite, known duration is required for interpolation.

3.4.5 The animation effect function F(t,u)

This section is informative.

As described above, the simple animation function f(t) defines the animation for the simple duration d. However, SMIL Timing allows the author to repeat the simple duration. SMIL Timing also allows authors to specify whether the animation should simply end when the active duration completes, or whether it should be frozen at the last value. SMIL Animation specifies what it means for an animation to be frozen.  In addition, the author can specify how each animation should be combined with other animations and the original DOM value.

This section describes the semantics for the additional functionality, including a detailed model for combining animations. This is presented as a sequence of functions building on the simple animation function:

Since these functions describe the animation outside of the simple duration, they are defined for any time t: 0<=t<AD . The frozen animation function ff(t),is additionally defined for t=AD, to account for the case when the element is frozen.

Repeating animations

This section is normative.

As described in the section Interval timing of the BasicInlineTiming module, repeating an element causes the element to be "played" several times in sequence. The repeated period is 0 to the simple duration of the element. Animation follows this model, where "playing" the animation means applying the simple animation function f(t) repeatedly.

Normative

The repeated animation function, fr(t), for any simple animation function f(t) is

fr(t) = f( REMAINDER( t, d ) ),

where t>=0, d is the simple duration , and REMAINDER( t, d ) is defined as (t - d*floor(t/d)).

This formulation follows the end-point exclusive model described in Interval timing. As an animation repeats, it starts at f(0), is sampled and applied up to but not including the end-point f(d). At the end of the simple duration, i.e. at the beginning of the next iteration, it starts back at f(0). f(d) may never actually be applied.

Examples

This section is informative.

In the following example, the 2.5 second animation function will be repeated twice; the active duration will be 5 seconds. The attribute top will go from 0 to (almost) 10, return to 0 at 2.5 seconds, and repeat.

<animate attributeName="top" from="0" to="10" dur="2.5s"
         repeatCount="2"
/>

In the following example, the animation function will be repeated two full times and then the first half is repeated once more; the active duration will be 7.5 seconds.

<animate attributeName="top" from="0" to="10" dur="3s"
         repeatCount="2.5"
/>

In the following example, the animation function will repeat for a total of 7 seconds. It will play fully two times, followed by a fractional part of 2 seconds. This is equivalent to a repeatCount of 2.8. The last (partial) iteration will apply values in the range "0" to "8". 

<animate attributeName="top" from="0" to="10" dur="2.5s"
         repeatDur="7s" />

In the following example, the simple duration is longer than the duration specified by repeatDur, and so the active duration will effectively cut short the simple duration. However, animation function still uses the specified simple duration. The effect of the animation is to interpolate the value of "top" from 10 to 15, over the course of 5 seconds.

<animate attributeName="top" from="10" to="20" 
         dur="10s" repeatDur="5s"
/>

Note that if the simple duration is not defined (e.g. it is indefinite), repeat behavior is not defined (but repeatDur still defines the active duration). In the following example the simple duration is indefinite, and so the repeatCount is effectively ignored. Nevertheless, this is not considered an error: the active duration is also indefinite. The effect of the animation is to to just use the value for f(0), setting the fill color to red for the remainder of the animate element's duration.

<animate attributeName="fill" from="red" to="blue" repeatCount="2" />

In the following example, the simple duration is indefinite, but the repeatDur still determines the active duration. The effect of the animation is to set the fill color to red for 10 seconds.

<animate attributeName="fill" from="red" to="blue" repeatDur="10s" />

In the following example, the simple duration is longer than the duration specified by repeatDur, and so the active duration will effectively cut short the simple duration. However, the animation function still interpolates using the specified simple duration. The effect of the animation is to interpolate the value of "top" from 10 to 17, over the course of 7 seconds.

<animate attributeName="top" from="10" to="20" 
         dur="10s" repeatDur="7s"
/>

Controlling behavior of repeating animation - Cumulative animation

The author may also select whether a repeating animation should repeat the original behavior for each iteration, or whether it should build upon the previous results, accumulating with each iteration. For example, a motion path that describes an arc can repeat by moving along the same arc over and over again, or it can begin each repeat iteration where the last left off, making the animated element bounce across the window. This is called cumulative animation.

Normative

Every animation element must be defined as either cumulative or non-cumulative. An animation element may be defined as cumulative only if addition is defined for the target attribute. The cumulative animation function, fc(t), for any simple animation function f(t) is

fc(t) = fr(t), if the element is non-cumulative.

If the element is cumulative:

Let fi(t) represent the cumulative animation function for a given iteration i.

The first iteration f0(t) is unaffected by accumulate, and so is the same as the original simple animation function definition. Each subsequent iteration adds to the result of the previous iterations:

f0(t) = f(t)

fi(t) = (f(d) * i) + f(t - (i*d))   for any integer i > 0.

The cumulative animation function is then

fc(t) = fi(t), where i = floor(t/d).

This section is informative.

Note that fi+1(t)starts at f(d)*i + f(0). To avoid jumps, authors will typically choose animation functions which start at 0.

For example, the path notation for a simple arc (detailed in The animateMotion element) can be used to describe a bouncing motion:

<img ...>
   <animateMotion path="m 0 0 c 30 50 70 50 100 0 z" dur="5s"
      accumulate="sum" repeatCount="4" />
</img>

The image moves from the original position along the arc over the course of 5 seconds. As the animation repeats, it builds upon the previous value and begins the second arc where the first one ended, as illustrated in Figure 1, below. In this way, the image "bounces" across the screen. The same animation could be described as a complete path of 4 arcs, but in the general case the path description can get quite large and cumbersome to edit.

Figure 1 - Illustration of repeating animation with accumulate="sum".

Diagram showing accumlating animation

Figure 1 - A cumulative repeating animation. Each repeat iteration builds upon the previous.

Note that cumulative animation only controls how a single animation accumulates the results of the simple animation function as it repeats. It specifically does not control how one animation interacts with other animations to produce a presentation value. This latter behavior is described in the section Additive animation. Similarly, if an element restarts, the accumulate from the first run is not applied to the second. See Restarting animations.

Any numeric attribute that supports addition can support cumulative animation. For example, we can define a "pulsing" animation that will grow the "width" of an SVG <rect> element by 100 pixels in 50 seconds.

<rect width="20px"...>
   <animate attributeName="width" dur="5s"
      values="0; 15; 10" additive="sum"
      accumulate="sum" repeatCount="10" />
</rect>

Each simple duration causes the rectangle width to bulge by 15 pixels and end up 10 pixels larger. The shape is 20 pixels wide at the beginning, and after 5 seconds is 30 pixels wide. The animation repeats, and builds upon the previous values. The shape will bulge to 45 pixels and then end up 40 pixels wide after 10 seconds, and will eventually end up 120 (20 + 100) pixels wide after all 10 repeats.

Freezing animations

Animation elements follow the definition of fill in the Timing module. This section extends that specification to cover animation-specific semantics.

By default when an animation element ends, its effect is no longer applied to the presentation value for the target attribute. For example, if an animation moves an image and the animation element ends, the image will "jump back" to its original position.

<img top="3" ...>
   <animate begin="5s" dur="10s" attributeName="top" by="100"/>
</img>

As shown in Figure 2, the image will appear stationary at the top value of "3" for 5 seconds, then move 100 pixels down in 10 seconds. 15 seconds after the document begin, the animation ends, the effect is no longer applied, and the image jumps back from 103 to 3 where it started (i.e. to the underlying DOM value of the top attribute).

Figure 2 - Illustration of animation without freezing.

Diagram showing an animation with default fill.

Figure 2 - Simple animation without freezing. After the animate element ends, the effect of the animation is removed.

The fill attribute can be used to maintain the value of the animation after the active duration of the animation element ends:

<img top="3" ...>
   <animate begin= "5s" dur="10s" attributeName="top" by="100"
          fill="freeze" />
</img>

The animation ends 15 seconds after the document begin, but the image remains at the top value of 103 (Figure 3). The attribute freezes the last value of the animation for the duration of the freeze effect. This duration is controlled by the time container (for details, see SMIL Timing and Synchronization).

Figure 3 - Illustration of animation with fill="freeze".

Diagram showing a frozen animation.

Figure 3 - Simple frozen animation. After the animate element ends, the effect of the animation is retained.

If the active duration cuts short the simple duration (including the case of partial repeats), the effect value of a frozen animation is defined by the shortened simple duration. In the following example, the simple animation function repeats two full times and then again for one-half of the simple duration. In this case, the value while frozen will be 53: 

<img top="3" ...>
   <animate begin= "5s" dur="10s" attributeName="top" by="100"
          repeatCount="2.5" fill="freeze" />
</img>

Figure 4 - Illustration of animation combining a partial repeat and fill="freeze".

Diagram showing an animation with a partial repeat and freezing.

In the following example, the dur attribute is missing, and so the simple duration is indefinite. The active duration is constrained by end to be 10 seconds. Interpolation is not defined, and the value while frozen will be the from value, 10:

<animate from="10" to="20" end="10s" fill="freeze" .../> 

Stating this formally:

Normative

The frozen animation function, ff(t), for an element with active duration AD, is given by

ff(t) = fc(t) for all times t: 0<=t<AD (i.e. before it is frozen)

When the element is frozen, t is effectively equal to AD.

The following equations assume that t is set to AD when the element is frozen.

If AD is not an even multiple of the simple duration d, ff(t) = fi(t), where i = floor(t/d).

This is equivalent to fc(t), except that fc(t) is not formally defined for t=AD. In this case, the equations remain consistent, and so the equivalent of fc(t) is used for the frozen value ff(t).

If AD is an even multiple of d, i.e. AD = d*i for some positive integer i , and the animation is non-cumulative,
ff(t) = f(d)
.

If AD is an even multiple of d, i.e. AD = d*i for some positive integer i, and the animation is cumulative,

ff(t) = f(d) * i.

Note that f(d) is a shorthand for the "last value defined for the animation function" (e.g., the "to" value or the last value in the "values" list).

3.4.6 Additive animation

This section is informative.

In addition to repeating and accumulating values of a single animation, an animation may be expressed as a delta to an attribute's value, rather than as an absolute value. This can be used in a single animation to modify the underlying DOM value, or complex animations can be produced by combining several simple ones.

For example, a simple "grow" animation can increase the width of an object by 10 pixels:

<rect width="20px" ...>
   <animate attributeName="width" from="0px" to="10px" dur="10s"
      additive="sum"/>
</rect>

The width begins at 20 pixels, and increases to 30 pixels over the course of 10 seconds.  If the animation were declared to be non-additive, the same from and to values would make the width go from 0 to 10 pixels over 10 seconds.

Many complex animations are best expressed as combinations of simpler animations. A "vibrating" path, for example, can be described as a repeating up and down motion added to any other motion:

<img ...>
   <animateMotion from="0,0" to="100,0" dur="10s" />
   <animateMotion values="0,0; 0,5; 0,0" dur="1s"
                  repeatDur="10s" additive="sum"/>
</img>

This section is normative.

The animation effect function, captures the semantics of this for a single animation element:

Normative

Every animation element must be defined as either additive or non-additive. An element may be defined as additive only if addition is defined for type type of the target attribute.

If the animation is additive, F(t,u) = u + ff(t).

If the animation is non-additive, F(t,u) = ff(t).

This section is informative.

When there are multiple animations defined for a given attribute that overlap at any moment, the two either add together or one overrides the other. Animations overlap when they are both either active or frozen at the same moment. The ordering of animations (e.g. which animation overrides which) is determined by a priority associated with each animation. The animations are prioritized according to when each begins. The animation first begun has lowest priority and the most recently begun animation has highest priority.

Higher priority animations that are not additive will override all earlier (lower priority) animations, and simply set the attribute value.  Animations that are additive apply (i.e. add to) to the result of the earlier-activated animations. For details on how animations are combined, see The animation sandwich model.

Additive animation is defined for numeric attributes and other data types for which an addition function is defined. This includes numeric attributes for concepts such as position, widths and heights, sizes, etc. This also includes color (refer to The animateColor element), and may include other data types as specified by the host language.

It is often useful to combine additive animations and fill behavior, for example when a series of motions are defined that should build upon one another:

<img ...>
   <animateMotion begin="0" dur="5s" path="[some path]"
           additive="sum" fill="freeze" />
   <animateMotion begin="5s" dur="5s" path="[some path]"
           additive="sum" fill="freeze" />
   <animateMotion begin="10s" dur="5s" path="[some path]"
           additive="sum" fill="freeze" />
</img>

The image moves along the first path, and then starts the second path from the end of the first, then follows the third path from the end of the second, and stays at the final point.

While many animations of numerical attributes will be additive, this is not always the case. As an example of an animation that is defined to be non-additive, consider a hypothetical extension animation "mouseFollow" that causes an object to track the mouse. 

<img ...>
   <animateMotion dur="10s" repeatDur="indefinite"
           path="[some nice path]" />
   <mouseFollow begin="mouseover" dur="5s"
           additive="replace" fill="remove" />
</img>

The mouse-tracking animation runs for 5 seconds every time the user mouses over the image. It cannot be additive, or it will just offset the motion path in some odd way. The mouseFollow needs to override the animateMotion while it is active. When the mouseFollow completes, its effect is no longer applied and the animateMotion again controls the presentation value for position.

In addition, some numeric attributes (e.g. a telephone number attribute) may not sensibly support addition. It is left to the host language to specify which attributes support additive animation. Attribute types for which addition is not defined, such as strings and Booleans, cannot support additive animation.

Additive and Cumulative animation

The accumulate attribute should not be confused with the additive attribute. The additive attribute defines how an animation is combined with other animations and the base value of the attribute.  The accumulate attribute defines only how the simple animation function interacts with itself, across repeat iterations.

Typically, authors expect cumulative animations to be additive (as in the examples described for accumulate above), but this is not required. The following example is cumulative but not additive.

<img ...>
   <animate dur="10s" repeatDur="indefinite"
            attributeName="top" from="20" by="10"
            additive="replace" accumulate="sum" />
</img>

The animation overrides whatever original value was set for "top", and begins at the value 20. It moves down by 10 pixels to 30, then repeats. It is cumulative, so the second iteration starts at 50 (the value of 30 from the previous iteration plus the from value, 20) and moves down by another 10 to 60, and so on.

When a cumulative animation is also defined to be additive, the two features function normally. The accumulated effect for F(t,u) is used as the value for the animation, and is added to the underlying value for the target attribute. For example:

<img top="10" ... >
  <animate dur="10s" repeatdur="indefinite"

           attributename="top" from="20" by="10"

           additive="sum" accumulate="sum" />
</img>

The animation adds to the original value of 10 that was set for "top", and begins at the value 30. It moves down by 10 pixels to 40, then repeats. It is cumulative, so the second iteration starts at 60 (the value of 40 from the previous iteration plus 20) and moves down by another 10 to 70, and so on.

Refer also to The animation sandwich model.

3.4.7 Restarting animations

This section is informative.

Animation elements follow the definition of restart in the SMIL Timing module. This section is descriptive.

When an animation restarts, the defining semantic is that it behaves as though this were the first time the animation had begun, independent of any earlier behavior. The animation effect function F(t,u) is defined independent of the restart behavior. Any effect of an animation playing earlier is no longer applied, and only the current animation effect F(t,u) is applied.

If an additive animation is restarted while it is active or frozen, the previous effect of the animation (i.e. before the restart) is no longer applied to the attribute. Note in particular that cumulative animation is defined only within the active duration of an animation. When an animation restarts, all accumulated context is discarded, and the animation effect F(t,u) begins accumulating again from the first iteration of the restarted active duration.

3.4.8 Animation function value details

Many animations specify the simple animation function f(t) as a sequence of values to be applied over time. For some types of attributes (e.g. numbers), it is also possible to describe an interpolation function between values.

As a simple form of describing the values, animation elements can specify a from value and a to value. If the attribute takes values that support interpolation (e.g. a number), the simple animation function can interpolate values in the range defined by  from and to, over the course of the simple duration. A variant on this uses a by value in place of the to value, to indicate an additive change to the attribute.

More complex forms specify a list of values, or even a path description for motion. Authors can also control the timing of the values, to describe "keyframe" animations, and even more complex functions.

In all cases, the animation effect function, F(t,u), must yield legal values for the target attribute. Three classes of values are described:

  1. Unitless scalar values. These are simple scalar values that can be parsed and set without semantic constraints. This class includes integers (base 10) and floating point (format specified by the host language).
  2. String values. These are simple strings.
  3. Language abstract values. These are values like CSS-length and CSS-angle values that have more complex parsing, but that can yield values that may be interpolated.

The animate element can interpolate unitless scalar values, and both animate and set elements can handle String values without any semantic knowledge of the target element or attribute. The animate and set elements must support unitless scalar values and string values. The host language must define which additional language abstract values should be handled by these elements. Note that the animateColor element implicitly handles the abstract values for color values, and that the animateMotion element implicitly handles position and path values. 

In order to support interpolation on attributes that define numeric values with some sort of units or qualifiers (e.g. "10px", "2.3feet", "$2.99"), some additional support is required to parse and interpolate these values. One possibility is to require that the animation framework have built-in knowledge of the unit-qualified value types. However, this violates the principle of encapsulation and does not scale beyond CSS to XML languages that define new attribute value types of this form.

The recommended approach is for the animation implementation for a given host environment to support two interfaces that abstract the handling of the language abstract values. These interfaces are not formally specified, but are simply described as follows:

  1. The first interface converts a string (the animation function value) to a unitless, canonical number (either an integer or a floating point value). This allows animation elements to interpolate between values without requiring specific knowledge of data types like CSS-length. The interface will likely require a reference to the target attribute, to determine the legal abstract values. If the passed string cannot be converted to a unitless scalar, the animation element will treat the animation function values as strings, and the calcMode will default to "discrete".
  2. The second interface converts a unitless canonical number to a legal string value for the target attribute. This may, for example, simply convert the number to a string and append a suffix for the canonical units. The animation element uses the result of this to actually set the presentation value.

Support for these two interfaces ensures that an animation engine need not replicate the parser and any additional semantic logic associated with language abstract values. 

This is not an attempt to specify how an implementation provides this support, but rather a requirement for how values are interpreted. Animation behaviors should not have to understand and be able to convert among all the CSS-length units, for example. In addition, this mechanism allows for application of animation to new XML languages, if the implementation for a language can provide parsing and conversion support for attribute values.

The above recommendations notwithstanding, it is sometimes useful to interpolate values in a specific unit-space, and to apply the result using the specified units rather than canonical units. This is especially true for certain relative units such as those defined by CSS (e.g. em units). If an animation specifies all the values in the same units, an implementation may use knowledge of the associated syntax to interpolate in the unit space, and apply the result within the animation sandwich, in terms of the specified units rather than canonical units. As noted above, this solution does not scale well to the general case. Nevertheless, in certain applications (such as CSS properties), it may be desirable to take this approach.

Interpolation and indefinite simple durations

If the simple duration of an animation is indefinite (e.g. if no dur value is specified), interpolation is not generally meaningful. While it is possible to define an animation function that is not based upon a defined simple duration (e.g. some random number algorithm), most animations define the function in terms of the simple duration. If an animation function is defined in terms of the simple duration and the simple duration is indefinite, the first value of the animation function (i.e. f(0)) should be used (effectively as a constant) for the animation function.

3.5 Overview of the SMIL 3.0 BasicAnimation Module

This section is informative.

The SMIL 3.0 BasicAnimation module provides

The BasicAnimation module defines attributes and elements following the model presented in the Animation Model section.

3.6 SMIL 3.0 BasicAnimation Module Common Attributes

The elements of the BasicAnimation module have in common the attributes used to identify the target attribute and, less universally, the attributes by which the animation functions are specified.

3.6.1 Specifying the animation target

This section is normative.

The animation target is defined as a specific attribute of a particular element. The means of specifying the target attribute and the target element are detailed in this section.

The target attribute

The target attribute to be animated is specified with attributeName. The value of this attribute is a string that specifies the name of the target attribute, as defined in the host language.

The attributes of an element that can be animated are often defined by different languages, and/or in different namespaces. For example, in many XML applications, the position of an element (which is a typical target attribute) is defined as a CSS property rather than as XML attributes. In some cases, the same attribute name is associated with attributes or properties in more than one language, or namespace.  To allow the author to disambiguate the name mapping, an additional attribute attributeType is provided that specifies the intended namespace. 

The attributeType attribute is optional. By default, the animation runtime will resolve the names according to the following rule: If there is a name conflict and attributeType is not specified, the list of CSS properties supported by the host language is matched first (if CSS is supported in the host language); if no CSS match is made (or CSS does not apply) the per-element-type partition namespace for the target element will be matched.

If a target attribute is defined in an XML Namespace other than the per-element-type partition namespace for the target element, the author must specify the namespace of the target attribute using the associated namespace prefix as defined in the scope of the animation element. The prefix is prepended to the value for attributeName.

For more information on XML namespaces, see [XML-NS].

Target attribute attributes
 
attributeName
Specifies the name of the target attribute. An xmlns prefix may be used to indicate the XML namespace for the attribute [XML-NS]. The prefix will be interpreted in the scope of the animation element.
 
attributeType
Specifies the namespace in which the target attribute and its associated values are defined. The attribute value is one of the following (values are case-sensitive):
CSS
This specifies that the value of attributeName is the name of a CSS property, as defined for the host document. This argument value is only meaningful in host language environments that support CSS.
XML
This specifies that the value of "attributeName" is the name of an XML attribute defined in the default XML namespace for the target element. Note that if the value for attributeName has an XMLNS prefix, the implementation must use the associated namespace as defined in the scope of the animation element.
auto
The implementation should match the attributeName to an attribute for the target element. The implementation must first search through the list of CSS properties for a matching property name, and if none is found, search the default XML namespace for the element.
This is the default.

The target element

An animation element can define the target element of the animation either explicitly or implicitly. An explicit definition uses an attribute to specify the target element. The syntax for this is described below.

If no explicit target is specified, the implicit target element is the parent element of the animation element in the document tree. It is expected that the common case will be that an animation element is declared as a child of the element to be animated. In this case, no explicit target need be specified.

If an explicit target element reference cannot be resolved (e.g. if no such element can be found), the animation has no effect. In addition, if the target element (either implicit or explicit) does not support the specified target attribute, the animation has no effect. See also Handling syntax errors.

The following two attributes can be used to identify the target element explicitly:

Target element attributes
 
targetElement
This attribute specifies the target element to be animated. The attribute value must be the value of an XML identifier attribute of an element (i.e. an "IDREF") within the host document. For a formal definition of IDREF, refer to XML 1.1 [XML11]
href
This attribute specifies the target element to be animated. The attribute value must be an XLink locator, referring to the target element to be animated.

When integrating animation elements into the host language, the language designer should avoid including both of these attributes. If however, the host language designer chooses to include both attributes in the host language, then when both are specified for a given animation element the XLink href attribute takes precedence over the targetElement attribute.

The advantage of using the targetElement attribute is the simpler syntax of the attribute value compared to the href attribute. The advantage of using the XLink href attribute is that it is extensible to a full linking mechanism in future versions of SMIL Animation, and the animation element can be processed by generic XLink processors. The XLink form is also provided for host languages that are designed to use XLink for all such references. The following two examples illustrate the two approaches.

This example uses the simpler targetElement syntax:

<animate targetElement="foo" attributeName="bar" .../> 

This example uses the more flexible XLink locater syntax, with the equivalent target:

<foo xmlns:xlink="http://www.w3.org/1999/xlink">
   ...
   <animate xlink:href="#foo" attributeName="bar" .../>
   ...
</foo>

When using an XLink href attribute on an animation element, the following additional XLink attributes need to be defined in the host language. These may be defined in a DTD, or the host language may require these in the document syntax to support generic XLink processors. For more information, refer to [XLINK].

The following XLink attributes are required by the XLink specification. The values are fixed, and so may be specified as such in a DTD. All other XLink attributes are optional, and do not affect SMIL Animation semantics.

XLink attributes for href
 
type
Must be simple. Identifies the type of XLink being used.
actuate
Must be onLoad. Indicates that the link to the target element is followed automatically (i.e., without user action).
show
Must be embed. Indicates that the reference does not include additional content in the file. 

Additional details on the target element specification as relates to the host document and language are described in Required definitions and constraints on animation targets.

3.6.2 Specifying the simple animation function f(t)

Every animation function defines the value of the attribute at a particular moment in time. The time range for which the animation function is defined is the simple duration. The animation function does not produce defined results for times outside the range of 0 to the simple duration.

An animation is described either as a list of values, or in a simplified form that describes the from, to and by values. The from/to/by form is defined in Simple animation functions defined by from, to and by.

Simple animation function attributes
values
A semicolon-separated list of one or more values, each of which must be a legal value for the specified attribute. Vector-valued attributes are supported using the vector syntax of the attributeType domain. Leading and trailing white space, and white space before and after semi-colon separators, will be ignored.

If any values are not legal, the animation will have no effect (see also Handling Syntax Errors).

calcMode
Specifies the interpolation mode for the animation. If the target attribute does not support linear interpolation (e.g. for strings), or if the values attribute has only one value, the calcMode attribute is ignored and discrete interpolation is used. The calcMode attribute can take any of the following values:
discrete
This specifies that the animation function will jump from one value to the next without any interpolation.
linear
Simple linear interpolation between values is used to calculate the animation function. 
This is the default.
paced
Defines interpolation to produce an even pace of change across the animation. This is only supported for values that define a linear numeric range, and for which some notion of "distance" between points can be calculated (e.g. position, width, height, etc.).

The animation will apply the values in order over the course of the animation. For discrete and linear animations, values in the values attribute are equally spaced through the animation duration. For paced animations, the values are spaced so that a uniform rate of change is obtained.

This section is informative.

The following example using the values syntax animates the width of an SVG shape over the course of 10 seconds, interpolating from a width of 40 to a width of 100 and back to 40.

<rect ...>
   <animate attributeName="width" values="40;100;40" dur="10s"/>
</rect>

The simple animation function for this example (with time in seconds) is

f(t) = 40 + 60*t/5,       0 <= t < 5, and
f(t) = 100 - 60*(t-5)/5,  5 <= t <= 10.

The simple animation function defined by the values and calcMode attributes can be formally specified:

Normative

Let i = floor((t*n)/d), d be the simple duration of the animation element, n be the number of entries in the values attribute, value[i] be the ith entry (counting from 0), di be the duration of the the ith time period, and ti be the time at which the the ith time period begins.

Note that a linear or paced animation will be a smoothly closed loop if the first value is repeated as the last. The keyTimes attribute is described in the SplineAnimation section.

Interpolation modes illustrated

This section is informative.

The three figures 5a, 5b and 5c below show how the same basic animation will change a value over time, given different interpolation modes.  All examples are based upon the following example, but with different values for calcMode:

<animate dur="30s" values="0; 6; 5; 11; 10; 16" calcMode="[as specified]" />

Figure 5 - Discrete, linear and paced animation

Diagram of linear         interpolation

Figure 5a: Default discrete animation.

calcMode="discrete"

There are 6 segments of equal duration: 1 segment per value.

Diagram of linear interpolation

Figure 5b: Default linear animation.

calcMode="linear"

There are 5 segments of equal duration: n-1 segments for n values.

Diagram of linear interpolation

Figure 5c: Default paced animation.

calcMode="paced"

There are 5 segments of varying duration: n-1 segments for n values, computed to yield a constant rate of change in the value.

Examples of calcMode

The following example describes a simple discrete animation:

<animate attributeName="foo" dur="8s" 
     values="bar; fun; far; boo" />

The value of the attribute "foo" will be set to each of the four strings for 2 seconds each. Because the string values cannot be interpolated, only discrete animation is possible; any calcMode attribute would be ignored.

The following example describes a simple linear animation:

<animate attributeName="x" dur="10s" values="0; 10; 100" 
     calcMode="linear"/>

The value of "x" will change from 0 to 10 in the first 5 seconds, and then from 10 to 100 in the second 5 seconds. Note that the values in the values attribute are spaced evenly in time; in this case the result is a much larger actual change in the value during the second half of the animation. Contrast this with the same example changed to use "paced" interpolation:

<animate attributeName="x" dur="10s" values="0; 10; 100" 
     calcMode="paced"/>

To produce an even pace of change to the attribute "x", the second segment defined by the values list gets most of the simple duration: The value of "x" will change from 0 to 10 in the first second, and then from 10 to 100 in the next 9 seconds. While this example could be easily authored as a from-to animation without paced interpolation, many examples (such as motion paths) are much harder to author without the paced value for calcMode

3.6.3 Specifying the animation effect function F(t,u)

This section is normative.

As described in The animation effect function F(t,u), the simple animation function may be

The animation effect function F(t,u) defines the semantics of these attributes, and give examples. This section gives only the syntax.

See the BasicInlineTiming module for definitions of the attributes repeatCount, repeatDur and fill.

The additive and cumulative behavior of repeating animations is controlled with the additive and accumulate attributes, respectively:

Animation effect function attributes
accumulate
Controls whether or not the animation is cumulative. May be either of the following two values:
sum
Specifies that the animation is cumulative, i.e. each repeat iteration after the first builds upon the last value of the previous iteration.
none
Specifies that the animation is non-cumulative, i.e. repeat iterations simply repeat the animation function f(t).
This is the default.
This attribute is ignored if the target attribute value does not support addition, or if the animation element does not repeat.
additive
Controls whether or not the animation is additive. 
sum
Specifies that the animation is additive, i.e. will add to the underlying value of the attribute and other lower priority animations.
replace
Specifies that the animation is non-additive, i.e. will override the underlying value of the attribute and other lower priority animations. This is the default.
This attribute is ignored if the target attribute does not support additive animation.

3.6.4 Simple animation functions specified by from, to and by

An animation is described either as a list of values, as described earlier, or in a simplified form that uses from, to and by values.

From/to/by attributes for simple animation functions
from
Specifies the starting value of the animation. Must be a legal value for the specified attribute. Ignored if the values attribute is specified.
to
Specifies the ending value of the animation. Must be a legal value for the specified attribute. Ignored if the values attribute is specified.
by
Specifies a relative offset value for the animation. Must be a legal value of a domain for which addition to the attributeType domain is defined and which yields a value in the attributeType domain. Ignored if the values attribute is specified.

The simpler from/to/by syntax provides for several variants. To use one of these variants, one of by or to must be specified; a from value is optional. It is not legal to specify both by and to attributes; if both are specified, only the to attribute will be used (the by will be ignored). The combinations of attributes yield the following classes of animation.

from-to animation
Specifying a from value and a to value defines a simple animation. The animation function is defined to start with the from value, and to finish with the to value.

Normative: A from-to animation with a from value vf and a to value vt is equivalent to the same animation with a values list with 2 values, vf and vt.
from-by animation
Specifying a from value and a by value defines a simple animation in which the animation function is defined to start with the from value, and to change this over the course of the simple duration by a delta specified with the by attribute. This may only be used with attributes that support addition (e.g. most numeric attributes).

Normative: A from-by animation with a from value vf and a by value vb is equivalent to the same animation with a values list with 2 values, vf and (vf+vb).
by animation
Specifying only a by value defines a simple animation in which the animation function is defined to offset the underlying value for the attribute, using a delta that varies over the course of the simple duration, starting from a delta of 0 and ending with the delta specified with the by attribute. This may only be used with attributes that support additive animation.

Normative: A by animation with a by value vb is equivalent to the same animation with a values list with 2 values, 0 and vb, and additive="sum". Any other specification of the additive attribute in a by animation is ignored.
to animation
This describes an animation in which the animation function is defined to start with the underlying value for the attribute, and finish with the value specified with the to attribute. Using this form, an author can describe an animation that will start with any current value for the attribute, and will end up at the desired to value.

A normative definition of a to animation is given below in To animation

This section is informative.

Examples

The following "from-to animation" example animates the width of an SVG shape over the course of 10 seconds from a width of 50 to a width of 100.

<rect ...>
   <animate attributeName="width" from="50" to="100" dur="10s"/>
</rect>

The following "from-by animation" example animates the width of an SVG shape over the course of 10 seconds from a width of 50 to a width of 75.

<rect ...>
   <animate attributeName="width" from="50" by="25" dur="10s"/>
</rect>

The following "by animation" example animates the width of an SVG shape over the course of 10 seconds from the original width of 40 to a width of 70.

<rect width="40"...>
   <animate attributeName="width" by="30" dur="10s"/>
</rect>

From-to and from-by animations also support cumulative animation, as in the following example:

<rect width="20px"...>
   <animate attributeName="width" dur="5s" from="10px" to="20px"
      accumulate="sum" repeatCount="10" />
</rect>

The rectangle will grow from 10 to 20 pixels in the first 5 seconds, and then from 20 to 30 in the next 5 seconds, and so on up to 110 pixels after 10 repeats. Note that since the default value for additive is replace, the original value is ignored. The following example makes the animation explicitly additive:

<rect width="20px"...>
   <animate attributeName="width" dur="5s" from="10px" to="20px"
      accumulate="sum" additive="sum" repeatCount="10" />
</rect>

The results are the same as before, except that all the values are shifted up by the original value of 20. The rectangle is 30 pixels wide after 5 seconds, and 130 pixels wide after 10 repeats.

To animation

A to animation of an attribute which supports addition is a kind of mix of additive and non-additive animation. The underlying value is used as a starting point as with additive animation, however the ending value specified by the to attribute overrides the underlying value as though the animation was non-additive.

The following "to animation" example animates the width of an SVG shape over the course of 10 seconds from the original width of 40 to a width of 100.

<rect width="40"...>
   <animate attributeName="width" to="100" dur="10s"/>
</rect>

Since a to animation has only 1 value, a discrete to animation will simply set the to value for the simple duration. In the following example, the rect will be blue for the 10 second duration of the animate element.

<rect color="red"...>
   <animate attributeName="color" to="blue" dur="10s" calcMode="discrete"/>
</rect>

The semantics of to animation fit into the general animation model, but with a few special cases. The normative definition given here parallels the definition for other types of animation presented in the Animation Model section.

Normative

The simple animation function f(t,u) for a to animation with to value vt is a linear interpolation between the underlying value, u, and the to value:

f(t,u) = (u * (d-t)/d) + (vt * t/d), for t: 0<=t<=d where d is the simple duration.

If no other (lower priority) animations are active or frozen, this defines simple interpolation. However if another animation is manipulating the underlying value, the to animation will initially add to the effect of the lower priority animation, and increasingly dominate it as it nears the end of the simple duration, eventually overriding it completely. The value for f(t,u) at the end of the simple duration is just the to value.

Repeating to animations is the same as repeating other animations:

Normative

The repeated animation function, fr(t,u), has the standard definition:
fr(t,u) = f( REMAINDER(t,d), u ).

Because to animation is defined in terms of absolute values of the target attribute, cumulative animation is not defined:

Normative

The cumulative animation function, fc(t), for a to animation is
fc(t,u) =fr(t,u).

A frozen to animation takes on the value at the time it is frozen, masking further changes in the underlying value. This matches the dominance of the to value at the end of the simple duration. Even if other, lower priority animations are active while a to animation is frozen, the value does not change.

Normative

The frozen animation function, ff(t), for a to animation is
ff(t,u) = fc(t,u), if the animation is not frozen at time t, and

ff(t,u) = vf, if the animation is frozen at time t, where vf is the value of ff(t,u) at the moment the animation was frozen.

For example, consider

<rect width="40"...>
   <animate attributeName="width" to="100" dur="10s" repeatCount="2.5" fill="freeze"/>
</rect>

The width will animate from 40 to 100 pixels in the first 10 seconds, repeat 40 to 100 in the second 10 seconds, go from 40 to 70 in the final 5 seconds, and freeze at 70.

To animation defines its own kind of additive semantics, so the additive attribute is ignored.

Normative

The animation effect function, F(t,u) for a to animation is
F(t,u) = ff(t,u).

Multiple to animations will also combine according to these semantics. As the animation progresses, the higher-priority animation will have greater and greater effect, and the end result will be to set the attribute to the final value of the higher-priority to animation.

This section is informative.

For an example of additive to animation, consider the following two additive animations. The first, a by-animation applies a delta to attribute "x" from 0 to -10. The second, a to animation animates to a final value of 10.

 <foo x="0" ...>
    <animate id="A1" attributeName="x" 
        by="-10" dur="10s" fill="freeze" />
    <animate id="A2" attributeName="x" 
        to="10"  dur="10s" fill="freeze" />
 </foo>

The presentation value for "x" in the example above, over the course of the 10 seconds is presented in Figure 6 below. These values are simply computed using the formula described above. Note that the value for F(t,u) for A2 is the presentation value for "x", since A2 is the higher-priority animation.

Figure 6 - Effect of Additive to animation example

Time F(t,u) for A1 F(t,u) for A2
 0 0 0
 1 -1 0.1
 2 -2 0.4
 3 -3 0.9
 4 -4 1.6
 5 -5 2.5
 6 -6 3.6
 7 -7 4.9
 8 -8 6.4
 9 -9 8.1
10 -10 10

3.7 SMIL 3.0 BasicAnimation Elements

This section is normative.

The SMIL BasicAnimation module defines four elements, animate, set, animateMotion and animateColor.

3.7.1 The animate element

The animate element introduces a generic attribute animation that requires little or no semantic understanding of the attribute being animated. It can animate numeric scalars as well as numeric vectors. It can also animate a single non-numeric attribute through a discrete set of values. The animate element is an empty element; it cannot have child elements.

This element supports from/to/by and values descriptions for the animation function, as well as all of the calculation modes. It supports all the described timing attributes. These are all described in respective sections above.

Element attributes
attributeName and
attributeType
The attribute to be animated. See The target attribute. attributeName is required; attributeType is optional.
targetElement,
href,
actuate,
show, and
type
The target element. See The target element. All are optional.
 
from,
to,
by,
values,
calcMode,
accumulate, and
additive
 
Specify the animation function and effect. See Specifying the simple animation function f(t) and Specifying the animation effect F(t,u).

Numerous examples are provided above, as are normative definitions of the semantics of all attributes supported by animate.

3.7.2 The set element

The set element provides a simple means of just setting the value of an attribute for a specified duration. As with all animation elements, this only manipulates the presentation value, and when the animation completes, the effect is no longer applied. That is, set does not permanently set the value of the attribute. 

The set element supports all attribute types, including those that cannot reasonably be interpolated and that more sensibly support semantics of simply setting a value (e.g. strings and Boolean values). The set element is non-additive. The additive and accumulate attributes are not allowed, and will be ignored if specified.

The set element supports all the timing attributes to specify the simple and active durations. However, the repeatCount and repeatDur attributes will just affect the active duration of the set, extending the effect of the set (since it is not really meaningful to "repeat" a static operation). Note that using fill="freeze" with set will have the same effect as defining the timing so that the active duration is indefinite.

The set element supports a more restricted set of attributes than the  animate element. Only one value is specified, and neither interpolation control nor additive or cumulative animation is supported:

Element attributes
attributeName and
attributeType
The attribute to be animated. See The target attribute. attributeName is required; attributeType is optional.
 
targetElement,
href,
actuate,
show, and
type
The target element. See The target element. All are optional.
to
Specifies the value for the target attribute during the active duration of the set element. The argument value must match the target attribute type.

Normative

The simple animation function defined by a set element is
f(t) = v

were v is the value of the to attribute.

The set element is non-cumulative and non-additive.

This section is informative.

Examples

The following changes the stroke-width of an SVG rectangle from the original value to 5 pixels wide. The effect begins at 5 seconds and lasts for 10 seconds, after which the original value is again used.

<rect ...>
   <set attributeName="stroke-width" to="5px" 
            begin="5s" dur="10s" fill="remove" />
</rect>

The following example sets the class attribute of the text element to the string "highlight" when the mouse moves over the element, and removes the effect when the mouse moves off the element. 

<text>This will highlight if you mouse over it...
   <set attributeName="class" to="highlight" 
            begin="mouseover" end="mouseout" />
</text> 

3.7.3 The animateMotion element

The animateMotion element will move an element along a path. The element abstracts the notion of motion and position across a variety of layout mechanisms - the host language defines the layout model and must specify the precise semantics of position and motion. The path can be described in either of two ways:

All values must be x, y value pairs. Each x and y value may specify any units supported for element positioning by the host language. The host language defines the default units. In addition, the host language defines the reference point for positioning an element. This is the point within the element that is aligned to the position described by the motion animation. The reference point defaults in some languages to the upper left corner of the element bounding box; in other languages the reference point may be implicit, or may be specified for an element.

The syntax for the x, y value pairs is:

coordinate-pair ::= "("coordinate comma-wsp coordinate")"
coordinate      ::= num
num             ::= Number

Coordinate values are separated by at least one white space character or a comma. Additional white space around the separator is allowed. The values of coordinate must be defined as some sort of number in the host language.

The attributeName and attributeType attributes are not used with animateMotion, as the manipulated position attribute(s) are defined by the host language. If the position is exposed as an attribute or attributes that can also be animated (e.g. as "top" and "left", or "posX" and "posY"), implementations must combine animateMotion animations with other animations that manipulate individual position attributes. See also The animation sandwich model.

If none of the from, to, by and values attributes are specified, the animation will have no effect.

The default calculation mode (calcMode) for animateMotion is paced. This will produce constant velocity motion along the specified path. Note that while animateMotion elements can be additive, the addition of two or more paced (constant velocity) animations may not result in a combined motion animation with constant velocity.

Element attributes
 
targetElement,
href,
actuate,
show, and
type
The target element. See The target element. All are optional.
from,
to,
by,
values,
accumulate, and
additive
 
Specify the animation function and effect. See Specifying the simple animation function f(t) and Specifying the animation effect F(t,u).
calcMode 
Defined as above in Specifying the simple animation function f(t), but note that the default calcMode for animateMotion is paced. This will produce constant velocity motion.

The use of linear for the calcMode with more than 2 points described in the values attribute may result in motion with varying velocity. The linear calcMode specifies that time is evenly divided among the segments defined by the values. The use of linear does not specify that time is divided evenly according to the distance described by each segment. 

For motion with constant velocity, calcMode should be set to paced.

origin
Specifies the origin of motion for the animation. The values and semantics of this attribute are dependent upon the layout and positioning model of the host language. In some languages, there may be only one option, default. However, in CSS positioning for example, it is possible to specify a motion path relative to the container block, or to the layout position of the element. It is often useful to describe motion relative to the position of the element as it is laid out (e.g. from off screen left to the layout position, specified as from="(-100,0)" and to="(0,0)". Authors must be able to describe motion both in this manner, as well as relative to the container block. The origin attribute supports this distinction. Nevertheless, because the host language defines the layout model, the host language must also specify the "default" behavior, as well as any additional attribute values that are supported.
Note that the definition of the layout model in the host language specifies whether containers have bounds, and the behavior when an element is moved outside the bounds of the layout container. In CSS2 [CSS2], for example, this can be controlled with the "clip" property.
Note that for additive animation, the origin distinction is not meaningful.  This attribute only applies when additive is set to replace.

3.7.4 The animateColor element

The animateColor element specifies an animation of a color attribute. The host language must specify those attributes that describe color values and can support color animation.

All values must represent [sRGB] color values. Legal value syntax for attribute values is defined by the host language.

Interpolation is defined on a per-color-channel basis.

Element attributes
attributeName and
attributeType
The attribute to be animated. See The target attribute. attributeName is required; attributeType is optional.
targetElement,
href,
actuate,
show, and
type
The target element. See The target element. All are optional.
 
from,
to,
by,
values,
calcMode,
accumulate, and
additive
 
Specify the animation function and effect. See Specifying the simple animation function f(t), Specifying the animation effect F(t,u).

The values in the from/to/by and values attributes may specify negative and out of gamut values for colors.  The function defined by an individual animateColor may yield negative or out of gamut values.  The implementation must correct the resulting presentation value, to be legal for the destination (display) colorspace. However, as described in The animation sandwich model, the implementation should only correct the final combined result of all animations for a given attribute, and should not correct the effect of individual animations.

Values are corrected by "clamping" the values to the correct range. Values less than the minimum allowed value are clamped to the minimum value (commonly 0, but not necessarily so for some color profiles). Values greater than the defined maximum are clamped to the maximum value (defined by the host language) .

This section is informative.

Note that color values are corrected by clamping them to the gamut of the destination (display) colorspace. Some implementations may be unable to process values which are outside the source (sRGB) colorspace and must thus perform clamping to the source colorspace, then convert to the destination colorspace and clamp to its gamut. The point is to distinguish between the source and destination gamuts; to clamp as late as possible, and to realize that some devices, such as inkjet printers which appear to be RGB devices, have non-cubical gamuts.

Note to implementers: When animateColor is specified as a to animation, the animation function should assume Euclidean RGB-cube distance where deltas must be computed. See also Specifying the simple animation function f(t) and Simple animation functions specified by from, to and by. Similarly, when the calcMode attribute for animateColor is set to paced, the animation function should assume Euclidean RGB-cube distance to compute the distance and pacing.

3.8 SMIL 3.0 BasicAnimation Module Details

This section is normative.

3.8.1 BasicAnimation integration requirements

This section describes what a language designer must actually do to specify the integration of SMIL Animation into a host language. This includes basic definitions and constraints upon animation.

In addition to the requirements listed in this section, those listed in Common animation integration requirements must be satisfied.

Required definitions and constraints on animation targets

Specifying the target element

The host language designer must choose whether to support the targetElement attribute or the XLink attributes for specifying the target element. Note that if the XLink syntax is used, the host language designer must decide how to denote the XLink namespace for the associated attributes. The namespace can be fixed in a DTD, or the language designer can require colonized attribute names (qnames) to denote the XLink namespace for the attributes. The required XLink attributes have fixed values, and so may also be specified in a DTD, or can be required on the animation elements. Host language designers may require that the optional XLink attributes be specified. These decisions are left to the host language designer - the syntax details for XLink attributes do not affect the semantics of SMIL Animation.

In general, target elements may be any element in the document. Host language designers must specify any exceptions to this. Host language designers are discouraged from allowing animation elements to target elements outside of the document in which the animation element is defined. The XLink syntax for the target element could allow this, but the SMIL timing and animation semantics of this are not defined in this version of SMIL Animation.

Target attribute issues

The definitions in this module can be used to animate any attribute of any element in a host document. However, it is expected that host language designers integrating SMIL Animation may choose to constrain which elements and attributes can support animation. For example, a host language may choose not to support animation of the language attribute of a script element. A host language which included a specification for DOM functionality might limit animation to the attributes which may legally be modified through the DOM.

Any attribute of any element not specifically excluded from animation by the host language may be animated, as long as the underlying data type (as defined by the host language for the attribute) supports discrete values (for discrete animation) and/or addition (for interpolated, additive and cumulative animation).

All constraints upon animation must be described in the host language specification or in an appropriate schema, as the DTD alone cannot reasonably express this.

The host language must define which language abstract values should be handled for animated attributes. For example, a host language that incorporates CSS may require that CSS length values be supported. This is further detailed in Animation function value details.

The host language must specify the interpretation of relative values. For example, if a value is specified as a percentage of the size of a container, the host language must specify whether this value will be dynamically interpreted as the container size is animated.

The host language must specify the semantics of clamping values for attributes. The language must specify any defined ranges for values, and how out of range values will be handled.

The host language must specify the formats supported for numeric attribute values. This includes both integer values and floating point values. As a reasonable minimum, host language designers are encouraged to support the format described in section 4.3.1, "Integers and real numbers," of [CSS2].

Integrating animateMotion functionality

The host language specification must define which elements can be the target of animateMotion. In addition, the host language specification must describe the positioning model for elements, and must describe the model for animateMotion in this context (i.e. the semantics of the default value for the origin attribute must be defined). If there are different ways to describe position, additional attribute values for the origin attribute should be defined to allow authors control over the positioning model.

3.8.2 Document type definition (DTD) for the BasicAnimation module

This section is informative.

See the full DTD for the SMIL Animation Modules.

3.9 Overview of the SMIL 3.0 SplineAnimation Module

This section is normative.

This section defines the functionality of the SMIL 3.0 SplineAnimation module. This module adds attributes for spline interpolation and for uneven spacing of points in time. These attributes may be used in animate, animateMotion and animateColor elements.

3.9.1 SMIL 3.0 SplineAnimation Module Attributes

Spline animation function calculation mode

The SplineAnimation module extends the discrete, linear and paced calculation modes of the BasicAnimation module, providing additional control over interpolation and timing:

Calculation mode attributes
calcMode
In addition to the values discrete, linear and paced of the BasicAnimation module, the SplineAnimation module supports the value
spline
Interpolates from one value in the values list to the next according to a time function defined by a cubic Bezier spline. The points of the spline are defined in the keyTimes attribute, and the control points for each interval are defined in the keySplines attribute.

The use of discrete for the calcMode together with a path specification is allowed, but will simply jump the target element from point to point. The times are derived from the points in the path specification, as described in the path attribute, immediately below.

keyTimes
A semicolon-separated list of time values used to control the pacing of the animation. Each time in the list corresponds to a value in the values attribute list, and defines when the value should be used in the animation function. Each time value in the keyTimes list is specified as a floating point value between 0 and 1 (inclusive), representing a proportional offset into the simple duration of the animation element.

If a list of keyTimes is specified, there must be exactly as many values in the keyTimes list as in the values list.

If no keyTimes attribute is specified, the simple duration is divided into equal segments as described in The simple animation function f(t).

Each successive time value must be greater than or equal to the preceding time value.

The keyTimes list semantics depends upon the interpolation mode:

  • For linear and spline animation, the first time value in the list must be 0, and the last time value in the list must be 1. The keyTime associated with each value defines when the value is set; values are interpolated between the keyTimes.
  • For discrete animation, the first time value in the list must be 0. The time associated with each value defines when the value is set; the animation function uses that value until the next time defined in keyTimes.

If the interpolation mode is paced, the keyTimes attribute is ignored.

If there are any errors in the keyTimes specification (bad values, too many or too few values), the animation will have no effect.

If the simple duration is indefinite and the interpolation mode is linear or spline, any keyTimes specification will be ignored.

keySplines
A set of Bezier control points associated with the keyTimes list, defining a cubic Bezier function that controls interval pacing. The attribute value is a semicolon separated list of control point descriptions. Each control point description is a set of four floating point values: x1 y1 x2 y2, describing the Bezier control points for one time segment. The keyTimes values that define the associated segment are the Bezier "anchor points", and the keySplines values are the control points. Thus, there must be one fewer sets of control points the keySplines attribute than there are keyTimes.

The values must all be in the range 0 to 1.

This attribute is ignored unless the calcMode is set to spline.


If there are any errors in the keySplines specification (bad values, too many or too few values), the animation will have no effect.

This semantic (the duration is divided into n-1 even periods) applies as well when the keySplines attribute is specified, but keyTimes is not. The times associated to the keySplines values are determined as described above.

The syntax for the control point sets in keySplines lists is:

control-pt-set ::= ( fpval comma-wsp fpval comma-wsp fpval comma-wsp fpval )

Using:

fpval          ::= Floating point number
S              ::= spacechar*
comma-wsp      ::= S (spacechar|",") S
spacechar      ::= (#x20 | #x9 | #xD | #xA)

Control point values are separated by at least one white space character or a comma. Additional white space around the separator is allowed. The allowed syntax for floating point numbers must be defined in the host language.

If the  argument values for keyTimes or keySplines are not legal (including too few or too many values for either attribute), the animation will have no effect (see also Handling syntax errors).

In the calcMode, keyTimes and keySplines attribute values, leading and trailing white space and white space before and after semicolon separators will be ignored.

This section is informative.

Examples of advanced uses of calcMode

Discrete animation can be used with keyTimes, as in the following example:

<animateColor attributeName="color" dur="10s" calcMode="discrete"
     values="green; yellow; red" keyTimes="0.0; 0.8;" />

This example also shows how keyTimes values can interact with an indefinite duration. The value of the "color" attribute will be set to green for 5 seconds, and then to yellow for 5 seconds, and then will remain red for the remainder of the document, since the (unspecified) duration defaults to "indefinite".

The following example illustrates the use of keyTimes:

<animate attributeName="x" dur="10s" values="0; 50; 100" 
     keyTimes="0; .8; 1" calcMode="linear"/>

The keyTimes values cause the "x" attribute to have a value of "0" at the start of the animation, "50" after 8 seconds (at 80% into the simple duration) and "100" at the end of the animation. The value will change more slowly in the first half of the animation, and more quickly in the second half.

Interpolation with keySplines

For some attributes, the pace of change may not be easily discernable by viewers. However for animations like motion, the ability to make the speed of the motion change gradually, and not in abrupt steps, can be important. The keySplines attribute provides this control.

Extending the above example to use keySplines:

<animate attributeName="x" dur="10s" values="0; 50; 100" 
     keyTimes="0; .8; 1" calcMode="spline" 
     keySplines=".5 0 .5 1; 0 0 1 1" />

The keyTimes still cause the "x" attribute to have a value of "0" at the start of the animation, "50" after 8 seconds and "100" at the end of the animation. However, the keySplines values define a curve for pacing the interpolation between values. In the example above, the spline causes an ease-in and ease-out effect between time 0 and 8 seconds (i.e. between keyTimes 0 and .8, and values "0" and "50"), but a strict linear interpolation between 8 seconds and the end (i.e. between keyTimes .8 and 1, and values  "50" and "100"). Figure 7 shows the curves that these keySplines values define.

Figure 7 - Illustration of keySplines effect

Example keySplines01 -                         keySplines of 0 0 1 1 (the default)
keySplines="0 0 1 1"
(the default)
Example keySplines02 -                         keySplines of .5 0 .5 1
keySplines=".5 0 .5 1"
 
Example keySplines03 - keySplines of 0 .75 .25                         1
keySplines="0 .75 .25 1"
Example keySplines04 - keySplines of 1 0 .25                         .25
keySplines="1 0 .25 .25"

Each diagram in Figure 7 illustrates the effect of keySplines settings for a single interval (i.e. between the associated pairs of values in the keyTimes and values lists.). The horizontal axis can be thought of as the input value for the unit progress of interpolation within the interval - i.e. the pace with which interpolation proceeds along the given interval. The vertical axis is the resulting value for the unit progress, yielded by the keySplines function. Another way of describing this is that the horizontal axis is the input unit time for the interval, and the vertical axis is the output unit time. See also the section Timing and real-world clock times.

To illustrate the calculations, consider the simple example:

<animate dur="4s" values="10; 20" keyTimes="0; 1"
     calcMode="spline" keySplines={as in table} />

Using the keySplines values for each of the four cases above, the approximate interpolated values as the animation proceeds are:

keySplines values  Initial value After 1s After 2s After 3s Final value
0 0 1 1 10.0 12.5 15.0 17.5 20.0
.5 0 .5 1 10.0 11.0 15.0 19.0 20.0
0 .75 .25 1 10.0 18.0 19.3 19.8 20.0
1 0 .25 .25 10.0 10.1 10.6 16.9 20.0

For a formal definition of Bezier spline calculation, see [COMP-GRAPHICS], pages 488-491.

The keyTimes and keySplines attributes can also be used with the from/to/by shorthand forms for specifying values, as in the following example:

<animate attributeName="foo" from="10" to="20" 
     dur="10s" keyTimes="0.0; 0.7"
     calcMode="spline" keySplines=".5 0 .5 1" />

The value will change from 10 to 20, using an "ease-in/ease-out" curve specified by the keySplines values. The keyTimes values cause the value of 20 to be reached at 7 seconds, and to hold there for the remainder of the 10 second simple duration.

The following example describes a somewhat unusual usage, a from-to animation with discrete animation. The stroke-linecap attribute of SVG elements takes a string, and so implies a calcMode of discrete. The animation will set the stroke-linecap attribute to round for 5 seconds (half the simple duration) and then set the stroke-linecap to square for 5 seconds.

<rect stroke-linecap="butt"...>
   <animate attributeName="stroke-linecap" 
      from="round" to="square" dur="10s"/>
</rect>

3.9.2 SMIL 3.0 SplineAnimation Module Elements

The SplineAnimation module extends the BasicAnimation elements animate, animateMotion and animateColor, adding the attributes keyTimes and keySplines, and the value spline for the caclMode attribute.

3.9.3 The spline animate element

The SplineAnimation module extends the animate element defined by the BasicAnimation module, adding the following attributes and values.

Element attributes
 
all attributes and associated elements of the animate element in BasicAnimation.
See The animate element.
keyTimes,
keySplines, and
calcMode
 
 
Extend the specification animation function and effect. See The animate element and Spline animation function calculation mode.

Examples are provided above, as are normative definitions of the semantics of all attributes supported by animate.

3.9.4 The spline animateMotion element

The SplineAnimation module extends the animateMotion element defined by the BasicAnimation module, adding the following attributes and values.

Element attributes
 
all attributes and associated elements of the animateMotion element in BasicAnimation.
See The animateMotion element.
keyTimes,
keySplines, and
calcMode
 
 
Extend the specification animation function and effect. See The animateMotion element and Spline animation function calculation mode.
path
Specifies the curve that describes the attribute value as a function of time. The supported syntax is a subset of the SVG path syntax. Support includes commands to describes lines ("MmLlHhVvZz") and Bezier curves ("Cc"). For details refer to the path specification in SVG [SVG].
Note that SVG provides two forms of path commands, "absolute" and "relative". These terms may appear to be related to the definition of additive animation and/or to the from attribute, but they are orthogonal. The terms "absolute" and "relative" apply only to the definition of the path itself, and not to the operation of the animation. The "relative" commands define a path point relative to the previously specified point. The terms "absolute" and "relative" are unrelated to the definitions of both "additive" animation and any specification of origin.
  • For the "absolute" commands ("MLHVZC"), the host language must specify the coordinate system of the path values.
  • If the "relative" commands ("mlhvzc") are used, they simply define the point as an offset from the previous point on the path. This does not affect the definition of "additive" or origin for the animateMotion element.

A path data segment must begin with either one of the "moveto" commands.

Move To commands - "M <x> <y>" or "m <dx> <dy>"
Start a new sub-path at the given (x,y) coordinate. If a moveto is followed by multiple pairs of coordinates, the subsequent pairs are treated as implicit lineto commands.
Line To commands - "L <x> <y>" or "l <dx> <dy>"
Draw a line from the current point to the given (x,y) coordinate which becomes the new current point. A number of coordinate pairs may be specified to draw a polyline.
Horizontal Line To commands - "H <x>" or "h <dx>"
Draws a horizontal line from the current point (cpx, cpy) to (x, cpy). Multiple x values can be provided.
Vertical Line To commands - "V <y>" or "v <dy>"
Draws a vertical line from the current point (cpx, cpy) to (cpx, y). Multiple y values can be provided.
Closepath commands - "Z" or "z"
The "closepath" causes an automatic straight line to be drawn from the current point to the initial point of the current subpath.
Cubic Bezier Curve To commands - 
  "C <x1> <y1> <x2> <y2> <x> <y>" or 
  "c <dx1> <dy1> <dx2> <dy2> <dx> <dy>"
Draws a cubic Bezier curve from the current point to (x,y) using (x1,y1) as the control point at the beginning of the curve and (x2,y2) as the control point at the end of the curve. Multiple sets of coordinates may be specified to draw a polybezier.

For all calcMode settings, the definition of the simple animation function, f(t), uses the number of values in the values attribute to determine how the simple duration is d is divided into segments. When a path attribute is used, the number of values is defined to be the number of points defined by the path, unless there are "move to" commands within the path.  A "move to" command does not define an additional "segment" for the purposes of timing or interpolation. A "move to" command does not count as an additional point when dividing up the duration. When a path is combined with a paced calcMode setting, all "move to" commands are considered to have 0 duration (i.e. they always happen instantaneously), and should not be considered in computing the pacing.

If the path attribute is is specified, any from/to/by or values attribute values will be ignored.

Examples are provided above, as are normative definitions of the semantics of all attributes supported by animate.

For complete velocity control, calcMode can be set to spline and the author can specify a velocity control spline with keyTimes and keySplines.

3.9.5 The spline animateColor element

The SplineAnimation module extends the animateColor element defined by the BasicAnimation module, adding the following attributes and values.

Element attributes
 
all attributes and associated elements of the animateColor element in BasicAnimation.
See The animateColor element.
keyTimes,
keySplines, and
calcMode
 
 
Extend the specification animation function and effect. See The animateColor element and Spline animation function calculation mode.

3.10 SMIL 3.0 SplineAnimation Module Details

3.10.1 SplineAnimation integration requirements

To specify the integration of the SMIL 3.0 SplineAnimation module into a host language, the language designer must integrate SMIL 3.0 BasicAnimation into the language, satisfying all the requirements listed in BasicAnimation integration requirements.

In addition to integrating BasicAnimation, the requirements listed in Common animation integration requirements must be satisfied for the SplineAnimation module.

3.10.2 Document type definition (DTD) for the SplineAnimation module

See the full DTD for the SMIL Animation Modules.

3.11 Common Animation Integration Requirements

This section presents host-language-integration issues which are the same for the BasicAnimation and SplineAnimation modules.

3.11.1 Integration requirements

The host language profile must integrate the SMIL 3.0 BasicInlineTiming module into the host language, satisfying all requirements of that module. In addition, all modules of the SMIL 3.0 Timing and Synchronization modules and of the SMIL 3.0 Time Manipulation modules which are integrated into the host language must be available on BasicAnimation elements.

In particular, the fill attribute is supported on animation elements only if the host language integrates the SMIL 3.0 BasicTimeContainers module in addition to the BasicInlineTiming module.

normative section

If the Eventbase-element term is missing, the event-base element is defined to be the target element of the animation.

The host langauge profile may add additional attributes to Animation elements. Attributes added to any Animation element must be added to all Animation elements. In particular, this module does not define an XML ID attribute. It is expected that the host language profile will add an XML ID attribute to the Animation elements.

Extending Animation

Language designers integrating SMIL Animation are encouraged to define new animation elements where such additions will be of convenience to authors. The new elements must be based on SMIL Animation and SMIL Timing and Synchronization, and must stay within the framework provided by SMIL Timing and Synchronization and SMIL Animation.

Language designers are also encouraged to define support for additive and cumulative animation for non-numeric data types where addition can sensibly be defined.

Constraints on manipulating animation elements

Language designers integrating SMIL Animation are encouraged to disallow manipulation of attributes of the animation elements after the document has begun. This includes both the attributes specifying targets and values, as well as the timing attributes. In particular, the id attribute (of type ID) on all animation elements must not be mutable (i.e. should be read-only). Requiring animation runtimes to track changes to id values introduces considerable complexity, for what is at best a questionable feature.

It is recommended that language specifications disallow manipulation of animation element attributes through DOM interfaces after the document has begun.  It is also recommended that language specifications disallow the use of animation elements to target other animation elements.

Note in particular that if the attributeName attribute can be changed (either by animation or script), problems may arise if the target attribute has a namespace qualified name. Current DOM specifications do not include a mechanism to handle this binding.

Dynamically changing the attribute values of animation elements introduces semantic complications to the model that are not yet sufficiently resolved. This constraint may be lifted in a future version of SMIL Animation.

Handling syntax errors

The specific error handling mechanisms for each attribute are described with the individual syntax descriptions.  Some of these specifications describe the behavior of an animation with syntax errors as "having no effect".  This means that the animation will continue to behave normally with respect to timing, but will not manipulate any presentation value, and so will have no visible impact upon the presentation. 

In particular, this means that if other animation elements are defined to begin or end relative to an animation that "has no effect", the other animation elements will begin and end as though there were no syntax errors. The presentation runtime may indicate an error, but need not halt presentation or animation of the document. 

Some host languages and/or runtimes may choose to impose stricter error handling (see also Error handling semantics for a discussion of host language issues with error handling). Authoring environments may also choose to be more intrusive when errors are detected.

Error handling semantics

The host language designer may impose stricter constraints upon the error handling semantics. That is, in the case of syntax errors, the host language may specify additional or stricter mechanisms to be used to indicate an error. An example would be to stop all processing of the document, or to halt all animation.

Host language designers may not relax the error handling specifications, or the error handling response (as described in Handling syntax errors). For example, host language designers may not define error recovery semantics for missing or erroneous values in the values or keyTimes attribute values.

4. The SMIL 3.0 Content Control Modules

Editors for SMIL 3.0
Dick Bulterman, CWI.
Thierry Michel, W3C.
Editors for Earlier Versions of SMIL
Dick Bulterman, Oratrix
Jeffrey Ayars, RealNetworks.

4.1 Overview and Summary of Changes for SMIL 3.0

This section is informative.

This version of the SMIL 3.0 content control modules leaves the baseline SMIL 2.1 Content Control modules [[SMIL2.1-content-control]] specification unchanged. In a future release of this section, we expect that some or all of the content control mechanisms specified will be modified to better align with the expression and test logic being developed within the SMIL 3.0 State modules. These changes will likely provide a backwards-compatible method of specifying original SMIL system and custom tests, but will also provide extensions that allow for a richer test expression syntax.

4.2 Introduction

This section is informative.

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 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 Module Overview

This section is normative.

SMIL 3.0 Content Control functionality is partitioned across the following 4 modules:

4.4 The SMIL 3.0 BasicContentControl Module

This section is normative.

4.4.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 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 3.0's camelCase conventions. The SMIL 1.0 hyphenated names are deprecated in this release.

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

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

The switch element

This section is informative.

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

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

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

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

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

4.4.2 Elements and Attributes

This section is normative.

SMIL 3.0 BasicContentControl defines the switch element 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 does not have attributes beyond 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.

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

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)+

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.

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.

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.
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)+
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: a screen size
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 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.

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.

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.3 Integration Requirements for the BasicContentControl Module

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

4.4.4 Document Type Definition (DTD) for the BasicContentControl Module

See the full DTD for the SMIL Content Control modules.

4.5 The SMIL 3.0 CustomTestAttributes Module

This section is normative.

4.5.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 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:

  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 can be applied within a SMIL 3.0 Language profile document:

<smil>
  <head>
    <layout>
       <!-- define projection regions -->
    </layout>
    <customAttributes>
      <customTest id="west-coast" title="West Coast Edition" 
        defaultState="false" override="visible"  
        uid="http://defs.example.org/user-settings/west-coast" />
      <customTest id="east-coast" title="East Coast Edition" 
        defaultState="false" override="visible" 
        uid="http://defs.example.org/user-settings/east-coast" />
      <customTest id="far-north"  title="Northern Edition"
        defaultState="false" override="visible"
        uid="http://defs.example.org/user-settings/far-north" />
      <customTest 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 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:

  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. Note also that not all implementations need support uid or UI setting of attributes.

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

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

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 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'):

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

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

4.5.4 Document Type Definition (DTD) for the CustomTestAttribute Module

See the full DTD for the SMIL Content Control modules.

4.6 The SMIL 3.0 PrefetchControl Module

This section is normative.

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

This section is informative.

Examples

  1. Prefetch an image so it can be displayed immediately after a video ends:
     <smil xmlns="http://www.w3.org/2006/SMIL30/WD/Language"> 
       <body> 
         <seq>
           <par>
             <prefetch id="endimage"
                src="http://www.example.org/logo.gif"/>
             <text id="interlude"
                src="http://www.example.org/pleasewait.html" fill="freeze"/>
           </par>
           <video 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 id="upimage" src="http://www.example.org/up.gif"/>
         <prefetch 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>
        

4.6.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-val         ::= ( 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).

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

bitrate-value ::= Digit+; any positive number

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

4.6.4 Document Type Definition (DTD) for the PrefetchControl Module

See the full DTD for the SMIL Content Control modules.

4.7 The SMIL 3.0 SkipContentControl Module

This section is normative.

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

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

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

5. The SMIL 3.0 Layout Modules

Editor for SMIL 3.0
Dick Bulterman, CWI
Editors for Earlier Versions of SMIL
Aaron Cohen, Intel
Dick Bulterman, Oratrix/CWI
Erik Hodge, RealNetworks.

5.1 Summary of Changes for SMIL 3.0

This section is informative.

SMIL 3.0 Layout defines extends the BasicLayout module with the backgroundOpacity attribute, which specifies the background opacity of a region. This attribute applies to both the background color of a SMIL layout region and to the opacity of background images specified for a region (if supported by the profile). This attribute complements new features defined in the Media Objects module to control media opacity for media types that support opacity control.

A new MotionLayout module is also defined. This module defines four attributes, crawlRate, crawlWrap, scrollRate and scrollWrap, which provide functions to facilities the movement of content horizontally and vertically within a region.

This version of the SMIL 3.0 Layout modules also provides minor editorial changes to the text of all of the module descriptions and it provides an expanded set of informative examples of layout element and attribute use.

5.2 Introduction

This section is normative.

This section defines the SMIL Layout Modules, which contain elements and attributes that allow positioning of media elements on visual and audio rendering surfaces and to control of audio volume. Since these elements and attributes are defined in modules, designers of other markup languages can choose the appropriate level of functionality to be included in their languages. Language designers incorporating other SMIL modules may include all, some or none of the modules described in this section.

5.2.1 Module Overview

SMIL 3.0 Layout functionality is partitioned across the following eight modules:

BasicLayout
The BasicLayout module defines the core SMIL layout elements and their attributes. Using these attributes, basic positioning can be achieved for simple presentations.
AudioLayout
The AudioLayout module extends the BasicLayout module with a single attribute to control audio output sound levels.
MultiWindowLayout
The MultiWindowLayout module extends the BasicLayout module by defining an alternative to the root-layout element for defining the outer containing rendering space for a presentation. This module also defines functionality for supporting multiple top-level windows simultaneously.
SubRegionLayout
The SubRegionLayout module extends the BasicLayout module by defining a facility for creating logically nested regions. These regions can be created statically within the layout section or dynamically on a media object reference.
AlignmentLayout
The AlignmentLayout module extends the BasicLayout module by defining attributes to position content within a region based on a set of registration points and alignment algorithms. Several convenience attribute values are also provided to simply common authoring cases.
BackgroundTilingLayout
The BackgroundTilingLayout module extends the BasicLayout module by defining a facility to fill a region background with a tiled image instead of simply a background color.
OverrideLayout
The OverrideLayout module extends the BasicLayout module by allowing per-media-object overrides of various layout attribute values.
MotionLayout
The MotionLayout module extends the BasicLayout module by allowing per-media-object specification of a crawl rate and a scroll rate; these allow horizontal and vertical movement of content within a region.

This section is informative.

Note that the SMIL 2.0 HierarchicalLayout module was deprecated in SMIL 2.1; all of this module's functionality was partitioned across other layout modules and thus it is not part of SMIL 3.0 Layout.

5.2.2 Support for Multiple Layout Models

The SMIL layout architecture allows support for multiple layout models within a presentation. Media layout may be described using the SMIL layout syntax described in this chapter or by using another layout mechanism, such as CSS2 syntax [CSS2]. Other layout types are possible as well.

Support for multiple layout models is implementation profile dependent. A given profile may support multiple layout models simultaneously (with selection performed using the SMIL switch element), or it may dictate that only a single layout model is supported (such as the use of CSS2 layout within the XHTML+SMIL candidate profile[XHTMLplusSMIL].

The remainder of this chapter will focus solely on the use of SMIL 3.0 layout semantics.

5.3 The SMIL BasicLayout Module

This section is normative.

5.3.1 Overview

SMIL BasicLayout module includes a layout model for organizing media elements into regions on the visual rendering surface. The layout element is used in the document head to declare a set of regions on which media elements are rendered. Media elements declare which region they are to be rendered into with the region attribute.

Each region has a set of CSS2 compatible properties such as top, left, height, width, and backgroundColor. These properties can be declared using a syntax defined by the type attribute of the layout element. In this way, media layout can be described using the either SMIL basic layout syntax or CSS2 syntax (note that these are not functionally identical). Other layout types are possible as well.

This section is informative.

An example declaration to define a region with the id "r" at location 15,20 that is 100 pixels wide by 50 pixels tall using the SMIL BasicLayout module is:

    <layout>
      <region id="r" top="15px" left="20px" width="100px" height="50px"/>
    </layout>

To display a media element in the region declared above, specify the region's id as the region attribute of the media element:

    <ref region="r" src="http://..." />

5.3.2 Elements and Attributes

This section defines the elements and attributes that make up the functionality in the SMIL BasicLayout module.

The layout element

The layout element defines a collection of rendering regions that determine how the elements in the document's body are positioned on an abstract rendering surface (either visual or acoustic).

The layout element must appear before any of the declared layout is used in the document. If present, the layout element must appear in the head section of the document. SMIL-defined default layout values can be assigned to all renderable elements by selecting the empty layout element <layout></layout>. If a document contains no layout element, no SMIL-defined default values are assigned and the positioning of the body elements is totally implementation-dependent.

Element Attributes
type
This attribute specifies which layout language is used in the layout element. If the user agent does not understand this language, it must skip the element and all of its content up until the next </layout> tag. The default value of the type attribute is "text/smil-basic-layout". This identifier value supports SMIL 1.0, SMIL 2.0 and SMIL 2.1 BasicLayout module layout semantics.
Element content

If the type attribute of the layout element has the value "text/smil-basic-layout", it may contain the following elements:

region
root-layout

Profiles incorporating the BasicLayout module may define additional elements that are allowed as children of the layout element. If the type attribute of the layout element has a value other than "text/smil-basic-layout", the element contains character data.

The region element

The region element controls the position, size and scaling of media object elements that are placed within it rendering space.

The position of a region, as specified by its top, bottom, left, and right attributes, is always relative to the parent geometry, which is defined by the parent element. For the SMIL BasicLayout module, all region elements must have as their immediate parent a layout element, and the region position is defined relative to the root window declared in the sibling root-layout element. The root-layout element is considered to be the logical parent of all region elements in SMIL BasicLayout. The intrinsic size of a region is equal to the size of the logical parent's geometry.

When region sizes, as specified by width and height attributes are declared relative with the "%" notation, the size of a region is relative to the size of the parent geometry. Sizes declared as absolute pixel values maintain those absolute values.

Conflicts between the region size and position attributes width, height, bottom, left, right, and top are resolved according to the rules for placeholder elements as detailed below. The default values of region position and size attributes is specified as auto. This attribute value has the same meaning here that it does in [CSS2], when there is no distinction drawn between replaced and non-replaced element.

A placeholder element is one which has no intrinsic width or height, but does have a bounding-box which has a width and height. SMIL BasicLayout regions are placeholder elements. Placeholder elements are clipped to the bounding box.

The governing equation for the horizontal dimension is:

bbw (bounding-box-width) = left + width + right

Given that each of these three parameters can have either a value of "auto" or a defined value not "auto", then there are 8 possibilities:

Attribute values

Result before clipping to the bounding box

left width right left width right
auto auto auto 0 bbw 0
auto auto defined 0 bbw - right right
auto defined auto 0 width bbw - width
auto defined defined bbw - right - width width right
defined auto auto left bbw - left 0
defined auto defined left bbw - right - left right
defined defined auto left width bbw - left - width
defined defined defined left width bbw - left - width

The vertical attributesheight, bottom, and top are resolved similarly. The governing equation for the vertical dimension is:

bbh (bounding-box-height) = top + height + bottom

Given that each of these three parameters can have either a value of "auto" or a defined value not "auto", then there are 8 possibilities:

Attribute values

Result before clipping to the bounding box

top height bottom top height bottom
auto auto auto 0 bbh 0
auto auto defined 0 bbh - bottom bottom
auto defined auto 0 height bbh - height
auto defined defined bbh - bottom - height height bottom
defined auto auto top bbh - top 0
defined auto defined top bbh - bottom - top bottom
defined defined auto top height bbh - top - height
defined defined defined top height bbh - top - height
Element attributes

The region element can have the following visual attributes:

backgroundColor
The use and definition of this attribute are identical to the "background-color" property in the CSS2 specification. Unlike SMIL 1.0, this module requires support for CSS2 system colors.
This attribute specifies the background color used to fill the area of a region displaying media that is not filled by the media. The display of the background color when the region is not in use by a media element is controlled by the showBackground attribute.
The backgroundColor attribute may take on the CSS value inherit. This means that the background color will be that of the parent element. If the parent element does not have an applicable background color property, the default value depends on the language profile: if the background-color attribute is supported by the language profile, the default value of backgroundColor is inherited from background-color. Otherwise, the default value is transparent.
background-color
Deprecated. Equivalent to backgroundColor, which replaces this attribute. The language profile must define whether or not the background-color attribute is supported. The default value of the background-color attribute is transparent.
backgroundOpacity
This attribute defines the opacity of the background of the region. It accepts a percentage value in the range 0-100%, with 100% meaning fully opaque. If implementation cannot support manipulation of the background opacity value, this attribute is ignored. The default value of this attribute is 100%.
bottom
The use and definition of this attribute are identical to the "bottom" property in the CSS2 specification. Attribute values can be non-negative "percentage" values, and a variation of the "length" values defined in CSS2. For "length" values, SMIL BasicLayout only supports pixel units as defined in CSS2. It allows the author to leave out the "px" unit qualifier in pixel values (the "px" qualifier is required in CSS2). Conflicts between the region size attributes bottom, left, right, top, width, and height are resolved according to the rules for absolutely positioned, replaced elements in [CSS2]. The default value of bottom attribute is auto.
fit
This attribute specifies the behavior if the intrinsic height and width of a visual media object differ from the values specified by the height and width attributes in the region element. This attribute does not have a one-to-one mapping onto a CSS2 property, but can be simulated in CSS2.
This attribute can have the following values:
fill
Scale the object's height and width independently so that the content just touches all edges of the box.
hidden
Has the following effect:
  • If the intrinsic height (width) of the media object element is smaller than the height (width) defined in the region element, render the object starting from the top (left) edge and fill up the remaining height (width) with the background color.
  • If the intrinsic height (width) of the media object element is greater than the height (width) defined in the region element, render the object starting from the top (left) edge until the height (width) defined in the region element is reached, and clip the parts of the object below (right of) the height (width).
meet
Scale the visual media object while preserving its aspect ratio until its height or width is equal to the value specified by the height or width attributes, while none of the content is clipped. The object's left top corner is positioned at the top-left coordinates of the box, and empty space at the right or bottom is filled up with the background color.
meetBest
The semantic of this value is identical to meet except that the image is not scaled to greater than 100% in either dimension. This limits degradation of upwardly-scaled media content.
scroll
A scrolling mechanism should be invoked when the element's rendered contents exceed its bounds.
slice
Scale the visual media object while preserving its aspect ratio so that its height or width are equal to the value specified by the height and width attributes while some of the content may get clipped. Depending on the exact situation, either a horizontal or a vertical slice of the visual media object is displayed. Overflow width is clipped from the right of the media object. Overflow height is clipped from the bottom of the media object.

The default value of fit is hidden.

Note that the fit attribute applies to visual media once it has an intrinsic two-dimensional size, such as images and video. It does not apply to visual media that is rendered and adapted to varying circumstances, such as the visual display of HTML, until its two-dimensional spatial dimensions have been determined, such as after an HTML page has been laid out to specific size.

height
The use and definition of this attribute are identical to the "height" property in the CSS2 specification. Attribute values follow the same restrictions and rules as the values of the bottom attribute. The intrinsic height of a region is the same as that of the parent geometry. The default value of the height attribute is auto.
left
The use and definition of this attribute are identical to the "left" property in the CSS2 specification. Attribute values follow the same restrictions and rules as the values of the "bottom" attribute. The default value of the left attribute is auto.
regionName
This attribute assigns a name to this region element that can be referred to by the region attribute of media object elements. The regionName attribute is not a unique identifier; multiple region elements can share the same regionName attribute value. This attribute does not have a default value.
right
The use and definition of this attribute are identical to the "right" property in the CSS2 specification. Attribute values follow the same restrictions and rules as the values of the "bottom" attribute. The default value of right attribute is auto.
showBackground
This attribute controls whether the backgroundColor of a region is shown when no media is being rendered to the region:
  • If the value of showBackground is always, then the background color will be shown in the region when no media object is rendering into that region. If the region is part of a hierarchical sub-region layout, then any ancestor regions must also either be active or have a showBackground value of always for the background color to be shown.
  • If the value of showBackground is whenActive, then the background color will be not be shown in the region when no media object is rendering into that region. If the region is part of a hierarchical sub-region layout, then the background color will also be shown when any descendent regions are active.
The default value of showBackground is always.
top
The use and definition of this attribute are identical to the "top" property in the CSS2 specification. Attribute values follow the same restrictions and rules as the values of the bottom attribute. The default value of the top attribute is auto.
width
The use and definition of this attribute are identical to the "width" property in the CSS2 specification. Attribute values follow the same restrictions and rules as the values of the bottom attribute. The intrinsic width of a region is the same as that of the parent geometry. The default value of width attribute is auto.
z-index
The use and definition of this attribute are identical to the "z-index" property in the CSS2 specification, with the following exception:

If two boxes generated by elements A and B have the same stack level, then:
  • If the display of an element A starts later than the display of an element B, the box of A is stacked on top of the box of B (temporal order).
  • Else, if the display of the elements starts at the same time, and an element A occurs later in the SMIL document text than an element B, the box of A is stacked on top of the box of B (document tree order as defined in CSS2).

A profile integrating the SMIL BasicLayout module must provide a means of declaring an XML identifier on region elements.

Element examples

This section is informative.

In the following example fragment, the position of a text element is set to a 5 pixel distance from the top border of the rendering window:

<smil xmlns="...">
<head>
...
<layout>
...
<region id="a" top="5" />
...
</layout>
</head>
<body>
...
<text region="a" src="text.html" dur="10s" />
...
</body>
</smil>

The root-layout element

The root-layout element determines the value of the layout properties of the root element, which in turn determines the size of the window in which the SMIL presentation is rendered.

If more than one root-layout element is parsed within a single layout element, this is an error, and the document should not be displayed. This does not include root-layout elements skipped by the user agent (e.g. because the enclosing layout element was skipped due to an unrecognized type or because a test attribute evaluated to false).

The semantics of the root-layout element are as in SMIL 1.0: the attributes of the root-layout element determine the size of the top level presentation window, and the declared sibling regions are arranged within this top level window. If either the height or width of the root-layout element is not specified, the value of the attribute is implementation-dependent.

Element attributes
backgroundColor
Defined in backgroundColor under the region element. Note that the effective default behavior is transparent, which implies that, by default, the implementation-dependent window background will be shown.
background-color
Deprecated. Defined in background-color under the region element.
backgroundOpacity
Defined in backgroundOpacity under the region element.
height
Sets the height of the root element. Only length values are allowed. For "length" values, SMIL BasicLayout only supports pixel units as defined in CSS2. It allows the author to leave out the "px" unit qualifier in pixel values (the "px" qualifier is required in CSS2).
width
Sets the width of the root element. Only length values are allowed. For "length" values, SMIL BasicLayout only supports pixel units as defined in CSS2. It allows the author to leave out the "px" unit qualifier in pixel values (the "px" qualifier is required in CSS2).
Element content

The root-layout element is an empty element. This element supports the SMIL 1.0 syntax where the root-layout element is an empty sibling of the top level region elements.

Element examples

This section is informative.

The following example extends the fragment above with a specification of the root-layout element:

<smil xmlns="...">
<head>
<layout>
<root-layout width="320" height="480" />
<region id="a" top="5" />
</layout>
</head>
<body>
<text region="a" src="text.html" dur="10s" />
</body>
</smil>

Note that the root-layout element is placed at a peer-level within the layout section. SMIL Layout also supports a nested containment model using the topLayout element defined in the MultiWindowLayout module.

The region attribute

The region attribute is added to the ref element (and its synonyms). The target of this attribute will be one or more regions with a regionName declared that matches the value of this attribute, or a single region element with a region attribute that matches this value. For processing rules, see the section Implementation details.

5.3.3 SMIL BasicLayout Implementation and Integration

Implementation Details

SMIL BasicLayout module is consistent with the visual rendering model defined in CSS2, it reuses the formatting properties defined by the CSS2 specification, and newly introduces the fit attribute [CSS2]. The reader is expected to be familiar with the concepts and terms defined in CSS2.

SMIL layout regions influence the propagation of user interface events (such as a mouse click, or hyperlink activation) to underlying visible elements. When the location of an event corresponds to the background of a region rather than the media that is displayed in that region, a region background color of transparent allows user interface events to pass through to elements lower in the display stacking order. Conversely, regions with non-transparent background colors will capture user interface events, not allowing the event to pass through to elements lower in the display stacking order. This behavior is separate from that of a language profile's ability to make use of user interface events captured by region elements.

An element that does not refer to a valid region element will display in the default region. If not otherwise specified by the profile, the default region is defined as filling and aligned to the upper-left corner of the presentation window. This default region takes on default values for all other region attributes.

The region attribute is applied to an element in order to specify which rendering region is assigned to the element. The attribute refers to the abstract rendering region (either visual or acoustic) defined within the layout section of the document. The referenced abstract rendering region is determined by applying the following rules, in order:

  1. Find all elements in the layout section with regionName attributes that are assigned the same value as that of the region attribute.
  2. Remove the elements from this collection that are removed from the rendered presentation due to the processing of switch elements and test attributes.
  3. If any elements remain, the media should be rendered in all of the referred to regions. If the application cannot render the media simultaneously in multiple regions, then the media should be rendered using the lexically first remaining element.
  4. If no elements have a regionName attribute that is assigned the same value as that of the region attribute, then select the element in the layout section whose unique identifier is the value of the region attribute.

If this process selects no rendering surface defined in the layout section, the values of the formatting properties of this element are defined by the default layout values, which is described in the section on integration requirements for this module.

Integration Requirements

A profile integrating the SMIL BasicLayout module must define the content models for the layout element if any elements beyond those specified here are to be allowed as children.

A profile integrating the SMIL BasicLayout module must provide a means of declaring an XML identifier on region elements if the profile intends on referring to region elements by XML identifier. This value is used as the argument value to the region attribute. This is not required if the profile will only use the regionName method of referring to a region element.

A profile integrating the SMIL BasicLayout module must specify which elements have a region attribute and any inheritance of the attribute.

If not otherwise defined by the profile, the default values of the layout attributes listed in the SMIL layout modules will apply to presented elements not otherwise specifying layout semantics.

5.3.4 Document Type Definition (DTD) for the BasicLayout Module

See the full DTD for the SMIL Layout modules.

5.4 The SMIL AudioLayout Module

This section is normative.

5.4.1 Overview

In SMIL AudioLayout, one attribute is supported that allows the sound intensity of an audio object to be specified via the soundLevel attribute. When used in conjunction with SMIL 3.0 Animation (and if supported by the profile), the value of the attribute may be varied over time.

This section is informative.

The following region defines an audio sound level that is set to 50% of its normal recorded value:

  <layout>
    ...
    <region id="a" soundLevel="50%"/>
    ...
  </layout>

5.4.2 Audio Volume Control

SMIL AudioLayout module supports control of aural media volumes via a new property on the region element, soundLevel. Multimedia assigned to a region with an explicit soundLevel attribute will have its audio rendered at the given relative sound intensity.

5.4.3 Elements and Attributes

This section defines the soundLevel attribute that makes up the SMIL AudioLayout module.

The region element

The region element defined in the BasicLayout module is extended with the addition of the soundLevel attribute.

Element attributes

The region element can have the following aural attribute:

soundLevel
Specifies the relative volume of the audio portion of a media element assigned to play within the given region. This associates the region element with a sound reproduction unit. Cascaded regions will accumulate their respective sound level settings, as will be explained below. region's that are used for multiple sources apply their sound level setting to all of them. A sound source may be reproduced by different units, e.g., through application of the regionName attribute. In such a "multiple window" case a separate soundLevel may be applied to each instance of the sound source, one per region. Assigned level changes accumulate across nested regions by multiplying percentage values.

Valid values are non-negative CSS2 percentage values. Percentage values are interpreted relative to the recorded volume of the media. The percentages are interpreted as a ratio of output to input signal level, and is defined in terms of dB:

dB change in signal level = 20 log10(percentage-value / 100)

A setting of '0%' plays the media silently. A value of '100%' will play the media at its recorded volume (0 dB). Similarly, a value of '200%' will play the media nearly twice as loud (6 dB) as its recorded volume (subject to hardware limitations). The default value is '100%'. The absolute sound level of media perceived is further subject to system volume settings, which cannot be controlled with this attribute.

5.4.4 Integration Requirements for the AudioLayout Module

The functionality in this module builds on top of the functionality in the BasicLayout module, which is a required prerequisite for inclusion of the AudioLayout module.

5.4.5 Document Type Definition (DTD) for the AudioLayout Module

See the full DTD for the SMIL Layout modules.

5.5 The SMIL MultiWindowLayout Module

This section is normative.

5.5.1 Overview

This section defines the functionality in the SMIL MultiWindowLayout module. This level contains elements and attributes providing for creation and control of multiple top level windows on the rendering device.

In the architecture of the SMIL BasicLayout module, each presentation is rendered into a single root window of a specific size/shape. The root window contains all of the regions used to manage the rendering of specific media objects and is defined by a peer-level root-layout element.

The SMIL Layout specification extends the root container level with the notion of a top-level rendering window, called a topLayout window. A SMIL layout section may support one or more topLayout windows. The assignment of the regions to individual top level windows allows independent placement and resizing of each top-level window, if supported by the including profile and implementation. The initial placement of the top level windows on the display device and any available means of relocating the top level windows is implementation-dependent.

The top-level windows function as rendering containers only, that is, they do not carry temporal significance. In other words, each window does not define a separate timeline or any other time-container properties. There is still a single master timeline for the SMIL presentation, no matter how many top-level windows have been created. This is important to allow synchronization between media displayed in separate top-level windows.

The display of top level windows can be controlled automatically by the player, or manually by the user of the application. If a window is closed (by the user) while any of the elements displayed in that window are active, there is no effect on the timeline (if any) of those elements. However, a player may choose not to decode content as a performance improvement. The means provided to a user to close top level windows is implementation-dependent.

For SMIL 1.0 compatibility, the root-layout element will continue to support SMIL 1.0 layout semantics. The new topLayout element will support the extension semantics and the improved, nested syntax.

Note also that any one region may belong to at most one top-level (or root-level) window. Regions not declared as children of a topLayout element belong to the root-layout window. If no root-layout element has been declared, the region is assigned to an additional window according to the semantics in the BasicLayout module.

5.5.2 Elements and Attributes

This section defines the elements and attributes that make up the SMIL MultiWindowLayout module.

The topLayout element

The topLayout element determines the size of the a window in which the SMIL presentation is rendered, as well as serving as a top level window in which to place child region elements.

Multiple topLayout elements may appear within a single layout element, each declaring an independent top-level window.

Each instance of a topLayout element determines the size of a separate top-level presentation window, and the descendant regions are arranged within this top-level window and relative to the coordinate system of this window.

This module also provides control over when topLayout windows open and close in a presentation. Note that the precise mapping of topLayout windows on to the host environment is implementation-dependent. It is expected that implementations will "pop up" independent desktop windows if they can, but other means of supporting multiple topLayouts, such as by using frames, are allowed. When automatically opening and closing windows, applications should try to comply with the WAI User Agent Guidelines [UAAG] and allow the user to choose whether to be warned that windows are being opened and closed, and give a method for disabling automatic opening and closing of windows.

Element attributes
backgroundColor
Defined in backgroundColor under the region element. Note that the effective default behavior is transparent, which implies that, by default, the implementation-dependent window background will be shown.
backgroundOpacity
Defined in backgroundOpacity under the region element.
close
Specifies when the top level window should be closed. If the value of close is onRequest, then the top level window should not be closed automatically by the player and will only close if the user explicitly closes it via the user interface. If the value of close is whenNotActive, then the top level window should close automatically when no media is being displayed in any one of the window's regions. For timed media using the SMIL timing and synchronization modules, this means when there is no media within its active duration or freeze period using any region of the topLayout. The default value of close is onRequest.
height
Sets the height of the top-level window. Only length values are allowed. For "length" values, SMIL MultiWindowLayout only supports pixel units as defined in CSS2. It allows the author to leave out the "px" unit qualifier in pixel values (the "px" qualifier is required in CSS2).
open
Specifies when the top level window should be opened. If the value of open is onStart, then the top level window should be opened when the presentation begins, and if closed, should not be reopened automatically during the presentation. If the value of open is whenActive, then, if not already open, the top level window should be opened when media is displayed in one of the window's regions. For timed media using the SMIL timing and synchronization modules, this means when there is any media within its active duration or freeze period using any region of the topLayout. The default value of open is onStart.
width
Sets the width of the top-level window. Only length values are allowed. For "length" values, SMIL MultiWindowLayout only supports pixel units as defined in CSS2. It allows the author to leave out the "px" unit qualifier in pixel values (the "px" qualifier is required in CSS2).
Element content

The topLayout element may contain any number of region elements, or be empty.

Element examples

This section is informative.

The following example provides a restatement of the root-layout example:

<smil xmlns="...">
  <head>
    <layout>
      <topLayout width="320" height="480" />
        <region id="a" top="5" />
      </topLayout/>
    </layout>
  </head>
  <body>
    <text region="a" src="text.html" dur="10s" />
  </body>
</smil>

Multiple instances of the topLayout element may occur within a single layout element:

  <layout>
    <topLayout id="WinV" title="Video" width="320" height="240"/>
      <region id="pictures" title="pictures" height="100%" fit="meet"/>
    </topLayout>
    <topLayout id="WinC" title="Captions" width="320" height="60">
      <region id="captions" title="caption text" top="90%" fit="meet"/>
    </topLayout>
  </layout>

In this example, two top-level windows are defined ("WinV" and "WinC"), and two regions are defined with one region ("pictures") assigned to WinV and the other ("captions") to WinC. These windows may be opened and closed independently by the presentation or by a user.

The layout element

The MultiWindowLayout module does not redefine the BasicLayout layout element. Instead, it simply extends the content model for that element, as described in the following subsection.

Element content

The layout element defined in the SMIL BasicLayout module is extended by adding topLayout element to the content model of the layout element if the type attribute of the layout element has the value "text/smil-basic-layout".

5.5.3 MultiWindowLayout Module Events

This module includes two events that may be included in the integrating language profile.

topLayoutOpenEvent
Raised when a topLayout window opens. This event is delivered to the associated topLayout element. If a topLayout closes and then reopens when additional media becomes active in any of its regions, this event will be raised again, and will be raised every subsequent time it reopens.
topLayoutCloseEvent
Raised when a topLayout closes for any reason. This event is delivered to the associated topLayout element. If a topLayout reopens when additional media becomes active in any of its regions, this event will be raised again if and when the topLayout closes again, and will be raised every subsequent time it closes.

5.5.4 Implementation and Integration Requirements for the MultiWindowLayout Module

Implementation details

Allowing multiple topLayout elements within a single layout element implies support for multiple top level windows. If an implementation does not support multiple top level windows (because of device or processing restrictions), only content in the first top-level window defined in the layout will be rendered. Non-rendered objects will still participate in all SMIL timing and scheduling operations.

If used together with the root-layout element, any direct peer-level regions to the root-layout will be contained within the extents of the root-layout.

5.5.5 Integration Requirements for the MultiWindowLayout Module

The functionality in this module builds on top of the functionality in the BasicLayout module, which is a required prerequisite for inclusion of the MultiWindowLayout module.

The language profile must specify the declarative names for binding the topLayoutOpenEvent and topLayoutCloseEvent events described in the MultiWindowLayout Module Events section, as well as the bubbling behavior of the events.

5.5.6 Document Type Definition (DTD) for the MultiWindowLayout Module

See the full DTD for the SMIL Layout modules.

5.6 The SMIL SubRegionLayout Module

This section is normative.

5.6.1 Overview

The SubRegionLayout module defines two mechanisms for defining regions that are logically contained within a parent region (these are SMIL's sub-regions). First, the SubRegionLayout module extends the definition of the region element to allow for the specification of sub-regions within the layout section as hierarchical content of regions. Second, the SubRegionLayout module extends the attributes allowed on (media) object references to allow a dynamic sub-region to be defined in-line by that object instance only. All values given for placement within sub-regions are defined in terms of the parent region's placement attributes. The ability to define sub-regions can be exploited for authoring convenience or when changing the location of a group of related regions using SMIL Animation.

This section is informative.

In the following fragment, a parent region (CaptionedVideo) is defined that contains two hierarchical sub-regions: image and captions. The placement of the image and caption content is specified as relative to the dimensions of the parent region. This is an example of a statically-defined hierarchy of sub-regions.

  <layout>
     ...
     <region id="CaptionedVideo" top="10px" left="20px" width="320" height="300">
       <region id="image" title="image content" width="100%" height="240px" fit="meet"/>
       <region id="captions" title="caption text" top="240px" height="60px" fit="meet"/>
     </region>
     ...
  </layout>

A presentation using the above layout specification could also create a dynamic sub-region that is defined for use by this single object:

  <body>
      ...
     <img id="Title" region="image" top="5%" left="3" bottom="10%" right="15%"  src="TitleImage.png"/>
     ...
  </body>

This statement creates a sub-region with the named region "image" with the given extents. In the example above, the effective boundaries of the sub-region for the placement of this object are defined by declaring the top, bottom, left and right edges of the region to the values shown, and then filling the resulting sub-region with the specified image as directed by the fit attribute. If the size of the media object being displayed is smaller than that of the resulting sub-region, the display will be similar to: picture of sub-regions

The use of in-line sub-region placement is intended as a light-weight alternative to defining a large number of single-use regions. Often, the dimensions used for the sub-region will match the dimensions of the media object being placed, but in all cases the values of the fit attribute will govern rendering of the object in the sub-region. The other attributes on the media element that would have been applied to a referenced region are applied to the sub-region instead. Note that the default values for the sub-region attributes are all 'auto', meaning that, by default, a sub-region is created having the same size and position as the parent region.

The use of sub-region positioning leads to authoring convenience and SMIL file compactness, since many separate regions do not need to be defined to handle incidental layout needs. The support for a hierarchy of sub-regions also allows multiple layout objects to be animated in concert by moving the parent region using SMIL Animation facilities.

5.6.2 Elements and attributes

This section defines extensions to the region and ref elements (and its synonyms) to support sub-region functionality.

The region element

This module extends the definition of the region element to include the definition of hierarchical sub-regions.

Element attributes

In the SubRegionLayout module, the region element has no additional attributes beyond that provided in the other included layout modules. However, the semantics of the z-index attribute are extended to support hierarchical sub-regions.

z-index
This attribute is defined as in the BasicLayout module with extensions presented here.
The z-index attribute defines the level of the region within the parent region stacking context. Elements assigned to higher level regions are rendered in front of lower level regions within the same parent region. Child regions are always placed in front of their parent region. This results in a two stage sorting of region visibility: first by parent-child containment, and then by z-index among siblings.

Just as with simple non-hierarchical regions, the stacking order of hierarchical regions may be affected by temporal activation. A region becomes active either when media begins rendering into it, or when one of its child regions becomes active. If two sibling regions have the same z-index, the region most recently made active is in front of the other region.

Element content

The SMIL SubRegionLayout module extends the region element content model to include region elements.

The ref element (and its synonyms)

The SubRegionLayout module extends the ref element to allow a separate, unnamed sub-region to be defined for the media object reference containing the sub-region positioning attributes.

Element attributes

The ref element defined in the MediaObject module and its synonyms are extended to include the following positioning attributes.

top
This value uniquely identifies the position or the distance (using CSS2 pixel or non-negative percentage values) of the top edge of the sub-region relative to the top of the region. The "px" unit qualifier in pixel values may be omitted. The default value of top is auto.
bottom
This value uniquely identifies the position or the distance (using CSS2 pixel or non-negative percentage values) of the bottom edge of the sub-region relative to the bottom of the region. The "px" unit qualifier in pixel values may be omitted. The default value of bottom is auto.
height
This value uniquely identifies the position or the distance (using CSS2 pixel or non-negative percentage values) of the bottom edge of the sub-region relative to the top side of the sub-region. The "px" unit qualifier in pixel values may be omitted. The default value of height is auto.
left
This value uniquely identifies the position or the distance (using CSS2 pixel or non-negative percentage values) of the left edge of the sub-region relative to the left of the region. The "px" unit qualifier in pixel values may be omitted. The default value of left is auto.
right
This value uniquely identifies the position or the distance (using CSS2 pixel or non-negative percentage values) of the right edge of the sub-region relative to the right side of the region. The "px" unit qualifier in pixel values may be omitted. The default value of right is auto.
width
This value uniquely identifies the position or the distance (using CSS2 pixel or non-negative percentage values) of the right edge of the sub-region relative to the left side of the sub-region. The "px" unit qualifier in pixel values may be omitted. The default value of width is auto.

Conflicts between the region size attributes bottom,height, left, right, top, and width are resolved according to the rules for placeholder elements described in the section on the region element.

The sub-region positioning attributes will be ignored if they are used on an element without a region attribute (or, if supported, the regionName attribute) that resolves to a region element in the layout section.

5.6.3 SubRegionLayout Module Events

This module does not define any SMIL events.

5.6.4 SubRegionLayout Implementation and Integration

Implementation Details

The position of a region, as specified by its top and left attributes, is always relative to the parent geometry, which is defined by the parent element. For the SMIL SubRegionLayout module, all hierarchical region elements must have as their immediate parent a region or topLayout element. The position of the hierarchical region is defined relative to that parent element. The intrinsic size of a region is equal to the size of the parent geometry.

When region sizes, as specified by width and height attributes are declared relative with the "%" notation, the size of the hierarchical region is relative to the size of the parent region. Sizes declared as absolute pixel values are absolute values even when used with a child region.

Note that a (hierarchical) region may be defined in such a way as to extend beyond the limits of its parent. In this case the child region must be clipped to the parent boundaries.

If a z-index attribute is defined on the hierarchical region, it is evaluated as a local index within that of the parent.

If the fit attribute and alignment attributes regPoint and regAlign are relevant to the placement of a particular media object, the interaction is the same as described in the definition of regPoint. If sub-region positioning attributes are used on a media object along with fit or the alignment attributes regPoint and regAlign, these attributes apply to the sub-region. In this case the fit setting on the referenced region element does not apply to the sub-region.

For both sub-region positioning and registration point use (as defined in the module), the value of the z-index attribute on the associated region is used. If media objects overlap spatially, existing rules for resolving z-index conflicts are applied.

Note that placement within the region may be defined in such a way as to extend the media object beyond the limits of the region. In this case the media object must be clipped to the region boundaries.

If two hierarchical regions with the same z-index attribute value overlap, the existing rules for z-index processing defined in the BasicLayout module are applied. Specifically, the rule concerning time priority is maintained, meaning that in the case of a z-index conflict, the media visible in the overlap will be determined by the region that is rendering the media that has most recently begun in time. If the conflicting media began at the same time, then the rule using the textual order of the media elements in the SMIL document is applied.

This section is informative.

For example:

<layout> 
   <root-layout width="640px" height="480px" />
   <region id="whole" top="0px" left="0px" width="640px" 
                                height="480px" z-index="5"/>
   <region id="right" top="0px" left="320px" width="320px"
                                height="480px" z-index="4">
       <region id="inset" top="140px" left="80" width="160px" 
                                height="200px" z-index="6"/>
       <region id="inset2" top="140px" left="80" width="160px" 
                                height="200px" z-index="6"/>
       <region id="inset3" top="140px" left="80" width="160px" 
                                height="200px" z-index="7"/>
   </region>
</layout>
...
<par>
        <img id="A" region="whole" src="imageA.jpg" dur="10s"/>
        <img id="B" region="inset" src="imageB.jpg" dur="10s"/>
</par>
<par>
        <img id="D" region="inset2" src="imageD.jpg" begin="1s" dur="10s"/>
        <img id="C" region="inset" src="imageC.jpg" begin="0s" dur="10s"/>
</par>
<par>
        <img id="E" region="inset2" src="imageE.jpg" dur="10s"/>
        <img id="F" region="inset3" src="imageF.jpg" dur="10s"/>
</par>
  1. In the first "par", image "A" and image "B" begin at the same time. Image A will obscure image "B", even though the z-index of "inset" is greater than that of "whole". This is because the z-index of "right", which is the region containing "inset" is less than that of "whole".
  2. In the second "par", images "C" and "D" are rendered into regions occupying the same area of the rendering surface. Image "C" will be shown for one second and then obscured by Image "D", since "D" begins after image "C". Note that lexical order is irrelevant here.
  3. In the third "par", the z-index of region "inset" is considered when computing stacking between siblings, and therefore image "F" will be shown, but image "E" will be obscured for the entire 10 seconds that they are both active.

Integration Requirements for the SubRegionLayout Module

The functionality in this module builds on top of the functionality in the BasicLayout module and the MediaObject module, which are required prerequisites for inclusion of the SubRegionLayout module. If the functionality in this module is to be used with the topLayout construct, the MultiWindowLayout module is a prerequisite.

5.6.5 Document Type Definition (DTD) for the SubRegionLayout Module

See the full DTD for the SMIL Layout modules.

5.7 AlignmentLayout Module

This section is normative.

5.7.1 Overview

A registration element is an element defined within this module that is used to define a point within a region and a default object alignment algorithm about that point. The element can be used in a media object element, where it is associated with a region and an optional override alignment algorithm. The placement values within registration elements can be either percentages or pixels.

The use of registration points allows for consistent relative placement across regions. As such, registration points are defined outside of any single region.

Registration points can be used to coordinate the placement of a set of media objects that do not share the same sizes. (For example, a set of images can be aligned to the center of a region.) They can also be used to coordinate the display of images about a particular point in a region.

For authoring convenience, SMIL AlignmentLayout module provides several pre-defined region registration points including topLeft, topMid, topRight, midLeft, center, midRight, bottomLeft, bottomMid, and bottomRight.

As a further convenience, SMIL AlignmentLayout module provides the mediaAlign attribute, which defines a combination of regAlign and regPoint attributes. For example, media objects can be centered in any region using mediaAlign as follows:

    <ref ... mediaAlign="center" />

If the mediaAlign attribute and either (or both) of the regPoint and regAlign attributes are used together, the regPoint and/or regAlign value(s) will override the corresponding effective regPoint/regAlign value(s) defined by the mediaAlign value.

The default value of regAlign for a region is topLeft. If the regAlign attribute is used without a regPoint attribute, the alignment operation is relative to the upper left point of the region containing this object, that is, the behavior is the same as if the regPoint were to be specified as topLeft.

Rules for handling clipping of objects within regions based on the regPoint and regAlign attributes are defined below.

This section is informative.

An example is given in the following code of two registration points (with id values "midPoint" and "topMargin"), one of which is defined as a relative location and one at a fixed pixel location, using the SMIL AlignmentLayout syntax:

    <layout>
<regPoint id="midPoint" top="50%" left="50%" regAlign="center" />
<regPoint id="topMargin" top="10" left="15" regAlign="topLeft" />
<region id="a" ... />
<region id="b" ... />
</layout>

In this example, the registration point with the id value "midPoint" has a default alignment algorithm that centers the media object about the defined point, while the registration point with the id value "topMargin" has a default alignment algorithm that places the top-left point of the media object at the registration point.

Various media elements could be displayed in the regions using the alignment points as follows:

  
<ref region="a" src="rtsp://..." dur="2s" regPoint="midPoint" />
<ref region="b" src="http://..." dur="2s"
regPoint="midPoint" regAlign="bottomRight"/>
<ref region="a" src="http://..." dur="2s" regPoint="topMargin" />
<ref region="b" src="http://..." dur="2s"
regPoint="topMargin" regAlign="center"/>

In the first example, a media object is centered in the middle of regiona. In the second example, a media object has its bottom right corner centered in the middle of region b. Similarly, in the third example, a media object has its top left corner placed at a point 10,15 within region a, and in the fourth example, an object is centered around the point 10,15 in region b.

The following example illustrates how images can be aligned at a particular point in a region:

   <layout>
<regPoint id="middle" top="50%" left="50%" regAlign="center" />
<region id="a" ... />
</layout>
...
<seq>
<ref region="a" src="rtsp://..." dur="2s" regPoint="middle"
regAlign="bottomRight"/>
<ref region="a" src="http://..." dur="2s" regPoint="middle"
regAlign="bottomLeft"/>
<ref region="a" src="http://..." dur="2s" regPoint="middle"
regAlign="topLeft"/>
<ref region="a" src="http://..." dur="2s" regPoint="middle"
regAlign="topRight"/>
</seq>

In this example, four objects are aligned over time to the middle of region. If any media element extends outside the bounds of a region, it will be clipped to the region.

In the following example, media objects can be centered in any region using pre-defined registration and alignment points:

    <ref ... regPoint="center" regAlign="center" />

Note that registration points are global within the context of a layout, and are not tied to a particular region, but can be reused across regions. As such, pixel-based offsets should be used with care.

5.7.2 Elements and Attributes for the AlignmentLayout Module

This section defines the elements and attributes that make up the SMIL AlignmentLayout module.

The layout element

This element extends the content model of the layout element to support the registration point functionality described in this section.

Element content

If the type attribute of the layout element has the value "text/smil-basic-layout", it is extended to contain the following elements:

region
root-layout
regPoint

The regPoint element

The regPoint element determines the (x, y) coordinates of a point relative to a region upper-left corner for use in aligning elements in the document's body on regions within a visual rendering surface. A regPoint may be defined using absolute (pixel) or relative (percentage) based values. The regPoint functionality is not defined and may not be used for media without intrinsic size.

For the purposes of regPoint functionality, media and regions are defined to be rectangular, with perpendicular sides, with the sides ordered clockwise top, right, bottom, and left. The top side is the edge closest to the point or edge of the display device considered "up".

Element attributes
top
This value uniquely identifies the position or the distance (using CSS2 pixel or non-negative percentage values) of the registration point relative to the top of the region. The "px" unit qualifier in pixel values may be omitted. The default value of top is auto.
bottom
This value uniquely identifies the position or the distance (using CSS2 pixel or non-negative percentage values) of the registration point relative to the bottom of the region. The "px" unit qualifier in pixel values may be omitted. The default value of bottom is auto.
left
This value uniquely identifies the position or the distance (using CSS2 pixel or non-negative percentage values) of the registration point relative to the left location of the region. The "px" unit qualifier in pixel values may be omitted. The default value of left is auto.
right
This value uniquely identifies the position or the distance (using CSS2 pixel or non-negative percentage values) of the registration point relative to the right location of the region. The "px" unit qualifier in pixel values may be omitted. The default value of right is auto.
regAlign
This attribute specifies the default alignment algorithm which is associated with a regPoint relative to the media object. The value of topLeft is the default. The following values are allowed:
topLeft
Align the top-left corner of the object with the registration point.
topMid
Align the top-middle point of the object with the registration point. The top-middle is the point offset width/2 to the right of the object top-left corner.
topRight
Align the top-right corner of the object with the registration point.
midLeft
Align the middle-left point of the object with the registration point. The middle-left is the point offset height/2 down from the object top-left corner.
center
Align the center of the object with the registration point.
midRight
Align the middle-right point of the object with the registration point. The middle-right is the point offset height/2 down from the object top-right corner.
bottomLeft
Align the bottom-left corner of the object with the registration point.
bottomMid
Align the bottom-middle point of the object with the registration point. The bottom-middle is the point offset width/2 right from the object bottom-left corner.
bottomRight
Align the bottom-right corner of the object with the registration point.
Element content

None.

The region element

This module extends the definition of the region element to include the definition of default alignment policies for content in that region.

Element attributes
regPoint
This attribute is identical to the regPoint attribute on media objects defined below, except that it defines a default alignment point for all media objects placed in the region. The default value for this attribute when used on the region element is topLeft.
regAlign
This attribute is identical to the regAlign attribute on media objects defined below, except that it defines a default alignment policy for all media objects placed in the region. The default value for this attribute when used on the region element is topLeft.
mediaAlign
This attribute is identical to the mediaAlign attribute on media objects defined below, except that it defines a default combination registration point/alignment policy for all media objects placed in the region. The default value for this attribute when used on the region element is undefined; the default behavior of this attribute is the behavior resulting from the application of the regPoint and regAlign attributes. (Note that this defines an effective default behavior of topLeft.)
soundAlign
This attribute is identical to the soundAlign attribute on media objects defined below, except that it defines a default 2D placement of the audio portion of a media element assigned to play within the given region. The default value for this attribute when used on the region element is both.
Element content

SMIL AlignmentLayout module does not extend the region element content model.

The ref element (and its synonyms)

The AlignmentLayout module extends the ref element to allow the positioning of media content within a region based on the an alignment registration point and an alignment policy.

Element attributes

The ref element defined in the MediaObject module is extended to include the regPoint attribute conjunction with the regPoint element. If a regPoint attribute is missing or refers to a non-existent regPoint element the value of the regAlign attributes are applied to the top-left point of the region containing the media object.

regPoint
This value uniquely identifies the registration point to be used for the placement of the object. The value should be an XML identifier of a regPoint element.
The following values are predefined registration points that do not have to be declared as regPoint elements before they are used:
topLeft
Same as using top="0%" left="0%" on the element without the regPoint attribute.
topMid
Same as using top="0%" left="50%" on the element without the regPoint attribute.
topRight
Same as using top="0%" left="100%" on the element without the regPoint attribute.
midLeft
Same as using top="50%" left="0%" on the element without the regPoint attribute.
center
Same as using top="50%" left="50%" on the element without the regPoint attribute.
midRight
Same as using top="50%" left="100%" on the element without the regPoint attribute.
bottomLeft
Same as using top="100%" left="0%" on the element without the regPoint attribute.
bottomMid
Same as using top="100%" left="50%" on the element without the regPoint attribute.
bottomRight
Same as using top="100%" left="100%" on the element without the regPoint attribute.
Note that the predefined registration points have the same meaning relative to the region as the regAlign attribute values have relative to the media. The defalut value is inherited from the regPoint value defined for the associated region. This implies a default behavior of topLeft.
regAlign
This value uniquely identifies the registration algorithm to be used for the regPoint defined for the object, and overrides any regAlign attribute on the referenced regPoint element. Permissible values are those defined under the regAlign attribute for the regPoint element. If used without an explicit regPoint attribute, the value is relative to the top left point of the region used by the associated media object. The defalut value is inherited from the regAlign value defined for the associated region. This implies a default behavior of topLeft.
mediaAlign
This value uniquely identifies a short-hand notation for combining set combinations of regAlign and regPoint attributes. Valid values are:
topLeft
Same as using the regPoint ="topLeft" and regAlign="topLeft" attributes.
topMid
Same as using the regPoint ="topMid" and regAlign="topMid" attributes.
topRight
Same as using the regPoint ="topRight" and regAlign="topRight" attributes.
midLeft
Same as using the regPoint ="midLeft" and regAlign="midLeft" attributes.
center
Same as using the regPoint ="center" and regAlign="center" attributes.
midRight
Same as using the regPoint ="midRight" and regAlign="midRight" attributes.
bottomLeft
Same as using the regPoint ="bottomLeft" and regAlign="bottomLeft" attributes.
bottomMid
Same as using the regPoint ="bottomMid" and regAlign="bottomMid" attributes.
bottomRight
Same as using the regPoint ="bottomRight" and regAlign="bottomRight" attributes.
If specified together with either (or both) of the regPoint and/or regAlign attributes, the effect values of the respective positioning attribute(s) specified by mediaAlign will be overridden by the values given for regPoint and/or regAlign. This attribute does not have a default value; the default behavior is inherited from the effective values of the regPoint and regAlign attributes.
soundAlign
Specifies the coarse 2D placement of the audio portion of a media element assigned to play within the given region. The default value is inherited from the region. The following values are allowed:
both
Place the audio on both channels. If stereo or other dual-channel audio is used, the audio will be reproduced on both channels, implementation permitting.
left
Place the audio on the left channel only. If stereo audio is used, only the left source audio will be reproduced on the left audio channel, implementation permitting.
right
Place the audio on the right channel only. If stereo audio is used, only the right source audio will be reproduced on the right audio channel, implementation permitting.
Element content

SMIL AlignmentLayout module does not extend the ref element content model.

5.7.3 AlignmentLayout Module Events

This module does not define any SMIL events.

5.7.4 SMIL AlignmentLayout Implementation and Integration

Implementation Details

If an implementation cannot support the soundLevel attribute, it may be ignored. Even when processing is ignored, the attribute must be correctly parsed.

The regPoint element may only appear as an immediate child of a layout element.

If the registration point functionality is used on a media object that also uses sub-region positioning, the registration point applies to the subregion.

For registration point use, the value of the z-index attribute on the associated region is used. If media objects overlap spatially, existing rules for resolving z-index conflicts are applied.

Note that placement within the region may be defined in such a way as to extend the media object beyond the limits of the region. In this case the media object must be clipped to the region boundaries.

The default value of regAlign for a region is topLeft. If the regAlign attribute is used without a regPoint attribute, the alignment operation is relative to the upper left point of the region containing this object, that is, the behavior is the same as if the regPoint were to be specified as topLeft.

If the registration point or alignment functionality is used on a media object, the interaction between the regPoint attribute value, the regAlign attribute value, and the fit attribute value of the region in which the media object is displayed is as follows:

fill fit value:
This depends on the value of the regAlign attribute. (Note: in all cases, the media must maintain proper alignment over the regPoint):
topLeft regAlign value:
Scale the object's height and width independently so that the content just touches the bottom and right edges of the box.
topMid regAlign value:
Scale the object's height and width independently so that the content just touches the bottom edge of the box, and the nearest (to the regPoint) of the left or right edges of the box.
topRight regAlign value:
Scale the object's height and width independently so that the content just touches the bottom and left edges of the box.
midLeft regAlign value:
Scale the object's height and width independently so that the content just touches the nearest (to the regPoint) of the top or bottom edges of the box, and touches the right edge of the box.
center regAlign value:
Scale the object's height and width independently so that the content just touches the nearest (to the regPoint) of the top or bottom edges of the box, and touches the nearest (to the regPoint) of the left or right edges of the box.
midRight regAlign value:
Scale the object's height and width independently so that the content just touches the nearest (to the regPoint) of the top or bottom edges of the box, and touches the left edge of the box.
bottomLeft regAlign value:
Scale the object's height and width independently so that the content just touches the top and right edges of the box.
bottomMid regAlign value:
Scale the object's height and width independently so that the content just touches the top edge of the box, and the nearest (to the regPoint) of the left or right edges of the box.
bottomRight regAlign value:
Scale the object's height and width independently so that the content just touches the top and left edges of the box.
hidden fit value:
Align the media over the given regPoint per the regAlign attribute. If the media so positioned extends past the bounds of the region, clip the excess media. If the media so positioned doesn't meet the bounds of the region, fill the remaining space with the background color of the region.
meet fit value:
This depends on the value of the regAlign attribute. Any part of the region that is not covered by the media is then filled with the region's background color. (Note: in all cases, the media must maintain proper alignment over the regPoint):
topLeft regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the right or bottom edge of the box while none of the content is clipped.
topMid regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches at least one of the left, right, or bottom edges while none of the content is clipped.
topRight regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the left or bottom edge of the box while none of the content is clipped.
midLeft regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches at least one of the top, right, or bottom edges while none of the content is clipped.
center regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches at least one of the top, left, right, or bottom edges while none of the content is clipped.
midRight regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches at least one of the top, left, or bottom edges while none of the content is clipped.
bottomLeft regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top or right edge of the box while none of the content is clipped.
bottomMid regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches at least one of the top, left, or right edges while none of the content is clipped.
bottomRight regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top or left edge of the box while none of the content is clipped.
meetBest fit value:
This interaction with the regAlign and regPoint attributes is identical that that of the meet fit value, with the exception that the size of the related media object is never scaled above 100%.
scroll fit value:
Align the media over the given regPoint per the regAlign attribute. If any part of the media extends beyond the bounds of the region, a scrolling mechanism should be invoked that allows viewing of the media that is clipped beyond the bounds of the region.
slice fit value:
This depends on the value of the regAlign attribute. (Note: in all cases, the media must maintain proper alignment over the regPoint):
topLeft regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the right or bottom edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped.
topMid regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the left, right, or bottom edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped. Clipping will occur on up to two sides of the region.
topRight regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the left or bottom edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped.
midLeft regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top, right, or bottom edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped. Clipping will occur on up to two sides of the region.
center regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top, left, right, or bottom edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped. Clipping will occur on up to three sides of the region.
midRight regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top, left, or bottom edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped. Clipping will occur on up to two sides of the region.
bottomLeft regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top or right edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped.
bottomMidregAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top, left, or right edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped. Clipping will occur on up to two sides of the region.
bottomRight regAlign value:
Scale the visual media object's height and width while maintaining its aspect ratio so that the content just touches the top or left edge of the box, whichever requires the largest scale factor. Any content that extends beyond the bounds of the region is clipped.

For example, a wide-screen video can be made to play in "letterbox" mode in a region, whose width-to-height ratio is smaller, by using regPoint ="center" and regAlign="center" and setting the region's fit value to "meet". The result is the video will touch the left and right edges of the region and will be centered vertically with the gaps above and below filled in with the region's background color.

Integration Requirements

The functionality in this module builds on top of the functionality in the BasicLayout module and the MediaObject module, which are required prerequisites for inclusion of the AlignmentLayout module.

5.7.5 Document Type Definition (DTD) for the AlignmentLayout Module

See the full DTD for the SMIL Layout modules.

5.8 BackgroundTilingLayout Module

This section is normative.

5.8.1 Overview

The SMIL BackgroundTilingLayout module defines a backgroundImage attribute that allows an image to be placed onto the background of a layout region. It also provides the same capability for the root-layout and any of the topLayout element(s), if supported by the language profile. This module also defines the backgroundRepeat attribute to control tiling of the background image. These facilities are provided as a convenience extension to SMIL's use of a background color in a region. Although similar functionality can be defined by using a combination of the image media object, the z-index attribute and subregions positioning, this would require substantially more authoring effort.

The BackgroundTilingLayout module allows simple convenience tiling support in a manner that is consistent with CSS2 [CSS2]. For more complex background image operations such as support for animated images or non-image background content, users are expected to use the standard media placement and alignment facilities available in SMIL Layout.

The opacity of the background images, whether or not tiled, is defined by the value of the backgroundOpacity attribute.

5.8.2 Elements and Attributes for the BackgroundTilingLayout Module

This section defines the backgroundImage and backgroundRepeat attributes that make up the SMIL BackgroundTilingLayout module.

The region Element

The root-layout Element

The topLayout Element

This module extends the attribute set for the region, root-layout and topLayout elements.

Element attributes
backgroundImage
This attribute may be used to specify an image that may be placed as the background of a region.
In SMIL Layout, the image is treated as a single image frame; any behavior that is specified in the image (such as animations or multiple frames) will be ignored. The legal values for this attribute are:
<uri>
This value consists of a URI containing the location of an image to be used as a background image. If the image is larger than the background, it will be clipped as if a fit attribute of hidden was specified. If the image is smaller in either or both dimensions than the region's dimensions, it will be processed according to the value of the backgroundRepeat attribute.
none
This value indicates that no background image should be used.
inherit
This value indicates that the same background image should be used as the logical parent of this region.
The default value is none.
backgroundRepeat
This attribute allows a repeat or tiling strategy to be specified for the background image. The legal values for this attribute are:
repeat
This value indicates that the background image should be repeated horizontally and vertically (that is, it should be tiled).
repeatX
This value indicates that the background image should be repeated horizontally only.
repeatY
This value indicates that the background image should be repeated vertically only.
noRepeat
This value indicates that the background image should not be repeated.
inherit
This value indicates that the same background repeat policy should be used as in the logical parent of this region.
The default value is repeat.
Element content

The SMIL BackgrondFillLayout module does not extend the content model for elements integrating these attributes.

5.8.3 BackgroundTilingLayout Module Events

This module does not define any SMIL events.

5.8.4 SMIL BackgroundTilingLayout Implementation and Integration

Implementation details

For purposes of establishing an inheritance default value, the root-layout element defined in SMIL BasicLayout is considered the root of the background image inheritance tree. In this case, both backgroundImage and backgroundRepeat may be used with the root-layout and region elements.

For profiles implementing the SMIL MultiWindowLayout module, each top-level layout element is considered to define a separate root of the background image inheritance tree. In this case, both backgroundImage and backgroundRepeat may be used with any topLayout elements.

Integration Requirements

The functionality in this module builds on top of the functionality in the BasicLayout module, which is a required prerequisite for inclusion of the BackgroundTilingLayout module. If this functionality is to be applied to multiple top-level windows, the MultiWindowLayout module must be included.

5.8.5 Document Type Definition (DTD) for the BackgroundTilingLayout Module

See the full DTD for the SMIL Layout modules.

5.9 OverrideLayout Module

This section is normative.

5.9.1 Overview

The SMIL OverrideLayout module includes the ability to use the fit, z-index, and backgroundColor attributes on objects displayed in a region in order to declare different behavior from that on the region element.

For languages and profiles integrating the AlignmentLayout module, the ability to specify override behavior for the regAlign, regPoint, mediaAlign, and soundAlign, attributes are defined as part of that module's specification and do not need to be explicitly specified in the OverrideLayout module.

5.9.2 Elements and Attributes for the OverrideLayout Module

This module does not define any new elements. It provides extensions to the ref element (and its synonyms).

The ref Element

The backgroundColor, backgroundOpacity, fit, and z-index attributes are added to media object references.

Element attributes
backgroundColor
This attribute specifies the background color that will be used in a sub-region. The range of legal values are the same as the backgroundColor attribute on the region element. The default value for this attribute is inherited from the region element.
backgroundOpacity
This attribute specifies the background opacity that will be used in a sub-region. The range of legal values are the same as with thebackgroundOpacity attribute under the region element.
fit
This attribute is used on a media element to override the fit attribute defined in the corresponding region definition. It takes the same values as the fit attribute on the region element, and has the same semantics with the exception that the declared fit only applies to the media element using it, and not to other elements which may use the same parent region. The default value for this attribute is inherited from the region element.
z-index
This attribute is used on a media element to override the z-index attribute defined in the corresponding region definition. It takes the same values as the z-index attribute on the region element, and has the same semantics with the exception that the declared z-index only applies to the media element containing the reference, and not to other elements which may use the same parent region. The default value for this attribute is inherited from the region element.
Element content

The SMIL OverrideLayout module does not extend the content model for the ref element integrating these attributes.

5.9.3 OverrideLayout Module Events

This module does not define any SMIL events.

5.9.4 SMIL OverrideLayout Implementation and Integration

Implementation Details

The OverrideLayout module allows individual media object references to override the default values for certain attributes. In all cases, the attributes will apply only to the (sub-)region referenced by the media object. Changes will not propagate to child sub-regions or to parent regions.

Integration Requirements

The functionality in this module builds on top of the functionality in the BasicLayout module, which is a required prerequisite for inclusion of the OverrideLayout module.

5.9.5 Document Type Definition (DTD) for the OverrideLayout Module

See the full DTD for the SMIL Layout modules.

5.10 MotionLayout Module

This section is normative.

5.10.1 Overview

The SMIL MotionLayout module defines four attributes for controlling motion within a layout region: crawlRate, crawlWrap, scrollRate and scrollWrap. These attributes extend the collection of attributes allowed on a media object reference. It is the expectation that these attributes will be animated during the presentation.

5.10.2 Elements and Attributes for the MotionLayout Module

This module does not define any new elements. It provides extensions to the region element.

The region Element

The crawlRate, crawlWrap, scrollRate and scrollWrap attributes are specified for a layout region.

Element attributes
crawlRate
This attribute specifies the vertical direction and rate of content mmovement within a region. A full description of this attribute will be given in a future version of this document.
crawlWrap
This attribute specifies the wrap behavior of content that is moved using the scrollRate attribute. A full description of this attribute will be given in a future version of this document.
scrollRate
This attribute specifies the vertical direction and rate of content movement within a region. A full description of this attribute will be given in a future version of this document.
scrollWrap
This attribute specifies the wrap behavior of content that is moved using the scrollRate attribute. A full description of this attribute will be given in a future version of this document.
Element content

The SMIL MotionLayout module does not extend the content model for the region element integrating these attributes.

5.10.3 MotionLayout Module Events

This module does not define any SMIL events.

5.10.4 SMIL MotionLayout Implementation and Integration

Implementation Details

This section will be provided in a future version of this module.

Integration Requirements

The functionality in this module builds on top of the functionality in the BasicLayout module, which is a required prerequisite for inclusion of the MotionLayout module.

5.10.5 Document Type Definition (DTD) for the MotionLayout Module

See the full DTD for the SMIL Layout modules.

6. The SMIL 3.0 Linking Modules

Editors for SMIL 3.0
Jack Jansen, CWI
Thierry Michel, W3C
Editors for Earlier Versions of SMIL
Lloyd Rutledge, CWI
Aaron Cohen, Intel.

6.1 Overview and Summary of Changes for SMIL 3.0

This section is informative.

The SMIL 3.0 specification integrates the general features of the XHTML-2 access and role attributes as an extension and replacement for the accessKey attribute.

6.2 Open Issues In This Version

The open issues at the time of writing this version of the SMIL State modules are:

6.3 Introduction

This section is informative.

The SMIL 3.0 Linking Modules define the SMIL 3.0 document attributes and elements for navigational hyperlinking. These are navigations through the SMIL presentation that can be triggered by user interaction or other triggering events, such as temporal events. SMIL 3.0 provides only for in-line link elements. Links are limited to uni-directional single-headed links (i.e. all links have exactly one source and one destination resource).The SMIL 3.0 Linking Modules are named LinkingAttributes, BasicLinking and ObjectLinking. The LinkingAttributes module includes a set of attributes used to provide SMIL linking semantics to linking elements. The BasicLinking module includes the SMIL 3.0 linking elements themselves. The ObjectLinking module includes additional optional linking features that a language profile may wish to include. Note that the BasicLinking module explicitly includes the attributes from the LinkingAttributes module on its elements.

6.4 Module Overview

This section is normative.

SMIL 3.0 Lin king functionality is partitioned across the following 2 modules:

6.5 Relationship with Other XML Linking-related Formats

This section is informative.

6.5.1 Relationship with XPointer

XPointer [XPTR] allows components of XML documents to be addressed in terms of their placement in the XML structure rather than on their unique identifiers. This allows referencing of any portion of an XML document without having to modify that document. Without XPointer, pointing within a document may require adding unique identifiers to it, or inserting specific elements into the document, such as a named anchor in HTML. XPointers are put within the fragment identifier part of a URI [URI] attribute value. The SMIL 3.0 specification allows but does not require that user agents be able to process XPointers in SMIL 3.0 URI attribute values (@@??).

6.5.2 Relationship with XLink

Where possible, SMIL linking constructs have the same names as constructs from XLink [XLINK]. This makes it easier to learn to write linking in code in both formats: authors familiar with XLink can more quickly learn SMIL linking, and vice versa. It also makes it easier for SMIL code to be processed into and recognized as XLink code when the appropriate transform mechanisms become available. However, the SMIL linking attributes are distinct from the XLink constructs and are part of a separate namespace. Using SMIL's modularization mechanism, these constructs are not in the XLink namespace but in the namespaces defined in the SMIL 3.0 specification.

6.5.3 Relationship with XML Base

SMIL profiles may use XML Base [XMLBase]. The SMIL 3.0 Language Profile, for example, includes support for XML Base. When XML Base is incorporated into a profile, XML Base declarations apply to the URI attribute values of SMIL used in that profile's documents. These attributes include the href attribute of the SMIL BasicLinking Module and the src attribute of the SMIL BasicMedia Module.

6.5.4 Relationship with XHTML

The elements names, attributes names and attribute values of SMIL linking constructs are, where possible, the same as constructs in XHTML [XHTML11] with corresponding linking behavior. This facilitates learning and writing in both languages and avoids confusion. It may also facilitate the processibility of both languages' linking constructs as XLink once the format is released. The linking constructs in SMIL, however, fall under the namespaces defined in SMIL 3.0, and not under any XHTML-related namespace.

6.6 Linking into SMIL 3.0 Documents

The SMIL 3.0 Linking Modules support name fragment identifiers and the '#' connector. The fragment part is an id value that identifies one of the elements within the referenced SMIL document. With this construct, SMIL 3.0 supports locators as currently used in HTML (that is, it uses locators of the form "http://www.example.org/some/path#anchor1"), with the difference that the values are of unique identifiers and not the values of "name" attributes. Of course, this type of link can only target elements that have an attribute of type ID. 

Links using fragment identifiers enable authors to encode links to a SMIL 3.0 presentation at the start time of a particular element rather than at the beginning of its presentation. If a link containing a fragment part is followed, the presentation should start as if the user had fast-forwarded the presentation represented by the destination document to the effective begin of the element designated by the fragment. See the discussion of linking to timing constructs in the SMIL 3.0 Timing and Synchronization Modules for more information.

There are special semantics defined for following a link containing a fragment part into a document containing SMIL timing. These semantics are defined in the SMIL 3.0 Timing and Synchronization Modules.

6.6.1 Handling of Links in Embedded Documents

Due to its integrating nature, the presentation of a SMIL 3.0 document may involve other (non-SMIL) applications or plug-ins. For example, a SMIL 3.0 user agent may use an HTML plug-in to display an embedded HTML page. Vice versa, an HTML user agent may use a SMIL plug-in to display a SMIL 3.0 document embedded in an HTML page. Note that this is only one of the supported methods of integrating SMIL 3.0 and HTML. Another alternative is to use the merged language approach. See the SMIL 3.0 Modules for further details.

In embedded presentations, links may be defined by documents at different levels and conflicts may arise. In this case, the link defined by the containing document should take precedence over the link defined by the embedded object. Note that since this might require communication between the user agent and the plug-in, SMIL 3.0 implementations may choose not to comply with this recommendation.

If a link is defined in an embedded SMIL 3.0 document, traversal of the link affects only the embedded SMIL 3.0 document.

If a link is defined in a non-SMIL document which is embedded in a SMIL 3.0 document, link traversal can only affect the presentation of the embedded document and not the presentation of the containing SMIL 3.0 document. This restriction may be relaxed in future versions of SMIL.

6.6.2 Error Handling

When a link into a SMIL 3.0 document contains an un-resolvable fragment identifier ("dangling link") because it identifies an element that is not actually part of the document, SMIL 3.0 software should ignore the fragment identifier, and start playback from the beginning of the document.

When a link into a SMIL 3.0 document contains a fragment identifier which identifies an element that is the content of a switch element, SMIL 3.0 software should interpret this link as going to the outermost ancestor switch element instead. In other words, the link should be considered as accessing the switch ancestor element that is not itself contained within a switch.

6.7 SMIL 3.0 LinkingAttributes Module

This section is normative.

The SMIL 3.0 LinkingAttribues module defines several attributes that a language profile can include on linking elements to add SMIL linking semantics to those elements. The elements in the BasicLinking Module explicitly include these attributes. These attributes can be applied to linking elements from other namespaces if allowed by the language profile.

sourceLevel
This attribute sets the relative audio volume of media objects in the presentation containing the link when the link is followed. This attribute takes non-negative percentage values. The units of the sourceLevel attribute are consistent with those described for the soundLevel attribute of the SMIL 3.0 Layout Modules, and the audio levels are modified in the same manner. The application of sourceLevel volume control is cumulative with any media specific volume control (such as the soundLevel attribute) on the presentation containing the link. When the display of the destination resource completes, the effect of sourceLevel attribute on the originating presentation should be removed. The default value is '100%'.
destinationLevel
This attribute sets the relative audio volume of media objects in the remote resource when the link is followed. This attribute can take non-negative percentage values. The destinationLevel attribute is applied to the natural or intrinsic audio volume of the destination media, and therefore is relative to the volume that the media would be played without application of the destinationLevel attribute. The units of the destinationLevel attribute are consistent with those described for the soundLevel attribute of the SMIL 3.0 Layout Modules, and the audio levels are modified in the same manner. The application of destinationLevel volume control is cumulative with any media specific volume control (such as the soundLevel attribute) specified by the remote resource. The default value is '100%'.
sourcePlaystate
This attribute controls the temporal behavior of the presentation containing the link when the link is traversed. It can have the following values:
  • play: When the link is traversed, the presentation containing the link continues playing.
  • pause: When the link is traversed, the presentation containing the link pauses. When the display of the destination resource completes, the originating presentation should resume playing.
  • stop: When the link is traversed, the presentation containing the link stops. That is, it is reset to the beginning of the presentation. The termination of the destination resource will not cause the originating presentation to continue or restart.
The value of the show attribute can determine the default value of or override the assignment of the sourcePlaystate attribute. In general, the show attribute takes precedence over the sourcePlaystate attribute. The rules for the impact of show on sourcePlaystate are:
  • If the show attribute is assigned the value new, then the default for the sourcePlaystate attribute is play.
  • If the show attribute is assigned the value replace or the deprecated value pause, then the presentation behaves as if the sourcePlaystate attribute had been set to pause. Any assignment of the sourcePlaystate attribute is ignored.
Note that the definition of what constitutes a resource completing needs to be defined in the language profile, or may be implementation dependent. Typical definitions would be when the user closes the display window, or when a continuous media object ends.
destinationPlaystate
This attribute controls the temporal behavior of the external resource (typically identified by the href attribute) when the link is followed. It only applies when this resource is a continuous media object. It can have the following values:
  • play: When the link is traversed, the destination of the link plays.
  • pause: When the link is traversed, the destination of the link is displayed in a paused state at the point depicted by the value of the href attribute.

The default value is play.

show
This attribute specifies how to handle the current state of the presentation at the time in which the link is activated. The following values are allowed:
  • new: The presentation of the destination resource starts in a new context, not affecting the source resource. If both the presentation containing the link and the remote resource contain audio media, both are played in parallel.
  • pause: This value is deprecated in favor of setting the show attribute to new and the sourcePlaystate attribute to pause.
  • replace: The current presentation is paused at its current state and is replaced by the destination resource. If the player offers a history mechanism, the source presentation resumes from the state in which it was paused when the user returns to it. The default value of  sourcePlaystate is pause when the show attribute has the value replace. If the link destination is within the same document in which this link element lies, then any assignment of this element's sourcePlaystate attribute is ignored, and the link is processed as if the value of sourcePlaystate was stop. For more discussion regarding hyperlinking within the current document, see the "Hyperlinks and Timing" section of the SMIL 3.0 Timing and Synchronization Modules.

The default value of show is replace.

external
This attribute defines whether the link destination should be opened by the current application or some external application. A value of true will open the link in an external application defined on the system to handle this media type. A value of false will open the destination in the current application, however, if the current application does not support the media type of the referenced media, then it should attempt to render the media using an external application. Note that the means of associating media types with external applications is system dependent and not defined here. The default value of external is false.
Note that the above behavior for the external attribute applies to mailto links as well as media.
actuate
The actuate attribute determines whether or not the link is triggered by some event or automatically traversed when its time span is active. Its default value is onRequest, which means something must trigger the link traversal, typically user interaction. A value of onLoad can also be assigned. This value indicates that the link is automatically traversed when the linking element becomes active. For linking elements containing SMIL timing, this is when the active duration of the linking element effectively begins, in other words, when the element's beginEvent event is fired. This means that a SMIL link can be encoded to be triggered by any event that can trigger the begin of a timed element. See the SMIL 3.0 Timing and Synchronization Modules for more details.

Each of the following attributes has the same syntax as the attributes of the same name in HTML [HTML4] and, where applicable, the same semantics:

alt
This attribute is defined for SMIL 3.0 in the SMIL 3.0 Media Object Modules. The recommendations given there for the alt attribute on media object elements apply to its use in linking elements as well.
accesskey
This attribute assigns a keyboard key whose activation by the user in turn activates this link. It has the same meaning as the attribute of the same name in HTML [HTML4]. Keystroke-activated links in embedded presentations stay effective when embedded -- that is, if the user hits that key during the SMIL presentation, that navigation occurs within the embedded media. The rules for disambiguating links in multiple objects are:
  • Keystroke links defined in SMIL dominate over those defined in embedded media.
  • When simultaneously active SMIL linking elements have the same "accesskey", then priority goes to the one activated earliest, then to the one defined first on the SMIL code.
  • In profiles in which the SMIL 3.0 Layout Modules are used, links in media objects placed in the foremost region dominate, as defined by "stacking level" in the SMIL 3.0 Layout Modules.
  • Media objects for which no region is assigned are assumed to be more forward on the stacking level than all media objects assigned regions. This allows for the possibility of audio objects that have keystroke input, such as hyperlinked talking books for the sight-impaired.
tabindex
This attribute provides the same functionality as the tabindex attribute in HTML [HTML4]. It specifies the position of the element in the tabbing order for the current document. The tabbing order defines the order in which elements will receive focus when navigated by the user via the keyboard. At any particular point in time, only elements with an active timeline are taken into account for the tabbing order. Inactive elements should be ignored for the tabbing order.
When a media object element has a tabindex attribute, then its ordered tab index is inserted in the SMIL tab index at the location specified by the media object's tabindex attribute value. This assumes the media object itself has tab indices, such as embedded HTML with tabindex attributes. This enables all link starting points in a SMIL presentation to have a place on the ordered list to be tab-keyed through, including those in embedded presentations.
target
This attribute defines either the existing display environment in which the link should be opened (e.g., a SMIL region, an HTML frame or another named window), or triggers the creation of a new display environment with the given name. Its value is the identifier of the display environment. If no currently active display environment has this identifier, a new display environment is opened and assigned the identifier of the target. When a presentation uses different types of display environments (e.g. SMIL regions and HTML frames), the namespace for identifiers is shared between these different types of display environments. For example, one cannot use a target attribute with the value "foo" twice in a document, and have it point once to an HTML frame, and then to a SMIL region. If the element has both a show attribute and a target attribute, the show attribute is ignored.

This section is informative.

Examples

These examples are encoded in the SMIL 3.0 Language Profile.

Example 1

This examples shows the use of the target and accesskey attributes. The upper half of the display shows an image. If the user clicks on the image, a SMIL presentation is played in the lower half of the display. The same thing happens if the user hits the 'a' key.

<smil xmlns="http://www.w3.org/2006/SMIL30/Language">
  <head>
    <layout>
      <region id="source"      height="50%"/>
      <region id="destination" top   ="50%"/>
    </layout>
 </head>
 <body>
   <a href="embeddedSMIL.smil" target="destination" accesskey="a">
     <img region="source" src="source.jpg" dur="indefinite"/>
   </a>
 </body>
</smil>

Example 2

This example shows the use of the tabindex attribute on media object elements. The HTML file "caption1.html" has 3 links, so the first 3 tabs focus on those links in turn. The file caption2.html has 4 links, so tabs 4-7 focus on them in turn. Tabs 8 and 9 focus the two links inside v1.mpg. Tab 10 focuses on the whole presentation of graph.imf. If any of the first 9 tabbed foci is activated, then a link inside one of the embedded presentations caption1.html, caption2.rtx or v1.mpg is triggered, affecting only that presentation. If the 10th tabbed focus is activated, then the SMIL presentation itself is affected, loading http://www.example.org/presentation into the same presentation space.

<smil xmlns="http://www.w3.org/2006/SMIL30/Language">
  ...
  <seq>
    <video src="http://www.example.org/graph.imf"/>
    <par>
        <a tabindex="4" href="http://www.example.org/presentation">
            <video src="http://www.example.org/graph.imf" ... />
        </a>
        <video tabindex="3" src="http://www.example.org/v1.mpg" ... />
        <text tabindex="1" src="http://www.example.org/caption1.html" ... />
        <text tabindex="2" src="http://www.example.org/caption2.html" ... />
    </par>
  </seq>

6.8 SMIL 3.0 BasicLinking Module

This section is normative.

The link elements allows the description of navigational links between objects. SMIL 3.0 linking provides only uni-directional, single-headed, in-line link elements.

6.8.1 The a Element

The functionality of the a element is very similar to the functionality of the a element in HTML [HTML4]. For synchronization purposes, the a element is transparent. That is, it does not influence the synchronization of its child elements. a elements may not be nested. An a element must have an href attribute.

An a element can specify several triggers for its traversal simultaneously. For example, the element's content visual media can be selected by the user or the key specified by the accesskey attribute can be typed to trigger a traversal. In cases where multiple triggers are specified, any of them can activate the link's traversal. That is, a logical OR is applied to the list of triggering conditions to determine if traversal occurs.

Traversal occurs if one of the conditions for traversal is met during the time that the a element is active. An a element is sensitive if the media or elements that it contains are active or frozen. See the SMIL 3.0 Timing and Synchronization Modules for further details. For timing purposes an a element is considered to be discrete media, that is, the intrinsic duration is 0. Note that an a element is not a time container and does not constrain the timing of its child elements.

Attributes
href
This attribute has the same syntax and semantics as the href attribute of HTML [HTML4]. It contains the URI of the link's destination. The href attribute is required for a elements.

The a element also includes the attributes defined in the SMIL 3.0 LinkingAttributes Module:

Element Content

The content of the a element must be defined by the language profile. In general, it is expected that a elements may contain the media and timing elements present in the language profile as children.

Other Integration Requirements

Language profiles that apply SMIL 3.0 timing to the a element must specify the default and allowed values of the fill attribute on the a element. Languages applying SMIL 3.0 timing to the a element wishing to remain compatible with SMIL 1.0, such as the SMIL 3.0 language profile, must default the value of the fill attribute on the a element to auto, and should consider fixing the value to auto. In all other cases, for compatibility, it is recommended to use a default value of auto

If not otherwise specified by the profile, the value of the fill attribute on the a element is fixed to auto.

This section is informative.

Examples

These examples are encoded in the SMIL 3.0 Language Profile.

Example 1

The link starts up the new presentation replacing the presentation that was playing.

<smil xmlns="http://www.w3.org/2006/SMIL30/Language">
  ...
  <a href="http://www.example.org/somewhereelse.smi">
     <video src="rtsp://www.example.org/graph.imf" region="l_window"/>
  </a>

Example 2

The link starts up the new presentation in addition to the presentation that was playing.

<smil xmlns="http://www.w3.org/2006/SMIL30/Language">
  ...
  <a href="http://www.example.org/somewhereelse.smi" show="new">
     <video src="rtsp://www.example.org/graph.imf" region="l_window"/>
  </a>

This could allow a SMIL 3.0 player to spawn off an HTML user agent:

<smil xmlns="http://www.w3.org/2006/SMIL30/Language">
  ...
  <a href="http://www.example.org/somewebpage.html" show="new">
     <video src="rtsp://www.example.org/graph.imf" region="l_window"/>
  </a>

Example 3

The link starts up the new presentation and pauses the presentation that was playing.

<smil xmlns="http://www.w3.org/2006/SMIL30/Language">
  ...
  <a href="http://www.example.org/somewhereelse.smi" show="new" sourcePlaystate="pause">
     <video src="rtsp://www.example.org/graph.imf" region="l_window"/>
  </a>

Example 4

The following example contains a link from an element in one presentation A to the middle of another presentation B. This would play presentation B starting from the effective begin of the element with id "next".

Presentation A:

<smil xmlns="http://www.w3.org/2006/SMIL30/Language">
  ...
  <a href="http://www.example.org/presentationB#next">
    <video src="rtsp://www.example.org/graph.imf"/>
  </a>


Presentation B (http://www.example.org/presentation):

<smil xmlns="http://www.w3.org/2006/SMIL30/Language">
  ...
  <seq>
    <video src="rtsp://www.example.org/graph.imf"/>
    <par>
      <video src="rtsp://www.example.org/timbl.rm" region="l_window"/>
      <video id="next" src="rtsp://www.example.org/v1.rm" region="r_window"/>
             ^^^^^^^^^
      <text src="rtsp://www.example.org/caption1.html" region="l_2_title"/>
      <text src="rtsp://www.example.org/caption2.rtx" region="r_2_title"/>
    </par>
  </seq>

6.8.2 The area Element

This section is normative.

The functionality of the a element is restricted in that it only allows associating a link with a complete media object. The HTML area element [HTML4] has demonstrated that it is useful to associate links with spatial portions of an object's visual display.

The semantics of the area element in SMIL 3.0 is the same as it is for HTML in that it can specify that a spatial portion of a visual object can be selected to trigger the appearance of the link's destination. The coords attribute specifies this spatial portion. In contrast, if an a element is applied to a visual object, then it specifies that any visual portion of that object can be selected to trigger the link traversal.

The area element also extends the syntax and semantics of the HTML area element by providing for linking from non-spatial portions of the media object's display. When used in profiles that include SMIL 3.0 Timing and Synchronization Modules, the area element allows breaking up an object into temporal subparts, using attributes such as the begin and end attributes. The values of the begin and end attributes are relative to the beginning of the containing media object. The area element can allow to make a subpart of the media object the destination of a link, using these timing attributes and the id attribute.

The anchor element of SMIL 1.0 [SMIL10] is deprecated in favor of area. For purposes of this specification of SMIL 3.0, the anchor element should be treated as a synonym for area

Attributes

The area element can have the attributes listed below, with the same syntax as in HTML [HTML4] and, where applicable, the same semantics:

href
Defined in the BasicLinking module.
alt
Defined in the LinkingAttributes module.
tabindex
Defined in the LinkingAttributes module.
accesskey
Defined in the LinkingAttributes module.
target
Defined in the LinkingAttributes module.
nohref
When set, this attribute specifies that the region has no associated link, even if other area elements for the media object define links for it. It uses the same syntax as for the nohref attribute in HTML 4.01.

shape
This attribute specifies the shape of an anchor on the screen, and is used with the coords attribute. The shape attribute of SMIL has the same behavior as in HTML [HTML4]. The object that the shape attribute is applied to is the media of the containing element after the media has been scaled for presentation but before it has been clipped.
coords
Along with the shape attribute, this attribute specifies the position and shape of the anchor on the screen. The number and order of values depends on the shape being defined. Where SMIL and HTML share visual display behavior, the coords attribute of SMIL has the same behavior as in HTML [HTML4]. How the coords attribute of SMIL applies to SMIL visual display behavior is as follows:
  1. The upper-left corner origin used by the coords attribute is in the image display space, not the region it is displayed in. One example of when the image and region upper-left corner differ is when left and top attributes are used in the media object elements and applied to the region.
  2. As in HTML, pixel values of the coords attribute refer to the pixels of the display space - that is, typically, of the user's screen. These can differ from the pixel values of the source image. One example of when they can differ in SMIL is when the fit attribute of the region element used is not "hidden".
  3. In SMIL, it is possible for a portion of the image to be not visible. For example, this can happen when the fit attribute of the region element is hidden, and the image is bigger in pixels than the region. In such cases, the rules for placing active areas on the image apply to the screen space the image would take if no cropping occurred. This is particular important to note for percentage values: these do not apply to the cropped image but to the space the image would occupy if it weren't cropped. Areas that, with this rule, are placed beyond display boundaries are not active.
If multiple area element children of the same media object element define simultaneously active overlapping areas with their coords attributes, then, as in HTML [HTML4], the area element that is encoded earliest in the document takes precedence.

The following attributes of the area element are unique to SMIL and not found in HTML. They are defined above in the section on LinkingAttributes module attributes:

Element Content

The area element is empty.

This section is informative.

Examples

These examples are encoded in the SMIL 3.0 Language Profile.

1) Decomposing a video into temporal segments

In the following example,  the temporal structure of an interview in a newscast (camera shot on interviewer asking a question followed by shot on interviewed person answering) is exposed by fragmentation:

<smil xmlns="http://www.w3.org/2006/SMIL30/Language">
  <body>
    <video src="video" title="Interview" >
        <area id="firstQ" begin="0s" dur="20s" title="first question" /> 
        <area id="firstA" begin="first0.end" dur="50s" title="first answer" />
    </video>
  </body>
</smil>

2) Associating links with spatial segments In the following example, the screen space taken up by a video clip is split into two sections. A different link is associated with each of these sections.

<smil xmlns="http://www.w3.org/2006/SMIL30/Language">
  <body>
    <video src="video" title="Interview" >
      <area shape="rect" coords="5,5,50,50" 
              title="Journalist" href="http://www.example.org/journalist"/> 

      <area shape="rect" coords="60,5,100,50" 
              title="Subject" href="http://www.example.org/subject"/>
   </video>
  </body>
</smil>

3) Associating links with temporal segments

In the following example, the duration of a video clip is split into two sub-intervals. A different link is associated with each of these sub-intervals.

<smil xmlns="http://www.w3.org/2006/SMIL30/Language">
  <body>
    <video src="video" title="Interview" >
        <area begin="0s" dur="20s" title="first question" 
              href="http://www.example.org/question"/>
        <area begin="20s" dur="50s" title="first answer" 
              href="http://www.example.org/answer"/>
   </video>
  </body>
</smil>

4) Associating links with spatial subparts

In the following example, two areas are assigned in the screen space taken up by a video clip. A different link is associated with each of these areas.

<smil xmlns="http://www.w3.org/2006/SMIL30/Language">
  ...
  <video src="http://www.example.org/CoolStuff">
    <area href="http://www.example.org/AudioVideo" coords="0%,0%,50%,50%"/>
    <area href="http://www.example.org/Style"      coords="50%,50%,100%,100%"/>
  </video>

5) Associating links with temporal subparts

In the following example, the duration of a video clip is split into two subintervals. A different link is associated with each of these subintervals.

<smil xmlns="http://www.w3.org/2006/SMIL30/Language">
  ...
  <video src="http://www.example.org/CoolStuff">
    <area href="http://www.example.org/AudioVideo" begin="0s" end="5s"/>
    <area href="http://www.example.org/Style"      begin="5s" end="10s"/>
  </video>

6) Jumping to a subpart of an object

The following example contains a link from an element in one presentation A to the middle of a video object contained in another presentation B. This would play presentation B starting from second 5 in the video. That is, the presentation would start as if the user had fast-forwarded the whole presentation to the point at which the designated fragment in the "CoolStuff" video begins.

Presentation A:

<smil xmlns="http://www.w3.org/2006/SMIL30/Language">
  ...
  <a href="http://www.example.org/mm/presentationB#tim">
     <video id="graph" src="rtsp://www.example.org/graph.imf" region="l_window"/>
  </a>


Presentation B:

<smil xmlns="http://www.w3.org/2006/SMIL30/Language">
  ...
  <video src="http://www.example.org/CoolStuff">
    <area id="joe" begin="0s" end="5s"/>
    <area id="tim" begin="5s" end="10s"/>
  </video>

7) Combining different uses of links

The following example shows how the different uses of associated links can be used in combination.

Presentation A:

<smil xmlns="http://www.w3.org/2006/SMIL30/Language">
  ...
  <a href="http://www.example.org/mm/presentationB#tim">
    <video id="graph" src="rtsp://www.example.org/graph.imf" region="l_window"/>
  </a>


Presentation B:

<smil xmlns="http://www.w3.org/2006/SMIL30/Language">
  ...
  <video src="http://www.example.org/CoolStuff">
    <area id="joe" begin="0s" end="5s" coords="0%,0%,50%,50%"
            href="http://www.example.org/"/>
    <area id="tim" begin="5s" end="10s" coords="0%,0%,50%,50%"
            href="http://www.example.org/Tim"/>
  </video>

8) The coords attribute and re-sized images

The following example shows the image file "example.jpg", which has the dimensions of 100x100 pixels. The active area for "example1.smil" is the entire display space, which is the cropped upper-left quarter of the original image. The active area for "example2.smil" cannot be triggered because the image area corresponding to it was cropped.

<smil xmlns="http://www.w3.org/2006/SMIL30/Language">
  <head>
    <layout>
      <region id="region" right="50" bottom="50"/>
    </layout>
  </head>
  <body>
    <img src="example.jpg" region="region">
      <area shape="rect" coords="0%,0%,50%,50%" href="example1.smil"/>
      <area shape="rect" coords="50%,50%,100%,100%" href="example2.smil"/>
    </img>
  </body
</smil>

6.9 SMIL 3.0 ObjectLinking Module

This section is normative.

The contents of this section represent capabilities that can be optionally included in the document profile. These features may or may not be included in a language profile, but they should not be optional features within a profile. This module requires support of the BasicLinking Module.

6.9.1 The fragment Attribute

A profile may choose to include the fragment attribute as part of the area element. It provides for a host document to externally include a link in a contained media object that will be processed at the level of the host document.

fragment
This attribute refers to a portion of the embedded media object that is to act as the starting point of this link in the SMIL presentation. If the user clicks on, or otherwise activates, this portion of the embedded media display, the SMIL user agent recognizes this as the current link being activated. This overrides any linking that may happen within the embedded display of the media object.

The value of the fragment attribute must be recognizable by the process managing the media object as an activate-able portion of the object. If the referenced media object is an HTML file, then the value of the fragment attribute is a named anchor within the HTML file. If the referenced media object is an XML file, then the value of the fragment attribute is a fragment identifier (the part that comes after a '#' in a URI [URI]).

Take for example the following SMIL code. It establishes a portion of the display as a formatted text menu. Clicking on an item in this menu triggers a link to elsewhere within the presentation.

<smil xmlns="http://www.w3.org/2006/SMIL30/Language">
  ...
  <ref src="menu.html" region="menubar">
    <area fragment="menuitem1" href="#selection1"/>
  </ref>

In the rendered HTML display, there is a portion of displayed text that is marked-up as an area with the name "menuitem1". If the user clicks on this during the SMIL presentation, a SMIL-activated link is triggered, navigating to the portion of the SMIL document with the ID "selection1". If the HTML area named "menuitem1" has an href attribute itself, then this hyperlink is overridden - only the SMIL hyperlink is processed. HTML area with href attributes and no associated SMIL fragment attributes are not overridden. This HTML area activates links within the embedded HTML presentation when clicked upon.

Use of the fragment attribute can override linking in the embedded media. If the attribute refers to a portion of the embedded media that is a link within that media, activating that link will trigger navigation in the SMIL presentation only, and not in the embedded presentation. For example, suppose a fragment attribute refers to a named anchor in an embedded HTML document. This named area has an href attribute, making it the starting point of a potential navigation within the HTML presentation itself. When embedded in the SMIL presentation, activation of this part of the HTML display triggers the SMIL link and not the HTML link. Links in embedded media that are not overridden in this manner, on the other hand, continue to trigger navigation within the embedded display when activated. All functionality defined for the SMIL link will override any equivalent functionality defined for the link in the embedded media. With the above example, the alt attribute of the SMIL area element would override the alt tag of the embedded HTML anchor.

The referencing performed by the fragment attribute only applies to one level of depth of embedded media. It only applies to directly embedded media; it does not apply to media embedded in turn within media embedded in a SMIL presentation. For example, consider a SMIL presentation that embeds a second SMIL presentation within it. The media object element of the first that embeds the second has within it an area element with a fragment attribute. The value of this attribute applies only to the embedded SMIL document itself. It does not apply to any media embedded within this second SMIL presentation.

This section is informative.

Examples

These examples are encoded in the SMIL 3.0 Language Profile.

Associating links with syntactic subparts

Below is an example with an integrated HTML file that displays a menu of

  link one
  link two

The user can click on one of the menu items, and the matching HTML file is displayed. That is, if user clicks on "link one", the "Link1.html" file is displayed in the "LinkText" region. Note that the links defined inside the embedded HTML presentation, those to "overridden1.html" and "overridden2.html" are not active when embedded here because they are overridden by the fragments.

The "menu.html" file contains the code:

<html>
...
   <A NAME="link1" HREF="overridden1.html">link one</A><BR/>
   <A NAME="link2" HREF="overridden2.html">link two</A>

The SMIL 3.0 file is:

   <smil xmlns="http://www.w3.org/2006/SMIL30/Language">
    <head>
      <layout>
        <region id="HTML"     width="100" height="100"/>
        <region id="LinkText" width="100" top   ="100"/>
      </layout>
    </head>
    <body>
      <par>
        <text region="HTML" src="menu.html" dur="indefinite">
          <area fragment="link1" href="#LinkOne"/>
          <area fragment="link2" href="#LinkTwo"/>
        </text>
        <excl dur="indefinite" >
          <text id="LinkOne" region="LinkText" src="Link1.html" dur="indefinite"/>
          <text id="LinkTwo" region="LinkText" src="Link2.html" dur="indefinite"/>
        </excl>
      </par>
    </body>
  </smil>

6.10 Integrating access and role into SMIL 3.0

This section is informative.

The intention for SMIL 3.0 is to incorporate the XHTML access and role attributes into SMIL. This is expected to result in the deprecation or removal of the accesskey attribute and the accesskey event from the SMIL language. Unfortunately, such a change brings with it some substantial semantic problems.

The SMIL 2.1 accesskey attribute was modelled after HTML, with some modifications because of the SMIL layout model and the SMIL timing model:

XHTML 2.0 took the HTML selection model and abstracted it on two levels:

Together, this allows for enumerating the keypresses used which means the devices missing a specific key can remap it. More importantly, end users can override or extend the mapping so that the can always use a self-selected keypress to focus on a specific role in any document.

Unfortunately, the SMIL 2.1 and XHTML 2.0 models are difficult to unify. The XHTML 2.0 model would be useful in SMIL: a SMIL document will often have sections that correspond to the XHTML roles. But due to a SMIL document being temporally organized this means that a keypress corresponding to "select navigation section" would have all sorts of temporal consequences. The issues to be solved here are similar to the way hyperlinks are handled in SMIL.

A more difficult issue is the existence of multiple items with the same role. XHTML deals with predominantly static documents, so it does not have to deal with this issue. In SMIL, however, a document has a timeline that can be long-lived so the same role can be filled by different elements at different times. Selecting the most appropriate element with a given role is at best non-trivial, at worst impossible.

Related to this is the fact that the XHTML model seems to miss functionality customarily provided by current accessible SMIL-based software: Daisy book readers often have keyboard shortcuts for navigating to the next or previous phrase, paragraph, chapter, etc. The Daisy standard prescribes a very specific structure for SMIL documents to enable this behaviour. Integration of access and role into SMIL should take this use case into account.

Finally the existing SMIL 2.0 functionality, allowing objects in the SMIL presentation to listen for keypresses and perform some action, has completely different but useful semantics. And allowing both models to coexist in the same document will lead to rather complex precedence rules.

This issue is under active discussion within the SYMM working group. Comments are welcome.

7. The SMIL 3.0 Media Object Modules

Editor for SMIL 3.0
Dick Bulterman, CWI
Editor for SMIL 2.0
Dick Bulterman, CWI
Rob Lanphier, RealNetworks.

7.1 Changes for SMIL 3.0

This section is informative.

There are two major changes to the Media Object modules for SMIL 3.0: the first is the addition of new attributes to the MediaParam module for chroma key and opacity control, the second is the introduction of the MediaPanZoom module. The MediaParam module is extended to define control over various aspects of media opacity using the mediaOpacity, mediaBackgroundOpacity, chromaKey, chromaKeyValue, and chromaKeyTolerance attributes. The MediaPanZoom module defines the viewBox attribute to provide a framework for panning and zooming over media content. (The viewBox attribute is based largely on equivalent functionality in SVG.)

The MediaParam module also includes new text that explicitly discusses the behavior of adding the various media control attributes defined in that section a SMIL layout region definition as a means of providing a global mechanism for applying default attribute settings to all content rendered within that region.

A number of editorial changes have also been integrated into the various Media Object modules descriptions; these do not impact the functionality defined in earlier versions of SMIL.

7.2 Introduction

This section is informative.

This section defines the SMIL media object modules, which are composed of a BasicMedia module and seven modules with additional functionality that build on top of the BasicMedia module: the MediaClipping, MediaClipMarkers, MediaParam, MediaAccessibility, MediaDescription, and MediaPanZoom modules. These modules contain elements and attributes used to describe media objects. Additionally, a BrushMedia element is provided which can be used as a media object. Since these elements and attributes are defined in a series of modules, designers of other markup languages can reuse the SMIL media module when they need to include media objects into their language.

Changes with respect to the media object elements in SMIL 1.0 provide additional functionality that was brought up as requirements of the Working Group, and those differences are explained in Appendix A and Appendix B.

7.3 Definitions

This section is normative.

SMIL provides a number of timing-related concepts that are used to determine activation, duration and termination of media objects in a presentation. The temporal semantics of these concepts are discussed in the SMIL 3.0 Timing and Synchronization module.

Intrinsic Duration
The duration of a referenced media item based on the temporal properties of that item (defined next), without any explicit SMIL timing markup. Some media objects have a well-defined notion of implicit duration (such as a 7 second audio clip), while other object do not have well-defined duration (such as a string of plain text). In SMIL, the implicit duration for any media object that does not have a well-defined duration is set to be zero seconds. The implicit duration is used to calculate scheduling information; it is sometimes independent of the actual duration of a media object (such as with a live media stream or with an image with multiple internal frames when no particular duration can be derived by the SMIL scheduler). From a scheduling perspective, an object's intrinsic duration forms the basis for the simple duration of the object during presentation. This duration can be shortened or extended using SMIL timing markup.
Continuous Media
Media objects, such as stored audio or video files, for which there is a measurable and well-understood duration. For example, a five second audio clip is continuous media, because it has a well-understood duration of five seconds. Opposite of "discrete media". See also the definition of continuous media in the Timing module.
Discrete Media
Media objects, such as images or non-timed text data, that has no obvious duration. For example, a JPEG image is generally considered discrete media, because there's nothing in the file indicating how long the JPEG should be displayed. Opposite of "continuous media". See also the definition of discrete media in the Timing module.

The distinction between continuous and discrete media is sometimes arbitrary and may be SMIL renderer dependent. For example, animated images that do not have a well-defined duration (simply a repeating collection of frames) are classified for SMIL scheduling purposes as being discrete media; such objects have an intrinsic scheduling duration of zero seconds.

7.4 SMIL BasicMedia Module

This section is normative.

This module defines the baseline media functionality of a SMIL player.

7.4.1 Media Object Elements - ref, and its synonyms animation, audio, img, text, textstream and video

SMIL defines a single generic media object element that allows the inclusion of media objects into a SMIL presentation. Media objects are included by reference (using a URI).

ref
Generic media reference

In addition to the ref element, SMIL allows the use of the following set of synonyms:

animation
Animated vector graphics or other animated format
audio
Audio clip
img
Still image, such as PNG or JPEG
text
Text reference
textstream
A text document that includes timing information for the purpose of time-dependent rendering of portions of the text document.
video
Video clip

All of these media elements are semantically identical. When playing back a media object, the player must not derive the exact type of the media object from the name of the media object element. Instead, it must rely solely on other sources about the type, such as the type information communicated by a server or the operating system, or by using type information contained in the typeattribute.

Authors, however, should make sure that the group into which of the media object falls (animation, audio, img, video, text or textstream) is reflected in the element name. This is in order to increase the readability of the SMIL document. Some SMIL implementations may require the use of an element type that matches the information type of the object. When in doubt about the group of a media object, authors should use the generic "ref" element.

The animation element defined here should not be confused with the elements defined in the SMIL 3.0 Animation Module. The animation element defined in this module is used to include an animation (such as a vector graphics animation) by reference. This is in contrast to the elements defined in the Animation module, which provide an in-line syntax for the animation of attributes and properties of other elements.

Anchors and links can be attached to visual media objects, i.e. media objects rendered on a visual abstract rendering surface.

Attributes Definitions

Languages implementing the SMIL BasicMedia Module must define which attributes may be attached to media object elements. In all languages implementing the SMIL BasicMedia module, media object elements can have the following attributes:

src
The value of the src attribute is the [URI] of the media element, used for locating and fetching the associated media.

The attribute supports fragment identifiers and the '#' connector in the URI value. The fragment part is an id value that identifies one of the elements within the referenced media item. With this construct, SMIL 3.0 supports locators as currently used in HTML (that is, it uses locators of the form http://www.example.org/some/path#anchor1), with the difference that the values are of unique identifiers and not the values of "name" attributes. Generally speaking, this type of addressing implies that the target media is of a structured type that supports the concept of id, such as HTML or XML-based languages.

Note that this attribute is not required. A media object with no src attribute has an intrinsic duration of zero, and participates in timing just as any other media element. No media will be fetched by the SMIL implementation for a media element without a src attribute.

type
Content type of the media object referenced by the src attribute. The usage of this attribute depends on the protocol of the src attribute.
RTSP [RTSP]
The type attribute is used for purposes of content selection and when the type of the referenced media is not otherwise available. It may be overridden by the contents of the RTSP DESCRIBE response or by the static RTP payload number.
HTTP [HTTP]
The type attribute is used for an alternative method of content selection and when the type of the referenced media is not otherwise available. It may override the contents of the "Content-type" field in an HTTP exchange only if a user has allowed such overrides, as specified in the TAG Finding Authoritative Metadata [AM]. The nominal precedence order for type resolution is: via the HTTP content-type field, via the type attribute, and then by using other clues (such as file inspection or use of the file extension).
FTP [FTP] and local file playback URL [URI]
The type attribute value takes precedence over other possible sources of the media type (for instance, the file extension).

When the content represented by a URL is available in many data formats, implementations MAY use the type value to influence which of the multiple formats is used. For instance, on a server implementing HTTP content negotiation, the client may use the type attribute to order the preferences in the negotiation. The type attribute is not intended for use in media sub-stream selection.

For protocols not enumerated in this specification, implementations should use the following rules: When the media is encapsulated in a media file and delivered intact to the SMIL user agent via a protocol designed for delivery as a complete file, the media type as provided by this protocol should take precedence over the type attribute value. For protocols which deliver the media in a media-aware fashion, such as those delivering media in a manner using or dependent upon the specific type of media, the application of the type attribute is not defined by this specification.

Element Content

Languages utilizing the SMIL BasicMedia module must define the complete set of elements which may act as children of media object elements. There are currently no required children of a media object defined in the BasicMedia Module, but languages utilizing the BasicMedia module may impose requirements beyond this specification.

7.4.2 Integration Requirements

If the including profile supports the XMLBase functionality [XMLBase] , the values of the src and longdesc attributes on the media object elements must be interpreted in the context of the relevant XMLBase URI prefix.

User-agents implementations are responsible for defining the rendering behavior when fragment addressing is used in the src attribute. Such definition should be added to language profiles that wish to include specific media addressing features. For example:
- User-agents should define the default behavior for when referencing a non-existing id in the target media document.
- User-agents should define the rendering method for the selected media fragment: in context, with or without highlighting and scrolling, or stand-alone (selective rendering only).
- User-agents should describe the timing implication for when addressing timed-content.

SMIL 3.0 allows but does not require user agents to be able to process XPointer values in the URI value of the src attribute. The SMIL 3.0 Linking Module provides additional information related to XPointer.

7.5 SMIL MediaParam Module

This section is normative.

This section defines the elements and attributes that make up the SMIL MediaParam Module definition. Languages implementing elements and attributes found in the MediaParam module must implement all elements and attributes defined below, as well as BasicMedia.

7.5.1 Media object initialization: the param element

The param element allows a general parameter value to be sent to a media object renderer as a name/value pair. This parameter is sent to the renderer at the time that the media object is processed by the scheduler. It is up to the media renderer to associate an action with the given param. The media renderer may choose to ignore any unknown or inappropriate param values (such as sending a font size to an audio object).

Any number of param elements may appear (in any order) in the content of a media object element or in a paramGroup element. If a given parameter is defined multiple times, the lexically last version of that parameter value should be used.

The syntax of names and values is assumed to be understood by the object's implementation. The SMIL specification does not specify how user agents should retrieve name/value pairs.

Attribute definitions
name
(CDATA) This attribute defines the name of a run-time parameter, assumed to be known by the inserted object. Whether the property name is case-sensitive depends on the specific object implementation.
value
(CDATA) This attribute specifies the value of a run-time parameter specified by name. Property values have no meaning to SMIL; their meaning is determined by the object in question.
valuetype
["data"|"ref"|"object"] This attribute specifies the type of the value attribute. Possible values:
  • data: This is default value for the attribute. It means that the value specified by value will be evaluated and passed to the object's implementation as a string.
  • ref: The value specified by value is a URI [URI] that designates a resource where run-time values are stored. This allows support tools to identify URIs given as parameters. The URI must be passed to the object as is, i.e., unresolved.
  • object: The value specified by value is an identifier that refers to a media object declaration in the same document. The identifier must be the value of the id attribute set for the declared media object element.
type
This attribute specifies the content type of the resource designated by the value attribute only in the case where valuetype is set to "ref". This attribute thus specifies for the user agent, the type of values that will be found at the URI designated by value. See 6.7 Content Type in [HTML4] for more information.

Example

This section is informative.

To illustrate the use of param: suppose that we have a facial animation plug-in that is able to accept different moods and accessories associated with characters. These could be defined in the following way:
<ref src="http://www.example.com/herbert.face">
  <param name="mood" value="surly" valuetype="data"/>
  <param name="accessories" value="baseball-cap,nose-ring" valuetype="data"/>

</ref>

7.5.2 The paramGroup element

The paramGroup element provides a convenience mechanism for defining a collection of media parameters that may be reused with several different media objects. If present, the paramGroup element must appear in the head section of the document. The content of the paramGroup element consists of zero or more param elements. The paramGroup element may not contain nested paramGroup element definitions.

Element attributes

id
This attribute specifies the ID by which the param group is referenced in a media object reference.

Examples

This section is informative.

This section contains several fragments that illustrate uses of the paramGroup element.

In the following fragment, a paramGroup is created to define parameters that are passed to several different media objects:

<smil ... >
  <head>
    ...
    <paramGroup id="clown">
       <param name="mood" value="upBeat" valuetype="data"/>
       <param name="accessories" value="flowers,dunceCap"/>
    </paramGroup>
    ...
  </head>
  <body>
    ...
    <ref src="http://www.example.com/andy.face" paramGroup="clown"/>
    ...
    <ref src="http://www.example.com/sally.face" paramGroup="clown"/>
    ...
  </body>
</smil>

In the following example, a media object provides an additional param value:

<smil ... >
  <head>
    ...
    <paramGroup id="clown">
       <param name="mood" value="upBeat" valuetype="data"/>
       <param name="accessories" value="flowers,dunceCap"/>
    </paramGroup>
    ...
  </head>
  <body>
    ...
    <ref src="http://www.example.com/andy.face" paramGroup="clown">
      <param name="gender" value="male"/>
    </ref>
    ...
  </body>
</smil>

In this final example, a media object provides a duplicate param value. The behavior in this case depends on the media renderer; all param values are passed to the renderer in the lexical order of the SMIL source file. It is expected that the lexically last value for any parameter sent to the renderer be used, if possible.

<smil ... >
  <head>
    ...
    <paramGroup id="clown">
       <param name="mood" value="upBeat" valuetype="data"/>
       <param name="accessories" value="flowers,dunceCap"/>
    </paramGroup>
    ...
  </head>
  <body>
    ...
    <ref src="http://www.example.com/andy.face" paramGroup="clown">
      <param name="gender" value="male"/>
      <param name="mood" value="depressed" valuetype="data"/>
    </ref>
    ...
  </body>
</smil>

7.5.3 Element Attributes for All Media Objects

In addition to the element attributes defined in BasicMedia, media object elements and layout regions man have the attributes and attribute extensions defined below. The inclusion or exclusion of these elements is left as an option in the language profile.

chromaKey
This attribute defines the color to be used for chroma key opacity manipulation. It accepts a single color value. The specification of a value for this attribute also sets the effective value of the chromaKeyOpacity attribute to 0%. If media objects or implementations cannot support manipulation of the chroma key value, this attribute is ignored. If this attribute is defined on a SMIL layout region definition, it specifies a default value for all content displayed within that region.
chromaKeyOpacity
This attribute defines the opacity of the chroma key value defined with the chromaKey attribute. It accepts a percentage value in the range 0-100%, with 100% meaning fully opaque. If no chroma key color was defined or if implementations cannot support manipulation of the media opacity value, this attribute is ignored. The default value of this attribute is 100%. If this attribute is defined on a SMIL layout region definition, it specifies a default value for all content displayed within that region.
chromaKeyTolerance
This attribute defines a color value that specifies a tolerance value that is added and subtracted from the effective chroma key. If no chroma key color was defined or if implementations cannot support manipulation of the chroma key values, this attribute is ignored. The default value of this attribute is #000000. If this attribute is defined on a SMIL layout region definition, it specifies a default value for all content displayed within that region.
erase
Controls the behavior of the media object after the effects of any timing are complete. For example, when SMIL Timing is applied to a media element, erase controls the display of the media when the active duration of the element and when the freeze period defined by the fill attribute is complete (see SMIL Timing and Synchronization module). If this attribute is defined on a SMIL layout region definition, it specifies a default value for all content displayed within that region.

Values:

whenDone (default)
When this is specified (or implied) the media removal occurs at the end of any applied timing.
never
When this value is specified, the last state of the media is kept displayed until the display area is reused (or if the display area is already being used by another media object). Any profile that integrates this element must define what is meant by "display area" and further define the interaction. Intrinsic hyperlinks (e.g., Flash, HTML) and explicit hyperlinks (e.g., area, a) stay active as long as the hyperlink is displayed. If timing is re-applied to an element, the effect of the erase=never is cleared. For example, when an element is restarted according to the SMIL Timing and Synchronization module, the element is cleared immediately before it restarts.

Example:

This section is informative.

<par>
  <seq>
    <par>
      <img src="image1.jpg" region="foo1" fill="freeze" erase="never" .../>
      <audio src="audio1.au"/>        
    </par>

    <par>
      <img src="image2.jpg" region="foo2" fill="freeze" erase="never" .../>
      <audio src="audio2.au"/>        
    </par>
     ...
    <par>
      <img src="imageN.jpg" region="fooN" fill="freeze" erase="never" .../>
      <audio src="audioN.au"/>        
    </par>
  </seq>
</par>

In this example, each image is successively displayed and remains displayed until the end of the presentation.

mediaOpacity
This attribute defines the opacity of the media object. It accepts a percentage value in the range 0-100%, with 100% meaning fully opaque. If implementations cannot support manipulation of the media opacity value, this attribute is ignored. The default value of this attribute is 100%. If this attribute is defined on a SMIL layout region definition, it specifies a default value for all content displayed within that region.
mediaBackgroundOpacity
This attribute defines the background color opacity of the media object for media objects that explicitly define a media background color. It accepts a percentage value in the range 0-100%, with 100% meaning fully opaque. If either media objects or implementations cannot support manipulation of the media background color opacity, this attribute is ignored. The default value of this attribute is 100%. If this attribute is defined on a SMIL layout region definition, it specifies a default value for all content displayed within that region.
mediaRepeat
Used to strip the intrinsic repeat value of the underlying media object. The interpretation of this attribute is specific to the media type of the media object, and is only applicable to those media types for which there is a definition of a repeat value found in the media type format specification. Media type viewers used in SMIL implementations will need to expose an interface for controlling the repeat value of the media for this attribute to be applied. For all media types where there is an expectation of interoperability between SMIL implementations, there should be a formal specification of the exact repeat value to which the mediaRepeat attribute applies. If this attribute is defined on a SMIL layout region definition, it specifies a default value for all content displayed within that region.

Values:

strip
Strip the intrinsic repeat value of the media object.
preserve (default)
Leave the intrinsic repeat value of the media object intact.

As an example of how this would be used, many animated GIFs intrinsically repeat indefinitely. The application of mediaRepeat= "strip" allows an author to remove the intrinsic repeat behavior of an animated GIF on a per-reference basis, causing the animation to display only once, regardless of the repeat value embedded in the GIF.

When mediaRepeat is used in conjunction with SMIL Timing Module attributes, this attribute is applied first, so that the repeat behavior can then be controlled with the SMIL Timing Module attributes such as repeatCount and repeatDur.

paramGroup
Used to specify the name of a paramGroup that was defined in the document head. The value is a single NMTOKEN that refers to the ID of a paramGroup element. If the named paramGroup does not exist, this attribute is ignored. If this attribute is defined on a SMIL layout region definition, it specifies a default value for all content displayed within that region.
sensitivity
Used to provide author control over the sensitivity of media to user interface selection events, such as the SMIL 2.1 activateEvent, and hyperlink activation. If the media is sensitive at the event location, it captures the event, and will not pass the event through to underlying media objects.  If not, it allows the event to be passed through to any media objects lower in the display hierarchy. If this attribute is defined on a SMIL layout region definition, it specifies a default value for all content displayed within that region.

Values:

opaque
The media is sensitive to user interface selection events over the entire area of the media.  This is the default.
transparent
The media is not sensitive to user interface selection events over the entire area of the media. Any user interface selection events will be "passed through" to any underlying media.
percentage-value
The media sensitivity to user interface selection events is dependent upon the opacity of the media at the location of the event (the alpha channel value). If rendered media supports an alpha channel and the opacity of the media is less than the given percentage value at the event location, the behavior will be transparent as specified above. Otherwise the behavior will be as opaque. Valid values are non-negative CSS2 percentage values.

7.5.4 Integration Requirements

Any profile that integrates the erase attribute must define what is meant by "display area" and further define the interaction. See the definition of erase for more details.

The supported uses of the type and valuetype attributes on the param element must be specified by the integrating profile. If a profile does not specify this, the type and valuetype attributes will be ignored in that profile.

7.6 SMIL MediaClipping Module

This section is normative.

This section defines the attributes that make up the SMIL MediaClipping Module definition. Languages implementing the attributes found in the MediaClipping module must implement the attributes defined below, as well as BasicMedia.

7.6.1 MediaClipping Attributes

clipBegin (clip-begin)
The clipBegin attribute specifies the beginning of a sub-clip of a continuous media object as offset from the start of the media object. This offset is measured in normal media playback time from the beginning of the media.
Values in the clipBegin attribute have the following syntax:
Clip-value-MediaClipping ::= [ Metric "=" ] ( Clock-val | Smpte-val )
Metric            ::= Smpte-type | "npt" 
Smpte-type        ::= "smpte" | "smpte-30-drop" | "smpte-25"
Smpte-val         ::= Hours ":" Minutes ":" Seconds 
                      [ ":" Frames [ "." Subframes ]]
Hours             ::= Digit+ 
                  /* see XML 1.0 for a definition of ´Digit´*/
Minutes           ::= Digit Digit; range from 00 to 59
Seconds           ::= Digit Digit; range from 00 to 59

Frames            ::= Digit Digit; smpte range = 00-29, smpte-30-drop range = 00-29, smpte-25 range = 00-24
Subframes         ::= Digit Digit; smpte range = 00-01, smpte-30-drop range = 00-01, smpte-25 range = 00-01
      
      

Informative Note: The definition of Subframe value in timecode introduces an inconsistency between SMIL 1.0 and SMIL 2.1.
At this time of revision, as some documents may have already been written using this Subframe value we have decided not to delete it from the Recommendation.
User agent should ignore subframe. Subframe should not be used as it is deprecated.The value of this attribute consists of a metric specifier, followed by a time value whose syntax and semantics depend on the metric specifier.

The value of this attribute consists of a metric specifier, followed by a time value whose syntax and semantics depend on the metric specifier. The following formats are allowed:

SMPTE Timestamp
SMPTE time codes [SMPTE] can be used for frame-level access accuracy. The metric specifier can have the following values:
smpte
smpte-30-drop
These values indicate the use of the "SMPTE 30 drop" format (approximately 29.97 frames per second), as defined in the SMPTE specification (also referred to as "NTSC drop frame"). The "frames" field in the time value can assume the values 0 through 29. The difference between 30 and 29.97 frames per second is handled by dropping the first two frame indices (values 00 and 01) of every minute, except every tenth minute.
smpte-25
The "frames" field in the time specification can assume the values 0 through 24. This corresponds to the PAL standard as noted in [SMPTE]

The time value has the format hours:minutes:seconds:frames.subframes. If the subframe value is zero, it may be omitted. Subframes are measured in one-hundredths of a frame.
Examples:
clipBegin="smpte=10:12:33"

Normal Play Time
Normal Play Time expresses time in terms of SMIL clock values. The metric specifier is "npt", and the syntax of the time value is identical to the syntax of SMIL clock values.
Examples:
clipBegin="npt=123.45s"
clipBegin="npt=12:05:35.3
"
Marker
Not defined in this module. See clipBegin Media Marker attribute extension in the MediaClipMarkers module.

If no metric specifier is given, then a default of "npt=" is presumed.

When used in conjunction with the timing attributes from the SMIL Timing Module, this attribute is applied before any SMIL Timing Module attributes.

clipBegin may also be expressed as clip-begin for compatibility with SMIL 1.0. Software supporting the SMIL 2.1 Language Profile must be able to handle both clipBegin and clip-begin, whereas software supporting only the SMIL MediaClipping module only needs to support clipBegin. If an element contains both a clipBegin and a clip-begin attribute, then clipBegin takes precedence over clip-begin.

Example:

<audio src="radio.wav" clip-begin="5s" clipBegin="10s" />

The clip begins at second 10 of the audio, and not at second 5, since the clip-begin attribute is ignored. A strict SMIL 1.0 implementation will start the clip at second 5 of the audio, since the clipBegin attribute will not be recognized by that implementation. See Changes to SMIL 1.0 Media Object Attributes for more discussion on this topic.

clipEnd (clip-end)
The clipEnd attribute specifies the end of a sub-clip of a continuous media object as offset from the start of the media object. This offset is measured in normal media playback time from the beginning of the media. It uses the same attribute value syntax as the clipBegin attribute.
If the value of the clipEnd attribute exceeds the duration of the media object, the value is ignored, and the clip end is set equal to the effective end of the media object. clipEnd may also be expressed as clip-end for compatibility with SMIL 1.0. Software supporting the SMIL 2.1 Language Profile must be able to handle both clipEnd and clip-end, whereas software supporting only the SMIL media object module only needs to support clipEnd. If an element contains both a clipEnd and a clip-end attribute, then clipEnd takes precedence over clip-end. When used in conjunction with the timing attributes from the SMIL Timing Module, this attribute is applied before any SMIL Timing Module attributes.

See Changes to SMIL 1.0 Media Object Attributes for more discussion on this topic.

7.7 SMIL MediaClipMarkers Module

This section is normative.

This section defines the attribute extensions that make up the SMIL MediaClipMarkers Module definition. Languages implementing elements and attributes found in the MediaClipMarkers module must implement all elements and attributes defined below, as well as BasicMedia and MediaClipping.

7.7.1 MediaClipMarkers Attribute Extensions

clipBegin Media Marker attribute extension
Used to define a clip using named time points in a media object, rather than using clock values or SMPTE values. The metric specifier is "marker", and the marker value is a URI (see [URI] ). The URI is relative to the src attribute, rather than to the document root or the XML base of the SMIL document.

Clip-value-MediaClipMarkers ::= Clip-value-MediaClipping |
                      "marker" "=" URI-reference
   /* "URI-reference" is defined in  [URI]  */

Example: Assume that a recorded radio transmission consists of a sequence of songs, which are separated by announcements by a disk jockey. The audio format supports marked time points, and the begin of each song or announcement with number X is marked as songX or djX respectively. To extract the first song using the "marker" metric, the following audio media element can be used:

<audio clipBegin="marker=#song1" clipEnd="marker=#dj1" />
clipEnd Media Marker attribute extension
clipEnd media markers use the same attribute value syntax as the clipBegin media marker extension media marker attribute extension. For the complete description, see clipBegin media marker extension.

7.8 SMIL BrushMedia Module

This section is normative.

This section defines the elements and attributes that make up the SMIL BrushMedia Module definition. Languages implementing elements and attributes found in the BrushMedia module must implement all elements and attributes defined below.

7.8.1 The brush element

The brush element is a lightweight media object element which allows an author to paint a solid color or other pattern in place of a media object. Thus, all attributes associated with media objects may also be applied to brush. Since all information about the media object is specified in the attributes of the element itself, the src attribute is ignored, and thus is not required.

Attribute definitions
color
The use and definition of this attribute are identical to the "background-color" property in the CSS2 specification.

7.8.2 Integration Requirements

Profiles including the BrushMedia module must provide semantics for using a color attribute value of inherit on the brush element. Because inherit doesn't make sense in all contexts, a profile may choose to prohibit the use of this value. The value of inherit is prohibited on the color attribute of the brush element for profiles that do not otherwise define these semantics.

7.9 SMIL MediaAccessibility Module

This section is normative.

This section defines the elements and attributes that make up the SMIL MediaAccessibility Module definition. Languages implementing elements and attributes found in the MediaAccessibility module must implement all elements and attributes defined below, as well as MediaDescription.

7.9.1 MediaAccessibility Attributes

Attribute definitions
alt
For user agents that cannot display a particular media object, this attribute specifies alternate text. alt may be displayed in addition to the media, or instead of media when the user has configured the user agent to not display the given media type.

It  is strongly recommended that all media object elements have an "alt" attribute with a brief, meaningful description. Authoring tools should ensure that no element can be introduced into a SMIL document without this attribute.

The value of this attribute is a CDATA text string.

longdesc
This attribute specifies a link ([URI] ) to a long description of a media object. This description should supplement the short description provided using the alt attribute or the abstract attribute. When the media object has associated hyperlinked content, this attribute should provide information about the hyperlinked content.

readIndex
This attribute specifies the position of the current element in the order in which longdesc, title and alt text are read aloud by assistive devices (such as screen readers) for the current document. User agents should ignore leading zeros. The default value is 0.

Elements that contain alt, title or longdesc attributes are read by the assistive technology according to the following rules:

  • Those elements that assign a positive value to the readindex attribute are read out first. Navigation proceeds from the element with the lowest readindex value to the element with the highest value. Values need not be sequential nor must they begin with any particular value. Elements that have identical readindex values should be read out in the order they appear in the character stream of the document.
  • Those elements that assign it a value of "0" are read out in the order they appear in the character stream of the document.
  • Elements in a switch statement that have test-attributes which evaluate to "false" are not read out.

Example

<par>
  <video id="carvideo" src="car.rm" region="videoregion" title="Car video"
         alt="Illustration of relativistic time dilation and length 
              contraction." 
         longdesc="carvideodesc.html" readIndex="3"/>
  <audio id="caraudio" src="caraudio.rm" region="videoregion" 
         title="Car presentation voiceover" begin="bar.begin"/>
  <animation id="cardiagram" src="car.svg" region="animregion" 
         title="Diagram of the car" readIndex="2"/>
  <img id="scvad" src="scv.png" region="videoregion" 
         title="Advertisement for Sugar Coated Vegetables"
         readIndex="1"/>
</par>

In this example, an assistive device that is presenting titles should present the "scvad" element title first (having the lowest readIndex value of "1"), followed by the "cardiagram" title, followed by the "carvideo" element title, and finally present the "caraudio" element title (having an implicit readIndex value of "0").

7.10 SMIL MediaDescription Module

This section is normative.

This section defines the elements and attributes that make up the SMIL MediaDescription Module definition. Languages implementing elements and attributes found in the MediaDescription module must implement all elements and attributes defined below.

7.10.1 MediaDescription Attributes

Attribute definitions
abstract
A brief description of the content contained in the element. Unlike alt, this attribute is generally not displayed as alternate content to the media object. It is typically used as a description when table of contents information is generated from a SMIL presentation, and typically contains more information than would be advisable to put in an alt attribute.

This attribute is deprecated in favor of using appropriate SMIL metadata markup in RDF. For example, this attribute maps well to the "description" attribute as defined by the Dublin Core Metadata Initiative [DC] .

author
The name of the author of the content contained in the element.

The value of this attribute is a CDATA text string.

copyright
The copyright notice of the content contained in the element.

The value of this attribute is a CDATA text string.

title
The title attribute as defined in the SMIL Structure module. It is strongly recommended that all media object elements have a title attribute with a brief, meaningful description. Authoring tools should ensure that no element can be introduced into a SMIL document without this attribute.
xml:lang
Used to identify the natural or formal language for the element. For a complete description, see section 2.12 Language Identification of [XML11].

xml:lang differs from the system-language test attribute in one important respect. xml:lang provides information about the content's language independent of what implementations do with the information, whereas system-language is a test attribute with specific associated behavior (see system-language in SMIL Content Control Module for details)

7.11 MediaPanZoom Module

This section is normative.

7.11.1 Changes for SMIL 3.0

This section is informative.

The MediaPanZoom module contains attributes that have been added as part of the SMIL 3.0 release. These attributes, based largely on equivalent functionality in SVG, provide a framework for panning and zooming over media content via the viewBox attribute.

7.11.2 Overview

This section is informative.

The SMIL MediaPanZoom module integrates the functionality of the SVG viewBox attribute and adapts it for use within the SMIL layout framework. The SMIL viewBox attribute allows a SMIL author to define a two-dimensional extent over the visible surface of a media object and to subsequently project the contents within the viewBox into a SMIL layout region.

Most of SMIL's layout elements and attributes provide the ability to define and manage a two-dimensional rendering space. This space is defined relative to a root_layout (or topLayout) specification. All of the coordinate and size specifications are in terms of the coordinate space defined for the layout root. In contrast, the viewBox attribute allows users to define an area in terms of the coordinate space used by the media object that is associated with the viewBox. The viewBox may define an area that is smaller, equal to, or larger than the related media object.

The following illustration shows three views of a 300x200 pixel image. In the left view, a viewBox is shown that is the same size as the media object; in the middle view, a viewBox is defined that covers the middle part of the image only; in the right view, a viewBox is illustrated that is positioned (in both dimensions) partially outside the media object. Note that while this illustration shows the viewBox projected onto an image, similar illustrations could be defined for videos or text objects, or any other object that can be mapped to a particular media bounding box.

Picture showing a base image and three viewBox examples

Once a portion of a media object's visible area is defined with a viewBox, the portion within the viewBox is processed further by SMIL layout as if it defined the full native view of the media object. The area within the viewBox is projected into a region in a manner that is dependent on the region element associated with that object, including any scaling dictated by the fit attribute or (if appropriate), sub-regions positioning and alignment directives.

If the region and the viewBox have the same aspect ratios, then the viewBox will, by default, fill the entire region. If the effective pixel dimensions of the region are larger then that of the viewBox, the effect will be an enlargement of the media content. If the effective pixel dimensions of the window are smaller than that of the viewBox, the effect will be a reduction in size of the media object. Other effects can be obtained by manipulating the fit attribute of the region.

If supported by the profile implementing this module, a dynamic pan-and-zoom effect can be obtained by applying standard SMIL animation primitives to the dimensions of the viewBox. A pan effect may be obtained by varying the X and Y positioning values, and a zoom effect can be obtained by changing the size dimensions of the viewBox. Examples of these effects are given later in this section.

If a viewBox extends past the viewable extents of a media object (such as in the rightmost illustration, above), then the effective contents of these extended areas will be transparent.

7.11.3 Elements and Attributes for the MediaPanZoom Module

This section is normative.

This module does not define any new elements. It provides extensions to the ref element (and its synonyms), and to the region element.

The ref Element

The viewBox attribute is added to media object references.

Element attributes
viewBox
This attribute specifies a rectangular area in media coordinates that defines the portion of that media object that is to be used in rendering object content into a SMIL region. The value of the viewBox attribute is an ordered list of four numbers, separated by whitespace and/or a comma:
min-x
A value that defines the minimum X coordinate of a rectangle in media space that serves as the X origin of the viewBox. A value of '0' represents the left edge of the media object.
min-y
A value that defines the minimum Y coordinate of a rectangle in media space that serves as the Y origin of the viewBox. A value of '0' represents the top edge of the media object.
width
A non-negative length value (using CSS2 pixel or non-negative percentage values) that defines the horizontal dimension of the viewBox. If pixel notation is used, the 'px' suffix may be omitted. A negative value is an error. The default value of width is auto.
height
A non-negative length value (using CSS2 pixel or non-negative percentage values) that defines the vertical dimension of the viewBox. If pixel notation is used, the 'px' suffix may be omitted. A negative value is an error. The default value of height is auto.
The default viewBox behavior is to select the entire visual space of the media object; this is equivalent to viewBox="0, 0, 100%, 100%".

The viewBox is processed on the media object before any other SMIL layout processing occurs. The actual visual rendering of the content resulting from the processed viewBox will be determined by, among other factors, the size of the target region, the application of sub-region positioning in that region (if supported by the profile), the value of the fit attribute on the region and the effect of SMIL alignment attributes (if supported by the profile).

Element content

The SMIL MediaPanZoom module does not extend the content model for the ref element integrating these attributes.

The region Element

The viewBox attribute is added to regions definitions.

Element attributes
viewBox
This attribute is identical in definition to the viewBox attribute defined for the ref element in this section, with the exception that it defines a default viewBox that is applied to all media rendered in the associated region. All other aspects of viewBox processing are the same as with the ref element, except that the values defined for the viewBox on a region may be overridden by a viewBox specification on the ref element.
Element content

The SMIL MediaPanZoom module does not extend the content model for the region element integrating these attributes.

Attribute Examples

This section is informative.

Assume the following SMIL example:

<smil ...>
  <head>
  ...
    <layout>
      <root-layout height="200" width="300" backgroundColor="red" />
      <region id="I" top="0" left="0" height="200" width="300"  backgroundColor="blue" />
    </layout>
  </head>
  <body>
    <seq> 
      <ref id="R0" src="table.jpg" viewBox="0,0,300,200" dur="5s" region="I" />
      <ref id="R1" src="table.jpg" viewBox="50,195,160,125" dur="5s" region="I" fit="meet"/>
      <ref id="R2" src="table.jpg" viewBox="50,195,160,125" dur="5s" region="I" fit="meetBest"/>
      <ref id="R3" src="table.jpg" viewBox="240,120,85,110" dur="5s" region="I" fit="meet"/>
    </seq>
  </body>
</smil>

In this example, a single region is defined that is used to display four instances of the same image. Each media reference within the sequence S contains a different viewBox definition, each of which will result in the following behavior:

  1. The media reference R1 defines a viewBox that encompasses the entire media object space; the full image will be shown in region I, as is shown in the following image:
    A viewBox projection that is the same size as the target region.
    Note that the origin of the image is aligned with the origin of the media object, at the top-left of the region.
  2. The media reference R2 defines a viewBox that encompasses the center portion of the media object space. The projection of the media into region I will result in a zoom into the source image, as is shown in the following image:
    A viewBox projection that is smaller than the target region, resulting in a zoom effect.

    Note that the origin of the sub-image defined by the viewBox is placed at the origin of the top-left of the region. Note also that the value of the fit attribute determines that the image is scale (while maintaining the aspect ratio), resulting in the zoom effect.

  3. The media reference R3 defines a viewBox that is the same as in reference R2; the difference in this example is that the value of the fit attribute does not permit enlargement of the source image into the region. As a result, the image is placed at top-left in an unscaled rendering:
    A viewBox projection that is smaller than the target region, but with a fit=
  4. The media reference R4 defines a viewBox that extends beyond the boundaries of the media object. When it is projected into the region I with a fit value that scales the image with preserved aspect ratio, it is the entire extent of the viewBox that is scaled: the areas that extend beyond the image content are rendered as (scaled) transparent content:
    A viewBox projection that extends beyond the right/bottom edge of the image -- the extended part of the box will be transparent.

All of the previous examples illustrate how a viewBox operates on a media object that contains a media-defined viewable extent. The viewBox attribute may also be applied to visual objects that do not have predefined extents. Consider the following example, in which an unstructured text object is placed in a region:

<smil ...>
  <head>
  ...
    <layout>
      <root-layout height="200" width="300" backgroundColor="red" />
      <region id="T" top="0" left="0" height="50" width="300"  backgroundColor="blue" />
    </layout>
  </head>
  <body>
    <seq> 
      <ref id="R0" src="short_story.txt" viewBox="0,10,50,200" dur="10s" region="T" />
    </seq>
  </body>
</smil>

In this example, a single region is defined that is used to display a undimensioned text object. In SMIL 3.0, the text object would first be rendered to an off-screen bitmap based on the default settings for the media object (font, font size, font color) and then a viewBox of the defined size would be overlaid on this text representation. This facility is especially useful when combined with SMIL Animation, as discussed in the next example.

EdNote: exact rendering behavior needs to be defined. My own feeling is that the ratio between width and height should determine whether the text is laid out horizontally or vertically, but this needs more thought.

The ability to define a viewBox, when combined with SMIL animation primitives, provides a simple mechanism for doing pan/zoom animations over a visual object. (These pan/zoom animations are often called 'Ken Burns' animations.) The following example illustrates how a pan window can be positioned and moved over an image area:

<smil ...>
  <head>
  ...
    <layout>
      <root-layout height="200" width="300" backgroundColor="red" />
      <region id="B" top="0" left="0" height="50" width="75"  backgroundColor="blue" />
    </layout>
  </head>
  <body>
    <seq> 
      <ref id="R0" src="table_233x150.jpg" viewBox="0,0,50,75" dur="20s" region="T" fit=""meet" >
         <animate attributeName="viewBox" 
                     values="(25,20,50,75); (45,55,50,75);(140,40,50,75);(35,0,100,150); (0,0,100,150);" 
                     dur="20s" />
      </ref>
      ...
    </seq>
  </body>
</smil>

In this example, a image with intrinsic size of 233x150 pixels is rendered into a region of size 50x75. An initial viewBox is defined that displays a 50x75 portion of that image, positioned in its top-left corner. During the following 20 seconds, the viewBox is moved across the image according to the behavior of the animate element; the viewBox changes are scheduled at equal points across the animation timeline (in this case, every 5 seconds). During the final animation, the viewBox is extended to implement a zoom-out across the entire image. An illustration of the rendering results is shown below:


A viewBox projection and a set of animations that move the viewBox across the source image.

7.11.4 MediaPanZoom Module Events

This section is normative.

This module does not define any SMIL events.

7.11.5 SMIL MediaPanZoom Implementation and Integration

This section is normative.

Implementation Details

The MediaPanZoom module allows individual media object references to override the default values for certain attributes. In all cases, the attributes will apply only to the (sub-)region referenced by the media object. Changes will not propagate to child sub-regions or to parent regions.

Integration Requirements

The functionality in this module builds on top of the functionality in the Media module, which is a required prerequisite for inclusion of the MediaPanZoom module.

Differences with the SVG viewBox Attribute

The functionality in this module builds on the viewBox definition of SVG. Unlike SVG, the SMIL viewBox attribute defines a logical sub-image that contains only content within the area defined by the viewBox; SVG uses the viewBox to define a minimum viewing dimension for content, but allowing content outside the viewBox to be displayed in the region.

The MediaPanZoom module does not define a preserveAspectRatio attribute, since this functionality is already provided by the SMIL fit and registration/alignment attributes.

7.11.6 Document Type Definition (DTD) for the MediaPanZoom Module

See the full DTD for the SMIL Layout modules.

7.12 Appendices

This section is informative.

7.12.1 Appendix A: Changes in SMIL 2.0 to SMIL 1.0 Media Object Attributes

clipBegin, clipEnd, clip-begin, clip-end

With regards to the clipBegin/clip-begin and clipEnd/clip-end elements, SMIL 2.1 defines the following changes to the syntax defined in SMIL 1.0:

Handling of new clipBegin/clipEnd syntax in SMIL 1.0 software

Using attribute names with hyphens such as clip-begin and clip-end is problematic when using a scripting language and the DOM to manipulate these attributes. Therefore, this specification adds the attribute names clipBegin and clipEnd as an equivalent alternative to the SMIL 1.0 clip-begin and clip-end attributes. The attribute names with hyphens are deprecated.

Authors can use two approaches for writing SMIL 2.1 presentations that use the new clipping syntax and functionality ("marker", default metric) defined in this specification, but can still can be handled by SMIL 1.0 software. First, authors can use non-hyphenated versions of the new attributes that use the new functionality, and add SMIL 1.0 conformant clipping attributes later in the text.

Example:

<audio src="radio.wav" clipBegin="marker=song1" clipEnd="marker=moderator1" 
       clip-begin="npt=0s" clip-end="npt=3:50" />

SMIL 1.0 players implementing the recommended extensibility rules of SMIL 1.0 [SMIL10] will ignore the clip attributes using the new functionality, since they are not part of SMIL 1.0. SMIL 2.1 players, in contrast, will ignore the clip attributes using SMIL 1.0 syntax, because the SMIL 2.1 syntax takes precedence over the SMIL 1.0 syntax.

The second approach is to use the following steps:

  1. Add a "system-required" test attribute to media object elements using the new functionality. The value of the "system-required" attribute would correspond to a namespace prefix whose namespace URI ([URI] ) points to a SMIL specification which integrates the new functionality.
  2. Add an alternative version of the media object element that conforms to SMIL 1.0
  3. Include these two elements in a "switch" element

Example:

<smil xmlns="http://www.w3.org/2006/SMIL30/WD/Language">
...
<switch>
  <audio src="radio.wav" clipBegin="marker=song1" clipEnd="marker=moderator1"  
   system-required="smil2" />
  <audio src="radio.wav" clip-begin="npt=0s" clip-end="npt=3:50" />
</switch>

New Accessibility Attributes

readIndex
Allows explicit ordering for controlling assistive technology.

New Advanced Media Attributes

mediaRepeat
The mediaRepeat attribute was added to provide better timing control over media with intrinsic repeat behavior (such as animated GIFs).
erase
Provides a way for visual media to remain visible throughout the duration of a presentation rather by overriding the default erase behavior.

7.12.2 Appendix B: Changes in SMIL 2.0 to SMIL 1.0 Media Object Elements

New child elements for media objects

SMIL 1.0 only allowed anchor as a child element of a media element. In addition to anchor (now defined in the Linking module), the param is now allowed as children of a SMIL media object. Additionally, other new children may also be defined by the host language.

The param and paramGroup elements

The param element provides a generalized mechanism to attach media-specific attributes to media objects. The paramGroup element provides a convenience grouping mechanism to collect commonly used param element definitions into a single unit that may be referenced by multiple media objects.

The brush element

A new brush element allows the specification of solid color media objects with no associated media.

8. The SMIL 3.0 SMILtext Modules

Editors for SMIL 3.0
Dick Bulterman, CWI
Sjoerd Mullender, CWI
Samuel Cruz-Lara, INRIA

8.1 Changes for SMIL 3.0

This section is informative.

This module defines new functionality for SMIL 3.0. It extends the media types available for SMIL, but does not alter any other existing functionality from SMIL 2.1 or earlier versions.

8.2 Open Issues in This Version

This section is informative.

The open issues at the time of writing this version of the SMILtext modules are:

8.3 Introduction

This section is informative.

The functionality described in these modules provide a new media type for use in SMIL presentations. This functionality is called SMILtext. Unlike other media types defined in the media object module, all of which are synonyms of the ref element, the SMILtext modules provide a text container element with an explicit content model for defining in-line text, and a set of additional elements and attributes to control explicit in-line text rendering. SMILtext content is processed in a manner consistent with other SMIL media. This means, among other aspects, that the SMILtext respects SMIL timing and layout behavior, including the semantics of the fit and fill attributes of SMIL Layout.

The SMILtext Modules are composed of a BasicText module and two modules with additional functionality that build on top of the BasicText module: the TextStyling and TextFlow modules. These modules contain elements and attributes used to define in-line text content. Since the SMILtext elements and attributes are defined in a series of modules, designers of other markup languages can reuse these modules when they need to include a simple form of timed text functionality into their language.

8.3.1 Motivation

The purpose of including text content functionality into SMIL 3.0 is to allow authors to define small amounts of (lightly-formatted) text within the context of a SMIL presentation. Such text can be used, among other things, for labels within a presentation or for incidental captions. Users who wish to use large amounts of structured text (with or without temporal markup) should consider the use of external text media objects encoded in formats such as XHTML or the DFXP profile of TimedText.

All versions of SMIL have had support for the text element, which is defined as an alias of the generic SMIL ref media reference element. A typical use of the text element is:

    <text region="Title" src="Headline.html" dur="10s" >

Users new to SMIL are often surprised that the text element does not have a content model -- that is, an ability to specify the content text along with the element, such as in:

    <text region="Title" dur="10s" >
       Willemijn's 11th Birthday Party
    </text>
 

More advanced users of SMIL found that they were able to insert in-line text content into the SMIL file using a data URL, such as:

    <text src="data:,Willemijn's%2011th%20Birthday%20Party" 
          region="Title" dur="10s" >
 

However, the strict syntax of this approach, plus the limited styling options available, make it a less-than-optimal way of including incidental text content into a SMIL presentation. A more author-friendly approach to text inclusion was a requirement for SMIL 3.0.

The implementation of SMIL on a wide range of devices, from set-top boxes and mobile devices to conventional desktop computers, means that care needed to be taken in defining the complexity of the SMILtext modules. The motivation of the SMIL's in-line text facility was not to provide complete support for all types of text, but to provide a balance between authoring convenience and player complexity. SMILtext was also designed to differentiate text styling from general layout and positioning so that SMILtext could be used efficiently with SMIL Layout. Both of these motivations, plus the desire to define a media facility that could be used across all of SMIL's implementation platforms, has resulted in a simple text specification that can meet many of the requirements for incidental text within a SMIL document.

SMILtext has been designed as a functional subset of the W3C Timed Text format DFXP. While users familiar with DFXP will recognize the functionality included in this specification, the differences in temporal and layout specifications between SMIL and DFXP have resulted in a slightly different syntax in the two languages. The SYMM working group has strived to minimize these differences. A complete list of differences between SMILtext and DFXP is presented in Appendix A.

8.3.2 The SMILtext Rendering Model

In order for text content to be compatible with the SMIL timing semantics, a general text processing model has been defined for SMILtext. In this model, text is classified as a discrete media type, with no inherent duration. All text content is processed as if it were first rendered to an off-screen bitmap; this bitmap is then used as the basis for inclusion into a SMIL presentation much as if it were an actual image. (There are some exceptions to this model; these are discussed in the Examples section of FlowModel module in this document.

The dimensions used in constructing the off-screen bitmap representation of SMILtext will depend on a number of factors. In general, the layout model used to define a drawing area for the text content will provide initial values for the extents of the text area. The default text-wrap behavior for SMILtext is to wrap the text content based on region width. In this case, the region will determine the text-area width and the text content will determine the effective off-screen bitmap height. If the wrap behavior is set to disallow automatic text wrapping (which is only possible if the TextStyle module is supported by the profile implementing SMILtext), the effective height is determined based on the number of lines of text (which in turn is determined by the number of manual line breaks created via the br element) and constrained by the region height, while the text content determines the off-screen bitmap width.

In most cases, content defined in a smilText element will define a new off-screen bitmap pseudo-image that will replace any existing content in the target region. If multiple smilText elements are active simultaneously and target the same layout region, the behavior is fully defined by the semantics of the SMIL timing model. Users of SMILtext are encouraged to study the examples at the end of each module description to better understand the impact of SMIL timing on text rendering with SMILtext.

8.4 SMIL 3.0 BasicText Module

This section is normative.

This section defines the elements and attributes that make up the functionality in the SMIL 3.0 BasicText module. Languages implementing elements and attributes found in the BasicText Module must implement all elements and attributes defined in this section.

8.4.1 Elements and Attributes

The SMIL 3.0 BasicText module defines two elements and one attribute which, together, provide basic support for in-line text within a SMIL presentation. The functionality provided by these elements and attributes represent the minimum level of text processing that can be required by a user agent implementing SMILtext.

The elements defined in this module are:

smilText
br

The attribute defined in this module is:

textWrapOption

In addition, this module extends the definition of the SMIL Layout region element to include the textWrapOption attribute.

For profiles that support only the BasicText module, all in-line text content styling and processing is defined and controlled by the SMIL user agent rendering the text. Additional content styling elements and attributes are defined in the TextStyling and TextFlow modules; support for this extended functionality is profile dependent.

The smilText Element

The smilText element functions as a logical and temporal structuring element that allows the inclusion of in-line text content into a SMIL presentation. When rendering in-line text, the smilText element provides a top-level container for timing semantics. No timing semantics may be defined on the content within the smilText element.

When text is rendered into an associated region, the existing contents of the region is replaced by the element content. The properties of the region will determine the extents of the rendering area and the clipping behavior of text placed in the region. The effective value of the textWrapOption attribute will determine if lines wrap if they are wider than the space provided. In-line text is considered to be rendered instanteously at the beginning of the simple duration of the text element. In SMILtext, extra white space between characters is ignored.

Anchors and links may be attached to content within the smilText element. In these cases, the syntax and semantics of SMIL Linking will be expected, including temporal attributes on anchors.

Element attributes

This element accepts the textWrapOption attribute, which will override the effective value for the attribute defined on the layout region. Profiles including the smilText element must define which other SMIL attributes may be attached to this element.

Element Content

The smilText element may contain character content. If this content is present, it will be rendered as text in a player-dependent fashion. If no content is present, the smilText element must still observe all SMIL timing properties.

The br Element

The br element functions as a forced line break within in-line content defined in a smilText element. The br element is only valid within as content of a smilText element and has no temporal semantics other than those of its parent smilText element.

Element attributes

This element does not accept any attributes.

Element content

This element has no content.

The textWrapOption Attribute

The textWrapOption attribute specifies whether text content that is larger than the effective space available on one line in a region wraps. This attribute may be used on the smilText element or as a default on the region element.

Values:

wrap (default)
Text is wrapped across lines within a region.
noWrap
Text is not wrapped across lines within a region.
inherit
The effective value of this attribute is used.

If this attribute is defined on the the smilText element, the text wrap option will be applied to all content visible within the region.

Examples

This section is informative.

General Use of SMILtext

The smilText element provides a temporal wrapper for in-line text:

    <smilText>
       Hello world!
    </smilText>

The smilText element is the equivalent of allowing a data URL that contains text content, such as: <ref src="data:,Hello world!" ... > .

In this simple form, the text will be rendered based on the default layout properties defined for the user agent. If SMIL Layout is used, the default behavior is: a dynamic region will be defined that contains the text content of the element. All styling information -- including font, font size, font style and font color -- will be determined by the SMIL player.

If the SMIL Layout BasicLayout module is also supported by the profile implementing this module, the rendering extent and the clipping behavior of the text rendered in a SMIL region will be determined by the effective value of SMIL's layout attributes.

<smil ...>
 <head>
   ...
   <layout>
     ...
     <region id="Title" top="5px" left="10%" width="80%" height="30px" />
     ...
   </layout>
  </head>
  <body>
   ...
    <smilText region="Title" dur"10s">
       Willemijn's 11th Birthday Party
    </smilText>
   ...
  </body>
</smil>

This is equivalent to specifying: <ref region="Title" src="data:,Hello world!" ... >. In both cases, the properties associated with the region named Title will be used when positioning the text.

If the rendering space for the content of the smilText element is greater than the horizontal extent of one line, the effective value of the textWrapOption attribute will determine whether content will be clipped or wrapped:

<smil ...>
 <head>
     ...
     <region id="Title" top="5px" left="10%" width="80%" height="30px" 
          textWrapOption="wrap"/>
     ...
  </head>
  <body>
   ...
    <smilText region="Title" dur"10s">
       Willemijn's 11th Birthday Party was held six weeks late. (Again!)
    </smilText>
   ...
  </body>
</smil>

Line breaks within SMILtext content may be forced by using the br element within text content:

   ...
    <smilText region="Title" dur"10s">
       Willemijn's 11th Birthday Party
was held six weeks late.
(Again!) </smilText> ... </body> </smil>
Timing Consequences of SMILtext

The following fragment illustrates use of basic SMILtext in a SMIL sequence:

 <smil ...>
  <head>
     ...
    <layout>
     <root-layout width="400" height="300"/>
      <region id="Contents" top="5px" left="10%" width="80%" height="300"/>
    </layout>
   </head>
   <body>
      ...
       <seq id="S0">
        <smilText id="TS01" region="Contents" dur="5s">
           Willemijn's 11th Birthday Party
        </smilText>
        <smilText id="TS02" region="Contents" begin="2s" dur="5s" fill="freeze">
           was held six weeks late.
        </smilText>
        <smilText id="TS03" region="Contents" begin="4s"  end="3s">
           (Again!)
        </smilText>
       </seq>
         ...
   </body>
 </smil>

The element TS01 starts the sequence and displays text for 5s. Since an explicit duration is declared, the text content will be removed from view after 5 seconds. Since element TS02 defines an explicit begin delay, the region containing the text will be empty for 2s. After this, TS02 will render the second text in the layout region for 5s. Element TS03 begins after a 4s delay, during which the content from TS02 remains visible because of an explicit fill="freeze". Finally, TS03 will be activated and removed after 3s.

The following example is used to illustrate SMILtext behavior when used with the SMIL parallel time container:

      ...
       <par id="P0">
        <smilText id="TP01" region="Contents" dur="10s">
           Willemijn's 11th Birthday Party
        </smilText>
        <smilText id="TP02" region="Contents" begin="2s" dur="7s" fill="freeze">
           was held six weeks late.
        </smilText>
        <smilText id="TP03" region="Contents" begin="4s"  end="3s">
           (Again!)
        </smilText>
       </par>
         ...

In this example, all three children of the parallel container P0 are activated together. Element TP01 starts with no begin delay and renders its text for 5s. After 2s, element TP02 begins and replaces the content displayed by TP01. After 2s (at a total of 4s into the parallel container), element TP03 starts, replacing the contents of the region with its text. Three seconds later, TP03 ends -- at this point, because of the explicit end time, the contents of TP03 are removed and replaced with those of TP02 (which is still active for another 2s.) When TP02 ends, TP02's text is not removed -- even though TP01 still has 1s of display time left -- because of the explicit fill value defined on TP02.

The most pertinent SMIL timing rules governing text with effective remove semantics are:

Layout and Rendering Consequences of SMILtext

In terms of visual behavior, the value of the fit attribute will determine clipping behavior of the text. Since not all user agents can be expected to dynamically scale plain text, fit="slice" will be the expected default behavior with basic SMILtext.

In terms of the rendering semantics defined in the TextFlow module, the only behavior defined by basic SMILtext is the replace text flow semantic.

8.4.2 Integration Requirements

If the including profile supports the XMLBase functionality [XMLBase] , the values of the longdesc attribute (of present) on the smilText element must be interpreted in the context of the relevant XMLBase URI prefix.

All of the attributes specified for media within the SMIL MediaParam module must be supported by implementations integrating this module.

8.5 SMIL 3.0 TextStyling Module

This section is normative.

This section defines the elements and attributes that make up the SMIL TextStyling Module. Languages implementing the elements and attributes in the TextStyling Module must implement all elements and attributes defined below, as well as those defined in the BasicText module.

8.5.1 Elements and Attributes

The TextStyling module defines the following three elements:

span
textStyle
textStyling

The TextStyling module defines the following eight attributes:

textAlign
textBackgroundColor
textColor
textDirection
textFontFamily
textFontSize
textFontWeight
textStyle

In addition, this module extends the definition of the SMIL Layout region element to include the TextStyling attributes listed above.

The span Element

The span element functions as a logical container for in-line formatting attributes defined within a smilText element. The span element may not be nested within another span element The span element is only valid within as content of a smilText element and has no temporal semantics other than those of its parent smilText element.

Element attributes

The span element may (re)specify values for any of the SMIL styling attributes defined in this module. All other attributes are ignored.

Element content

This element accepts as content zero or more characters to which the specified styling is applied. Any styling attributes changed within the scope of this element must be restored to their previous values outside the scope of this element.

The textStyle Element

The textStyle element is used to define a set of text style attributes in the document head section. The style group defined with this element may be used within a SMIL layout region to define default styles for text elements in that region, or within the smilText and span in-line content elements in a SMIL body section.

Element attributes

All of the styling attributes defined in this module (with the exception of the textStyle attribute) may be specified within a textStyle element in the head section. Note that if text style attributes are referenced on an element to which they do not apply, they are ignored. If multiple instances of the same styling attribute are defined, the value associated with the lexically-last instance are used.

In addition, this attribute defines:

IDREF
The ID of the textStyle definition.
Element content

This element has no content.

The textStyling Element

The textStyling element deliniates a set of textStyle elements in the document head section.

Element attributes

This attribute accepts no attributes.

Element content

This element contains one or more textStyle elements as children.

The textAlign Attribute

The textAlign attribute specifies how text is aligned within the region specified by the text element. This attribute may be used on the smilText element or as a default on the region element. The semantics of this attribute are a subset of those defined in XSL 1.1.

Values:

start (default)
The text is left-aligned in the region if the effective value of the textDirection attribute is ltr, or right-aligned otherwise.
end
The text is right-aligned in the region if the effective value of the textDirection attribute is ltr, or left-aligned otherwise.
left
The text is left-aligned in the region.
right
The text is right-aligned in the region.
center
The text is centered in the region.
inherit
The effective value defined for the region is used.

If this attribute is defined on the the smilText element, the new alignment mode will be applied to all text displayed in the region.

The textBackgroundColor Attribute

The textBackgroundColor attribute is identical to the "background-color" property in the XSL 1.1 specification. As such, support for CSS2 system colors is required. This attribute specifies the background color used to fill the area around text content that falls within a player-defined bounding box. This attribute may be used on the smilText element, on the span element or as a default on the region element.

Values:

CSS2 color specification
The textBackgroundColor attribute may take on the CSS value inherit. This means that the background color used for text will be that of the backgroundColor attribute defined for the region specified by the parent text element. If no color has been specified, the default is transparent.

If this attribute is defined on the the smilText or span elements, the new background color will be applied only to the content within the scope of that element.

The textColor Attribute

The textColor attribute is identical to the "color" property in the XSL 1.1 specification. As such, support for CSS2 system colors is required. This attribute specifies the color used to render text content in the region specified by the parent text element. This attribute may be used on the smilText element, on the span element or as a default on the region element.

Values:

CSS2 color specification
The textColor attribute may take on the CSS value inherit. This means that the color used for text will be that of the color attribute defined for the region specified by the parent text element. If no color has been specified, the default is transparent.

If this attribute is defined on the the smilText or span elements, the new color will be applied only to the content within the scope of that element.

The textDirection Attribute

The textDirection attribute specifies the direction of text added to a region based on the Unicode Bidirectional algorithm. The semantics of this attribute are defined in XSL 1.1. Note that only simple text direction control is available in SMILtext; for more elaborate text processing (including tb-lr), an external text formatting language is required. This attribute may be used on the smilText element, on the span elements or as a default on the region element.

Values:

inherit (default)
The text is written in the direction defined for the region referenced in the text element. If no direction was defined, the default is ltr.
ltr
The text is written in a left-to-right direction
rtl
The text is written in a right-to-left direction

If this attribute is defined on the smilText element, the new alignment mode will be applied to all text displayed in the region. If this attribute is applied to the span element, it only will be applied to the content within the scope of that element.

The textFontFamily Attribute

This attribute defines the family of font used to render text. The resolution of a generic family name to a specific font instance is not defined by this specification, but may be defined by a profile implementing this module. In order to reduce implementation burden, only generic font families may be specified in SMILtext. If an unrecognized font family is defined, then monospace can be expected. The sansSerif and serif fonts are expected to be proportional. See XSL 1.1 for font family details. This attribute may be used on the smilText element, on the span element or as a default on the region element.

Values:

monospace (default)
sansSerif
serif
inherit

If this attribute is defined on the the smilText or span elements, the new font family will be applied only to the content within the scope of that element.

The textFontSize Attribute

This attribute defines the size of the font to be used. In order to reduce implementation burden and to provide scalability across device classes, only absolute and relative sizes (as defined in XSL 1.1) are supported by SMILtext. This attribute may be used on the smilText element, on the span element or as a default on the region element.

Values:

length (default)
absolute-size (default)
absolute-size represents a set of absolute font sizes, maintained by the SMIL player (and possible influenced by the player user agent). Expected absolute sizes are: [ xx-small | x-small | small | medium | large | x-large | xx-large ]. As recommended in XSL 1.1, it is expected that each of the absolute sizes will differ by a factor of 1.2. The default absolute size is medium.
relative-size (default)
relative-size represents a relative increase or reduction in the absolute font size value. Expected values are: [ larger | smaller ]. Effective font sizes larger than the absolute-sez xx-large or smaller than the absolute-size xx-small will not be supported.
inherit

If this attribute is defined on the the smilText or span elements, the new font size will be applied only to the content within the scope of that element.

The textFontStyle Attribute

This attribute defines the style (italic, oblique, reverseOblique or normal) of the text displayed. If the specified style is not available, a style of normal will be used. This attribute may be used on the smilText element, on the span element or as a default on the region element. Of the values defined in XSL 1.1, only the options defined in the following list will be supported by SMILtext.

Values:

normal (default)
italic
oblique
reverseOblique
inherit

If this attribute is defined on the the smilText or span elements, the new font style will be applied only to the content within the scope of that element.

The textFontWeight Attribute

This attribute defines the weight (bold or regular) of text displayed. If the specified weight is not available, a weight of normal will be used. This attribute may be used on the smilText element, on the span element or as a default on the region element. Of the values defined in XSL 1.1, only the options defined in the following list will be supported by SMILtext.

Values:

normal (default)
The normal font weight for the font family selected is used.
bold
The bold font weight for the font family selected is used.
inherit
The effective font weight for the font family selected, as defined on the text element or the referenced region, is used.

If this attribute is defined on the the smilText or span elements, the new font weight will be applied only to the content within the scope of that element.

The textStyle Attribute

The attribute references a text style set defined using the textStyle element in the document head. This attribute may be used on the smilText element, on the span element or as a default on the region element.

Values:

IDREF
The ID of a textStyle definition. If the IDREF specified as a value does not refer to a valid textStyle set definition, this attributed is ignored.

If this attribute is defined on the the smilText or span elements, the set of styling attributes will be applied only to the content within the scope of that element.

Examples

This section is informative.

The following example provides an indication of the use of SMILtext within a profile that provides support for the TextStyling module (such as the SMIL 3.0 Language profile).

00 <smil ...>
01  <head>
     ...
02    <textStyling>
03      <textStyle id="HeadlineStyle" textFontFamily="serif" textFontSize="12px" 
             textFontWeight="Bold" textFontstyle="italic"          
             textWrapOption="noWrap" textColor="Blue" textBackgroundColor="white">
04    </textStyling>
05    <layout>
06      <region id="Title" top="5px" left="10%" width="80%" height="25px"
             textStyle="HeadlineStyle" />
07      <region id="Captions" top="215px" left="10%" width="80%" height="35px" 
          textFontFamily="serif" textColor="orange"  backgroundColor="blue"/>
08      <region id="Slides" top="10px" left="5%" width="90%" height="200px" />
09    </layout>
10   </head>
11   <body>
      ...
12    <par>
13     <smilText region="Title" fontfamily="sansSerif" fill="freeze">
14        Willemijn's 11th Birthday Party
15     </smilText>
16     <seq>
17       <par>
18         <img region="slides" src="p001.jpg" begin="1s" dur="9s"/>
19         <seq>
20           <smilText region="Captions" textAlign="left" dur="2s">
21              Shortly <span textFontStyle="italic">before</span> dawn ...
22           </smilText>
23           <smilText region="Captions" textColor="green" begin="0.5s" end="4.5s">
24              just as the clock began
25              <br/>
26              to chime six times...
27           </smilText>
28           <smilText region="Captions" textAlign="right" dur="3s">
29              our trusty dog Gretchen barked. 
30           </smilText>
31          </seq>
32       </par>
         ...
33       <par>
34         <img region="slides" src="p128.jpg" dur="7s"/>
35         <text region="Captions" src="c128.html" dur="7s"/>
36       </par>
37     <seq>
38     <audio src="Commentary.mp3" />
39    </par>
40   </body>
41 </smil>

In this example, one text style is defined (on line 03) and three layout regions are defined, one of which (on line 06) references a style definition with local overrides, and another of which (on line 07) uses mostly default style. In the body of the presentation, a parallel container is defined that contains a text title (on line 13); most of the styling attributes are defined on the region via the text style attribute. Later in the presentation, a sequence of images are defined that are each accompanied by one or more text captions. The text definition on line 13 illustrates that text, like images, has no inherit duration, but that by using the SMIL fill attribute, the content of the smilText element remains visible until the end of the parent time container (in this case, the par that is defined on line 12). The three smilText elements that accompany the image defined on line 18 illustrate that the in-line text object can use the standard SMIL timing attributes, plus several new attributes to explicitly control text placement and styling. Finally, the text element on line 35 illustrates that it is possible to mix in-line and external text in a single document.

8.5.2 Integration Requirements

Any profile that integrates the erase attribute must define what is meant by "display area" and further define the interaction. See the definition of erase for more details.

8.6 SMIL 3.0 TextFlow Module

This section is normative.

This section defines the elements and attributes that make up the SMIL TextFlow Module. Languages implementing the elements and attributes in the TextFlow Module must implement all elements and attributes defined below, as well as those defined in the BasicText module.

8.6.1 Elements and Attributes

This section defines the elements and attributes that make up the functionality in the SMIL 3.0 TextFlow module.

This module does not define any new elements.

The attribute defined by the TextFlow module is:

textFlowMode

If the TextStyling module is used in the profile implementing this module, then the textStyle element is extended to include the textFlowMode attribute. In addition, this module extends the definition of the SMIL Layout region element to include the textFlowMode attribute.

The textFlowMode Attribute

The textFlowMode attribute specifies how text in a smilText element is added to a region. It may be used on the smilText element or as a default on the region.

Values:

replace (default)
The text replaces the content in the region.
append
The text is added to the content in the region, if any.
inherit
The effective value defined for the region is used.

If this attribute is defined on the the smilText element, the new flow mode will be applied to all text displayed in the region.

Examples

This section is informative.

The text flow rendering behavior of within this module has been designed to be consistent with other types of media processed by a SMIL user agent. The example below illustrates the processing of SMILtext when the textFlowMode attribute is set to append and used in a SMIL sequential container:

 <smil ...>
  <head>
     ...
    <layout>
        ...
      <region id="Contents" top="5px" left="10%" width="80%" height="300px"
             textFlowMode="append" />
    </layout>
   </head>
   <body>
      ...
       <seq id="S2">
        <smilText id="TS21" region="Contents" >
           Willemijn's 11th Birthday Party
        </smilText>
        <smilText id="TS22" region="Contents" begin="5s" fill="hold">
           was held six weeks late.
        </smilText>
        <smilText id="TS23" region="Contents" begin="9s" dur="3s">
           (Again!)
        </smilText>
       </seq>
         ...
   </body>
 </smil>

This example starts with the addition of the textFlowMode attribute to the region definition. The region is referenced by the sequence labelled S2. Element TS21 places a line of text in the region; the default fill behavior of freeze keeps this text visible until TS22 starts. The text in TS22 is not appended to the region, but replaces the existing content because all existing content is removed when an element's active duration ends. When TS23 begins 9s later, the new text is appended to the text from TS22 because of the use of the fill="hold" attribute. All text is removed when S2 ends.

The following fragment illustrates the behavior of append mode when placed in a parallel container:

 <smil ...>
  <head>
     ...
    <layout>
        ...
      <region id="Contents" top="5px" left="10%" width="80%" height="300px"
             textFlowMode="append" />
    </layout>
   </head>
   <body>
      ...
       <par id="P2" dur="15s">
        <smilText id="TP21" region="Contents" dur="10s">
           Willemijn's 11th Birthday Party
        </smilText>
        <smilText id="TP22" region="Contents" begin="2s" end="6s" fill="freeze">
           was held six weeks late.
        </smilText>
        <smilText id="TP23" region="Contents" begin="4s" dur="3s">
           (Again!)
        </smilText>
       </par>
         ...
   </body>
 </smil>

When element P2 begins, it establishes a common timeline for the three text elements shown in the example. Element TP21 starts immediately and appends a text fragment to the region Contents. After 2s, element TP22 appends a line of text to the current contents of the region. Element TP23 adds an additional text fragment 2s later (at 4s into P2). After 3s, the active duration of TP23 ends and its contents is removed; this leaves the content from TP21 and TP22 in the region. TP22 ends 1s later, but the fill="freeze" forces its content to remain in the region until the end of the parent container (P2). At 10s after the start of P2, TP21 ends its active duration. The content associated with TP21 is removed from the region, leaving only the content from TP22.

In the following example, the value of the textFlowMode attribute is overridden by parts of the presentation body (with all other parts of the previous example remaining the same):

 <smil ...>
   ...
       <par id="P2" dur="15s">
        <smilText id="TP21" region="Contents" dur="10s">
           Willemijn's 11th Birthday Party
        </smilText>
        <smilText id="TP22" region="Contents" begin="2s" end="6s" fill="freeze">
           was held six weeks late.
        </smilText>
        <smilText id="TP23" region="Contents" begin="4s" dur="3s"
            textFlowMode="replace">
           (Again!)
   ...
 </smil>

The presentation logic of this example follows the previous discussion up to the start of TP23. When TP23 starts, it explicitly clears the region by specifying a textFlowMode="replace". The content of TP23 is placed alone in the region. After 3s, TP23 ends; at this point, the contents of TP21 and TP22 are restored into the region and processing proceeds as above.

8.6.2 Integration Requirements

Any profile that integrates the erase attribute must define what is meant by "display area" and further define the interaction. See the definition of erase for more details.

The value of the fit attribute will determine how text rendered within the region is processed.

8.7 Extended Examples

This section is informative.

This section provides a set of extended examples that motivate and illustrate SMILtext behavior.

8.7.1 General Behavior of SMILtext

All versions of SMIL have had support for the text element, which is defined as an alias of the generic SMIL ref media reference element. A typical use of the original SMIL text element is:

   ...
    <text region="Title" src="Headline.txt" dur="10s" >
   ...

The rendering semantic of the SMIL ref element -- and its aliases, such as img, audio, video, text, textstream -- is that content in the external file referenced by the src attribute is processed by an appropriate media renderer and replaces the contents of the layout region for the temporal duration of the element (including its fill period).

The following fragment illustrates the use of external text within a SMIL seq container:

  ...
  <layout>
    ...
    <region id="Title" height="80px" width="240px" fit="hidden"/>
  </layout>
  ...
  <seq id="S1" dur="25s" >
    <text id="T1" region="Title" src="Headline1.txt" dur="10s" />
    <text id="T2" region="Title" src="Headline2.txt" dur="10s" fill="freeze" />
  </seq>
 

This fragment renders the contents of T1 in the region Title for 10 seconds, under control of SMIL's layout rules. In this example, these rules determine that the media is positioned at the top-left edge of the region and that the text is clipped or wrapped (depending on the SMIL player) if it extends beyond the horizontal extent of the region and clipped if it extends beyond the vertical extent of the region. After 10 seconds, the contents of the region is replaced with that referenced in T2. Note that in both T1 and T2, all of the text is rendered at once, at the beginning of each element's active duration. After another 10 seconds, the active duration of T2 ends, but its parent remains active for an additional 5 seconds; since the fill behavior of T2 is freeze, the contents of T2 will remain visible at least until the end of S1.

The following fragment extends the previous example, using a par container instead of a seq:

  ...
  <layout>
    ...
    <region id="Title" height="20px" width="200px" fit="hidden"/>
  </layout>
  ...
  <par isd="P1" dur="20s" >
    <text id="T3" region="Title" src="Headline1.txt" begin="0s"  dur="15s" />
    <text id="T4" region="Title" src="Headline2.txt" begin="5s"  dur="5s"  />
  </par>
 

In this fragment, T3 starts at the same time as the parent P1. It fills the Title region in a manner identical to that described for T1, above. After 5 seconds, the rendering of T4 starts. The contents of T4 will be placed "on top" of the contents of T3 for a period of 5 seconds. (Whether the contents of T3 is fully obscured is player dependent.) At the end of T4's 5-second active duration its content will be removed and the content associated with T3 will reappear for 5 seconds. In this example, the effective fill behavior for T3 is remove, which means that the region will be empty (expect for the backgroundColor) for the final 5 seconds. Note that similar behavior is expected when the text objects are replaced with images containing the text.

SMILtext uses the same model to render text as was described above.

  ...
  <layout>
    ...
    <region id="Title" height="20px" width="200px" fit="hidden"/>
  </layout>
  ...
  <par isd="P2" dur="20s" >
    <smilText id="T5" region="Title" begin="0s"  dur="15s" fill="freeze" >
       This is a relatively long string of character text, which fills much of
       the target region.
    </smilText>
    <smilText id="T6" region="Title" begin="5s"  dur="5s"  >
       This is a relatively short string of text.
    </smilText>
  </par>
 

In this example, T5's content will be rendered started at time 0, followed by the content of T6 "on top" of the content of T5 during the interval between 5 and 10 seconds. The content in T6 will not be appended to that in T5, nor will the text in T5 reflow at anytime during this fragment. In order to keep SMILtext consistent with earlier versions of SMIL, this has been defined as default behavior within the BasicText module. There should be no functional difference in terms of layout and timing between rendering text via an external renderer and as in-line SMILtext.

There are some instances when it would be useful to allow text to append to the end of existing text in a region. Similarly, it may be useful to allow text to reflow if the active duration of a portion of text content ends while others remain active. To accommodate these cases, SMILtext defines the textAppend attribute in the TextFlow module. Consider the following fragment:

  ...
  <layout>
    ...
    <region id="Title" height="20px" width="200px" fit="hidden"
      textAppend="append" /> 
  </layout>
  ...
  <par isd="P3" dur="20s" >
    <smilText id="T7" region="Title" begin="0s"  dur="7s" >
       This is a relatively long string of character text, 
    </smilText>
    <smilText id="T8" region="Title" begin="0s"  dur="15s" >
       which fills much of the target region.
    </smilText>
    <smilText id="T9" region="Title" begin="5s"  dur="5s"  >
       This is a relatively short string of text.
    </smilText>
  </par>
 

Here, the contents of T7 and T8 are rendered at the start of P3. Since both T7 and T8 start at the same time, document order determines that T7 is rendered first, after which T8 is appended. After 5 seconds, the contents of T9 is appended to the contents in the region. At 7 seconds after the start of P3, T7's duration ends and its text is removed from the region, causing the contents to reflow. After an additional 3 second, T9 ends, causing its contents to be removed. Only T8 remains rendered. Note that this functionality is only relevant when multiple active text objects write into a region that has the textAppend attribute set: the attribute has no effect in, for example, a seq unless the effective fill semantics are hold. The use of textAppend allows a limited degree of dynamic content reflow, but it is not the intent of this attribute (or SMILtext) to provide extensive dynamic reflow capabilities; users interested in extensive text processing are expected to use external text rendering formats. Note also that support for this module is profile dependent.

Various attributes determine how text content is rendered in a region. In its most basic form, SMILtext provides a single attriute: textWrap. This attribute is a property of the region, but may be overridden on the text element. BasicText also supports a textBr element, for forcing a line break within text content. If the TextStyling module is included in the profile, an additional set of styling attributes are available, as is the textSpan element (which allows most styling attributes to be overriden within the span). In general, all styling attributes are properties of the rendering region, and most may be overriden on the text or textSpan elements. To make the specification of common styling elements more readable, the TextStyling module also defines a textStyle element within a textStyling section of the document head. The textStyle attribute allows these style sets to be applied to either regions, text elements or textSpan elements. An example of the definnition of style sets is:

  ...
  <textStyling>
    <textStyle id="Plain" textColor="black" textBackgroundColor="white"
                  textFontFamily="sansserif" textFontSize="medium" />
    <textStyle id="Fancy" textColor="orange" textBackgroundColor="blue"
                  textFontFamily="serif" textFontWeight="bold" />
  </textStyling>
  <layout>
    ...
    <region id="Title" height="20px" width="200px" textStyle="Plain"/>
  </layout>
  ...
  <smilText id="T5" region="Title" begin="0s"  dur="15s" textFontStyle="italic" >
     This is a relatively long string of 
     <span textStyle="fancy" textFontSize="large">character</span>
     text, which fills much of the target region.
  </smilText>
 

One of the common uses of text in a media presentation is to provide a crawling text string in one of the regions of a presentation. In SMIL NxG, this functionality is not a property of the text element, but a general function of the visual rendering model supported by SMIL layout. The following example illustrates how this is applied to SMILtext:

  <layout>
    ...
    <region id="News" height="20px" width="200px" fit="scroll" crawlRate="-10px"/>
    <region id="Credits" height="20px" width="200px" fit="scroll" scrollRate="5px"/>
  </layout>

In this example, any text written into the region News will be crawled at a rate of 10 pixels per second in the direction opposite to the expected direction specified by the textDirection attribute (this is the meaning of the minus sign). Any text written into the Credits region will be scrolled from bottom to top. For more details on the behavior of scrollRate and crawlRate, please refer to the definition in the Layout module.

8.8 Appendices

This section is informative.

8.8.1 Appendix A: Differences with the DFXP Specification

While SMILtext has been modelled as a functional subset of the DFXP profile of W3C TimedText, there are several differences between the languages. In this section, we review the components taken from DFXP, the components not taken from DFXP and the extensions defined that are not in DFXP.

Components Taken From DFXP for SMILtext

The following elements and attributes have been taken from DFXP and are included in SMILtext. Note that relevant attribute names from DFXP are preceded with 'text' to avoid conflict with attributes used in SMIL layout.

Component DFXP Name SMILtext Name Differences
Content br
span
br
span
The br element is identical in use.
The span element may not be nested in SMILtext.
Styling elements style
styling
textStyle
textStyling
These elements are declared in the document head.
SMILtext allows styles to be associated with layout regions as default values.
Styling attributes textAlign
BackgroundColor
Color
Direction
FontFamily
FontSize
FontWeight
Style
WrapOption
textAlign
textBackgroundColor
textColor
textDirection
textFontFamily
textFontSize
textFontWeight
textStyle
textWrapOption
SMILtext limits the range of values permitted for some of these attributes. The basic functionality is the same in all cases.

Components Not Taken From DFXP for SMILtext

The following elements and attributes are not included in SMILtext.

Additions in SMILtext Not in DFXP

The following elements and attributes are included in SMILtext but are not directly available in DFXP:

9. The SMIL 3.0 Metainformation Module

Editors for SMIL 3.0:
Dick Bulterman, CWI.
Marisa DeMeglio, Daisy.
Editors for Earlier Versions of SMIL:
Thierry Michel, W3C.

9.1 Summary of Changes for SMIL 3.0

This section is informative.

There are three sets of changes to this module. First, the SMIL 3.0 specification now allows meta-information to be placed on elements within the body instead of only in the head element. This may make it easier to provide information on semantic intent within a SMIL presentation by making the binding of that information with the relevant nodes more logical. Second, the text in this section makes it clear that several different types of metainformation encodings may be used within a single presentation. Third, the label attribute has been added to the Metainformation module so that extended content information can be provided for document components.

9.2 Introduction

This section is informative.

This section defines the SMIL 3.0 Metainformation Module. The SMIL metainformation facilities are composed of a module containing elements and attributes that allow description of metadata annotation of presentation creation information and presentation semantic intent to be added to SMIL documents. Since these elements and attributes are defined in a module, designers of other markup languages can choose whether or not to include this functionality in their languages.

The SMIL 1.0 specification allowed authors to describe documents with a very basic vocabulary using the meta element. This was extended in the SMIL 2.0 specification with the introduction of the element. The element introduced the capability for describing metadata using the Resource Description Framework Model and Syntax [RDFsyntax]. In SMIL 3.0, the element's description is exanded to allow multiple metainformation encodings to be used within a single presentation. Note that the profile integrating these modules will ultimately determine which metainformation formalisms will be required to be support by user agents for that profile.

Both the meta and elements were originally intended to be used in the head section of a SMIL document. While this was useful for general information about a document (such as when, where, and by whom it was created), this was deemed to be less appropriate for more semantic information about the intended use of individual media objects or structural elements of the presentation. For this reason, the descriptions and examples for both metadata elements now explicitly cite the ability of including meta-information descriptions within the body section of the presentation as well. As with multiple metainformation formats, it is the profile integrating these modules that will ultimately determine which elements may have metainformation as child elements.

SMIL 3.0 also extends the capabilities presented for describing the nature of a content fragment within a document by introducing the label attribute. This attribute specifies a URI to a SMIL document that provides additional information in an accessible manner on the related element.

Unless specified otherwise by a profile, a SMIL user agent is not required to process or otherwise interpret specific metainformation strings. In all cases, metainformation can be considered to be optional information in a presentation.

9.3 The SMIL 3.0 Metainformation Module

This section is normative.

This section defines the elements and attributes that make up the functionality in the SMIL Metainformation module.

9.3.1 Elements and Attributes

The SMIL 3.0 Metainformation module defines two elements and one attribute that provide basic support for metainformation mark-up within a SMIL presentation.

The elements defined in this module are:

meta

The attribute defined in this module is:

label

The meta element

The meta element specifies a single property/value pair in its name and content attributes, respectively. Multiple property/value pairs must be described in multiple instances of the meta element.

Element Attributes

The meta element defines the following attributes:

name = CDATA
This attribute identifies a property name. The name attribute is required for meta elements. The list of properties for the name attribute is open-ended and may be extended by a particular SMIL profile. This specification defines the following properties:
  • base: The value of this property determines the base URI for all relative URIs used in the document.
    Note: the base property has been deprecated in favor of the more general XML base URL mechanism described in [XMLBase]. The language profile including the SMIL 3.0 meta-information module will determine if the base property will be supported by that profile.
  • pics-label or PICS-Label: The value of this property specifies a valid rating label for the document as defined by PICS [PICS] .
  • title: The value of this property specifies the title of the presentation. SMIL user agents may use this property to display a title for the presentation during rendering.
content = CDATA
This attribute specifies a property's value. This specification does not list legal values for this attribute.
The content attribute is required for meta elements.
Element Content

The meta element is an empty element.

The metadata element

The element contains information that is also related to meta information of the document or document components. The element allows meta-information to be defined using a wide range of meta-information structuring languages. In many cases, it will act as the root element of an RDF tree, but it may also act as the root of other application-domain-specific meta-information structuring languages. The contents of the element are not processed within the context of a SMIL presentation, although different user agents may use the information within the element to support functionality such as searching or content labelling.

Element Attributes

The metadata element does not define any new attributes.

Element Content

When used with RDF, the element is expected to contain an RDF element and its sub-elements [RDFsyntax].

When used with other metainformation structuring languages, the element is expected to contain a metainformation description based on the structure and vocabulary of that language.

The label attribute

The label attribute specifies the name of a SMIL presentation that can be referenced by the user agent to provide additional information on the element to which this attribute is attached. A SMIL file is used as the target because this can provide a richer description of an element than a single text string or audio fragment. In this way, a richer mechanism is providing information on the intent of the relevant element than is available with other metadata facilities.

Attribute Values
label = URI
This attribute specifies a URI to a SMIL document containing a description for the role of the element or option given by the element.

9.4 Compatibility with Earlier Versions of SMIL

This section is informative.

To insure backward compatibility with SMIL 1.0, the meta element as specified in the SMIL 1.0 [SMIL10] Recommendation can be used to define properties of a document (e.g., author/creator, expiration date, a list of key words, etc.) and assign values to those properties. SMIL does not define which document properties must be used and it does not define a vocabulary of values for these properties. Use of properties defined in the [DC] is recommended.

SMIL 2.1 extended SMIL 1.0 meta information functionalities with the new element to host RDF statements. RDF is a declarative language and provides a W3C-recommended way for using XML to represent metadata in the form of statements about properties and relationships of items on the Web. Such items, known as resources, can be almost anything, provided it has a Web address. This means that you can associate metadata information with a SMIL document, but also a graphic, an audio file, a movie clip, or a structural sub-portion of a SMIL document. The specifications for RDF can be found at:

SMIL 3.0 maintains the use of both the meta and elements. New to SMIL 3.0 is the explicit possibility to allow the element to appear within the body section of a SMIL document. This allows the semantic intent of a portion of a SMIL document to be described in manner that is local to the media objects (or SMIL structure) being described. Note that it is ultimately up to the designer of the relevant SMIL 3.0 profile to determine where the element may appear in a SMIL document -- this Module simply highlights the possibility for including such information outside of the head section.

9.5 Examples

This section is informative.

This section contains four examples of the use of meta-information in a SMIL presentation.

The first example uses the Dublin Core version 1.0 RDF schema[DC] and a set of RDF descriptions, all contained in the document head section. The XML base attribute is used with the host-level language description to define the base address of relative URI references in the document.

<?xml version="1.1" ?>
<smil xmlns="http://www.w3.org/2007/SMIL30/WD/Language" xml:base="http://example.org/metaInf/assets/" >
    
 <head>
 <meta id="meta-smil1.0-a" name="Publisher" content="W3C" />
 <meta id="meta-smil1.0-b" name="Date" content="2007-01-03" />
 <meta id="meta-smil1.0-c" name="Rights" content="Copyright 1999 John Smith" />
 <meta id="meta-smil1.0-d" http-equiv="Expires" content="31 Dec 2001 12:00:00 GMT"/>


  <metadata id="meta-rdf">
   <rdf:RDF
       xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
       xmlns:rdfs = "http://www.w3.org/2000/01/rdf-schema#"
       xmlns:dc = "http://purl.org/dc/elements/1.1/"
       xmlns:smilmetadata = "http://www.example.org/AudioVideo/.../smil-ns#" >

<!-- Metadata about the SMIL presentation -->
   <rdf:Description rdf:about="http://www.example.com/meta.smi">
        ...
   </rdf:Description>

<!-- Metadata about the video -->
   <rdf:Description rdf:about="http://www.example.com/videos/meta-1999.mpg">
        ...
   </rdf:Description>

<!-- Metadata about a scene of the video -->
   <rdf:Description rdf:about="#scene1"
        ...
   </rdf:Description>
  </rdf:RDF>
 </metadata>

 <layout>
    <region id="a" top="5" />
 </layout>
 </head>
 <body>
   <video region="a" src="/videos/meta-1999.mpg" >
     <area id="scene1" begin="0s" end ="30s"/>
     <area id="scene2" begin="30s" end ="60s"/>
   </video>
   <video region="a" src="/videos/meta2-1999.mpg"/>
 </body>
</smil>

The second example is similar to the first, except that references on individual media elements are placed within the document definition instead of the head element.

<?xml version="1.1" ?>
<smil xmlns="http://www.w3.org/2007/SMIL30/WD/Language" xml:base="http://example.org/metaInf/assets/" >
    
 <head>
 <meta id="meta-smil1.0-a" name="Publisher" content="W3C" />
 <meta id="meta-smil1.0-b" name="Date" content="2007-01-03" />
 <meta id="meta-smil1.0-c" name="Rights" content="Copyright 1999 John Smith" />
 <meta id="meta-smil1.0-d" http-equiv="Expires" content="31 Dec 2001 12:00:00 GMT"/>


  <metadata id="meta-rdf">
   <rdf:RDF
       xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
       xmlns:rdfs = "http://www.w3.org/2000/01/rdf-schema#"
       xmlns:dc = "http://purl.org/dc/elements/1.1/"
       xmlns:smilmetadata = "http://www.example.org/AudioVideo/.../smil-ns#" >

<!-- Metadata about the SMIL presentation -->
   <rdf:Description rdf:about="http://www.example.com/meta.smi">
        ...
   </rdf:Description>
  </rdf:RDF>
 </metadata>

 <layout>
    <region id="a" top="5" />
 </layout>
 </head>
 <body>
   <video id="v1" region="a" src="/videos/meta-1999.mpg" >
      <metadata id="meta-rdf">
         <rdf:RDF
            xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
            xmlns:rdfs = "http://www.w3.org/2000/01/rdf-schema#"
            xmlns:dc = "http://purl.org/dc/elements/1.1/"
            xmlns:smilmetadata = "http://www.example.org/AudioVideo/.../smil-ns#" >

            <!-- Metadata about the video -->
              <rdf:Description rdf:about="http://www.example.com/videos/meta-1999.mpg"
                ...
              </rdf:Description>
        </rdf:RDF>
     </metadata>
     <area id="scene1" begin="0s" end ="30s">
        <metadata id="meta-rdf">
           <rdf:RDF
              xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
              xmlns:rdfs = "http://www.w3.org/2000/01/rdf-schema#"
              xmlns:dc = "http://purl.org/dc/elements/1.1/"
              xmlns:smilmetadata = "http://www.example.org/AudioVideo/.../smil-ns#" >

           <!-- Metadata about a scene of the video -->
             <rdf:Description rdf:about="#scene1"
                  ...
             </rdf:Description>
         </rdf:RDF>
        </metadata>
     </area>
     <area id="scene2" begin="30s" end ="60s"/>
   </video>
   <video region="a" src="/videos/meta2-1999.mpg"/>
 </body>
</smil>

In this example, separate meta-information blocks have been defined for the presentation, the video element 'v1' and open of the scenes of the video. Although RDF has been used for all of these objects, other formalisms (such as MPEG-7 or TV-Anytime) may also be used.

The third example shows part of a presentation with the role of chapter, labeled as such. The example also shows the label in its own file. It can therefore be referred to by using a simple URI with no XPointer or ID fragment.

<?xml version="1.1" ?>
<smil>
 ...
 <body>
   <!–– This part of the presentation is a chapter ––>
   <seq role="chapter" label="chapterlabel.smil">
     <par>
       <text src="example.html#fragment_one"/>
       <audio src="audio_document.mp3" clipBegin="0.00s" clipEnd="5.00s"/>
     </par>
     ...
   </seq>
 </body>
</smil>

The label is in a separate file (chapterlabel.smil):

<?xml version="1.1" ?>
<smil>
 ...
 <body>
   <!––the label itself, as text and audio––>
   <par>
     <text>Chapter</text>
     <audio src="chapter.mp3"/>
   </par>
 </body>
</smil>
The fourth example shows a presentation with two content control options, to be set by the user. Both labels used here are found in the same external SMIL file, wrapped in an excl container (so that only one is played at a time). The referencing URI specifies which label is required.
 ...
 <head>
   <customAttributes>
     <!–– the option to play page numbers ––>
     <customTest id="pagenumbersOn" defaultState="false" override="visible" label="labels.smil#pagenumbers"/>
     <!–– the option to play footnotes ––>
     <customTest id="footnotesOn" defaultState="true" override="visible" label="labels.smil#footnotes"/>
   </customAttributes>
 </head>
 ...

The following SMIL file (labels.smil) contains both labels used in example four:

<?xml version="1.1" ?>
<smil>
   ...
 <body>
   <excl>
     <par id="footnotes">
       <text>Footnotes</text>
       <audio src="footnotes.mp3" clipBegin="0.00s" clipEnd="1.54s"/>
     </par>
     <par id="pagenumbers">
       <–– the label's textual content can reference inline or external text ––>
       <text src="labeltext.xml#pagenum"/>
       <audio src="pagenumbers.mp3"/>
     </par>
   </excl>
 </body>
</smil<

The collections of elements that allow the element as a child is determined by the SMIL language profile integrating this module.

10. The SMIL 3.0 Structure Module

Editor for SMIL 3.0
Thierry Michel, W3C
Editor for Earlier Versions of SMIL
Warner ten Kate, Philips Electronics
Aaron Cohen, Intel.

10.1 Overview and Summary of Changes for SMIL 3.0

This section is informative.

The SMIL 3.0 specification leaves the SMIL 2.1 Structure Module [SMIL21-structure] unchanged.

10.2 Introduction

This section is informative

This Section defines the SMIL Structure module. The Structure module provides the base elements for structuring SMIL content. These elements act as the root in the content model of all SMIL Host Language conformant language profiles. The Structure module is a mandatory module for SMIL Host Language conformant language profiles.The SMIL Structure module is composed of the smil, head, and body elements, and is compatible with SMIL 1.0 [SMIL10]. The corresponding SMIL 1.0 elements form a subset of the Structure module, both in syntax and semantics, as their attributes and content model is also exposed by the Structure module. Thus, the Structure module is backwards compatible with SMIL 1.0.

10.3 The SMIL 3.0 Structure Module Syntax and Semantics

This section is normative

10.3.1 Elements and attributes

This section defines the elements and attributes that make up the SMIL 3.0 Structure module.

The smil element

The smil element acts as the root element for all SMIL Host Language conformant language profiles.

Element attributes

The smil element can have the following attributes:

id
The id attribute uniquely identifies an element within a document. Its value is an XML identifier.
class
The class attribute assigns a class name or a set of class names to an element. Any number of elements may be assigned the same class name or names. Multiple class names must be separated by white space characters.
xml:lang
The xml:lang attribute specifies the language of an element, and is specified in XML 1.1 [XML11]. xml:lang differs from systemLanguage test attribute in one important respect. xml:lang provides information about content's language independent of what implementations do with the information, whereas systemLanguage is a test attribute with specific associated behavior (see systemLanguage in SMIL 3.0 BasicContentControl Module for details).
title
The title attribute offers advisory information about the element for which it is set. Values of the title attribute may be rendered by user agents in a variety of ways. For instance, visual browsers frequently display the title as a "tool tip" (a short message that appears when the pointing device pauses over an object).
xmlns
The xmlns attribute declares an XML namespace, and is defined in "Namespaces in XML" [XML-NS].
Element content

The smil element can contain the following elements:

head
body

The head element

The head element contains information that is not related to the temporal behavior of the presentation. Three types of information may be contained by head. These are meta information, layout information, and author-defined content control.

Element attributes

The head element can have the following attributes:

id
Defined in id under the smil element.
class
Defined in class under the smil element.
xml:lang
Defined in xml:lang under the smil element.
title
Defined in title under the smil element.
Element content

The head element contains elements depending on the other modules and specific syntax included in the language profile integrating this module.

The body element

The body element contains information that is related to the temporal and linking behavior of the document. It acts as the root element of the timing tree.

The body element has the timing semantics of a time container equal to that of the seq element [BasicTimeContainers module]. Note, that in other language profiles, where a body element from another (Structure) Module is in use, that body element may have different timing semantics. For example, in the XHTML+SMIL language profile (still in progress and not yet a W3C Recommendation), the body element comes from XTML, and acts as a par time container.

Element attributes

The body element can have the following attributes:

id
Defined in id under the smil element.
class
Defined in class under the smil element.
xml:lang
Defined in xml:lang under the smil element.
title
Defined in title under the smil element.

The timing attributes defined in the various SMIL 3.0 Timing modules are part of the body element so far as the corresponding timing modules, such as BasicInlineTiming, are part of the language profile. When a timing module is included in a language profile, the features of that module should be supported on the body element just as they are supported on the other elements in the profile. For example, the syncMaster attribute should be supported on the body element if the SyncMaster module is included in the integrating profile.

Element content

The body element contains elements depending on the other modules and specific syntax included in the language profile integrating this module.

10.4 Integrating the SMIL Structure Module

This section is normative

When this module is included in a language profile, the id, class, and title attributes defined in this module must be included on all elements from all modules used in the profile, including those from other module families and of non-SMIL origin. The integrating profile should also consider adding the xml:lang attribute to the applicable elements.

The SMIL Structure module is the starting module when building any SMIL Host Language conformant language profile. The Structure module may not be used for building other, non-SMIL Host Language conformant language profiles. This implies that the SMIL Structure module must at least be accompanied with the other modules mandatory for SMIL Host language conformance, and the elements in the structure module must include at least the minimum content models required for SMIL Host language conformance. 

When modules from outside the SMIL 3.0 namespace are integrated in the language profile, it must be specified how the elements from those non-SMIL modules fit into the content model of the used SMIL modules (and vice versa). For example, with respect to the SMIL Structure module, the Profiling Entities in the DTD need to be overridden. This creates a so-called hybrid document type [XMOD]. In case of a so-called compound document type, the rules of XML namespaces must be satisfied [XML-NS].

11. The SMIL 3.0 Timing and Synchronization Module

Editor for SMIL 3.0
Sjoerd Mullender, CWI
Editor for Earlier Versions of SMIL
Dick Bulterman, CWI/Amsterdam
Patrick Schmitz, Microsoft
Jeff Ayars, RealNetworks
Bridie Saccocio, RealNetworks
Muriel Jourdan, INRIA.

11.1 Overview and Summary of Changes for SMIL 3.0

This section is informative.

The SMIL 3.0 specification leaves the basic syntax and semantics of the SMIL 2.1 timing model unchanged [SMIL21-timing]. The only changes for SMIL 3.0 are that the allowed values for the begin attribute of children of a seq container to simplify implementations by removing the need for special case code; and that the four DOM method calls which were reserved in SMIL 2.1 have now been defined. A new module, DOMTimingMethods, was added which contains these DOM methods.

11.2 Introduction

This section is informative

SMIL 1.0 solved fundamental media synchronization problems and defined a powerful way of choreographing multimedia content. SMIL 2.1 extends the timing and synchronization support, adding capabilities to the timing model and associated syntax. SMIL 3.0 relaxes some artificial constraints and adds Document Object Model support. Some SMIL 1.0 syntax has been changed or deprecated. This section of the document specifies the Timing and Synchronization module.

There are two intended audiences for this module: implementers of SMIL 3.0 document viewers or authoring tools, and authors of other XML languages who wish to integrate timing and synchronization support. A language with which this module is integrated is referred to as a host language. A document containing SMIL Timing and Synchronization elements and attributes is referred to as a host document.

As this module is used in different profiles (i.e. host languages), the associated syntax requirements may vary. Differences in syntax should be minimized as much as is practical.

SMIL 3.0 Timing and Synchronization support is broken down into 17 modules, allowing broad flexibility for language designers integrating this functionality. These modules are described in Appendix A: SMIL Timing and Synchronization modules.

11.3 Overview of SMIL timing

This section is informative

SMIL Timing defines elements and attributes to coordinate and synchronize the presentation of media over time. The term media covers a broad range, including discrete media types such as still images, text, and vector graphics, as well as continuous media types that are intrinsically time-based, such as video, audio and animation.

Three synchronization elements support common timing use-cases:

These elements are referred to as time containers. They group their contained children together into coordinated timelines.

SMIL Timing also provides attributes that can be used to specify an element's timing behavior. Elements have a begin, and a simple duration. The begin can be specified in various ways - for example, an element can begin at a given time, or based upon when another element begins, or when some event (such as a mouse click) happens. The simple duration defines the basic presentation duration of an element. Elements can be defined to repeat the simple duration, a number of times or for an amount of time. The simple duration and any effects of repeat are combined to define the active duration. When an element's active duration has ended, the element can either be removed from the presentation or frozen (held in its final state), e.g. to fill any gaps in the presentation.

An element becomes active when it begins its active duration, and becomes inactive when it ends its active duration. Within the active duration, the element is active, and outside the active duration, the element is inactive.

Figure 1 illustrates the basic support of a repeating element within a simple <par> time container. The corresponding syntax is included with the diagram.

Basic strip illustration of timing

<par begin="0s" dur="33s">
   <video begin="1s" dur="10s" repeatCount="2.5" fill="freeze" .../>
</par>

Figure 1 - Strip diagram of basic timing support. The starred "Simple*" duration indicates that the simple duration is partial (i.e. it is cut off early).

The attributes that control these aspects of timing can be applied not only to media elements, but to the time containers as well. This allows, for example, an entire sequence to be repeated, and to be coordinated as a unit with other media and time containers. While authors can specify a particular simple duration for a time container, it is often easier to leave the duration unspecified, in which case the simple duration is defined by the contained child elements. When an element does not specify a simple duration, the time model defines an implicit simple duration for the element. For example, the implicit simple duration of a sequence is based upon the sum of the active durations of all the children.

Each time container also imposes certain defaults and constraints upon the contained children. For example in a <seq>, elements begin by default right after the previous element ends, and in all time containers, the active duration of child elements is constrained not to extend past the end of the time container's simple duration. Figure 2 illustrates the effects of a repeating <par> time container as it constrains a <video> child element.

More complex strip illustration of timing

<par begin="0s" dur="12s" repeatDur="33s" fill="freeze" >
   <video begin="1s" dur="5s" repeatCount="1.8" fill="freeze" .../>
</par>

Figure 2 - Strip diagram of time container constraints upon child elements. The starred "Simple*" durations indicate that the simple duration is partial (i.e. it is cut off early).

The SMIL Timing Model defines how the time container elements and timing attributes are interpreted to construct a time graph. The time graph is a model of the presentation schedule and synchronization relationships. The time graph is a dynamic structure, changing to reflect the effect of user events, media delivery, and DOM control of the presentation. At any given instant, the time graph models the document at that instant, and the semantics described in this module. However, as user events or other factors cause changes to elements, the semantic rules are re-evaluated to yield an updated time graph.

When a begin or end value refers to an event, or to the begin or active end of another element, it may not be possible to calculate the time value. For example, if an element is defined to begin on some event, the begin time will not be known until the event happens. Begin and end values like this are described as unresolved. When such a time becomes known (i.e. when it can be calculated as a presentation time), the time is said to be resolved. A resolved time is said to be definite if it is not the value "indefinite". See also the discussion of Unifying scheduled and interactive timing.

In an ideal environment, the presentation would perform precisely as specified. However, various real-world limitations (such as network delays) can influence the actual playback of media. How the presentation application adapts and manages the presentation in response to media playback problems is termed runtime synchronization behavior. SMIL includes attributes that allow the author to control the runtime synchronization behavior for a presentation.

11.4 Language definition

11.4.1 Changes for SMIL 3.0

This section is informative

This section remains largely unchanged for SMIL 3.0 except for the relaxation of the restrictions on the begin attributes of children of a seq time container. Also, a number of examples have been added.

11.4.2 Overview

This section is informative

The timing model is defined by building up from the simplest to the most complex concepts: first the basic timing and simple duration controls, followed by the attributes that control repeating and constraining the active duration. Finally, the elements that define time containers are presented.

The time model depends upon several definitions for the host document: A host document is presented over a certain time interval.

11.4.3 Attributes

This section defines the set of timing attributes that are common to all of the SMIL synchronization elements.

Unless otherwise specified below, if there is any error in the argument value syntax for an attribute, the attribute will be ignored (as though it were not specified).

The begin and dur attributes: basic timing support

This section is informative

The basic timing for an element is described using the begin and dur attributes. Authors can specify the begin time of an element in a variety of ways, ranging from simple clock times to the time that an event (e.g. a mouse click) happens. The simple duration of an element is specified as a simple time value. The begin attribute syntax is described below. The normative syntax rules for each attribute value variant are described in Timing attribute value grammars; an attribute value syntax summary is provided here as an aid to the reader.

This section is normative

begin : smil-1.0-syncbase-value | begin-value-list
Defines when the element becomes active.
The attribute value is either a SMIL 1.0 syncbase declaration, or a semi-colon separated list of values.
smil-1.0-syncbase-value : "id(" Id-value ")" ( "(" ( "begin" | "end" | Clock-value ) ")" )?
Deprecated. Describes a syncbase and an offset from that syncbase. The element begin is defined relative to the begin or active end of another element.
begin-value-list : begin-value (";" begin-value-list )?
A semi-colon separated list of begin values. The interpretation of a list of begin times is detailed in the section Evaluation of begin and end time lists.
begin-value : ( offset-value | syncbase-value | event-value | repeat-value | accesskey-value | media-marker-value | wallclock-sync-value | "indefinite" )
Describes the element begin.
offset-value : ( "+" | "-" )? Clock-value
Describes the element begin as an offset from an implicit syncbase. The definition of the implicit syncbase depends upon the element's parent time container. The offset is measured in parent simple time.
syncbase-value : ( Id-value "." ( "begin" | "end" ) ) ( ( "+" | "-" ) Clock-value )?
Describes a syncbase and an offset from that syncbase. The element begin is defined relative to the begin or active end of another element.
event-value : ( Id-value "." )? ( event-ref ) ( ( "+" | "-" ) Clock-value )?
Describes an event and an optional offset that determine the element begin. The element begin is defined relative to the time that the event is raised. Events may be any event defined for the host language in accordance with [DOM2Events]. These may include user-interface events, event-triggers transmitted via a network, etc. Details of event-based timing are described in the section below on Unifying Event-based and Scheduled Timing.
repeat-value : ( Id-value "." )? "repeat(" integer ")" ( ( "+" | "-" ) Clock-value )?
Describes a qualified repeat event. The element begin is defined relative to the time that the repeat event is raised with the specified iteration value.
accesskey-value : "accesskey(" character ")"( ( "+" | "-" ) Clock-value )?
Describes an accesskey that determines the element begin. The element begin is defined relative to the time that the accesskey character is input by the user.
media-marker-value : Id-value ".marker(" marker-name ")"
Describes the element begin as a named marker time defined by a media element.
wallclock-sync-value : "wallclock(" wallclock-value ")"
Describes the element begin as a real-world clock time. The wallclock time syntax is based upon syntax defined in [ISO8601].
"indefinite"
The begin of the element will be determined by a "beginElement()" method call or a hyperlink targeted to the element.
The SMIL Timing and Synchronization DOM methods are described in the Reserveed DOM methods section.
Hyperlink-based timing is described in the Hyperlinks and timing section.
Begin value semantics

This section is normative

This section is informative

Children of a par begin by default when the par begins (equivalent to begin="0s"). Children of a seq begin by default when the previous child ends its active duration (equivalent to begin="0s"); the first child begins by default when the parent seq begins. Children of an excl default to a begin value of "indefinite".

The begin value can specify a list of times. This can be used to specify multiple "ways" or "rules" to begin an element, e.g. if any one of several events is raised. A list of times can also define multiple begin times, allowing the element to play more than once (this behavior can be controlled, e.g. to only allow the earliest begin to actually be used - see also the restart attribute).

In general, the earliest time in the list determines the begin time of the element. There are additional constraints upon the evaluation of the begin time list, detailed in Evaluation of begin and end time lists.

Note that while it is legal to include "indefinite" in a list of values for begin, "indefinite" is only really useful as a single value. Combining it with other values does not impact begin timing, as DOM begin methods can be called with or without specifying "indefinite" for begin.

When a begin time is specified as a syncbase variant, a marker value or a wallclock value, the defined time must be converted by the implementation to a time that is relative to the parent time container (i.e. to the equivalent of an offset value). This is known as timespace conversion, and is detailed in the section Converting between local and global times.

Handling negative offsets for begin

This section is informative

The use of negative offsets to define begin times merely defines the synchronization relationship of the element. It does not in any way override the time container constraints upon the element, and it cannot override the constraints of presentation time.

This section is normative

The computed begin time defines the scheduled synchronization relationship of the element, even if it is not possible to begin the element at the computed time. The time model uses the computed begin time, and not the observed time of the element begin.

This section is informative

If an element has a begin time that resolves to a time before the parent time container begins, the parent time container constraint still applies. For example:

<par>
   <video id="vid" begin="-5s" dur="10s" src="movie.mpg" />
   <audio begin="vid.begin+2s" dur="8s" src="sound.au" />
</par>

The video element cannot begin before the par begins. The begin is simply defined to occur "in the past" when the par begins. The viewer will observe that the video begins 5 seconds into the media, and ends after 5 seconds. Note that the audio element begins relative to the video begin, and that the computed begin time is used, and not the observed begin time as constrained by the parent. Thus the audio begins 3 seconds into the media, and also lasts 5 seconds.

The behavior can be thought of as a clipBegin value applied to the element, that only applies to the first iteration of repeating elements. In the example above, if either element were defined to repeat, the second and later iterations of the media would play from the beginning of the media (see also the repeatCount, repeatDur, and repeat attributes: repeating elements).

This section is normative

The behavior can be thought of as a clipBegin value applied to the element, that only applies to the first iteration of repeating elements.

The element will actually begin at the time computed according to the following algorithm:

Let o be the offset value of a given begin value,
d be the associated simple duration, 
AD be the associated active duration.
Let rAt be the time when the begin time becomes resolved.
Let rTo be the resolved sync-base or event-base time without the offset
Let rD be rTo - rAt.  If rD < 0 then rD is set to 0.
 
If AD is indefinite, it compares greater than any value of o or ABS(o).
REM( x, y ) is defined as x - (y * floor( x/y )). 
If y is indefinite or unresolved, REM( x, y ) is just x.

Let mb = REM( ABS(o), d ) - rD
If ABS(o) >= AD then the element does not begin.
Else if mb >= 0 then the media begins at mb.
Else the media begins at mb + d.

If the element repeats, the iteration value of the repeat event has the calculated value based upon the above computed begin time, and not the observed number of repeats.

This section is informative

Thus for example:

<smil ...> 
...
<ref begin="foo.activateEvent-8s" dur="3s" repeatCount="10" .../>
...
</smil>

The element begins when the user activates (for example, clicks on) the element "foo". Its calculated begin time is actually 8 seconds earlier, and so it begins to play at 2 seconds into the 3 second simple duration, on the third repeat iteration. One second later, the fourth iteration of the element will begin, and the associated repeat event will have the iteration value set to 3 (since it is zero based). The element will end 22 seconds after the activation. The beginEvent event is raised when the element begins, but has a time stamp value that corresponds to the defined begin time, 8 seconds earlier. Any time dependents are activated relative to the computed begin time, and not the observed begin time.

Note: If script authors wish to distinguish between the computed repeat iterations and observed repeat iterations, they can count actual repeat events in the associated event handler.

Negative begin delays

A begin time specifies a synchronization relationship between the element and the parent time container. Syncbase variants, eventbase, marker and wallclock timing are implicitly converted to an offset on the parent time container, just as an offset value specifies this directly. For children of a time container the computed offset relative to the parent begin time may be negative.

Note that an element cannot actually begin until the parent time container begins. For children of a seq there is the additional constraint that they cannot begin before the previous child has ended its active duration. An element with a negative time delay behaves as if it had begun earlier.

The presentation effect for the element (e.g. the display of visual media) is equivalent to that for a clipBegin value (with the same magnitude) for the first -- and only the first -- iteration of a repeated element. If no repeat behavior is specified, the element presentation effect of a negative begin offset is equivalent to a clipBegin specification with the same magnitude as the offset value. Nevertheless, the timing side effects are not equivalent to a clipBegin value as described. Time dependents of the begin value will behave as though the element had begun earlier.

Dur value semantics

The length of the simple duration is specified using the dur attribute. The dur attribute syntax is described below.

This section is normative

dur
Specifies the simple duration.
The attribute value can be any of the following:
Clock-value
Specifies the length of the simple duration, measured in element active time.
Value must be greater than 0.
"media"
Specifies the simple duration as the intrinsic media duration. This is only valid for elements that define media.
"indefinite"
Specifies the simple duration as indefinite.

If there is any error in the argument value syntax for dur, the attribute will be ignored (as though it were not specified).

If the "media" attribute value is used on an element that does not define media (e.g. on the SMIL 3.0 time container elements par, seq and excl), the attribute will be ignored (as though it were not specified). Contained media such as the children of a par are not considered media directly associated with the element.

If the element does not have a (valid) dur attribute, the simple duration for the element is defined to be the implicit duration of the element.

The implicit duration depends upon the type of an element. The primary distinction is between different types of media elements and time containers. If the media element has no timed children, it is described as a simple media element.

If the author specifies a value for dur that is shorter than the implicit duration for an element, the implicit duration will be cut short by the specified simple duration.

If the author specifies a simple duration that is longer than the implicit duration for an element, the implicit duration of the element is extended to the specified simple duration:

Note that when the simple duration is "indefinite", some simple use cases can yield surprising results. See the related example #4 in Appendix B.

Examples

The following example shows simple offset begin timing. The <audio> element begins 5 seconds after the <par> time container begins, and ends 4 seconds later.

<par>
   <audio src="song1.au" begin="5s" dur="4s" />
</par>

The following example shows syncbase begin timing. The <img> element begins 2 seconds after the <audio> element begins.

<par>
   <audio id="song1" src="song1.au" />
   <img src="img1.jpg" begin="song1.begin+2s" />
</par>

Elements can also be specified to begin in response to an event. In this example, the image element begins (appears) when the user clicks on element "show". The image will end (disappear) 3 and a half seconds later.

<smil ...>
...
<text id="show" ... />
<img begin="show.activateEvent" dur="3.5s" ... />
...
</smil ...>

The end attribute: controlling active duration

This section is informative

SMIL 3.0 provides an additional control over the active duration. The end attribute allows the author to constrain the active duration by specifying an end value using a simple offset, a time base, an event-base, a syncbase, or DOM methods calls. The rules for combining the attributes to compute the active duration are presented in the section, Computing the active duration.

The normative syntax rules for each attribute value variant are described in the section Timing attribute value grammars; a syntax summary is provided here as an aid to the reader.

This section is normative

end : smil-1.0-syncbase-value | end-value-list
Defines an end value for the element that can constrain the active duration.
The attribute value is either a SMIL 1.0 syncbase declaration, a semi-colon separated list of values.
smil-1.0-syncbase-value : "id(" Id-value ")" ( "(" ( "begin" | "end" | Clock-value ) ")" )?
Deprecated. Describes a syncbase and an offset from that syncbase. The end value is defined relative to the begin or active end of another element.
end-value-list : end-value (";" end-value-list )?
A semi-colon separated list of end values. The interpretation of a list of end times is detailed in the section Evaluation of begin and end time lists.
end-value : ( offset-value | syncbase-value | event-value | repeat-value | accesskey-value | media-marker-value | wallclock-sync-value | "indefinite" )
Describes the end value of the element.
offset-value : ( "+" | "-" )? Clock-value
Describes the end value as an offset from an implicit syncbase. The definition of the implicit syncbase depends upon the element's parent time container. The offset is measured in parent simple time.
syncbase-value : ( Id-value "." ( "begin" | "end" ) ) ( ( "+" | "-" ) Clock-value )?
Describes a syncbase and an offset from that syncbase. The end value is defined relative to the begin or active end of another element.
event-value : ( Id-value "." )? ( event-ref ) ( ( "+" | "-" ) Clock-value )?
Describes an event and an optional offset that determine the end value. The end value is defined relative to the time that the event is raised. Events may be any event defined for the host language in accordance with [DOM2Events]. These may include user-interface events, event-triggers transmitted via a network, etc. Details of event-based timing are described in the section below on Unifying Event-based and Scheduled Timing.
repeat-value : ( Id-value "." )? "repeat(" integer ")" ( ( "+" | "-" ) Clock-value )?
Describes a qualified repeat event. The end value is defined relative to the time that the repeat event is raised with the specified iteration value.
accesskey-value : "accesskey(" character ")"( ( "+" | "-" ) Clock-value )?
Describes an accesskey that determines the end value. The end value is defined as the time that the accesskey character is input by the user.
media-marker-value : Id-value ".marker(" marker-name ")"
Describes the end value as a named marker time defined by a media element.
wallclock-sync-value : "wallclock(" wallclock-value ")"
Describes the end value as a real-world clock time. The wallclock time is based upon syntax defined in [ISO8601].
"indefinite"
The end value of the element will be determined by an endElement() method call.
The SMIL Timing and Synchronization DOM methods are described in the Reserved DOM methods section.

If an end attribute is specified but none of dur, repeatCount and repeatDur are specified, the simple duration is defined to be indefinite, and the end value constrains this to define the active duration. The behavior of the simple duration in this case is defined in Dur value semantics, as though dur had been specified as "indefinite".

If the end value becomes resolved while the element is still active, and the resolved time is in the past, the element should end the active duration immediately. Time dependents defined relative to the end of this element should be resolved using the computed active end (which may be in the past), and not the observed active end.

The deprecated SMIL 1.0-syncbase-values are semantically equivalent to the following SMIL 3.0 end-value types:

This section is informative

The end value can specify a list of times. This can be used to specify multiple "ways" or "rules" to end an element, e.g. if any one of several events is raised. A list of times can also define multiple end times that can correspond to multiple begin times, allowing the element to play more than once (this behavior can be controlled - see also the restart attribute).

In the following example, the dur attribute is not specified, and so the simple duration is defined to be the implicit media duration. In this case (and this case only) the value of end will extend the active duration if it specifies a duration greater than the implicit duration. The video will be shown for 8 seconds, and then the last frame will be shown for 2 seconds.

<video end="10s" src="8-SecondVideo.mpg" .../>

If an author wishes to specify the implicit duration as well as an end constraint, the dur attribute can be specified as "media". In the following example, the element will end at the earlier of the intrinsic media duration, or a mouse click:

<html ...>
...
<video dur="media" end="click" src="movie.mpg" .../>
...
</html>

These cases arise from the use of negative offsets in the sync-base and event-base forms, and authors should be aware of the complexities this can introduce. See also Handling negative offsets for end.

In the following example, the active duration will end at the earlier of 10 seconds, or the end of the "foo" element. This is particularly useful if "foo" is defined to begin or end relative to an event.

<audio src="foo.au" dur="2s" repeatDur="10s" 
       end="foo.end" .../>

In the following example, the active duration will end at 10 seconds, and will cut short the simple duration defined to be 20 seconds. The effect is that only the first half of the element is actually played. For a simple media element, the author could just specify this using the dur attribute. However in other cases, it is sometimes important to specify the simple duration independent of the active duration.

<par>
   <audio src="music.au" dur="20s" end="10s" ... />
</par>

In the following example, the element begins when the user activates (e.g., clicks on) the "gobtn" element. The active duration will end 30 seconds after the parent time container begins.

<smil ...>
...
<par>
<audio src="music.au" begin="gobtn.activateEvent" repeatDur="indefinite"
          end="30s" ... />
     <img src="foo.jpg" dur="40s" ... />
</par>
...
</smil>

Note that if the user has not clicked on the target element before 30 seconds elapse, the element will never begin. In this case, the element has no active duration and no active end.

The defaults for the event syntax make it easy to define simple interactive behavior. The following example stops the image when the user clicks on the element.

<html ...>
...
<img src="image.jpg" end="click" />
...
</html>

Using end with an event value enables authors to end an element based on either an interactive event or a maximum active duration. This is sometimes known as lazy interaction.

In this example, a presentation describes factory processes. Each step is a video, and set to repeat 3 times to make the point clear. Each element can also be ended by clicking on the video, or on some element "next" that indicates to the user that the next step should be shown.

<smil ...>
...
<seq>
  <video dur="5s" repeatCount="3" end="activateEvent; next.activateEvent" .../>
  <video dur="5s" repeatCount="3" end="activateEvent; next.activateEvent" .../>
  <video dur="5s" repeatCount="3" end="activateEvent; next.activateEvent" .../>
  <video dur="5s" repeatCount="3" end="activateEvent; next.activateEvent" .../>
  <video dur="5s" repeatCount="3" end="activateEvent; next.activateEvent" .../>
</seq>
...
</smil>

In this case, the active end of each element is defined to be the earlier of 15 (5s dur * 3 repeats) seconds after it begins, or a click on "next". This lets the viewer sit back and watch, or advance the presentation at a faster pace.

Handling negative offsets for end

This section is normative

The min and max attributes: more control over the active duration

This section is informative

The min/max attributes provide the author with a way to control the lower and upper bound of the element active duration.

This section is normative

min
Specifies the minimum value of the active duration.
The attribute value can be either of the following:
Clock-value
Specifies the length of the minimum value of the active duration, measured in element active time.
Value must be greater than or equal to 0.
"media"
Specifies the minimum value of the active duration as the intrinsic media duration. This is only valid for elements that define media.

If there is any error in the argument value syntax for min, the attribute will be ignored (as though it were not specified).

The default value for min is "0". This does not constrain the active duration at all.

max
Specifies the maximum value of the active duration.
The attribute value can be either of the following:
Clock-value
Specifies the length of the maximum value of the active duration, measured in element active time.
Value must be greater than 0.
"media"
Specifies the maximum value of the active duration as the intrinsic media duration. This is only valid for elements that define media.
"indefinite"
The maximum value of the duration is indefinite, and so is not constrained.

If there is any error in the argument value syntax for max, the attribute will be ignored (as though it were not specified).

The default value for max is "indefinite". This does not constrain the active duration at all.

If the "media" argument value is specified for either min or max on an element that does not define media (e.g. on the SMIL 3.0 time container elements par, seq and excl), the respective attribute will be ignored (as though it were not specified). Contained media such as the children of a par are not considered media directly associated with the element.

If both min and max attributes are specified then the max value must be greater than or equal to the min value. If this requirement is not fulfilled then both attributes are ignored.

The rule to apply to compute the active duration of an element with min or max specified is the following: Each time the active duration of an element is computed (i.e. for each interval of the element if it begins more than once), this computation is made without taking into account the min and max attributes (by applying the algorithm described in Computing the active duration). The result of this step is checked against the min and max bounds. If the result is within the bounds, this first computed value is correct. Otherwise two situations may occur:

This section is informative

The following examples illustrate some simple use cases for min and max attributes:

Example 1. In the following example, the video will only play for 10 seconds.

<smil ...>
...
<par >
   <video id="video_of_15s" max="10s".../>
</par>
...
</smil>

Example 2. In the following example, if an activate event happens before 10 seconds, this activation (e.g. click) does not interrupt the video immediately, but the video plays until 10 seconds and then stops. If a click event happens after 10 seconds, the video plays (repeating) until the click happens. Note, the endEvent is only raised if a click occurs after 10 seconds, not at the simple end of each repeat.

<smil ...>
...
<par >
   <video id="video_of_15s" repeatDur="indefinite" end="activateEvent" min="10s".../>
</par>
...
</smil>

Example 3. In the following example, if an activate event happens on element "foo" at 5 seconds, this event does not end the time container immediately, but rather at 12 seconds. The simple duration is defined to be "indefinite" (because an end attribute is specified with no dur attribute), and so the time container plays normally until it ends at 12 seconds.

<smil ...>
...
<par end="foo.activateEvent" min="12s" >
   <video id="video_of_15s" .../>
   <video id="video_of_10s" .../>
</par>
...
</smil>

Example 4. In the following example, if a click event happens on the first video at 5 seconds, then the simple duration of the time container is computed as 5 seconds. Respecting the fill attribute in the time between the end of the simple duration and the end of the active duration, the two videos are frozen between 5 seconds and 12 seconds.

<html ...>
...
<par endsync="first" min="12s" fill="freeze" >
   <video id="video_of_15s" end="click" ...>
   <video id="video_of_10s" .../>
</par>
...
</html>

Example 5. In the following example, the time container simple duration is defined to be 5 seconds, and the min constraint defines the active duration to be 12 seconds. Since the default value of fill in this case is "remove", nothing is shown for the time container between 5 seconds and 12 seconds.

<par dur="5s" min="12s" >
   <video id="video_of_15s"/>
   <video id="video_of_10s" />
</par>
The min attribute and negative begin times

If an element is defined to begin before its parent (e.g. with a simple negative offset value), the min duration is measured from the calculated begin time not the observed begin (see example 1 below). This means that the min value may have no observed effect (as in example 2 below).

Example 1. In the following example, the image will be displayed from the beginning of the time container for 2 seconds.

<par> 
   <img id="img" begin="-5s" min="7s" dur="5s" .../>
</par>

Example 2. In the following example, the image will not be displayed at all.

<par>
   <img id="img" begin="-5s" min="4s" dur="2s" .../>
</par>

See also the sections The min attribute and restart and Time container constraints on child durations.

Timing attribute value grammars

This section is normative

The syntax specifications are defined using EBNF notation as defined in XML 1.1 [XML11]

In the syntax specifications that follow, allowed white space is indicated as "S", defined as follows (taken from the [XML11] definition for 'S'):

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

This section is normative

A begin-value-list is a semi-colon separated list of timing specifiers:

begin-value-list ::= begin-value (S? ";" S? begin-value-list )?
begin-value      ::= (offset-value | syncbase-value 
                      | event-value | repeat-value | accesskey-value
                      | media-marker-value | wallclock-sync-value
                      | "indefinite" )
End values

This section is normative

An end-value-list is a semi-colon separated list of timing specifiers:

end-value-list ::= end-value (S? ";" S? end-value-list )?
end-value      ::= (offset-value | syncbase-value 
                      | event-value | repeat-value | accesskey-value
                      | media-marker-value | wallclock-sync-value
                      | "indefinite" )
Parsing timing specifiers

Several of the timing specification values have a similar syntax. To parse an individual item in a value-list, the following approach defines the correct interpretation. In addition, Id-values and Event-symbols are XML NMTOKEN values and as such are allowed to contain the full stop '.' and hyphen-minus '-' characters. The reverse solidus character '\' must be used to escape these characters within Id-values and Event-symbols, otherwise these characters will be interpreted as the full stop separator and hyphen-minus sign, respectively. Once these rules are interpreted, but before Id-values in syncbase values, event values, or media-marker values are further handled, all leading and embedded escape characters should be removed.

  1. Strip any leading, trailing, or intervening white space characters.
  2. If the value begins with a number or numeric sign indicator (i.e. '+' or '-'), the value should be parsed as an offset value.
  3. Else if the value begins with the unescaped token "wallclock", it should be parsed as a wallclock-sync-value.
  4. Else if the value is the unescaped token "indefinite", it should be parsed as the value "indefinite".
  5. Else: Build a token substring up to but not including any sign indicator (i.e. strip off any offset, parse that separately, and add it to the result of this step). In the following, any '.' characters preceded by a reverse solidus '\' escape character should not be treated as a separator, but as a normal token character.
    1. If the token contains no '.' separator character, then the value should be parsed as an event-value with an unspecified (i.e. default) eventbase-element.
    2. Else if the token ends with the unescaped string ".begin" or ".end", then the value should be parsed as a syncbase-value.
    3. Else if the token contains the unescaped string ".marker(", then the value should be parsed as a media-marker-value.
    4. Else, the value should be parsed as an event-value (with a specified eventbase-element).

This approach allows implementations to treat the tokens wallclock and indefinite as reserved element IDs, and begin, end and marker as reserved event names, while retaining an escape mechanism so that elements and events with those names may be referenced.

Clock values

Clock values have the following syntax:

Clock-value         ::= ( Full-clock-value | Partial-clock-value | Timecount-value )
Full-clock-value    ::= Hours ":" Minutes ":" Seconds ("." Fraction)?
Partial-clock-value ::= Minutes ":" Seconds ("." Fraction)?
Timecount-value     ::= 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
Fraction            ::= DIGIT+
Timecount           ::= DIGIT+
2DIGIT              ::= DIGIT DIGIT
DIGIT               ::= [0-9]

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

No embedded white space is allowed in clock values, although leading and trailing white space characters will be ignored.

The following are examples of legal clock values:

Fractional values are just (base 10) floating point definitions of seconds. The number of digits allowed is unlimited (although actual precision may vary among implementations).

For example:

00.5s = 500 milliseconds
00:00.005 = 5 milliseconds
Offset values

Offset values are used to specify when an element should begin or end relative to its syncbase.

This section is normative

An offset value has the following syntax:

offset-value   ::= ( S? ("+" | "-") S? )? ( Clock-value )

The implicit syncbase for an offset value is dependent upon the time container:

SMIL 1.0 begin and end values

Deprecated.

smil-1-syncbase-value  ::= "id(" Id-value ")" 
                           ( "(" ( "begin" | "end" | Clock-value) ")" )?
ID-Reference values

This section is normative

ID reference values are references to the value of an "id" attribute of another element in the document.

Id-value                   ::= Id-ref-value
Id-ref-value                ::= IDREF | Escaped-Id-ref-value
Escaped-Id-ref-value        ::= Escape-Char NMTOKEN
Escape-Char                ::= "\"

If the element referenced by the IDREF is ignored as described in the Content Control modules (e.g. if it specifies test attributes that evaluate false), the associated time value (i.e.. the syncbase value or the eventbase value that specifies the Id-value) will be considered invalid.

This section is informative

The semantics of ignored elements may change in a future version of SMIL. One possible semantic is that the associated sync arc arguments will not be invalid, but will instead always be "unresolved". When this behavior needs to be simulated in this version of SMIL Timing and Synchronization, an author can include the value "indefinite" in the list of values for the begin or end attribute.

Syncbase values

A syncbase value starts with a Syncbase-element term defining the value of an "id" attribute of another element referred to as the syncbase element.

This section is normative

A syncbase value has the following syntax:

Syncbase-value ::= ( Syncbase-element "." Time-symbol )
( S? ("+"|"-") S? Clock-value )?
Syncbase-element ::= Id-value
Time-symbol ::= "begin" | "end"

The syncbase element is qualified with one of the following time symbols:

begin
Specifies the begin time of the syncbase element.
end
Specifies the Active End of the syncbase element.

Examples

begin="x.end-5s" : Begin 5 seconds before "x" ends
begin=" x.begin " : Begin when "x" begins
end="x.begin + 1min" : End 1 minute after "x" begins

Event values

This section is informative

An Event value starts with an Eventbase-element term that specifies the event-base element. The event-base element is the element on which the event is observed. Given DOM event bubbling, the event-base element may be either the element that raised the event, or it may be an ancestor element on which the bubbled event can be observed. Refer to DOM-Level2-Events [DOM2Events] for details.

This section is normative

An event value has the following syntax:

Event-value ::= ( Eventbase-element "." )? Event-symbol
( S? ("+"|"-") S? Clock-value )?
Eventbase-element ::= ID

The eventbase-element must be another element contained in the host document.

If the Eventbase-element term is missing, the event-base element defaults to the element on which the eventbase timing is specified (the current element). A host language designer may override the definition of the default eventbase element. As an example of this, the SMIL 3.0 Animation modules describe Timing integration requirements for the animation elements (animate, animateMotion, etc.). These requirements specify that the default eventbase element is the target element of the animation. See SMIL 2 Animation section 3.9.1 (Integration requirements).

The event value must specify an Event-symbol. This term is an XML NMTOKEN that specifies the name of the event that is raised on the Event-base element. The host language designer must specify which events can be specified.

The last term specifies an optional offset-value that is an offset from the time of the event.

This section is informative

This module defines several events that may be included in the supported set for a host language, including beginEvent and endEvent. These should not be confused with the syncbase time values. See the section on Events and event model.

The semantics of event-based timing are detailed in Unifying Scheduling and Interactive Timing. Constraints on event sensitivity are detailed in Event sensitivity.

Examples:

begin=" x.load " : Begin when "load" is observed on "x"
begin="x.focus+3s" : Begin 3 seconds after a "focus" event on "x"
begin="x.endEvent+1.5s" : Begin 1 and a half seconds after an "endEvent" event on "x"
begin="x.repeat" : Begin each time a repeat event is observed on "x"

The following example describes a qualified repeat eventbase value:

<html ...>
...
<video id="foo" repeatCount="10" end="endVideo.click" ... />
<img id="endVideo" begin="foo.repeat(2)" .../>
...
</html>

The "endVideo" image will appear when the video "foo" repeats the second time. This example allows the user to stop the video after it has played though at least twice.

Repeat values

Repeat values are a variant on event values that support a qualified repeat event. The repeat event defined in Events and event model allows an additional suffix to qualify the event based upon an iteration value.

A repeat value has the following syntax:

Repeat-value ::= ( Eventbase-element "." )? "repeat(" iteration ")"
( S? ("+"|"-") S? Clock-value )?
iteration ::= DIGIT+

If this qualified form is used, the eventbase value will only be resolved when a repeat is observed that has a iteration value that matches the specified iteration.

The qualified repeat event syntax allows an author to respond only to an individual repeat of an element.

Accesskey values

Accesskey values allow an author to tie a begin or end time to a particular key press, independent of focus issues. It is modeled on the HTML accesskey support. Unlike with HTML, user agents should not require that a modifier key (such as "ALT") be required to activate an access key.

An access key value has the following syntax:

Accesskey-value ::= "accesskey(" character ")"
( S? ("+"|"-") S? Clock-value )?

The character is a single character from [ISO10646].

The time value is defined as the time that the access key character is input by the user.

Media marker values

Certain types of media can have associated marker values that associate a name with a particular point (i.e. a time) in the media. The media marker value provides a means of defining a begin or end time in terms of these marker values. Note that if the referenced id is not associated with a media element that supports markers, or if the specified marker name is not defined by the media element, the associated time may never be resolved.

This section is normative

Media-Marker-value ::= Id-value ".marker(" S? marker-name S? ")"

Wallclock-sync values

This section is informative

Wallclock-sync values have the following syntax. The values allowed are based upon several of the "profiles" described in [DATETIME], which is based upon [ISO8601].

This section is normative

wallclock-sync-value  ::= "wallclock(" S? (DateTime | WallTime | Date)  S? ")"
DateTime       ::= Date "T" WallTime
Date           ::= Years "-" Months "-" Days
WallTime       ::= (HHMM-Time | HHMMSS-Time)(TZD)?
HHMM-Time      ::= Hours24 ":" Minutes
HHMMSS-Time    ::= Hours24 ":" Minutes ":" Seconds ("." Fraction)?
Years          ::= 4DIGIT;
Months         ::= 2DIGIT; range from 01 to 12
Days           ::= 2DIGIT; range from 01 to 31
Hours24        ::= 2DIGIT; range from 00 to 23
4DIGIT         ::= DIGIT DIGIT DIGIT DIGIT
TZD            ::= "Z" | (("+" | "-") Hours24 ":" Minutes )

This section is informative

Complete date plus hours and minutes:

   YYYY-MM-DDThh:mmTZD (e.g. 1997-07-16T19:20+01:00)

Complete date plus hours, minutes and seconds:

   YYYY-MM-DDThh:mm:ssTZD (e.g. 1997-07-16T19:20:30+01:00)

Complete date plus hours, minutes, seconds and a decimal fraction of a second

   YYYY-MM-DDThh:mm:ss.sTZD (e.g. 1997-07-16T19:20:30.45+01:00)

Note that the Minutes, Seconds, Fraction, 2DIGIT and DIGIT syntax is as defined for Clock-values. Note that white space is not allowed within the date and time specification.

This section is normative

There are three ways of handling time zone offsets:

  1. Times are expressed in UTC (Coordinated Universal Time), with a special UTC designator ("Z").
  2. Times are expressed in local time, together with a time zone offset in hours and minutes. A time zone offset of "+hh:mm" indicates that the date/time uses a local time zone which is "hh" hours and "mm" minutes ahead of UTC. A time zone offset of "-hh:mm" indicates that the date/time uses a local time zone which is "hh" hours and "mm" minutes behind UTC.
  3. Times are expressed in local time, as defined for the presentation location. The local time zone of the end-user platform is used.

The presentation engine must be able to convert wallclock-values to a time within the document.

This section is informative

Note that the resulting begin or end time may be before the begin, or after end of the parent time container. This is not an error, but the time container constraints still apply. In any case, the semantics of the begin and end attribute govern the interpretation of the wallclock value.

Examples

The following examples all specify a begin at midnight on January 1st 2000, UTC:

begin="wallclock( 2000-01-01T00:00Z )"
begin="wallclock( 2000-01-01T00:00:00Z )"
begin="wallclock( 2000-01-01T00:00:00.0Z )"
begin="wallclock( 2000-01-01T00:00:00.0Z )"
begin="wallclock( 2000-01-01T00:00:00.0-00:00 )"

The following example specifies a begin at 3:30 in the afternoon