=====================
                              The movie15 Package
                             =====================

Author:

    Alexander Grahn


Description:

    This package provides an interface to embed movies, sounds and 3D objects
    into PDF documents for use with LaTeX as well as pdfLaTeX. It follows the
    PDF-1.5 and PDF-1.6 specifications for embedding multimedia content. The
    specification allows media file data to be completely incorporated into the
    PDF output, thus producing selfcontained PDF documents. A number of file
    formats is supported. For a (possibly incomplete) list see the table at the
    end of this file or refer to the PDF specification:

        PDF Reference, fifth edition:
        Adobe Portable Document Format version 1.6,
        Implementation note 144, Appendix H.3,

    available somewhere on Adobe's web site (http://www.adobe.com).

    Note, this file only gives a summary of usage and available command
    options. Please refer to the documentation `movie15.pdf' for details.


Usage:

 \usepackage[3D]{movie15}

   Package option `3D' enables the 3D feature from the PDF-1.6 specification.


 \includemovie[<options>]{<width>}{<height>}{<media file>}

   <width> and <height> in TeX dimensions, may be left empty, see option `text'

   <media file> file name of the media clip


 \movieref[<options>]{<label spec>}{<text>}

   makes <text> a hyperlink to the embedded media file which has been labelled
   with <label spec> using the `label' option of the inclusion command.

   Provides a means to control the playback state and properties of the
   referenced media.

   In addition to `play' (default), `stop', `resume', `pause', `reset' and
   `close' it accepts `controls', `repeat', `palindrome', `startat', `endat',
   `mouse', `rate' and `volume' from the subsequent list of command options.


 Options:

   attach[=false]             By default, the embedded data stream is re-used as
                              embedded file attachment, giving the user the
                              oportunity to extract the media file and to save
                              it to disk for later playback with an external
                              player.  Re-use as file attachment can be
                              suppressed with `attach=false'.

   autopause                  Pause playback when page is closed.

   autoplay                   Start playback when page is opened. Useful for
                              side by side movies to be played back
                              simultaneously.

   autostop                   Stop playback when page is closed.
                              Default behaviour, override with option
                              `continue'.

   autoresume                 Resume previously paused playback when page
                              is opened.

   continue                   Continue playback in background on premature page
                              change.

   controls[=true|false]      Display player specific controls.

   depth=<depth>              Specifies how far the media display area should
                              extend below the reference line of the running
                              text. Any valid TeX dimension will be accepted.

   externalviewer             Opens and plays the media in an external
                              application.

   inline[=false]             Movie file data are embedded into the PDF output
                              by default. Embedding can be suppressed using
                              `inline=false'.

   label=<label spec>         The media is labelled with <label spec> such that
                              it can be referenced by the `\movieref' command
                              somewhere else in the document.

   mimetype=<mimetype>        Mime type of media. Must be specified if
                              <media file> has a non-standard filename
                              extension from which the mimetype cannot be
                              guessed. See table `Known file name extensions'
                              below.

   mouse[=true|false]         Enable mouse interaction: Clicking onto the media
                              (giving it the focus) pauses the playback while
                              clicking outside resumes it.

   palindrome[=true|false]    Play media forward and backward.

   poster                     The first frame of the movie or the frame at the
                              beginning of the movie section specified by the
                              `startat' and `endat' options is shown.

   poster=<image>             Insert still image from file to be shown when
                              media is not activated. The file type depends on
                              the output driver: PS or EPS when using latex
                              together with dvips; PDF, PNG or JPEG when using
                              pdflatex.

                              Deprecated. Use option `text' instead.

                              See option `text' for a possibility to scale the
                              media display area according to the poster image
                              dimensions.

   rate=<rate>                Playback rate (multiple of original speed).

   repeat[=<repeats>]         Number of repeats. Without argument -> repeat
                              forever.

   startat=<offset>           Start/stop playback at the specified offsets
   endat=<offset>             (time, frame, named marker). <offset> syntax:

                              time:<seconds>
                              frame:<frame number>
                              marker:<quoted string>
                              {marker:<quoted string>, time:<seconds>}
                              {marker:<quoted string>, frame:<frame number>}

   text=<text>                <text> is typeset onto the media display area.
                              <text> is centred horizontally and vertically.
                              If either or both of the <width> and <height>
                              arguments are left empty, any unspecified
                              dimension of the media clip is scaled to fit the
                              corresponding dimension, i. e. width or height, of
                              <text>. Likewise, the depth of the media display
                              is adjusted to the depth of <text> if the `depth'
                              option has not been given.

                              This option can be used to scale the media display
                              area to the natural or scaled dimensions of the
                              poster image, e. g.:

                              \includemovie[text={\includegraphics[scale=2]{
                                path/to/poster}}]{}{}{path/to/movie}

   textoverposter[=false]     Set this option to `false' if you wish <text> to
                              be obscured by the external poster image (if
                              specified). Deprecated.

   url                        Treat <media file> as URL. Sets option `inline'
                              to false automatically.

   volume=<volume>            Percentage of original volume.

   3Daac=<angle>              This option sets the aperture angle of the camera,
                              measured in degrees. Fixed point real numbers
                              between 0 and 180 are admissible. A sensible value
                              of 30 is preset by default. Larger values can be
                              used to achieve wide-angle or fish-eye effects.

   3Dc2c=<x> <y> <z>          Direction vector C2C of arbitrary length,
                              originating in the centre of orbit and pointing
                              to the virtual camera; cf. option `3Dcoo' for the
                              number format of <x> <y> <z>.

   3Dcoo=<x> <y> <z>          Positional vector COO of the centre of orbit.
                              Only fixed point numbers in the range from
                              -999999999999999999.999999999999999999 to
                              +999999999999999999.999999999999999999 are
                              allowed.

   3Droo=<r>                  Radius of orbit ROO of the virtual camera; cf.
                              option `3Dcoo' for the number format.

   3Dviews=<views file>       Further named, predefined views can be set in an
                              auxiliary file specified by the 3Dviews option.
                              The file <views file> contains lines which obey
                              the syntax:

        [<name>]{<coo_x> <coo_y> <coo_z>}{<c2c_x> <c2c_y> <c2c_z>}{<roo>}{<aac>}

                              The <name> entry is optional. For <coo_x>,
                              <coo_y>, <coo_z>, <c2c_x>, <c2c_y>, <c2c_z>, <roo>
                              and <aac> the same rules as for the corresponding
                              options `3Dcoo', `3Dc2c', `3Droo' and `3Daac'
                              apply.

   3Dbg=<r> <g> <b>           This option sets the background colour of the
                              canvas. Only fixed point real numbers in the range
                              from 0 to 1 are allowed for the colour components.

   3Djscript=<JavaScipt file> Things like animation, lighting, background colour
                              etc. may also be script driven. Option `3Djscript'
                              associates a <JavaScipt file> with the 3D object.
                              The script will be executed upon activation of the
                              object.


 Additional options for use with `\movieref':

   play                       (Default) Immediately closes the media and
                              restarts playback. If new playback settings have
                              been specified through the options given above,
                              they override the original settings being in
                              effect during media inclusion.

   stop                       Stops and rewinds the media to its beginning or to
                              the `startat' position.

   resume                     Resumes paused media. In fact, this option makes
                              the hyperlink a toggle switch: repeated clicking
                              switches between paused and resumed state.

   pause                      Has the same effect as option `resume'. Added for
                              completeness only.

   reset                      Revert to the original settings which were in
                              effect during media inclusion.

   close                      Immediately closes the media player.


