Mallard and TTML
The core Mallard language is intentionally as simple as possible. It addresses a specific set of problems, allowing domain-specific languages to handle other areas. As a well-designed, modern XML vocabulary, Mallard defines exactly where and how you can mix XML markup from external namespaces. With proper tool support, you can embed almost any XML vocabulary into Mallard.
This tutorial explains how to embed Timed Text Markup Language (TTML) into your Mallard documents. TTML is an XML vocabulary for marking up timed text, or text that is shown only at certain times for timed media like videos. This is generally used to subtitle spoken parts of a video, or to provide captions for demonstrations that may not contain spoken audio.
One of the advantages of embedding TTML into Mallard is that the subtitles can be translated as part of the normal translation workflow. Translating video is expensive in terms of both translator time and storage requirements. Whether or not the video is translated, embedding subtitles into your Mallard document with TTML allows a relatively low-cost localization.
To see the results of the examples in this tutorial, your browser needs to support HTML5 video.
Basic TTML
The Mallard media element allows you to add images, video, audio, and external applications to a page. To add a video, set the type attribute to video. This tutorial uses a video from the GNOME Getting Started videos.
<media type="video" src="gnome-change-wallpaper.webm"
width="700" height="394"/>You can add child content to the media element. This can be used to add fallback content (for example, to use an image instead of a video in print media), or to enable extension content. In this case, TTML is extension content. Mallard implementations that understand TTML will show the subtitles. Implementations that do not will just show the video without subtitles.
TTML subtitles are defined with elements in the namespace http://www.w3.org/ns/ttml. This tutorial uses the tt prefix for that namespace. Subtitles are contained in a tt:tt element, which in turn contains a single tt:body element. The tt:body element contains any number of tt:div elements, which contains tt:p elements. The begin and end attributes specify when the content should be shown.
This example adds a single caption for the introductory text that starts after one second and ends at the five-second mark.
<media type="video" src="gnome-change-wallpaper.webm"
width="700" height="394">
<tt:tt xmlns:tt="http://www.w3.org/ns/ttml">
<tt:body>
<tt:div begin="1s" end="5s">
<tt:p>Changing Wallpaper</tt:p>
</tt:div>
</tt:body>
</tt:tt>
</media>You can also use the dur attribute instead of the end attribute. This specifies how long the caption is displayed, rather than the time at which it is hidden.
<media type="video" src="gnome-change-wallpaper.webm"
width="700" height="394">
<tt:tt xmlns:tt="http://www.w3.org/ns/ttml">
<tt:body>
<tt:div begin="1s" dur="4s">
<tt:p>Changing Wallpaper</tt:p>
</tt:div>
</tt:body>
</tt:tt>
</media>You can then add more tt:div elements for more captions.
<media type="video" src="gnome-change-wallpaper.webm"
width="700" height="394">
<tt:tt xmlns:tt="http://www.w3.org/ns/ttml">
<tt:body>
<tt:div begin="1s" end="5s">
<tt:p>Changing Wallpaper</tt:p>
</tt:div>
<tt:div begin="6s" end="9s">
<tt:p>Click the system menu on the right side of the top bar
and press the settings button.</tt:p>
</tt:div>
</tt:body>
</tt:tt>
</media>Nesting Timed Content
You can add more than one tt:p element to a tt:div, or even nest tt:div elements inside other tt:div elements. Nested tt:div elements and tt:p elements can both take timing attributes, which are calculated relative to their parent elements.
This example shows the word “Wallpaper” in its own paragraph, starting one second after the enclosing caption is shown, or at the two-second mark. Because it does not have an end or dur attribute, it is shown as long as the enclosing caption is shown.
<media type="video" src="gnome-change-wallpaper.webm"
width="700" height="394">
<tt:tt xmlns:tt="http://www.w3.org/ns/ttml">
<tt:body>
<tt:div begin="1s" end="5s">
<tt:p>Changing</tt:p>
<tt:p begin="1s">Wallpaper</tt:p>
</tt:div>
</tt:body>
</tt:tt>
</media>TTML also provides the tt:span element, which is an inline element. You can put timing attributes on tt:span as well to show certain spans of text in a paragraph at certain times. Like the previous example, this example shows the word “Wallpaper” at the two-second mark, but it keeps it within the same paragraph.
<media type="video" src="gnome-change-wallpaper.webm"
width="700" height="394">
<tt:tt xmlns:tt="http://www.w3.org/ns/ttml">
<tt:body>
<tt:div begin="1s" end="5s">
<tt:p>Changing <tt:span begin="1s">Wallpaper</tt:span></tt:p>
</tt:div>
</tt:body>
</tt:tt>
</media>This can get arbitrarily complex. The following example uses millisecond timing to progressively show words. This may appear somewhat choppy, depending on the resolution of timing events in your browser.
<media type="video" src="gnome-change-wallpaper.webm"
width="700" height="394">
<tt:tt xmlns:tt="http://www.w3.org/ns/ttml">
<tt:body>
<tt:div begin="1s" end="5s">
<tt:p>Changing Wallpaper</tt:p>
</tt:div>
<tt:div begin="6s" end="9s">
<tt:p>Click <tt:span begin="100ms">the
<tt:span begin="100ms">system <tt:span begin="100ms">menu
<tt:span begin="100ms">on <tt:span begin="100ms">the
<tt:span begin="100ms">right <tt:span begin="100ms">side
<tt:span begin="100ms">of <tt:span begin="100ms">the
<tt:span begin="100ms">top <tt:span begin="100ms">bar
<tt:span begin="100ms">and <tt:span begin="100ms">press
<tt:span begin="100ms">the <tt:span begin="100ms">settings
<tt:span begin="100ms">button.</tt:span></tt:span></tt:span>
</tt:span></tt:span></tt:span></tt:span></tt:span></tt:span>
</tt:span></tt:span></tt:span></tt:span></tt:span></tt:span>
</tt:span></tt:p>
</tt:div>
</tt:body>
</tt:tt>
</media>Mixing Mallard and TTML
Mallard is designed to have other XML vocabularies mixed in, but it’s also designed to be mixed into those vocabularies. So just as you can put TTML in your Mallard pages, you can put Mallard elements in the TTML elements in your Mallard pages.
This example uses the inline Mallard gui element to mark up the label of a user interface element when it appears in a TTML subtitle.
<media type="video" src="gnome-change-wallpaper.webm"
width="700" height="394">
<tt:tt xmlns:tt="http://www.w3.org/ns/ttml">
<tt:body>
<tt:div begin="1s" end="5s">
<tt:p>Changing Wallpaper</tt:p>
</tt:div>
<tt:div begin="6s" end="9s">
<tt:p>Click the system menu on the right side of the top bar
and press the settings button.</tt:p>
</tt:div>
<tt:div begin="10s" end="12s">
<tt:p>Select <gui>Background</gui>.</tt:p>
</tt:div>
</tt:body>
</tt:tt>
</media>Just as you can use inline Mallard elements inside a tt:p element, you can also use block Mallard elements inside a tt:div element. This example puts all the steps into Mallard steps element. It uses the continues style hint to number them correctly, even though only one step is shown at a time.
<media type="video" src="gnome-change-wallpaper.webm"
width="700" height="394">
<tt:tt xmlns:tt="http://www.w3.org/ns/ttml">
<tt:body>
<tt:div begin="1s" end="5s">
<tt:p>Changing Wallpaper</tt:p>
</tt:div>
<tt:div begin="6s" end="10s">
<steps>
<item>
<p>Click the system menu on the right side of the top bar
and press the settings button.</p>
</item>
</steps>
</tt:div>
<tt:div begin="10s" end="12s">
<steps style="continues">
<item>
<p>Select <gui>Background</gui>.</p>
</item>
</steps>
</tt:div>
<tt:div begin="12s" end="13s">
<steps style="continues">
<item>
<p>Click the current background image.</p>
</item>
</steps>
</tt:div>
<tt:div begin="13s" end="16s">
<steps style="continues">
<item>
<p>Click the background image you want to use.</p>
</item>
</steps>
</tt:div>
<tt:div begin="16s" end="18s">
<steps style="continues">
<item>
<p>Click the <gui>Select</gui> button.</p>
</item>
</steps>
</tt:div>
<tt:div begin="18s" end="21s">
<steps style="continues">
<item>
<p>Close the <gui>Background</gui> window.</p>
</item>
</steps>
</tt:div>
</tt:body>
</tt:tt>
</media>Click the system menu on the right side of the top bar and press the settings button.
Select Background.
Click the current background image.
Click the background image you want to use.
Click the Select button.
Close the Background window.
