% Copyright 2012--\today Alexander Grahn % % This material is subject to the LaTeX Project Public License. See % http://mirror.ctan.org/help/Catalogue/licenses.lppl.html % for the details of that license. % %\pdfcompresslevel=0 %\pdfobjcompresslevel=0 \listfiles \documentclass[a4paper]{article} \frenchspacing \usepackage{media9} %\usepackage[draft]{media9} \usepackage{animate} \usepackage{fancyvrb} \usepackage{float} \usepackage{amssymb} \usepackage[UKenglish]{babel} \usepackage{graphicx} \usepackage{color} \usepackage{lmodern} \usepackage{microtype} \usepackage[T1]{fontenc} %\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 flv audio multimedia streamed media rtmp YouTube animation JavaScript pdfLaTeX dvips ps2pdf dvipdfmx XeLaTeX u3d prc Adobe Reader RichMedia annotation LuaLaTeX} \hypersetup{ bookmarksnumbered,linktocpage,breaklinks, pdftitle={The media9 Package}, pdfsubject={Documentation}, pdfauthor={Alexander Grahn}, pdfkeywords={\keywords}, citebordercolor={0 0 1}, filebordercolor={0 0 1}, linkbordercolor={0 0 1}, menubordercolor={0 0 1}, pagebordercolor={0 0 1}, urlbordercolor={0 0 1} } \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{\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} } \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]\includegraphics[height=2.7ex]{mailto}} \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{nohyphenation}{\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 sound 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. 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 (\verb+ffmpeg+ can be substituted with \verb+avconv+) \begin{Verbatim} ffmpeg -i video.avi -c:v libx264 -g 30 -r 30 video.mp4 \end{Verbatim} 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 -c:v libx264 -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. \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. 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} \makeatletter \item l3kernel (\LaTeX{} package), version $\ge \g@mix@liiikerneldate$ \item l3packages (\LaTeX{} package), version $\ge \g@mix@liiipkgdate$ \makeatother \item pdf\TeX{}, version $\ge1.30$ \item Ghostscript, version $\ge8.31$ or Adobe Distiller for PS to PDF conversion \item dvipdfmx, version $\ge 20120420$ for DVI to PDF conversion \item Adobe Reader, version $\ge9$, but not greater than 9.4.1 on Linux \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://tug.ctan.org/tex-archive/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 `\href{http://tug.ctan.org/tex-archive/install/macros/latex/contrib/media9.tds.zip}{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 noplaybutton activate=... deactivate=... windowed=... transparent passcontext 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]{1.5}\strut\emph{Important:}\newframe\newframe[5]\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 exceeded+'. See Sect.\ \ref{bugs}. \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+', `\verb+height+' and optionally with `\verb+depth+'. If sizing options `\verb+width+' and `\verb+height+' are given \emph{together} with \verb++, \verb++ will be shrunk or stretched to fit exactly into the rectangle defined by the options, possibly changing the original aspect ratio of the poster text. On the other hand, if only one of `\verb+width+' or `\verb+height+' is given, the other dimension of \verb++ is scaled such that the original aspect ratio is preserved. 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} width=, height=, depth= \end{verbatim} Resize the media playback area, overriding the original dimensions of the {\tt} argument. Option `\verb+depth+' specifies how far the playback area should extend below the base line of the running text. If only one of `\verb+width+' or `\verb+height+' is given, the other dimension is scaled to maintain the aspect ratio of \verb++. Any valid \TeX{} dimension is accepted as a parameter. In addition, the length commands \verb+\width+, \verb+\height+, \verb+\depth+ and \verb+\totalheight+ can be used to refer to the original dimensions of \verb++. \begin{verbatim} label=