diff options
Diffstat (limited to 'DOCS/man/en/input.rst')
| -rw-r--r-- | DOCS/man/en/input.rst | 98 |
1 files changed, 85 insertions, 13 deletions
diff --git a/DOCS/man/en/input.rst b/DOCS/man/en/input.rst index 72d8cb7c92..bf6ec4437a 100644 --- a/DOCS/man/en/input.rst +++ b/DOCS/man/en/input.rst @@ -164,7 +164,7 @@ playlist_clear run "<command>" Run the given command with ``/bin/sh -c``. The string is expanded like in - ``--playing-msg``. + property_expansion_. quit [<code>] Exit the player using the given exit code. @@ -196,13 +196,13 @@ osd [<level>] (see ``--osd-level`` for valid values). print_text "<string>" - Print text to stdout. The string can contain properties, which are expanded - like in ``--playing-msg``. + Print text to stdout. The string can contain properties (see + property_expansion_). 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. + as described in property_expansion_. 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``. @@ -289,7 +289,7 @@ osd-msg-bar raw Don't expand properties in string arguments. (Like ``"${property-name}"``.) expand-properties (default) - All string arguments are expanded like in ``--playing-msg``. + All string arguments are expanded as described in property_expansion_. All of the osd prefixes are still overridden by the global ``--osd-level`` @@ -304,11 +304,11 @@ Properties Properties are used to set mpv 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.) +expansion. (See property_expansion_.) -``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. +The ``W`` column 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 @@ -352,7 +352,8 @@ 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``) +aid x current audio track (similar to ``--aid``) +audio x alias for ``aid`` balance x audio channel balance fullscreen x see ``--fullscreen`` deinterlace x deinterlacing, if available (bool) @@ -377,9 +378,11 @@ fps container FPS (may contain bogus values) dwidth video width (after filters and aspect scaling) dheight video height aspect x video aspect -video x current video track (similar to ``--vid``) +vid x current video track (similar to ``--vid``) +video x alias for ``vid`` program x switch TS program (write-only) -sub x current subtitle track (similar to ``--sid``) +sid x current subtitle track (similar to ``--sid``) +sub x alias for ``sid`` sub-delay x see ``--sub-delay`` sub-pos x see ``--sub-pos`` sub-visibility x whether current subtitle is rendered @@ -397,3 +400,72 @@ track-list list of audio/video/sub tracks, cur. entr. marked chapter-list list of chapters, current entry marked playlist playlist, current entry marked =========================== = ================================================== + +.. _property_expansion: + +Property expansion +------------------ + +All string arguments to input commands as well as certain options (like +``--playing-msg``) are subject to property expansion. + +*EXAMPLE for input.conf*: + +- ``i show_text "Filename: ${filename}"`` shows the filename of the current file + when pressing the ``i`` key + +Within ``input.conf``, property expansion can be inhibited by putting the +``raw`` prefix in front of commands. + +The following expansions are supported: + +\${NAME} + Expands to the value of the property ``NAME``. If retrieving the property + fails, expand to an error string. (Use ``${NAME:}`` with a trailing + ``:`` to expand to an empty string instead.) + If ``NAME`` is prefixed with ``=``, expand to the raw value of the property + (see below). +\${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 recursive + expansion.) +\$> + Disable property expansion and special handling of ``$`` for the rest + of the string. + +In places where property expansion is allowed, C-style escapes are often +accepted as well. Example: + +- ``\n`` becomes a newline character +- ``\\`` expands to ``\`` + +Raw and formatted properties +---------------------------- + +Normally, properties are formatted as human readable text, meant to be +displayed on OSD or on the terminal. It is possible to retrieve an unformatted +(raw) value from a property by prefixing its name with ``=``. These raw values +can be parsed by scripts, and follow the same conventions as the options +associated with the properties. + +*EXAMPLE*: + +- ``${time-pos}`` expands to ``00:14:23`` (if playback position is at 15 minutes + 32 seconds) +- ``${=time-pos}`` expands to ``863.4`` (same time, plus 400 milliseconds - + milliseconds are normally not shown in the formatted case) + +Sometimes, the difference in amount of information carried by raw and formatted +property values can be rather big. In some cases, raw values have more +information, like higher precision than seconds with ``time-pos``. Sometimes +it's the other way around, e.g. ``aid`` shows track title and language in the +formatted case, but only the track number if it's raw. |