Known file name extensions:

 Extension          MIME type                       Description
 =============================================================================
 aif, aifc, aiff    audio/aiff                      Audio Interchange File
                                                    Format
 au, snd            audio/basic                     NeXT/Sun Audio Format
 avi                video/avi                       AVI (Audio/Video Inter-
                                                    leaved)
 mid, rmi           audio/midi                      MIDI (Musical Instrument
                                                    Digital Interface)
 mov, qt            video/quicktime                 Apple QuickTime
 mp3, m3u           audio/x-mp3                     MPEG Audio Layer-3
 mp4                video/mp4                       MPEG-4 Video/Audio
 mpeg, mpg          video/mpeg                      MPEG-2 Video
 ra, ram, rm        audio/x-pn-realaudio            Real Media
 smil               application/smil                Synchronized Multimedia
                                                    Integration Language
 swf                application/x-shockwave-flash   (Adobe?) Macromedia Flash
 u3d                model/u3d                       Universal 3D File Format
 wav                audio/wav                       MS Audio Format
 wma                audio/x-ms-wma                  Windows Media Audio Format
 wmv                video/x-ms-wmv                  Windows Media Video Format


Requirements:

 package `fp', if option `3D' is selected

 pdfLaTeX, version >= 1.20 is needed for direct PDF output

 Adobe Reader, version >=6 for playing movies/sound,
 Adobe Reader, version >=7 for 3D objects
 (Only Windows and Mac versions support embedded multimedia playback)

 Embedded media file data can also be extracted and saved to disk from within
 Readers which support file attachments. This makes PDF documents a little more
 portable to Readers which do not ship with a multimedia plugin.


Installation:

 Put the file movie15.sty to a place where TeX can find it.


License:

 This material is subject to the LaTeX Project Public License. See

    http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html

 for the details of that license.