SVG Tiny 1.2 - 20050413

12 Multimedia

Contents

12.1 Media elements

SVG supports media elements similar to the SMIL Media Elements. Media elements define their own timelines within their time container. All SVG Media elements support the SVG Timing attributes and run time synchronization.

The following elements are media elements:

12.2 The 'audio' element

The audio element specifies an audio file which is to be rendered to provide synchronized audio. The usual SMIL timing features are used to start and stop the audio at the appropriate times. An xlink:href is used to link to the audio content. No visual representation is produced. However, content authors can if desired create graphical representations of control panels to start, stop, pause, rewind, or adjust the volume of audio content.

Schema: audio
  <define name='audio'>
    <element name='audio'>
      <ref name='audio.AT'/>
      <ref name='audio.CM'/>
    </element>
  </define>

  <define name='audio.AT' combine='interleave'>
    <ref name='svg.Core.attr'/>
    <ref name='svg.XLinkEmbed.attr'/>
    <ref name='svg.Conditional.attr'/>
    <ref name='svg.External.attr'/>
    <ref name='svg.AnimateTimingNoFillNoMinMax.attr'/>
    <ref name='svg.AnimateSync.attr'/>
    <ref name='svg.Media.attr'/>
    <ref name='svg.ContentType.attr'/>
  </define>

  <define name='audio.CM'>
    <zeroOrMore>
      <choice>
        <ref name='svg.Desc.group'/>
        <ref name='svg.Animate.group'/>
        <ref name='svg.Handler.group'/>
        <ref name='svg.Discard.group'/>
      </choice>
    </zeroOrMore>
  </define>
    

Attribute definitions:

xlink:href = "<iri>"
An IRI reference.

Animatable: yes.
type = "<media/type>"
The audio format.

Animatable: no.

This element also supports all Run-time synchronization attributes and SVG Timing attributes.

The following example illustrates the use of the audio element. When the button is pushed, the audio file is played three times.

Example: media01.svg

<svg width="100%" height="100%" version="1.2" baseProfile="tiny"
     xmlns="http://www.w3.org/2000/svg"
     xmlns:xlink="http://www.w3.org/1999/xlink">

  <desc>SVG audio example</desc>

  <audio xlink:href="ouch.ogg" volume="0.7" type="application/ogg"
        begin="mybutton.click" repeatCount="3"/>

  <g id="mybutton">
    <rect width="150" height="50" x="20" y="20" rx="10"
      fill="#ffd" stroke="#933" stroke-width="5"/>
    <text x="95" y="55" text-anchor="middle" font-size="30"
      fill="#933">Press Me</text>
  </g>

  <rect x="0" y="0" width="190" height="90" fill="none" stroke="#777"/>

</svg>    

When rendered, this looks as follows:

Example of the audio element triggered by a button

This specification does not mandate support for any particular audio format. Content can check for a particular audio codec with the requiredFormats test attribute.

12.3 The 'video' element

The video element specifies a video file which is to be rendered to provide synchronized video. It should not point to other types of media. The usual SMIL timing features are used to start and stop the video at the appropriate times. An xlink:href is used to link to the video content. It is assumed that the video content may also include an audio stream, since this is the usual way that video content is produced, and thus the audio is controlled by the video element's media attributes.

The video element produces a rendered result, and thus has width, height, x and y attributes.

A 'video' element establishes a new viewport for the referenced file as described in Establishing a new viewport. Therefore the video element supports the 'viewport-fill' and 'viewport-fill-opacity' properties. The bounds for the new viewport are defined by attributes x, y, width and height. The placement and scaling of the referenced video is controlled by the preserveAspectRatio attribute on the 'video' element.

The value of the 'viewBox' attribute to use when evaluating the preserveAspectRatio attribute is defined by the referenced content. For content that clearly identifies a viewBox that value should be used. For most video content the bounds of the video should be used (i.e. the 'video' element has an implicit 'viewBox' of "0 0 video-width video-height"). Where no value is readily available the preserveAspectRatio attribute is ignored.

