media9 (27jun14)

git-svn-id: svn://tug.org/texlive/trunk@34456 c570f23f-e606-0410-a88d-b1316a301751

7 files changed, 221 insertions, 84 deletions

diff --git a/Master/texmf-dist/doc/latex/media9/ChangeLog b/Master/texmf-dist/doc/latex/media9/ChangeLog
index 824633d925d..814c551f827 100644
--- a/Master/texmf-dist/doc/latex/media9/ChangeLog
+++ b/Master/texmf-dist/doc/latex/media9/ChangeLog
@@ -1,3 +1,12 @@
+2014-06-25
+	* v0.45
+	* fix: transparency in media button faces drawn with TikZ/PGF didn't work when
+	using the dvipdfmx/xetex driver
+	* new: [AV]Player ActionScript methods `play' and `pause' take optional time
+	offsets, allowing for playing portions of the media file
+	* Change: `depth' option deprecated and ignored if used, added `totalheight'
+	and `keepaspectratio' options
+
 2014-06-04
 	* v0.44
 	* fix: prevent the play button from being printed to paper or exported to
diff --git a/Master/texmf-dist/doc/latex/media9/files/players/APlayer.mxml b/Master/texmf-dist/doc/latex/media9/files/players/APlayer.mxml
index 78503bc4695..30ae5de9229 100644
--- a/Master/texmf-dist/doc/latex/media9/files/players/APlayer.mxml
+++ b/Master/texmf-dist/doc/latex/media9/files/players/APlayer.mxml
@@ -4,7 +4,7 @@
 <!-- a FlashPlayer-10 compatible component for playing             -->
 <!-- MP3 audio files and streams.                                  -->
 <!--                                                               -->
-<!-- version 20140211                                              -->
+<!-- version 20140625                                              -->
 <!--                                                               -->
 <!--                                                               -->
 <!-- The free Apache Flex 4 SDK is required to compile             -->
@@ -64,7 +64,9 @@
       private var id3:ID3Info;
       private var sndCh:SoundChannel;
       private var sndTr:SoundTransform;
-      private var playResumePosition:Number = 0;
+      private var playResumePos:Number = 0;
+      private var pauseAtPos:Number = -1;
+      private var toBePaused:Boolean = false;
       private var plyng:Boolean = false;
       private var muted:Boolean = false;
       private var lastVol:Number;
@@ -117,12 +119,12 @@
             break;
           case 36: //home
             pause();
-            playResumePosition=(0);
+            playResumePos=(0);
             break;
           case 35: //end
             if(playProgress.indeterminate) break;
             pause();
-            playResumePosition=(snd.length);
+            playResumePos=(snd.length);
             break;
           case 37: //<--
             fadeEffect.end();
@@ -137,11 +139,11 @@
             if(plyng)
               curTime=sndCh.position;
             else
-              curTime=playResumePosition;
+              curTime=playResumePos;
             }
             keyPressed=true;
-            playResumePosition=Math.max(0,curTime-deltaSeek);
-            if(plyng) seek(playResumePosition/1000);
+            playResumePos=Math.max(0,curTime-deltaSeek);
+            if(plyng) seek(playResumePos/1000);
             deltaSeek*=1.1;
             break;
           case 39: //-->
@@ -157,11 +159,11 @@
             if(plyng)
               curTime=sndCh.position;
             else
-              curTime=playResumePosition;
+              curTime=playResumePos;
             }
             keyPressed=true;
-            playResumePosition=Math.min(snd.length-10,curTime+deltaSeek);
-            seek(playResumePosition/1000);
+            playResumePos=Math.min(snd.length-10,curTime+deltaSeek);
+            seek(playResumePos/1000);
             deltaSeek*=1.1;
             break;
           case 38:
@@ -233,17 +235,19 @@
 
       private function loadPolicy(p:String):void {policy=p;}
 
-      private function play():void {
+      private function play(p:Number=-1):void {
+        if(p>=0) seek(p);
         if(plyng) return;
-        try{sndCh = snd.play(playResumePosition, 0, sndTr);}
+        try{sndCh = snd.play(playResumePos, 0, sndTr);}
         catch(e:Error){Alert.show(e.message,'Error');}
         sndCh.addEventListener(Event.SOUND_COMPLETE, onSoundComplete);
         plyng = true;
       }
 
-      private function pause():void {
+      private function pause(p:Number=-1):void {
+        if(p>=0){pauseAtPos=p*1000;return;}
         if(!plyng) return;
-        playResumePosition = sndCh.position;
+        playResumePos = sndCh.position;
         sndCh.stop();
         plyng = false;
       }
@@ -253,7 +257,7 @@
       }
 
       private function seek(p:Number):void {
-        playResumePosition = p*1000;
+        playResumePos = p*1000;
         if(!plyng) return;
         sndCh.stop();
         plyng = false;
@@ -288,7 +292,7 @@
       }
 
       private function currentTime():Number {
-      return sndCh.position/1000;
+        return sndCh.position/1000;
       }
 
       private function playing():Boolean {
@@ -322,7 +326,7 @@
 
       private function onSoundComplete(e:Event):void {
         plyng = false;
-        playResumePosition = 0;
+        playResumePos = 0;
         if(loop) play();
       }
 
@@ -340,8 +344,8 @@
             playProgress.setProgress(sndCh.position,snd.length);
             caption.text=formatLabel(sndCh.position);
           } else {
-            playProgress.setProgress(playResumePosition,snd.length);
-            caption.text=formatLabel(playResumePosition);
+            playProgress.setProgress(playResumePos,snd.length);
+            caption.text=formatLabel(playResumePos);
           }
         }else{
           if(plyng) {
@@ -349,9 +353,19 @@
             caption.text=formatLabel(sndCh.position);
           } else {
             playProgress.setProgress(snd.bytesLoaded,snd.bytesTotal);
-            caption.text=formatLabel(playResumePosition);
+            caption.text=formatLabel(playResumePos);
           }
         }
+        if(plyng&&pauseAtPos>=0&&sndCh.position<pauseAtPos)
+          toBePaused=true;
+        if(
+          plyng&&pauseAtPos>=0&&
+          sndCh.position>=pauseAtPos&&toBePaused
+        ){
+          pause();
+          pauseAtPos=-1;
+          toBePaused=false;
+        }
       }
 
       private function onID3Info(e:Event):void {id3 = e.target.id3;}
diff --git a/Master/texmf-dist/doc/latex/media9/files/players/APlayer9.mxml b/Master/texmf-dist/doc/latex/media9/files/players/APlayer9.mxml
index 35a154ae3fc..1a80f98c921 100644
--- a/Master/texmf-dist/doc/latex/media9/files/players/APlayer9.mxml
+++ b/Master/texmf-dist/doc/latex/media9/files/players/APlayer9.mxml
@@ -4,7 +4,7 @@
 <!-- a FlashPlayer-9 compatible component for playing              -->
 <!-- MP3 audio files and streams.                                  -->
 <!--                                                               -->
-<!-- version 20131114                                              -->
+<!-- version 20140625                                              -->
 <!--                                                               -->
 <!-- Copyright (C) 2012-today  Alexander Grahn                     -->
 <!--                                                               -->
@@ -50,13 +50,15 @@
       private var id3:ID3Info;
       private var sndCh:SoundChannel;
       private var sndTr:SoundTransform;
-      private var playResumePosition:Number = 0;
-      private var playing:Boolean = false;
+      private var playResumePos:Number = 0;
+      private var pauseAtPos:Number = -1;
+      private var toBePaused:Boolean = false;
+      private var plyng:Boolean = false;
       private var muted:Boolean = false;
       private var lastVol:Number;
 
       private var deltaSeek:Number;
-      private var currentTime:Number;
+      private var curTime:Number;
       private var keyPressed:Boolean=false;
       private var mouseIsOver:Boolean=false;
 
@@ -104,12 +106,12 @@
             break;
           case 36: //home
             pause();
-            playResumePosition=(0);
+            playResumePos=(0);
             break;
           case 35: //end
             if(playProgress.indeterminate) break;
             pause();
-            playResumePosition=(snd.length);
+            playResumePos=(snd.length);
             break;
           case 37: //<--
             fadeEffect.end();
@@ -122,14 +124,14 @@
             }
             if(!keyPressed){
               deltaSeek=Math.max(100,snd.length/10000);
-            if(playing)
-              currentTime=sndCh.position;
+            if(plyng)
+              curTime=sndCh.position;
             else
-              currentTime=playResumePosition;
+              curTime=playResumePos;
             }
             keyPressed=true;
-            playResumePosition=Math.max(0,currentTime-deltaSeek);
-            if(playing) seek(playResumePosition/1000);
+            playResumePos=Math.max(0,curTime-deltaSeek);
+            if(plyng) seek(playResumePos/1000);
             deltaSeek*=1.1;
             break;
           case 39: //-->
@@ -143,14 +145,14 @@
             }
             if(!keyPressed){
               deltaSeek=Math.max(100,snd.length/10000);
-            if(playing)
-              currentTime=sndCh.position;
+            if(plyng)
+              curTime=sndCh.position;
             else
-              currentTime=playResumePosition;
+              curTime=playResumePos;
             }
             keyPressed=true;
-            playResumePosition=Math.min(snd.length-10,currentTime+deltaSeek);
-          seek(playResumePosition/1000);
+            playResumePos=Math.min(snd.length-10,curTime+deltaSeek);
+            seek(playResumePos/1000);
             deltaSeek*=1.1;
             break;
           case 38:
@@ -222,30 +224,32 @@
 
       private function loadPolicy(p:String):void {policy=p;}
 
-      private function play():void {
-        if(playing) return;
-        try{sndCh = snd.play(playResumePosition, 0, sndTr);}
+      private function play(p:Number=-1):void {
+        if(p>=0) seek(p);
+        if(plyng) return;
+        try{sndCh = snd.play(playResumePos, 0, sndTr);}
         catch(e:Error){Alert.show(e.message,'Error');}
         sndCh.addEventListener(Event.SOUND_COMPLETE, onSoundComplete);
-        playing = true;
+        plyng = true;
       }
 
-      private function pause():void {
-        if(!playing) return;
-        playResumePosition = sndCh.position;
+      private function pause(p:Number=-1):void {
+        if(p>=0){pauseAtPos=p*1000;return;}
+        if(!plyng) return;
+        playResumePos = sndCh.position;
         sndCh.stop();
-        playing = false;
+        plyng = false;
       }
 
       private function playPause():void {
-        if(playing) pause(); else play();
+        if(plyng) pause(); else play();
       }
 
       private function seek(p:Number):void {
-        playResumePosition = p*1000;
-        if(!playing) return;
+        playResumePos = p*1000;
+        if(!plyng) return;
         sndCh.stop();
-        playing = false;
+        plyng = false;
         play();
       }
 
@@ -276,6 +280,22 @@
         sndCh.soundTransform=sndTr;
       }
 
+      private function currentTime():Number {
+        return sndCh.position/1000;
+      }
+
+      private function playing():Boolean {
+        return plyng;
+      }
+
+      private function duration():Number {
+        return snd.length/1000;
+      }
+
+      private function ismuted():Boolean {
+        return muted;
+      }
+
       private function initCallBacks():void {
         ExternalInterface.addCallback("play", play);
         ExternalInterface.addCallback("pause", pause);
@@ -287,11 +307,15 @@
         ExternalInterface.addCallback("mute", mute);
         ExternalInterface.addCallback("setSource", setSource);
         ExternalInterface.addCallback("loadPolicy", loadPolicy);
+        ExternalInterface.addCallback("currentTime", currentTime);
+        ExternalInterface.addCallback("duration", duration);
+        ExternalInterface.addCallback("playing", playing);
+        ExternalInterface.addCallback("muted", ismuted);
       }
 
       private function onSoundComplete(e:Event):void {
-        playing = false;
-        playResumePosition = 0;
+        plyng = false;
+        playResumePos = 0;
         if(loop) play();
       }
 
@@ -305,22 +329,32 @@
 
       private function onEnterFrame(e:Event):void {
         if(!playProgress.indeterminate) {
-          if(playing) {
+          if(plyng) {
             playProgress.setProgress(sndCh.position,snd.length);
             caption.text=formatLabel(sndCh.position);
           } else {
-            playProgress.setProgress(playResumePosition,snd.length);
-            caption.text=formatLabel(playResumePosition);
+            playProgress.setProgress(playResumePos,snd.length);
+            caption.text=formatLabel(playResumePos);
           }
         }else{
-          if(playing) {
+          if(plyng) {
             playProgress.setProgress(Math.random(),1);
             caption.text=formatLabel(sndCh.position);
           } else {
             playProgress.setProgress(snd.bytesLoaded,snd.bytesTotal);
-            caption.text=formatLabel(playResumePosition);
+            caption.text=formatLabel(playResumePos);
           }
         }
+        if(plyng&&pauseAtPos>=0&&sndCh.position<pauseAtPos)
+          toBePaused=true;
+        if(
+          plyng&&pauseAtPos>=0&&
+          sndCh.position>=pauseAtPos&&toBePaused
+        ){
+          pause();
+          pauseAtPos=-1;
+          toBePaused=false;
+        }
       }
 
       private function onID3Info(e:Event):void {id3 = e.target.id3;}
diff --git a/Master/texmf-dist/doc/latex/media9/files/players/VPlayer.mxml b/Master/texmf-dist/doc/latex/media9/files/players/VPlayer.mxml
index a5f05bbb425..7d73ce43b7d 100644
--- a/Master/texmf-dist/doc/latex/media9/files/players/VPlayer.mxml
+++ b/Master/texmf-dist/doc/latex/media9/files/players/VPlayer.mxml
@@ -4,7 +4,7 @@
 <!-- a FlashPlayer-10 compatible component for playing             -->
 <!-- FLV and MP4/H.264 video files and streams.                    -->
 <!--                                                               -->
-<!-- version 20140306                                              -->
+<!-- version 20140625                                              -->
 <!--                                                               -->
 <!--                                                               -->
 <!-- The free Apache Flex 4 SDK is required to compile             -->
@@ -57,6 +57,8 @@
       private var curTime:Number;
       private var newPos:Number;
       private var keyPressed:Boolean=false;
+      private var pauseAtPos:Number = -1;
+      private var toBePaused:Boolean = false;
 
       import mx.core.FlexGlobals;
       private function initialise(flashVars:Object):void {
@@ -155,11 +157,26 @@
         if(stepping&&vidDisp.playing){vidDisp.pause();}
       }
 
-      private function play():void {
-        if(vidComplete){vidDisp.seek(0);}vidDisp.play();
+      private function onCurrentTimeChange(e:Event):void {
+        if(vidDisp.playing&&pauseAtPos>=0&&vidDisp.currentTime<pauseAtPos)
+          toBePaused=true;
+        if(
+          vidDisp.playing&&pauseAtPos>=0&&
+          vidDisp.currentTime>=pauseAtPos&&toBePaused
+        ){
+          pause();
+          pauseAtPos=-1;
+          toBePaused=false;
+        }
+      }
+
+      private function play(p:Number=-1):void {
+        if(p>=0) seek(p);
+        if(vidComplete){seek(0);}vidDisp.play();
       }
 
-      private function pause():void {
+      private function pause(p:Number=-1):void {
+        if(p>=0){pauseAtPos=p;return;}
         vidDisp.pause();
       }
 
@@ -262,12 +279,13 @@
       id="vidDisp"
       width="100%" height="100%" scaleMode="{scaleMode}"
       source="{source}" volume="{vol}"
-	  autoPlay="{autoPlay}" autoRewind="{autoRewind}" loop="{loop}"
+      autoPlay="{autoPlay}" autoRewind="{autoRewind}" loop="{loop}"
       mouseDown="if(stepping){vidDisp.play();}else{vidDisp.pause();}this.setFocus();"
       mouseUp="if(vidComplete) vidDisp.seek(0);if(!stepping){vidDisp.play();}"
       mediaPlayerStateChange="onStateChange(event);"
       complete="vidComplete=true;"
       durationChange="vidDisp.seek(0);"
+      currentTimeChange="onCurrentTimeChange(event);"
   />
 
   <mx:ProgressBar width="100%" mode="polled" source="vidDisp"
diff --git a/Master/texmf-dist/doc/latex/media9/files/players/VPlayer9.mxml b/Master/texmf-dist/doc/latex/media9/files/players/VPlayer9.mxml
index 6a405c30145..02c684ffe32 100644
--- a/Master/texmf-dist/doc/latex/media9/files/players/VPlayer9.mxml
+++ b/Master/texmf-dist/doc/latex/media9/files/players/VPlayer9.mxml
@@ -4,7 +4,7 @@
 <!-- a FlashPlayer-9 compatible component for playing              -->
 <!-- FLV and MP4/H.264 video files and streams.                    -->
 <!--                                                               -->
-<!-- version 20131114                                              -->
+<!-- version 20140625                                              -->
 <!--                                                               -->
 <!-- Copyright (C) 2012-today  Alexander Grahn                     -->
 <!--                                                               -->
@@ -46,6 +46,8 @@
       private var keyPressed:Boolean=false;
       private var muted:Boolean=false;
       private var lastVolume:Number;
+      private var pauseAtPos:Number = -1;
+      private var toBePaused:Boolean = false;
 
       import flash.external.*;
       private function initialise(flashVars:Object):void {
@@ -143,11 +145,26 @@
         if(stepping&&vidDisp.playing){vidDisp.pause();}
       }
 
-      private function play():void {
-        if(vidComplete){vidDisp.playheadTime=0;}vidDisp.play();
+      private function onPlayheadUpdate(e:Event):void {
+        if(vidDisp.playing&&pauseAtPos>=0&&vidDisp.playheadTime<pauseAtPos)
+          toBePaused=true;
+        if(
+          vidDisp.playing&&pauseAtPos>=0&&
+          vidDisp.playheadTime>=pauseAtPos&&toBePaused
+        ){
+          pause();
+          pauseAtPos=-1;
+          toBePaused=false;
+        }
+      }
+
+      private function play(p:Number=-1):void {
+        if(p>=0) seek(p);
+        if(vidComplete){seek(0);}vidDisp.play();
       }
 
-      private function pause():void {
+      private function pause(p:Number=-1):void {
+        if(p>=0){pauseAtPos=p;return;}
         vidDisp.pause();
       }
 
@@ -206,6 +223,22 @@
         return fmtd;
       }
 
+      private function currentTime():Number {
+        return vidDisp.playheadTime;
+      }
+
+      private function playing():Boolean {
+        return vidDisp.playing;
+      }
+
+      private function duration():Number {
+        return vidDisp.totalTime;
+      }
+
+      private function ismuted():Boolean {
+        return muted;
+      }
+
       private function init():void {
         this.setFocus();
         this.addEventListener(KeyboardEvent.KEY_DOWN, onKeyDown);
@@ -220,6 +253,10 @@
         ExternalInterface.addCallback("mute", mute);
         ExternalInterface.addCallback("setSource", setSource);
         ExternalInterface.addCallback("stepping", step);
+        ExternalInterface.addCallback("currentTime", currentTime);
+        ExternalInterface.addCallback("duration", duration);
+        ExternalInterface.addCallback("playing", playing);
+        ExternalInterface.addCallback("muted", ismuted);
       }
     ]]>
   </mx:Script>
@@ -239,6 +276,7 @@
       stateChange="onStateChange(event);"
       complete="vidComplete=true;"
       rewind="vidDisp.play();"
+      playheadUpdate="onPlayheadUpdate(event);"
   />
 
   <mx:ProgressBar width="100%" mode="polled" source="vidDisp"
diff --git a/Master/texmf-dist/doc/latex/media9/media9.pdf b/Master/texmf-dist/doc/latex/media9/media9.pdf
index 04ad52c1b8c..5d57ba4c45d 100644
--- a/Master/texmf-dist/doc/latex/media9/media9.pdf
+++ b/Master/texmf-dist/doc/latex/media9/media9.pdf
diff --git a/Master/texmf-dist/doc/latex/media9/media9.tex b/Master/texmf-dist/doc/latex/media9/media9.tex
index c000a69ba82..5470962d4e8 100644
--- a/Master/texmf-dist/doc/latex/media9/media9.tex
+++ b/Master/texmf-dist/doc/latex/media9/media9.tex
@@ -189,7 +189,7 @@ The last argument, \verb+<main Flash (SWF) file or URL | 3D (PRC, U3D) file>+, i
 
 Argument \verb+<poster text>+ defines the size of the rectangular region of the document page in which the media will be displayed. Moreover, \verb+<poster text>+ will be shown in case the media has not been activated.
 %(Internally, \verb+<poster text>+ 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+<poster text>+ 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+<poster text>+ 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+<poster text>+, \verb+<poster text>+ 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+<poster text>+ is scaled such that the original aspect ratio is preserved.
+\verb+<poster text>+ 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+<poster text>+ can be left blank in which case the size of the media rectangle should be set with options `\verb+width+' and `\verb+height+'. If a non-zero size \verb+<poster text>+ was provided, it can be resized using any combination of options `\verb+width+', `\verb+height+' or `\verb+totalheight+', `\verb+keepaspectratio+' and `\verb+scale+'.
 
 A list of directories where \TeX{} searches for media and resource files can be set-up by means of
 \begin{verbatim}
