summaryrefslogtreecommitdiffstats
path: root/DOCS/man/en
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2013-06-08 18:04:36 +0200
committerwm4 <wm4@nowhere>2013-06-08 18:09:58 +0200
commit4af59abbb416a365a98efca8875c0f0c1b0c872f (patch)
tree06190ded619bda96bc692cc06a6b5b81e6d3060b /DOCS/man/en
parent667c8352f3b0a8dcdaadd2aac6d4588a376e5e52 (diff)
downloadmpv-4af59abbb416a365a98efca8875c0f0c1b0c872f.tar.bz2
mpv-4af59abbb416a365a98efca8875c0f0c1b0c872f.tar.xz
manpage: improve documentation of property expansion
Diffstat (limited to 'DOCS/man/en')
-rw-r--r--DOCS/man/en/input.rst98
-rw-r--r--DOCS/man/en/options.rst37
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 "<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.
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=<string>
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=<filename>
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=<string>
- 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=<option1:option2:...>
This option tunes various properties of the TV capture module. For