Schema: video
  <define name='video'>
    <element name='video'>
      <ref name='video.AT'/>
      <ref name='video.CM'/>
    </element>
  </define>

  <define name='video.AT' combine='interleave'>
    <ref name='svg.Core.attr'/>
    <ref name='svg.Media.attr'/>
    <ref name='svg.XLinkEmbed.attr'/>
    <ref name='svg.Conditional.attr'/>
    <ref name='svg.External.attr'/>
    <ref name='svg.AnimateTimingNoFillNoMinMax.attr'/>
    <ref name='svg.AnimateSync.attr'/>
    <ref name='svg.Focus.attr'/>
    <ref name='svg.Transform.attr'/>
    <ref name='svg.XYWH.attr'/>
    <ref name='svg.PAR.attr'/>
    <ref name='svg.ContentType.attr'/>
    <optional>
      <attribute name='transformBehavior' a:defaultValue='geometric' svg:animatable='no' svg:inheritable='false'>
        <choice>
          <value>geometric</value>
          <value>pinned</value>
        </choice>
      </attribute>
    </optional>
    <optional>
      <attribute name='overlay' a:defaultValue='none' svg:animatable='no' svg:inheritable='false'>
        <choice>
          <value>none</value>
          <value>top</value>
        </choice>
      </attribute>
    </optional>
  </define>

  <define name='video.CM'>
    <zeroOrMore>
      <choice>
        <ref name='svg.Desc.group'/>
        <ref name='svg.Animate.group'/>
        <ref name='svg.Handler.group'/>
        <ref name='svg.Discard.group'/>
      </choice>
    </zeroOrMore>
  </define>
    

Attribute definitions:

x = "<coordinate>"
The x-axis coordinate of one corner of the rectangular region into which the video is placed.

If the attribute is not specified, the effect is as if a value of "0" were specified.

Animatable: yes.
y = "<coordinate>"
The y-axis coordinate of one corner of the rectangular region into which the video is placed.

If the attribute is not specified, the effect is as if a value of "0" were specified.

Animatable: yes.
width = "<length>"
The width of the rectangular region into which the video is placed.

A negative value is an error (see Error processing). A value of zero disables rendering of the element.

Animatable: yes.
height = "<length>"
The height of the rectangular region into which the video is placed.

A negative value is an error (see Error processing). A value of zero disables rendering of the element.

Animatable: yes.
xlink:href = "<iri>"
An IRI reference.

Animatable: yes.
preserveAspectRatio = [defer] <align> [<meetOrSlice>]
Indicates whether or not to force uniform scaling. (See The preserveAspectRatio attribute for the syntax of <align> and the interpretation of this attribute.)

Animatable: yes.
type = "<media/type>"
The video format.

Animatable: no.
transformBehavior = "geometric | pinned"
See the transformBehavior attribute.
overlay = "top | none"
See the overlay attribute.

This element also supports all Run-time synchronization attributes and SVG Timing attributes.

The following example illustrates the use of the 'video' element. The video content is partially obscured by other graphics elements. This example shows the video element being rendered into an offscreen buffer and then transformed and composited in the normal way, so that it behaves like any other graphical primitive such as an image or a rectangle. Like this, the video element may be scaled, rotated, skewed, displayed at various sizes, and animated.

Example: media02.svg
<svg xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     width="420" height="340" viewBox="0 0 420 340">
  <desc>SVG 1.2 video example</desc>
    <g>
    <circle cx="0" cy="0" r="170" fill="#da4" fill-opacity="0.3"/>
    <video xlink:href="noonoo.avi" volume=".8" type="video/x-msvideo"
         width="320" height="240" x="50" y="50" repeatCount="indefinite"/>
    <circle cx="420" cy="340" r="170" fill="#927" fill-opacity="0.3"/>
    <rect x="1" y="1" width="418" height="338" fill="none"
       stroke="#777" stroke-width="1"/>
    </g>
</svg>
    

Show this example of the video element (requires an SVG 1.2 viewer and support for a Windows AVI using Motion JPEG. This is a 3.7M video file).

When rendered, this looks as follows:

