summaryrefslogtreecommitdiffstats
path: root/DOCS
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2012-09-27 03:20:12 +0200
committerwm4 <wm4@nowhere>2012-10-12 10:10:33 +0200
commit65074ec1f074d22101b4c8bd95eb4a0354401246 (patch)
tree6cfb64c8f6e8817e25f50f18646857b65331657b /DOCS
parent1d1f59234b0e60df0b9461dd8194b639d334dd61 (diff)
downloadmpv-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.
Diffstat (limited to 'DOCS')
-rw-r--r--DOCS/man/en/changes.rst45
-rw-r--r--DOCS/man/en/input.rst303
-rw-r--r--DOCS/man/en/mplayer.rst2
-rw-r--r--DOCS/man/en/options.rst34
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