139
edits
Changes
Jump to navigation
Jump to search
initial version
= 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.<ref>As explained in ''13.2 Multimedia'' from the PDF specification, https://opensource.adobe.com/dc-acrobat-sdk-docs/standards/pdfstandards/pdf/PDF32000_2008.pdf#G12.2317045.</ref>
Although ''Adobe'' seems to handle them as legacy code, these are part of the newer PDF–2.0 specification.<ref>From PDF–2.0, the specification constitutes a copyrighted ISO standard. Thanks to the Arlington PDF Model (https://github.com/pdf-association/arlington-pdf-model), the elements of the PDF model may be still checked there.</ref>
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<ref>Section ''9.6 Rich Media'' from ''Adobe® Supplement to ISO 32000: BaseVersion 1.7, ExtensionLevel 3'' (original location https://www.adobe.com/content/dam/acom/en/devnet/acrobat/pdfs/adobe_supplement_iso32000.pdf#G10.1527015, available thanks to the ''Internet Archive'': https://web.archive.org/web/20210308070824if_/https://www.adobe.com/content/dam/acom/en/devnet/acrobat/pdfs/adobe_supplement_iso32000.pdf#G10.1527015).</ref>.
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.<ref>https://www.pdfa.org/community/rich-media-twg/. A recent description from that TWG chair may be found at https://www.pdfa.org/presentation/leveling-up-richmedia/.</ref>
== 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.<ref>Just an example, _ ECMAScript for PDF_ (short title for ''Document management — ECMAScript for PDF — Part 1: Use of ISO 32000-2 (PDF 2.0)'') only means CHF 208 in payment (https://www.iso.org/standard/71559.html). According to https://www.pdfa.org/wp-content/uploads/2022/08/1615-Zellmann.pdf#page=16, just joining working groups—such as the one that deals with rich media—requires membership (which may be achieved a liaison, through a non–profit organization).</ref>
= Including Video =
A minimal sample code to include video would read:
<texcode>
\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
</texcode>
The resulting PDF document requires a <code>video.mp4</code> file on the same directory as your ConTeXt source file.
The output PDF contains three pages and the second pages contains your <code>video.mp4</code>.
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: {{cmd|definerenderingwindow}}, {{cmd|userendering}} and {{cmd|placerenderingwindow}}.
# {{cmd|definerenderingwindow}} creates the window to display the media (inherits options from {{cmd|setupframed}}.
# {{cmd|userendering}} selects the media to be displayed and specifies its MIME type. Its options are <code>embed</code> (which equals to <code>yes</code> or <code>no</code>) and <code>auto</code> (media is played/stopped when page containing the media is reached/left).
# {{cmd|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:
<texcode>
\unexpanded\def\IncludeMPFour[#1]
{\definerenderingwindow[#1]
[width=\textwidth, height=\textwidth]
\userendering[#1][video/mp4][#1]
[embed=yes, auto]
\placerenderingwindow[#1][#1]}
</texcode>
It could be invoked as {{cmd|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 {{cmd|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:
<texcode>
\unexpanded\def\IncludeMPThree[#1]
{\definerenderingwindow[#1]
[width=\zeropoint, height=\zeropoint]
\userendering[#1][audio/mp3][#1]
[embed=yes, auto]
\placerenderingwindow[#1][#1]}
</texcode>
= Extra Features =
There is an improvement (pending to be added) which will configure:
# <code>controls</code>: <code>yes</code> or <code>no</code>, default to <code>no</code>.
# <code>volume</code>: from <code>0</code> to <code>100</code>, default to <code>100</code>.
# <code>repeat</code>: any positive number, <code>0</code> repeats forever, default no repeat (<code>1</code>).
# <code>opacity</code>: from <code>0.0</code> (fully transparent) to <code>1.0</code> (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).<ref>You may need enable “legacy” content in ''Acrobat'' first.</ref>
The latest version of ''Foxit Reader'' seems to be able to handle renditions.
''Poppler'' automatically plays the included media, although it still doesn’t handle the automatic actions included with the screen annotation (there is a patch pending to be merged).
= Footnotes =
<references />
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.<ref>As explained in ''13.2 Multimedia'' from the PDF specification, https://opensource.adobe.com/dc-acrobat-sdk-docs/standards/pdfstandards/pdf/PDF32000_2008.pdf#G12.2317045.</ref>
Although ''Adobe'' seems to handle them as legacy code, these are part of the newer PDF–2.0 specification.<ref>From PDF–2.0, the specification constitutes a copyrighted ISO standard. Thanks to the Arlington PDF Model (https://github.com/pdf-association/arlington-pdf-model), the elements of the PDF model may be still checked there.</ref>
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<ref>Section ''9.6 Rich Media'' from ''Adobe® Supplement to ISO 32000: BaseVersion 1.7, ExtensionLevel 3'' (original location https://www.adobe.com/content/dam/acom/en/devnet/acrobat/pdfs/adobe_supplement_iso32000.pdf#G10.1527015, available thanks to the ''Internet Archive'': https://web.archive.org/web/20210308070824if_/https://www.adobe.com/content/dam/acom/en/devnet/acrobat/pdfs/adobe_supplement_iso32000.pdf#G10.1527015).</ref>.
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.<ref>https://www.pdfa.org/community/rich-media-twg/. A recent description from that TWG chair may be found at https://www.pdfa.org/presentation/leveling-up-richmedia/.</ref>
== 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.<ref>Just an example, _ ECMAScript for PDF_ (short title for ''Document management — ECMAScript for PDF — Part 1: Use of ISO 32000-2 (PDF 2.0)'') only means CHF 208 in payment (https://www.iso.org/standard/71559.html). According to https://www.pdfa.org/wp-content/uploads/2022/08/1615-Zellmann.pdf#page=16, just joining working groups—such as the one that deals with rich media—requires membership (which may be achieved a liaison, through a non–profit organization).</ref>
= Including Video =
A minimal sample code to include video would read:
<texcode>
\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
</texcode>
The resulting PDF document requires a <code>video.mp4</code> file on the same directory as your ConTeXt source file.
The output PDF contains three pages and the second pages contains your <code>video.mp4</code>.
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: {{cmd|definerenderingwindow}}, {{cmd|userendering}} and {{cmd|placerenderingwindow}}.
# {{cmd|definerenderingwindow}} creates the window to display the media (inherits options from {{cmd|setupframed}}.
# {{cmd|userendering}} selects the media to be displayed and specifies its MIME type. Its options are <code>embed</code> (which equals to <code>yes</code> or <code>no</code>) and <code>auto</code> (media is played/stopped when page containing the media is reached/left).
# {{cmd|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:
<texcode>
\unexpanded\def\IncludeMPFour[#1]
{\definerenderingwindow[#1]
[width=\textwidth, height=\textwidth]
\userendering[#1][video/mp4][#1]
[embed=yes, auto]
\placerenderingwindow[#1][#1]}
</texcode>
It could be invoked as {{cmd|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 {{cmd|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:
<texcode>
\unexpanded\def\IncludeMPThree[#1]
{\definerenderingwindow[#1]
[width=\zeropoint, height=\zeropoint]
\userendering[#1][audio/mp3][#1]
[embed=yes, auto]
\placerenderingwindow[#1][#1]}
</texcode>
= Extra Features =
There is an improvement (pending to be added) which will configure:
# <code>controls</code>: <code>yes</code> or <code>no</code>, default to <code>no</code>.
# <code>volume</code>: from <code>0</code> to <code>100</code>, default to <code>100</code>.
# <code>repeat</code>: any positive number, <code>0</code> repeats forever, default no repeat (<code>1</code>).
# <code>opacity</code>: from <code>0.0</code> (fully transparent) to <code>1.0</code> (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).<ref>You may need enable “legacy” content in ''Acrobat'' first.</ref>
The latest version of ''Foxit Reader'' seems to be able to handle renditions.
''Poppler'' automatically plays the included media, although it still doesn’t handle the automatic actions included with the screen annotation (there is a patch pending to be merged).
= Footnotes =
<references />