Example of the video element partially obscured by regular SVG graphics

This specification does not mandate support for any particular video format. Content can check for a particular video codec with the requiredFormats test attribute.

The content creator should be aware that video is a feature that may not be available on all target devices. In order to create interoperable content the content creator should provide a fall-back alternative by using the 'switch' element. The following feature string is defined for checking for video support: http://www.w3.org/TR/SVG12/feature#Video. Video may not be completely supported on a resource limited device. SVGT 1.2 introduces more granular video rendering control to provide reproducible results in all environments. This control is documented in the two following sections.

12.3.1 Restricting the transformation of the 'video' element

Transforming video is an expensive operation that should be used with caution, especially on content targeted for mobile devices. Using transformed video may also lead to non-interoperable content since not all devices will support this feature. To give the content creator control over video transformation SVGT 1.2 introduces the transformBehavior attribute and a corresponding feature string: http://www.w3.org/TR/SVG12/feature#TransformedVideo. A viewer supporting video transformation must treat the 'video' element like any other element regarding transformations. A viewer not supporting video transformation treats the video as a point (given by x and y attributes). The width and height attributes are ignored if present and instead the width and height (in device pixels) are taken from the media itself. The video is displayed with its center aligned with the origin of the local coordinate system.

A content creator can use the transformBehavior attribute to explicitly choose the transform behavior on a viewer supporting transformed video. This might be of interest to increase the performance of content targeting restricted devices.

Attribute definition:

transformBehavior = "geometric" | "pinned"
Define whether a video is transformed/resampled (in essence treated as a geometric rectangle) or pinned/unresampled (ie, treated as a pin point for a non-geometric blit region).

The attribute value can be either of the following:
"geometric"
the media is treated as a geometric rectangle in the local coordinate system, defined by x y width and height attributes. the media is resampled to fill the rectangle and is subject to transformation. This is the default transformBehavior
"pinned"
The media is treated as a point, defined by x and y attributes. This point is transformed to the nearest actual device pixel. Video at the native resolution given by the media is then painted on a region whose center is the pin point and whose width and height are defined by the media. The pixels are aligned to the device pixel grid and no resampling will be done.


Animatable: no.

12.3.2 Restricting compositing of the 'video' element

For the same reasons as restricting transformations the content creator might need to restrict the compositing of video with other elements. Not all devices support compositing of the video element with other content. In that case it is necessary to render the video on top of all other svg content. SVGT1.2 therefore introduces the overlay attribute and a corresponding feature string: http://www.w3.org/TR/SVG12/feature#ComposedVideo. A viewer supporting compositing of video must render the video element according to the svg painters model, graphical elements might be rendered on top of the video. A viewer not supporting video compositing will always render the video on top of all other svg elements.

A content creator can use the overlay attribute to explicitly choose the compositing behavior on a viewer supporting composited video. This may increase the performance of content that is targeted at restricted devices.

Attribute definition:

overlay = "top" | "none"
Define whether a 'video' is rendered according to the svg painters model or if it should be positioned on top of all other svg elements.

The attribute value can be either of the following:
"top"
When a 'video' element has the overlay set to 'top' it is not composited to the background as usual. Instead a temporary video canvas is set aside and drawn last in the whole document's compositing process.
"none"
The 'video' is rendered according to the svg painters model. This is the default overlay behavior.


Animatable: no.

If multiple 'video' elements have overlay='top', the drawing order between those 'video' elements is document order.

12.3.3 Example

The following example illustrates the use of the TransformedVideo feature string. A switch element is wrapped around two groups, the first group will render a scaled and rotated video sequence on a viewer supporting video transformations while the second group will render the untransformed video on viewers that doesn't support video transformations.

