% % http://www.adobe.com/devnet/acrobat/pdfs/PDF32000_2008.pdf % % makeindex < aebpro_man.idx > aebpro_man.ind \documentclass{article} \usepackage[fleqn]{amsmath} \usepackage[% web={centertitlepage,designv, forcolorpaper,latextoc,pro},%usesf, aebxmp,eforms ]{aeb_pro} \usepackage[dvipsone,showembeds]{graphicxsp} \usepackage{aeb_mlink} \usepackage{array,longtable} %\usepackage{myriadpro} \usepackage[altbullet]{lucidbry} \usepackage[use3D]{rmannot} \usepackage{makeidx} \makeindex \usepackage{acroman} \usepackage[active]{srcltx} \setlongtables \def\expath{../examples/rma} \urlstyle{rm} \let\pkg\textsf \newdimen\aebdimen \aebdimen6pt %\partopsep \advance\aebdimen\partopsep \newcommand\bVerb[1][]{\begingroup#1\vskip\aebdimen\parindent0pt}% \def\eVerb{\vskip\aebdimen\endgroup\noindent} \def\takeMeasurei#1{\global\setbox\webtempboxi\hbox{\ttfamily#1}\egroup} \def\bxSize{\wd\webtempboxi+2\fboxsep+2\fboxrule} %\def\tutpath{doc/tutorial} %\def\tutpathi{tutorial} \DeclareDocInfo { university={\AcroTeX.Net}, title={ The \texorpdfstring{\texttt{rmannot} Package\\[1em]}{rmannot Package: } Rich Media Annotations\texorpdfstring{\\[1em]}{ }for Acrobat 9 Pro, or later}, author={D. P. Story}, email={dpstory@acrotex.net}, subject={Documentation for AeB Pro from AcroTeX}, talksite={\url{www.acrotex.net}}, version={v2.0, 2016/10/09}, keywords={Rich Media Annotations, SWF, FLV, MP3, AcroTeX, AcroFlex, LaTeX}, copyrightStatus=True, copyrightNotice={Copyright (C) \the\year, D. P. Story}, copyrightInfoURL={http://www.acrotex.net} } \nocopyright \copyrightyears{2008-\the\year} \def\dps{$\hbox{$\mathfrak D$\kern-.3em\hbox{$\mathfrak P$}% \kern-.6em \hbox{$\mathcal S$}}$} \universityLayout{fontsize=Large} \titleLayout{fontsize=LARGE} \authorLayout{fontsize=Large} \tocLayout{fontsize=Large,color=aeb} \sectionLayout{indent=-62.5pt,fontsize=large,color=aeb} \subsectionLayout{indent=-31.25pt,color=aeb} \subsubsectionLayout{indent=0pt,color=aeb} \subsubDefaultDing{\texorpdfstring{$\bullet$}{\textrm\textbullet}} \definePath{\urlAcroTeXBlog}{http://www.acrotex.net/blog} \def\anglemeta#1{$\langle\textit{\texttt{#1}}\rangle$} %\def\meta#1{\textit{\texttt{#1}}} \let\meta\anglemeta \let\amtIndent\leftmargini \def\bNH{\begin{NoHyper}}\def\eNH{\end{NoHyper}} \def\nhnameref#1{\bNH\nameref{#1}\eNH} \def\nhNameref#1{\bNH\Nameref{#1}\eNH} \def\nhurl#1{\bNH\url{#1}\eNH} \makeatletter \renewcommand{\paragraph} {\@startsection{paragraph}{4}{0pt}{6pt}{-3pt} {\normalfont\normalsize\bfseries}} \renewcommand{\subparagraph} {\@startsection{subparagraph}{5}{\parindent}{6pt}{-3pt}% {\normalfont\normalsize\bfseries}} \renewcommand*\descriptionlabel[1]{\hspace\labelsep \normalfont #1} \newcommand{\aebDescriptionlabel}[1]{% \setlength\dimen@{\amtIndent+\labelsep}% {\hspace*{\dimen@}#1}} \makeatother \newenvironment{aebDescript} {\begin{list}{}{\setlength{\labelwidth}{0pt}% \setlength{\leftmargin}{\leftmargin}% \setlength{\leftmargin}{\leftmargin+\amtIndent}% \setlength\itemindent{-\leftmargin}% \let\makelabel\aebDescriptionlabel }}{\end{list}} %\pagestyle{empty} %\parindent0pt\parskip\medskipamount \AcroVer{Beta} \newcommand{\myRMFiles}{% C:/Users/Public/Documents/My TeX Files/% tex/latex/aeb/aebpro/rmannot/RMfiles} \saveNamedPath{AcroAd}{\myRMFiles/Acro_Advertiser.swf} \saveNamedPath{horse1}{\myRMFiles/horse1.flv} \saveNamedPath{trek}{\myRMFiles/trek.mp3} \saveNamedPath{AcroLimerick}{\myRMFiles/AcroTeX_limerick.mp3} \makePoster[hiresbb]{AcroAd_poster}{\expath/AcroAd_poster} \makePoster[hiresbb]{aebmovie_poster}{\expath/aebmovie_poster} \makePoster[hiresbb]{horse1_poster}{\expath/horse1_poster} \definePath{\myPath}{C:/Users/Public/Documents/% My TeX Files/tex/latex/aeb/aebpro/rmannot/% examples/rm3da} \definePath{\myRMFiles}{% C:/Users/Public/Documents/My TeX Files/% tex/latex/aeb/aebpro/rmannot/RMfiles} \saveNamedPath{myDice}{\myPath/3dmodels/dice.u3d} \def\takeMeasure{\bgroup\obeyspaces\takeMeasurei} \def\takeMeasurei#1{\global\setbox\webtempboxi\hbox{\ttfamily#1}\egroup} \optionalPageMatter {% \makebox[\linewidth][c]{% \rmAnnot[poster=AcroAd_poster,enabled=pageopen]% {.5\linewidth}{.5\linewidth*\ratio{265bp}{612bp}}{AcroAd}}% } \chngDocObjectTo{\newDO}{doc} \begin{docassembly} var titleOfManual="The rmAnnot MANUAL"; var manualfilename="Manual_BG_Print_rmannot.pdf"; var manualtemplate="Manual_BG_Green.pdf"; // Blue, Green, Brown var _pathToBlank="C:/Users/Public/Documents/ManualBGs/"+manualtemplate; var doc; var buildIt=false; if ( buildIt ) { console.println("Creating new " + manualfilename + " file."); doc = \appopenDoc({cPath: _pathToBlank, bHidden: true}); var _path=this.path; var pos=_path.lastIndexOf("/"); _path=_path.substring(0,pos)+"/"+manualfilename; \docSaveAs\newDO ({ cPath: _path }); doc.closeDoc(); doc = \appopenDoc({cPath: manualfilename, oDoc:this, bHidden: true}); f=doc.getField("ManualTitle"); f.value=titleOfManual; doc.flattenPages(); \docSaveAs\newDO({ cPath: manualfilename }); doc.closeDoc(); } else { console.println("Using the current "+manualfilename+" file."); } var _path=this.path; var pos=_path.lastIndexOf("/"); _path=_path.substring(0,pos)+"/"+manualfilename; \addWatermarkFromFile({ bOnTop:false, bOnPrint:false, cDIPath:_path }); \executeSave(); \end{docassembly} \def\puncPt#1{#1} \begin{document} \maketitle \selectColors{linkColor=black} \tableofcontents \selectColors{linkColor=webgreen} \section{Introduction} Beginning with version 9, \textsf{Adobe Reader} and \textsf{Acrobat} contain an embedded \textsf{Adobe Flash Player} that will play \textsf{SWF}, \textsf{FLV}, and \textsf{MP3} files. A new annotation type, called a \emph{rich media annotation}, was developed to manage these media file types in a PDF file. The \texttt{rmannot} package supports the creation of rich media annotations (a \texttt{RichMedia} annotation type), and the embedding of \textsf{SWF}, \textsf{FLV}, and \textsf{MP3} files in a PDF. \textsf{SWF} animations, \textsf{FLV} video, and \textsf{MP3} sound can then be played within a PDF viewed within version~9 (or later) of \textsf{Adobe Reader} or \textsf{Acrobat}.\footnote{The \texttt{rmannot} package was written, in part, to support the {\AcroFLeX} Graphing package.} Source material for the creation of this package is the document \textsl{Adobe Supplement to the ISO 32000}, June 2008. This document contains the PDF specification---the so called, BaseLevel~1.7, ExtensionLevel~3 specification---of the rich media annotation. \exAeBBlogPDF{p=}\textbf{Examples.} In addition to the examples that ship with the \textsf{rmannot} package, there are numerous examples of \textsf{rmannot} on my \href{\urlAcroTeXBlog//?tag=rmannot-package}{{\AcroTeX} Blog} (having tag \textsl{rmannot-package}). There is also a whole series of articles on the \textbf{\href{\urlAcroTeXBlog/?cat=22}{Rich Media Annotation}} using \textbf{AeB Pro} and \textsf{rmannot}. \paragraph*{Version 2.0 or later.} With this version, we introduce 3D models. Version 9.0 of Acrobat introduced the rich media annotation, buried in the specifications for RMA are references to 3D models. This structure was designed for having 3D model and rich media (SWF, FLV) in the same annotation. We now support what I am calling the \textbf{RM3D} annotations What is created is not a 3D annotation, but a rich media annotation with 3D content. See \hyperref[RM3D]{Section~\ref*{RM3D}}, page~\pageref*{RM3D} for details. A simple example appears on page~\pageref*{RM3Dexample}. \section{Requirements} The requirements for your {\LaTeX} system, and well as any other software, is highlighted in this section. \subsection{{\LaTeX} Package Requirements} The following packages, in addition to the standard {\LaTeX} distribution, are required: \begin{enumerate} \item The \texttt{xkeyval} package is used to set up the key-value pairs of the \cs{rmAnnot} command. Get a recent version. \item AeB (\AcroTeX{} eDucation Bundle) The most recent version. In particular the \texttt{eforms} package and its companion package \texttt{insdljs}. The AeB Pro package is recommended. (All the demo files use AeB Pro.) Get it at \href{http://ctan.org/pkg/acrotex}{ctan.org/pkg/acrotex}. \item The \texttt{graphicxsp} Package. The latest version, I made some slight modifications of this package for \texttt{rmannot}. This package allows the embedding of poster graphics for use in the appearances of the annotations when they are not activated. Get it at \href{http://ctan.org/pkg/graphicxsp}{ctan.org/pkg/graphicxsp}. \item (Recommended) Many of the demo files use AeB Pro (\href{http://ctan.org/pkg/graphicxsp}{ctan.org/pkg/aeb-pro}) is a recommended addition to your {\AcroTeX} collection. \end{enumerate} The installation instructions for AeB and AeB Pro must be read very closely as there are certain JavaScript files that must be copied to the correct location on your local hard drive. \subsection{PDF Creator Requirements} The \textsf{rmannot} package supports \textbf{Acrobat Distiller 9.0} (or later) as the PDF creator. The document author must have \textbf{Acrobat 9.0 Pro} and its companion application \textbf{Distiller}. The document author typically uses dvips to produce a PostScript file, which is then distilled to obtain a PDF. \subsection{Supported Media Formats} \subsubsection{Supported Video Formats} The resource for video formats is \href{http://kb2.adobe.com/cps/405/kb405848.html}{Supported file formats | Acrobat, Reader}, see the sections \textbf{Video formats (Acrobat X Pro)} and \textbf{Video formats (Acrobat~9 Pro and Pro Extended)}. The \textsf{rmannot} package generally supports all formats listed there that have a `Yes' in the column labeled \textbf{Direct placement without transcoding}; in particular, \textsf{rmannot} supports \textbf{SWF}, \textbf{FLV}, \textbf{F4V}, \textbf{MP4}, \textbf{M4V}, \textbf{MOV}, \textbf{3GP}, \textbf{3G2}, and \textbf{MP3} files. Some of these are not supported by version~9. For greatest compatibility, use \textbf{SWF}, \textbf{FLV} (or \textbf{F4V}, Version~9.2 or later). \subsubsection{Supported Audio Format} The resource for audio formats is \href{http://kb2.adobe.com/cps/405/kb405848.html}{Supported file formats | Acrobat, Reader}, see the section \textbf{Audio formats (Acrobat)}. For assured compatibility, use \textbf{MP3} files for audio. \section{Installation} The installation is simple enough. Unzip \texttt{rmannot.zip} in a folder that is on your {\LaTeX} search path. Refresh your filename database, if appropriate. I am perhaps the last one using YandY, but if there is anyone else, there is one other thing to do. The distribution comes with the default poster file for the \textsf{MP3} file; the name of this file is \texttt{ramp3poster.eps} (found in the \texttt{graphics} subfolder). For YandY users, this file needs to be copied to a folder on the \texttt{PSPATH}. If you don't know what I'm talking about, follow the steps below. Open \textsf{dviwindo}, and go to \texttt{Preferences\;>\;Environment} and choose \texttt{PSPATH} from the drop down menu. Add the path \begin{Verbatim}[fontsize=\small] C:\yandy\tex\latex\contrib\rmannot\graphics\\ \end{Verbatim} at the end of your \texttt{PSPATH} string.\footnote{If your \textsf{YandY System} installation is elsewhere, enter that path.} It is important to have the double backslash at the end of the path. This tells the \textsf{YandY System} to search all subfolders for the graphics files. When you are finished, your \texttt{PSPATH} should look something like this: \begin{Verbatim}[fontsize=\small] C:\yandy\ps;C:\yandy\tex\latex\contrib\rmannot\graphics\\ \end{Verbatim} Be sure to separate these paths by a semicolon. \paragraph*{\textcolor{red}{Important:}} In recent versions of Acrobat, security restrictions have been put in place to prevent \textbf{Distiller} from reading files (the PostScript \textbf{file} operator does not work). Fortunately, Distiller has a switch that turns off this particular restriction. To successfully use this package, therefore, you need to run Distiller by using the \texttt{-F} command line switch. I personally use the WinEdt application as my text editor,\footnote{WinEdt home page: \url{www.winedt.com}} and have defined a Distiller button on my toolbar. The Distiller button executes the following WinEdt macro. \begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\footnotesize] Run(|"c:\Program Files\Adobe\Acrobat 9.0\Acrobat\acrodist.exe" -F "%P\%N.ps"|, '%P',0,0,'%N.ps - Distiller',1,1); \end{Verbatim} Note the use of the \texttt{-F} switch for \texttt{acrodist.exe}. If this package is used to create rich media annotations without the \texttt{-F} switch, you typically get the following error message in the Distiller log file \begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] %%[ Error: undefinedfilename; OffendingCommand: file ]%% \end{Verbatim} This tells you that either you have not started Distiller with the \texttt{-F} command line switch, or Distiller can't find one of the files that the \textbf{file} operator was trying to read. \paragraph*{Mac OS Users.} The above comments on the \texttt{-F} command line switch are for \textsf{Windows~OS} users, \textsf{Mac~OS} users must choose the \texttt{AllowPSFileOps} user preference, this is located in the \texttt{plist}, possibly located at \begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] /Users/[User]/Library/Preferences/com.adobe.distiller9.plist \end{Verbatim} You can use Spotlight, the search utility on Mac, to search for \texttt{com.adobe.distiller}. This finds the file \texttt{com.adobe.distiller9.plist}. Clicking on this find, Spotlight opens \texttt{com.adobe.distiller9.plist} in the \texttt{plist} editor, see \hyperref[plist]{Figure~\ref*{plist}}. If necessary, click on the arrow next to the Root to expand the choices, then click the up and down arrows at the far right in the \texttt{AllowPSFileOps} row to select \texttt{Yes} as the value. \begin{figure}[hbt]\setlength{\fboxsep}{0pt}\centering \fbox{\includegraphics[width=.75\linewidth]{plistEditor}} \caption{com.adobe.distiller9.plist}\label{plist} \end{figure} % \section{Options of this Package} \section{Setting the Paths and Posters} The paths to \textsf{SWF}/\textsf{FLV}/\textsf{MP3} files are required to appear in the preamble, and any poster graphics are required to appear in the preamble as well. \subsection{Setting the Paths} There are two types of paths: System paths to resources needed by \textbf{Acrobat Distiller}, and media paths to the files used in the document. \paragraph*{System Paths.} This package uses \textbf{Acrobat Distiller~9.0} (or later), and requires the document author to have \textbf{Acrobat 9 Pro}. In the \textsf{Acrobat} program folder is a \texttt{Multimedia Skins} folder. This folder contains skins (\textsf{SWF} files) used in providing playing controls to \textsf{FLV} video files, and in the \texttt{Players} subfolder you will find \texttt{VideoPlayer.swf} and \texttt{AudioPlayer.swf}. The former plays \textsf{FLV} files with an appropriate skin for user controls, the latter plays \textsf{MP3} files. The document author needs to set these paths to these files, which are passed on to the distiller. This is easily done using the \Com{AcroVer} command. \takeMeasure{\string\AcroVer[win|mac]\{\meta{version}\}}% \begin{dCmd*}[commandchars=!()]{\wd\webtempboxi+2\fboxsep+2\fboxrule} \AcroVer[win|mac]{!meta(version)} \end{dCmd*} In the preamble, or in the \texttt{rmannot.cfg} configuration, provide the type of operating system (\texttt{win} or \texttt{mac}) you are using and version of \textsf{Acrobat} you are using to build your RMA document. When no optional argument is passed, \texttt{win} is assumed (\textsf{Windows OS}). Possible values for \meta{version} are \texttt{DC}, a year (\texttt{2015} or later), or a version number, such as \texttt{9}, \texttt{10}, or \texttt{11}.\footnote{A value of \texttt{Beta} is also recognized, for those in the Beta Program of \textsf{Acrobat}.} At the time of this writing, the default is \cs{AcroVer\{11\}}. The \textsf{rmannot} package, based on the information passed to it by \cs{AcroVer}, builds the appropriated path and passes this path to the \cs{pathToSkins} command as its argument. Should the path be proven to be incorrect, you can hunt down the correct path and directly enter it in the preamble, or in the \texttt{rmannot.cfg} configuration file. For version XI (version 11) of \textsf{Acrobat}, for example, the path is, \takeMeasure{\string\pathToSkins\{C:/Program Files (x86)/Adobe/\%}% \begin{dCmd*}{\wd\webtempboxi+2\fboxsep+2\fboxrule} \pathToSkins{C:/Program Files (x86)/Adobe/% Acrobat 11.0/Acrobat/Multimedia Skins} \end{dCmd*} The path for the Mac OS may look like this, \takeMeasure{\string\pathToSkins\{/Applications/Adobe\string\ Acrobat\string\ 9\string\ Pro/Adobe\string\ Acrobat\string\ }% \begin{dCmd*}{\wd\webtempboxi+2\fboxsep+2\fboxrule} \pathToSkins{/Applications/Adobe\ Acrobat\ XI\ Pro/Adobe\ Acrobat\ Pro.app/Contents/Resources/Multimedia\ Skins} \end{dCmd*} These paths differ from platform to platform and \cs{AcroVer} tries to take all platforms and versions into consideration. %Note what the path is to the Multimedia Skins folder. The command %\cs{pathToSkins} also defines the path to the \texttt{Players} subfolder. %Future releases of \textsf{Acrobat} may change the name of the folders, so %a \Com{pathToPlayers} command is also provided; as with \cs{pathToSkins}, %\cs{pathToPlayers} takes one argument, the path to the players. \handpoint The \textsf{rmannot} distribution comes with a \texttt{rmannot.cfg} file. In this file, you can place the \cs{AcroVer} command with its appropriate arguments for your platform and version of \textsf{Acrobat}. Remember, if you update your \textsf{Acrobat}, update also the \meta{version} argument of \cs{AcroVer}. \paragraph*{Document Media Paths.} Each media file (\textsf{SWF}, \textsf{FLV}, \textsf{MP3}) must be declared in the preamble using the \Com{saveNamedPath} command. \takeMeasure{\string\saveNamedPath[\meta{mime\_type}]\{\meta{name}\}\{\meta{path}\}} \begin{dCmd}[commandchars=!()]{\wd\webtempboxi+2\fboxsep+2\fboxrule} \saveNamedPath[!meta(mime_type)]{!meta(name)}{!meta(path)} \end{dCmd} The first optional argument \meta{mime\_type} is normally not needed. It is the mime type of the file. Currently, only \textsf{SWF}, \textsf{FLV} and \textsf{MP3} files are supported, and the extension of the file name is isolated to determine the mime type. The second parameter \meta{name} is a \emph{unique} name that will be used to reference this media file. Finally, \meta{path} is full and absolute path to the media file. The path includes the file name and extension. For example,\takeMeasure{\string\saveNamedPath\{summertime\}\{C:/myMedia/Summertime.mp3\}} \begin{dCmd*}{\wd\webtempboxi+2\fboxsep+2\fboxrule} \saveNamedPath{mySWF}{C:/myMedia/AcroFlex3_demo.swf} \saveNamedPath{fishing}{C:/myMedia/100_0239.flv} \saveNamedPath{summertime}{C:/myMedia/Summertime.mp3} \end{dCmd*} Once the paths are defined in this way, the media files are referenced using their given names. This has a couple of purposes. \begin{enumerate} \item The names are used to determine if the media file has already been embedded in the document. Though the media clip may be used in several rich media annotations, the \texttt{rmannot} attempts to embed a media file only once. \item The command \cs{saveNamePath} uses \cs{hyper@normalise}, of the \texttt{hyperref} package, to ``sanitize'' special characters, so the path may contain characters that normally have special meaning to {\LaTeX}. \item Defining the path once leads to a consistent reference to the file paths, and reduces the chance of typos. \end{enumerate} A brief example to illustrate the use of the names assigned by the \cs{saveNamedPath} follows:\takeMeasure{\string\rmAnnot\{200bp\}\{200bp\}\{mySWF\}} \begin{dCmd*}{\wd\webtempboxi+2\fboxsep+2\fboxrule} \rmAnnot{200bp}{200bp}{mySWF} \end{dCmd*} See \Nameref{rmAnnot} for additional details on the \texttt{poster} key and the \cs{rmAnnot} command. The above example would use the default poster image to give a visual of the annotation when it is not activated. The next section discusses how to define and implement your own poster image. \paragraph*{Defining a RM Path.} The resources (\texttt{.flv}, \texttt{.swf}, \texttt{.mp3} files, for example) for your Flash application may reside on your local computer or in the Internet. As a way of reducing the amount of typing, you can use \Com{defineRMPath} to define common paths to your resources.\takeMeasure{\string\defineRMPath\{\meta{name}\}\{\meta{path}\}} \begin{dCmd}[commandchars=!()]{\wd\webtempboxi+2\fboxsep+2\fboxrule} \defineRMPath{!meta(name)}{!meta(path)} \end{dCmd} The command uses \cs{hyper@normalise} (of \textsf{hyperref}) to ``sanitize'' the path. The first argument \meta{name} is the name of the command to be created, and \meta{path} is the path. After the definition, the command \cs{\meta{name}} expands to \meta{path}. For example,\takeMeasure{\string\saveNamedPath\{summertime\}\{\string\myRMFiles/Summertime.mp3\}} \begin{dCmd*}{\wd\webtempboxi+2\fboxsep+2\fboxrule} \defineRMPath{\myRMFiles}{C:/myMedia} \saveNamedPath{mySWF}{\myRMFiles/AcroFlex3_demo.swf} \saveNamedPath{fishing}{\myRMFiles/100_0239.flv} \saveNamedPath{summertime}{\myRMFiles/Summertime.mp3} \end{dCmd*} We first define a path to our resources, then save those paths along with the file names. You can use \cs{defineRMPath} to define URLs as well {\small\takeMeasure{\string\defineRMPath\{\string\myRMURLs\}\{http://www.example.com/\string~dpspeaker/videos\}} \begin{dCmd*}{\wd\webtempboxi+2\fboxsep+2\fboxrule} \defineRMPath{\myRMURLs}{http://www.example.com/~dpspeaker/videos} \end{dCmd*} } Now, \cs{myRMURLs} points to your common video resources on the Internet. \subsection{Creating Posters}\label{createPosters} The \cs{rmAnnot} command has a \texttt{poster} key that is recognized as part of optional key-value pairs. The use of the \texttt{poster} key is optional, if you do not specify one, one will be generated for you. (More on the default poster appearance is presented below.) The poster image is visible when the rich media annotation is not activated. To create a poster for your rich media annotation, use a graphics application (Adobe Illustrator, Adobe Photoshop, etc.), and save as an EPS file. Move this file to your source file folder. Let's call this file \texttt{cool\_poster.eps}. In the preamble place the command, \takeMeasure{\string\makePoster\{myCP\}\{cool\_poster\}} \begin{dCmd*}{\wd\webtempboxi+2\fboxsep+2\fboxrule} \makePoster{myCP}{cool_poster} \end{dCmd*} The first argument is a \emph{unique name} for the graphic, the second argument is the path name of the graphic (without the extension). The name is used as the value of the \texttt{poster} key. The command actually has an optional first argument. This argument is passed to the command \cs{includegraphics} (of the \texttt{graphicx} package). The general syntax of the command is, \takeMeasure{\string\makePoster[\meta{options}]\{\meta{name}\}\{\meta{path\_to\_EPS}\}} \begin{dCmd}[commandchars=!()]{\wd\webtempboxi+2\fboxsep+2\fboxrule} \makePoster[!meta(options)]{!meta(name)}{!meta(path_to_EPS)} \end{dCmd} The command uses the \texttt{graphicxsp} package to embed the file in the PDF document. The graphical image can then be used multiple times in many annotations.For example, \takeMeasure{\string\rmAnnot[poster=myCP]\{200bp\}\{200bp\}\{mySWF\}} \begin{dCmd*}{\wd\webtempboxi+2\fboxsep+2\fboxrule} \rmAnnot[poster=myCP]{200bp}{200bp}{mySWF} \end{dCmd*} \noindent See \Nameref{rmAnnot} for additional discussion of the \texttt{poster} key and \cs{rmAnnot}. The graphic itself should have the same \emph{aspect ratio} as the rich media annotation; this is important if the graphic contains text or images that would get otherwise distorted. \paragraph*{Default Poster Image.} The \texttt{rmannot} package has default poster appearance. This poster appearance takes one of two forms. If the media file is \textsf{MP3}, an image of the AudioPlayer control bar is used; otherwise it is dynamically generated (with the correct dimensions) using the following PostScript operators: \begin{dCmd*}{.8\linewidth} \defaultPoster {% .7529 setgray 0 0 \this@width\space\this@height\space rectfill 10 \adj@measure 10 \adj@measure moveto .4 setgray /Helvetica \this@height\space 10 div selectfont (\rma@posternote) show } \end{dCmd*} The commands \cs{this@width} and \cs{this@height} are the width and height of the annotation. The command \cs{adj@measure} converts a measurement to a proportion of the smaller of the two measurements \cs{this@width} and \cs{this@height}.\footnote{The code presented here is a simplified version of the actual code found in \texttt{rmannot.dtx}. The definition of the default poster has a number of macros that can be redefined to change the placement of text, the color, size of the font, etc. See \texttt{rmannot.dtx} for details.} Note that, in the above code, some text is generated in the lower left corner of the annotation, the text is \cs{rma@posternote}. This command is populated by the value of the \texttt{posternote} key of the optional argument of \cs{rmAnnot}. The default value of \texttt{posternote} is `\textsf{AcroTeX Flash}' or `\textsf{AcroTeX Video}', depending on the file type of the media. This can be changed through the \texttt{posternote} key. The default poster itself can be redefined by a document author who is schooled in PostScript things, perhaps if only to change colors, or font, or location of the poster note. \section{\texorpdfstring{\protect\cs{rmAnnot}}{\CMD{rmAnnot}} and its Options}\label{rmAnnot} The \cs{rmAnnot} command creates a rich media annotation, new to version 9 of \textsf{Acrobat}/\textsf{Adobe Reader}. Media files (\textsf{SWF}, \textsf{FLV}, or \textsf{MP3}) can be either embedded in the document, or linked via a URL, and played. \textsf{Acrobat}/\textsf{Adobe Reader} have a built-in Flash player that plays \textsf{SWF}, \textsf{FLV} and \textsf{MP3} files. \goodbreak Media files in other formats need to be converted to one of these three supported formats.\footnote{The new \textbf{Acrobat 9 Pro Extended} can convert media files to \textsf{FLV}, but embed the converted file in the PDF, so we cannot really use that re-encoded file with our \texttt{rmannot} package. Adobe Flash Video Encoder converts many movie formats to \textsf{FLV} format, which can, in turn, be used in this package. Other utilities may be available as shareware or commercialware.} \subsection{\texorpdfstring{\protect\cs{rmAnnot}}{\CMD{rmAnnot}} Command} The primary command of this package is \Com{rmAnnot}, which has four arguments, one optional and three required. \takeMeasure{\string\rmAnnot[\meta{options}]\{\meta{width}\}\{\meta{height}\}\{\meta{name}\}} \begin{dCmd}[commandchars=!()]{\wd\webtempboxi+2\fboxsep+2\fboxrule} \rmAnnot[!meta(options)]{!meta(width)}{!meta(height)}{!meta(name)} \end{dCmd} The \meta{width} and \meta{height} parameters are what they are, the width and height to be used in the rich media annotation. The aspect ratio should be the same as the aspect ratio of the Flash media. The annotation can be resized using either \cs{resizebox} or \cs{scalebox} of the \texttt{graphicx} package to get the physical dimensions you want. \subparagraph*{For \textsf{MP3} Files.} After a careful measurement, the aspect ratio (width/height) of the \textsf{MP3} \texttt{AudioPlayer} control bar is about 9.6. In some of the demo files, I've been using a width of \texttt{268bp} and a height of \texttt{28bp}, and resize the annotation to what is desired. Use \texttt{268bp} and \texttt{28bp} for the width and height of an \textsf{MP3} file, and resize. \newtopic\indent The \meta{name} argument references a media file defined by the \cs{saveNamedPath} in the preamble. The \meta{options} are discussed in the subsection that follows. \subsubsection{\texorpdfstring{\protect\cs{rmAnnot}}{\CMD{rmAnnot}} Options} The \cs{rmAnnot} command has many key-value pairs that are passed to it through its first optional argument. Most of these key-value pairs correspond to options available through the user interface of \textsf{Acrobat}. Below is a listing of the key-values, and a brief description of each. \begin{description} \item[\texttt{name=\meta{string}}] The name (\meta{string}) of the annotation. If none is supplied, then \verb!aebRM\therm@Cnt! is used, where \texttt{rm@Cnt} is a {\LaTeX} counter that is incremented each time \cs{rmAnnot} is expanded. \item[\texttt{enabled=\meta{value}}] The \texttt{enabled} key determines when the annotation is activated, possible values are \texttt{onclick}, \texttt{pageopen}, and \texttt{pagevisible}. \begin{description}\def\NH{\hspace*{-\labelsep}} \item[\texttt{onclick}] The annotation is activated when the user clicks on the annotation, or is activated through JavaScript. \item [\texttt{pageopen}] The annotation is activated when the page containing the annotation is opened. \item[\texttt{pagevisible}] The annotation is activated when the page containing the annotation becomes visible. (Useful for continuous page mode.) \end{description} The default is \texttt{onclick}. \item[\texttt{deactivated=\meta{value}}] The \texttt{deactivated} key determines when the annotation is deactivated, possible values are \texttt{onclick}, \texttt{pageclose}, and \texttt{pageinvisible}. \begin{description} \item [\texttt{onclick}] The annotation is deactivated by user script or by right-clicking the annotation and choosing Disable Content. \item [\texttt{pageclose}] The annotation is deactivated when the page containing the annotation is closed. \item [\texttt{pageinvisible}] The annotation is deactivated when the page containing the annotation becomes invisible. (Useful for continuous page mode.) \end{description} The default is \texttt{onclick}. \item [\texttt{windowed=\meta{\upshape{true|false}}}] A Boolean, which if \texttt{true}, the media is played in a floating window. The default is \texttt{false}, the media is played in the annotation on the page. For information on how to set the floating window parameters, see \mlNameref{winparams}. \item [\texttt{url}=\meta{\upshape{true|false}}] A Boolean, which if \texttt{true}, the media is to be interpreted as an URL. The default is \texttt{false}, the media is embedded from the local hard drive and embedded in the PDF file. \item [\texttt{borderwidth=\meta{value}}] The borderwidth determines whether a border is drawn around the annotation when it is activated. Possible values are \texttt{none}, \texttt{thin}, \texttt{medium}, and \texttt{thick}. The default is \texttt{none}. \item [\texttt{poster=\meta{name}}] The name of a poster graphic created by \cs{makePoster}. See the section \Nameref{createPosters} for additional details. \item [\texttt{posternote=\meta{text}}] When the poster key is not given, the default poster is generated. A short note of text appears in the lower left-corner. The text for that note can be passed to the default poster appearance through \texttt{posternote}. See \mlNameref{createPosters} for additional details. \item [\texttt{invisible=\meta{\upshape{true|false}}}] A Boolean which, if present, \textsf{rmannot} creates a transparent poster for the RMA. The RMA has not hidden property as form fields do, the best you can do is to give the RMA a transparent poster and place it in an obscure corner of the page, or under a form field. Normally, if invisible is specified, the video content is played in a window (that is, \texttt{windowed} is specified as well). \textbf{Note:} The \texttt{invisible} option requires that you distill the document with a job options setting of \texttt{Standard\_transparency}, distributed with the \textsf{graphicxsp} package. \item \texttt{transparentBG=\meta{\upshape{true|false}}}: This option is available for \textsf{SWF} files only. Quoting the \emph{Adobe Supplement} document, ``A flag that indicates whether the page content is displayed through the transparent areas of the rich media content (where the alpha value is less than 1.0). If \texttt{true}, the rich media artwork is composited over the page content using an alpha channel. If false, the rich media artwork is drawn over an opaque background prior to composition over the page content.'' The default is \texttt{false}. \item [\texttt{passcontext=\meta{\upshape{true|false}}}] A Boolean, if \texttt{true}, passes right-click context to Flash. Should be used only if there is a way of deactivating the annotation, perhaps through JavaScript. Recognized only for \textsf{SWF} files. The default is \texttt{false}. \textsf{SWF} file developers can select this option to replace the \textsf{Acrobat} context menu with the context menu of the originating \textsf{SWF} file. When the user right-clicks the \textsf{SWF} file, the available options are from the originating file. \item [\texttt{skin=\meta{value}}] For playing a \textsf{FLV} file, seven different skins are available for the user to control the video, \texttt{skin1}, \texttt{skin2}, \texttt{skin3}, \texttt{skin4}, \texttt{skin5}, \texttt{skin6}, and \texttt{skin7}. Another possible value is \texttt{none}, for no skin. In the latter case, the media is played when activated, but there is no user interface to control the play. As for the description of each of the skins, \begin{aebDescript} \item [\texttt{skin1}] All Controls \item [\texttt{skin2}] Play, Stop, Forward, Rewind, Seek, Mute, and Volume \item [\texttt{skin3}] Play \item [\texttt{skin4}] Play and Mute \item [\texttt{skin5}] Play, Seek, and Mute \item [\texttt{skin6}] Play, Seek, and Stop \item [\texttt{skin7}] Play, Stop, Seek, Mute, and Volume \item [\texttt{none}] No Controls \end{aebDescript} You can add other skins as well. If you have \textsf{Adobe Flash Professional CS5}, you have access to other skins. Place a new skin in the location Acrobat expect them to be in (as defined by \cs{PathToSkins}, then place a declaration like the following in the preamble of your document: \begin{Verbatim}[xleftmargin=\amtIndent] \saveNamedPath{skin8}{\PathToSkins/% MinimaUnderPlayBackSeekCounterVolMuteNoFull.swf} \end{Verbatim} (Here, I've wrapped the line around for display purposes.) Now, when you use \cs{rmAnnot}, you can specify \texttt{skin=skin8} as a key-value in the optional parameter list. \item [\texttt{skinAutoHide=\meta{\upshape{true|false}}}] A Boolean, if \texttt{true}, the skin auto hides. Only valid for video files. \item [\texttt{skinBGColor=\meta{color\_hex}}] The color of the skin. The value is a color in hex format. The default is \texttt{0x5F5F5F}. Only valid for \textsf{FLV} files. \item [\texttt{skinBGAlpha=\meta{num}}] The alpha level of the skin, a number between 0 and 1. The default is 0.75. Only valid for \textsf{FLV} files. \item [\texttt{volume=\meta{num}}] The initial volume level of the video file, a number between 0 (muted) and 1 (max volume). The default is 1.0. Only valid for \textsf{FLV} files. % \item \texttt{speed}: Description quoted from the \textsl{Adobe % Supplement} document. ``A positive number specifying the speed to be used % when running the animation. A value greater than one shortens % the time it takes to play the animation, or effectively speeds % up the animation.'' The default is 1. % \item\texttt{playcount}: Description quoted from the \textsl{Adobe % Supplement} document. ``An integer specifying the play count for % this animation style. A nonnegative integer represents the % number of times the animation is played. A negative integer % indicates that the animation is infinitely repeated.'' The % default is -1. \item [\texttt{cuepoints=\meta{list\_cuepoints}}] If the video is encoded with cue points, you can associate a JavaScript action with each. The value of \texttt{cuepoints} is a comma delimited list of cue points. See the paragraph \Nameref{cuepoints} for more details. \item [\texttt{resources=\meta{list}}] Use this key to list all files that are required to run a \textsf{SWF} file. The value of the resources key is a \emph{comma-delimited} list of path names created by the \cs{saveNamedPath} command. \emph{The files referenced within this key are embedded in the PDF.} Files that are on the Internet---and are played from the Internet---should not be listed here. \item [\texttt{flashvars=\meta{vars}}] Flash developers can use the \texttt{flashvars} key to add ActionScript variables for the \textsf{SWF} file. See the discussion of \textbf{\nhnameref{NameCmds}} in the paragraph below. \end{description} \paragraph*{The \cs{Name} and \cs{urlName} commands.}\label{NameCmds} Within the optional parameters of the \cs{rmAnnot} command, two convenience commands, \Com{Name} and \Com{urlName}, are defined. They can be used, for example, with the \texttt{flashvars} key. The \cs{Name} command may be used to set the value of a flash variable. \cs{Name} has one argument, the symbolic name of a file embedded by \cs{saveNamedPath}. The expansion of \cs{Name\{\meta{name}\}} will appear in the Resources tab of the Edit Flash dialog box. For example, if we define \texttt{myVid} as \begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] \defineRMPath{\myRMFiles}{C:/acrotex/video} \saveNamedPath{myVid}{\myRMFiles/assets/myVid.flv} \end{Verbatim} then \cs{Name\{myVid\}} expands to \texttt{myVid.flv}. If the path is grouped with braces, like so, \begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] \saveNamedPath{myVid}{\myRMFiles/{assets/myVid.flv}} \end{Verbatim} then \verb!\Name{myVid}! expands to \texttt{assets/myVid.flv}. This latter form corresponds to adding a directory using the Add Directory button on the Resources tab of the Edit Flash dialog box. We can then use \cs{Name} as follows: \begin{Verbatim}[xleftmargin=\amtIndent] \rmAnnot[flashvars={source=\Name{myVid}}, resources={myVid}]{320bp}{240bp}{mySWF} \end{Verbatim} where \texttt{mySWF} is the name of an \textsf{SWF} application that takes a flash variable named \texttt{source}, the value of the variable is the video to be played. The \cs{urlName} command is designed for resources on the Internet, and which are passed to the \textsf{SWF} application with a flash variable. \begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] \defineRMPath{\myRMURLs}{http://www.example.com/~dpspeaker/videos} \saveNamedPath{myVid}{\myRMURLs/myVid.flv} \end{Verbatim} The expansion of \verb!\urlName{myVid}! is \begin{Verbatim}[xleftmargin=\amtIndent] http://www.example.com/~dpspeaker/videos/myVid.flv \end{Verbatim} We can then use \cs{urlName} as follows: \begin{Verbatim}[xleftmargin=\amtIndent] \rmAnnot[flashvars={source=\urlName{myVid}}]{320bp}{240bp}{mySWF} \end{Verbatim} Note that we don't list \texttt{myVid} as a resource, we just pass the URL to \texttt{mySWF} as a flash variable. \paragraph*{Note.} The \cs{Name} and \cs{urlName} commands are defined within the optional parameters of \textsf{Acrobat} form fields created by the \textsf{eforms} package. \paragraph*{On Cue Points.}\label{cuepoints} A cue point is any significant moment in time occurring within a video clip. Cue points can be embedded in the \textsf{FLV} using \textsf{Adobe Flash Professional}, or some other video encoder. The value of the \texttt{cuepoints} key is a list of cue points data, a ``typical example'' is \begin{Verbatim}[fontsize=\footnotesize] \newcommand{\myCuePoints}{% {type=nav,name=Chapter1,time=0,action={console.println("Chapter1")}},% {type=nav,name=Chapter2,time=1883,action={console.println("Chapter2")}},% {type=nav,name=Chapter3,time=5197,action={console.println("Chapter3")}},% {type=nav,name=Chapter4,time=6817,action={console.println("Chapter4")}},% {type=nav,name=Chapter5,time=9114,action={console.println("Chapter6")}},% {type=nav,name=Chapter6,time=12712,action={console.println("Chapter6")}} } \end{Verbatim} \textbf{\textcolor{red}{Comments:}} Having made such a definition, we then say \verb!cuepoints={\myCuePoints}!, note that \cs{myCuePoints} must be enclosed in braces. Note also in the above example, that the comment character (\texttt{\%}) is used after each comma (\texttt{,}) in a line break. Because of the way the argument is initially parsed, these comment characters are needed. \newtopic\indent Each of the cue points is a comma-delimited list of key-value pairs; the keys are \texttt{type}, \texttt{name}, \texttt{time}, and \texttt{action}. Each of these are briefly described. \begin{aebDescript} \item [\texttt{type=\meta{\upshape nav|event}}] Possible values for this key are \texttt{nav} and \texttt{event}, and describes the type of cue point this is. \begin{description} \item [\texttt{type=nav}] Navigation cue points enable users to seek to a specified part of a file. Embed Navigation cue points in the \textsf{FLV} stream and \textsf{FLV} metadata packet when the \textsf{FLV} file is encoded. Navigation cue points create a keyframe at the specified cue point location, so you can use code to move a video player’s playhead to that location. You can set particular points in an \textsf{FLV} file where you might want users to seek. For example, your video might have multiple chapters or segments, and you can control the video by embedding navigation cue points in the video file.\footnote{Taken in part from \url{http://www.peachpit.com/articles/article.aspx?p=663087}} \item [\texttt{type=event}] Event cue points can also be embedded in your \textsf{FLV} stream and \textsf{FLV} metadata packet when video clip is encoded. You can write code to handle the events that are triggered at specified points during \textsf{FLV} playback.\footnote{Ibid.} \end{description} \item [\texttt{name=\meta{name}}] The name of the cue point \item [\texttt{time=\meta{time}}] The time in milliseconds the cue point occurs. \item [\texttt{action=\meta{script}}] The JavaScript code that is executed when this cue point is reached. \end{aebDescript} \subsubsection{Setting the Floating Window Parameters}\label{winparams} When the \texttt{windowed} key is set to \texttt{true}, the rich media annotation appears in a floating window. Use the \Com{setWindowDimPos} command to set the dimensions of the window and its positioning.\takeMeasure{\string\setWindowDimPos\{\meta{KV-pairs}\}} \begin{dCmd}[commandchars=!()]{\wd\webtempboxi+2\fboxsep+2\fboxrule} \setWindowDimPos{!meta(KV-pairs)} \end{dCmd} \CmdLoc This command may be placed anywhere and will take affect for the next rich media annotation created by \cs{rmAnnot}. \PD There are a number of key-value pairs (\meta{KV-pairs}) for setting the floating window; the default values are normally adequate for most applications. \begin{description} \item [\texttt{width=\meta{KV-pairs}}] The width is described by three \emph{key-value pairs}, \texttt{default}, \texttt{max}, and \texttt{min}, measured in default user space units. The \meta{KV-pairs} have the form \texttt{\meta{key}:\meta{value}}. For example, \texttt{width=\{default=300,max=600,min=80\}}. Default values: \texttt{default}: \texttt{288}, \texttt{max}:\texttt{576}, \texttt{min}: \texttt{72}. \item [\texttt{height=\meta{KV-pairs}}] The height is described by three \emph{key-value pairs}, \texttt{default}, \texttt{max}, and \texttt{min}, measured in default user space units. The \meta{KV-pairs} have the form \texttt{\meta{key}:\meta{value}}. For example, \texttt{height=\{default=300,max=600,min=80\}}. Default values: \texttt{default}: \texttt{216}, \texttt{max}:\texttt{432}, \texttt{min}: \texttt{72}. \item[\texttt{position=\meta{\upshape{halign|valign|hoffset|voffset}}}] The position of the floating window is described by four key-value pairs. \begin{description} \item [\texttt{halign=\meta{\upshape{near|center|far}}}] The \texttt{halign} describes the horizontal alignment of the window. Valid values are \texttt{near}, \texttt{center} and \texttt{far}. The default is \texttt{far}. For languages that read from left-to-right, a value of \texttt{near} refers to the left edge of the viewing window; whereas \texttt{far} refers to the right edge of the viewing window. (For right-to-left reading languages, the description of \texttt{near} and \texttt{far} are reversed.) \item [\texttt{valign=\meta{\upshape{near|center|far}}}] The \texttt{valign} parameter describes the vertical alignment of the window. Valid values are \texttt{near}, \texttt{center} and \texttt{far}. The default is \texttt{near}. \item [\texttt{hoffset=\meta{num}}] The description of \texttt{hoffset} is paraphrased from the \textsl{Adobe Supplement} document: The offset from the alignment point specified by the \texttt{halign} key. A positive value for \texttt{hoffset}, when \texttt{halign} is either \texttt{near} or \texttt{center}, offsets the position towards the \texttt{far} direction. A positive value for \texttt{hoffset}, when \texttt{halign} is \texttt{far}, offsets the position towards the \texttt{near} direction. The default is~18. \item[\texttt{voffset=\meta{num}}] The description of \texttt{voffset} is paraphrased from the \textsl{Adobe Supplement} document: The offset from the alignment point specified by the \texttt{valign} key. A positive value for \texttt{voffset}, when \texttt{valign} is either \texttt{near} or \texttt{center}, offsets the position towards the \texttt{far} direction. A positive value for \texttt{voffset}, when \texttt{valign} is \texttt{far}, offsets the position towards the \texttt{near} direction. The default is~18. \end{description} \end{description} In layman's terms the combination of \texttt{halign=far,\,valign=near} puts the floating window in the upper right corner of the active window of \textsf{Adobe Reader/Acrobat}, assuming a left-to-right reading language. The values of \texttt{voffset=18,\,hoffset=18}, moves the floating window 18 points down and 18 points to the left. That would be its initial position. \paragraph*{\textcolor{red}{Note}}: This feature, the positioning of the window, never worked in Version~9, but has been implemented for Version~10. \newtopic\indent The \Com{resetWindowDimPos} command can be used to reset the floating window parameters to their default values. \takeMeasure{\string\resetWindowDimPos} \begin{dCmd}{\wd\webtempboxi+2\fboxsep+2\fboxrule} \resetWindowDimPos \end{dCmd} \subsection{Examples} In this section, several examples are presented that illustrate the \cs{rmAnnot} and some of the key-value pairs. \subsubsection{Posters} The poster is an image that is displayed when the rich media annotation is not activated. If a poster is not specified using the \texttt{poster} key, one is supplied for it. Consider the following Flash animation. \begin{center} \resizebox{!}{.75in}{\rmAnnot{612bp}{265bp}{AcroAd}}\quad \resizebox{!}{.75in}{\rmAnnot[poster=AcroAd_poster]{612bp}{265bp}{AcroAd}}% \end{center} Above are two rich media annotations, each running the same \textsf{SWF} file. The one on the left uses the default poster, the one on the right uses a custom poster. In the annotation on the left, you see the default \texttt{posternote}, this can be changed using the \texttt{posternote} key. The custom poster was obtained by viewing the \textsf{SWF} file in Adobe Flash Player~9, then printing one of the frames to Adobe PDF, cropping the PDF, then saving the resulting PDF as an EPS file. After you crop the printed image, you can determine its dimensions by moving your mouse to the lower-left corner; the width and height values should appear. Use these in setting up your annotation. The verbatim listing for the two above annotations is found below. \takeMeasure{ \string\resizebox\{!\}\{.75in\}\{\string\rmAnnot\{612bp\}\{265bp\}\{AcroAd\}\}\string\quad} \begin{dCmd*}{\wd\webtempboxi+2\fboxsep+2\fboxrule} \begin{center} \resizebox{!}{.75in}{\rmAnnot{612bp}{265bp}{AcroAd}}\quad \resizebox{!}{.75in}{% \rmAnnot[poster=AcroAd_poster]{612bp}{265bp}{AcroAd}} \end{center} \end{dCmd*} \noindent The poster \texttt{AcroAd\_poster} was defined in the preamble of this document. Below is the same video, the one on the left is a generic poster created from a {\LaTeX} source file, then saved as an EPS file, the one on the right was obtained from the poster page generated by \textsf{Acrobat}. (See the paragraph below, \hyperref[acroposter]{page~\pageref*{acroposter}}, for details on how this was done.) \begin{center} \resizebox{2in}{!}{% \rmAnnot[poster=aebmovie_poster]{209bp}{157bp}{horse1}}\quad \resizebox{2in}{!}{% \rmAnnot[poster=horse1_poster]{209bp}{157bp}{horse1}} \end{center} The verbatim listing for the two above annotations follows: \takeMeasure{ \string\rmAnnot[poster=aebmovie\_poster]\{209bp\}\{157bp\}\{horse1\}\}\string\quad}% \begin{dCmd*}{\wd\webtempboxi+2\fboxsep+2\fboxrule} \resizebox{2in}{!}{% \rmAnnot[poster=aebmovie_poster]{209bp}{157bp}{horse1}}\quad \resizebox{2in}{!}{% \rmAnnot[poster=horse1_poster]{209bp}{157bp}{horse1}} \end{dCmd*} Posters and media files are embedded only once, so using the same poster and/or media file multiple times does not increase the file size significantly. For \textsf{MP3} files, the default poster is an EPS file that is an image of the player control bar, the example below shows the \textsf{MP3} poster and audio player. \begin{center} \resizebox{!}{14bp}{\rmAnnot{268bp}{28bp}{trek}} \end{center} The code for the above annotation follows: \takeMeasure{\string\resizebox\{!\}\{14bp\}\{\string\rmAnnot\{268bp\}\{28bp\}\{trek\}\}}% \begin{dCmd*}{\wd\webtempboxi+2\fboxsep+2\fboxrule} \resizebox{!}{14bp}{\rmAnnot{268bp}{28bp}{trek}} \end{dCmd*} \noindent A custom poster can be inserted using the \texttt{poster} key, as usual. \paragraph*{The \textsf{Acrobat Pro} generated poster.}\label{acroposter} To acquire the same poster image that \textsf{Acrobat} generates, use the following steps: \begin{enumerate} \item Open \textsf{Acrobat} \item Drag and drop your \textsf{SWF} or \textsf{FLV} file onto an empty \textsf{Acrobat} window \item Press \textbf{Ctrl-P}, or select {File > Print} \item Select \textsf{Adobe PDF} as the printer \item Select \textbf{Choose paper source by PDF page size} \item Select \textbf{Use custom paper size when needed} \item Press \textbf{OK} \item A new PDF should be created, and it should be the same size as the poster image \item Choose {File > Save As}, select \texttt{Encapsulated PostScript (*.eps)} as the \textbf{Save as type} \item Press \textbf{Save}, and save to an appropriate folder. \end{enumerate} \subsubsection{Skin Options} When a \textsf{FLV} video file is used, the video is played by the VideoPlayer.swf and uses one of the seven standard skins. Customizing information is actually passed using FlashVars. (For \textsf{FLV} files, the user does not have access to the FlashVars, the application, in this case, this package, uses the FlashVars.) Customizing options include a choice of skin, setting the auto hide flag, a choice of the color of the skin, setting the opacity of the skin and setting the initial volume level. The following illustrates some of the options on a short \textsf{FLV} video with a horse theme. \begin{center} \resizebox{2in}{!}{\rmAnnot[posternote=All Controls]{209bp}{157bp}{horse1}}\quad \resizebox{2in}{!}{\rmAnnot[posternote={skin6: Play, Seek, Stop},skin=skin6, skinBGColor=0xFF0000,skinBGAlpha=0.25]{209bp}{157bp}{horse1}} \end{center} The video on the left shows the default settings (default skin, skin alpha, volume level, etc.), while the same video on the right uses skin6, with skin color of \texttt{0xFF0000} (red) and skin alpha level set to 0.25. \begin{center} \setLinkText[\A{\JS{% var rm=this.getAnnotRichMedia({nPage: this.pageNum, cName: "acrolimerick"});\r if (rm.activated) rm.callAS("multimedia_play");\r else rm.activated=true; }}]{\includegraphics[width=2in]{AeB_Logo}}\\[1ex] \resizebox{!}{14bp}{\rmAnnot[name=acrolimerick]{268bp}{28bp}{AcroLimerick}} \end{center} Note, click on the {\AcroTeX} logo to play an \textsf{MP3} file. \subsection{Third-party Video Players} When you play an \textsf{FLV} file, the \textsf{SWF} file \texttt{VideoPlayer.swf} is embedded in the PDF. It is \texttt{VideoPlayer.swf} that plays the \textsf{FLV} file. It is this \textsf{SWF} file that allows us to customize the look of the RMA, what skin to use, skin color, skin opacity, value, speed, and so on. The \texttt{VideoPlayer.swf} file, which is shipped with Acrobat Pro, version~9 or later, lacks several useful features, among these are the ability to play more than one video in the same rich media annotation (RMA). In the past year, there have been two extensions to Adobe's \texttt{VideoPlayer.swf}: \begin{itemize} \item \texttt{VideoPlayerX.swf} is an extension to the video player shipped by Adobe. This one is being developed by \textbf{\href{http://www.uvsar.com/projects/acrobat/videoplayerx/}{UVSAR}}. Full documentation can be found on this page. Both documentation and the widget itself are found in the \texttt{videoplayerx} folder of the \pkg{rmannot} package distribution. \item \texttt{VideoPlayerPlus.swf} is available from Joel Geraci's web site \mlhref{http://blogs.adobe.com/pdfdevjunkie/2010/03/introducing_the_video_player_p.html} {The PDF Developer Junkie Blog}. Joel is a guru at Adobe. Extended features are in the form of additional JavaScript API to play more than one video in an RMA, change skins, change skin color, and a few others. Full documentation can be found on the reference blog page. {\setlength{\fboxsep}{2\fboxsep}\fcolorbox{blue}{webyellow}{\parbox{\linewidth-2\fboxsep-2\fboxrule}{\bfseries \color{red}Beginning 2016/10/09, the use of \texttt{VideoPlayerPlus.swf} is deprecated, and defaults to \texttt{VideoPlayerX.swf}.}}} % I have extensively tested the \texttt{VideoPlayerPlus.swf}, and it seems to % work as advertised, no problem. \end{itemize} \textbf{Installation of third-party players.} If you want to use either or both of these video players, download them from the appropriate web site: \begin{itemize} \item \href{http://www.uvsar.com/projects/acrobat/videoplayerx/} {VideoPlayerX.swf}: Also available in the \texttt{videoplayerx} folder. \item \st{VideoPlayerPlus.swf} % \href{http://blogs.adobe.com/pdfdevjunkie/2010/03/introducing_the_video_player_p.html} % {VideoPlayerPlus.swf} \end{itemize} If you download from \href{http://www.uvsar.com/projects/acrobat/videoplayerx/}{UVSAR}, rename the SWF widget to \texttt{VideoPlayerX.swf}; or simply retrieve it from the \texttt{videoplayerx} folder. Place \texttt{VideoPlayerX.swf} into the same folder that contains Adobe's \texttt{VideoPlayer.swf}. This is where the \textsf{rmannot} package will look for it. Once you have installed the widgets \textsf{rmannot} can use it. If you want to the {UVSAR} extension \texttt{VideoPlayerX.swf}, make following declaration in the preamble: \bVerb\takeMeasure{\string\useVideoPlayerPlus}% \def\1{\makebox[0pt][l]{\hspace*{\linewidth}\quad\normalfont(defaults to \cs{useVideoPlayerX})}} \begin{minipage}{\bxSize} \begin{Verbatim}[frame=single,commandchars=!(),,rulecolor=\color{red}] \useVideoPlayerX !1!st(\useVideoPlayerPlus) \end{Verbatim} \end{minipage}\eVerb \redpoint On 13 Oct 2011, \textbf{\href{http://www.uvsar.com/projects/acrobat/videoplayerx/}{UVSAR}} published build VP10.2 of \textbf{VideoPlayerX}. The new widget subsumes the \textbf{VideoPlayerPlus} of \mlhref{http://blogs.adobe.com/pdfdevjunkie/2010/03/introducing_the_video_player_p.html}{Joel Geraci}. The build is targeted at Flash Player~10, so \textbf{VideoPlayerX} requires \textsf{Adobe Acrobat} or \textsf{Adobe Reader~9.2}, \textsf{Acrobat} is required to build the document using \textsf{rmannot}, but \textbf{Reader} is only needed to view the document. Therefore, if extended API is needed for your document, I would recommend the use of \textbf{VideoPlayerX}. \redpoint On 28 Oct 2014, \textbf{\href{http://www.uvsar.com/projects/acrobat/videoplayerx/}{UVSAR}} published build VP10.4 of \textbf{VideoPlayerX}; this is the one that in the \texttt{videoplayerx} folder. \exAeBBlogPDF{p=} Articles and examples of the use of these players are found at the \href{\urlAcroTeXBlog}{{\AcroTeX} Blog}, articles on the \href{\urlAcroTeXBlog/?tag=rmannot-package}{rmannot package} illustrate each of these players; more generally, there are multiple articles on \href{\urlAcroTeXBlog/?cat=22}{rich media annotations}. \newtopic In addition to {\AcroTeX} Blog articles on the topic, sample files for the \textbf{VideoPlayerX} that come with the distribution are \texttt{vpx-btn.tex} and \texttt{vpn-combo.tex}. \subsubsection{JavaScript/ActionScript API for Video Players} Normally, we use \cs{rmAnnot} to create a RMA to play a \textsf{FLV} (or \textsf{SWF} or \textsf{MP3}) without any controls. The user clicks on the RMA and the media content plays. For \textsf{FLV} files, a skin may be provided to control over the movie once the RMA becomes activated. For a fancier presentation, you might want to create control buttons to control the movie; to do that, you need to use the JavaScript API for the RMA. In this section we document the JavaScript API for RMA. The resources for this section are the \href{http://livedocs.adobe.com/acrobat_sdk/9.1/Acrobat9_1_HTMLHelp/wwhelp/wwhimpl/js/html/wwhelp.htm?href=JS_API_AcroJSPreface.87.1.html&accessible=true} {JavaScript for Acrobat API Reference} and \textbf{\href{http://www.uvsar.com/projects/acrobat/videoplayerx/}{UVSAR}}. %\href{http://blogs.adobe.com/pdfdevjunkie/2010/03/introducing_the_video_player_p.html}{The PDF Developer Junkie Blog}, \newtopic\noindent The basic methodology for passing a command to the the video player: \begin{enumerate} \item \textbf{Get the RMA object.} To do this use either the \texttt{Doc.getAnnotRichMedia()} or \texttt{Doc.getAnnotsRichMedia()} methods. Note that in the latter method the word \texttt{Annots} is plural, the plural form distinguishes these to methods from each other. The former gets a single RMA object, while the latter returns an array of RMA objects. For work with \textsf{rmannot}, I prefer the use of \texttt{Doc.getAnnotRichMedia()}. \item[] \texttt{Doc.getAnnotRichMedia()} takes two arguments, the first is the page number, and second is the name (a string) of the annot. For example \begin{Verbatim}[xleftmargin=\amtIndent] var rma = this.getAnnotRichMedia(this.pageNum, "myCoolRMA"); \end{Verbatim} The first argument is normally \texttt{this.pageNum}, which is a JavaScript property referring to the current page. \item \textbf{Activate the RMA.} Use the \texttt{RMA.activated} property, a Boolean: \begin{Verbatim}[xleftmargin=\amtIndent] rma.activated=true; \end{Verbatim} You can, as an alternative say, \verb|if(!rma.activated) rma.activated=true;| \item \textbf{Make the call(s).} Use the \texttt{callAS} method of the RMA object. For example, if you want to play the video, you might say, \begin{Verbatim}[xleftmargin=\amtIndent] rma.callAS("multimedia_play"); \end{Verbatim} \end{enumerate} Putting these lines together to play media, we have \begin{Verbatim}[xleftmargin=\amtIndent] var rma = this.getAnnotRichMedia(this.pageNum, "myCoolRMA"); if(!rma.activated) rma.activated=true; rma.callAS("multimedia_play"); \end{Verbatim} Those are the basics of making a call over the ``bridge'' to the video player widget. In the rest of the section, we concentrate on the JavaScript APIs, the third line above \texttt{rma.callAS("multimedia\_play");}. The first argument of the \texttt{callAS} method is a string which names the method to use. Note that this first argument is a string. Additional argument may be used if the multimedia method requires them. \paragraph*{The Scripting Bridge between JavaScript and ActionScript.} When a JavaScript method, such as \texttt{rma.callAS("multimedia\_play")}, is executed on the PDF side, the specified ActionScript function \texttt{multimedia\_play()} is executed in the \textsf{SWF} widget (for example, in \texttt{VideoPlayer.swf}). The \texttt{callAS} communicates across what is called the ``scripting bridge'' to the ActionScript engine. For more information on the scripting bridge, see the \textbf{\href{\urlAcroTeXBlog/?tag=scripting-bridge} {\AcroTeX{} Blog}}. \subsubsection{Core API} The following methods are defined for all three players. The first argument of the \texttt{callAS} method is a string, which names the (ActionScript) method to use in the video player widget. The \texttt{rmannot} package defines some convenience commands to give the user a consistent experience between video players (\textbf{VideoPlayer}, \textbf{VideoPlayerX}). %\textbf{VideoPlayerPlus}, \begin{flushleft} \begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}>{\small}b{4in}>{\small}l@{}} \multicolumn{1}{>{\bfseries}l}{Method/Description}&\multicolumn{1}{>{\bfseries}l}{Command}\\\hline {\Large\strut}\texttt{multimedia\_play():void}&\cs{mmPlay}\\ Play the video or sound clip from the current location\\[6pt] % \texttt{multimedia\_pause():void}&\cs{mmPause}\\ Pause playback of the current media\\[6pt] % \texttt{multimedia\_rewind():void}&\cs{mmRewind}\\ Rewind the media clip to the beginning. This method does not pause the clip.\\[6pt] % \texttt{multimedia\_nextCuePoint():void}&\cs{mmNextCuePoint}\\ Move the play head to the next cue (chapter) point\\[6pt] % \texttt{multimedia\_prevCuePoint():void}&\cs{mmPrevCuePoint}\\ Move the play head to the previous (chapter) point\\[6pt] % \texttt{multimedia\_seek(time:Number):void}&\cs{mmSeek}\\ Move the play location to an offset of time from the beginning of the media, where time is measured in seconds.\\[6pt] % \texttt{multimedia\_mute():void}&\cs{mmMute}\\ Mute the audio of the media\\[6pt] % \texttt{multimedia\_volume(volume:Number):void}&\cs{mmVolume}\\ Set the volume level. The volume is a number between 0 and 1 inclusive. A value of 0 mutes the audio, while a volume of 1 sets the volume level to the maximum level. \end{tabular*} \end{flushleft} \goodbreak \paragraph*{Examples of usage}\leavevmode \begin{Verbatim}[xleftmargin=\amtIndent] var rma = this.getAnnotRichMedia(this.pageNum, "myCoolRMA"); if(!rma.activated) rma.activated=true; rma.callAS(\mmVolume, .5); // half-volume rma.callAS(\mmPlay); // and play it \end{Verbatim} \begin{comment} \subsubsection{API of VideoPlayerPlus} The \textbf{VideoPlayerPlus} supports all the functions of the core API, and adds four more functions. \begin{flushleft} \begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}>{\small}b{4in}>{\small}l@{}} \multicolumn{1}{>{\bfseries}l}{Method/Description}&\multicolumn{1}{>{\bfseries}l}{Command}\\\hline {\Large\strut}\texttt{multimedia\_source(path:string):void}&\cs{mmSource}\\ Sets a new source file for the video. The video can either be embedded resource or a URL to streaming content.\\[6pt] % \texttt{multimedia\_skin(path:string):void}&\cs{mmSkin}\\ Sets a new skin file to be used by the player. This should be an embedded resource.\\[6pt] % \texttt{multimedia\_skinBackgroundColor(color:uint):void}&\cs{mmSkinColor}\\ Sets a new background color for the player skin in the form of \texttt{0xRRGGBB}.\\[6pt] % \texttt{multimedia\_skinAutoHide(state:boolean):void}&\cs{mmSkinAutoHide}\\ Sets the auto hide behavior for the player bar. [\texttt{true} or \texttt{false}] \end{tabular*} \end{flushleft} \paragraph*{Examples of usage} %\vspace{-\baselineskip} \begin{Verbatim} var rma = this.getAnnotRichMedia(this.pageNum, "myCoolRMA"); if(!rma.activated) rma.activated=true; // use embedded video as source rma.callAS(\mmSource, "myVideo.flv"); // use video on web as source // rma.callAS(\mmSource, "http://www.example.com/myCool.flv"); rma.callAS(\mmPlay); // and play it \end{Verbatim} \end{comment} \subsubsection{API of VideoPlayerX} The \textbf{VideoPlayerX} redefines many of the core API, which returned void, to methods that return meaningful information. It also adds many new methods. In the table below, the functions marked with an `$*$' are also core functions that have been re-defined to have a return value. \begingroup\setlength{\extrarowheight}{1mm}%\setlength{\LTleft}{0pt}\setlength{\LTright}{0pt}% \begin{longtable}{@{}>{\small}b{4in}>{\small}l!{\extracolsep{\fill}}} \multicolumn{1}{>{\bfseries}l}{Method/Description}&\multicolumn{1}{>{\bfseries}l}{Command}\\\hline \endfirsthead \multicolumn{1}{>{\bfseries}l}{Method/Description}&\multicolumn{1}{>{\bfseries}l}{Command}\\\hline \endhead \texttt{multimedia\_pause():Number}${}^*$&\cs{mmPause}\\[-\extrarowheight] Pause playback of the current media.\par \medskip Returns on success: Playhead time in seconds \\[6pt] % \texttt{multimedia\_mute():Number}${}^*$&\cs{mmMute}\\[-\extrarowheight] Mute the audio of the media\par\medskip Returns on success: Previous volume setting. \\[6pt] % \texttt{multimedia\_volume(volume:Number):Number}${}^*$&\cs{mmVolume}\\[-\extrarowheight] Set the volume level. The volume is a number between 0 and 1 inclusive. A value of 0 mutes the audio, while a volume of 1 sets the volume level to the maximum level.\par\medskip Returns on success: Previous volume setting.\\[6pt] % \texttt{multimedia\_seekCuePoint(cuePointName:String):String}&\makebox[1in+3pt][l]{\cs{mmSeekCuePoint}\hss}\\[-\extrarowheight] Seeks to the named navigation cue point in an \textsf{FLV} video.\par\medskip Returns on success: Empty string\\ Returns on error: String ERROR: xxxx where xxx is one of the standard numeric error codes defined in ActionScript 3.0. \\[6pt] % \texttt{multimedia\_setSource(url:String):String}&\cs{mmSource}\\[-\extrarowheight] Sets the source for the video (a URL or a local file reference).\par\medskip Returns on success: \texttt{local=} or \texttt{remote=} and the source in string format.\par\medskip If the remote source cannot be played for any reason, the player automatically returns to playing the local source instead. \\[6pt] % \texttt{multimedia\_setSkin(skinName:String):void}&\cs{mmSkin}\\[-\extrarowheight] Sets a new skin file to be used by the player. This should be an embedded resource.\\[6pt] % \texttt{multimedia\_setSkinColor(color:uint):uint}&\cs{mmSkinColor}\\[-\extrarowheight] Sets a new background color for the player skin in the form of \texttt{0xRRGGBB}.\\[6pt] % \texttt{multimedia\_setSkinAlpha(alpha:uint):uint}&\cs{mmSkinAlpha}\\[-\extrarowheight] Sets the background alpha for the player skin (will only take effect where the skin supports alpha changes).\par\medskip Returns on success: Previous alpha value. \\[6pt] % \texttt{multimedia\_useLocal(isLocal:boolean):String}&\cs{mmUseLocal}\\[-\extrarowheight] Switches to the local source if \texttt{isLocal} is set to \texttt{true}, or to the remote source if \texttt{isLocal} is \texttt{false}.\par\medskip Returns on success: source filename/URL in string format.\\ Returns on error: \texttt{"NOT AVAILABLE"}.\\[6pt] % %\newpage % \texttt{multimedia\_getMetdata( attribute:String ):String}&\cs{mmGetMetaData}\\[-\extrarowheight] Returns the video metadata associated with the attribute. Valid attribute strings are \texttt{width}, \texttt{height}, \texttt{audiocodecid}, \texttt{videocodecid}, \texttt{framerate}, \texttt{videodatarate}, and \texttt{duration}.\\[6pt] % %\newpage % \texttt{multimedia\_getVideoState():String}&\cs{mmGetVideoState}\\[-\extrarowheight] Returns the video state. The possible values for the state property are \texttt{buffering}, \texttt{connectionError}, \texttt{disconnected}, \texttt{loading}, \texttt{paused}, \texttt{playing}, \texttt{rewinding}, \texttt{seeking}, and \texttt{stopped}.\\[6pt] % \texttt{multimedia\_setScaleMode(attribute:String):String}&\cs{mmSetScaleMode}\\[-\extrarowheight] Sets video scale mode. Valid attribute strings are \texttt{exactFit}, \texttt{noScale}, and \texttt{maintainAspectRatio}.\par\medskip Returns on success: Previous value.\par\medskip Note that if the scale mode is changed to \texttt{"maintain\-Aspect\-Ratio"}, the align mode will be switched to ``top left'' rather that ``center''.\\[6pt] % \texttt{multimedia\_getVersion():String}&\cs{mmGetVersion}\\[-\extrarowheight] Returns a string in the form \texttt{"NNNN fp=FFFF vp=VVVV"}, where \texttt{NNNN} is the name of the Rich Media Annotation, \texttt{FFFF} is the version of Flash Player being used, and \texttt{VVVV} is the version of the \textsf{VideoPlayerX} code (currently 10.2). The length of each element is variable.\\[12pt] % \multicolumn{2}{@{}l}{\large\textbf{New API for version 10.2}}\\[6pt] %The \textsf{VideoPlayerX} now accepts all the extended ActionScript calls %defined by Joel Geraci's \textsf{VideoPlayerPlus} %widget.\\[6pt] The two functions \texttt{\href{http://www.uvsar.com/projects/acrobat/videoplayerx/listener.php}{vpx\_listener()}} and \texttt{\href{http://www.uvsar.com/projects/acrobat/videoplayerx/init.php}{vpx\_init()}} are listening and initialization functions. Follow these two links for information on these functions.\\[6pt] % \newpage % \texttt{multimedia\_setStageColor(color:uint):void}&\cs{mmSetStageColor}\\[-\extrarowheight] Sets the background color for the Stage (the area around the video when it isn't scaled to fit the annotation). For example, \begin{Verbatim} var rm=this.getAnnotRichMedia(this.pageNum,"myRMA"); rm.callAS(\mmSetStageColor,0xFF00FF); \end{Verbatim} \\[6pt] % \texttt{multimedia\_isLooping():Boolean}&\cs{mmIsLooping}\\[-\extrarowheight] Sets if the video should loop automatically when it reaches the end of the timeline. The default is \texttt{true}. \par\medskip Returns on success: Previous value of the setting.\\[6pt] % \texttt{multimedia\_skinAutoHide(state:Boolean):void}&\cs{mmSkinAutoHide}\\[-\extrarowheight] Sets the auto hide behavior for the player bar.\\[12pt] % %\newpage % \multicolumn{2}{@{}l}{\large\textbf{New API for version 10.4}}\\[6pt] \texttt{multimedia\_showLoopButton():Boolean}&\cs{mmShowLoopButton}\\[-\extrarowheight] Determines whether the video loop control button should appear on mouseover. A value of \texttt{true} shows the button, a value of false \texttt{hides} the button. This function is \emph{ineffective} when placed in the \texttt{vpx\_init()} function. \par\medskip Returns on success: Previous value of the setting. \end{longtable} \endgroup \noindent There are considerably more functions that are not listed here. For a full list, go to the page \href{http://www.uvsar.com/projects/acrobat/videoplayerx/} {VideoPlayerX: Enhanced Video Tool for Adobe Acrobat} on the \textbf{UVSAR} website. The documentation is also in the \texttt{videoplayerx} folder. \paragraph*{Examples of usage} %\vspace{-\bigskipamount} \begin{Verbatim} var rma = this.getAnnotRichMedia(this.pageNum, "myCoolRMA"); if(!rma.activated) rma.activated=true; // use embedded video as source rma.callAS(\mmSource, "myVideo.flv"); // use video on web as source // rma.callAS(\mmSource, "http://www.example.com/myCool.flv"); rm.callAS(\mmShowLoopButton, false); // no loop button rma.callAS(\mmPlay); // and play it \end{Verbatim} \begin{comment} \subsubsection{Methods shared by all Video Players} The three players (\textbf{VideoPlayer}, \textbf{VideoPlayerPlus}, and \textbf{VideoPlayerX}) all share the core API. Beyond the core API, extended API supported by \textbf{VideoPlayerPlus} and \textbf{VideoPlayerX} are different, but they do have some overlap. Though there is overlap, the common methods may have different names, this is one of the main reasons for the convenience commands. The command, \cs{mmSource}, for example, expands to the string \texttt{"multimedia\_source"} for \textbf{VideoPlayerPlus}, but for \textbf{VideoPlayerX} expands to the string \texttt{"multimedia\_setSource"}. \paragraph*{Extended API Overlap:} \cs{mmSource}, \cs{mmSkin}, and \cs{mmSkinColor}. \newtopic For either player (\textbf{VideoPlayerPlus} or \textbf{VideoPlayerX}), you can dynamically load in a new source file (either local or remote), designate the skin and skin color. \paragraph*{\textcolor{red}{Examples.}} Again, over time, I plan posting several example files to illustrate \textbf{VideoPlayerPlus} or \textbf{VideoPlayerX} and their capabilities. Keep your browser set to the \href{http://www.math.uakron.edu/~dpstory/aebblog.html}{AeB Blog}. \end{comment} \subsection{\texorpdfstring{\protect\cs{rmAnnot}}{\CMD{rmAnnot}} and 3D}\label{RM3D} Here is something that I've only just come to realize: If you use the user interface (UI) of \textsf{Acrobat} and you create a 3D annotation in \textsf{Acrobat}, then give it a \textsf{SWF} as a resource, the 3D annot gets converted into a Rich Media annotation (RMA). Looking through the specification as described in the \emph{Adobe Supplement to ISO 32000}, I determined to implement this feature, and why not since most of the structure (that of an RMA) was already in place by way of my \textsf{rmannot} package. So, this version of \textsf{rmannot} supports what I'll call \emph{Rich Media 3D annotation} (RM3DA). Initially, it was not a challenge to get a 3D model to appear in a RMA created by \textsf{rmannot}, some straight forward modifications to \textsf{rmannot} were required with \emph{ISO 32000} as a guide. Looking at Alexander Grahn's very fine and brilliant \textsf{movie15} package, I saw the difficulties of defining and creating \emph{view}s through the {\LaTeX} interface. With Alexander's permission, I gently lifted all the really heavy code from \textsf{movie15}, and placed it in \textsf{rmannot}. I offer up my great and humble thanks for his kindness in allowing the use of his code (characterized by commands beginning with \texttt{@MXV} in \textsf{rmannot.dtx}). If you want to insert an RMA3D annotation into your document, begin by calling the \textsf{rmannot} package with the \texttt{use3D} option \begin{Verbatim}[xleftmargin=\leftmargini] \usepackage[use3D]{rmannot} \end{Verbatim} Using this option brings in a large amount of code to support 3D. Regular RMAs can be created as usual, if you do not use 3D there is no reason to use this option. The 3D Models support by Acrobat/Adobe Reader are U3D and PRC. To construct a RM3D, you use one of these filetypes as the fourth argument of \cs{rmannot}, for example, \begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small,commandchars=!()] \rmAnnot[!meta(rmannot_opts)]{!meta(width)}{!meta(height)}{!meta(3dmodel)} \end{Verbatim} \cs{rmAnnot} files and resources are referred to symbolically, and need to be declared in the preamble. For example, we might declare \begin{Verbatim}[xleftmargin=\leftmargini] \saveNamedPath{myDice}{c:/.../3dmodels/dice.u3d} \end{Verbatim} \cs{rmAnnot} parses the fourth argument, and looks at its extension. If the extension os \texttt{.u3d} or \texttt{.prc}, the appropriate 3D structure is generated for this annotation. The first optional argument of \cs{rmAnnot} has two new key-value pairs, both Boolean: \texttt{toolbar} and \texttt{modeltree}. \begin{itemize} \item\texttt{toolbar}: A Boolean, which if true (the default), causes the 3D toolbar to appear when the annot is activated. If \texttt{toolbar=false}, the toolbar does not appear when the annotation is activated. \item\texttt{modeltree}: A Boolean, which if true causes the \textbf{Model Tree} as viewed in the \textbf{Navigation Pane}. The default is false, the \textbf{Model Tree} is not displayed when the annotation is activated. \end{itemize} There are a large number of key-values that support RMA3D annotations, rather than inserting them into the first optional parameter of \cs{rmAnnot}, I've created a separate command, \cs{setRmOptions3D} for this purpose. The command may appear appear anywhere before the RMA3D annot it is referencing. The syntax is \begin{Verbatim}[numbers=left,xleftmargin=\leftmargini,commandchars=!(),fontsize=\fontsize{9}{11}\selectfont] \setRmOptions3D{!meta(annot_name)} { 3DOptions={options from movie15}, 3DResources={% none={rName=!meta(name1)},..., foreground={rName=!meta(name2),flashvars=!meta(vars)},..., background={rName=!meta(name3),flashvars=!meta(vars)},..., material={rName=!meta(name4),mName=!meta(materialName),flashvars=!meta(vars)},... } } \end{Verbatim} The command takes two arguments, the first \meta{annot\_name} is the name of the annot, as declare by the name key in the first optional argument of \cs{rmAnnot}, like so, \begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\fontsize{9}{11}\selectfont] \rmAnnot[name=my3DDice,...]{4in}{3in}{myDice} \end{Verbatim} In the above example, we've named this annot \texttt{my3DDice}, and it is this name we would put in as the first argument of \cs{setRmOptions3D} in line~(1) above. The second argument of \cs{setRmOptions3D} takes key-value pairs, but there are only two keys: \texttt{3DOptions} and \texttt{3DResources}. Each of these will be explained in turn. \paragraph*{\texttt{3DOptions}} As noted in line~(3), the value of this key are key-value pairs defined in \textsf{movie15}, appropriate to 3D models. The keys supported are \texttt{3Dbg}, \texttt{3Djscript}, \texttt{3Dcoo}, \texttt{3Dc2c}, \texttt{3Droo}, \texttt{3Daac}, \texttt{3Droll}, \texttt{3Dviews}, \texttt{3Dlights}, and \texttt{3Drender}. See the \mlhref{http://mirror.ctan.org/macros/latex/contrib/movie15/doc/movie15.pdf} {\textsf{movie15} documentation} for a description of these keys. There are a couple of differences. First \texttt{3Dviews} is the \texttt{3Dviews2} of \textsf{movie15}. Alexander Grahn had deprecated his original \texttt{3Dviews} key, and later came up with a better format for storing the views. Since we are beginning anew, \texttt{3Dviews} uses the new format as described in the \mlhref{http://mirror.ctan.org/macros/latex/contrib/movie15/doc/movie15.pdf} {\textsf{movie15} documentation} as \texttt{3Dviews2}. Another difference is with the \texttt{3Djscript} key. The file descriptor must be a symbolic name, defined by \cs{saveNamedPath} command. The value of \texttt{3Djscript} can be a comma delimited list of JavaScript files, for example, \begin{Verbatim}[xleftmargin=\leftmargini] 3DOptions={% ..., 3Djscript={myScript,myTurntable}, ..., ... } \end{Verbatim} Again \texttt{myScript} and \texttt{myTurntable} are defined by the \cs{saveNamedPath} command. In theory, one can build a library of general and specific JavaScripts to do 3D work, and you can concatenate them together in this way. The \texttt{3Dviews} key takes as its argument a views file. This is purely a {\LaTeX} object (not used required by Distiller), to the usual filename is needed, for example, \begin{Verbatim}[xleftmargin=\leftmargini] 3DOptions={% ..., 3Djscript={myScript,myTurntable}, 3Dviews=dice.vws, ... } \end{Verbatim} \paragraph*{\texttt{3DResources}} This is a key that is new, and separate from the \textsf{movie15} keys just outlined. \texttt{3DResources} recognizes four keys, these are \texttt{none}, \texttt{foreground}, \texttt{background}, and \texttt{material}. The names and values found within \texttt{3DResources} are modeled after the \textbf{Resources} tab of the \textbf{Edit 3D} dialog box of Acrobat 9 or later. \begin{Verbatim}[numbers=left,xleftmargin=\leftmargini,commandchars=!(),fontsize=\fontsize{9}{11}\selectfont] \setRmOptions3D{!meta(annot_name)} { 3DOptions={options from movie15}, 3DResources={% none={rName=!meta(name1)},..., foreground={rName=!meta(name2),flashvars=!meta(vars)},..., background={rName=!meta(name3),flashvars=!meta(vars)},..., material={rName=!meta(name4),mName=!meta(materialName),flashvars=!meta(vars)},... } } \end{Verbatim} A resource is usually a \textsf{SWF} file, but can be a \textsf{FLV}, or another 3D model (\texttt{.u3d}, \texttt{.prc}); \textsf{rmannot} does not support image files are resources (\textsf{JPG}, \textsf{PNG}, etc). \paragraph*{\textcolor{red}{Note:}} Convert all image files (\textsf{JPG}, \textsf{PNG}, etc) to a \textsf{SWF} for used by \textsf{rmannot}. The conversion can be made by \textsf{Adobe Flash Professional}, or by using \textbf{\href{http://www.swftools.org/}{SWF Tools}} (use the \textsf{jpeg2swf} and \textsf{png2swf} tools). \newtopic\texttt{SWF} files may be bound to the background, foreground, a material of the 3D model, or not bound at all. \textsf{FLV} and 3D models must be not bound, and listed under the \texttt{none} key. The keys \texttt{none}, \texttt{foreground}, \texttt{background}, and \texttt{material} may appear multiple times. A brief description of the values of each key follows:\bgroup\tightsettings \begin{itemize} \item \texttt{none}: The value of none is a single key-value combination. \texttt{rName=\meta{name}}, where \meta{name} is the symbolic name of a resource file declared by the \cs{saveNamedPath}. These files can be \textsf{SWF}, \textsf{FLV}, or even another model (advanced). \item \texttt{foreground}: This key binds a resource to the foreground of the 3D scene. The \texttt{foreground} key takes at most two key-value pairs, only \texttt{rName} is required, the symbolic name of the resource. The \texttt{flashvars} key is used to pass flash variables to the \textsf{SWF} application. \item\texttt{background}: This key binds a resource to the background canvas of the 3D scene. The \texttt{background} key takes at most two key-value pairs, only \texttt{rName} is required, the symbolic name of the resource. The \texttt{flashvars} key is used to pass flash variables to the \textsf{SWF} application. \item\texttt{material}: This key binds a resource to a material. The resource name is \texttt{rName} (as defined by \cs{saveNamedPath}), the key \texttt{mName} is the name of the material the resource is to be bound to; \texttt{flashvars} is used to pass variables to the \textsf{SWF} application. \end{itemize}\par\egroup If a \textsf{SWF} resource is to be used as background, foreground, or a material using 3D JavaScript (through the JS file input by the \texttt{3Djscript} key), it must be listed through the none key. %\previewtrue \paragraph*{Example.}\label{RM3Dexample} We finish off this section with a simple example,\medskip \setRmOptions3D{my3DDice}{% 3DOptions={% 3Droo=40, 3Dlights=CAD, 3Drender=Solid, 3Dbg=1 0 0, 3Dviews=../examples/rm3da/views/dice.vws, },% 3DResources={% background={rName=AcroAd} }% } \noindent\rmAnnot[name=my3DDice,toolbar]{\linewidth}{2.5in}{myDice}\smallskip \noindent Notice the nice advertisement playing in the background of the 3D scene. \verb!:-{)! \newtopic\noindent The verbatim listing is \begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\fontsize{9}{11}\selectfont] \setRmOptions3D{my3DDice}{% 3DOptions={% 3Droo=40, 3Dlights=CAD, 3Drender=Solid, 3Dbg=1 0 0, 3Dviews=views/dice.vws, },% 3DResources={% background={rName=AcroAd} }% } \noindent\rmAnnot[name=my3DDice,toolbar]{\linewidth}{2.5in}{myDice} \end{Verbatim} Further examples will appear, in time, on my \href{\urlAcroTeXBlog//?tag=rmannot-package}{{\AcroTeX} Blog}. \bigskip\noindent That's all for now, I simply must get back to my retirement. \dps \end{document} \begin{Verbatim}[numbers=left,xleftmargin=\leftmargini,fontsize=\fontsize{9}{11}\selectfont] d