How to Define Custom Tests in SMIL 3.0?

Synchronized Multimedia Integration Language (SMIL) 3.0 allows authors to create adaptive, conditional multimedia presentations using the customTest element within the Content Control module. By declaring custom test rules inside the document head, authors can define application-specific flags, user preferences, or runtime conditions that determine whether specific elements and media streams are evaluated, rendered, or skipped during playback.

Declaring Custom Tests in the Document Head

Custom test attributes must be defined inside the <customAttributes> container within the SMIL <head> element before they can be referenced in the document body. Each <customTest> element defines a distinct boolean condition along with its default state and control behavior.

The key attributes supported by the <customTest> element include:

id: A unique XML identifier used to reference this specific test rule elsewhere in the SMIL document.
defaultState: Specifies the initial evaluation state of the test rule, set to either true or false. If omitted, the default is false.
override: Defines whether the user or runtime environment can override the author's declared state. Values include visible (the test is exposed to the user interface for toggling) or hidden (the rule remains strictly internal or programmatic).
uid: An optional URI string providing a globally unique identifier for standardizing test meanings across multiple documents or players.

<smil xmlns="http://www.w3.org/ns/SMIL" version="3.0" baseProfile="Language">
  <head>
    <customAttributes>
      <customTest id="directorCommentary" 
                  defaultState="false" 
                  override="visible" 
                  uid="http://example.org/tests/commentary" />
      <customTest id="highBandwidth" 
                  defaultState="true" 
                  override="hidden" />
    </customAttributes>
  </head>
  <body>
    <!-- Content logic references tests here -->
  </body>
</smil>

Applying Custom Test Attributes in the Document Body

Once a customTest has been declared, media elements, timing containers, and grouping structures can link to it using the customTest attribute.

When applied to an element, the playback engine checks the current evaluation state of the referenced ID:

If the condition evaluates to true, the element plays as normal.
If the condition evaluates to false, the element is ignored in the presentation timeline.

<body>
  <par>
    <video src="movie.mp4" />
    <audio src="commentary.mp3" customTest="directorCommentary" />
  </par>
</body>

Using Custom Tests with Switch Elements

Custom tests can also be integrated into SMIL <switch> structures to provide fallback behaviors and alternative content tracks. The player evaluates the children of a <switch> sequentially and renders the first element whose conditions evaluate to true.

<switch>
  <video src="main_hd.mp4" customTest="highBandwidth" />
  <video src="main_sd.mp4" />
</switch>

In this scenario, main_hd.mp4 will be rendered if highBandwidth evaluates to true. If disabled or unavailable, the player falls through to the standard-definition stream, ensuring uninterrupted playback across different user configurations and network environments.