mpv Documentation

meson setup build
meson compile -C build
meson install -C build

mkdir -p subprojects
git clone https://code.videolan.org/videolan/libplacebo.git --depth=1 --recursive subprojects/libplacebo

This is an object settings list option. See `List Options`_ for details.

To get a full list of available audio filters, see ``--af=help``.

Also, keep in mind that most actual filters are available via the ``lavfi``
wrapper, which gives you access to most of libavfilter's filters. This
includes all filters that have been ported from MPlayer to libavfilter.

The ``--vf`` description describes how libavfilter can be used and how to
workaround deprecated mpv filters.

``tospdif=<yes|no>``
    Output raw AC-3 stream if ``no``, output to S/PDIF for
    pass-through if ``yes`` (default).

``bitrate=<rate>``
    The bitrate use for the AC-3 stream. Set it to 384 to get 384 kbps.

    The default is 640. Some receivers might not be able to handle this.

    Valid values: 32, 40, 48, 56, 64, 80, 96, 112, 128,
    160, 192, 224, 256, 320, 384, 448, 512, 576, 640.

    The special value ``auto`` selects a default bitrate based on the
    input channel number:

    :1ch: 96
    :2ch: 192
    :3ch: 224
    :4ch: 384
    :5ch: 448
    :6ch: 448

``minch=<n>``
    If the input channel number is less than ``<minch>``, the filter will
    detach itself (default: 3).

``encoder=<name>``
    Select the libavcodec encoder used. Currently, this should be an AC-3
    encoder, and using another codec will fail horribly.

All parameters are optional. The first 3 parameters restrict what the filter
accepts as input. They will therefore cause conversion filters to be
inserted before this one.  The ``out-`` parameters tell the filters or audio
outputs following this filter how to interpret the data without actually
doing a conversion. Setting these will probably just break things unless you
really know you want this for some reason, such as testing or dealing with
broken media.

``<format>``
    Force conversion to this format. Use ``--af=format=format=help`` to get
    a list of valid formats.

``<srate>``
    Force conversion to a specific sample rate. The rate is an integer,
    48000 for example.

``<channels>``
    Force mixing to a specific channel layout. See ``--audio-channels`` option
    for possible values.

``<out-srate>``

``<out-channels>``

*NOTE*: this filter used to be named ``force``. The old ``format`` filter
used to do conversion itself, unlike this one which lets the filter system
handle the conversion.

This works by playing 'stride' ms of audio at normal speed then consuming
'stride*scale' ms of input audio. It pieces the strides together by
blending 'overlap'% of stride with audio following the previous stride. It
optionally performs a short statistical analysis on the next 'search' ms
of audio to determine the best overlap position.

``scale=<amount>``
    Nominal amount to scale tempo. Scales this amount in addition to
    speed. (default: 1.0)
``stride=<amount>``
    Length in milliseconds to output each stride. Too high of a value will
    cause noticeable skips at high scale amounts and an echo at low scale
    amounts. Very low values will alter pitch. Increasing improves
    performance. (default: 60)
``overlap=<factor>``
    Factor of stride to overlap. Decreasing improves performance.
    (default: .20)
``search=<amount>``
    Length in milliseconds to search for best overlap position. Decreasing
    improves performance greatly. On slow systems, you will probably want
    to set this very low. (default: 14)
``speed=<tempo|pitch|both|none>``
    Set response to speed change.

    tempo
         Scale tempo in sync with speed (default).
    pitch
         Reverses effect of filter. Scales pitch without altering tempo.
         Add this to your ``input.conf`` to step by musical semi-tones::

            [ multiply speed 0.9438743126816935
            ] multiply speed 1.059463094352953

         .. warning::

            Loses sync with video.
    both
        Scale both tempo and pitch.
    none
        Ignore speed changes.

.. admonition:: Examples

    ``mpv --af=scaletempo --speed=1.2 media.ogg``
        Would play media at 1.2x normal speed, with audio at normal
        pitch. Changing playback speed would change audio tempo to match.

    ``mpv --af=scaletempo=scale=1.2:speed=none --speed=1.2 media.ogg``
        Would play media at 1.2x normal speed, with audio at normal
        pitch, but changing playback speed would have no effect on audio
        tempo.

    ``mpv --af=scaletempo=stride=30:overlap=.50:search=10 media.ogg``
        Would tweak the quality and performance parameters.

    ``mpv --af=scaletempo=scale=1.2:speed=pitch audio.ogg``
        Would play media at 1.2x normal speed, with audio at normal pitch.
        Changing playback speed would change pitch, leaving audio tempo at
        1.2x.

By default, the ``search-interval`` and ``window-size`` parameters
have the same values as in chromium.

``min-speed=<speed>``
    Mute audio if the playback speed is below ``<speed>``. (default: 0.25)

``max-speed=<speed>``
    Mute audio if the playback speed is above ``<speed>``
    and ``<speed> != 0``. (default: 8.0)

``search-interval=<amount>``
    Length in milliseconds to search for best overlap position. (default: 40)

``window-size=<amount>``
    Length in milliseconds of the overlap-and-add window. (default: 12)

If ``ascale`` (Librempeg only) is not available in the loaded
libavfilter, ``atempo`` will be used as a fall-back.

This can be used in place of ``scaletempo`` and ``scaletempo2``.


.. admonition:: Examples

    ``mpv --af=lavfi-tempo --speed=1.2 media.ogg``
        Would play media at 1.2x normal speed at normal pitch with tempo
        scaled by the ``atempo`` filter from lavfi.

    ``mpv --af=lavfi-tempo=atempo --speed=1.2 media.ogg``
        Same as above.

    ``mpv --af=lavfi-tempo=filter=atempo --speed=1.2 media.ogg``
        Same as above.

    ``mpv --af=lavfi-tempo=ascale --speed=1.2 media.ogg``
        Would play media at 1.2x normal speed at normal pitch with tempo
        scaled by the ``ascale`` filter from lavfi, unless the filter is
        not available, then ``atempo`` will be used as a fall-back.

    ``mpv --af=lavfi-tempo=filter=ascale --speed=1.2 media.ogg``
        Same as above.

``pitch-scale=<amount>``
    Sets the pitch scaling factor. Frequencies are multiplied by this value.
    (default: 1.0)

``engine=<faster|finer>``
    Select the core Rubberband engine to be used. There are two available:

    :Faster: This is the Rubberband R2 engine. It uses significantly less
             CPU than the Finer (R3) engine.
    :Finer: This is the Rubberband R3 engine. This engine is only available
            with librubberband version 3 or newer. This produces significantly
            higher quality output, at the cost of higher CPU usage. (Default
            if available)

This filter has a number of additional sub-options. You can list them with
``mpv --af=rubberband=help``. This will also show the default values
for each option. The options are not documented here, because they are
merely passed to librubberband. Look at the librubberband documentation
to learn what each option does:
https://breakfastquay.com/rubberband/code-doc/classRubberBand_1_1RubberBandStretcher.html
Do note that certain options are only applicable to one of R2 (faster) and
R3 (finer) engines.
(The mapping of the mpv rubberband filter sub-option names and values to
those of librubberband follows a simple pattern: ``"Option" + Name + Value``.)

This filter supports the following ``af-command`` commands:

``set-pitch``
    Set the ```` argument dynamically. This can be used to
    change the playback pitch at runtime. Note that speed is controlled
    using the standard ``speed`` property, not ``af-command``.

``multiply-pitch <factor>``
    Multiply the current value of ```` dynamically.

``<graph>``
    Libavfilter graph. See ``lavfi`` video filter for details - the graph
    syntax is the same.

    .. warning::

        Don't forget to quote libavfilter graphs as described in the lavfi
        video filter section.

``o=<string>``
    AVOptions.

``fix-pts=<yes|no>``
    Determine PTS based on sample count (default: no). If this is enabled,
    the player won't rely on libavfilter passing through PTS accurately.
    Instead, it pass a sample count as PTS to libavfilter, and compute the
    PTS used by mpv based on that and the input PTS. This helps with filters
    which output a recomputed PTS instead of the original PTS (including
    filters which require the PTS to start at 0). mpv normally expects
    filters to not touch the PTS (or only to the extent of changing frame
    boundaries), so this is not the default, but it will be needed to use
    broken filters. In practice, these broken filters will either cause slow
    A/V desync over time (with some files), or break playback completely if
    you seek or start playback from the middle of a file.

See ``--ao=help`` for a list of compiled-in audio output drivers sorted by
autoprobe order.

Note that the default audio output driver is subject to change, and must
not be relied upon. If a certain AO needs to be used, it must be
explicitly specified.

The following global options are supported by this audio output:

``--alsa-resample=yes``
    Enable ALSA resampling plugin. (This is disabled by default, because
    some drivers report incorrect audio delay in some cases.)

``--alsa-mixer-device=<device>``
    Set the mixer device used with ``ao-volume`` (default: ``default``).

``--alsa-mixer-name=<name>``
    Set the name of the mixer element (default: ``Master``). This is for
    example ``PCM`` or ``Master``.

``--alsa-mixer-index=<number>``
    Set the index of the mixer channel (default: 0). Consider the output of
    "``amixer scontrols``", then the index is the number that follows the
    name of the element.

``--alsa-non-interleaved``
    Allow output of non-interleaved formats (if the audio decoder uses
    this format). Currently disabled by default, because some popular
    ALSA plugins are utterly broken with non-interleaved formats.

``--alsa-ignore-chmap``
    Don't read or set the channel map of the ALSA device - only request the
    required number of channels, and then pass the audio as-is to it. This
    option most likely should not be used. It can be useful for debugging,
    or for static setups with a specially engineered ALSA configuration (in
    this case you should always force the same layout with ``--audio-channels``,
    or it will work only for files which use the layout implicit to your
    ALSA device).

``--alsa-buffer-time=<microseconds>``
    Set the requested buffer time in microseconds. A value of 0 skips requesting
    anything from the ALSA API. This and the ``--alsa-periods`` option uses the
    ALSA ``near`` functions to set the requested parameters. If doing so results
    in an empty configuration set, setting these parameters is skipped.

    Both options control the buffer size. A low buffer size can lead to higher
    CPU usage and audio dropouts, while a high buffer size can lead to higher
    latency in volume changes and other filtering.

``--alsa-periods=<number>``
    Number of periods requested from the ALSA API. See ``--alsa-buffer-time``
    for further remarks.

.. warning::

    To get multichannel/surround audio, use ``--audio-channels=auto``. The
    default for this option is ``auto-safe``, which makes this audio output
    explicitly reject multichannel output, as there is no way to detect
    whether a certain channel layout is actually supported.

    You can also try `using the upmix plugin
    <https://github.com/mpv-player/mpv/wiki/ALSA-Surround-Sound-and-Upmixing>`_.
    This setup enables multichannel audio on the ``default`` device
    with automatic upmixing with shared access, so playing stereo
    and multichannel audio at the same time will work as expected.

The following global options are supported by this audio output:

``--jack-port=<name>``
    Connects to the ports with the given name (default: physical ports).
``--jack-name=<client>``
    Client name that is passed to JACK (default: ``mpv``). Useful
    if you want to have certain connections established automatically.
``--jack-autostart=<yes|no>``
    Automatically start jackd if necessary (default: disabled). Note that
    this tends to be unreliable and will flood stdout with server messages.
``--jack-connect=<yes|no>``
    Automatically create connections to output ports (default: enabled).
    When enabled, the maximum number of output channels will be limited to
    the number of available output ports.
``--jack-std-channel-layout=<waveext|any>``
    Select the standard channel layout (default: waveext). JACK itself has no
    notion of channel layouts (i.e. assigning which speaker a given
    channel is supposed to map to) - it just takes whatever the application
    outputs, and reroutes it to whatever the user defines. This means the
    user and the application are in charge of dealing with the channel
    layout. ``waveext`` uses WAVE_FORMAT_EXTENSIBLE order, which, even
    though it was defined by Microsoft, is the standard on many systems.
    The value ``any`` makes JACK accept whatever comes from the audio
    filter chain, regardless of channel layout and without reordering. This
    mode is probably not very useful, other than for debugging or when used
    with fixed setups.

Automatically redirects to ``coreaudio_exclusive`` when playing compressed
formats.

The following global options are supported by this audio output:

``--coreaudio-change-physical-format=<yes|no>``
    Change the physical format to one similar to the requested audio format
    (default: no). This has the advantage that multichannel audio output
    will actually work. The disadvantage is that it will change the
    system-wide audio settings. This is equivalent to changing the ``Format``
    setting in the ``Audio Devices`` dialog in the ``Audio MIDI Setup``
    utility. Note that this does not affect the selected speaker setup.

``--coreaudio-spdif-hack=<yes|no>``
    Try to pass through AC3/DTS data as PCM. This is useful for drivers
    which do not report AC3 support. It converts the AC3 data to float,
    and assumes the driver will do the inverse conversion, which means
    a typical A/V receiver will pick it up as compressed IEC framed AC3
    stream, ignoring that it's marked as PCM. This disables normal AC3
    passthrough (even if the device reports it as supported). Use with
    extreme care.

.. warning::

    Turning on spatial audio may hang the playback
    if mpv is not started out of the bundle,
    though playback with spatial audio off always works.

``--openal-num-buffers=<2-128>``
    Specify the number of audio buffers to use. Lower values are better for
    lower CPU usage. Default: 4.

``--openal-num-samples=<256-32768>``
    Specify the number of complete samples to use for each buffer. Higher
    values are better for lower CPU usage. Default: 8192.

``--openal-direct-channels=<yes|no>``
    Enable OpenAL Soft's direct channel extension when available to avoid
    tinting the sound with ambisonics or HRTF. Default: yes.

The following global options are supported by this audio output:

``--pulse-host=<host>``
    Specify the host to use. An empty <host> string uses a local connection,
    "localhost" uses network transfer (most likely not what you want).

``--pulse-buffer=<1-2000|native>``
    Set the audio buffer size in milliseconds. A higher value buffers
    more data, and has a lower probability of buffer underruns. A smaller
    value makes the audio stream react faster, e.g. to playback speed
    changes. "native" lets the sound server determine buffers.

``--pulse-latency-hacks=<yes|no>``
    Enable hacks to workaround PulseAudio timing bugs (default: yes). If
    enabled, mpv will do elaborate latency calculations on its own. If
    disabled, it will use PulseAudio automatically updated timing
    information. Disabling this might help with e.g. networked audio or
    some plugins, while enabling it might help in some unknown situations
    (it is currently enabled due to known bugs with PulseAudio 16.0).

``--pulse-allow-suspended=<yes|no>``
    Allow mpv to use PulseAudio even if the sink is suspended (default: no).
    Can be useful if PulseAudio is running as a bridge to jack and mpv has its sink-input set to the one jack is using.

The following global options are supported by this audio output:

