Inline 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 a mixture of text and any general inline elements.
The media element can occur in any general inline context, including inside most inline elements, some basic block elements, and certain informational elements.
The media element can link to other pages or documents. See Ubiquitous Linking for more information.
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 a block context. See Multimedia Objects for more information.

Examples

Use media to insert an image into your document:

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

Processing Expectations

When a media element occurs in an inline context, it is displayed inline. The exact rendering of a media element will depend on the type and mime attributes. It may be necessary 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 displays the child elements of the 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.

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.

Comparison to Other Formats

The media element can be used in place of the DocBook elements audioobject, imageobject, and videoobject. DocBook uses the inlinemediaobject 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 inline media element. The namespace declarations for this definition are on the page Pages.

mal_inline_media = element media {
  mal_inline_media_attr,
  mal_inline_media_inline
}
mal_inline_media_attr = (
  mal_attr_link *,
  attribute type { "image" | "video" | "audio" | "application" } ?,
  attribute style { xsd:NMTOKENS } ?,
  attribute mime { text } ?,
  attribute src { text },
  attribute height { text } ?,
  attribute width { text } ?,
  mal_inline_attr,
  mal_attr_external *
)
mal_inline_media_inline = mal_inline