# How PDF Handles Multimedia

ConTeXt LMTX can include multimedia files in PDF documents. But this inclusion depends on how PDF handles multimedia.

There are mainly two ways of including multimedia in PDF: renditions and rich media.

Renditions were the standard way of handling multimedia in PDF–1.7.

Rich media were added as an addition to PDF–1.7 and were fully incorporated in PDF–2.0.

## Renditions

The public PDF specification (version 1.7) includes a way of including multimedia, called renditions or mediaclips.[1]

Although Adobe seems to handle them as legacy code, these are part of the newer PDF–2.0 specification.[2]

The main feature with renditions is that the PDF viewer relies on the OS to reproduce the media.

The main gain and drawback of this feature is that format and capabilities are only limited by the OS standard player.

## Rich Media

Rich media were added as an extension in a supplement to the first ISO PDF standard[3].

Originally, rich media for multimedia involved the use of Flash (which Adobe itself deprecated after 2020). To the best of my knowledge, rich media for PDF–2.0 (without Flash) seems to be something that its technical working group may be specifying.[4]

## ConTeXt Support

ConTeXt LMTX supports renditions only, since from PDF–2.0 getting any specification relateds to the format is complicated and not free at all.[5]

# Including Video

A minimal sample code to include video would read:

\setupinteraction[state=start]
\starttext
\null\page
\definerenderingwindow[myrenderingwindow]
[width=\textwidth, height=\textwidth]
\startTEXpage[offset=1ex, pagestate=start]
\userendering[key-name][video/mp4][video.mp4]
[embed=yes, auto]
\placerenderingwindow[myrenderingwindow][key-name]
\stopTEXpage
\null\page
\stoptext


A video.mp4 file is required to be on the same directory as your ConTeXt source file, so the resulting PDF file can have it embedded. If the file isn’t embedded, it needs to be on the same directory as the PDF document (so it can be invoked as external file).

The output PDF contains three pages and the second pages contains your video.mp4.

Once the second page is reached, video will be automatically played. It will be automatically closed, when the page containing it is left.

## Explanation

Three commands are required to include multimedia: \definerenderingwindow, \userendering and \placerenderingwindow.

1. \definerenderingwindow creates the window to display the media (inherits options from \setupframed.
2. \userendering selects the media to be displayed and specifies its MIME type. Its options are embed (which equals to yes or no) and auto (media is played/stopped when page containing the media is reached/left).
3. \placerenderingwindow: places the multimedia content by linking the window and the media to be rendered.

Nothing prevents you from creating a command for video inclusion such as:

\unexpanded\def\IncludeMPFour[#1]
{\definerenderingwindow[#1]
[width=\textwidth, height=\textwidth]
\userendering[#1][video/mp4][#1]
[embed=yes, auto]
\placerenderingwindow[#1][#1]}


It could be invoked as \IncludeMPFour[video.mp4]. Of course, rendering window dimensions, embedding and auto playback will be the same for all videos using this command.

# Audio Inclusion

Audio may not really need a visible rendering window (when playing controls aren’t displayed).

In that case, you have to define a frame with width and height of \zeropoint.

Also the MIME type should be different, since the file type is different.

Another way to define a general command to include audio would be:

\unexpanded\def\IncludeMPThree[#1]
{\definerenderingwindow[#1]
[width=\zeropoint, height=\zeropoint]
\userendering[#1][audio/mp3][#1]
[embed=yes, auto]
\placerenderingwindow[#1][#1]}


# Extra Features

There is an improvement (pending to be added) which will configure:

1. controls: yes or no, default to no.
2. volume: from 0 to 100, default to 100.
3. repeat: any positive number, 0 repeats forever, default no repeat (1).
4. opacity: from 0.0 (fully transparent) to 1.0 (fully opaque).

All defaults are not set by ConTeXt, but by the PDF specification.

# PDF Viewers

The latest released Acrobat Reader DC is able to display the multimedia (that your OS default player also handles).[6]