Multimedia Objects

Use the media element to insert an image, video, or other multimedia object into your document. Since not all display tools will be able to display all types of objects, you can provide fallback elements in the contents of a media element. See Processing Expectations for details on how fallback elements are handled.

Notes

The media element can contain an optional info element, followed by any general block content. The content is only used as a fallback or alternative.
The media element can occur in any general block context, including inside pages, sections, and certain block elements.
The type attribute specifies what type of object to insert. It can be one of "image", "video", "audio", or "application". If no type attribute is present, "image" is assumed.
The style attribute takes a space-separated list of style hints. Processing tools should adjust their behavior according to those style hints they understand.
The mime attribute takes a valid MIME type for the object that is being inserted.
The src attribute provides a URL for the object, possibly relative to the current page.
The height and width attributes can be used to provide the dimensions, in pixels, of an image or video.
The media element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.
The media element may also be used in an inline context. See Inline Multimedia Objects for more information.

Examples

Use media to insert an image into your document:

<media type="image" mime="image/png" src="mallard-logo.png">
<p>The Mallard logo</p>
</media>

Processing Expectations

When a media element occurs in a block context, it should be displayed as a block element. The exact rendering of a media element will depend on the type and mime attributes. Display tools may need to add controls for audio and video objects.

The application type is intended for embedding interactive applications in documents. There are currently no specific recommendations for displaying application objects. Behavior may vary according to the type of application being embedded.

Some display tools will not be able to display all types of objects. For example, a printed document will not be able to display video or play back audio. Even when a display tool can display the type of object, it may not be able to work with the given MIME type for technical or other reasons.

When a display tool cannot display a media element, it should display the child elements of the element, excepting the optional info element, as if the media element itself were replaced by its children. The child elements may consist of simply another media element referencing a different type of content. When processing any child media elements, display tools may need to fall back further to their child elements.

Frequently, the children of a media element will be a single block element, such as another media element or a p element. Note, however, that this is not required, and fallback rendering may involve displaying several block elements.

In some display media, multimedia objects can have alternate text. This may be displayed when a user hovers over the object, or it may be provided to assistive technologies. When displaying in such a medium, display tools should extract the text value of a media element by processing its child elements, and recursively processing any child media elements, as if it can not display any types of media elements.

The optional info element can provide metadata for the media element, such as attributions, licensing information, and additional titles for extensions. It is not displayed directly.

Comparison to Other Formats

The media element can be used in place of the DocBook elements audioobject, imageobject, and videoobject. DocBook uses the mediaobject element to provide alternative objects. In Mallard, alternative objects are nested, obviating the need for a container element.

The media element can be used in place of the image element in DITA. DITA does not provide a mechanism to embed video, audio, or other types of rich media content in documents. In DITA, the image element may contain a single alt element to provide fallback content. In Mallard, alternative content is nested with no need for a container element. In DITA, the placement attribute specifies whether an image is inline or block content. In Mallard, inline or block context is always unambiguous from placement.

Schema

The formal definition of the Mallard language is maintained in RELAX NG Compact Syntax in code blocks within this specification. This is the formal definition for the block media element. The namespace declarations for this definition are on the page Pages.

mal_block_media = element media {
  mal_block_media_attr,
  mal_info ?,
  mal_block_media_content *
}
mal_block_media_attr = (
  attribute type { "image" | "video" | "audio" | "application" } ?,
  attribute style { xsd:NMTOKENS } ?,
  attribute mime { text } ?,
  attribute src { text },
  attribute height { text } ?,
  attribute width { text } ?,
  mal_block_attr,
  mal_attr_external *
)
mal_block_media_content = mal_block