Example: media04.svg
<svg version="1.2" baseProfile="tiny" xmlns="http://www.w3.org/2000/svg"
     width="100%" height="100%" viewBox="0 0 400 300">
     <desc>Example of switching on the TransformedVideo feature string</desc>
     <switch>

       <!-- Transformed video group -->
       <g requiredFeatures="http://www.w3.org/TR/SVG12/feature#TransformedVideo"
             transform="translate(-21,-34) scale(1.24) rotate(-30)">
         <rect x="6" y="166" width="184" height="140" fill="none" stroke="blue"
                  stroke-width="4" />
         <video xlink:href="ski.avi" volume=".8" type="video/x-msvideo"
                   x="10" y="170" width="176" height="132"/>
       </g>

       <!-- Untransformed video group -->
       <g>
         <rect x="6" y="166" width="184" height="140" fill="none" stroke="blue"
                  stroke-width="4"/>
         <video xlink:href="ski.avi" volume=".8" type="video/x-msvideo"
                   x="10" y="170"/>
       </g>
     </switch>
</svg>     

Screenshot of the example above rendered on two viewers, the first one supporting transformed video, the second one not:

image showing the difference between transformed and untransformed video rendering

12.4 The 'animation' element

The animation elements specifies an SVG document or an SVG document fragment providing synchronized animated vector graphics. Like video, the animation element is a graphical object with size determined by its x, y, width and height attributes.

While somewhat similar (both reference svg content), the behaviour of the 'animation' element is different from the 'use' element. The 'use' element makes a conceptual reference to the original content while the 'animation' element makes a duplicate of the original content. Furthermore the 'animation' element supports timing and synchronisation attributes which allows multiple animations to run with independent timelines in the same svg document.

Besides what is described about the 'animation' element in this section, important restrictions for 'animation' can be found in the Reference Section.

An 'animation' element referencing an SVG Document establishes a new viewport for the referenced file as described in Establishing a new viewport. The bounds for the new viewport are defined by attributes 'x', 'y', 'width' and 'height'. The placement and scaling of the referenced image are controlled by the 'preserveAspectRatio' attribute on the 'animation' element.

An 'animation' element referencing an SVG document fragment do not establish a new viewport, and the 'width' and 'height' attributes must be ignored.

When an 'animation' element references an SVG Document the 'preserveAspectRatio' attribute on the root element in the referenced SVG Document is ignored (in the same manner as the x, y, width and height attributes are ignored). Instead, the 'preserveAspectRatio' attribute on the referencing 'animation' element defines how the SVG content is fitted into the viewport. The same rule applies for the 'viewport-fill' and 'viewport-fill-opacity' properties.

The value of the 'viewBox' attribute to use when evaluating the 'preserveAspectRatio' attribute is defined by the referenced content. For 'animation' elements that references an SVG Document the 'viewBox' value of that document is used. When no value is available the 'preserveAspectRatio' attribute is ignored, and only the translate due to the 'x' & 'y' attributes of the viewport is used to display the content.

The usual SMIL timing features are used to start and stop the animation at the appropriate times. The xlink:href attribute refers to the vector graphics content that is to be animated. The restrictions listed in the Reference section need to be met, otherwise the document is in error.

In the case where the animation element references an external SVG document the external document represents a separate document which generates its own parse tree and document object model (if the resource is XML). Thus, there is no inheritance of properties into the referenced animation. For details, see Externally referenced documents.

In the case where the animation element references an SVG document fragment, the conceptual processing model is that the entire document containing the fragment is processed as a complete SVG document instance (coordinate systems transformations and stylesheets are applied; scripts are executed; etc.). The document is conceptually rendered to an invisible (offscreen) canvas except for the referenced fragment which is rendered directly to the screen canvas. When the animation element references a document fragment the 'preserveAspectRatio', 'width' and 'height' attributes have no meaning. The rules for applying 'x' and 'y' are the same set of rules that apply for the 'use' element.

The animation element supports the 'overflow' property.

