From 4af59abbb416a365a98efca8875c0f0c1b0c872f Mon Sep 17 00:00:00 2001 From: wm4 Date: Sat, 8 Jun 2013 18:04:36 +0200 Subject: [PATCH] manpage: improve documentation of property expansion --- DOCS/man/en/input.rst | 98 +++++++++++++++++++++++++++++++++++------ DOCS/man/en/options.rst | 37 +++------------- 2 files changed, 90 insertions(+), 45 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 "" Run the given command with ``/bin/sh -c``. The string is expanded like in - ``--playing-msg``. + property_expansion_. quit [] Exit the player using the given exit code. @@ -196,13 +196,13 @@ osd [] (see ``--osd-level`` for valid values). print_text "" - 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 "" [|- []] 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. 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. diff --git a/DOCS/man/en/options.rst b/DOCS/man/en/options.rst index 78678267cb..bc78c2aeaf 100644 --- a/DOCS/man/en/options.rst +++ b/DOCS/man/en/options.rst @@ -1440,7 +1440,7 @@ Show a custom string during playback instead of the standard status text. This overrides the status text used for ``--osd-level=3``, when using the ``show_progress`` command (by default mapped to ``P``), or in some - non-default cases when seeking. Expands properties. See ``--playing-msg``. + non-default cases when seeking. Expands properties. See property_expansion_. --overlapsub Allows the next subtitle to be displayed while the current one is still @@ -1472,38 +1472,11 @@ properties, e.g. ``--playing-msg=file: ${filename}`` will print the string ``file:`` followed by a space and the currently played filename. - The following expansions are supported: - - \${NAME} - 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 recursive - expansion.) - \$> - Disable property expansion and special handling of ``$`` for the rest - of the string. - - This option also parses C-style escapes. Example: - - - ``\n`` becomes a newline character - - ``\\`` expands to ``\`` + See property_expansion_. --status-msg= Print out a custom string during playback instead of the standard status - line. Expands properties. See ``--playing-msg``. + line. Expands properties. See property_expansion_. --stream-capture= Allows capturing the primary stream (not additional audio tracks or other @@ -2142,8 +2115,8 @@ the line used for the OSD and clear it (default: ``^[[A\r^[[K``). --title= - Set the window title. Properties are expanded on playback start - (see ``--playing-msg``). + Set the window title. Properties are expanded on playback start. + (See property_expansion_.) --tv= This option tunes various properties of the TV capture module. For