% Copyright 2012--\today Alexander Grahn % % This material is subject to the LaTeX Project Public License. See % http://mirrors.ctan.org/macros/latex/base/lppl.txt % for the details of that license. % \listfiles %%%%%%% pdfmanagement-testphase %%%%%% \RequirePackage{pdfmanagement-testphase} % load the package \DeclareDocumentMetadata % activates the PDF management interface { %uncompress, } %%%%%% /pdfmanagement-testphase %%%%%% \documentclass[a4paper]{article} \frenchspacing \usepackage[utf8]{inputenc} \usepackage{textcomp} \usepackage[attachfiles]{media9} %\usepackage[draft]{media9} \usepackage{animate} \usepackage{fancyvrb} \usepackage{float} \usepackage{amssymb} \usepackage[main=UKenglish,nil]{babel} \usepackage{graphicx} \usepackage{color} \usepackage[T1]{fontenc} %\usepackage{lmodern} %\usepackage[scaled=0.85]{luximono} \usepackage[tt=false]{libertine} %override beramono (doesn't look like tt font) \usepackage[libertine]{newtxmath} % \usepackage[scaled=0.83]{luximono} %override beramono (doesn't look like tt font) \usepackage{microtype} %\usepackage{float} \usepackage{parskip} \usepackage{tabls} \usepackage{menukeys} \usepackage{hyperref} \usepackage{hypcap} \def\keywords{embed flash movie LaTeX pdf 3d include sound swf mp3 video mp4 h.264 aac slideshow image gallery flv audio multimedia streamed media rtmp YouTube animation JavaScript pdfLaTeX dvips ps2pdf dvipdfmx XeLaTeX u3d prc Adobe Reader Foxit RichMedia annotation LuaLaTeX} \hypersetup{ bookmarksnumbered,linktocpage,breaklinks, pdftitle={The media9 Package}, pdfsubject={Documentation}, pdfauthor={Alexander Grahn}, pdfkeywords={\keywords}, allcolors=blue } \usepackage[ocgcolorlinks]{ocgx2} %\usepackage{listings} \usepackage{minted} \def\XeLaTeX{X\kern-.1667em\lower.5ex\hbox{\reflectbox{E}}\kern-.125em\LaTeX} \def\pXepLaTeX{(X\kern-.1667em\lower.5ex\hbox{\reflectbox{E}})\kern-.125em\LaTeX} \graphicspath{{files/}} \addmediapath{files} \hyphenation{Ja-va-Script} \newsavebox{\keyshift} \newsavebox{\spacebar} \newsavebox{\COO} \savebox{\COO}{$\overrightarrow{COO}$} \newsavebox{\CtoC} \savebox{\CtoC}{$\overrightarrow{C2C}$} \renewcommand{\textfraction}{0.0} \renewcommand{\topfraction}{1.0} \renewcommand{\bottomfraction}{1.0} \ifpdf\else \makeatletter \@latex@error{Please use pdfLaTeX to compile this documentation} \makeatother \fi \def\parsedate#1/#2/#3\relax{ \def\year{#1} \def\month{#2} \def\day{#3} } \usepackage{siunitx} \begin{document} \makeatletter %\title{The {\sffamily media9} Package\\Version \g@mix@version@tl} \title{The {\sffamily media9} Package, v\g@mix@version@tl} \expandafter\parsedate\g@mix@date@tl\relax %set current date to package date \makeatother \author{Alexander Grahn\\[1ex]\hypersetup{breaklinks=false}\url{https://gitlab.com/agrahn/media9}\hypersetup{breaklinks=true}} \maketitle \begin{abstract}\noindent A \LaTeX{} package for embedding interactive Adobe Flash (SWF) and 3D files (Adobe U3D \& PRC) as well as video and sound files or streams (FLV, MP4/H.246, MP3) into PDF documents with Adobe Reader-9/X compatibility.\\[0.2\baselineskip] \begin{sloppypar}\foreignlanguage{nil}{\noindent\emph{Keywords}: \keywords}\end{sloppypar} \end{abstract} \tableofcontents \section{Introduction} This package provides an interface to embed, in the first place, interactive Flash (SWF) and 3D objects (Adobe U3D \& PRC) into PDF documents. Video and audio files or streams in the popular MP4, FLV and MP3 formats can be embedded as well. However, a media player Flash component is required for playback, as will be explained shortly. Playback of multimedia files uses Adobe Flash Player, which was bundled with Adobe Reader 9 and 10 versions. Unfortunately, beginning with Adobe Reader 11, it must be installed as a separate plug-in. Among the supported media types, video and sound files require an additional Flash (SWF) application for playback, which must be either embedded into the PDF or loaded at runtime from the internet. There are numerous such players, both open-source and commercial, available on the internet. One of them is the highly configurable open-source `StrobeMediaPlayback.swf'~\cite{strobe}, maintained by Adobe and hosted on \href{http://sourceforge.net/projects/osmf.adobe/files/}{SourceForge.net}. Package `media9' comes with an enhanced version of `StrobeMediaPlayback.swf'. In addition, two simple players for video and audio, `VPlayer.swf' and `APlayer.swf' are included, which can be used instead. They provide sufficient functionality for playing embedded files and streamed media. There is yet another player bundled with `media9'. It is a simple image gallery viewer called `SlideShow.swf' which can display collections of embedded and remote images in the PNG, JPEG and GIF file formats. Remote images are downloaded at viewing time and can be configured to be refreshed at definite time intervals. Flash Player supports the efficient H.264 codec for video compression. MP4/H.264 video files can be encoded from existing video files and from numbered bitmap sequences using the \verb+ffmpeg+ (\url{http://ffmpeg.org}) or \verb+avconv+ (\url{http://libav.org}) command line tools (Libav is a fork from the FFmpeg code). In order to allow for precise seeking within video files it is necessary to encode them with a sufficient number of key frames. The command line for recoding an existing video file \verb+video.avi+ into \verb+video.mp4+ reads (one line; \verb+ffmpeg+ can be substituted with \verb+avconv+) \begin{center} \begin{Verbatim} ffmpeg -i video.avi -vf scale="trunc(iw/2)*2:trunc(ih/2)*2" -c:v libx264 -profile:v high -pix_fmt yuv420p -g 30 -r 30 video.mp4 \end{Verbatim} \end{center} From a sequence \verb+frame-0.png+, \verb+frame-1.png+, ... of bitmap files, an MP4 video is produced by \begin{Verbatim} ffmpeg -i frame-%d.png -vf scale="trunc(iw/2)*2:trunc(ih/2)*2" -c:v libx264 -profile:v high -pix_fmt yuv420p -g 30 -r 30 video.mp4 \end{Verbatim} Both examples insert a key frame (option `\verb+-g+') at every second since the frame rate is set to 30 fps. The video encoder requires even pixel numbers in both dimensions which is ensured by adding `\verb+-vf scale="..."+' to the option list. \emph{Note:} `media9' package replaces the now obsolete `movie15' package. `media9' is based on the RichMedia Annotation (Annotations are the interactive elements in a document, in PDF specification parlance.), an Adobe addition to the PDF specification~\cite{supplement}, while `movie15' uses the old multimedia framework (`Screen Annotation') of pre-9 Readers which depends on third-party plug-ins and which does not support recent media file formats. Package `media9' supports the usual PDF making workflows, i.\,e. pdf\LaTeX{}, Lua\LaTeX, \LaTeX{} $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+/Distiller and \pXepLaTeX{} $\rightarrow$ \verb+(x)dvipdfmx+. The final PDF can be viewed in current Adobe Readers on MS Windows and other platforms. On Unix platforms including Linux, however, support of Flash, video and sound was discontinued at Reader version 9.4.2, probably for security reasons. PDF documents which target \href{ftp://ftp.adobe.com/pub/adobe/reader/unix/9.x/9.4.1/}{Adobe Reader 9.4.1 for Linux} should use `VPlayer9.swf' and `APlayer9.swf' (also included in the `media9' package). These media player components are compatible with the older Flash Player 9 plugin that is bundled with the Reader for Linux. Recent versions of Foxit PDF Reader, which is available on the Windows platform, are known to render embedded Flash, video and audio content. Foxit also uses Adobe Flash Player plugin. On tablets and phones running Android or iOS, ezPDF Reader was reported to play video and sound files embedded with `media9'. \section{Requirements} \begin{trivlist} \item l3kernel (\LaTeX{} package), version $\ge \ExplFileDate$ \item pdf\TeX{}, version $\ge1.40$ \item Ghostscript, version $\ge9.15$, or Adobe Distiller for PS to PDF conversion \item dvipdfmx, version $\ge 20190503$ for DVI to PDF conversion \item Adobe Reader, version $\ge9$, but not greater than 9.4.1 on Linux; Foxit Reader (Flash, video, audio) \item Adobe Flash Player plugin for Firefox \end{trivlist} \section{Installation} MiK\TeX{} and \TeX{}Live users should run the package manager for installation and updates. Otherwise, a manual installation into the \emph{local} TeX-Directory-Structure (TDS) root directory is done along the following steps: \begin{enumerate} \item Download the TDS compliant package file `\href{http://mirror.ctan.org/install/macros/latex/contrib/media9.tds.zip}{media9.tds.zip}' from CTAN. \item Find the local TDS root directory by running\\ {\tt\phantom{xx}kpsewhich -var-value TEXMFLOCAL}\\ on the command line. The local TDS root directory is intended for packages that are not maintained by the \TeX{}Live package manager. \item Unzip `\verb+media9.tds.zip+' into the local TDS root directory previously found. Depending on the location of this directory, you may need to be logged in as Root/Administrator. \item After installation, update the filename database by running `{\tt texhash}' on the command line. Again, Root/Administrator privileges may be required. \end{enumerate} For updating the package, repeat the steps given above. \section{Using the package}\label{pkguse} Invoke the package by putting the line \begin{verbatim} \usepackage[]{media9} \end{verbatim} to the preamble of your document, i.\,e. somewhere between \verb+\documentclass+ and \verb+\begin{document}+. `media9' honours the package options: \begin{verbatim} dvipdfmx xetex bigfiles draft final playbutton=... noplaybutton activate=... deactivate=... windowed=... transparent passcontext attachfiles 3Dplaytype=... 3Dplaycount=... 3Dplayspeed=... 3Dtoolbar 3Dnavpane 3Dpartsattrs=... 3Dmenu 3Dbg=... 3Dlights=... 3Drender=... \end{verbatim} Except for `\verb+dvipdfmx+', `\verb+xetex+' and `\verb+bigfiles+', the options above are also available (among others) as command options and will be explained shortly. However, if used as package options they have global scope, taking effect on all embedded media in the document. In turn, command options locally override global settings. Options without an argument are boolean options and can be negated by appending `\verb+=false+'. \XeLaTeX{} will be auto-detected. Therefore package option `\verb+xetex+' is optional. However, in the case of \verb+dvipdfmx+, package option `\verb+dvipdfmx+' is mandatory because it cannot be auto-detected. \begin{animateinline}[autoplay,loop,nomouse]{1}\strut\emph{Important:}\newframe[3]\end{animateinline} If PDF is generated via DVI and Postscript by the command sequence \verb+latex+ $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+, \verb+dvips+ option `\verb+-Ppdf+' should \emph{not} be set when converting the intermediate DVI into Postscript. If you cannot do without, put `\verb+-D 1200+' \emph{after} `\verb+-Ppdf+' on the command line. Users of \LaTeX-aware text editors with menu-driven toolchain invocation, such as \TeX{}nicCenter, should check the configuration of the \verb+dvips+ call. Option `\verb+bigfiles+' is only relevant for the \verb+latex+ $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+ workflow. It may be needed if large media files cause \verb+latex+ to abort with error `\Verb+TeX capacity+ \Verb+exceeded+'. See Sect.\ \ref{bugs}.\enlargethispage{2\baselineskip} \section{The user interface} Package `media9' provides commands for media inclusion (\verb+\includemedia+) and insertion of media control buttons (\verb+\mediabutton+). The latter is introduced in Sect. \ref{mbtn}. \subsection{Media inclusion} \begin{verbatim} \includemedia[]{}{
} \end{verbatim} The last argument, \verb+
+, is the main interactive application to be inserted into the PDF. In the case of Flash, this can be a local SWF file, or a URL, such as a YouTube video player. A local file will become part of the final PDF file, while Flash content from a URL requires an internet connection when the user activates it in Adobe Reader. A URL must be fully qualified, i.\,e., starting with either `\verb+http[s]://+' or `\verb+ftp://+'. As for 3D content, Adobe Reader only supports U3D or PRC files embedded in the PDF; they cannot be loaded or streamed during runtime. The most frequent use of \verb+\includemedia+ will likely be embedding video or sound files for playback in Adobe Reader. For this we need some media player, which is an SWF file we embed as our main application. It will be configured to load, upon activation, a particular video or sound file that was embedded as a resource into the PDF or is to be streamed from the internet. This will be shown later. Note that a local file (main application or resource) will only once be physically embedded in order to keep the final PDF file size small. If the same file (identified by MD5 checksum) appears in other \verb+\includemedia+ commands, only a reference will be inserted that points to the same storage location in the PDF. Argument \verb++ defines the size of the rectangular region of the document page in which the media will be displayed. Moreover, \verb++ will be shown in case the media has not been activated. %(Internally, \verb++ is put into a \LaTeX{} box, which is used as the appearance of the PDF annotation, i.\,e. the interactive region created by \verb+\includemedia+, in PDF specification parlance.) \verb++ can be anything that \LaTeX{} can typeset, such as an \verb+\includegraphics+ command serving as a poster image, a PGF/TikZ/PSTricks inline graphics or just ordinary text. Alternatively, \verb++ can be left blank in which case the size of the media rectangle should be set with options `\verb+width+' and `\verb+height+'. If a non-zero size \verb++ was provided, it can be resized using any combination of options `\verb+width+', `\verb+height+' or `\verb+totalheight+', `\verb+keepaspectratio+' and `\verb+scale+'. A list of directories where \TeX{} searches for media and resource files can be set-up by means of \begin{verbatim} \addmediapath{} \end{verbatim} This command appends one directory at a time to the search list. To specify more directories, just use it repeatedly. The path separator is always `\verb+/+', independent from the operating system. The following section explains all command options provided. They are passed to the media inclusion command as a comma separated list enclosed in a pair of square brackets. \subsection{Command options} A subset of the command options (see Sect. \ref{pkguse}) can also be used as package options, which lets them apply to all embedded media. Some of the options listed here are meaningful only for a specific media type (either Flash or 3D), which will be noted explicitly if not obvious. Dedicated sections covering Flash, video and sound as well as 3D inclusion will follow later on in this document. \begin{verbatim} label=