## 6. Rich media content

This chapter explains how to add SVG, MathML, audio, video and Flash animations to your DITA topics and how `ditac` processes this rich media content in the case where the output format supports rich media (e.g. XHTML 5, EPUB 3) and also in the case where the output format does not support rich media (e.g. XHTML 1, PDF, RTF).

##### Note

XMLmind XML Editor has an "Insert media object" button in its DITA Topic tool bar which allows to easily insert any of the elements and processing-instructions described in this chapter.

### SVG

It is possible to include SVG graphics in a DITA topic either by reference or by inclusion. Use an `image` element pointing to an SVG file to include it by reference. Example:
The XML source code corresponding to the above example is:

    <p><image href="media/graphic.svg"/></p>

Embed the `svg:svg` element in a `foreign` element (or any element specializing `foreign`) to include it by inclusion. Example:
The XML source code corresponding to the above example is:

    <p><foreign><svg:svg height="140" id="svg2" version="1.1"
      viewBox="0 0 264 120" width="320"
      xmlns:svg="http://www.w3.org/2000/svg">
      <svg:defs id="defs39"/>
      ...
      </svg:g>
    </svg:svg></foreign></p>

- It is recommended to include SVG graphics by reference as the `image` element has useful attributes (`width`, `height`, `scale`, `scalefit`) allowing to adjust the dimension of the image.
- Only the following screen formats may contain SVG: XHTML 5, XHTML 5 Web Help and EPUB 3. Note that only modern web browsers support XHTML 5 and XHTML 5 Web Help. Very few EPUB readers (e.g. iBooks) support EPUB 3.
- All XSL-FO based formats support SVG whatever the XSL-FO processor you may use.

### MathML