@@ -203,16 +203,16 @@ The following section explains all command options provided. They are passed to
 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=<width>,
-height=<height>,
-depth=<depth>
-\end{verbatim}
-Resize the media playback area, overriding the original dimensions of the {\tt<poster text>} 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+<poster text>+. 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+<poster text>+.
-\begin{verbatim}
 label=<label text>
 \end{verbatim}
 The media annotation is given a label, \verb+<label text>+, which should be unique. Labelled media annotations can be targeted by the media actions of a control button (see description of the \verb+\mediabutton+ command in Sect. ~\ref{mbtn}). Moreover, a reference to the RichMedia Annotation object (of type `\verb+AnnotRichMedia+') is assigned to the JavaScript variable \verb+annotRM['<label text>']+ in order to facilitate its access in JavaScript. Note that the JavaScript reference is known only after the first opening of the page containing the media.
 \begin{verbatim}
+width=<h-size>,
+height=<v-size> | totalheight=<v-size>,
+keepaspectratio
+\end{verbatim}
+Resize the media playback area. \verb+<poster text>+, if provided, is squeezed or stretched accordingly. If only one of `\verb+width+' or `\verb+[total]height+' is given, the other dimension is scaled to maintain the aspect ratio of \verb+<poster text>+. If both `\verb+width+' and `\verb+[total]height+' are given together with `\verb+keepaspectratio+', \verb+<poster text>+ is resized to fit within \verb+<h-size>+ and \verb+<v-size>+ while maintaining its original aspect ratio. Any valid \TeX{} dimension is acceptable for \verb+<h-size>+ and \verb+<v-size>+. 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+<poster text>+.
+\begin{verbatim}
 scale=<factor>
 \end{verbatim}
 Scales the playback area by \verb+<factor>+.
@@ -499,13 +499,13 @@ A box with \verb+<tip text>+ is shown when the mouse pointer is moved over the b
 Selects a view from the list of predefined views associated with a 3D media inclusion (see option `\verb+3Dviews+'). The target media is specified by \verb+<label text>+, as defined by the `\verb+label+' option of `\verb+\includemedia+'. \verb+<label text>+ alone without a view specification simply activates the 3D object if not yet activated. {\tt<view specification>} which is separated from the label by a colon (\verb+:+) can be one of the following: an integer specifying the zero-based index into the list of views in the 3D views file; one of `\verb+D+', `\verb+F+', `\verb+L+', `\verb+N+', `\verb+P+' indicating the default, first, last, next or previous view in the list of views; a string delimited by `\verb+(+' and `\verb+)+' matching the name of a view as specified by the `\verb+VIEW=...+' entry in the views file. The option can be given several times to simultaneously change the view in more than one 3D inclusion. However, it cannot be used to create an animation effect within the same 3D inclusion, because \verb+3Dgotoview+ actions are executed in parallel.
 %For this, one may implement a 3D JavaScript function that is associated with the media button using the `\verb+mediacommand+' option.
 \begin{verbatim}
-mediacommand=<label text>[:<command> [<arg1> <arg2> ...]]
+mediacommand=<label text>[:<command> [(<arg1>) (<arg2>) ...]]
 \end{verbatim}
-A media command \verb+<command>+, with arguments if required, is sent to a media inclusion identified by \verb+<label text>+, as defined by the `\verb+label+' option of `\verb+\includemedia+'. \verb+<label text>+ alone without a command specification simply activates the media, if not yet activated. The option can be multiply used within the same button to target different media inclusions at the same time or to execute several commands for the same media. Depending on the type of the target media (3D or Flash), \verb+<command>+ is either the name of a JavaScript function defined in a 3D JavaScript file associated with the 3D media (see option `\verb+add3Djscript+') or the name of an ActionScript function that was exposed by the embedded Flash file. ActionScript functions are exposed to the scripting context of the hosting document by using the \verb+ExternalInterface+ call within the Flash file. Arguments to be passed to \verb+<command>+ must be separated by spaces and the whole list be enclosed in `\verb+[+' and `\verb+]+'. Arguments can be of Boolean type (\verb+true+, \verb+false+), numbers (integer, reals) and strings. String arguments must be passed as \verb+(string arg)+, i.\,e. enclosed in parentheses, while numbers and Booleans are passed as they are. Of course, the number of arguments and their types must match the definition of the function to be called. Media players VPlayer.swf and APlayer.swf shipping with media9 expose a number of ActionScript functions that can be used with this option (see Tab. \ref{AVPlayerMethods}). \verb+<command> [<arg1> <arg2> ...]+ must be enclosed in braces if there are embedded equals signs or commas.
+A media command \verb+<command>+, with arguments if required, is sent to a media inclusion identified by \verb+<label text>+, as defined by the `\verb+label+' option of `\verb+\includemedia+'. \verb+<label text>+ alone without a command specification simply activates the media, if not yet activated. The option can be used multiple times within the same button to target different media inclusions at the same time or to execute several commands for the same media. Depending on the type of the target media (3D or Flash), \verb+<command>+ is either the name of a JavaScript function defined in a 3D JavaScript file associated with the 3D media (see option `\verb+add3Djscript+') or the name of an ActionScript function that was exposed by the embedded Flash file. ActionScript functions are exposed to the scripting context of the hosting document by using the \verb+ExternalInterface+ call within the Flash file. Arguments to be passed to \verb+<command>+ must be enclosed in `\verb+(+' and `\verb+)+' and separated by spaces, the whole list be finally enclosed in `\verb+[+' and `\verb+]+', even if there is only a single argument. Arguments can be of Boolean type (\verb+true+, \verb+false+), numbers (integer, reals) and strings. The number of arguments and their types must match the definition of the function to be called. Media players VPlayer.swf and APlayer.swf shipping with `media9' expose a number of ActionScript functions that can be used with this option (see Tab. \ref{AVPlayerMethods}). \verb+<command> [(<arg1>) (<arg2>) ...]+ must be enclosed in braces if there are embedded equals signs or commas. Examples of using `\verb+mediacommand+' are given in Figs.~\ref{videoa} and \ref{radio}c.
 \begin{verbatim}
 jsaction=[<label text>:]{<JavaScript code>}
 \end{verbatim}
-The JavaScript code is executed in the context of the document's instance of the JavaScript engine (there is one instance of the JavaScript engine per open document in Adobe Reader). \verb+<JavaScript code>+ is required and must be enclosed in braces. Unlike media actions defined with options `\verb+mediacommand+' and `\verb+3Dgotoview+', the JavaScript action defined here is not targeted at a particular embedded media and can be used to run arbitrary code. Therefore, \verb+<label text>+ is optional. If provided, it must be separated from \verb+<JavaScript code>+ by a colon. However, it is recommended to provide a label text. It ensures that \verb+annotRM['<label text>']+ is a valid JavaScript reference to the \verb+AnnotRichMedia+ object. \verb+annotRM['<label text>']+ can be used to get access to the global context of the annotation's instance of the 3D JavaScript engine (there is one instance of the 3D JavaScript engine per activated RichMedia Annotation with 3D content). The 3D JavaScript context of a 3D model can be accessed as \verb+annotRM['<label text>'].context3D+. Refer to the Acrobat 3D JavaScript Reference~\cite{jscript3D} for details on built-in JavaScript objects that are available in the 3D context. The \verb+annotRM['<label text>'].callAS()+ method may be used as an alternative to the `\verb+mediacommand+` option in order run exposed ActionScript functions of an embedded Flash file. See~\cite{jscript} for details.
+The JavaScript code is executed in the context of the document's instance of the JavaScript engine (there is one instance of the JavaScript engine per open document in Adobe Reader). \verb+<JavaScript code>+ is required and must be enclosed in braces. Unlike media actions defined with options `\verb+mediacommand+' and `\verb+3Dgotoview+', the JavaScript action defined here is not targeted at a particular embedded media and can be used to run arbitrary code. Therefore, \verb+<label text>+ is optional. If provided, it must be separated from \verb+<JavaScript code>+ by a colon. However, it is recommended to provide a label text. It ensures that \verb+annotRM['<label text>']+ is a valid JavaScript reference to the \verb+AnnotRichMedia+ object. \verb+annotRM['<label text>']+ can be used to get access to the global context of the annotation's instance of the 3D JavaScript engine (there is one instance of the 3D JavaScript engine per activated RichMedia Annotation with 3D content). The 3D JavaScript context of a 3D model can be accessed as \verb+annotRM['<label text>'].context3D+. Refer to the Acrobat 3D JavaScript Reference~\cite{jscript3D} for details on built-in JavaScript objects that are available in the 3D context. The \verb+annotRM['<label text>'].callAS()+ method may be used as an alternative to the `\verb+mediacommand+` option. Both serve as means of running ActionScript functions exposed by embedded Flash files. See~\cite{jscript} for details.
 \begin{verbatim}
 draft
 final
@@ -608,8 +608,8 @@ parameter & description\\\hline\hline
 \caption{Exposed ActionScript functions of media players `VPlayer.swf' and `APlayer.swf', that can be called from within media buttons (see Sect. \ref{mbtn}) or from JavaScript using the `{\tt callAS}' method of the `{\tt AnnotRichMedia}' JavaScript object (see~\cite{jscript} for further information).}\label{AVPlayerMethods}
 \begin{tabular}[t]{lp{0.25\linewidth}p{0.5\linewidth}}\hline
 function & argument &description\\\hline\hline
-{\tt play}       &                        & play media\\
-{\tt pause}      &                        & pause media\\
+{\tt play}       & number (optional)      & play media, optionally starting at \emph{number} seconds offset into the media file\\
+{\tt pause}      & number (optional)      & pause media, optionally at the given offset of \emph{number} seconds into the media file\\
 {\tt playPause}  &                        & toggle between play and pause\\
 {\tt stepping}   &                        & (VPlayer.swf only) toggle stepping mode (one frame per click)\\
 {\tt setSource}  & string                 & load another media file (path to file, embedded using option `{\tt addresource}', or URL)\\
@@ -779,20 +779,44 @@ http://mirrors.ibiblio.org/pub/mirrors/CTAN/macros/latex/contrib/media9/players/
 \vskip 4ex
 \begin{Verbatim}
   \includemedia[
-    flashvars={
-      source=http://www.openbsd.org/songs/song49.mp3
-     &autoPlay=true
-    },
+    label=song49,
+    flashvars={source=http://www.openbsd.org/songs/song49.mp3},
     transparent
-  ]{\color{blue}\fbox{Listen to OpenBSD 4.9 release song}}{APlayer.swf}
+  ]{\color{blue}\fbox{Listen to OpenBSD 4.9 release song}}{APlayer.swf}\\
+  \mediabutton[
+    mediacommand=song49:play[(5.5)],
+    mediacommand=song49:pause[(37)]
+  ]{\fbox{First verse}}
+  \mediabutton[
+    mediacommand=song49:play[(39)],
+    mediacommand=song49:pause[(49)]
+  ]{\fbox{The Answer}}
+  \mediabutton[
+    mediacommand=song49:play[(206.5)],
+    mediacommand=song49:pause[(221)]
+  ]{\fbox{Harmonica solo}}
 \end{Verbatim}
-\makebox[\linewidth]{c)\hfill\includemedia[
+\makebox[\linewidth]{\rule{0pt}{1.5\baselineskip}\hfill\includemedia[
+  label=song49,
   flashvars={
     source=http://www.openbsd.org/songs/song49.mp3
-   &autoPlay=true
   },
   transparent
-]{\color{blue}\fbox{Listen to OpenBSD 4.9 release song}}{APlayer.swf}\hfill}
+]{\color{blue}\fbox{Listen to OpenBSD 4.9 release song}}{APlayer.swf}\hfill}\\
+\makebox[\linewidth]{\makebox[0pt][l]{c)}\hfill%
+  \mediabutton[
+    mediacommand=song49:play[(5.5)],
+    mediacommand=song49:pause[(37)]
+  ]{\fbox{First verse}}
+  \mediabutton[
+    mediacommand=song49:play[(39)],
+    mediacommand=song49:pause[(49)]
+  ]{\fbox{The Answer}}
+  \mediabutton[
+    mediacommand=song49:play[(206.5)],
+    mediacommand=song49:pause[(221)]
+  ]{\fbox{Harmonica solo}}%
+\hfill}
 \caption{Example of (a) embedded sound file, (b) streamed audio and (c) progressively downloaded MP3. ID3 tags `title', `artist' and `album' are displayed if contained in the MP3 stream or file. In (b), the sound player, APlayer.swf, is loaded from a CTAN mirror upon activation.}\label{radio}
 \end{figure}