diff options
author | wm4 <wm4@nowhere> | 2012-09-27 03:20:12 +0200 |
---|---|---|
committer | wm4 <wm4@nowhere> | 2012-10-12 10:10:33 +0200 |
commit | 65074ec1f074d22101b4c8bd95eb4a0354401246 (patch) | |
tree | 6cfb64c8f6e8817e25f50f18646857b65331657b | |
parent | 1d1f59234b0e60df0b9461dd8194b639d334dd61 (diff) | |
download | mpv-65074ec1f074d22101b4c8bd95eb4a0354401246.tar.bz2 mpv-65074ec1f074d22101b4c8bd95eb4a0354401246.tar.xz |
manpage: document input.conf related things
This directly corresponds to DOCS/OUTDATED-tech/slave.txt.
Changes from the recent commits are included too.
-rw-r--r-- | DOCS/man/en/changes.rst | 45 | ||||
-rw-r--r-- | DOCS/man/en/input.rst | 303 | ||||
-rw-r--r-- | DOCS/man/en/mplayer.rst | 2 | ||||
-rw-r--r-- | DOCS/man/en/options.rst | 34 |
4 files changed, 367 insertions, 17 deletions
diff --git a/DOCS/man/en/changes.rst b/DOCS/man/en/changes.rst index 11b7242d1a..de56621278 100644 --- a/DOCS/man/en/changes.rst +++ b/DOCS/man/en/changes.rst @@ -106,15 +106,42 @@ Command line switches input.conf and slave commands ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* Table of renamed slave commands: - - =================================== =================================== - Old New - =================================== =================================== - pt_step 1 b playlist_next b - pt_step -1 b playlist_prev b - pt_clear playlist_clear - =================================== =================================== +* Table of renamed input commands: + + This lists only commands that are not always gracefully handled by the + internal legacy translation layer. If an input.conf contains any legacy + commands, they will be displayed with ``-v`` when it is loaded, and show + and the replacement commands. + + Properties containing ``_`` to separate words use ``-`` instead. + + +--------------------------------+----------------------------------------+ + | Old | New | + +================================+========================================+ + | pt_step 1 [0|1] | playlist_next [weak|force] | + | | (translation layer can't deal with | + | | whitespace) | + +--------------------------------+----------------------------------------+ + | pt_step -1 [0|1] | playlist_prev [weak|force] (same) | + +--------------------------------+----------------------------------------+ + | switch_ratio [<ratio>] | set aspect <ratio> | + | | set aspect 0 (to reset aspect) | + +--------------------------------+----------------------------------------+ + | step_property_osd <prop> <step>| cycle <prop> <step> (wraps), | + | <dir> | add <prop> <step> (clamps). | + | | <dir> parameter unsupported. Use | + | | a negative step instead. | + +--------------------------------+----------------------------------------+ + | step_property <prop> <step> | Prefix cycle or add with no-osd: | + | <dur> | no-osd cycle <prop> <step> | + +--------------------------------+----------------------------------------+ + | osd_show_property_text <text> | show_text <text> | + | | The property expansion format string | + | | syntax slightly changed. | + +--------------------------------+----------------------------------------+ + | osd_show_text | Now does the same as | + | | osd_show_property_text. | + +--------------------------------+----------------------------------------+ Other ~~~~~ diff --git a/DOCS/man/en/input.rst b/DOCS/man/en/input.rst new file mode 100644 index 0000000000..ab392a5696 --- /dev/null +++ b/DOCS/man/en/input.rst @@ -0,0 +1,303 @@ +.. _input: + +INPUT.CONF +========== + +The input.conf file consists of a list of key bindings, for example: + +| s screenshot # take a screenshot with the s key + +Each line maps a key to an input command. Keys are specified with their literal +value (upper case if combined with ``Shift``), or a name for special keys. For +example, ``a`` maps to the ``a`` key without shift, and ``A`` maps to ``a`` +with shift. + +A list of special keys can be obtained with + +| **mplayer** --input=keylist + +In general, keys can be combined with ``Shift``, ``Ctrl`` and ``Alt``: + +| ctrl+q quit + +General input command syntax +---------------------------- + +`[Shift+][Ctrl+][Alt+][Meta+]<key> [<prefix>] <command> (<argument>)*` + +Newlines always start a new binding. ``#`` starts a comment (outside of quoted +string arguments). To bind commands to the ``#`` key, ``SHARP`` can be used. + +<key> is either the literal character the key produces (ASCII or unicode +character), or a symbol name. + +Arguments are separated by whitespace. This applies even to string arguments. +For this reason, string arguments should be quoted with ``"``. Inside quotes, +C style escaping can be used. + +Optional arguments can be skipped with ``-``. + +List of input commands +---------------------- + +ignore + Use this to "block" keys that should be unbound, and do nothing. Useful for + disabling default bindings, without disabling all bindings with + ``--input=default-bindings=no``. + +seek <seconds> [relative|absolute|absolute-percent] [default-precise|exact|keyframes] + Change the playback position. By default, seeks by a relative amount of + seconds. + + The second argument sets the seek mode: + + relative (default) + Seek relative to current position (a negative value seeks backwards). + absolute + Seek to a given time. + absolute-percent + Seek to agiven percent position. + + The third argument defines how exact the seek is: + + default-precise (default) + Follow the default behavior as set by ``--hr-seek``, which by default + does imprecise seeks (like ``keyframes``). + exact + Always do exact/hr/precise seeks (slow). + keyframes + Always restart playback at keyframe boundaries (fast). + +frame_step + Basically seek forward by one frame. Actually this plays one frame, then + pauses again. + +set <property> "<value>" + Set the given property to the given value. + +add <property> [<value>] + Add the given value to the property. On overflow or underflow, clamp the + property to the maximum. If <value> is omitted, assume ``1``. + +cycle <property> [<value>] + Cycle the given property. Negative values cycle the property backwards. On + overflow, set the property back to the minimum, on underflow set it to the + maximum. If <value> is omitted, assume ``1``. + +speed_mult <value> + Multiply the ``speed`` property by the given value. + +screenshot [single|each-frame] [video|window] + Take a screenshot. + + First argument: + + <single> (default) + Take a single screenshot. + <each-frame> + Take a screenshot each frame. Issue this command again to stop taking + screenshots. + + Second argument: + + <video> (default) + Save the video image, in its original resolution. Typically without + OSD or subtitles, but the exact behavior depends on the selected video + output. + <window> + Save the contents of the mplayer window. Typically scaled, with OSD and + subtitles. The exact behavior depends on the selected video output, and + if not support is available, this will act like ``video``. + +playlist_next [weak|force] + Go to the next entry on the playlist. + + weak (default) + If the last file on the playlist is currently played, do nothing. + force + Terminate playback if there are no more files on the playlist. + +playlist_prev [weak|force] + Go to the previous entry on the playlist. + + weak (default) + If the first file on the playlist is currently played, do nothing. + force + Terminate playback if the first file is being played. + +loadfile "<file>" [replace|append] + Load the given file and play it. + + Second argument: + + <replace> (default) + Stop playback of the current file, and play the new file immediately. + <append> + Append the file to the playlist. + +loadlist "<playlist>" [replace|append] + Load the given playlist file (like ``--playlist``). + +playlist_clear + Clear the playlist, except the currently played file. + +run "<command>" + Run the given command with ``/bin/sh -c``. The string is expanded like in + ``--playing-msg`` before + +quit [<code>] + Exit the player using the given exit code. + +sub_load "<file>" + Load the given subtitle file. It's not selected as current subtitle after + loading. + +sub_step <skip> + Change subtitle timing such, that the subtitle event after the next <skip> + subtitle events is displayed. <skip> can be negative to step back. + +osd [<level>] + Toggle OSD level. If <level> is specified, set the OSD mode + (see ``--osd-level`` for valid values). + +show_text "<string>" [<duration>] [<level>] + Show text on the OSD. The string can contain properties, which are expanded + like in ``--playing-msg``. This can be used to show playback time, filename, + and so on. + + <duration> is the time in ms to show the message. By default, it uses the + same value as ``--osd-duration``. + + <level> is the minimum OSD level to show the text (see ``--osd-level``). + +show_progress + Show the progress bar, the elapsed time and the total duration of the file + on the OSD. + +show_chapters + Show a list of chapters on the OSD. + +show_tracks + Show a list of video/audio/subtitle tracks on the OSD. + + + +Undocumented properties: tv_start_scan, tv_step_channel, tv_step_norm, +tv_step_chanlist, tv_set_channel, tv_last_channel, tv_set_freq, tv_step_freq, +tv_set_norm, dvb_set_channel, radio_step_channel, radio_set_channel, +radio_set_freq, radio_step_freq (all of these should be replaced by properties), +edl_mark, stop (questionable use), get_property (?), af_switch, af_add, af_del, +af_clr, af_cmdline, vo_cmdline (experimental). + +Input command prefixes +---------------------- + +osd-auto (default) + Use the default behavior for this command. +no-osd + Do not use any OSD for this command. +osd-bar + If possible, show a bar with this command. Seek commands will show the + progress bar, property changing commands may show the newly set value. +osd-msg + If possible, show an OSD message with this command. The seek command shows + the current playback time (like ``show_progress``), property changing + commands show the newly set value as text. +osd-msg-bar + Combine osd-bar and osd-msg. + + + +All of these are still overridden by the global ``--osd-level`` settings. + +Undocumented prefixes: pausing, pausing_keep, pausing_toggle, +pausing_keep_force. (Should these be made official?) + +Properties +---------- + +Properties are used to set mplayer options during runtime, or to query arbitrary +information. They can be manipulated with the ``set``/``add``/``cycle`` +commands, and retrieved with ``show_text``, or anything else that uses property +expansion. (See ``--playing-msg`` how properties are expanded.) + +``W`` indicates whether the property is generally writeable. If an option +is referenced, the property should take/return exactly the same values as the +option. + +=========================== = ================================================== +Name W Comment +=========================== = ================================================== +osd-level x see ``--osd-level`` +loop x see ``--loop`` +speed x see ``--speed`` +filename currently played file (path stripped) +path currently played file (full path) +demuxer +stream-pos x byte position in source stream +stream-start start byte offset in source stream +stream-end end position in bytes in source stream +stream-length length in bytes (${stream-end} - ${stream-start}) +stream-time-pos x time position in source stream (also see time-pos) +length length of the current file in seconds +percent-pos x position in current file (0-100) +time-pos x position in current file in seconds +chapter x current chapter number +edition x current MKV edition number +titles number of DVD titles +chapters number of chapters +editions number of MKV editions +angle current DVD angle +metadata metadata key/value pairs +metadata/<key> value of metedata entry <key> +pause x pause status (bool) +pts-association-mode x see ``--pts-association-mode`` +hr-seek x see ``--hr-seek`` +volume x current volume (0-100) +mute x current mute status (bool) +audio-delay x see ``--audio-delay`` +audio-format audio format (codec tag) +audio-codec audio codec selected for decoding +audio-bitrate audio bitrate +samplerate audio samplerate +channels number of audio channels +audio x current audio track (similar to ``--aid``) +balance x audio channel balance +fullscreen x see ``--fullscreen`` +deinterlace x deinterlacing, if available (bool) +colormatrix x see ``--colormatrix`` +colormatrix-input-range x see ``--colormatrix-input-range`` +colormatrix-output-range x see ``--colormatrix-output-range`` +ontop x see ``--ontop`` +rootwin x see ``--rootwin`` +border x see ``--border`` +framedrop x see ``--framedrop`` +gamma x see ``--gamma`` +brightness x see ``--brightness`` +contrast x see ``--contrast`` +saturation x see ``--saturation`` +hue x see ``--hue`` +panscan x see ``--panscan`` +vsync x see ``--vsync`` +video-format video format (integer FourCC) +video-codec video codec selected for decoding +video-bitrate video bitrate +width video width +height video height +fps FPS (may contain bogus values) +aspect x video aspect +video x current video track (similar to ``--vid``) +program x switch TS program (write-only) +sub x current subttitle track (similar to ``--sid``) +sub-delay x see ``--sub-delay`` +sub-pos x see ``--sub-pos`` +sub-visibility x whether current subtitle is rendered +sub-forced-only x see ``--sub-forced-only`` +sub-scale x subtitle font size multiplicator +ass-use-margins x see ``--ass-use-margins`` +ass-vsfilter-aspect-compat x see ``--ass-vsfilter-aspect-compat`` +tv-brightness +tv-contrast +tv-saturation +tv-hue +=========================== = ================================================== diff --git a/DOCS/man/en/mplayer.rst b/DOCS/man/en/mplayer.rst index 89b03737c3..840f36f23c 100644 --- a/DOCS/man/en/mplayer.rst +++ b/DOCS/man/en/mplayer.rst @@ -409,6 +409,8 @@ OPTIONS .. include:: encode.rst +.. include:: input.rst + Taking screenshots ================== diff --git a/DOCS/man/en/options.rst b/DOCS/man/en/options.rst index 342626d5d2..453c8e052f 100644 --- a/DOCS/man/en/options.rst +++ b/DOCS/man/en/options.rst @@ -1326,15 +1326,33 @@ See also ``--user``. --playing-msg=<string> - Print out a string before starting playback. The following expansions are - supported: + Print out a string before starting playback. The string is expanded for + properties, e.g. ``--playing-msg=file: ${filename}`` will print the string + ``file: `` followed by the currently played filename. + + The following expansions are supported: ${NAME} - Expand to the value of the property ``NAME``. - ?(NAME:TEXT) - Expand ``TEXT`` only if the property ``NAME`` is available. - ?(!NAME:TEXT) - Expand ``TEXT`` only if the property ``NAME`` is not available. + Expands to the value of the property ``NAME``. If ``NAME`` starts with + ``=``, use the raw value of the property. If retrieving the property + fails, expand to an error string. (Use ``${NAME:}`` with a trailing + ``:`` to expand to an empty string instead.) + ${NAME:STR} + Expands to the value of the property ``NAME``, or ``STR`` if the + property can't be retrieved. ``STR`` is expanded recursively. + ${!NAME:STR} + Expands to ``STR`` (recursively) if the property ``NAME`` can't be + retrieved. + ${?NAME:STR} + Expands to ``STR`` (recursively) if the property ``NAME`` is available. + $$ + Expands to ``$``. + $} + Expands to ``}``. (To produce this character inside rexursive + expansion.) + $> + Disable property expansion and special handling of ``$`` for the rest + of the string. --playlist=<filename> Play files according to a playlist file (ASX, Winamp, SMIL, or @@ -1980,7 +1998,7 @@ the line used for the OSD and clear it (default: ``^[[A\r^[[K``). --title - Set the window title. The string can contain property names. + Set the window title. Properties are expanded (see ``--playing-msg``). --tv=<option1:option2:...> This option tunes various properties of the TV capture module. For |