% Copyright 2004 Alexander Grahn % % This material is subject to the LaTeX Project Public License. See % http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html % for the details of that license. % \documentclass[a4paper]{article} %please use pdfLaTeX \usepackage{ifthen} \ifthenelse{\isundefined{\pdfoutput}}{% \errmessage{Use pdfLaTeX, please!} }{% \ifthenelse{\number\pdfoutput<1}{% \errmessage{Use pdfLaTeX, please!} }{} } \usepackage[3D]{movie15} \usepackage{ragged2e} \usepackage{amssymb} \usepackage[UKenglish]{babel} \usepackage{color} \usepackage{graphicx} \usepackage{hyperref} \pdfpagewidth595bp \pdfpageheight842bp \parindent0pt \parskip1.2ex \hypersetup{ bookmarksnumbered,linktocpage,breaklinks, pdftitle={The movie15 Package}, pdfsubject={Documentation}, pdfauthor={Alexander Grahn}, pdfkeywords={embed, embedded, multimedia, movie, sound, 3D, LaTeX, pdfLaTeX, PDF, Adobe}, citebordercolor={0 0 1}, filebordercolor={0 0 1}, linkbordercolor={0 0 1}, menubordercolor={0 0 1}, pagebordercolor={0 0 1}, urlbordercolor={0 0 1} } \begin{document} \title{The {\sffamily movie15} Package} \author{Alexander Grahn\\[1ex]\includegraphics[height=2.7ex]{mailto}} \maketitle \begin{abstract} A \LaTeX{} package for inclusion of movies, sounds and 3D objects into PDF documents with PDF-1.5/1.6 compatibility. \end{abstract} \tableofcontents \section{Introduction} The way multimedia content, i.\,e. movies and sounds, is included into PDF has changed with Adobe's PDF specification, version 1.5. PDF-1.5 supports a larger variety of movie and sound formats, limited only by the number of plugins available for Adobe Reader\textsuperscript{\scriptsize\textregistered}. With PDF-1.6, support for 3D objects, stored in the U3D file format, has been added. See Table \ref{table:mime} for a list of viable media formats. The specification allows media file contents to be completely embedded into the PDF output, thus producing selfcontained PDF documents. This package provides an interface to embed movies, sounds and 3D objects into PDF documents for use with \LaTeX{} as well as pdf\LaTeX. Media file contents is incorporated into PDF output by default. This is done either directly during source processing using pdf\LaTeX{} or during conversion from Postscript to PDF using Ghostscript's \verb+ps2pdf+. The final PDF output can be viewed with Windows\textsuperscript{\scriptsize\textregistered} and Mac OS\textsuperscript{\scriptsize\textregistered} versions of Adobe Reader. However, embedded media file data can also be extracted and saved to disk from within Readers which support file attachments. This makes PDF documents a little more portable to Readers which do not ship with a multimedia plugin. \section{Installation} The file `movie15.sty' should be stored in a place where \LaTeX{} can find it. \section{Using the package} Invoke the package by putting the line \begin{verbatim} \usepackage[]{movie15} \end{verbatim} to the preamble of your document, i.\,e. somewhere between \verb+\documentclass+ and \verb+\begin{document}+. `movie15' takes the option `\verb+3D+'. It enables the 3D feature from the PDF-1.6 specification. Inclusion of 3D files into PDF is discussed separately in section~\ref{3dtut}. Currently, there are no further options. If PDF is generated via DVI and Postscript by the usual \verb+latex+ $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+ sequence of commands, the `graphicx' and `hyperref' packages are required and must be loaded \emph{after} `movie15'. In the case of pdf\LaTeX{}, the `graphicx' and `hyperref' packages are not required. Note, that more than one run may be necessary to resolve internally created cross-references. Appropriate warnings will be emitted in such cases. \section{Requirements} pdf\LaTeX{}, version $\ge1.20$, is needed for direct PDF output. If the package option `\verb+3D+' is set, `movie15' loads Michael Mehlich's `fp' package for fixed point arithmetic. Since it does not belong to the core packages of most \TeX{} distributions it must be installed prior to selecting the `\verb+3D+' option. Adobe Reader, version 6, is required for playing movies and sounds, version 7 for rendering embedded 3D content. Unfortunately, only Windows and Mac versions of Adobe Reader provide the necessary plugins. \section{The user interface} \subsection{Media inclusion}\label{usrif} Movies, sounds and 3D objects are embedded into the document using the command \begin{verbatim} \includemovie[]{}{}{} \end{verbatim} Unless left empty (cf. option `\verb+text+') the \verb++ and \verb++ arguments must be given in valid \TeX{} dimensions. Horizontal and vertical dimensions of the media clip are scaled independently to fit \verb++ and \verb++. \verb++ specifies the file name of the media clip. If the media file is embedded as part of the final PDF output, which is the default, it may reside wherever \TeX{} or Ghostscript search for input files, depending on the PDF producing method. Below, common options to \verb+\includemovie+ are listed. Options specific to embedding of 3D content are discussed separately in section~\ref{3dtut}. \begin{verbatim} attach[=false] \end{verbatim} By default, the embedded data stream is re-used as embedded file attachment. This makes `movie15' a little more portable to PDF Readers which do not have a multimedia plugin because it gives the user the opportunity to extract the media file and to save it to disk for later playback with an external player. However, support of file attachments is required. Re-use as file attachment can be suppressed with option `\verb+attach=false+'. Note, that `\verb+attach=false+' is a poor method to prevent the user from obtaining a copy of the media file. There are several (free) tools for decompressing and extracting stream objects from PDF files. \begin{verbatim} autopause \end{verbatim} Pause playing when the page is closed. \begin{verbatim} autoplay \end{verbatim} Put this option to the options list if you want the playback of the media clip to be started automatically after the page has opened. This is especially useful if there are multiple movie clips on the current page to be played at the same time. Also resumes playback of previously paused media. In the case of embedded sound being started this way, \verb++ and \verb++ can be safely set to `0pt' since no further user interaction is necessary to start playing. \begin{verbatim} autostop \end{verbatim} Stop playing when the page is closed. This is default behaviour. Override with option `\verb+continue+'. \begin{verbatim} autoresume \end{verbatim} Resume previously paused playback when the page is opened again. \begin{verbatim} continue \end{verbatim} Continue playback in background on premature page change. However, paused media remain paused. So do media that have reached the end or that still show the poster. \begin{verbatim} controls[=true|false] \end{verbatim} Player specific controls are displayed during playback of the media clip, if available. For movies and sounds the default is `\verb+false+'; controls are not shown. For 3D content, the default is `\verb+true+', since `\verb+false+' would make the 3D content non-interactive, i.\,e. not responsive to mouse interaction.% All animation would need be driven by JavaScript in this case. \begin{verbatim} depth= \end{verbatim} Specifies how far the media display area should extend below the bottom line of the running text. Any valid \TeX{} dimension is accepted. \begin{verbatim} externalviewer \end{verbatim} Opens and plays the media in an external application. \begin{verbatim} inline[=false] \end{verbatim} Media file \emph{data} are embedded into PDF output by default. This can be suppressed with option `\verb+inline=false+'. \begin{verbatim} label=