Embed the `mml:math` element in a `foreign` element (or any element specializing `foreign`) to add math to your DITA topics. Example:
{ ∇× E = - ∂ ⁡ B ∂ ⁡ t ∇× B = μ 0 ⁢ J + μ 0 ⁢ ε 0 ⁢ ∂ ⁡ E ∂ ⁡ t
The XML source code corresponding to the above example is:

    <p><foreign><mml:math display="block"
      xmlns:mml="http://www.w3.org/1998/Math/MathML">
      <mml:mrow>
        <mml:mo>{</mml:mo>
        <mml:mtable>
          <mml:mtr>
            <mml:mtd>
            ...
            </mml:mtd>
          </mml:mtr>
        </mml:mtable>
      </mml:mrow>
    </mml:math></foreign></p>

- Only the following screen formats may contain MathML: XHTML 5, XHTML 5 Web Help and EPUB 3. Most modern web browsers (Firefox, Chrome) support XHTML 5 and XHTML 5 Web Help containing MathML. Very few EPUB readers (e.g. iBooks) support EPUB 3.
- XSL-FO based formats support MathML dependin g on the XSL-FO processor you use:
  - Apache FOP requires you to download and install the the JEuclid FOP plug-in .
  - RenderX XEP does not support MathML.
  - Antenna House Formatter supports MathML as an option.
  - XMLmind XSL-FO Converter supports MathML out of the box.

### Audio

Use the `object` DITA element to add audio to your DITA topics. Example:
audio.mp3 (audio/mpeg)
The XML source code corresponding to the above example is:

    <p><object data="media/audio.mp3" type="audio/mpeg">
         <param name="source.src" value="media/audio.ogg"/>
         <param name="source.type" value="audio/ogg"/>

         <param name="source.src" value="media/audio.m4a"/>
         <param name="source.type" value="audio/mp4"/>

         <param name="source.src" value="media/audio.wav"/>
         <param name="source.type" value="audio/wav"/>

         <param name="controls" value="true"/>
    </object></p>

- The `data` and `type` attributes are required. The value of the `type` attribute must start with "`audio/`".
- It is strongly recommended to specify alternate audio files as modern web browsers, while all supporting the HTML 5 `audio` element, vary in their support of audio formats. This is done by adding pairs of `param` child elements to the `object` element. The first `param` of a pair must have `name="source.src"` attribute and its `value` attribute must reference an audio file. The second `param` of a pair must have `name="source.type"` attribute and its `value` attribute must contain the media type of the preceding audio file.
- It is possible to add `param` elements corresponding to the attributes supported by the HTML 5 `audio` element (`crossorigin`, `preload`, `autoplay`, `mediagroup`, `loop`, `muted`, `controls`). In the above example, we have added a `param` element corresponding to the `controls` HTML 5 attribute. Note that in the case of HTML 5 boolean attributes (`autoplay`, `loop`, `muted`, `controls`), the `value` attribute of a `param` is not significant. For example, in the case of the above example, you could have specified "`yes`", "`on`", "`1`", etc, instead of "`true`".
- If the `object` element has a `desc` child element, then this `desc` element is used to generate fallback content in case audio is not supported. If the object element has no `desc` child element, then a simple fallback content is automatically generated by ditac. This automatic fallback content basically consists in a link allowing to download the audio file.
- When ditac is used to generate an XSL-FO based format (PDF, RTF, etc), only the fallback content appears in the ouput file.

### Video

Use the `object` DITA element to add video to your DITA topics. Example:
video.mp4 (video/mp4)
The XML source code corresponding to the above example is:

    <p><object data="media/video.mp4" type="video/mp4">
         <param name="source.src" value="media/video.ogv"/>
         <param name="source.type" value='video/ogg; codecs="theora, vorbis"'/>

         <param name="source.src" value="media/video.webm"/>
         <param name="source.type" value="video/webm"/>

         <param name="width" value="320"/>
         <param name="controls" value="yes"/>
         <param name="poster" value="media/video_poster.jpg"/>
    </object></p>

- The `data` and `type` attributes are required. The value of the `type` attribute must start with "`video/`".
- It is strongly recommended to specify alternate video files as modern web browsers, while all supporting the HTML 5 `video` element, vary in their support of video formats. This is done by adding pairs of `param` child elements to the `object` element. The first `param` of a pair must have `name="source.src"` attribute and its `value` attribute must reference an video file. The second `param` of a pair must have `name="source.type"` attribute and its `value` attribute must contain the media type of the preceding video file.
- It is possible to add `param` elements corresponding to the attributes supported by the HTML 5 `video` element (`crossorigin`, `poster`, `preload`, `autoplay`, `mediagroup`, `loop`, `muted`, `controls`, `width`, `height`). In the above example, we have added a `param` element corresponding to the `width`, `controls` and `poster` HTML 5 attributes. Note that in the case of HTML 5 boolean attributes (`autoplay`, `loop`, `muted`, `controls`), the `value` attribute of a `param` is not significant. For example, in the case of the above example, you could have specified "`true`", "`on`", "`1`", etc, instead of "`yes`".
- If the `object` element has a `desc` child element, then this `desc` element is used to generate fallback content in case video is not supported. If the object element has no `desc` child element, then a simple fallback content is automatically generated by ditac. This automatic fallback content basically consists in a link allowing to download the video file. The `param` element corresponding to the `poster` HTML 5 attribute, if present, is used to generate a nicer automatic fallback content.
- When ditac is used to generate an XSL-FO based format (PDF, RTF, etc), only the fallback content appears in the ouput file.

### Flash animation

Use the `object` DITA element to add Adobe® Flash® animations to your DITA topics. Example:
(You may have to right-click on the above screenshot and select Play from the Flash popup menu to replay the animation.)
The XML source code corresponding to the above example is:

    <p><object data="animation.swf"
               type="application/x-shockwave-flash"
               width="431" height="123">
        <param name="movie" value="animation.swf"/>

        <param name="menu" value="true"/>
        <param name="quality" value="low"/>
    </object></p>

- The `data`, `type`, `width` and `height` attributes are required. The `param name=movie` child element having the same value as attribute `data` is required too.
- You may add any other `param` child element supported by the Flash object. In the above example, you'll find `menu` and `quality` in addition to required `movie`.
- If the `object` element has a `desc` child element, then this `desc` element is used to generate fallback content in case Flash is not supported. If the object element has no `desc` child element, then a simple fallback content is automatically generated by ditac. This automatic fallback content basically consists in a link allowing to download the `.swf` file.
- When ditac is used to generate an XSL-FO based format (PDF, RTF, etc), only the fallback content appears in the ouput file.

### Actions

Unless you add `param name="controls"` (see above), you'll not be able to play audio or video. Even worse, without the `controls` `param`, an audio object is not rendered on screen (that is, it is invisible).
A simple solution for this problem is to insert a `<?onclick?>` processing-instruction in a DITA element (typically an inline element such as `xref` or `ph`). The `<?onclick?>` processing-instruction allows to specify an number of actions:

`play`
  Play the associated resource from the beginning. Only applicable to video or audio targets.
`pause`
  Pause playing . Only applicable to video or audio targets.
`resume`
  Resume playing . Only applicable to video or audio targets.
`mute`
  Mute sound . Only applicable to video or audio targets.
`unmute`
  Unmute sound . Only applicable to video or audio targets.
`show`
  Set the visibility property of the target element to visible.
`hide`
  Set the visibility property of the target element to hidden.

The above actions are exactly those supported by EPUB 3's `epub:trigger`.
The `<?onclick?>` processing-instruction is processed by `ditac` for the following output formats: XHTML 5, XHTML 5 Web Help and EPUB 3. It is discarded for any other output format.
The syntax for the content of `<?onclick?>` is:

    onclick_data -> action (S action)*
    action -> op '(' target_id? ')'
    op -> 'play'|'pause'|'resume'|'mute'|'unmute'
          'show'|'hide'

When target_id is not specified, it is taken from the `href` attribute of the element containing the `<?onclick?>` processing-instruction. For example, `<xref href="#media/target_audio"><?onclick play()?>` is equivalent to: `<xref href="#media/target_audio"><?onclick play(media/target_audio)?>`.
Example 1: Say: "Viens Hubble!", which, in French, means: "Come here Hubble!".
No audio. Say: "Viens Hubble!", which, in French, means: "Come here Hubble!".
The XML source code corresponding to the above example is:

    <p>Example 1: <xref href="#media/target_audio"><?onclick play()?>
    Say "<ph xml:lang="fr">Viens Hubble!</ph>"</xref>
    ...
    <object data="media/audio.wav" id="audio_sample" type="audio/wav">
      <desc> ... </desc>
    </object></p>

Example 2: Hide Hubble. Show Hubble.

#### Figure 5. My name is Hubble. I'm a 7-month old Golden Retriever.

The XML source code corresponding to the above example is:

    <p>Example 2:
    <xref href="#media/target_image"><?onclick hide()?>Hide Hubble</xref>.
    <xref href="#media/target_image"><?onclick show()?>Show Hubble</xref>.</p>