SVG supports media elements similar to the SMIL 2.1 Media Elements ([SMIL21], chapter 7). Media elements define their own timelines within their time container. All SVG media elements support the SVG timing attributes and runtime synchronization attributes. The default event-base element for all SVG media elements is the element itself.
The following elements are media elements:
Media elements start playing when they become active, i.e. at a time specified in the document timeline which depends on their 'begin' attribute (see SVG timing attributes). However, depending on the value of the 'timelineBegin' attribute on the rootmost 'svg' element, the actual beginning of the document timeline may be delayed until the whole document is loaded. This is the case when 'timelineBegin' is set to 'onLoad'. In that case, the beginning of the actual playback of the media will be delayed, but the media begin time in the document timeline will remain as specified.
Note: 'image' elements are not considered as media elements because they are not timed. They start playing at time 0 in the document timeline.
The following examples illustrate this behavior:
In this example, the document timeline will start after the document is fully processed, i.e. at time t0+t1+t2 ≥ 6s. The video will start when the document is loaded. But, at that time, the document time will be 0. So, the video will start with the first frame of the video.
In this example, the document timeline will start when the 'svg' element is fully parsed and processed, i.e. at time t0. The video will also start at document time 0, but since the video will only be processed when document time is t0+t1+t2, the video will start displaying the frame at time t0+t1+t2 in the video timeline.
Furthermore, the time in the media timeline which is played, e.g. the exact frame of video or the exact sample of audio that is played, can be altered by the 'syncBehavior' attribute. The following examples illustrate this behavior. These examples are the same as the previous ones, but the values of the 'syncBehavior' attributes are changed from the default value to 'independent'.
In example video-timelineBegin-03.svg, the video does not start until the document's load event, whereas in example video-timelineBegin-04.svg, the video begins as soon as the video element is parsed and the video is ready for rendering. In both cases, since the timeline of the document and of the video are independent, when the video will start, it will start from the first frame, i.e. time 0 in the media timeline.
The value of the 'externalResourcesRequired' attribute may also delay the actual time at which a media (even images) will start playing, but it does not affect the time in the document timeline. Indeed, media elements and the image element may require external resources referenced by the 'xlink:href' attribute. If the 'externalResourcesRequired' attribute is set to 'true', on the resource or on a parent in the scene tree, e.g. a 'g' element, then this external resource has to become available before the media can start. If the 'externalResourcesRequired' attribute is set to 'false', the media element or the image element will start playing as soon as it becomes active.
The meaning of "available" depends on the media type, on the protocol used to access the resource as well as on the implementation. For example, if a protocol like HTTP is used, "available" may mean that the whole resource is downloaded. It may also mean that a coarse version of the resource is available, for example in case of progressive PNG (see PNG Pass extraction ([PNG], section 4.5.2)). In that case, it is an implementation choice to decide whether to display the coarse version before the whole resource is downloaded. Another example is when streaming protocols like RTSP/RTP are used. In that case, "available" usually means that enough stream has been buffered before the playback may start. To reduce the amount of time required for a media to become available, authors are encouraged to use the 'prefetch' element to signal that external resources have to be prefetched.
Particular platforms may have restrictions on the number of audio voices or channels that can be mixed, or the number of video streams that may be presented concurrently. Since these vary, the SVG language itself does not impose any such limits on audio or video.
If two or more audio streams from 'audio' or 'video' elements are active at the same time, their rendering should be mixed in proportions equal to the computed value of the 'audio-level' property of each audio stream. An audio stream may be active if it is referred to by an active audio element or if it is part of video content that is referred to by an active 'video' element.
Authors may wish to independently control both the visual and auditory aspects of the 'video' element. Through a combination of the various properties available, all permutations are possible, as described below:
In addition to setting fixed timeline attribute values or using declarative animation to control the playback of media elements such as 'audio', 'video', and 'animation', SVG allows scripted control. See the uDOM section on Multimedia control for details.
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' must be used to link to the audio content. No visual representation shall be 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.
The 'audio' element must reference content with an audio stream.
Attribute definitions:
An IRI reference. An invalid IRI reference is an unsupported value. An empty string value (xlink:href="") disables playback of the element. The lacuna value is the empty string.
When the value of this attribute is animated or otherwise modified, if the media timeline can be controlled, then the media timeline is restarted only if the 'syncBehavior' attribute is set to independent. If the media timeline cannot be controlled, then the media timeline is unaffected by such modification.
Animatable: yes.
The audio format. Implementations may choose not to fetch audios of formats that they do not support. For optimizing download time by requiring a particular content format authors are encouraged to use 'requiredFormats', instead of 'type'.
Animatable: yes.
The following example illustrates the use of the 'audio' element. When the button is pushed, the audio file is played three times.
This specification does not mandate support for any particular audio format. Content can check for a particular audio codec with the 'requiredFormats' conditional processing attribute.
The 'video' element specifies a video file which is to be rendered to provide synchronized video. The usual SMIL timing features are used to start and stop the video at the appropriate times. An 'xlink:href' must be 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 shall be controlled by the 'video' element's media attributes.
The 'video' element must reference content with a video stream.
The 'video' element produces a rendered result, and thus has 'width', 'height', 'x' and 'y' attributes.
The 'video' element can have two different transform behaviors, either geometric or pinned, depending on the value of the transformBehavior attribute. If the transform behavior is geometric, the 'video' element must establish a new viewport for the referenced document as described in Establishing a new viewport. In this case, the 'video' element supports the 'viewport-fill' and 'viewport-fill-opacity' properties. The bounds for the new viewport shall be defined by attributes 'x', 'y', 'width' and 'height'. The placement and scaling of the referenced video shall be controlled by the 'preserveAspectRatio' attribute on the 'video' element. In the case of pinned transform behavior, a new viewport must not be established. As such, 'viewport-fill', 'viewport-fill-opacity', 'width', 'height', or 'preserveAspectRatio' have no effect.
The value of the 'viewBox' attribute to use when evaluating the 'preserveAspectRatio' attribute shall be defined by the referenced content. For content that clearly identifies a 'viewBox' that value shall 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 shall be ignored.
Attribute definitions:
The x-axis coordinate of the rectangular region into which the video is placed. The lacuna value is '0'.
If the transform behavior of the video is geometric, this coordinate is one corner of the rectangular region. If it is pinned, this coordinate is the pin point of the rectangular region. See the 'transformBehavior' attribute for the interpretation of this attribute.
Animatable: yes.
The y-axis coordinate of the rectangular region into which the video is placed. The lacuna value is '0'.
If the transform behavior of the video is geometric, this coordinate is one corner of the rectangular region. If it is pinned, this coordinate is the pin point of the rectangular region. See the 'transformBehavior' for the interpretation of this attribute.
Animatable: yes.
The width of the rectangular region into which the video is placed. A negative value shall be treated as unsupported. The lacuna value is '0'.
If the transform behavior of the video is geometric, a value of zero shall disable rendering of the element. If it is pinned, this attribute shall have no effect on rendering.
Animatable: yes.
The height of the rectangular region into which the video is placed. A negative value shall be treated as unsupported. The lacuna value is '0'.
If the transform behavior of the video is geometric, a value of zero shall disable rendering of the element. If it is pinned, this attribute shall have no effect on rendering.
Animatable: yes.
An IRI reference to the video content. An invalid IRI reference is an unsupported value. An empty string value (xlink:href="") disables rendering of the element. The lacuna value is the empty string.
When the value of this attribute is animated or otherwise modified, if the media timeline can be controlled, then the media timeline is restarted only if the 'syncBehavior' attribute is set to independent. If the media timeline cannot be controlled, then the media timeline is unaffected by such modification.
Animatable: yes.
Indicates whether or not to force uniform scaling. (See the 'preserveAspectRatio' for the syntax of <align> and the interpretation of this attribute.)
Animatable: yes.The video format. Implementations may choose not to fetch videos of formats that they do not support. For optimizing download time by requiring a particular content format authors are encouraged to use 'requiredFormats', instead of 'type'.
Animatable: yes.
See attribute definition for description.
Animatable: no.
See attribute definition for description.
Animatable: no.
See attribute definition for description.
Animatable: no.
See attribute definition for description.
Animatable: yes.
See definition.
See definition.
See definition.
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. In this manner, the 'video' element may be scaled, rotated, skewed, displayed at various sizes, and animated.
Show this example of the 'video' element (requires an SVG Tiny 1.2 viewer and support for a Windows AVI using Motion JPEG; this is a 3.7M video file).
This specification does not mandate support for any particular video format. Content can check for a particular video codec with the 'requiredFormats' conditional processing 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/Graphics/SVG/feature/1.2/#Video. Video may not be completely supported on a resource limited device. SVG Tiny 1.2 introduces more granular video rendering control to provide reproducible results in all environments. This control is documented in the two following sections.
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, SVG Tiny 1.2 introduces the 'transformBehavior' attribute and a corresponding feature string: http://www.w3.org/Graphics/SVG/feature/1.2/#TransformedVideo. A viewer supporting video transformation must treat the 'video' element like any other element regarding transformations. A viewer not supporting video transformation must treat the video as a point (given by the 'x' and 'y' attributes). The 'width' and 'height' attributes shall be ignored if present and instead the width and height (in device pixels) shall be taken from the media itself. The video must be 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:
Defines whether a video is transformed/resampled (in essence treated as a geometric rectangle) or pinned/unresampled (i.e., treated as a pin point for a non-geometric blit region).
The attribute can take one of the five following values:
The media shall be treated as a geometric rectangle in the local coordinate system, defined by 'x', 'y', 'width' and 'height' attributes. The media must be resampled to fill the rectangle and is subject to transformation. This is the lacuna value.
If one of the four values 'pinned', 'pinned90', 'pinned180' and 'pinned270' is specified, the media shall be treated as a point, defined by 'x' and 'y' attributes. This point must be transformed to the nearest actual device pixel. Video at the native resolution given by the media shall then be painted on a region whose center is the pin point and whose width and height are defined by the media. The pixels must be aligned to the device pixel grid and there shall be no resampling. The values of the 'width' and 'height' attributes in this case shall have no effect on the rendering of the video.
Animatable: no.
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. SVG Tiny 1.2 therefore introduces the 'overlay' attribute and a corresponding feature string: http://www.w3.org/Graphics/SVG/feature/1.2/#ComposedVideo. A viewer supporting compositing of video must render the 'video' element according to the SVG painter's model, and thus graphical elements might be rendered on top of the video. A viewer not supporting video compositing must 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:
Defines whether a 'video' is rendered according to the SVG painter's model or if it must be positioned on top of all other SVG elements.
The attribute value can be either of the following:
Animatable: no.
If multiple 'video' elements have overlay="top", the drawing order of those 'video' elements follows the typical SVG rendering order.
The following example illustrates the use of the http://www.w3.org/Graphics/SVG/feature/1.2/#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 don't support video transformations.
The above images show the rendering of Example media04 in two SVG user agents: the first one supporting transformed video (on the left) and the second one not (on the right).
The following example illustrates the use of the http://www.w3.org/Graphics/SVG/feature/1.2/#ComposedVideo feature string. A 'switch' element is wrapped around two groups. The first group must render a video with text composited on top on viewers supporting composed video while the second group must render a video with text placed above the video on viewers that do not support composed video.
The above images show the rendering of Example media05 in two SVG user agents: the first one supporting composed video (on the left) and the second one not (on the right).
The 'animation' elements specifies an SVG document 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. Furthermore, the 'animation' element supports timing and synchronization attributes which allow multiple animations to run with independent timelines in the same SVG document. Just like 'video' and 'image', the 'animation' element must not point to document fragments within SVG files.
An 'animation' element 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 'preserveAspectRatio' attribute on the rootmost 'svg' element in the referenced SVG document shall be ignored (as are its 'width' and 'height' attributes). Instead, the 'preserveAspectRatio' attribute on the referencing 'animation' element shall define 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 document's 'viewBox' value. When no value is available the 'preserveAspectRatio' attribute must be ignored, and only the translation due to the 'x' and 'y' attributes of the viewport must be used to display the content.
The referenced SVG document represents a separate document which generates its own parse tree and document object model. Thus, there is no inheritance of properties into the referenced animation. For details, see Processing of external references to documents.
The SVG specification does not specify when an animation that is not being displayed should be loaded. A user agent is not required to load animation data for an animation that is not displayed (e.g. display="none"). However, it should be noted that this may cause a delay when an animation becomes visible for the first time. In the case where an author wants to suggest that the user agent load animation data before it is displayed, they should use the 'prefetch' element.
Attribute definitions:
The x-axis coordinate of one corner of the rectangular region into which the animation is placed. The lacuna value is '0'.
Animatable: yes.
The y-axis coordinate of one corner of the rectangular region into which the animation is placed. The lacuna value is '0'.
Animatable: yes.
The width of the rectangular region into which the animation is placed. A negative value is unsupported. A value of zero must disable rendering of the element. The lacuna value is '0'.
Animatable: yes.
The height of the rectangular region into which the animation is placed. A negative value is unsupported. A value of zero must disable rendering of the element. The lacuna value is '0'.
Animatable: yes.
An IRI reference to the animation data. An invalid IRI reference is an unsupported value. An empty attribute value (xlink:href="") disables rendering of the element. The lacuna value is the empty string.
When the value of this attribute is animated or otherwise modified, if the media timeline can be controlled, then the media timeline is restarted only if the 'syncBehavior' attribute is set to independent. If the media timeline cannot be controlled, then the media timeline is unaffected by such modification.
Animatable: yes.
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.
See attribute definition for description.
Animatable: no.
See attribute definition for description.
Animatable: yes.
See definition.
See definition.
See definition.
The example below shows basic usage of the 'animation' element. For another example, see the use and animation example in the Linking chapter.
The 'audio-level' property can be applied to the 'audio', 'video' and 'animation' elements described above, the 'use' element, plus container elements such as the 'g' element.
| Value: | <number> | inherit |
| Initial: | 1.0 |
| Applies to: | media elements, 'use' and container elements |
| Inherited: | no |
| Percentages: | N/A |
| Media: | visual, audio |
| Animatable: | yes |
| Computed value: | Specified value, except inherit |
The 'audio-level' property specifies a value that is used to calculate the volume of a particular element. Values below 1.0 decrease it and a value of zero silences it.
An element's volume is the product of its clamped 'audio-level' property and either the clamped computed value of its parent, or the initial value (1.0) if it has no parent. Audio level clamping occurs for any values outside the range 0.0 (silent) to 1.0 (system volume). (See Clamping values which are restricted to a particular range.)
This sentence is informative: An element's volume cannot be louder than the volume of its parent.
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)
User agents may limit the actual signal level to some maximum, based on user preferences and hardware limitations.
If the element has an element volume of 0, then the output signal must be inaudible. If the element has an element volume of 1, then the output signal must be at the system volume level. Neither the 'audio-level' property nor the element volume override the system volume setting.
SVG Tiny 1.2 supports the five attributes listed below from SMIL 2.1 to control runtime synchronization of timed elements. In SVG Tiny 1.2 the 'syncBehavior', 'syncTolerance' and 'syncMaster' attributes can be specified on the 'audio', 'video' and 'animation' elements. The 'syncBehaviorDefault' and 'syncToleranceDefault' attributes can be specified on the 'svg' element.
Attribute definitions:
See the SMIL 2.1 definition of 'syncBehavior' ([SMIL21], section 10.4.1).
Animatable: no.
See the SMIL 2.1 definition of 'syncBehaviorDefault' ([SMIL21], section 10.4.1).
Animatable: no.
See the SMIL 2.1 definition of 'syncTolerance' ([SMIL21], section 10.4.1).
Animatable: no.
See the SMIL 2.1 definition of 'syncToleranceDefault' ([SMIL21], section 10.4.1).
Animatable: no.
See the SMIL 2.1 definition of 'syncMaster' ([SMIL21], section 10.4.1).
Animatable: no.
The two files below illustrate how it is possible to make sure some video content can be synchronized with some text using the synchronization attributes.
Since the timed elements ('video' and 'animation') do not specify their runtime synchronization behavior using the 'syncBehavior' attribute, the behavior is deduced from the 'syncBehaviorDefault' attribute on the nearest ancestor, in this case on the 'svg' element.
This attribute has the value 'locked', which means that all the timed elements in the subtree share the same timeline. In this case, the main scene timeline, the 'video' and 'animation' timelines are then locked to each other.
Then, the master is given to the video, which means that if the video is stalled in the streaming session, the timeline of the video will be paused and, as a consequence, the timeline of the lyrics and of the main scene will be paused as well.
The 'initialVisibility' attribute applies to visual media elements ('video' and 'animation') and is used to control the visibility of the media object before its first active duration period has started. A visible media element that is visible before activation shall have its first frame displayed. For an 'animation' element this means the referenced file rendered at time 0. For a 'video' element it means the first frame of the video sequence.
Attribute definition:
Controls the visibility of the media object before its first active duration period has started.
The attribute value can be either of the following:
The lacuna value. Indicates that the media object is not displayed, as though the element had display="none", until its first active duration starts.
The media element is visible from the initialization of the parent time container (i.e. time 0 of the parent SVG document). During this time, and until the active duration starts, the media element is initialized but remains inactive.
Animatable: no.