summaryrefslogtreecommitdiffstats
path: root/DOCS/man/en/input.rst
diff options
context:
space:
mode:
authorMartin Herkt <lachs0r@srsfckn.biz>2013-07-08 18:02:14 +0200
committerMartin Herkt <lachs0r@srsfckn.biz>2013-07-08 18:02:46 +0200
commit09d2dd7c3ab1cc650ede12f00affbba4b73b970b (patch)
tree525e8e400199ca61c59175e5e874e709138c7cba /DOCS/man/en/input.rst
parent1a8ab1d6adb8d849ed6f1b8a31baf0ef31242e4a (diff)
downloadmpv-09d2dd7c3ab1cc650ede12f00affbba4b73b970b.tar.bz2
mpv-09d2dd7c3ab1cc650ede12f00affbba4b73b970b.tar.xz
manpage: proofread and fix formatting
Diffstat (limited to 'DOCS/man/en/input.rst')
-rw-r--r--DOCS/man/en/input.rst416
1 files changed, 209 insertions, 207 deletions
diff --git a/DOCS/man/en/input.rst b/DOCS/man/en/input.rst
index 5b8a57ead1..7dab3bb1b4 100644
--- a/DOCS/man/en/input.rst
+++ b/DOCS/man/en/input.rst
@@ -1,11 +1,9 @@
-.. _input:
-
INPUT.CONF
==========
-The input.conf file consists of a list of key bindings, for example:
+The input.conf file consists of a list of key bindings, for example::
-| s screenshot # take a screenshot with the s key
+ 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
@@ -14,16 +12,16 @@ with shift.
A list of special keys can be obtained with
-| **mpv** --input-keylist
+ ``mpv --input-keylist``
-In general, keys can be combined with ``Shift``, ``Ctrl`` and ``Alt``:
+In general, keys can be combined with ``Shift``, ``Ctrl`` and ``Alt``::
-| ctrl+q quit
+ ctrl+q quit
**mpv** can be started in input test mode, which displays key bindings and the
-commands they're bound to on the OSD, instead of running the commands:
+commands they're bound to on the OSD, instead of executing the commands::
-| **mpv** --input-test --demuxer=rawvideo --rawvideo=w=1280:h=720 /dev/zero
+ mpv --input-test --demuxer=rawvideo --rawvideo=w=1280:h=720 /dev/zero
(Commands which normally close the player will not work in this mode, and you
must kill **mpv** externally to make it exit.)
@@ -31,31 +29,32 @@ must kill **mpv** externally to make it exit.)
General Input Command Syntax
----------------------------
-`[Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] [<prefixes>] <command> (<argument>)*`
+``[Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] [<prefixes>] <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
+``<key>`` is either the literal character the key produces (ASCII or Unicode
character), or a symbol name.
-<section> (braced with ``{`` and ``}``) is the input section for this command.
+``<section>`` (braced with ``{`` and ``}``) is the input section for this
+command.
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.
+C-style escaping can be used.
Optional arguments can be skipped with ``-``.
List of Input Commands
----------------------
-ignore
+``ignore``
Use this to "block" keys that should be unbound, and do nothing. Useful for
disabling default bindings, without disabling all bindings with
``--no-input-default-bindings``.
-seek <seconds> [relative|absolute|absolute-percent|- [default-precise|exact|keyframes]]
+``seek <seconds> [relative|absolute|absolute-percent|- [default-precise|exact|keyframes]]``
Change the playback position. By default, seeks by a relative amount of
seconds.
@@ -78,10 +77,10 @@ seek <seconds> [relative|absolute|absolute-percent|- [default-precise|exact|keyf
keyframes
Always restart playback at keyframe boundaries (fast).
-frame_step
+``frame_step``
Play one frame, then pause.
-frame_back_step
+``frame_back_step``
Go back by one frame, then pause. Note that this can be very slow (it tries
to be precise, not fast), and sometimes fails to behave as expected. How
well this works depends on whether precise seeking works correctly (e.g.
@@ -90,24 +89,24 @@ frame_back_step
usually work, but might make backstepping silently behave incorrectly in
corner cases.
- This doesn't work with audio-only playback.
+ This does not work with audio-only playback.
-set <property> "<value>"
+``set <property> "<value>"``
Set the given property to the given value.
-add <property> [<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``.
+ property to the maximum. If ``<value>`` is omitted, assume ``1``.
-cycle <property> [up|down]
+``cycle <property> [up|down]``
Cycle the given property. ``up`` and ``down`` set the cycle direction. On
overflow, set the property back to the minimum, on underflow set it to the
maximum. If ``up`` or ``down`` is omitted, assume ``up``.
-speed_mult <value>
+``speed_mult <value>``
Multiply the ``speed`` property by the given value.
-screenshot [subtitles|video|window|- [single|each-frame]]
+``screenshot [subtitles|video|window|- [single|each-frame]]``
Take a screenshot.
First argument:
@@ -132,7 +131,7 @@ screenshot [subtitles|video|window|- [single|each-frame]]
Take a screenshot each frame. Issue this command again to stop taking
screenshots.
-playlist_next [weak|force]
+``playlist_next [weak|force]``
Go to the next entry on the playlist.
weak (default)
@@ -140,7 +139,7 @@ playlist_next [weak|force]
force
Terminate playback if there are no more files on the playlist.
-playlist_prev [weak|force]
+``playlist_prev [weak|force]``
Go to the previous entry on the playlist.
weak (default)
@@ -148,7 +147,7 @@ playlist_prev [weak|force]
force
Terminate playback if the first file is being played.
-loadfile "<file>" [replace|append]
+``loadfile "<file>" [replace|append]``
Load the given file and play it.
Second argument:
@@ -158,91 +157,94 @@ loadfile "<file>" [replace|append]
<append>
Append the file to the playlist.
-loadlist "<playlist>" [replace|append]
+``loadlist "<playlist>" [replace|append]``
Load the given playlist file (like ``--playlist``).
-playlist_clear
+``playlist_clear``
Clear the playlist, except the currently played file.
-playlist_remove <index>
+``playlist_remove <index>``
Remove the playlist entry at the given index. Index values start counting
- with 0. You can't remove the entry for the currently played file.
+ with 0. You cannot remove the entry for the currently played file.
-playlist_move <index1> <index2>
+``playlist_move <index1> <index2>``
Move the playlist entry at index1, so that it takes the place of the
entry index2. (Paradoxically, the moved playlist entry will not have
the index value index2 after moving if index1 was lower than index2,
because index2 refers to the target entry, not the index the entry
will have after moving.)
-run "<command>"
+``run "<command>"``
Run the given command with ``/bin/sh -c``. The string is expanded like in
- property_expansion_.
+ `Property Expansion`_.
-quit [<code>]
+``quit [<code>]``
Exit the player using the given exit code.
-quit_watch_later
+``quit_watch_later``
Exit player, and store current playback position. Playing that file later
will seek to the previous position on start.
-sub_add "<file>"
- Load the given subtitle file. It's not selected as current subtitle after
+``sub_add "<file>"``
+ Load the given subtitle file. It is not selected as current subtitle after
loading.
-sub_remove [<id>]
+``sub_remove [<id>]``
Remove the given subtitle track. If the ``id`` argument is missing, remove
the current track. (Works on external subtitle files only.)
-sub_reload [<id>]
+``sub_reload [<id>]``
Reload the given subtitle tracks. If the ``id`` argument is missing, remove
the current track. (Works on external subtitle files only.)
This works by unloading and re-adding the subtitle track.
-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.
+``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
+ backwards.
-osd [<level>]
- Toggle OSD level. If <level> is specified, set the OSD mode
+``osd [<level>]``
+ Toggle OSD level. If ``<level>`` is specified, set the OSD mode
(see ``--osd-level`` for valid values).
-print_text "<string>"
+``print_text "<string>"``
Print text to stdout. The string can contain properties (see
- property_expansion_).
+ `Property Expansion`_).
-show_text "<string>" [<duration>|- [<level>]]
+``show_text "<string>" [<duration>|- [<level>]]``
Show text on the OSD. The string can contain properties, which are expanded
- as described in property_expansion_. This can be used to show playback
+ 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``.
+ <duration>
+ The time in ms to show the message for. By default, it uses the same
+ value as ``--osd-duration``.
- <level> is the minimum OSD level to show the text (see ``--osd-level``).
+ <level>
+ The minimum OSD level to show the text at (see ``--osd-level``).
-show_progress
+``show_progress``
Show the progress bar, the elapsed time and the total duration of the file
on the OSD.
Input Commands that are Possibly Subject to Change
--------------------------------------------------
-af_switch "filter1=params,filter2,..."
+``af_switch "filter1=params,filter2,..."``
Replace the current filter chain with the given list.
-af_add "filter1=params,filter2,..."
+``af_add "filter1=params,filter2,..."``
Add the given list of audio filters to the audio filter chain.
-af_del "filter1,filter2,..."
+``af_del "filter1,filter2,..."``
Remove the given list of audio filters.
-af_clr
+``af_clr``
Remove all audio filters. (Conversion filters will be re-added
automatically if needed.)
-vf set|add|toggle|del "filter1=params,filter2,..."
+``vf set|add|toggle|del "filter1=params,filter2,..."``
Change video filter chain.
The first argument decides what happens:
@@ -267,64 +269,66 @@ vf set|add|toggle|del "filter1=params,filter2,..."
filter.
You can assign labels to filter by prefixing them with ``@name:`` (where
- ``name`` is a user-chosen arbitrary identifiers). Labels can be used to
+ ``name`` is a user-chosen arbitrary identifier). Labels can be used to
refer to filters by name in all of the filter chain modification commands.
For ``add``, using an already used label will replace the existing filter.
- *EXAMPLE for input.conf*:
+ .. admonition:: Example for input.conf
- - ``a vf set flip`` turn video upside-down on the ``a`` key
- - ``b vf set ""`` remove all video filters on ``b``
- - ``c vf toggle lavfi=gradfun`` toggle debanding on ``c``
+ - ``a vf set flip`` turn video upside-down on the ``a`` key
+ - ``b vf set ""`` remove all video filters on ``b``
+ - ``c vf toggle lavfi=gradfun`` toggle debanding on ``c``
-enable_section "<section>" [default|exclusive]
+``enable_section "<section>" [default|exclusive]``
Enable all key bindings in the named input section.
The enabled input sections form a stack. Bindings in sections on the top of
the stack are preferred to lower sections. This command puts the section
- on top of the stack. If the section was already on the stack, it's
- implicitly removed beforehand. (A section can't be on the stack twice.)
+ on top of the stack. If the section was already on the stack, it is
+ implicitly removed beforehand. (A section cannot be on the stack more than
+ once.)
If ``exclusive`` is specified as second argument, all sections below the
newly enabled section are disabled. They will be re-enabled as soon as
- all exclusive above them are removed.
+ all exclusive sections above them are removed.
-disable_section "<section>"
+``disable_section "<section>"``
Disable the named input section. Undoes ``enable_section``.
-Undocumented commands: 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),
-stop (questionable use), get_property (?), af_cmdline, vo_cmdline (experimental).
+Undocumented commands: ``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), ``stop`` (questionable use), ``get_property``
+(?), ``af_cmdline``, ``vo_cmdline`` (experimental).
Input Command Prefixes
----------------------
-osd-auto (default)
+``osd-auto`` (default)
Use the default behavior for this command.
-no-osd
+``no-osd``
Do not use any OSD for this command.
-osd-bar
+``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
+``osd-msg``
If possible, show an OSD message with this command. Seek command show
the current playback time, property changing commands show the newly set
value as text.
-osd-msg-bar
+``osd-msg-bar``
Combine osd-bar and osd-msg.
-raw
- Don't expand properties in string arguments. (Like ``"${property-name}"``.)
-expand-properties (default)
- All string arguments are expanded as described in property_expansion_.
+``raw``
+ Do not expand properties in string arguments. (Like ``"${property-name}"``.)
+``expand-properties`` (default)
+ All string arguments are expanded as described in `Property Expansion`_.
All of the osd prefixes are still overridden by the global ``--osd-level``
settings.
-Undocumented prefixes: pausing, pausing_keep, pausing_toggle,
-pausing_keep_force. (Should these be made official?)
+Undocumented prefixes: ``pausing``, ``pausing_keep``, ``pausing_toggle``,
+``pausing_keep_force``. (Should these be made official?)
Input Sections
--------------
@@ -337,10 +341,10 @@ Also see ``enable_section`` and ``disable_section`` commands.
Predefined bindings:
-default
+``default``
Bindings without input section are implicitly assigned to this section. It
is enabled by default during normal playback.
-encode
+``encode``
Section which is active in encoding mode. It is enabled exclusively, so
that bindings in the ``default`` sections are ignored.
@@ -350,108 +354,106 @@ 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 property_expansion_.)
+expansion. (See `Property Expansion`_.)
-The ``W`` column indicates whether the property is generally writeable. If an
+The ``W`` column indicates whether the property is generally writable. 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``
-osd-scale x osd font size multiplicator, see ``--osd-scale``
-loop x see ``--loop``
-speed x see ``--speed``
-filename currently played file (path stripped)
-path currently played file (full path)
-media-title filename or libquvi QUVIPROP_PAGETITLE
-demuxer
-stream-path filename (full path) of stream layer filename
-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
-avsync last A/V synchronization difference
-percent-pos x position in current file (0-100)
-ratio-pos x position in current file (0.0-1.0)
-time-pos x position in current file in seconds
-time-remaining estimated remaining length of the 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 x current DVD angle
-metadata metadata key/value pairs
-metadata/<key> value of metadata entry <key>
-pause x pause status (bool)
-cache network cache fill state (0-100)
-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 (string)
-audio-codec audio codec selected for decoding
-audio-bitrate audio bitrate
-samplerate audio samplerate
-channels number of audio channels
-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)
-colormatrix x see ``--colormatrix``
-colormatrix-input-range x see ``--colormatrix-input-range``
-colormatrix-output-range x see ``--colormatrix-output-range``
-ontop x see ``--ontop``
-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``
-video-format video format (string)
-video-codec video codec selected for decoding
-video-bitrate video bitrate
-width video width (container or decoded size)
-height video height
-fps container FPS (may contain bogus values)
-dwidth video width (after filters and aspect scaling)
-dheight video height
-aspect x video aspect
-vid x current video track (similar to ``--vid``)
-video x alias for ``vid``
-program x switch TS program (write-only)
-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
-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``
-ass-style-override x see ``--ass-style-override``
-stream-capture x a filename, see ``--capture``
-tv-brightness x
-tv-contrast x
-tv-saturation x
-tv-hue x
-playlist-pos current position on playlist
-playlist-count number of total playlist entries
-playlist playlist, current entry marked
-track-list list of audio/video/sub tracks, cur. entr. marked
-chapter-list list of chapters, current entry marked
-quvi-format x see ``--quvi-format``
-=========================== = ==================================================
-
-.. _property_expansion:
+=============================== = ==================================================
+Name W Comment
+=============================== = ==================================================
+``osd-level`` x see ``--osd-level``
+``osd-scale`` x osd font size multiplicator, see ``--osd-scale``
+``loop`` x see ``--loop``
+``speed`` x see ``--speed``
+``filename`` currently played file (path stripped)
+``path`` currently played file (full path)
+``media-title`` filename or libquvi ``QUVIPROP_PAGETITLE``
+``demuxer``
+``stream-path`` filename (full path) of stream layer filename
+``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
+``avsync`` last A/V synchronization difference
+``percent-pos`` x position in current file (0-100)
+``ratio-pos`` x position in current file (0.0-1.0)
+``time-pos`` x position in current file in seconds
+``time-remaining`` estimated remaining length of the 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`` x current DVD angle
+``metadata`` metadata key/value pairs
+``metadata/<key>`` value of metadata entry ``<key>``
+``pause`` x pause status (bool)
+``cache`` network cache fill state (0-100)
+``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 (string)
+``audio-codec`` audio codec selected for decoding
+``audio-bitrate`` audio bitrate
+``samplerate`` audio samplerate
+``channels`` number of audio channels
+``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)
+``colormatrix`` x see ``--colormatrix``
+``colormatrix-input-range`` x see ``--colormatrix-input-range``
+``colormatrix-output-range`` x see ``--colormatrix-output-range``
+``ontop`` x see ``--ontop``
+``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``
+``video-format`` video format (string)
+``video-codec`` video codec selected for decoding
+``video-bitrate`` video bitrate
+``width`` video width (container or decoded size)
+``height`` video height
+``fps`` container FPS (may contain bogus values)
+``dwidth`` video width (after filters and aspect scaling)
+``dheight`` video height
+``aspect`` x video aspect
+``vid`` x current video track (similar to ``--vid``)
+``video`` x alias for ``vid``
+``program`` x switch TS program (write-only)
+``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
+``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``
+``ass-style-override`` x see ``--ass-style-override``
+``stream-capture`` x a filename, see ``--capture``
+``tv-brightness`` x
+``tv-contrast`` x
+``tv-saturation`` x
+``tv-hue`` x
+``playlist-pos`` current position on playlist
+``playlist-count`` number of total playlist entries
+``playlist`` playlist, current entry marked
+``track-list`` list of audio/video/sub tracks, cur. entr. marked
+``chapter-list`` list of chapters, current entry marked
+``quvi-format`` x see ``--quvi-format``
+=============================== = ==================================================
Property Expansion
------------------
@@ -459,63 +461,63 @@ 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*:
+.. admonition:: Example for input.conf
-- ``i show_text "Filename: ${filename}"`` shows the filename of the current file
- when pressing the ``i`` key
+ ``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}
+``${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}
+``${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
+ property cannot be retrieved. ``STR`` is expanded recursively.
+``${!NAME:STR}``
+ Expands to ``STR`` (recursively) if the property ``NAME`` cannot be
retrieved.
-\${?NAME:STR}
+``${?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 ``\``
+ - ``\n`` becomes a newline character
+ - ``\\`` expands to ``\``
Raw and Formatted Properties
----------------------------
-Normally, properties are formatted as human readable text, meant to be
+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
+can be parsed by other programs and follow the same conventions as the options
associated with the properties.
-*EXAMPLE*:
+.. admonition:: Examples
-- ``${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)
+ - ``${time-pos}`` expands to ``00:14:23`` (if playback position is at 14
+ minutes 23 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.
+it is the other way around, e.g. ``aid`` shows track title and language in the
+formatted case, but only the track number if it is raw.