``--pipewire-buffer=<1-2000|native>``
    Set the audio buffer size in milliseconds. A higher value buffers
    more data, and has a lower probability of buffer underruns. A smaller
    value makes the audio stream react faster, e.g. to playback speed
    changes. "native" lets the sound server determine buffers.

``--pipewire-remote=<remote>``
    Specify the PipeWire remote daemon name to connect to via local UNIX
    sockets.
    An empty <remote> string uses the default remote named ``pipewire-0``.

``--pipewire-volume-mode=<channel|global>``
    Specify if the ``ao-volume`` property should apply to the channel
    volumes or the global volume.
    By default the channel volumes are used.

.. note:: This driver is for compatibility with extremely foreign
          environments, such as systems where none of the other drivers
          are available.

The following global options are supported by this audio output:

``--sdl-buflen=<length>``
    Sets the audio buffer length in seconds. Is used only as a hint by the
    sound system. Playing a file with ``-v`` will show the requested and
    obtained exact buffer size. A value of 0 selects the sound system
    default.

The following global options are supported by this audio output:

``--ao-null-untimed``
    Do not simulate timing of a perfect audio device. This means audio
    decoding will go as fast as possible, instead of timing it to the
    system clock.

``--ao-null-buffer``
    Simulated buffer length in seconds.

``--ao-null-outburst``
    Simulated chunk size in samples.

``--ao-null-speed``
    Simulated audio playback speed as a multiplier. Usually, a real audio
    device will not go exactly as fast as the system clock. It will deviate
    just a little, and this option helps to simulate this.

``--ao-null-latency``
    Simulated device latency. This is additional to EOF.

``--ao-null-broken-eof``
    Simulate broken audio drivers, which always add the fixed device
    latency to the reported audio playback position.

``--ao-null-broken-delay``
    Simulate broken audio drivers, which don't report latency correctly.

``--ao-null-channel-layouts``
    If not empty, this is a ``,`` separated list of channel layouts the
    AO allows. This can be used to test channel layout selection.

``--ao-null-format``
    Force the audio output format the AO will accept. If unset accepts any.

The following global options are supported by this audio output:

``--ao-pcm-waveheader=<yes|no>``
    Include or do not include the WAVE header (default: included). When
    not included, raw PCM will be generated.
``--ao-pcm-file=<filename>``
    Write the sound to ``<filename>`` instead of the default
    ``audiodump.wav``. If ``no-waveheader`` is specified, the default is
    ``audiodump.pcm``.
``--ao-pcm-append=<yes|no>``
    Append to the file, instead of overwriting it. Always use this with the
    ``no-waveheader`` option - with ``waveheader`` it's broken, because
    it will write a WAVE header every time the file is opened.

(Note: only supports mono, stereo, 4.0, 5.1 and 7.1 channel
layouts.)

The following global options are supported by this audio output:

``--wasapi-exclusive-buffer=<default|min|1-2000000>``
    Set buffer duration in exclusive mode (i.e., with
    ``--audio-exclusive=yes``). ``default`` and ``min`` use the default and
    minimum device period reported by WASAPI, respectively. You can also
    directly specify the buffer duration in microseconds, in which case a
    duration shorter than the minimum device period will be rounded up to
    the minimum period.

    The default buffer duration should provide robust playback in most
    cases, but reportedly on some devices there are glitches following
    stream resets under the default setting. In such cases, specifying a
    shorter duration might help.

Open the console to enter commands.

.. admonition:: Examples for input.conf

    ``% script-message-to commands type "seek  absolute-percent" 6``
        Enter a percent position to seek to.

    ``Ctrl+o script-message-to commands type "loadfile ''" 11``
        Enter a file or URL to play, with autocompletion of paths in the
        filesystem.

``persist_history``
    Default: no

    Whether to save the command history to a file and load it.

``history_path``
    Default: ``~~state/command_history.txt``

    The file path for ``persist_history`` (see `FILES`_).

``remember_input``
    Default: yes

    Whether to remember the input line and cursor position when closing the
    console, and prefill it the next time it is opened.

---

## File: DOCS/man/console.rst

CONSOLE
=======

This script provides the ability to process the user's textual input to other
scripts through the ``mp.input`` API. It can be displayed on both the video
window and the terminal. It can be disabled entirely using the
``--load-console=no`` option.

Console can either process free-form text or select from a predefined list of
items.

Free-form text mode keybindings
-------------------------------

ESC and Ctrl+[
    Hide the console.

ENTER, Ctrl+j and Ctrl+m
    Select the first completion if one wasn't already manually selected, and run
    the typed command.

Shift+ENTER
    Type a literal newline character.

LEFT and Ctrl+b
    Move the cursor to the previous character.

RIGHT and Ctrl+f
    Move the cursor to the next character.

Ctrl+LEFT and Alt+b
    Move the cursor to the beginning of the current word, or if between words,
    to the beginning of the previous word.

Ctrl+RIGHT and Alt+f
    Move the cursor to the end of the current word, or if between words, to the
    end of the next word.

HOME and Ctrl+a
    Move the cursor to the start of the current line.

END and Ctrl+e
    Move the cursor to the end of the current line.

BACKSPACE and Ctrl+h
    Delete the previous character.

Ctrl+d
    Hide the console if the current line is empty, otherwise delete the next
    character.

Ctrl+BACKSPACE and Ctrl+w
    Delete text from the cursor to the beginning of the current word, or if
    between words, to the beginning of the previous word.

Ctrl+DEL and Alt+d
    Delete text from the cursor to the end of the current word, or if between
    words, to the end of the next word.

Ctrl+u
    Delete text from the cursor to the beginning of the current line.

Ctrl+k
    Delete text from the cursor to the end of the current line.

Ctrl+c
    Clear the current line.

UP and Ctrl+p
    Move back in the command history.

DOWN and Ctrl+n
    Move forward in the command history.

PGUP
    Go to the first command in the history.

PGDN
    Stop navigating the command history.

Ctrl+r
    Search the command history. See `SELECT`_ for the key bindings in this mode.

Shift+UP
    Scroll the log one line up.

Shift+DOWN
    Scroll the log one line down.

INSERT
    Toggle insert mode.

Ctrl+v
    Paste text (uses the clipboard on X11 and Wayland).

Shift+INSERT
    Paste text (uses the primary selection on X11 and Wayland).

Ctrl+y
    Copy the current line to the clipboard.

TAB and Ctrl+i
    Cycle through completions.

Shift+TAB
    Cycle through the completions backwards.

Ctrl+l
    Clear all log messages from the console.

MBTN_MID
    Paste text (uses the primary selection on X11 and Wayland).

WHEEL_UP
    Move back in the command history.

WHEEL_DOWN
    Move forward in the command history.

Known issues
------------

- Non-ASCII keyboard input has restrictions
- The cursor keys move between Unicode code-points, not grapheme clusters

Configuration
-------------

This script can be customized through a config file ``script-opts/console.conf``
placed in mpv's user directory and through the ``--script-opts`` command-line
option. The configuration syntax is described in `mp.options functions`_.

Note that ``mp.input`` clients can selectively override these options.

Configurable Options

The monospace font used when there are completions to align in a grid.

When there are no completions, ``--osd-font`` is used.

The font size. This will be multiplied by ``display-hidpi-scale`` when the
console is not scaled with the window.

The font border size.

The transparency of the menu's background. Ranges from 0 (opaque) to 255
(fully transparent).

The gap between menu items, specified as a percentage the font size.

The padding of the menu.

The size of the menu's border.

The color of the menu's border.

The radius of the menu's corners.

The margin from the left of the window.

The margin from the bottom of the window.

Whether to scale the console with the window height. Can be ``yes``, ``no``,
or ``auto``, which follows the value of ``--osd-scale-by-window``.

The color of the focused item.

The background color of the focused item.

The color of characters that match the searched string.

Whether to match menu search queries exactly instead of fuzzily. Without
this option, prefixing queries with ``'`` enables exact matching.

Whether exact searches are case sensitive. Only works with ASCII characters.

Remove duplicate entries in history as to only keep the latest one.

The ratio of font height to font width.
Adjusts grid width of completions.
Values in the range 1.8..2.5 make sense for common monospace fonts.

This is a key/value list option. See `List Options`_ for details.

``--ofopts-add=<option>``
    Appends the option given as an argument to the options list. (Passing
    multiple options is currently still possible, but deprecated.)

``--ofopts=""``
    Completely empties the options list.

.. admonition:: Example

    "``--oac=libmp3lame --oacopts=b=128000``"
        selects 128 kbps MP3 encoding.

This is a key/value list option. See `List Options`_ for details.

``--oacopts-add=<option>``
    Appends the option given as an argument to the options list. (Passing
    multiple options is currently still possible, but deprecated.)

``--oacopts=""``
    Completely empties the options list.

.. admonition:: Examples

    ``"--ovc=mpeg4 --ovcopts=qscale=5"``
        selects constant quantizer scale 5 for MPEG-4 encoding.

    ``"--ovc=libx264 --ovcopts=crf=23"``
        selects VBR quality factor 23 for H.264 encoding.

This is a key/value list option. See `List Options`_ for details.

``--ovcopts-add=<option>``
    Appends the option given as an argument to the options list. (Passing
    multiple options is currently still possible, but deprecated.)

``--ovcopts=""``
    Completely empties the options list.

This is a key/value list option. See `List Options`_ for details.

.. admonition:: Example

    "``--oset-metadata=title="Output title",comment="Another tag"``"
        adds a title and a comment to the output file.

This is a string list option. See `List Options`_ for details.

.. admonition:: Example

    "``--oremove-metadata=comment,genre``"
        excludes copying of the comment and genre tags to the output
        file.

s screenshot      # take a screenshot with the s key
LEFT seek 15      # map the left-arrow key to seeking forward by 15 seconds

https://github.com/mpv-player/mpv/blob/master/etc/input.conf

``mpv --input-keylist``

ctrl+q quit

mpv --input-test --force-window --idle

The ``Shift`` modifier requires some attention. In general, when the
``Shift`` modifier is combined with a key which produces text, the actual
produced text key name when shift is pressed should be used.

For instance, on the US keyboard layout, ``Shift+2`` should usually be
specified as key-name ``@`` at ``input.conf``, and similarly the
combination ``Alt+Shift+2`` is usually ``Alt+@``, etc.

In general, the ``Shift`` modifier, when specified with text key names,
is ignored: for instance, mpv interprets ``Shift+2`` as ``2``.
The only exceptions are ASCII letters, which are normalized by mpv.
For example, ``Shift+a`` is interpreted as ``A``.

Special key names like ``Shift+LEFT`` work as expected.
If in doubt - use ``--input-test`` to check how a key/combination is seen
by mpv.

Depending on backend, the mouse wheel might also be represented as a button.
In addition, ``MOUSE_BTN3`` to ``MOUSE_BTN6`` are deprecated aliases for
``WHEEL_UP``, ``WHEEL_DOWN``, ``WHEEL_LEFT``, ``WHEEL_RIGHT``.

``MBTN*`` are aliases for ``MOUSE_BTN*``.

These key are scalable when used with scalable commands if the underlying
device supports high-resolution scrolling (e.g. touch pads).

``seek <target> [<flags>]``
    Change the playback position. By default, seeks by a relative amount of
    seconds.

    The second argument consists of flags controlling the seek mode:

    relative (default)
        Seek relative to current position (a negative value seeks backwards).
    absolute
        Seek to a given time (a negative value starts from the end of the file).
    absolute-percent
        Seek to a given percent position.
    relative-percent
        Seek relative to current position in percent.
    keyframes
        Always restart playback at keyframe boundaries (fast).
    exact
        Always do exact/hr/precise seeks (slow).

    Multiple flags can be combined, e.g.: ``absolute+keyframes``.

    By default, ``keyframes`` is used for ``relative``, ``relative-percent``,
    and ``absolute-percent`` seeks, while ``exact`` is used for ``absolute``
    seeks.

    This is a scalable command. See the documentation of ``nonscalable`` input
    command prefix in `Input Command Prefixes`_ for details.

``revert-seek [<flags>]``
    Undoes the ``seek`` command, and some other commands that seek (but not
    necessarily all of them). Calling this command once will jump to the
    playback position before the seek. Calling it a second time undoes the
    ``revert-seek`` command itself. This only works within a single file.

    The first argument is optional, and can change the behavior:

    mark
        Mark the current time position. The next normal ``revert-seek`` command
        will seek back to this point, no matter how many seeks happened since
        last time.
    mark-permanent
        If set, mark the current position, and do not change the mark position
        before the next ``revert-seek`` command that has ``mark`` or
        ``mark-permanent`` set (or playback of the current file ends). Until
        this happens, ``revert-seek`` will always seek to the marked point. This
        flag cannot be combined with ``mark``.

    Using it without any arguments gives you the default behavior.

``sub-seek <skip> [<flags>]``
    Change video and audio position such that the subtitle event after
    ``<skip>`` subtitle events is displayed. For example, ``sub-seek 1`` skips
    to the next subtitle, ``sub-seek -1`` skips to the previous subtitles, and
    ``sub-seek 0`` seeks to the beginning of the current subtitle.

    This is similar to ``sub-step``, except that it seeks video and audio
    instead of adjusting the subtitle delay.

    Secondary argument:

    primary (default)
        Seeks through the primary subtitles.
    secondary
        Seeks through the secondary subtitles.

    For embedded subtitles (like with Matroska), this works only with subtitle
    events that have already been displayed, or are within a short prefetch
    range. See `Cache`_ for details on how to control the available prefetch range.


``frame-step [<frames>] [<flags>]``
    Go forward or backwards by a given amount of frames. If ``<frames>`` is
    omitted, the value is assumed to be ``1``.

    The second argument consists of flags controlling the frameskip mode:

    play (default)
        Play the video forward by the desired amount of frames and then pause.
        This only works with a positive value (i.e. frame stepping forwards).
    seek
        Perform a very exact seek that attempts to seek by the desired amount
        of frames. If ``<frames>`` is ``-1``, this will go exactly to the
        previous frame.
    mute
        The same as ``play`` but mutes the audio stream if there is any during
        the duration of the frame step.

    Note that the default frameskip mode, play, is more accurate but can be
    slow depending on how many frames you are skipping (i.e. skipping forward
    100 frames will play 100 frames of video before stopping). This mode only
    works when going forwards. Frame stepping back always performs a seek.

    When using seek mode, this can still 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. see the
    ``--hr-seek-demuxer-offset`` option). Video filters or other video
    post-processing that modifies timing of frames (e.g. deinterlacing) should
    usually work, but might make framestepping silently behave incorrectly in
    corner cases. Using ``--hr-seek-framedrop=no`` should help, although it
    might make precise seeking slower. Also if the video is VFR, framestepping
    using seeks will probably not work correctly except for the ``-1`` case.

    This does not work with audio-only playback.