Schema: animation
  <define name='animation'>
    <element name='animation'>
      <ref name='animation.AT'/>
      <ref name='animation.CM'/>
    </element>
  </define>

  <define name='animation.AT' combine='interleave'>
    <ref name='svg.Core.attr'/>
    <ref name='svg.Media.attr'/>
    <ref name='svg.Conditional.attr'/>
    <ref name='svg.External.attr'/>
    <ref name='svg.XLinkEmbed.attr'/>
    <ref name='svg.Focus.attr'/>
    <ref name='svg.AnimateTimingNoMinMax.attr'/>
    <ref name='svg.AnimateSync.attr'/>
    <ref name='svg.XYWH.attr'/>
    <ref name='svg.PAR.attr'/>
    <ref name='svg.Overflow.attr'/>
  </define>

  <define name='animation.CM'>
    <zeroOrMore>
      <choice>
        <ref name='svg.Desc.group'/>
        <ref name='svg.Animate.group'/>
        <ref name='svg.Discard.group'/>
        <ref name='svg.Handler.group'/>
      </choice>
    </zeroOrMore>
  </define>
    

Attribute definitions:

x = "<coordinate>"
The x-axis coordinate of one corner of the rectangular region into which the animation is placed.

If the attribute is not specified, the effect is as if a value of "0" were specified.

Animatable: yes.
y = "<coordinate>"
The y-axis coordinate of one corner of the rectangular region into which the animation is placed.

If the attribute is not specified, the effect is as if a value of "0" were specified.

Animatable: yes.
width = "<length>"
The width of the rectangular region into which the animation is placed.

A negative value is an error (see Error processing). A value of zero disables rendering of the element.

Animatable: yes.
height = "<length>"
The height of the rectangular region into which the animation is placed.

A negative value is an error (see Error processing). A value of zero disables rendering of the element.

Animatable: yes.
xlink:href = "<iri>"
An IRI reference.

Animatable: yes.
preserveAspectRatio = [defer] <align> [<meetOrSlice>]
Indicates whether or not to force uniform scaling. (See The preserveAspectRatio attribute for the syntax of <align> and the interpretation of this attribute.)

Animatable: yes.

This element also supports all Run-time synchronization attributes and SVG Timing attributes.

Example: media03.svg

<svg xmlns="http://www.w3.org/2000/svg"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     version="1.2" baseProfile="tiny">
     
  <desc>Example of the animation element.</desc>

  <defs>
    <rect id="movieClip" x="-50" y="-50" width="100" height="100"
          fill="purple" stroke="black">

      <animate attributeName="fill" values="purple;yellow;purple"
               keyTimes="0;.5;1" begin="0" dur="2" fill="freeze"/>

   </rect>
  </defs>


  <animation begin="1" dur="3" repeatCount="1.5" fill="freeze"
             x="100 y="100" xlink:href="#movieClip"/>

  <animation begin="2" x="100" y="300" xlink:href="#movieClip"/>

</svg>    

12.5 The audio-level property

The audio-level property can be applied to the 'audio', 'video' and 'animation' elements described above, plus container elements such as the 'g' element.

audio-level
Value: <float>
Initial: 1
Applies to: audio, video, animation and container elements
Inherited: no
Percentages: N/A
Media: visual, audible
Animatable: yes

The audio-level property specifies a value between 0 and 1 that is used to calculate the volume of a particular element. Values above 1 and below 0 are clipped.

An element's volume is the product of its audio-level property and the element volume of its parent. The exception to this rule is the root element, where the element volume is only the value of its audio-level property. Therefore, element volume is calculated in a similar way to opacity.

If the audio-level of an element to a value less than 1.0, all children elements will be quieter. It is not possible to increase the volume on an element.

The output signal level is calculated using the logarithmic scale described below (where vol is the value of the element volume):

dB change in signal level = 20 * log10(vol)

If the element has an element volume of 0, then the output signal will be inaudible. If the element has an element volume of 1, then the output signal will be at the system volume level. Neither the audio-level property or the element volume override the system volume setting.

12.6 Attributes for run-time synchronization

SVG supports the four attributes listed below from SMIL 2 to control run-time synchronization of different time containers. In SVGT1.2 these attributes apply to <video>, <audio> and <animation>.

The normative definition for these attributes is the SMIL 2 specification.

Animatable: no

12.7 Audio Module

The Audio Module contains the following element:

12.8 Video Module

The Video Module contains the following element:

12.9 Animation Module

The Animation Module contains the following element: