diff options
author | Norbert Preining <norbert@preining.info> | 2020-04-10 03:06:35 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2020-04-10 03:06:35 +0000 |
commit | 25111608e6aa05042b0c6f83009262e1973d7a45 (patch) | |
tree | 4e47675c9f816298a780508cf0b31db2f84bd5fd /macros/latex/contrib/media4svg/README.md | |
parent | 122d129e46fd990f791aeb4ff07eaa1b35b9af0d (diff) |
CTAN sync 202004100306
Diffstat (limited to 'macros/latex/contrib/media4svg/README.md')
-rw-r--r-- | macros/latex/contrib/media4svg/README.md | 173 |
1 files changed, 173 insertions, 0 deletions
diff --git a/macros/latex/contrib/media4svg/README.md b/macros/latex/contrib/media4svg/README.md new file mode 100644 index 0000000000..841f2ba63c --- /dev/null +++ b/macros/latex/contrib/media4svg/README.md @@ -0,0 +1,173 @@ +# The `media4svg` LaTeX Package + +Version 0.1, 2020/04/09 + +© 2020--today, Alexander Grahn + +https://gitlab.com/agrahn/media4svg + +## Introduction + +This package implements an interface for embedding video and audio files in SVG +(Scalable Vector Graphics) output. SVG with embedded media is very portable, +as it is supported by all modern Web browsers across a variety of operating +systems and platforms, including portable devices. + +The most portable media formats are as follows: + +**Video** + +| **File extension** | **Codecs** | **MIME-type** | +|:-------------------|:---------------------|:--------------| +| `mp4` | v: h264, a: AAC | `video/mp4` | +| `webm` | v: VP8, a: Vorbis | `video/webm` | +| `ogg` | v: Theora, a: Vorbis | `video/ogg` | + +**Audio** + +| **File extension** | **MIME-type** | +|:-------------------|:--------------| +| `mp3` | `audio/mpeg` | +| `ogg` | `audio/ogg` | +| `wav` | `audio/wav` | + + +In the world of TeX and LaTeX, SVG is produced by means of the +[`dvisvgm`](https://dvisvgm.de/) backend by M. Gieseking, which is included in +TeXLive and MiKTeX. + +Supported workflows are: +* `dvilualatex` ⇒ `dvisvgm` +* `[p|up]latex` ⇒ `dvisvgm` +* `xelatex --no-pdf` ⇒ `dvisvgm` + +All TeX engines that produce DVI/XDV output can be used, but `dvilualatex` is +to be preferred. By default, media data are physically embedded into the SVG +output. For this, they need to be Base64 encoded, which is done by the +built-in Lua interpreter of LuaTeX. The other, non-LuaTeX-based engines call +the Lua script for Base64-encoding as an external program via shell-escape, +which is much slower. + +**Recommended `dvisvgm` commandline options** + +There are a number of `dvisvgm` commandline options that should be used in general: + +````latex +dvisvgm --zoom=-1 --exact --pages=1,- --font-format=woff2 <DVI/XDV file> +```` +For exporting `beamer`-class documents to SVG, option `--box=papersize` +should also be added. Refer to the manual page, `man dvisvgm`, for additional +information. + +## Usage + +---- + +**Usage example** + +Here is an +[example presentation](http://mirrors.ctan.org/macros/latex/contrib/media4svg/example/beamer-example-1.svg) +([source code][http://mirrors.ctan.org/macros/latex/contrib/media4svg/example/beamer-example.tex]) +with an embedded video file and a streamed video. It also explains how to use +the mouse and the keyboard for playback control. + +---- + +Option `dvisvgm` must be set globally by passing it to the document class. +````latex +\documentclass[dvisvgm]{...} +```` + +The package itself is loaded with +````latex +\usepackage[<options>]{media4svg} +```` + +Package options are: `draft`, `final`, `autoplay`, `loop`, `controls`, +`mimetype`, `width`, `height`, `totalheight`, `keepaspectratio`, `scale`, +`url`, `embed`. They have the same meaning as the command options explained +below, but are applied globally. + +Note that `media4svg` is incompatible with package `media9`. + +The command for media inclusion is +````latex +\includemedia[<options>]{<poster text>}{<media file or URL>} +```` +Command options: +````latex +id=<label> +```` +The media is given an ID by which it can be referenced in JavaScript code, as +in `$("myVid").play();`, for example. +````latex +draft +final +```` +These have the usual meaning. If `draft` is set, a box is inserted into the +document instead of the media widget. +````latex +autoplay +```` +Media playback is started after the page has been loaded in the web browser. +Depending on their settings, browsers may refuse to autoplay audio and +video with unmuted audio. Option `muted` may need to be set as well to allow +automatically start of video playback. +````latex +loop +```` +Media is played in a loop. +````latex +muted +```` +The audio will be initially silenced. +````latex +time=<time offset> +```` +Playback starts with an offset, specified in seconds. +````latex +controls +```` +Player-specific controls are shown as an overlay in the media widget. +````latex +mimetype=<mime type> +```` +Although optional, it may be a good idea to give a hint to the web browser +about the kind of media to be played, such as `audio/mpeg` or `video/mp4`. +````latex +url +```` +The last argument of `\includemedia` is taken as a URL and media data will not +be embedded in the SVG file. +````latex +embed=false +```` +By default, a local media file, given as the last argument of `\includemedia`, is +encoded and embedded as a data blob into the SVG output. Option `embed=false` +suppresses embedding and the media file remains separate. +````latex +width=<h-size> +height=<v-size> | totalheight=<v-size> +keepaspectratio +```` +Resize the media widget or set its size if `<poster text>` is left empty. If +provided, `<poster text>` is squeezed or stretched according to the given +options. If only one of `width` or `[total]height` is given, the other +dimension is scaled to maintain the aspect ratio of `<poster text>`. If both +`width` and `[total]height` are given together with `keepaspectratio`, +`<poster text>` is resized to fit within `<h-size>` and `<v-size>` while +maintaining its original aspect ratio. Any valid TeX dimension is acceptable +for `<h-size>` and `<v-size>`. In addition, the length commands `\width`, +`\height`, `\depth` and `\totalheight` can be used to refer to the original +dimensions of `<poster text>`. +````latex +scale=<factor> +```` +Scales the media widget by `<factor>`. + +---- + +## License + +This material is subject to the [LaTeX Project Public License](http://mirrors.ctan.org/macros/latex/base/lppl.txt). + |