``frame-back-step``
    Calls ``frame-step`` with a value of ``-1`` and the ``seek`` flag.

    This does not work with audio-only playback.

``stop [<flags>]``
    Stop playback and clear playlist. With default settings, this is
    essentially like ``quit``. Useful for the client API: playback can be
    stopped without terminating the player.

    The first argument is optional, and supports the following flags:

    keep-playlist
        Do not clear the playlist.

Property Manipulation

Whether or not key-repeat is enabled by default depends on the property.
Currently properties with continuous values are repeatable by default (like
``volume``), while discrete values are not (like ``osd-level``).

This is a scalable command. See the documentation of ``nonscalable`` input
command prefix in `Input Command Prefixes`_ for details.

Whether or not key-repeat is enabled by default depends on the property.
Currently properties with continuous values are repeatable by default (like
``volume``), while discrete values are not (like ``osd-level``).

This is a scalable command. See the documentation of ``nonscalable`` input
command prefix in `Input Command Prefixes`_ for details.

This command has a variable number of arguments, and cannot be used with
named arguments.

The special argument ``!reverse`` can be used to cycle the value list in
reverse. The only advantage is that you don't need to reverse the value
list yourself when adding a second key binding for cycling backwards.

Some operations take no value, but the command still requires the value
parameter. In these cases, the value must be an empty string.

.. admonition:: Example

    ``change-list glsl-shaders append file.glsl``

    Add a filename to the ``glsl-shaders`` list. The command line
    equivalent is ``--glsl-shaders-append=file.glsl`` or alternatively
    ``--glsl-shader=file.glsl``.

``playlist-next [<flags>]``
    Go to the next entry on the playlist.

    First argument:

    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 [<flags>]``
    Go to the previous entry on the playlist.

    First argument:

    weak (default)
        If the first file on the playlist is currently played, do nothing.
    force
        Terminate playback if the first file is being played.

``playlist-next-playlist``
    Go to the next entry on the playlist with a different ``playlist-path``.

``playlist-prev-playlist``
    Go to the first of the previous entries on the playlist with a different
    ``playlist-path``.

``playlist-play-index  [preserve-options]``]
    Start (or restart) playback of the given playlist index. In addition to the
    0-based playlist entry index, it supports the following values:

    <current>
        The current playlist entry (as in ``playlist-current-pos``) will be
        played again (unload and reload). If none is set, playback is stopped.
        (In corner cases, ``playlist-current-pos`` can point to a playlist entry
        even if playback is currently inactive,

    <none>
        Playback is stopped. If idle mode (``--idle``) is enabled, the player
        will enter idle mode, otherwise it will exit.

    Setting ``preserve-options`` (``MPV_FORMAT_FLAG``) will not reset file-local
    options when the playback of the current playlist index is restarted.

    This command is similar to ``loadfile`` in that it only manipulates the
    state of what to play next, without waiting until the current file is
    unloaded, and the next one is loaded.

    Setting ``playlist-pos`` or similar properties can have a similar effect to
    this command. However, it's more explicit, and guarantees that playback is
    restarted if for example the new playlist entry is the same as the previous
    one.

``loadfile  [<flags> [ [<options>]]]``
    Load the given file or URL and play it. Technically, this is just a playlist
    manipulation command (which either replaces the playlist or adds an entry
    to it). Actual file loading happens independently. For example, a
    ``loadfile`` command that replaces the current file with a new one returns
    before the current file is stopped, and the new file even begins loading.

    Second argument:

    <replace> (default)
        Stop playback of the current file, and play the new file immediately.
    <append>
        Append the file to the playlist.
    
        Insert the file into the playlist, directly after the current entry.
    
        Insert the file into the playlist, at the index given in the third
        argument.
    
        If nothing is currently playing, start playback. (Always starts with the
        added file, even if the playlist was not empty before running this
        command).

    Multiple flags can be combined, e.g.: ``append+play``.

    By default, ``append``, ``insert-next``, and ``insert-at`` will not
    immediately start playback even if the playlist was previously empty. Adding
    the ``play`` flag to them forces playback to start.

    The following values are considered deprecated and were the old way
    (before mpv 0.42) of forcing playback to start before the ``play`` flag was
    added.

    <append-play>
        Append the file, and if nothing is currently playing, start playback.
        (Always starts with the added file, even if the playlist was not empty
        before running this command.)
    
        Insert the file next, and if nothing is currently playing, start playback.
        (Always starts with the added file, even if the playlist was not empty
        before running this command.)
    
        Insert the file at the index given in the third argument, and if nothing
        is currently playing, start playback. (Always starts with the added
        file, even if the playlist was not empty before running this command.)

    The third argument is an insertion index, used only by the ``insert-at``
    action. When used with those actions, the new item will be inserted at the
    index position in the playlist, or appended to the end if index is less than
    0 or greater than the size of the playlist. This argument will be ignored for
    all other actions. This argument was added in mpv 0.38.0.

    The fourth argument is a list of options and values which should be set
    while the file is playing. It is of the form ``opt1=value1,opt2=value2,..``.
    When using the client API, this can be a ``MPV_FORMAT_NODE_MAP`` (or a Lua
    table), however the values themselves must be strings currently. These
    options are set during playback, and restored to the previous value at end
    of playback (see `Per-File Options`_).

    .. warning::

        Since mpv 0.38.0, an insertion index argument is added as the third argument.
        This breaks all existing uses of this command which make use of the argument
        to include the list of options to be set while the file is playing. To address
        this problem, the third argument now needs to be set to -1 if the fourth
        argument needs to be used.

``loadlist  [<flags> []]``
    Load the given playlist file or URL (like ``--playlist``).

    Second argument:

    <replace> (default)
        Stop playback and replace the internal playlist with the new one.
    <append>
        Append the new playlist at the end of the current internal playlist.
    
        Insert the new playlist into the current internal playlist, directly
        after the current entry.
    
        Insert the new playlist at the index given in the third argument.
    
        If nothing is currently playing, start playback. (Always starts with the
        added playlist, even if the internal playlist was not empty before running
        this command).

    Multiple flags can be combined, e.g.: ``append+play``.

    By default, ``append``, ``insert-next``, and ``insert-at`` will not
    immediately start playback even if the playlist was previously empty. Adding
    the ``play`` flag to them forces playback to start.

    The following values are considered deprecated and were the old way
    (before mpv 0.42) of forcing playback to start before the ``play`` flag was
    added.

    <append-play>
        Append the new playlist, and if nothing is currently playing, start
        playback. (Always starts with the new playlist, even if the internal
        playlist was not empty before running this command.)
    
        Insert the new playlist, and if nothing is currently playing, start
        playback. (Always starts with the new playlist, even if the internal
        playlist was not empty before running this command.)
    
        Insert the new playlist at the index given in the third argument, and if
        nothing is currently playing, start playback. (Always starts with the
        new playlist, even if the internal playlist was not empty before running
        this command.)

    The third argument is an insertion index, used only by the ``insert-at`` action.
    When used with those actions, the new playlist will be inserted at the index
    position in the internal playlist, or appended to the end if index is less
    than 0 or greater than the size of the internal playlist. This argument will be
    ignored for all other actions. This argument was added in mpv 0.38.0.

``playlist-clear``
    Clear the playlist, except the currently played file.

``playlist-remove ``
    Remove the playlist entry at the given index. Index values start counting
    with 0. The special value ``current`` removes the current entry. Note that
    removing the current entry also stops playback and starts playing the next
    entry.

``playlist-move  ``
    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.)

``playlist-shuffle``
    Shuffle the playlist. This is similar to what is done on start if the
    ``--shuffle`` option is used.

``playlist-unshuffle``
    Attempt to revert the previous ``playlist-shuffle`` command. This works
    only once (multiple successive ``playlist-unshuffle`` commands do nothing).
    May not work correctly if new recursive playlists have been opened since
    a ``playlist-shuffle`` command.

Track Manipulation
~~~~~~~~~~~~~~~~~~

``sub-add  [<flags> [<title> [<lang>]]]``
    Load the given subtitle file or stream. By default, it is selected as
    current subtitle  after loading.

    The ``flags`` argument is one of the following values:

    <select>

        Select the subtitle immediately (default).

    <auto>

        Don't select the subtitle. (Or in some special situations, let the
        default stream selection mechanism decide.)

    <cached>

        Select the subtitle. If a subtitle with the same filename was already
        added, that one is selected, instead of loading a duplicate entry.
        (In this case, title/language are ignored, and if the was changed since
        it was loaded, these changes won't be reflected.)

    Additionally the following flags can be added with a ``+``:

    <hearing-impaired>

        Marks the track as suitable for the hearing impaired.

    <visual-impaired>

        Marks the track as suitable for the visually impaired.

    <forced>

        Marks the track as forced.

    <default>

        Marks the track as default.

    <original>

        Marks the track as being in the original language.

    <commentary>

        Marks the track as containing commentary.

    <attached-picture> (only for ``video-add``)

        Marks the track as an attached picture, same as ``albumart`` argument
        for ```
/* Detailed source-code truncated for AI context efficiency. */
```` is omitted, only the position will be updated.

    Third argument:

    <single> (default)
        The mouse event represents regular single click.

    <double>
        The mouse event represents double-click.

``keypress <name> [<scale>]``
    Send a key event through mpv's input handler, triggering whatever
    behavior is configured to that key. ``name`` uses the ``input.conf``
    naming scheme for keys and modifiers. ``scale`` is used to scale numerical
    change effected by the bound command (same mechanism as precise scrolling).
    Useful for the client API: key events can be sent to libmpv to handle
    internally.

``keydown <name>``
    Similar to ``keypress``, but sets the ``KEYDOWN`` flag so that if the key is
    bound to a repeatable command, it will be run repeatedly with mpv's key
    repeat timing until the ``keyup`` command is called.

``keyup [<name>]``
    Set the ``KEYUP`` flag, stopping any repeated behavior that had been
    triggered. ``name`` is optional. If ``name`` is not given or is an
    empty string, ``KEYUP`` will be set on all keys. Otherwise, ``KEYUP`` will
    only be set on the key specified by ``name``.

``keybind <name> <cmd> [<comment>]``
    Binds a key to an input command. ``cmd`` must be a complete command
    containing all the desired arguments and flags. Both ``name`` and
    ``cmd`` use the ``input.conf`` naming scheme. ``comment`` is an optional
    string which can be read as the ``comment`` entry of ``input-bindings``.
    This is primarily useful for the client API.

``enable-section <name> [<flags>]``
    This command is deprecated, except for mpv-internal uses.

    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 is
    implicitly removed beforehand. (A section cannot be on the stack more than
    once.)

    The ``flags`` parameter can be a combination (separated by ``+``) of the
    following flags:

    <exclusive>
        All sections enabled before the newly enabled section are disabled.
        They will be re-enabled as soon as all exclusive sections above them
        are removed. In other words, the new section shadows all previous
        sections.
    <allow-hide-cursor>
        This feature can't be used through the public API.
    <allow-vo-dragging>
        Same.

``disable-section <name>``
    This command is deprecated, except for mpv-internal uses.

    Disable the named input section. Undoes ``enable-section``.

``define-section <name> <contents> [<flags>]``
    This command is deprecated, except for mpv-internal uses.

    Create a named input section, or replace the contents of an already existing
    input section. The ``contents`` parameter uses the same syntax as the
    ``input.conf`` file (except that using the section syntax in it is not
    allowed), including the need to separate bindings with a newline character.

    If the ``contents`` parameter is an empty string, the section is removed.

    The section with the name ``default`` is the normal input section.

    In general, input sections have to be enabled with the ``enable-section``
    command, or they are ignored.

    The last parameter has the following meaning:

    <default> (also used if parameter omitted)
        Use a key binding defined by this section only if the user hasn't
        already bound this key to a command.
    <force>
        Always bind a key. (The input section that was made active most recently
        wins if there are ambiguities.)

    This command can be used to dispatch arbitrary keys to a script or a client
    API user. If the input section defines ``script-binding`` commands, it is
    also possible to get separate events on key up/down, and relatively detailed
    information about the key state. The special key name ``unmapped`` can be
    used to match any unmapped key.

``load-input-conf <filename>``
    Load an input configuration file, similar to the ``--input-conf`` option. If
    the file was already included, its previous bindings are not reset before it
    is reparsed.

Execution Commands
~~~~~~~~~~~~~~~~~~

``run <command> [<arg1> [<arg2> [...]]]``
    Run the given command.

    This doesn't call the shell. Instead, the command is run directly, with each
    argument passed separately. Each argument is expanded like in `Property
    Expansion`_.

    This command has a variable number of arguments, and cannot be used with
    named arguments.

    The program is run in a detached way. mpv doesn't wait until the command
    is completed, but continues playback right after spawning it.

    To get the old behavior, use ``/bin/sh`` and ``-c`` as the first two
    arguments.

    .. admonition:: Example

        ``run "/bin/sh" "-c" "echo ${title} > /tmp/playing"``

        This is not a particularly good example, because it doesn't handle
        escaping, and a specially prepared file might allow an attacker to
        execute arbitrary shell commands. It is recommended to write a small
        shell script, and call that with ``run``.

``subprocess``
    Similar to ``run``, but gives more control about process execution to the
    caller, and does not detach the process.

    You can avoid blocking until the process terminates by running this command
    asynchronously. (For example ``mp.command_native_async()`` in Lua scripting.)

    This has the following named arguments. The order of them is not guaranteed,
    so you should always call them with named arguments, see `Named arguments`_.

    ``args`` (``MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING]``)
        Array of strings with the command as first argument, and subsequent
        command line arguments following. This is just like the ``run`` command
        argument list.

        The first array entry is either an absolute path to the executable, or
        a filename with no path components, in which case the executable is
        searched in the directories in the ``PATH`` environment variable. On
        Unix, this is equivalent to ``posix_spawnp`` and ``execvp`` behavior.

    ``playback_only`` (``MPV_FORMAT_FLAG``)
        Boolean indicating whether the process should be killed when playback
        of the current playlist entry terminates (optional, default: true). If
        enabled, stopping playback will automatically kill the process, and you
        can't start it outside of playback.

    ``capture_size`` (``MPV_FORMAT_INT64``)
        Integer setting the maximum number of stdout plus stderr bytes that can
        be captured (optional, default: 64MB). If the number of bytes exceeds
        this, capturing is stopped. The limit is per captured stream.

    ``capture_stdout`` (``MPV_FORMAT_FLAG``)
        Capture all data the process outputs to stdout and return it once the
        process ends (optional, default: no).

    ``capture_stderr`` (``MPV_FORMAT_FLAG``)
        Same as ``capture_stdout``, but for stderr.

    ``detach`` (``MPV_FORMAT_FLAG``)
        Whether to run the process in detached mode (optional, default: no). In
        this mode, the process is run in a new process session, and the command
        does not wait for the process to terminate. If neither
        ``capture_stdout`` nor ``capture_stderr`` have been set to true,
        the command returns immediately after the new process has been started,
        otherwise the command will read as long as the pipes are open.

    ``env`` (``MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING]``)
        Set a list of environment variables for the new process (default: empty).
        If an empty list is passed, the environment of the mpv process is used
        instead. (Unlike the underlying OS mechanisms, the mpv command cannot
        start a process with empty environment. Fortunately, that is completely
        useless.) The format of the list is as in the ``execle()`` syscall. Each
        string item defines an environment variable as in ``NAME=VALUE``.

        On Lua, you may use ``utils.get_env_list()`` to retrieve the current
        environment if you e.g. simply want to add a new variable.

    ``stdin_data`` (``MPV_FORMAT_STRING``)
        Feed the given string to the new process' stdin. Since this is a string,
        you cannot pass arbitrary binary data. If the process terminates or
        closes the pipe before all data is written, the remaining data is
        silently discarded. Probably does not work on win32.

    ``passthrough_stdin`` (``MPV_FORMAT_FLAG``)
        If enabled, wire the new process' stdin to mpv's stdin (default: no).

    The command returns the following result (as ``MPV_FORMAT_NODE_MAP``):

    ``status`` (``MPV_FORMAT_INT64``)
        Typically this is the process exit code (0 or positive) if the process
        terminates normally, or negative for other errors (failed to start,
        terminated by mpv, and others).  The meaning of negative values is
        undefined, other than meaning error (and does not correspond to OS low
        level exit status values).

        On Windows, it can happen that a negative return value is returned even
        if the process terminates normally, because the win32 ``UINT`` exit
        code is assigned to an ``int`` variable before being set as ``int64_t``
        field in the result map. This might be fixed later.

    ``stdout`` (``MPV_FORMAT_BYTE_ARRAY``)
        Captured stdout stream, limited to ``capture_size``.

    ``stderr`` (``MPV_FORMAT_BYTE_ARRAY``)
        Same as ``stdout``, but for stderr.

    ``error_string`` (``MPV_FORMAT_STRING``)
        Empty string if the process terminated normally. The string ``killed``
        if the process was terminated in an unusual way. The string ``init`` if
        the process could not be started.

        On Windows, ``killed`` is only returned when the process has been
        killed by mpv as a result of ``playback_only`` being set to true.

    ``killed_by_us`` (``MPV_FORMAT_FLAG``)
        Whether the process has been killed by mpv, for example as a result of
        ``playback_only`` being set to true, aborting the command (e.g. by
        ``mp.abort_async_command()``), or if the player is about to exit.

    Note that the command itself will always return success as long as the
    parameters are correct. Whether the process could be spawned or whether
    it was somehow killed or returned an error status has to be queried from
    the result value.

    This command can be asynchronously aborted via API. Also see `Asynchronous
    command details`_. Only the ``run`` command can start processes in a truly
    detached way.

    .. note:: The subprocess will always be terminated on player exit if it
              wasn't started in detached mode, even if ``playback_only`` is
              false.

    .. warning::

        Don't forget to set the ``playback_only`` field to false if you want
        the command to run while the player is in idle mode, or if you don't
        want the end of playback to kill the command.

    .. admonition:: Example

        ::

            local r = mp.command_native({
                _name = "subprocess",
                playback_only = false,
                capture_stdout = true,
                args = {"cat", "/proc/cpuinfo"},
            })
            if r.status == 0 then
                print("result: " .. r.stdout)
            end

        This is a fairly useless Lua example, which demonstrates how to run
        a process in a blocking manner, and retrieving its stdout output.

``quit [<code>]``
    Exit the player. If an argument is given, it's used as process exit code.

``quit-watch-later [<code>]``
    Exit player, and store current playback position. Playing that file later
    will seek to the previous position on start. The (optional) argument is
    exactly as in the ``quit`` command. See `RESUMING PLAYBACK`_.

Scripting Commands
~~~~~~~~~~~~~~~~~~

``script-message [<arg1> [<arg2> [...]]]``
    Send a message to all clients, and pass it the following list of arguments.
    What this message means, how many arguments it takes, and what the arguments
    mean is fully up to the receiver and the sender. Every client receives the
    message, so be careful about name clashes (or use ``script-message-to``).

    This command has a variable number of arguments, and cannot be used with
    named arguments.

``script-message-to <target> [<arg1> [<arg2> [...]]]``
    Same as ``script-message``, but send it only to the client named
    ``<target>``. Each client (scripts etc.) has a unique name. For example,
    Lua scripts can get their name via ``mp.get_script_name()``. Note that
    client names only consist of alphanumeric characters and ``_``.

    This command has a variable number of arguments, and cannot be used with
    named arguments.

``script-binding <name> [<arg>]``
    Invoke a script-provided key binding. This can be used to remap key
    bindings provided by external Lua scripts.

    ``<name>`` is the name of the binding. ``<arg>`` is a user-provided
    arbitrary string which can be used to provide extra information.

    It can optionally be prefixed with the name of the script, using ``/`` as
    separator, e.g. ``script-binding scriptname/bindingname``. Note that script
    names only consist of alphanumeric characters and ``_``.

    For completeness, here is how this command works internally. The details
    could change any time. On any matching key event, ``script-message-to``
    or ``script-message`` is called (depending on whether the script name is
    included), with the following arguments in string format:

    1. The string ``key-binding``.
    2. The name of the binding (as established above).
    3. The key state as string (see below).
    4. The key name.
    5. The text the key would produce, or empty string if not applicable.
    6. The scale of the key, such as the ones produced by ``WHEEL_*`` keys.
       The scale is 1 if the key is nonscalable.
    7. The user-provided string ``<arg>``, or empty string if the argument is
       not used.

    The 5th argument is only set if no modifiers are present (using the shift
    key with a letter is normally not emitted as having a modifier, and results
    in upper case text instead, but some backends may mess up).

    The key state consists of 3 characters:

    1. One of ``d`` (key was pressed down), ``u`` (was released), ``r`` (key
       is still down, and was repeated; only if key repeat is enabled for this
       binding), ``p`` (key was pressed; happens if up/down can't be tracked).
    2. Whether the event originates from the mouse, either ``m`` (mouse button)
       or ``-`` (something else).
    3. Whether the event results from a cancellation (e.g. the key is logically
       released but not physically released), either ``c`` (canceled) or ``-``
       (something else). Not all types of cancellations set this flag.

    Future versions can add more arguments and more key state characters to
    support more input peculiarities.

    This is a scalable command. See the documentation of ``nonscalable`` input
    command prefix in `Input Command Prefixes`_ for details.

``load-script <filename>``
    Load a script, similar to the ``--script`` option. Whether this waits for
    the script to finish initialization or not changed multiple times, and the
    future behavior is left undefined.

    On success, returns a ``mpv_node`` with a ``client_id`` field set to the
    return value of the ``mpv_client_id()`` API call of the newly created script
    handle.

    ::

        MPV_FORMAT_NODE_MAP
            "client_id"    MPV_FORMAT_STRING

Screenshot Commands
~~~~~~~~~~~~~~~~~~~

``screenshot [<flags>]``
    Take a screenshot.

    Multiple flags are available (some can be combined with ``+``):

    <video>
        Save the video image in its original resolution, without OSD or
        subtitles. This is the default when no flag is specified, and it does
        not need to be explicitly added when combined with other flags.
    <scaled>
        Save the video image in the current playback resolution.
    <subtitles> (default)
        Save the video image with subtitles.
        Some video outputs may still include the OSD in the output under certain
        circumstances.
    <osd>
        Save the video image with OSD.
    <window>
        Save the contents of the mpv window, with OSD and subtitles.
        This is an alias of ``scaled+subtitles+osd``.
    <each-frame>
        Take a screenshot each frame. Issue this command again to stop taking
        screenshots. Note that you should disable frame-dropping when using
        this mode - or you might receive duplicate images in cases when a
        frame was dropped. This flag can be combined with the other flags,
        e.g. ``video+each-frame``.

    The exact behaviors of all flags other than ``each-frame`` depend on the
    selected video output.

    Older mpv versions required passing ``single`` and ``each-frame`` as
    second argument (and did not have flags). This syntax is still understood,
    but deprecated and might be removed in the future.

    If you combine this command with another one using ``;``, you can use the
    ``async`` flag to make encoding/writing the image file asynchronous. For
    normal standalone commands, this is always asynchronous, and the flag has
    no effect.

    On success, returns a ``mpv_node`` with a ``filename`` field set to the
    saved screenshot location.

    ::

        MPV_FORMAT_NODE_MAP
            "filename"    MPV_FORMAT_STRING

``screenshot-to-file <filename> [<flags>]``
    Take a screenshot and save it to a given file. The format of the file will
    be guessed by the extension (and ``--screenshot-format`` is ignored - the
    behavior when the extension is missing or unknown is arbitrary).

    The second argument is like the first argument to ``screenshot`` and
    supports ``subtitles``, ``video``, ``window``.

    If the file already exists, it's overwritten.

    Like all input command parameters, the filename is subject to property
    expansion as described in `Property Expansion`_.

``screenshot-raw [<flags> [<format>]]``
    Return a screenshot in memory. This can be used only through the client API
    or from a script using ``mp.command_native``. The MPV_FORMAT_NODE_MAP
    returned by this command has the ``w``, ``h``, ``stride`` fields set to
    obvious contents.

    The ``format`` field is set to the format of the screenshot image data.
    This can be controlled by the ``format`` argument. The format can be one of
    the following:

    bgr0 (default)
        This format is organized as ``B8G8R8X8`` (where ``B`` is the LSB).
        The contents of the padding ``X`` are undefined.
    bgra
        This format is organized as ``B8G8R8A8`` (where ``B`` is the LSB).
    rgba
        This format is organized as ``R8G8B8A8`` (where ``R`` is the LSB).
    rgba64
        This format is organized as ``R16G16B16A16`` (where ``R`` is the LSB).
        Each component occupies 2 bytes per pixel.
        When this format is used, the image data will be high bit depth, and
        ``--screenshot-high-bit-depth`` is ignored.

    The ``data`` field is of type MPV_FORMAT_BYTE_ARRAY with the actual image
    data. The image is freed as soon as the result mpv_node is freed. As usual
    with client API semantics, you are not allowed to write to the image data.

    The ``stride`` is the number of bytes from a pixel at ``(x0, y0)`` to the
    pixel at ``(x0, y0 + 1)``. This can be larger than ``w * bpp`` if the image
    was cropped, or if there is padding. This number can be negative as well.
    You access a pixel with ``byte_index = y * stride + x * bpp``.
    Here, ``bpp`` is the number of bytes per pixel, which is 8 for ``rgba64``
    format and 4 for other formats.

    The ``flags`` argument is like the first argument to ``screenshot`` and
    supports ``subtitles``, ``video``, ``window``.

    ::

        MPV_FORMAT_NODE_MAP
            "w"         MPV_FORMAT_INT64
            "h"         MPV_FORMAT_INT64
            "stride"    MPV_FORMAT_INT64
            "format"    MPV_FORMAT_STRING
            "data"      MPV_FORMAT_BYTE_ARRAY

Filter Commands
~~~~~~~~~~~~~~~

``af <operation> <value>``
    Change audio filter chain. See ``vf`` command.

``vf <operation> <value>``
    Change video filter chain.

    The semantics are exactly the same as with option parsing (see
    `VIDEO FILTERS`_). As such the text below is a redundant and incomplete
    summary.

    The first argument decides what happens:

    <set>
        Overwrite the previous filter chain with the new one.

    <add>
        Append the new filter chain to the previous one.

    <toggle>
        Check if the given filter (with the exact parameters) is already in the
        video chain. If it is, remove the filter. If it isn't, add the filter.
        (If several filters are passed to the command, this is done for
        each filter.)

        A special variant is combining this with labels, and using ``@name``
        without filter name and parameters as filter entry. This toggles the
        enable/disable flag.

    <remove>
        Like ``toggle``, but always remove the given filter from the chain.

    <clr>
        Remove all filters. Note that like the other sub-commands, this does
        not control automatically inserted filters.

    The argument is always needed. E.g. in case of ``clr`` use ``vf clr ""``.

    You can assign labels to filter by prefixing them with ``@name:`` (where
    ``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.

    The ``vf`` command shows the list of requested filters on the OSD after
    changing the filter chain. This is roughly equivalent to
    ``show-text ${vf}``. Note that auto-inserted filters for format conversion
    are not shown on the list, only what was requested by the user.

    Normally, the commands will check whether the video chain is recreated
    successfully, and will undo the operation on failure. If the command is run
    before video is configured (can happen if the command is run immediately
    after opening a file and before a video frame is decoded), this check can't
    be run. Then it can happen that creating the video chain fails.

    .. admonition:: Example for input.conf

        - ``a vf set vflip`` turn the video upside-down on the ``a`` key
        - ``b vf set ""`` remove all video filters on ``b``
        - ``c vf toggle gradfun`` toggle debanding on ``c``

    .. admonition:: Example how to toggle disabled filters at runtime

        - Add something like ``vf-add=@deband:!gradfun`` to ``mpv.conf``.
          The ``@deband:`` is the label, an arbitrary, user-given name for this
          filter entry. The ``!`` before the filter name disables the filter by
          default. Everything after this is the normal filter name and possibly
          filter parameters, like in the normal ``--vf`` syntax.
        - Add ``a vf toggle @deband`` to ``input.conf``. This toggles the
          "disabled" flag for the filter with the label ``deband`` when the
          ``a`` key is hit.

``vf-command <label> <command> <argument> [<target>]``
    Send a command to the filter. Note that currently, this only works with
    the ``lavfi`` filter. Refer to the libavfilter documentation for the list
    of supported commands for each filter.

    ``<label>`` is a mpv filter label, use ``all`` to send it to all filters
    at once.

    ``<command>`` and ``<argument>`` are filter-specific strings.

    ``<target>`` is a filter or filter instance name and defaults to ``all``.
    Note that the target is an additional specifier for filters that
    support them, such as complex ``lavfi`` filter chains.

``af-command <label> <command> <argument> [<target>]``
    Same as ``vf-command``, but for audio filters.

Miscellaneous Commands

Dumping a larger part of the cache will freeze the player. No effort was
made to fix this, as this feature was meant mostly for creating small
excerpts.

See ``--stream-record`` for various caveats that mostly apply to this
command too, as both use the same underlying code for writing the output
file.

If ``<filename>`` is an empty string, an ongoing ``dump-cache`` is stopped.

If ``<end>`` is ``no``, then continuous dumping is enabled. Then, after
dumping the existing parts of the cache, anything read from network is
appended to the cache as well. This behaves similar to ``--stream-record``
(although it does not conflict with that option, and they can be both active
at the same time).

If the ``<end>`` time is after the cache, the command will _not_ wait and
write newly received data to it.

The end of the resulting file may be slightly damaged or incomplete at the
end. (Not enough effort was made to ensure that the end lines up properly.)

Note that this command will finish only once dumping ends. That means it
works similar to the ``screenshot`` command, just that it can block much
longer. If continuous dumping is used, the command will not finish until
playback is stopped, an error happens, another ``dump-cache`` command is
run, or an API like ``mp.abort_async_command`` was called to explicitly stop
the command. See `Synchronous vs. Asynchronous`_.

.. note::

    This was mostly created for network streams. For local files, there may
    be much better methods to create excerpts and such. There are tons of
    much more user-friendly Lua scripts, that will re-encode parts of a file
    by spawning a separate instance of ``ffmpeg``. With network streams,
    this is not that easily possible, as the stream would have to be
    downloaded again. Even if ``--stream-record`` is used to record the
    stream to the local filesystem, there may be problems, because the
    recorded file is still written to.

This command is experimental, and all details about it may change in the
future.

The author reserves the right to remove this command if enough motivation
is found to move this functionality to a trivial Lua script.

This command has an even more uncertain future than ``ab-loop-dump-cache``
and might disappear without replacement if the author decides it's useless.

This command returns as soon as the clipboard content is updated or the
timeout has reached. On some platforms, this command does nothing and
returns immediately.

This command can be asynchronously aborted via API. See `Asynchronous
command details`_.

This has the following fields:

``playlist_entry_id``
    Playlist entry ID of the file being loaded now.

The event has the following fields:

``reason``
    Has one of these values:

    ``eof``
        The file has ended. This can (but doesn't have to) include
        incomplete files or broken network connections under
        circumstances.

    ``stop``
        Playback was ended by a command.

    ``quit``
        Playback was ended by sending the quit command.

    ``error``
        An error happened.

    ``redirect``
        Happens with playlists and similar. Details see
        ``MPV_END_FILE_REASON_REDIRECT`` in the C API.

    ``unknown``
        Unknown. Normally doesn't happen, unless the Lua API is out of sync
        with the C API. (Likewise, it could happen that your script gets
        reason strings that did not exist yet at the time your script was
        written.)

``playlist_entry_id``
    Playlist entry ID of the file that was being played or attempted to be
    played. This has the same value as the ``playlist_entry_id`` field in the
    corresponding ``start-file`` event.

``file_error``
    Set to mpv error string describing the approximate reason why playback
    failed. Unset if no error known.

``playlist_insert_id``
    If loading ended, because the playlist entry to be played was for example
    a playlist, and the current playlist entry is replaced with a number of
    other entries. This may happen at least with MPV_END_FILE_REASON_REDIRECT
    (other event types may use this for similar but different purposes in the
    future). In this case, playlist_insert_id will be set to the playlist
    entry ID of the first inserted entry, and playlist_insert_num_entries to
    the total number of inserted playlist entries. Note this in this specific
    case, the ID of the last inserted entry is playlist_insert_id+num-1.
    Beware that depending on circumstances, you may observe the new playlist
    entries before seeing the event (e.g. reading the "playlist" property or
    getting a property change notification before receiving the event).
    If this is 0 in the C API, this field isn't added.

``playlist_insert_num_entries``
    See playlist_insert_id. Only present if playlist_insert_id is present.

This contains, in addition to the default event fields, the following
fields:

``prefix``
    The module prefix, identifies the sender of the message. This is what
    the terminal player puts in front of the message text when using the
    ``--v`` option, and is also what is used for ``--msg-level``.

``level``
    The log level as string. See ``msg.log`` for possible log level names.
    Note that later versions of mpv might add new levels or remove
    (undocumented) existing ones.

``text``
    The log message. The text will end with a newline character. Sometimes
    it can contain multiple lines.

Keep in mind that these messages are meant to be hints for humans. You
should not parse them, and prefix/level/text of messages might change
any time.

``hook_id``
    ID to pass to ``mpv_hook_continue()``. The Lua scripting wrapper
    provides a better API around this with ``mp.add_hook()``.

JSON IPC and Lua and possibly other backends treat this specially and may
not pass the actual event to the user. See C API.

The event has the following fields:

``result``
    The result (on success) of any ``mpv_node`` type, if any.

The event has the following fields:

``args``
    Array of strings with the message data.

The event has the following fields:

``name``
    The name of the property.

``data``
    The new value of the property.

Ordered after ``start-file`` and before ``playback-restart``.

Ordered after ``on_load``, and before ``playback-restart`` and ``end-file``.

Note that this does not yet apply default track selection. Which operations
exactly can be done and not be done, and what information is available and
what is not yet available yet, is all subject to change.

Ordered after ``on_load_fail`` etc. and before ``playback-restart``.

Ordered after ``on_preloaded``. and before ``playback-restart``.

Ordered before ``end-file``. Will also happen in the error case (then after
``on_load_fail``).

Most options can be set at runtime via properties as well. Just remove the
leading ``--`` from the option name. These are not documented below, see
`OPTIONS`_ instead. Only properties which do not exist as option with the
same name, or which have very different behavior from the options are
documented below.

Properties marked as (RW) are writeable, while those that aren't are
read-only.

OSD formatting will display it in the form of ``+1.23456%``, with the number
being ``(raw - 1) * 100`` for the given raw property value.

This has a sub-property:

``filename/no-ext``
    Like the ``filename`` property, but if the text contains a ``.``, strip
    all text after the last ``.``. Usually this removes the file extension.

.. note:: This is only an estimate. (It's computed from two unreliable
          quantities: fps and stream length.)

.. note:: This is only an estimate. (It's computed from two unreliable
          quantities: fps and possibly rounded timestamps.)

.. note:: On certain platforms (e.g Windows) environment variables are case
          insensitive and so ``${env/PATH}`` and ``${env/Path}`` will
          resolve to the same thing. However, the returned table will
          contain the variable name as is without any case-normalization.

Otherwise, return the ``filename`` property.

(Renamed from ``demuxer``.)

This has a sub-property:

``duration/full``
    ``duration`` with milliseconds.

This has a sub-property:

``time-pos/full``
    ``time-pos`` with milliseconds.

This has a sub-property:

``time-remaining/full``
    ``time-remaining`` with milliseconds.

This has a sub-property:

``audio-pts/full``
    ``audio-pts`` with milliseconds.

This has a sub-property:

``playtime-remaining/full``
    ``playtime-remaining`` with milliseconds.

Prior to mpv 0.39.0, ``time-pos`` and ``playback-time`` could report
different values in certain edge cases.

This has a sub-property:

``playback-time/full``
    ``playback-time`` with milliseconds.

Setting this property results in an absolute seek to the start of the
chapter. However, if the property is changed with ``add`` or ``cycle``
command which results in a decrement in value, it may go to the start of
the current chapter instead of the previous chapter.
See ``--chapter-seek-threshold`` for details.

For Matroska files, this is the edition. For DVD/Blu-ray, this is the title.
For MPEG-TS, HLS, and EDL streams, this maps to the underlying program/variant.

This strictly returns the user-set option or property value, and the
``current-edition`` property returns the runtime selected edition (this
matters with ``--edition=auto``, the default).

This has a number of sub-properties. Replace ``N`` with the 0-based edition
index.

``edition-list/count``
    Number of editions. If there are no editions, this can be 0 or 1 (1
    if there's a useless dummy edition).

``edition-list/N/id``
    Edition ID as integer. Currently, this is the same as the edition index.

``edition-list/N/default``
    Whether this is the default edition.

``edition-list/N/title``
    Edition title as stored in the file. Not always available.

``edition-list/N/metadata``
    Per-edition metadata key/value pairs.

When querying the property with the client API using ``MPV_FORMAT_NODE``,
or with Lua ``mp.get_property_native``, this will return a mpv_node with
the following contents:

::

    MPV_FORMAT_NODE_ARRAY
        MPV_FORMAT_NODE_MAP (for each edition)
            "id"                MPV_FORMAT_INT64
            "title"             MPV_FORMAT_STRING
            "default"           MPV_FORMAT_FLAG
            "metadata"          MPV_FORMAT_NODE_MAP

If the property is accessed with Lua's ``mp.get_property_native``, this
returns a table with metadata keys mapping to metadata values. If it is
accessed with the client API, this returns a ``MPV_FORMAT_NODE_MAP``,
with tag keys mapping to tag values.

For OSD, it returns a formatted list. Trying to retrieve this property as
a raw string doesn't work.

This has a number of sub-properties:

``metadata/by-key/<key>`` (RW)
    Value of metadata entry ``<key>``.

``metadata/list/count``
    Number of metadata entries.

``metadata/list/N/key``
    Key name of the Nth metadata entry. (The first entry is ``0``).

``metadata/list/N/value``
    Value of the Nth metadata entry.

``metadata/<key>``
    Old version of ``metadata/by-key/<key>``. Use is discouraged, because
    the metadata key string could conflict with other sub-properties.

The layout of this property might be subject to change. Suggestions are
welcome how exactly this property should work.

When querying the property with the client API using ``MPV_FORMAT_NODE``,
or with Lua ``mp.get_property_native``, this will return a mpv_node with
the following contents:

::

    MPV_FORMAT_NODE_MAP
        (key and string value for each metadata entry)

Per-chapter metadata is very rare. Usually, only the chapter name
(``title``) is set.

For accessing other information, like chapter start, see the
``chapter-list`` property.

Works similar to ``metadata`` property. It allows the same access
methods (using sub-properties).

An example of this kind of metadata are the cropping parameters
added by ``--vf=lavfi=cropdetect``.

(Renamed from ``idle``.)

This also returns ``yes``/true if playback is restarting or if nothing is
playing at all. In other words, it's only ``no``/false if there's actually
video playing.

This is the same as ``demuxer-cache-state/raw-input-rate``.

The end of a seek range is usually smaller than the value returned by the
``demuxer-cache-time`` property, because that property returns the guessed
buffering amount, while the seek ranges represent the buffered data that
can actually be used for cached seeking.

``bof-cached`` indicates whether the seek range with the lowest timestamp
points to the beginning of the stream (BOF). This implies you cannot seek
before this position at all. ``eof-cached`` indicates whether the seek range
with the highest timestamp points to the end of the stream (EOF). If both
``bof-cached`` and ``eof-cached`` are true, and there's only 1 cache range,
the entire stream is cached.

``fw-bytes`` is the number of bytes of packets buffered in the range
starting from the current decoding position. This is a rough estimate
(may not account correctly for various overhead), and stops at the
demuxer position (it ignores seek ranges after it).

``file-cache-bytes`` is the number of bytes stored in the file cache. This
includes all overhead, and possibly unused data (like pruned data). This
member is missing if the file cache wasn't enabled with
``--cache-on-disk=yes``.

``cache-end`` is ``demuxer-cache-time``. Missing if unavailable.

``reader-pts`` is the approximate timestamp of the start of the buffered
range. Missing if unavailable.

``cache-duration`` is ``demuxer-cache-duration``. Missing if unavailable.

``raw-input-rate`` is the estimated input rate of the network layer (or any
other byte-oriented input layer) in bytes per second. May be inaccurate or
missing.

``ts-per-stream`` is an array containing an entry for each stream type: video,
audio, and subtitle. For each stream type, the details for the demuxer cache
for that stream type are available as ``cache-duration``, ``reader-pts`` and
``cache-end``.

When querying the property with the client API using ``MPV_FORMAT_NODE``,
or with Lua ``mp.get_property_native``, this will return a mpv_node with
the following contents:

::

    MPV_FORMAT_NODE_MAP
        "seekable-ranges"   MPV_FORMAT_NODE_ARRAY
            MPV_FORMAT_NODE_MAP
                "start"           MPV_FORMAT_DOUBLE
                "end"             MPV_FORMAT_DOUBLE
        "bof-cached"        MPV_FORMAT_FLAG
        "eof-cached"        MPV_FORMAT_FLAG
        "fw-bytes"          MPV_FORMAT_INT64
        "file-cache-bytes"  MPV_FORMAT_INT64
        "cache-end"         MPV_FORMAT_DOUBLE
        "reader-pts"        MPV_FORMAT_DOUBLE
        "cache-duration"    MPV_FORMAT_DOUBLE
        "raw-input-rate"    MPV_FORMAT_INT64
        "ts-per-stream"     MPV_FORMAT_NODE_ARRAY
            MPV_FORMAT_NODE_MAP
                "type"            MPV_FORMAT_STRING
                "cache-duration"  MPV_FORMAT_DOUBLE
                "reader-pts"      MPV_FORMAT_DOUBLE
                "cache-end"       MPV_FORMAT_DOUBLE

Other fields (might be changed or removed in the future):

``eof``
    Whether the reader thread has hit the end of the file.

``underrun``
    Whether the reader thread could not satisfy a decoder's request for a
    new packet.

``idle``
    Whether the thread is currently not reading.

``total-bytes``
    Sum of packet bytes (plus some overhead estimation) of the entire packet
    queue, including cached seekable ranges.

This option is relatively useless.

``audio-params/format``
    The sample format as string. This uses the same names as used in other
    places of mpv.

``audio-params/samplerate``
    Samplerate.

``audio-params/channels``
    The channel layout as a string. This is similar to what the
    ``--audio-channels`` accepts.

``audio-params/hr-channels``
    As ``channels``, but instead of the possibly cryptic actual layout
    sent to the audio device, return a hopefully more human readable form.
    (Usually only ``audio-out-params/hr-channels`` makes sense.)

``audio-params/channel-count``
    Number of audio channels. This is redundant to the ``channels`` field
    described above.

When querying the property with the client API using ``MPV_FORMAT_NODE``,
or with Lua ``mp.get_property_native``, this will return a mpv_node with
the following contents:

::

    MPV_FORMAT_NODE_MAP
        "format"            MPV_FORMAT_STRING
        "samplerate"        MPV_FORMAT_INT64
        "channels"          MPV_FORMAT_STRING
        "channel-count"     MPV_FORMAT_INT64
        "hr-channels"       MPV_FORMAT_STRING

Writing to it may change the currently used hardware decoder, if possible.
(Internally, the player may reinitialize the decoder, and will perform a
seek to refresh the video properly.) You can watch the other hwdec
properties to see whether this was successful.

This does not return the currently active hardware decoder.
``hwdec-current`` is available for this purpose.

If no VO is active or no interop driver is known, this property is
unavailable.

This does not necessarily use the same values as ``hwdec``. There can be
multiple interop drivers for the same hardware decoder, depending on
platform and VO.

``video-params/pixelformat``
    The pixel format as string. This uses the same names as used in other
    places of mpv.

``video-params/hw-pixelformat``
    The underlying pixel format as string. This is relevant for some cases
    of hardware decoding and unavailable otherwise.

``video-params/average-bpp``
    Average bits-per-pixel as integer. Subsampled planar formats use a
    different resolution, which is the reason this value can sometimes be
    odd or confusing. Can be unavailable with some formats.

``video-params/w``, ``video-params/h``
    Video size as integers, with no aspect correction applied.

``video-params/dw``, ``video-params/dh``
    Video size as integers, scaled for correct aspect ratio.

``video-params/crop-x``, ``video-params/crop-y``
    Crop offset of the source video frame.

``video-params/crop-w``, ``video-params/crop-h``
    Video size after cropping.

``video-params/aspect``
    Display aspect ratio as double.

``video-params/aspect-name``
    Display aspect ratio name as string. The name corresponds to motion
    picture film format that introduced given aspect ratio in film.

``video-params/par``
    Pixel aspect ratio.

``video-params/sar``
    Storage aspect ratio.

``video-params/sar-name``
    Storage aspect ratio name as string.

``video-params/colormatrix``
    The colormatrix in use as string. (Exact values subject to change.)

``video-params/colorlevels``
    The colorlevels as string. (Exact values subject to change.)

``video-params/primaries``
    The primaries in use as string. (Exact values subject to change.)

``video-params/gamma``
    The gamma function in use as string. (Exact values subject to change.)

``video-params/sig-peak`` (deprecated)
    The video file's tagged signal peak as float.

``video-params/light``
    The light type in use as a string. (Exact values subject to change.)

``video-params/chroma-location``
    Chroma location as string. (Exact values subject to change.)

``video-params/rotate``
    Intended display rotation in degrees (clockwise).

``video-params/stereo-in``
    Source file stereo 3D mode. (See the ``format`` video filter's
    ``stereo-in`` option.)

``video-params/alpha``
    Alpha type. If the format has no alpha channel, this will be unavailable
    (but in future releases, it could change to ``no``). If alpha is
    present, this is set to ``straight`` or ``premul``.

``video-params/min-luma``
    Minimum luminance, as reported by HDR10 metadata (in cd/m²)

``video-params/max-luma``
    Maximum luminance, as reported by HDR10 metadata (in cd/m²)

``video-params/max-cll``
    Maximum content light level, as reported by HDR10 metadata (in cd/m²)

``video-params/max-fall``
    Maximum frame average light level, as reported by HDR10 metadata (in cd/m²)

``video-params/scene-max-r``
    MaxRGB of a scene for R component, as reported by HDR10+ metadata (in cd/m²)

``video-params/scene-max-g``
    MaxRGB of a scene for G component, as reported by HDR10+ metadata (in cd/m²)

``video-params/scene-max-b``
    MaxRGB of a scene for B component, as reported by HDR10+ metadata (in cd/m²)

``video-params/max-pq-y``
    Maximum PQ luminance of a frame, as reported by peak detection (in PQ, 0-1)

``video-params/avg-pq-y``
    Average PQ luminance of a frame, as reported by peak detection (in PQ, 0-1)

``video-params/prim-red-x``, ``video-params/prim-red-y``
    Red primary chromaticity coordinates, available only if differs from ``video-params/primaries``

``video-params/prim-green-x``, ``video-params/prim-green-y``
    Green primary chromaticity coordinates, available only if differs from ``video-params/primaries``

``video-params/prim-blue-x``, ``video-params/prim-blue-y``
    Blue primary chromaticity coordinates, available only if differs from ``video-params/primaries``

``video-params/prim-white-x``, ``video-params/prim-white-y``
    White point chromaticity coordinates, available only if differs from ``video-params/primaries``

When querying the property with the client API using ``MPV_FORMAT_NODE``,
or with Lua ``mp.get_property_native``, this will return a mpv_node with
the following contents:

::

    MPV_FORMAT_NODE_MAP
        "pixelformat"       MPV_FORMAT_STRING
        "hw-pixelformat"    MPV_FORMAT_STRING
        "w"                 MPV_FORMAT_INT64
        "h"                 MPV_FORMAT_INT64
        "dw"                MPV_FORMAT_INT64
        "dh"                MPV_FORMAT_INT64
        "aspect"            MPV_FORMAT_DOUBLE
        "aspect-name"       MPV_FORMAT_STRING
        "par"               MPV_FORMAT_DOUBLE
        "colormatrix"       MPV_FORMAT_STRING
        "colorlevels"       MPV_FORMAT_STRING
        "primaries"         MPV_FORMAT_STRING
        "gamma"             MPV_FORMAT_STRING
        "sig-peak"          MPV_FORMAT_DOUBLE
        "light"             MPV_FORMAT_STRING
        "chroma-location"   MPV_FORMAT_STRING
        "rotate"            MPV_FORMAT_INT64
        "stereo-in"         MPV_FORMAT_STRING
        "average-bpp"       MPV_FORMAT_INT64
        "alpha"             MPV_FORMAT_STRING
        "min-luma"          MPV_FORMAT_DOUBLE
        "max-luma"          MPV_FORMAT_DOUBLE
        "max-cll"           MPV_FORMAT_DOUBLE
        "max-fall"          MPV_FORMAT_DOUBLE
        "scene-max-r"       MPV_FORMAT_DOUBLE
        "scene-max-g"       MPV_FORMAT_DOUBLE
        "scene-max-b"       MPV_FORMAT_DOUBLE
        "max-pq-y"          MPV_FORMAT_DOUBLE
        "avg-pq-y"          MPV_FORMAT_DOUBLE
        "prim-red-x"        MPV_FORMAT_DOUBLE
        "prim-red-y"        MPV_FORMAT_DOUBLE
        "prim-green-x"      MPV_FORMAT_DOUBLE
        "prim-green-y"      MPV_FORMAT_DOUBLE
        "prim-blue-x"       MPV_FORMAT_DOUBLE
        "prim-blue-y"       MPV_FORMAT_DOUBLE
        "prim-white-x"      MPV_FORMAT_DOUBLE
        "prim-white-y"      MPV_FORMAT_DOUBLE

These have the same values as ``video-out-params/dw`` and
``video-out-params/dh``.

Has the same sub-properties as ``video-params``.

Has the same sub-properties as ``video-params``.

This has a number of sub-properties:

``video-frame-info/picture-type``
    The type of the picture. It can be "I" (intra), "P" (predicted), "B"
    (bi-dir predicted) or unavailable.

``video-frame-info/interlaced``
    Whether the content of the frame is interlaced.

``video-frame-info/tff``
    If the content is interlaced, whether the top field is displayed first.

``video-frame-info/repeat``
    Whether the frame must be delayed when decoding.

``video-frame-info/gop-timecode``
    String with the GOP timecode encoded in the frame.

``video-frame-info/smpte-timecode``
    String with the SMPTE timecode encoded in the frame.

``video-frame-info/estimated-smpte-timecode``
    Estimated timecode based on the current playback position and frame count.

(Renamed from ``fps``.)

It is also possible to write to this property. This has the same behavior as
writing ``window-scale``. Note that writing to ``current-window-scale`` will
not affect the value of ``window-scale``.

Alias to ``osd-dimensions/w`` and ``osd-dimensions/h``.

Alias to ``osd-dimensions/osd-par``.

Has the following sub-properties (which can be read as ``MPV_FORMAT_NODE``
or Lua table with ``mp.get_property_native``):

``osd-dimensions/w``
    Size of the VO window in OSD render units (usually pixels, but may be
    scaled pixels with VOs like ``xv``).

``osd-dimensions/h``
    Size of the VO window in OSD render units,

``osd-dimensions/par``
    Pixel aspect ratio of the OSD (usually 1).

``osd-dimensions/aspect``
    Display aspect ratio of the VO window. (Computing from the properties
    above.)

``osd-dimensions/mt``, ``osd-dimensions/mb``, ``osd-dimensions/ml``, ``osd-dimensions/mr``
    OSD to video margins (top, bottom, left, right). This describes the
    area into which the video is rendered.

Any of these properties may be unavailable or set to dummy values if the
VO window is not created or visible.

This has two sub-properties.

``term-size/w``
    width of the terminal in cells
``term-size/h``
    height of the terminal in cells

This property is not observable. Reacting to size changes requires
polling.

Has the following sub-properties (which can be read as ``MPV_FORMAT_NODE``
or Lua table with ``mp.get_property_native``):

``mouse-pos/x``, ``mouse-pos/y``
    Last known coordinates of the mouse pointer.

``mouse-pos/hover``
    Boolean - whether the mouse pointer hovers the video window. The
    coordinates should be ignored when this value is false if no mouse
    button is being pressed, because the video backends update them only
    when the pointer hovers the window in this case.

    If a mouse button is pressed while the pointer hovers the video window
    and then the mouse pointer moves out of window region without releasing
    the button, some video backends "capture" the pointer and still report
    the coordinates. In this case, the value of this property may be true or
    false depending on the video backend.

This has a number of sub-properties. Replace ``N`` with the 0-based touch
point index. Whenever a new finger touches the screen, a new touch point is
added to the list of touch points with the smallest unused ``N`` available.

``touch-pos/count``
    Number of active touch points.

``touch-pos/N/x``, ``touch-pos/N/y``
    Position of the Nth touch point.

``touch-pos/N/id``
    Unique identifier of the touch point. This can be used to identify
    individual touch points when their indexes change.

When querying the property with the client API using ``MPV_FORMAT_NODE``,
or with Lua ``mp.get_property_native``, this will return a mpv_node with
the following contents:

::

    MPV_FORMAT_NODE_ARRAY
        MPV_FORMAT_NODE_MAP (for each touch point)
            "x"        MPV_FORMAT_INT64
            "y"        MPV_FORMAT_INT64
            "id"       MPV_FORMAT_INT64

Has the following sub-properties:

``tablet-pos/x``, ``tablet-pos/y``
    Last known coordinates of the tablet tool.
``tablet-pos/tool-in-proximity``
    Boolean - whether a tablet tool is currently in proximity of the tablet
    surface / hovers above the tablet surface.
``tablet-pos/tool-tip``,
    The state of the tablet tool tip, ``up`` or ``down.``
``tablet-pos/tool-stylus-btn1``, ``tablet-pos/tool-stylus-btn2``, ``tablet-pos/tool-stylus-btn3``
    The state of tablet tool side buttons, ``pressed`` or ``released``.
``tablet-pos/pad-focus``
    Boolean - whether a tablet pad is currently focused.
``tablet-pos/pad-btns/N``
    The state of the Nth tablet pad button, ``pressed`` or ``released``.

::

    MPV_FORMAT_NODE_MAP
        "x"                  MPV_FORMAT_INT64
        "y"                  MPV_FORMAT_INT64
        "tool-in-proximity"  MPV_FORMAT_FLAG
        "tool-tip"           MPV_FORMAT_STRING
        "tool-stylus-btn1"   MPV_FORMAT_STRING
        "tool-stylus-btn2"   MPV_FORMAT_STRING
        "tool-stylus-btn3"   MPV_FORMAT_STRING
        "pad-focus"          MPV_FORMAT_FLAG
        "pad-btns"           MPV_FORMAT_NODE_MAP
           (key and string value for each pad-btn entry)

Has the following sub-properties:

``dropped-files/time``
    The timestamp of the last drag-and-drop event mpv received, in
    nanoseconds. This uses the same clock as ``mpv_get_time_ns()``.

``dropped-files/action``
    The action of the drag-and-drop event. This is normally ``replace``.
    Depending on the platform, this can also be ``append`` in some cases,
    such as shift key being held while files are dropped.

``dropped-files/files``
    The dropped file names of the drag-and-drop event.

When querying the property with the client API using ``MPV_FORMAT_NODE``,
or with Lua ``mp.get_property_native``, this will return a mpv_node with
the following contents:

::

    MPV_FORMAT_NODE_MAP
        "time"    MPV_FORMAT_INT64
        "action"  MPV_FORMAT_STRING
        "files"   MPV_FORMAT_NODE_ARRAY
            MPV_FORMAT_STRING

This has sub-properties for different formats:

``sub-text/ass``
    Like ``sub-text``, but return the text in ASS format. Text subtitles in
    other formats are converted. For native ASS subtitles, events that do
    not contain any text (but vector drawings etc.) are not filtered out. If
    multiple events match with the current playback time, they are concatenated
    with line breaks. Contains only the "Text" part of the events.

    This property is not enough to render ASS subtitles correctly, because ASS
    header and per-event metadata are not returned. Use ``/ass-full`` for that.

``sub-text/ass-full``
    Like ``sub-text-ass``, but return the full event with all fields, formatted as
    lines in a .ass text file. Use with ``sub-ass-extradata`` for style information.

This has a sub-property:

``sub-start/full``
    ``sub-start`` with milliseconds.

This has a sub-property:

``sub-end/full``
    ``sub-end`` with milliseconds.

When querying the property with the client API using ``MPV_FORMAT_NODE``,
or with Lua ``mp.get_property_native``, this will return a mpv_node with
the following contents:

::

    MPV_FORMAT_NODE_ARRAY
        MPV_FORMAT_NODE_MAP (for each subtitle line)
            "text"  MPV_FORMAT_STRING
            "start" MPV_FORMAT_DOUBLE
            "end"   MPV_FORMAT_DOUBLE

ASS tags are stripped from ``text``.

``end`` is absent if unknown.

In some cases, this is not necessarily the currently playing file. See
explanation of ``current`` and ``playing`` flags in ``playlist``.

If there the playlist is empty, or if it's non-empty, but no entry is
"current", this property returns -1. Likewise, writing -1 will put the
player into idle mode (or exit playback if idle mode is not enabled). If an
out of range index is written to the property, this behaves as if writing -1.

Writing the current value back to the property will have no effect.
Use ``playlist-play-index`` to restart the playback of the current entry if
desired.

For reading, this is exactly the same as ``playlist-pos``.

For writing, this *only* sets the position of the "current" item, without
stopping playback of the current file (or starting playback, if this is done
in idle mode). Use -1 to remove the current flag.

This property is only vaguely useful. If set during playback, it will
typically cause the playlist entry *after* it to be played next. Another
possibly odd observable state is that if ``playlist-next`` is run during
playback, this property is set to the playlist entry to play next (unlike
the previous case). There is an internal flag that decides whether the
current playlist entry or the next one should be played, and this flag is
currently inaccessible for API users. (Whether this behavior will kept is
possibly subject to change.)

In the "playing" state, this is usually the same as ``playlist-pos``, except
during state changes, or if ``playlist-current-pos`` was written explicitly.

This has a number of sub-properties. Replace ``N`` with the 0-based playlist
entry index.

``playlist/count``
    Number of playlist entries (same as ``playlist-count``).

``playlist/N/filename``
    Filename of the Nth entry.

``playlist/N/playing``
    ``yes``/true if the ``playlist-playing-pos`` property points to this
    entry, ``no``/false or unavailable otherwise.

``playlist/N/current``
    ``yes``/true if the ``playlist-current-pos`` property points to this
    entry, ``no``/false or unavailable otherwise.

``playlist/N/title``
    Name of the Nth entry. Available if the playlist file contains
    such fields and mpv's parser supports it for the given
    playlist format, or if the playlist entry has been opened before and a
    media-title other than filename has been acquired.

``playlist/N/id``
    Unique ID for this entry. This is an automatically assigned integer ID
    that is unique for the entire life time of the current mpv core
    instance. Other commands, events, etc. use this as ``playlist_entry_id``
    fields.

``playlist/N/playlist-path``
    The original path of the playlist for this entry before mpv expanded
    it. Unavailable if the file was not originally associated with a playlist
    in some way.

When querying the property with the client API using ``MPV_FORMAT_NODE``,
or with Lua ``mp.get_property_native``, this will return a mpv_node with
the following contents:

::

    MPV_FORMAT_NODE_ARRAY
        MPV_FORMAT_NODE_MAP (for each playlist entry)
            "filename"      MPV_FORMAT_STRING
            "current"       MPV_FORMAT_FLAG (might be missing)
            "playing"       MPV_FORMAT_FLAG (same)
            "title"         MPV_FORMAT_STRING (optional)
            "id"            MPV_FORMAT_INT64
            "playlist-path" MPV_FORMAT_STRING (optional)

This has a number of sub-properties. Replace ``N`` with the 0-based track
index.

``track-list/count``
    Total number of tracks.

``track-list/video``
    The list of video tracks. This is only usable for printing and its value
    can't be retrieved.

``track-list/audio``
    The list of audio tracks. This is only usable for printing and its value
    can't be retrieved.

``track-list/sub``
    The list of sub tracks. This is only usable for printing and its value
    can't be retrieved.

``track-list/N/id``
    The ID as it's used for ``--sid``/``--aid``/``--vid``. This is unique
    within tracks of the same type (sub/audio/video), but otherwise not.

``track-list/N/type``
    String describing the media type. One of ``audio``, ``video``, ``sub``.

``track-list/N/src-id``
    Track ID as used in the source file. Not always available. (It is
    missing if the format has no native ID, if the track is a pseudo-track
    that does not exist in this way in the actual file, or if the format
    is handled by libavformat, and the format was not whitelisted as having
    track IDs.)

``track-list/N/title``
    Track title as it is stored in the file. Not always available.

``track-list/N/lang``
    Track language as identified by the file. Not always available.

``track-list/N/image``
    ``yes``/true if this is a video track that consists of a single
    picture, ``no``/false or unavailable otherwise. The heuristic used to
    determine if a stream is an image doesn't attempt to detect images in
    codecs normally used for videos. Otherwise, it is reliable.

``track-list/N/albumart``
    ``yes``/true if this is an image embedded in an audio file or external
    cover art, ``no``/false or unavailable otherwise.

``track-list/N/default``
    ``yes``/true if the track has the default flag set in the file,
    ``no``/false or unavailable otherwise.

``track-list/N/forced``
    ``yes``/true if the track has the forced flag set in the file,
    ``no``/false or unavailable otherwise.

``track-list/N/dependent``
    ``yes``/true if the track has the dependent flag set in the file,
    ``no``/false or unavailable otherwise.

``track-list/N/visual-impaired``
    ``yes``/true if the track has the visual impaired flag set in the file,
    ``no``/false or unavailable otherwise.

``track-list/N/hearing-impaired``
    ``yes``/true if the track has the hearing impaired flag set in the file,
    ``no``/false or unavailable otherwise.

``track-list/N/hls-bitrate``
    The bitrate of the HLS stream, if available.

``track-list/N/program-id``
    The first program ID this stream belongs to, if any. Deprecated,
    use ``track-list/N/program-ids``.

``track-list/N/program-ids``
    A list of all program IDs this stream belongs to. A stream can belong
    to more than one program (e.g. in MPEG-TS or HLS). Unavailable if the
    stream does not belong to any program.

``track-list/N/codec``
    The codec name used by this track, for example ``h264``. Unavailable
    in some rare cases.

``track-list/N/codec-desc``
    The codec descriptive name used by this track.

``track-list/N/codec-profile``
    The codec profile used by this track. Available only if the track has
    been already decoded.

``track-list/N/external``
    ``yes``/true if the track is an external file, ``no``/false or
    unavailable otherwise. This is set for separate subtitle files.

``track-list/N/external-filename``
    The filename if the track is from an external file, unavailable
    otherwise.

``track-list/N/selected``
    ``yes``/true if the track is currently decoded, ``no``/false or
    unavailable otherwise.

``track-list/N/main-selection``
    It indicates the selection order of tracks for the same type.
    If a track is not selected, or is selected by the ``--lavfi-complex``,
    it is not available. For subtitle tracks, ``0`` represents the ``sid``,
    and ``1`` represents the ``secondary-sid``.

``track-list/N/ff-index``
    The stream index as usually used by the FFmpeg utilities. Note that
    this can be potentially wrong if a demuxer other than libavformat
    (``--demuxer=lavf``) is used. For mkv files, the index will usually
    match even if the default (builtin) demuxer is used, but there is
    no hard guarantee. May be unavailable if no known mapping exists.

``track-list/N/decoder``
    If this track is being decoded, the short decoder name,

``track-list/N/decoder-desc``
    If this track is being decoded, the human-readable decoder name,

``track-list/N/demux-w``, ``track-list/N/demux-h``
    Video size hint as indicated by the container. (Not always accurate.)

``track-list/N/demux-crop-x``, ``track-list/N/demux-crop-y``
    Crop offset of the source video frame.

``track-list/N/demux-crop-w``, ``track-list/N/demux-crop-h``
    Video size after cropping.

``track-list/N/demux-channel-count``
    Number of audio channels as indicated by the container. (Not always
    accurate - in particular, the track could be decoded as a different
    number of channels.)

``track-list/N/demux-channels``
    Channel layout as indicated by the container. (Not always accurate.)

``track-list/N/demux-samplerate``
    Audio sample rate as indicated by the container. (Not always accurate.)

``track-list/N/demux-fps``
    Video FPS as indicated by the container. (Not always accurate.)

``track-list/N/demux-bitrate``
    Average bitrate, in bits per second. (Not always accurate.)

``track-list/N/demux-rotation``
    Video clockwise rotation metadata, in degrees.

``track-list/N/demux-par``
    Pixel aspect ratio.

``track-list/N/demux-duration``
    Track duration as indicated by the container.

``track-list/N/format-name``
    Short name for format from ffmpeg. If the track is audio, this will be
    the name of the sample format. If the track is video, this will be the
    name of the pixel format.

``track-list/N/audio-channels`` (deprecated)
    Deprecated alias for ``track-list/N/demux-channel-count``.

``track-list/N/replaygain-track-peak``, ``track-list/N/replaygain-track-gain``
    Per-track replaygain values. Only available for audio tracks with
    corresponding information stored in the source file.

``track-list/N/replaygain-album-peak``, ``track-list/N/replaygain-album-gain``
    Per-album replaygain values. If the file has per-track but no per-album
    information, the per-album values will be copied from the per-track
    values currently. It's possible that future mpv versions will make
    these properties unavailable instead in this case.

``track-list/N/dolby-vision-profile``, ``track-list/N/dolby-vision-level``
    Dolby Vision profile and level. May not be available if the container
    does not provide this information.

``track-list/N/metadata``,
    Works like the ``metadata`` property, but it accesses metadata that is
    set per track/stream instead of global values for the entire file.

When querying the property with the client API using ``MPV_FORMAT_NODE``,
or with Lua ``mp.get_property_native``, this will return a mpv_node with
the following contents:

::

    MPV_FORMAT_NODE_ARRAY
        MPV_FORMAT_NODE_MAP (for each track)
            "id"                MPV_FORMAT_INT64
            "type"              MPV_FORMAT_STRING
            "src-id"            MPV_FORMAT_INT64
            "title"             MPV_FORMAT_STRING
            "lang"              MPV_FORMAT_STRING
            "image"             MPV_FORMAT_FLAG
            "albumart"          MPV_FORMAT_FLAG
            "default"           MPV_FORMAT_FLAG
            "forced"            MPV_FORMAT_FLAG
            "dependent"         MPV_FORMAT_FLAG
            "visual-impaired"   MPV_FORMAT_FLAG
            "hearing-impaired"  MPV_FORMAT_FLAG
            "hls-bitrate"       MPV_FORMAT_INT64
            "program-id"        MPV_FORMAT_INT64
            "program-ids"       MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_INT64]
            "selected"          MPV_FORMAT_FLAG
            "main-selection"    MPV_FORMAT_INT64
            "external"          MPV_FORMAT_FLAG
            "external-filename" MPV_FORMAT_STRING
            "codec"             MPV_FORMAT_STRING
            "codec-desc"        MPV_FORMAT_STRING
            "codec-profile"     MPV_FORMAT_STRING
            "ff-index"          MPV_FORMAT_INT64
            "decoder"           MPV_FORMAT_STRING
            "decoder-desc"      MPV_FORMAT_STRING
            "demux-w"           MPV_FORMAT_INT64
            "demux-h"           MPV_FORMAT_INT64
            "demux-crop-x"      MPV_FORMAT_INT64
            "demux-crop-y"      MPV_FORMAT_INT64
            "demux-crop-w"      MPV_FORMAT_INT64
            "demux-crop-h"      MPV_FORMAT_INT64
            "demux-channel-count" MPV_FORMAT_INT64
            "demux-channels"    MPV_FORMAT_STRING
            "demux-samplerate"  MPV_FORMAT_INT64
            "demux-fps"         MPV_FORMAT_DOUBLE
            "demux-bitrate"     MPV_FORMAT_INT64
            "demux-rotation"    MPV_FORMAT_INT64
            "demux-par"         MPV_FORMAT_DOUBLE
            "format-name"       MPV_FORMAT_STRING
            "audio-channels"    MPV_FORMAT_INT64
            "replaygain-track-peak" MPV_FORMAT_DOUBLE
            "replaygain-track-gain" MPV_FORMAT_DOUBLE
            "replaygain-album-peak" MPV_FORMAT_DOUBLE
            "replaygain-album-gain" MPV_FORMAT_DOUBLE
            "dolby-vision-profile" MPV_FORMAT_INT64
            "dolby-vision-level" MPV_FORMAT_INT64
            "metadata"           MPV_FORMAT_NODE_MAP
                (key and string value for each metadata entry)

The following sub-entries are defined: ``video``, ``audio``, ``sub``,
``sub2``

For example, ``current-tracks/audio/lang`` returns the current audio track's
language field (the same value as ``track-list/N/lang``).

If tracks of the requested type are selected via ``--lavfi-complex``, the
first one is returned.

Note that this property cannot be used directly, a sub-property is required.

This has a number of sub-properties. Replace ``N`` with the 0-based chapter
index.

``chapter-list/count``
    Number of chapters.

``chapter-list/N/title``
    Chapter title as stored in the file. Not always available.

``chapter-list/N/time``
    Chapter start time in seconds as float.

When querying the property with the client API using ``MPV_FORMAT_NODE``,
or with Lua ``mp.get_property_native``, this will return a mpv_node with
the following contents:

::

    MPV_FORMAT_NODE_ARRAY
        MPV_FORMAT_NODE_MAP (for each chapter)
            "title" MPV_FORMAT_STRING
            "time"  MPV_FORMAT_DOUBLE

When querying the property with the client API using ``MPV_FORMAT_NODE``,
or with Lua ``mp.get_property_native``, this will return a mpv_node with
the following contents:

::

    MPV_FORMAT_NODE_ARRAY
        MPV_FORMAT_NODE_MAP (for each filter entry)
            "name"      MPV_FORMAT_STRING
            "label"     MPV_FORMAT_STRING [optional]
            "enabled"   MPV_FORMAT_FLAG [optional]
            "params"    MPV_FORMAT_NODE_MAP [optional]
                (key and string value for each param entry)

It's also possible to write the property using this format.

If this property returns ``yes``/true, so will ``seekable``.

.. admonition:: Example

    - ``--osd-msg3='This is ${osd-ass-cc/0}{\\b1}bold text'``
    - ``show-text "This is ${osd-ass-cc/0}{\\b1}bold text"``

Any ASS override tags as understood by libass can be used.

Note that you need to escape the ``\`` character, because the string is
processed for C escape sequences before passing it to the OSD code. See
`Flat command syntax`_ for details.

A list of tags can be found here:
https://aegisub.org/docs/latest/ass_tags/

This is further subdivided into two frame types, ``vo-passes/fresh`` for
fresh frames (which have to be uploaded, scaled, etc.) and
``vo-passes/redraw`` for redrawn frames (which only have to be re-painted).
The number of passes for any given subtype can change from frame to frame,
and should not be relied upon.

Each frame type has a number of further sub-properties. Replace ``TYPE``
with the frame type, ``N`` with the 0-based pass index, and ``M`` with the
0-based sample index.

``vo-passes/TYPE/count``
    Number of passes.

``vo-passes/TYPE/N/desc``
    Human-friendy description of the pass.

``vo-passes/TYPE/N/last``
    Last measured execution time, in nanoseconds.

``vo-passes/TYPE/N/avg``
    Average execution time of this pass, in nanoseconds. The exact
    timeframe varies, but it should generally be a handful of seconds.

``vo-passes/TYPE/N/peak``
    The peak execution time (highest value) within this averaging range, in
    nanoseconds.

``vo-passes/TYPE/N/count``
    The number of samples for this pass.

``vo-passes/TYPE/N/samples/M``
    The raw execution time of a specific sample for this pass, in
    nanoseconds.

When querying the property with the client API using ``MPV_FORMAT_NODE``,
or with Lua ``mp.get_property_native``, this will return a mpv_node with
the following contents:

::

    MPV_FORMAT_NODE_MAP
        (key and array value for each TYPE entry)
        MPV_FORMAT_NODE_ARRAY (for each pass entry)
            MPV_FORMAT_NODE_MAP
                "desc"    MPV_FORMAT_STRING
                "last"    MPV_FORMAT_INT64
                "avg"     MPV_FORMAT_INT64
                "peak"    MPV_FORMAT_INT64
                "count"   MPV_FORMAT_INT64
                "samples" MPV_FORMAT_NODE_ARRAY
                     MPV_FORMAT_INT64

Note that directly accessing this structure via subkeys is not supported,
the only access is through aforementioned ``MPV_FORMAT_NODE``.

The unit is bits per second. OSD formatting turns these values in kilobits
(or megabits, if appropriate), which can be prevented by using the
raw property value, e.g. with ``${=video-bitrate}``.

Note that the accuracy of these properties is influenced by a few factors.
If the underlying demuxer rewrites the packets on demuxing (done for some
file formats), the bitrate might be slightly off. If timestamps are bad
or jittery (like in Matroska), even constant bitrate streams might show
fluctuating bitrate.

How exactly these values are calculated might change in the future.

In earlier versions of mpv, these properties returned a static (but bad)
guess using a completely different method.

When querying the property with the client API using ``MPV_FORMAT_NODE``,
or with Lua ``mp.get_property_native``, this will return a mpv_node with
the following contents:

::

    MPV_FORMAT_NODE_ARRAY
        MPV_FORMAT_NODE_MAP (for each device entry)
            "name"          MPV_FORMAT_STRING
            "description"   MPV_FORMAT_STRING

The ``name`` is what is to be passed to the ``--audio-device`` option (and
often a rather cryptic audio API-specific ID), while ``description`` is
human readable free form text. The description is set to the device name
(minus mpv-specific ``<driver>/`` prefix) if no description is available
or the description would have been an empty string.

The special entry with the name set to ``auto`` selects the default audio
output driver and the default device.

The property can be watched with the property observation mechanism in
the client API and in Lua scripts. (Technically, change notification is
enabled the first time this property is read.)

Writing this property while no audio output is active will not automatically
enable audio. (This is also true in the case when audio was disabled due to
reinitialization failure after a previous write access to ``audio-device``.)

This property also doesn't tell you which audio device is actually in use.

How these details are handled may change in the future.

Sub-paths can be accessed directly; e.g. ``user-data/my-script/state/a`` can be
read, written, or observed.

The top-level object itself cannot be written directly; write to sub-paths instead.

Converting this property or its sub-properties to strings will give a JSON
representation. If converting a leaf-level object (i.e. not a map or array)
and not using raw mode, the underlying content will be given (e.g. strings will be
printed directly, rather than quoted and JSON-escaped).

The following sub-paths are reserved for internal uses or have special semantics:
``user-data/osc``, ``user-data/mpv``. Unless noted otherwise, the semantics of
any properties under these sub-paths can change at any time and may not be relied
upon, and writing to these properties may prevent builtin scripts from working
properly.

Currently, the following properties have defined special semantics:

``user-data/osc/margins``
    This property is written by an OSC implementation to indicate the margins that it
    occupies. Its sub-properties ``l``, ``r``, ``t``, and ``b`` should all be set to
    the left, right, top, and bottom margins respectively.
    Values are between 0.0 and 1.0, normalized to window width/height.

``user-data/osc/draw-preview``
    Used to communicate between osc and compatible thumbnailer (if
    installed). See `OSC Preview API`_ section for more details.

``user-data/mpv/ytdl``
    Data shared by the builtin ytdl hook script.

    ``user-data/mpv/ytdl/path``
        Path to the ytdl executable, if found, or an empty string otherwise.
        The property is not set until the script attempts to find the ytdl
        executable, i.e. until an URL is being loaded by the script.

    ``user-data/mpv/ytdl/json-subprocess-result``
        Result of executing ytdl to retrieve the JSON data of the URL being
        loaded. The format is the same as ``subprocess``'s result, capturing
        stdout and stderr.

``user-data/mpv/console/open``
    Whether the console is open.

``user-data/mpv/context-menu/open``
    Whether the context menu script is open.

``type``
    Menu item type. Can be: ``separator``, ``submenu``, or empty.

``title``
    Menu item title. Required if type is not ``separator``.

``cmd``
    Command to execute when the menu item is clicked.

``shortcut``
    Menu item shortcut key which appears to the right of the menu item.
    A shortcut key does not have to be functional; it's just a visual hint.

``state``
    Menu item state. Can be: ``checked``, ``disabled``, ``hidden``, or empty.

``submenu``
    Submenu items, which is required if type is ``submenu``.

When querying the property with the client API using ``MPV_FORMAT_NODE``, or with
Lua ``mp.get_property_native``, this will return a mpv_node with the following
contents:

::

    MPV_FORMAT_NODE_ARRAY
        MPV_FORMAT_NODE_MAP (menu item)
            "type"           MPV_FORMAT_STRING
            "title"          MPV_FORMAT_STRING
            "cmd"            MPV_FORMAT_STRING
            "shortcut"       MPV_FORMAT_STRING
            "state"          MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING]
            "submenu"        MPV_FORMAT_NODE_ARRAY[menu item]

Writing to this property with the client API using ``MPV_FORMAT_NODE`` or with
Lua ``mp.set_property_native`` will trigger an immediate update of the menu if
mpv video output is currently active. You may observe the ``current-vo``
property to check if this is the case.

``codec``
    Canonical codec name, which identifies the format the decoder can
    handle.

``driver``
    The name of the decoder itself. Often, this is the same as ``codec``.
    Sometimes it can be different. It is used to distinguish multiple
    decoders for the same codec.

``description``
    Human readable description of the decoder and codec.

When querying the property with the client API using ``MPV_FORMAT_NODE``,
or with Lua ``mp.get_property_native``, this will return a mpv_node with
the following contents:

::

    MPV_FORMAT_NODE_ARRAY
        MPV_FORMAT_NODE_MAP (for each decoder entry)
            "codec"         MPV_FORMAT_STRING
            "driver"        MPV_FORMAT_STRING
            "description"   MPV_FORMAT_STRING

There shouldn't be any reason to access ``options/<name>`` instead of
``<name>``, except in situations in which the properties have different
behavior or conflicting semantics.

If an option is applied through a file specific mechanism such as per-file
options, watch later, ``options`` parameter of the ``loadfile`` command,
or file-specific configuration files, the option is similarly marked as
file-local.

(Note that if an option is marked as file-local, even ``options/`` will
access the local value, and the ``old`` value, which will be restored on
end of playback, cannot be read or written until end of playback.)

This has a number of sub-properties. Replace ``<name>`` with the name of
a top-level option. No guarantee of stability is given to any of these
sub-properties - they may change radically in the future.

``option-info/<name>/name``
    The name of the option.

``option-info/<name>/type``
    The name of the option type, like ``String`` or ``Integer``. For many
    complex types, this isn't very accurate.

``option-info/<name>/set-from-commandline``
    Whether the option was set from the mpv command line. What this is set
    to if the option is e.g. changed at runtime is left undefined (meaning
    it could change in the future).

``option-info/<name>/set-locally``
    Whether the option was set per-file. This is the case with
    automatically loaded profiles, file-dir configs, and other cases. It
    means the option value will be restored to the value before playback
    start when playback ends.

``option-info/<name>/expects-file``
    Whether the option takes file paths as arguments.

``option-info/<name>/default-value``
    The default value of the option. May not always be available.

``option-info/<name>/min``, ``option-info/<name>/max``
    Integer minimum and maximum values allowed for the option. Only
    available if the options are numeric, and the minimum/maximum has been
    set internally. It's also possible that only one of these is set.

``option-info/<name>/choices``
    If the option is a choice option, the possible choices. Choices that
    are integers may or may not be included (they can be implied by ``min``
    and ``max``). Note that options which behave like choice options, but
    are not actual choice options internally, may not have this info
    available.

::

    MPV_FORMAT_NODE_MAP
        "name"                    MPV_FORMAT_STRING
        "type"                    MPV_FORMAT_STRING
        "set-from-commandline"    MPV_FORMAT_FLAG
        "set-locally"             MPV_FORMAT_FLAG
        "expects-file"            MPV_FORMAT_FLAG
        "default-value"           MPV_FORMAT_NODE (optional, value of "type")
        "min"                     MPV_FORMAT_DOUBLE (optional)
        "max"                     MPV_FORMAT_DOUBLE (optional)
        "choices"                 MPV_FORMAT_NODE_ARRAY (optional)
            MPV_FORMAT_STRING

The ``profile-restore`` field is currently missing if it holds the default
value (either because it was not set, or set explicitly to ``default``),
but in the future it might hold the value ``default``.

::

    MPV_FORMAT_NODE_ARRAY
        MPV_FORMAT_NODE_MAP (for each profile entry)
            "name"       MPV_FORMAT_STRING
            "options"    MPV_FORMAT_NODE_ARRAY (for each option entry)
                MPV_FORMAT_NODE_MAP
                    "key"      MPV_FORMAT_STRING
                    "value"    MPV_FORMAT_STRING

``name``
    The name of the command.

``vararg``
    Whether the command accepts a variable number of arguments.

``args``
    An array of maps, where each map node represents an argument with the
    following entries:

    ``name``
        The name of the argument.

    ``type``
        The name of the argument type, like ``String`` or ``Integer``.

    ``optional``
        Whether the argument is optional.

When querying the property with the client API using ``MPV_FORMAT_NODE``,
or with Lua ``mp.get_property_native``, this will return a mpv_node with
the following contents:

::

    MPV_FORMAT_NODE_ARRAY
        MPV_FORMAT_NODE_MAP (for each command entry)
            "name"    MPV_FORMAT_STRING
            "vararg"  MPV_FORMAT_FLAG
            "args"    MPV_FORMAT_NODE_ARRAY
                MPV_FORMAT_NODE_MAP
                    "name"           MPV_FORMAT_STRING
                    "type"           MPV_FORMAT_STRING
                    "optional"       MPV_FORMAT_FLAG
                    "default-value"  MPV_FORMAT_NODE (optional, value of "type")
                    "choices"        MPV_FORMAT_NODE_ARRAY (optional)
                        MPV_FORMAT_STRING

``key``
    The key name. This is normalized and may look slightly different from
    how it was specified in the source (e.g. in input.conf).

``cmd``
    The command mapped to the key. (Currently, this is exactly the same
    string as specified in the source, other than stripping whitespace and
    comments. It's possible that it will be normalized in the future.)

``is_weak``
    If set to true, any existing and active user bindings will take priority.

``owner``
    If this entry exists, the name of the script (or similar) which added
    this binding.

``section``
    Name of the section this binding is part of. This is a rarely used
    mechanism. This entry may be removed or change meaning in the future.

``priority``
    A number. Bindings with a higher value are preferred over bindings
    with a lower value. If the value is negative, this binding is inactive
    and will not be triggered by input. Note that mpv does not use this
    value internally, and matching of bindings may work slightly differently
    in some cases. In addition, this value is dynamic and can change around
    at runtime.

``comment``
    If available, the comment following the command on the same line. (For
    example, the input.conf entry ``f cycle bla # toggle bla`` would
    result in an entry with ``comment = "toggle bla", cmd = "cycle bla"``.)

::

    MPV_FORMAT_NODE_ARRAY
        MPV_FORMAT_NODE_MAP
            "key"         MPV_FORMAT_STRING
            "cmd"         MPV_FORMAT_STRING
            "is_weak"     MPV_FORMAT_FLAG
            "owner"       MPV_FORMAT_STRING (optional)
            "section"     MPV_FORMAT_STRING
            "priority"    MPV_FORMAT_INT64
            "comment"     MPV_FORMAT_STRING (optional)

This property is read-only, and change notification is not supported.

This has a number of sub-properties:

``clipboard/text`` (RW)
    The text content in the clipboard.
    Writing to this property sets the text clipboard content

``clipboard/text-primary`` (RW)
    The text content in the primary selection (X11 and Wayland only).

.. note::

    On Wayland with the ``vo`` clipboard backend, the clipboard content is
    only updated when the compositor sends a selection data offer
    (typically when VO window is focused). The ``wayland`` backend typically
    does not have this limitation.
    See ``current-clipboard-backend`` property for more details.

.. warning::

    Since mpv 0.42.0, this property does not return the current clipboard
    content on certain platforms if ``--clipboard-monitor=no``.
    When reading clipboard content, you must run ``update-clipboard``
    command to update the clipboard content manually in this case.

::

    MPV_FORMAT_NODE_MAP
        "text"            MPV_FORMAT_STRING
        "text-primary"    MPV_FORMAT_STRING

``i show-text "Filename: ${filename}"``
    shows the filename of the current file when pressing the ``i`` key

- ``\n`` becomes a newline character
- ``\\`` expands to ``\``

- ``${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)

- ``${avsync}`` expands to ``+0.003``
- ``${>avsync}`` expands to ``+0.0030``
- ``${=avsync}`` expands to ``0.003028``

This is not intended to be a secure network protocol. It is explicitly
insecure: there is no authentication, no encryption, and the commands
themselves are insecure too. For example, the ``run`` command is exposed,
which can run arbitrary system commands. The use-case is controlling the
player locally. This is not different from the MPlayer slave protocol.

mpv file.mkv --input-ipc-server=/tmp/mpvsocket

> echo '{ "command": ["get_property", "playback-time"] }' | socat - /tmp/mpvsocket
{"data":190.482000,"error":"success"}

> echo 'show-text ${playback-time}' | socat - /tmp/mpvsocket

mpv file.mkv --input-ipc-server=\\.\pipe\mpvsocket

echo show-text ${playback-time} >\\.\pipe\mpvsocket

{ "command": ["command_name", "param1", "param2", ...] }

{ "error": "success", "data": null }

{ "event": "event_name" }

{ "command": ["get_property", "time-pos"], "request_id": 100 }

{ "error": "success", "data": 1.468135, "request_id": 100 }

{ "command": ["screenshot"], "request_id": 123, "async": true }

{"request_id":123,"error":"success","data":null}

Example:

::

    { "command": ["get_property", "volume"] }
    { "data": 50.0, "error": "success" }

Example:

::

    { "command": ["get_property_string", "volume"] }
    { "data": "50.000000", "error": "success" }

Example:

::

    { "command": ["set_property", "pause", true] }
    { "error": "success" }

Example:

::

    { "command": ["observe_property", 1, "volume"] }
    { "error": "success" }
    { "event": "property-change", "id": 1, "data": 52.0, "name": "volume" }

.. warning::

    If the connection is closed, the IPC client is destroyed internally,
    and the observed properties are unregistered. This happens for example
    when sending commands to a socket with separate ``socat`` invocations.
    This can make it seem like property observation does not work. You must
    keep the IPC connection open to make it work.

Example:

::

    { "command": ["observe_property_string", 1, "volume"] }
    { "error": "success" }
    { "event": "property-change", "id": 1, "data": "52.000000", "name": "volume" }

Example:

::

    { "command": ["unobserve_property", 1] }
    { "error": "success" }

Log message output is meant for humans only (mostly for debugging).
Attempting to retrieve information by parsing these messages will just
lead to breakages with future mpv releases. Instead, make a feature request,
and ask for a proper event that returns the information you need.

By default, most events are enabled, and there is not much use for this
command.

See also: ``DOCS/client-api-changes.rst``.

- a list or object item can have a trailing ","
- object syntax accepts "=" in addition of ":"
- object keys can be unquoted, if they start with a character in "A-Za-z\_"
  and contain only characters in "A-Za-z0-9\_"
- byte escapes with "\xAB" are allowed (with AB being a 2 digit hex number)

{ objkey = "value\x0A" }

{ "objkey": "value\n" }