1COMMAND INTERFACE 2================= 3 4The mpv core can be controlled with commands and properties. A number of ways 5to interact with the player use them: key bindings (``input.conf``), OSD 6(showing information with properties), JSON IPC, the client API (``libmpv``), 7and the classic slave mode. 8 9input.conf 10---------- 11 12The input.conf file consists of a list of key bindings, for example:: 13 14 s screenshot # take a screenshot with the s key 15 LEFT seek 15 # map the left-arrow key to seeking forward by 15 seconds 16 17Each line maps a key to an input command. Keys are specified with their literal 18value (upper case if combined with ``Shift``), or a name for special keys. For 19example, ``a`` maps to the ``a`` key without shift, and ``A`` maps to ``a`` 20with shift. 21 22The file is located in the mpv configuration directory (normally at 23``~/.config/mpv/input.conf`` depending on platform). The default bindings are 24defined here:: 25 26 https://github.com/mpv-player/mpv/blob/master/etc/input.conf 27 28A list of special keys can be obtained with 29 30 ``mpv --input-keylist`` 31 32In general, keys can be combined with ``Shift``, ``Ctrl`` and ``Alt``:: 33 34 ctrl+q quit 35 36**mpv** can be started in input test mode, which displays key bindings and the 37commands they're bound to on the OSD, instead of executing the commands:: 38 39 mpv --input-test --force-window --idle 40 41(Only closing the window will make **mpv** exit, pressing normal keys will 42merely display the binding, even if mapped to quit.) 43 44Also see `Key names`_. 45 46input.conf syntax 47----------------- 48 49``[Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] <command> ( ; <command> )*`` 50 51Note that by default, the right Alt key can be used to create special 52characters, and thus does not register as a modifier. The option 53``--no-input-right-alt-gr`` changes this behavior. 54 55Newlines always start a new binding. ``#`` starts a comment (outside of quoted 56string arguments). To bind commands to the ``#`` key, ``SHARP`` can be used. 57 58``<key>`` is either the literal character the key produces (ASCII or Unicode 59character), or a symbolic name (as printed by ``--input-keylist``). 60 61``<section>`` (braced with ``{`` and ``}``) is the input section for this 62command. 63 64``<command>`` is the command itself. It consists of the command name and 65multiple (or none) arguments, all separated by whitespace. String arguments 66should be quoted, typically with ``"``. See ``Flat command syntax``. 67 68You can bind multiple commands to one key. For example: 69 70| a show-text "command 1" ; show-text "command 2" 71 72It's also possible to bind a command to a sequence of keys: 73 74| a-b-c show-text "command run after a, b, c have been pressed" 75 76(This is not shown in the general command syntax.) 77 78If ``a`` or ``a-b`` or ``b`` are already bound, this will run the first command 79that matches, and the multi-key command will never be called. Intermediate keys 80can be remapped to ``ignore`` in order to avoid this issue. The maximum number 81of (non-modifier) keys for combinations is currently 4. 82 83Key names 84--------- 85 86All mouse and keyboard input is to converted to mpv-specific key names. Key 87names are either special symbolic identifiers representing a physical key, or a 88text key names, which are unicode code points encoded as UTF-8. These are what 89keyboard input would normally produce, for example ``a`` for the A key. As a 90consequence, mpv uses input translated by the current OS keyboard layout, rather 91than physical scan codes. 92 93Currently there is the hardcoded assumption that every text key can be 94represented as a single unicode code point (in NFKC form). 95 96All key names can be combined with the modifiers ``Shift``, ``Ctrl``, ``Alt``, 97``Meta``. They must be prefixed to the actual key name, where each modifier 98is followed by a ``+`` (for example ``ctrl+q``). 99 100The ``Shift`` modifier requires some attention. For instance ``Shift+2`` should 101usually be specified as key-name ``@`` at ``input.conf``, and similarly the 102combination ``Alt+Shift+2`` is usually ``Alt+@``, etc. Special key names like 103``Shift+LEFT`` work as expected. If in doubt - use ``--input-test`` to check 104how a key/combination is seen by mpv. 105 106Symbolic key names and modifier names are case-insensitive. Unicode key names 107are case-sensitive because input bindings typically respect the shift key. 108 109Another type of key names are hexadecimal key names, that serve as fallback 110for special keys that are neither unicode, nor have a special mpv defined name. 111They will break as soon as mpv adds proper names for them, but can enable you 112to use a key at all if that does not happen. 113 114All symbolic names are listed by ``--input-keylist``. ``--input-test`` is a 115special mode that prints all input on the OSD. 116 117Comments on some symbolic names: 118 119``KP*`` 120 Keypad names. Behavior varies by backend (whether they implement this, and 121 on how they treat numlock), but typically, mpv tries to map keys on the 122 keypad to separate names, even if they produce the same text as normal keys. 123 124``MOUSE_BTN*``, ``MBTN*`` 125 Various mouse buttons. 126 127 Depending on backend, the mouse wheel might also be represented as a button. 128 In addition, ``MOUSE_BTN3`` to ``MOUSE_BTN6`` are deprecated aliases for 129 ``WHEEL_UP``, ``WHEEL_DOWN``, ``WHEEL_LEFT``, ``WHEEL_RIGHT``. 130 131 ``MBTN*`` are aliases for ``MOUSE_BTN*``. 132 133``WHEEL_*`` 134 Mouse wheels (typically). 135 136``AXIS_*`` 137 Deprecated aliases for ``WHEEL_*``. 138 139``*_DBL`` 140 Mouse button double clicks. 141 142``MOUSE_MOVE``, ``MOUSE_ENTER``, ``MOUSE_LEAVE`` 143 Emitted by mouse move events. Enter/leave happens when the mouse enters or 144 leave the mpv window (or the current mouse region, using the deprecated 145 mouse region input section mechanism). 146 147``CLOSE_WIN`` 148 Pseudo key emitted when closing the mpv window using the OS window manager 149 (for example, by clicking the close button in the window title bar). 150 151``GAMEPAD_*`` 152 Keys emitted by the SDL gamepad backend. 153 154``UNMAPPED`` 155 Pseudo-key that matches any unmapped key. (You should probably avoid this 156 if possible, because it might change behavior or get removed in the future.) 157 158``ANY_UNICODE`` 159 Pseudo-key that matches any key that produces text. (You should probably 160 avoid this if possible, because it might change behavior or get removed in 161 the future.) 162 163Flat command syntax 164------------------- 165 166This is the syntax used in input.conf, and referred to "input.conf syntax" in 167a number of other places. 168 169| 170| ``<command> ::= [<prefixes>] <command_name> (<argument>)*`` 171| ``<argument> ::= (<unquoted> | " <double_quoted> " | ' <single_quoted> ' | `X <custom_quoted> X`)`` 172 173``command_name`` is an unquoted string with the command name itself. See 174`List of Input Commands`_ for a list. 175 176Arguments are separated by whitespaces even if the command expects only one 177argument. Arguments with whitespaces or other special characters must be quoted, 178or the command cannot be parsed correctly. 179 180Double quotes interpret JSON/C-style escaping, like ``\t`` or ``\"`` or ``\\``. 181JSON escapes according to RFC 8259, minus surrogate pair escapes. This is the 182only form which allows newlines at the value - as ``\n``. 183 184Single quotes take the content literally, and cannot include the single-quote 185character at the value. 186 187Custom quotes also take the content literally, but are more flexible than single 188quotes. They start with ````` (back-quote) followed by any ASCII character, 189and end at the first occurance of the same pair in reverse order, e.g. 190```-foo-``` or ````bar````. The final pair sequence is not allowed at the 191value - in these examples ``-``` and `````` respectively. In the second 192example the last character of the value also can't be a back-quote. 193 194Mixed quoting at the same argument, like ``'foo'"bar"``, is not supported. 195 196Note that argument parsing and property expansion happen at different stages. 197First, arguments are determined as described above, and then, where applicable, 198properties are expanded - regardless of argument quoting. However, expansion 199can still be prevented with the ``raw`` prefix or ``$>``. See `Input Command 200Prefixes`_ and `Property Expansion`_. 201 202Commands specified as arrays 203---------------------------- 204 205This applies to certain APIs, such as ``mp.commandv()`` or 206``mp.command_native()`` (with array parameters) in Lua scripting, or 207``mpv_command()`` or ``mpv_command_node()`` (with MPV_FORMAT_NODE_ARRAY) in the 208C libmpv client API. 209 210The command as well as all arguments are passed as a single array. Similar to 211the `Flat command syntax`_, you can first pass prefixes as strings (each as 212separate array item), then the command name as string, and then each argument 213as string or a native value. 214 215Since these APIs pass arguments as separate strings or native values, they do 216not expect quotes, and do support escaping. Technically, there is the input.conf 217parser, which first splits the command string into arguments, and then invokes 218argument parsers for each argument. The input.conf parser normally handles 219quotes and escaping. The array command APIs mentioned above pass strings 220directly to the argument parsers, or can sidestep them by the ability to pass 221non-string values. 222 223Property expansion is disabled by default for these APIs. This can be changed 224with the ``expand-properties`` prefix. See `Input Command Prefixes`_. 225 226Sometimes commands have string arguments, that in turn are actually parsed by 227other components (e.g. filter strings with ``vf add``) - in these cases, you 228you would have to double-escape in input.conf, but not with the array APIs. 229 230For complex commands, consider using `Named arguments`_ instead, which should 231give slightly more compatibility. Some commands do not support named arguments 232and inherently take an array, though. 233 234Named arguments 235--------------- 236 237This applies to certain APIs, such as ``mp.command_native()`` (with tables that 238have string keys) in Lua scripting, or ``mpv_command_node()`` (with 239MPV_FORMAT_NODE_MAP) in the C libmpv client API. 240 241The name of the command is provided with a ``name`` string field. The name of 242each command is defined in each command description in the 243`List of Input Commands`_. ``--input-cmdlist`` also lists them. See the 244``subprocess`` command for an example. 245 246Some commands do not support named arguments (e.g. ``run`` command). You need 247to use APIs that pass arguments as arrays. 248 249Named arguments are not supported in the "flat" input.conf syntax, which means 250you cannot use them for key bindings in input.conf at all. 251 252Property expansion is disabled by default for these APIs. This can be changed 253with the ``expand-properties`` prefix. See `Input Command Prefixes`_. 254 255List of Input Commands 256---------------------- 257 258Commands with parameters have the parameter name enclosed in ``<`` / ``>``. 259Don't add those to the actual command. Optional arguments are enclosed in 260``[`` / ``]``. If you don't pass them, they will be set to a default value. 261 262Remember to quote string arguments in input.conf (see `Flat command syntax`_). 263 264``ignore`` 265 Use this to "block" keys that should be unbound, and do nothing. Useful for 266 disabling default bindings, without disabling all bindings with 267 ``--no-input-default-bindings``. 268 269``seek <target> [<flags>]`` 270 Change the playback position. By default, seeks by a relative amount of 271 seconds. 272 273 The second argument consists of flags controlling the seek mode: 274 275 relative (default) 276 Seek relative to current position (a negative value seeks backwards). 277 absolute 278 Seek to a given time (a negative value starts from the end of the file). 279 absolute-percent 280 Seek to a given percent position. 281 relative-percent 282 Seek relative to current position in percent. 283 keyframes 284 Always restart playback at keyframe boundaries (fast). 285 exact 286 Always do exact/hr/precise seeks (slow). 287 288 Multiple flags can be combined, e.g.: ``absolute+keyframes``. 289 290 By default, ``keyframes`` is used for ``relative``, ``relative-percent``, 291 and ``absolute-percent`` seeks, while ``exact`` is used for ``absolute`` 292 seeks. 293 294 Before mpv 0.9, the ``keyframes`` and ``exact`` flags had to be passed as 295 3rd parameter (essentially using a space instead of ``+``). The 3rd 296 parameter is still parsed, but is considered deprecated. 297 298``revert-seek [<flags>]`` 299 Undoes the ``seek`` command, and some other commands that seek (but not 300 necessarily all of them). Calling this command once will jump to the 301 playback position before the seek. Calling it a second time undoes the 302 ``revert-seek`` command itself. This only works within a single file. 303 304 The first argument is optional, and can change the behavior: 305 306 mark 307 Mark the current time position. The next normal ``revert-seek`` command 308 will seek back to this point, no matter how many seeks happened since 309 last time. 310 mark-permanent 311 If set, mark the current position, and do not change the mark position 312 before the next ``revert-seek`` command that has ``mark`` or 313 ``mark-permanent`` set (or playback of the current file ends). Until 314 this happens, ``revert-seek`` will always seek to the marked point. This 315 flag cannot be combined with ``mark``. 316 317 Using it without any arguments gives you the default behavior. 318 319``frame-step`` 320 Play one frame, then pause. Does nothing with audio-only playback. 321 322``frame-back-step`` 323 Go back by one frame, then pause. Note that this can be very slow (it tries 324 to be precise, not fast), and sometimes fails to behave as expected. How 325 well this works depends on whether precise seeking works correctly (e.g. 326 see the ``--hr-seek-demuxer-offset`` option). Video filters or other video 327 post-processing that modifies timing of frames (e.g. deinterlacing) should 328 usually work, but might make backstepping silently behave incorrectly in 329 corner cases. Using ``--hr-seek-framedrop=no`` should help, although it 330 might make precise seeking slower. 331 332 This does not work with audio-only playback. 333 334``set <name> <value>`` 335 Set the given property or option to the given value. 336 337``add <name> [<value>]`` 338 Add the given value to the property or option. On overflow or underflow, 339 clamp the property to the maximum. If ``<value>`` is omitted, assume ``1``. 340 341``cycle <name> [<value>]`` 342 Cycle the given property or option. The second argument can be ``up`` or 343 ``down`` to set the cycle direction. On overflow, set the property back to 344 the minimum, on underflow set it to the maximum. If ``up`` or ``down`` is 345 omitted, assume ``up``. 346 347 Whether or not key-repeat is enabled by default depends on the property. 348 Currently properties with continuous values are repeatable by default (like 349 ``volume``), while discrete values are not (like ``osd-level``). 350 351``multiply <name> <value>`` 352 Similar to ``add``, but multiplies the property or option with the numeric 353 value. 354 355``screenshot <flags>`` 356 Take a screenshot. 357 358 Multiple flags are available (some can be combined with ``+``): 359 360 <subtitles> (default) 361 Save the video image, in its original resolution, and with subtitles. 362 Some video outputs may still include the OSD in the output under certain 363 circumstances. 364 <video> 365 Like ``subtitles``, but typically without OSD or subtitles. The exact 366 behavior depends on the selected video output. 367 <window> 368 Save the contents of the mpv window. Typically scaled, with OSD and 369 subtitles. The exact behavior depends on the selected video output, and 370 if no support is available, this will act like ``video``. 371 <each-frame> 372 Take a screenshot each frame. Issue this command again to stop taking 373 screenshots. Note that you should disable frame-dropping when using 374 this mode - or you might receive duplicate images in cases when a 375 frame was dropped. This flag can be combined with the other flags, 376 e.g. ``video+each-frame``. 377 378 Older mpv versions required passing ``single`` and ``each-frame`` as 379 second argument (and did not have flags). This syntax is still understood, 380 but deprecated and might be removed in the future. 381 382 If you combine this command with another one using ``;``, you can use the 383 ``async`` flag to make encoding/writing the image file asynchronous. For 384 normal standalone commands, this is always asynchronous, and the flag has 385 no effect. (This behavior changed with mpv 0.29.0.) 386 387``screenshot-to-file <filename> <flags>`` 388 Take a screenshot and save it to a given file. The format of the file will 389 be guessed by the extension (and ``--screenshot-format`` is ignored - the 390 behavior when the extension is missing or unknown is arbitrary). 391 392 The second argument is like the first argument to ``screenshot`` and 393 supports ``subtitles``, ``video``, ``window``. 394 395 If the file already exists, it's overwritten. 396 397 Like all input command parameters, the filename is subject to property 398 expansion as described in `Property Expansion`_. 399 400``playlist-next <flags>`` 401 Go to the next entry on the playlist. 402 403 First argument: 404 405 weak (default) 406 If the last file on the playlist is currently played, do nothing. 407 force 408 Terminate playback if there are no more files on the playlist. 409 410``playlist-prev <flags>`` 411 Go to the previous entry on the playlist. 412 413 First argument: 414 415 weak (default) 416 If the first file on the playlist is currently played, do nothing. 417 force 418 Terminate playback if the first file is being played. 419 420``playlist-play-index <integer|current|none>`` 421 Start (or restart) playback of the given playlist index. In addition to the 422 0-based playlist entry index, it supports the following values: 423 424 <current> 425 The current playlist entry (as in ``playlist-current-pos``) will be 426 played again (unload and reload). If none is set, playback is stopped. 427 (In corner cases, ``playlist-current-pos`` can point to a playlist entry 428 even if playback is currently inactive, 429 430 <none> 431 Playback is stopped. If idle mode (``--idle``) is enabled, the player 432 will enter idle mode, otherwise it will exit. 433 434 This comm and is similar to ``loadfile`` in that it only manipulates the 435 state of what to play next, without waiting until the current file is 436 unloaded, and the next one is loaded. 437 438 Setting ``playlist-pos`` or similar properties can have a similar effect to 439 this command. However, it's more explicit, and guarantees that playback is 440 restarted if for example the new playlist entry is the same as the previous 441 one. 442 443``loadfile <url> [<flags> [<options>]]`` 444 Load the given file or URL and play it. Technically, this is just a playlist 445 manipulation command (which either replaces the playlist or appends an entry 446 to it). Actual file loading happens independently. For example, a 447 ``loadfile`` command that replaces the current file with a new one returns 448 before the current file is stopped, and the new file even begins loading. 449 450 Second argument: 451 452 <replace> (default) 453 Stop playback of the current file, and play the new file immediately. 454 <append> 455 Append the file to the playlist. 456 <append-play> 457 Append the file, and if nothing is currently playing, start playback. 458 (Always starts with the added file, even if the playlist was not empty 459 before running this command.) 460 461 The third argument is a list of options and values which should be set 462 while the file is playing. It is of the form ``opt1=value1,opt2=value2,..``. 463 When using the client API, this can be a ``MPV_FORMAT_NODE_MAP`` (or a Lua 464 table), however the values themselves must be strings currently. These 465 options are set during playback, and restored to the previous value at end 466 of playback (see `Per-File Options`_). 467 468``loadlist <url> [<flags>]`` 469 Load the given playlist file or URL (like ``--playlist``). 470 471 Second argument: 472 473 <replace> (default) 474 Stop playback and replace the internal playlist with the new one. 475 <append> 476 Append the new playlist at the end of the current internal playlist. 477 <append-play> 478 Append the new playlist, and if nothing is currently playing, start 479 playback. (Always starts with the new playlist, even if the internal 480 playlist was not empty before running this command.) 481 482``playlist-clear`` 483 Clear the playlist, except the currently played file. 484 485``playlist-remove <index>`` 486 Remove the playlist entry at the given index. Index values start counting 487 with 0. The special value ``current`` removes the current entry. Note that 488 removing the current entry also stops playback and starts playing the next 489 entry. 490 491``playlist-move <index1> <index2>`` 492 Move the playlist entry at index1, so that it takes the place of the 493 entry index2. (Paradoxically, the moved playlist entry will not have 494 the index value index2 after moving if index1 was lower than index2, 495 because index2 refers to the target entry, not the index the entry 496 will have after moving.) 497 498``playlist-shuffle`` 499 Shuffle the playlist. This is similar to what is done on start if the 500 ``--shuffle`` option is used. 501 502``playlist-unshuffle`` 503 Attempt to revert the previous ``playlist-shuffle`` command. This works 504 only once (multiple successive ``playlist-unshuffle`` commands do nothing). 505 May not work correctly if new recursive playlists have been opened since 506 a ``playlist-shuffle`` command. 507 508``run <command> [<arg1> [<arg2> [...]]]`` 509 Run the given command. Unlike in MPlayer/mplayer2 and earlier versions of 510 mpv (0.2.x and older), this doesn't call the shell. Instead, the command 511 is run directly, with each argument passed separately. Each argument is 512 expanded like in `Property Expansion`_. 513 514 This command has a variable number of arguments, and cannot be used with 515 named arguments. 516 517 The program is run in a detached way. mpv doesn't wait until the command 518 is completed, but continues playback right after spawning it. 519 520 To get the old behavior, use ``/bin/sh`` and ``-c`` as the first two 521 arguments. 522 523 .. admonition:: Example 524 525 ``run "/bin/sh" "-c" "echo ${title} > /tmp/playing"`` 526 527 This is not a particularly good example, because it doesn't handle 528 escaping, and a specially prepared file might allow an attacker to 529 execute arbitrary shell commands. It is recommended to write a small 530 shell script, and call that with ``run``. 531 532``subprocess`` 533 Similar to ``run``, but gives more control about process execution to the 534 caller, and does does not detach the process. 535 536 You can avoid blocking until the process terminates by running this command 537 asynchronously. (For example ``mp.command_native_async()`` in Lua scripting.) 538 539 This has the following named arguments. The order of them is not guaranteed, 540 so you should always call them with named arguments, see `Named arguments`_. 541 542 ``args`` (``MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING]``) 543 Array of strings with the command as first argument, and subsequent 544 command line arguments following. This is just like the ``run`` command 545 argument list. 546 547 The first array entry is either an absolute path to the executable, or 548 a filename with no path components, in which case the executable is 549 searched in the directories in the ``PATH`` environment variable. On 550 Unix, this is equivalent to ``posix_spawnp`` and ``execvp`` behavior. 551 552 ``playback_only`` (``MPV_FORMAT_FLAG``) 553 Boolean indicating whether the process should be killed when playback 554 terminates (optional, default: true). If enabled, stopping playback 555 will automatically kill the process, and you can't start it outside of 556 playback. 557 558 ``capture_size`` (``MPV_FORMAT_INT64``) 559 Integer setting the maximum number of stdout plus stderr bytes that can 560 be captured (optional, default: 64MB). If the number of bytes exceeds 561 this, capturing is stopped. The limit is per captured stream. 562 563 ``capture_stdout`` (``MPV_FORMAT_FLAG``) 564 Capture all data the process outputs to stdout and return it once the 565 process ends (optional, default: no). 566 567 ``capture_stderr`` (``MPV_FORMAT_FLAG``) 568 Same as ``capture_stdout``, but for stderr. 569 570 ``detach`` (``MPV_FORMAT_FLAG``) 571 Whether to run the process in detached mode (optional, default: no). In 572 this mode, the process is run in a new process session, and the command 573 does not wait for the process to terminate. If neither 574 ``capture_stdout`` nor ``capture_stderr`` have been set to true, 575 the command returns immediately after the new process has been started, 576 otherwise the command will read as long as the pipes are open. 577 578 ``env`` (``MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING]``) 579 Set a list of environment variables for the new process (default: empty). 580 If an empty list is passed, the environment of the mpv process is used 581 instead. (Unlike the underlying OS mechanisms, the mpv command cannot 582 start a process with empty environment. Fortunately, that is completely 583 useless.) The format of the list is as in the ``execle()`` syscall. Each 584 string item defines an environment variable as in ``NANME=VALUE``. 585 586 On Lua, you may use ``utils.get_env_list()`` to retrieve the current 587 environment if you e.g. simply want to add a new variable. 588 589 ``stdin_data`` (``MPV_FORMAT_STRING``) 590 Feed the given string to the new process' stdin. Since this is a string, 591 you cannot pass arbitrary binary data. If the process terminates or 592 closes the pipe before all data is written, the remaining data is 593 silently discarded. Probably does not work on win32. 594 595 ``passthrough_stdin`` (``MPV_FORMAT_FLAG``) 596 If enabled, wire the new process' stdin to mpv's stdin (default: no). 597 Before mpv 0.33.0, this argument did not exist, but the behavior was as 598 if this was set to true. 599 600 The command returns the following result (as ``MPV_FORMAT_NODE_MAP``): 601 602 ``status`` (``MPV_FORMAT_INT64``) 603 The raw exit status of the process. It will be negative on error. The 604 meaning of negative values is undefined, other than meaning error (and 605 does not correspond to OS low level exit status values). 606 607 On Windows, it can happen that a negative return value is returned 608 even if the process exits gracefully, because the win32 ``UINT`` exit 609 code is assigned to an ``int`` variable before being set as ``int64_t`` 610 field in the result map. This might be fixed later. 611 612 ``stdout`` (``MPV_FORMAT_BYTE_ARRAY``) 613 Captured stdout stream, limited to ``capture_size``. 614 615 ``stderr`` (``MPV_FORMAT_BYTE_ARRAY``) 616 Same as ``stdout``, but for stderr. 617 618 ``error_string`` (``MPV_FORMAT_STRING``) 619 Empty string if the process exited gracefully. The string ``killed`` if 620 the process was terminated in an unusual way. The string ``init`` if the 621 process could not be started. 622 623 On Windows, ``killed`` is only returned when the process has been 624 killed by mpv as a result of ``playback_only`` being set to true. 625 626 ``killed_by_us`` (``MPV_FORMAT_FLAG``) 627 Whether the process has been killed by mpv, for example as a result of 628 ``playback_only`` being set to true, aborting the command (e.g. by 629 ``mp.abort_async_command()``), or if the player is about to exit. 630 631 Note that the command itself will always return success as long as the 632 parameters are correct. Whether the process could be spawned or whether 633 it was somehow killed or returned an error status has to be queried from 634 the result value. 635 636 This command can be asynchronously aborted via API. 637 638 In all cases, the subprocess will be terminated on player exit. Also see 639 `Asynchronous command details`_. Only the ``run`` command can start 640 processes in a truly detached way. 641 642 .. admonition:: Warning 643 644 Don't forget to set the ``playback_only`` field if you want the command 645 run while the player is in idle mode, or if you don't want that end of 646 playback kills the command. 647 648 .. admonition:: Example 649 650 :: 651 652 local r = mp.command_native({ 653 name = "subprocess", 654 playback_only = false, 655 capture_stdout = true, 656 args = {"cat", "/proc/cpuinfo"}, 657 }) 658 if r.status == 0 then 659 print("result: " .. r.stdout) 660 end 661 662 This is a fairly useless Lua example, which demonstrates how to run 663 a process in a blocking manner, and retrieving its stdout output. 664 665``quit [<code>]`` 666 Exit the player. If an argument is given, it's used as process exit code. 667 668``quit-watch-later [<code>]`` 669 Exit player, and store current playback position. Playing that file later 670 will seek to the previous position on start. The (optional) argument is 671 exactly as in the ``quit`` command. 672 673``sub-add <url> [<flags> [<title> [<lang>]]]`` 674 Load the given subtitle file or stream. By default, it is selected as 675 current subtitle after loading. 676 677 The ``flags`` argument is one of the following values: 678 679 <select> 680 681 Select the subtitle immediately (default). 682 683 <auto> 684 685 Don't select the subtitle. (Or in some special situations, let the 686 default stream selection mechanism decide.) 687 688 <cached> 689 690 Select the subtitle. If a subtitle with the same filename was already 691 added, that one is selected, instead of loading a duplicate entry. 692 (In this case, title/language are ignored, and if the was changed since 693 it was loaded, these changes won't be reflected.) 694 695 The ``title`` argument sets the track title in the UI. 696 697 The ``lang`` argument sets the track language, and can also influence 698 stream selection with ``flags`` set to ``auto``. 699 700``sub-remove [<id>]`` 701 Remove the given subtitle track. If the ``id`` argument is missing, remove 702 the current track. (Works on external subtitle files only.) 703 704``sub-reload [<id>]`` 705 Reload the given subtitle tracks. If the ``id`` argument is missing, reload 706 the current track. (Works on external subtitle files only.) 707 708 This works by unloading and re-adding the subtitle track. 709 710``sub-step <skip> <flags>`` 711 Change subtitle timing such, that the subtitle event after the next 712 ``<skip>`` subtitle events is displayed. ``<skip>`` can be negative to step 713 backwards. 714 715 Secondary argument: 716 717 primary (default) 718 Steps through the primary subtitles. 719 secondary 720 Steps through the secondary subtitles. 721 722``sub-seek <skip> <flags>`` 723 Seek to the next (skip set to 1) or the previous (skip set to -1) subtitle. 724 This is similar to ``sub-step``, except that it seeks video and audio 725 instead of adjusting the subtitle delay. 726 727 Secondary argument: 728 729 primary (default) 730 Seeks through the primary subtitles. 731 secondary 732 Seeks through the secondary subtitles. 733 734 For embedded subtitles (like with Matroska), this works only with subtitle 735 events that have already been displayed, or are within a short prefetch 736 range. 737 738``print-text <text>`` 739 Print text to stdout. The string can contain properties (see 740 `Property Expansion`_). Take care to put the argument in quotes. 741 742``show-text <text> [<duration>|-1 [<level>]]`` 743 Show text on the OSD. The string can contain properties, which are expanded 744 as described in `Property Expansion`_. This can be used to show playback 745 time, filename, and so on. 746 747 <duration> 748 The time in ms to show the message for. By default, it uses the same 749 value as ``--osd-duration``. 750 751 <level> 752 The minimum OSD level to show the text at (see ``--osd-level``). 753 754``expand-text <string>`` 755 Property-expand the argument and return the expanded string. This can be 756 used only through the client API or from a script using 757 ``mp.command_native``. (see `Property Expansion`_). 758 759``expand-path "<string>"`` 760 Expand a path's double-tilde placeholders into a platform-specific path. 761 As ``expand-text``, this can only be used through the client API or from 762 a script using ``mp.command_native``. 763 764 .. admonition:: Example 765 766 ``mp.osd_message(mp.command_native({"expand-path", "~~home/"}))`` 767 768 This line of Lua would show the location of the user's mpv 769 configuration directory on the OSD. 770 771``show-progress`` 772 Show the progress bar, the elapsed time and the total duration of the file 773 on the OSD. 774 775``write-watch-later-config`` 776 Write the resume config file that the ``quit-watch-later`` command writes, 777 but continue playback normally. 778 779``delete-watch-later-config [<filename>]`` 780 Delete any existing resume config file that was written by 781 ``quit-watch-later`` or ``write-watch-later-config``. If a filename is 782 specified, then the deleted config is for that file; otherwise, it is the 783 same one as would be written by ``quit-watch-later`` or 784 ``write-watch-later-config`` in the current circumstance. 785 786``stop [<flags>]`` 787 Stop playback and clear playlist. With default settings, this is 788 essentially like ``quit``. Useful for the client API: playback can be 789 stopped without terminating the player. 790 791 The first argument is optional, and supports the following flags: 792 793 keep-playlist 794 Do not clear the playlist. 795 796 797``mouse <x> <y> [<button> [<mode>]]`` 798 Send a mouse event with given coordinate (``<x>``, ``<y>``). 799 800 Second argument: 801 802 <button> 803 The button number of clicked mouse button. This should be one of 0-19. 804 If ``<button>`` is omitted, only the position will be updated. 805 806 Third argument: 807 808 <single> (default) 809 The mouse event represents regular single click. 810 811 <double> 812 The mouse event represents double-click. 813 814``keypress <name>`` 815 Send a key event through mpv's input handler, triggering whatever 816 behavior is configured to that key. ``name`` uses the ``input.conf`` 817 naming scheme for keys and modifiers. Useful for the client API: key events 818 can be sent to libmpv to handle internally. 819 820``keydown <name>`` 821 Similar to ``keypress``, but sets the ``KEYDOWN`` flag so that if the key is 822 bound to a repeatable command, it will be run repeatedly with mpv's key 823 repeat timing until the ``keyup`` command is called. 824 825``keyup [<name>]`` 826 Set the ``KEYUP`` flag, stopping any repeated behavior that had been 827 triggered. ``name`` is optional. If ``name`` is not given or is an 828 empty string, ``KEYUP`` will be set on all keys. Otherwise, ``KEYUP`` will 829 only be set on the key specified by ``name``. 830 831``keybind <name> <command>`` 832 Binds a key to an input command. ``command`` must be a complete command 833 containing all the desired arguments and flags. Both ``name`` and 834 ``command`` use the ``input.conf`` naming scheme. This is primarily 835 useful for the client API. 836 837``audio-add <url> [<flags> [<title> [<lang>]]]`` 838 Load the given audio file. See ``sub-add`` command. 839 840``audio-remove [<id>]`` 841 Remove the given audio track. See ``sub-remove`` command. 842 843``audio-reload [<id>]`` 844 Reload the given audio tracks. See ``sub-reload`` command. 845 846``video-add <url> [<flags> [<title> [<lang> [<albumart>]]]]`` 847 Load the given video file. See ``sub-add`` command for common options. 848 849 ``albumart`` (``MPV_FORMAT_FLAG``) 850 If enabled, mpv will load the given video as album art. 851 852``video-remove [<id>]`` 853 Remove the given video track. See ``sub-remove`` command. 854 855``video-reload [<id>]`` 856 Reload the given video tracks. See ``sub-reload`` command. 857 858``rescan-external-files [<mode>]`` 859 Rescan external files according to the current ``--sub-auto``, 860 ``--audio-file-auto`` and ``--cover-art-auto`` settings. This can be used 861 to auto-load external files *after* the file was loaded. 862 863 The ``mode`` argument is one of the following: 864 865 <reselect> (default) 866 Select the default audio and subtitle streams, which typically selects 867 external files with the highest preference. (The implementation is not 868 perfect, and could be improved on request.) 869 870 <keep-selection> 871 Do not change current track selections. 872 873 874Input Commands that are Possibly Subject to Change 875-------------------------------------------------- 876 877``af <operation> <value>`` 878 Change audio filter chain. See ``vf`` command. 879 880``vf <operation> <value>`` 881 Change video filter chain. 882 883 The semantics are exactly the same as with option parsing (see 884 `VIDEO FILTERS`_). As such the text below is a redundant and incomplete 885 summary. 886 887 The first argument decides what happens: 888 889 <set> 890 Overwrite the previous filter chain with the new one. 891 892 <add> 893 Append the new filter chain to the previous one. 894 895 <toggle> 896 Check if the given filter (with the exact parameters) is already in the 897 video chain. If it is, remove the filter. If it isn't, add the filter. 898 (If several filters are passed to the command, this is done for 899 each filter.) 900 901 A special variant is combining this with labels, and using ``@name`` 902 without filter name and parameters as filter entry. This toggles the 903 enable/disable flag. 904 905 <remove> 906 Like ``toggle``, but always remove the given filter from the chain. 907 908 <del> 909 Remove the given filters from the video chain. Unlike in the other 910 cases, the second parameter is a comma separated list of filter names 911 or integer indexes. ``0`` would denote the first filter. Negative 912 indexes start from the last filter, and ``-1`` denotes the last 913 filter. Deprecated, use ``remove``. 914 915 <clr> 916 Remove all filters. Note that like the other sub-commands, this does 917 not control automatically inserted filters. 918 919 The argument is always needed. E.g. in case of ``clr`` use ``vf clr ""``. 920 921 You can assign labels to filter by prefixing them with ``@name:`` (where 922 ``name`` is a user-chosen arbitrary identifier). Labels can be used to 923 refer to filters by name in all of the filter chain modification commands. 924 For ``add``, using an already used label will replace the existing filter. 925 926 The ``vf`` command shows the list of requested filters on the OSD after 927 changing the filter chain. This is roughly equivalent to 928 ``show-text ${vf}``. Note that auto-inserted filters for format conversion 929 are not shown on the list, only what was requested by the user. 930 931 Normally, the commands will check whether the video chain is recreated 932 successfully, and will undo the operation on failure. If the command is run 933 before video is configured (can happen if the command is run immediately 934 after opening a file and before a video frame is decoded), this check can't 935 be run. Then it can happen that creating the video chain fails. 936 937 .. admonition:: Example for input.conf 938 939 - ``a vf set vflip`` turn the video upside-down on the ``a`` key 940 - ``b vf set ""`` remove all video filters on ``b`` 941 - ``c vf toggle gradfun`` toggle debanding on ``c`` 942 943 .. admonition:: Example how to toggle disabled filters at runtime 944 945 - Add something like ``vf-add=@deband:!gradfun`` to ``mpv.conf``. 946 The ``@deband:`` is the label, an arbitrary, user-given name for this 947 filter entry. The ``!`` before the filter name disables the filter by 948 default. Everything after this is the normal filter name and possibly 949 filter parameters, like in the normal ``--vf`` syntax. 950 - Add ``a vf toggle @deband`` to ``input.conf``. This toggles the 951 "disabled" flag for the filter with the label ``deband`` when the 952 ``a`` key is hit. 953 954``cycle-values [<"!reverse">] <property> <value1> [<value2> [...]]`` 955 Cycle through a list of values. Each invocation of the command will set the 956 given property to the next value in the list. The command will use the 957 current value of the property/option, and use it to determine the current 958 position in the list of values. Once it has found it, it will set the 959 next value in the list (wrapping around to the first item if needed). 960 961 This command has a variable number of arguments, and cannot be used with 962 named arguments. 963 964 The special argument ``!reverse`` can be used to cycle the value list in 965 reverse. The only advantage is that you don't need to reverse the value 966 list yourself when adding a second key binding for cycling backwards. 967 968``enable-section <name> [<flags>]`` 969 This command is deprecated, except for mpv-internal uses. 970 971 Enable all key bindings in the named input section. 972 973 The enabled input sections form a stack. Bindings in sections on the top of 974 the stack are preferred to lower sections. This command puts the section 975 on top of the stack. If the section was already on the stack, it is 976 implicitly removed beforehand. (A section cannot be on the stack more than 977 once.) 978 979 The ``flags`` parameter can be a combination (separated by ``+``) of the 980 following flags: 981 982 <exclusive> 983 All sections enabled before the newly enabled section are disabled. 984 They will be re-enabled as soon as all exclusive sections above them 985 are removed. In other words, the new section shadows all previous 986 sections. 987 <allow-hide-cursor> 988 This feature can't be used through the public API. 989 <allow-vo-dragging> 990 Same. 991 992``disable-section <name>`` 993 This command is deprecated, except for mpv-internal uses. 994 995 Disable the named input section. Undoes ``enable-section``. 996 997``define-section <name> <contents> [<flags>]`` 998 This command is deprecated, except for mpv-internal uses. 999 1000 Create a named input section, or replace the contents of an already existing 1001 input section. The ``contents`` parameter uses the same syntax as the 1002 ``input.conf`` file (except that using the section syntax in it is not 1003 allowed), including the need to separate bindings with a newline character. 1004 1005 If the ``contents`` parameter is an empty string, the section is removed. 1006 1007 The section with the name ``default`` is the normal input section. 1008 1009 In general, input sections have to be enabled with the ``enable-section`` 1010 command, or they are ignored. 1011 1012 The last parameter has the following meaning: 1013 1014 <default> (also used if parameter omitted) 1015 Use a key binding defined by this section only if the user hasn't 1016 already bound this key to a command. 1017 <force> 1018 Always bind a key. (The input section that was made active most recently 1019 wins if there are ambiguities.) 1020 1021 This command can be used to dispatch arbitrary keys to a script or a client 1022 API user. If the input section defines ``script-binding`` commands, it is 1023 also possible to get separate events on key up/down, and relatively detailed 1024 information about the key state. The special key name ``unmapped`` can be 1025 used to match any unmapped key. 1026 1027``overlay-add <id> <x> <y> <file> <offset> <fmt> <w> <h> <stride>`` 1028 Add an OSD overlay sourced from raw data. This might be useful for scripts 1029 and applications controlling mpv, and which want to display things on top 1030 of the video window. 1031 1032 Overlays are usually displayed in screen resolution, but with some VOs, 1033 the resolution is reduced to that of the video's. You can read the 1034 ``osd-width`` and ``osd-height`` properties. At least with ``--vo-xv`` and 1035 anamorphic video (such as DVD), ``osd-par`` should be read as well, and the 1036 overlay should be aspect-compensated. 1037 1038 This has the following named arguments. The order of them is not guaranteed, 1039 so you should always call them with named arguments, see `Named arguments`_. 1040 1041 ``id`` is an integer between 0 and 63 identifying the overlay element. The 1042 ID can be used to add multiple overlay parts, update a part by using this 1043 command with an already existing ID, or to remove a part with 1044 ``overlay-remove``. Using a previously unused ID will add a new overlay, 1045 while reusing an ID will update it. 1046 1047 ``x`` and ``y`` specify the position where the OSD should be displayed. 1048 1049 ``file`` specifies the file the raw image data is read from. It can be 1050 either a numeric UNIX file descriptor prefixed with ``@`` (e.g. ``@4``), 1051 or a filename. The file will be mapped into memory with ``mmap()``, 1052 copied, and unmapped before the command returns (changed in mpv 0.18.1). 1053 1054 It is also possible to pass a raw memory address for use as bitmap memory 1055 by passing a memory address as integer prefixed with an ``&`` character. 1056 Passing the wrong thing here will crash the player. This mode might be 1057 useful for use with libmpv. The ``offset`` parameter is simply added to the 1058 memory address (since mpv 0.8.0, ignored before). 1059 1060 ``offset`` is the byte offset of the first pixel in the source file. 1061 (The current implementation always mmap's the whole file from position 0 to 1062 the end of the image, so large offsets should be avoided. Before mpv 0.8.0, 1063 the offset was actually passed directly to ``mmap``, but it was changed to 1064 make using it easier.) 1065 1066 ``fmt`` is a string identifying the image format. Currently, only ``bgra`` 1067 is defined. This format has 4 bytes per pixels, with 8 bits per component. 1068 The least significant 8 bits are blue, and the most significant 8 bits 1069 are alpha (in little endian, the components are B-G-R-A, with B as first 1070 byte). This uses premultiplied alpha: every color component is already 1071 multiplied with the alpha component. This means the numeric value of each 1072 component is equal to or smaller than the alpha component. (Violating this 1073 rule will lead to different results with different VOs: numeric overflows 1074 resulting from blending broken alpha values is considered something that 1075 shouldn't happen, and consequently implementations don't ensure that you 1076 get predictable behavior in this case.) 1077 1078 ``w``, ``h``, and ``stride`` specify the size of the overlay. ``w`` is the 1079 visible width of the overlay, while ``stride`` gives the width in bytes in 1080 memory. In the simple case, and with the ``bgra`` format, ``stride==4*w``. 1081 In general, the total amount of memory accessed is ``stride * h``. 1082 (Technically, the minimum size would be ``stride * (h - 1) + w * 4``, but 1083 for simplicity, the player will access all ``stride * h`` bytes.) 1084 1085 .. note:: 1086 1087 Before mpv 0.18.1, you had to do manual "double buffering" when updating 1088 an overlay by replacing it with a different memory buffer. Since mpv 1089 0.18.1, the memory is simply copied and doesn't reference any of the 1090 memory indicated by the command's arguments after the commend returns. 1091 If you want to use this command before mpv 0.18.1, reads the old docs 1092 to see how to handle this correctly. 1093 1094``overlay-remove <id>`` 1095 Remove an overlay added with ``overlay-add`` and the same ID. Does nothing 1096 if no overlay with this ID exists. 1097 1098``osd-overlay`` 1099 Add/update/remove an OSD overlay. 1100 1101 (Although this sounds similar to ``overlay-add``, ``osd-overlay`` is for 1102 text overlays, while ``overlay-add`` is for bitmaps. Maybe ``overlay-add`` 1103 will be merged into ``osd-overlay`` to remove this oddity.) 1104 1105 You can use this to add text overlays in ASS format. ASS has advanced 1106 positioning and rendering tags, which can be used to render almost any kind 1107 of vector graphics. 1108 1109 This command accepts the following parameters: 1110 1111 ``id`` 1112 Arbitrary integer that identifies the overlay. Multiple overlays can be 1113 added by calling this command with different ``id`` parameters. Calling 1114 this command with the same ``id`` replaces the previously set overlay. 1115 1116 There is a separate namespace for each libmpv client (i.e. IPC 1117 connection, script), so IDs can be made up and assigned by the API user 1118 without conflicting with other API users. 1119 1120 If the libmpv client is destroyed, all overlays associated with it are 1121 also deleted. In particular, connecting via ``--input-ipc-server``, 1122 adding an overlay, and disconnecting will remove the overlay immediately 1123 again. 1124 1125 ``format`` 1126 String that gives the type of the overlay. Accepts the following values 1127 (HTML rendering of this is broken, view the generated manpage instead, 1128 or the raw RST source): 1129 1130 ``ass-events`` 1131 The ``data`` parameter is a string. The string is split on the 1132 newline character. Every line is turned into the ``Text`` part of 1133 a ``Dialogue`` ASS event. Timing is unused (but behavior of timing 1134 dependent ASS tags may change in future mpv versions). 1135 1136 Note that it's better to put multiple lines into ``data``, instead 1137 of adding multiple OSD overlays. 1138 1139 This provides 2 ASS ``Styles``. ``OSD`` contains the text style as 1140 defined by the current ``--osd-...`` options. ``Default`` is 1141 similar, and contains style that ``OSD`` would have if all options 1142 were set to the default. 1143 1144 In addition, the ``res_x`` and ``res_y`` options specify the value 1145 of the ASS ``PlayResX`` and ``PlayResY`` header fields. If ``res_y`` 1146 is set to 0, ``PlayResY`` is initialized to an arbitrary default 1147 value (but note that the default for this command is 720, not 0). 1148 If ``res_x`` is set to 0, ``PlayResX`` is set based on ``res_y`` 1149 such that a virtual ASS pixel has a square pixel aspect ratio. 1150 1151 ``none`` 1152 Special value that causes the overlay to be removed. Most parameters 1153 other than ``id`` and ``format`` are mostly ignored. 1154 1155 ``data`` 1156 String defining the overlay contents according to the ``format`` 1157 parameter. 1158 1159 ``res_x``, ``res_y`` 1160 Used if ``format`` is set to ``ass-events`` (see description there). 1161 Optional, defaults to 0/720. 1162 1163 ``z`` 1164 The Z order of the overlay. Optional, defaults to 0. 1165 1166 Note that Z order between different overlays of different formats is 1167 static, and cannot be changed (currently, this means that bitmap 1168 overlays added by ``overlay-add`` are always on top of the ASS overlays 1169 added by ``osd-overlay``). In addition, the builtin OSD components are 1170 always below any of the custom OSD. (This includes subtitles of any kind 1171 as well as text rendered by ``show-text``.) 1172 1173 It's possible that future mpv versions will randomly change how Z order 1174 between different OSD formats and builtin OSD is handled. 1175 1176 ``hidden`` 1177 If set to true, do not display this (default: false). 1178 1179 ``compute_bounds`` 1180 If set to true, attempt to determine bounds and write them to the 1181 command's result value as ``x0``, ``x1``, ``y0``, ``y1`` rectangle 1182 (default: false). If the rectangle is empty, not known, or somehow 1183 degenerate, it is not set. ``x1``/``y1`` is the coordinate of the 1184 bottom exclusive corner of the rectangle. 1185 1186 The result value may depend on the VO window size, and is based on the 1187 last known window size at the time of the call. This means the results 1188 may be different from what is actually rendered. 1189 1190 For ``ass-events``, the result rectangle is recomputed to ``PlayRes`` 1191 coordinates (``res_x``/``res_y``). If window size is not known, a 1192 fallback is chosen. 1193 1194 You should be aware that this mechanism is very inefficient, as it 1195 renders the full result, and then uses the bounding box of the rendered 1196 bitmap list (even if ``hidden`` is set). It will flush various caches. 1197 Its results also depend on the used libass version. 1198 1199 This feature is experimental, and may change in some way again. 1200 1201 .. note:: 1202 1203 Always use named arguments (``mpv_command_node()``). Lua scripts should 1204 use the ``mp.create_osd_overlay()`` helper instead of invoking this 1205 command directly. 1206 1207``script-message [<arg1> [<arg2> [...]]]`` 1208 Send a message to all clients, and pass it the following list of arguments. 1209 What this message means, how many arguments it takes, and what the arguments 1210 mean is fully up to the receiver and the sender. Every client receives the 1211 message, so be careful about name clashes (or use ``script-message-to``). 1212 1213 This command has a variable number of arguments, and cannot be used with 1214 named arguments. 1215 1216``script-message-to <target> [<arg1> [<arg2> [...]]]`` 1217 Same as ``script-message``, but send it only to the client named 1218 ``<target>``. Each client (scripts etc.) has a unique name. For example, 1219 Lua scripts can get their name via ``mp.get_script_name()``. Note that 1220 client names only consist of alphanumeric characters and ``_``. 1221 1222 This command has a variable number of arguments, and cannot be used with 1223 named arguments. 1224 1225``script-binding <name>`` 1226 Invoke a script-provided key binding. This can be used to remap key 1227 bindings provided by external Lua scripts. 1228 1229 The argument is the name of the binding. 1230 1231 It can optionally be prefixed with the name of the script, using ``/`` as 1232 separator, e.g. ``script-binding scriptname/bindingname``. Note that script 1233 names only consist of alphanumeric characters and ``_``. 1234 1235 For completeness, here is how this command works internally. The details 1236 could change any time. On any matching key event, ``script-message-to`` 1237 or ``script-message`` is called (depending on whether the script name is 1238 included), with the following arguments: 1239 1240 1. The string ``key-binding``. 1241 2. The name of the binding (as established above). 1242 3. The key state as string (see below). 1243 4. The key name (since mpv 0.15.0). 1244 5. The text the key would produce, or empty string if not applicable. 1245 1246 The 5th argument is only set if no modifiers are present (using the shift 1247 key with a letter is normally not emitted as having a modifier, and results 1248 in upper case text instead, but some backends may mess up). 1249 1250 The key state consists of 2 characters: 1251 1252 1. One of ``d`` (key was pressed down), ``u`` (was released), ``r`` (key 1253 is still down, and was repeated; only if key repeat is enabled for this 1254 binding), ``p`` (key was pressed; happens if up/down can't be tracked). 1255 2. Whether the event originates from the mouse, either ``m`` (mouse button) 1256 or ``-`` (something else). 1257 1258 Future versions can add more arguments and more key state characters to 1259 support more input peculiarities. 1260 1261``ab-loop`` 1262 Cycle through A-B loop states. The first command will set the ``A`` point 1263 (the ``ab-loop-a`` property); the second the ``B`` point, and the third 1264 will clear both points. 1265 1266``drop-buffers`` 1267 Drop audio/video/demuxer buffers, and restart from fresh. Might help with 1268 unseekable streams that are going out of sync. 1269 This command might be changed or removed in the future. 1270 1271``screenshot-raw [<flags>]`` 1272 Return a screenshot in memory. This can be used only through the client 1273 API. The MPV_FORMAT_NODE_MAP returned by this command has the ``w``, ``h``, 1274 ``stride`` fields set to obvious contents. The ``format`` field is set to 1275 ``bgr0`` by default. This format is organized as ``B8G8R8X8`` (where ``B`` 1276 is the LSB). The contents of the padding ``X`` are undefined. The ``data`` 1277 field is of type MPV_FORMAT_BYTE_ARRAY with the actual image data. The image 1278 is freed as soon as the result mpv_node is freed. As usual with client API 1279 semantics, you are not allowed to write to the image data. 1280 1281 The ``stride`` is the number of bytes from a pixel at ``(x0, y0)`` to the 1282 pixel at ``(x0, y0 + 1)``. This can be larger than ``w * 4`` if the image 1283 was cropped, or if there is padding. This number can be negative as well. 1284 You access a pixel with ``byte_index = y * stride + x * 4`` (assuming the 1285 ``bgr0`` format). 1286 1287 The ``flags`` argument is like the first argument to ``screenshot`` and 1288 supports ``subtitles``, ``video``, ``window``. 1289 1290``vf-command <label> <command> <argument>`` 1291 Send a command to the filter with the given ``<label>``. Use ``all`` to send 1292 it to all filters at once. The command and argument string is filter 1293 specific. Currently, this only works with the ``lavfi`` filter - see 1294 the libavfilter documentation for which commands a filter supports. 1295 1296 Note that the ``<label>`` is a mpv filter label, not a libavfilter filter 1297 name. 1298 1299``af-command <label> <command> <argument>`` 1300 Same as ``vf-command``, but for audio filters. 1301 1302``apply-profile <name> [<mode>]`` 1303 Apply the contents of a named profile. This is like using ``profile=name`` 1304 in a config file, except you can map it to a key binding to change it at 1305 runtime. 1306 1307 The mode argument: 1308 1309 ``default`` 1310 Apply the profile. Default if the argument is omitted. 1311 1312 ``restore`` 1313 Restore options set by a previous ``apply-profile`` command for this 1314 profile. Only works if the profile has ``profile-restore`` set to a 1315 relevant mode. Prints a warning if nothing could be done. See 1316 `Runtime profiles`_ for details. 1317 1318``load-script <filename>`` 1319 Load a script, similar to the ``--script`` option. Whether this waits for 1320 the script to finish initialization or not changed multiple times, and the 1321 future behavior is left undefined. 1322 1323 On success, returns a ``mpv_node`` with a ``client_id`` field set to the 1324 return value of the ``mpv_client_id()`` API call of the newly created script 1325 handle. 1326 1327``change-list <name> <operation> <value>`` 1328 This command changes list options as described in `List Options`_. The 1329 ``<name>`` parameter is the normal option name, while ``<operation>`` is 1330 the suffix or action used on the option. 1331 1332 Some operations take no value, but the command still requires the value 1333 parameter. In these cases, the value must be an empty string. 1334 1335 .. admonition:: Example 1336 1337 ``change-list glsl-shaders append file.glsl`` 1338 1339 Add a filename to the ``glsl-shaders`` list. The command line 1340 equivalent is ``--glsl-shaders-append=file.glsl`` or alternatively 1341 ``--glsl-shader=file.glsl``. 1342 1343``dump-cache <start> <end> <filename>`` 1344 Dump the current cache to the given filename. The ``<filename>`` file is 1345 overwritten if it already exists. ``<start>`` and ``<end>`` give the 1346 time range of what to dump. If no data is cached at the given time range, 1347 nothing may be dumped (creating a file with no packets). 1348 1349 Dumping a larger part of the cache will freeze the player. No effort was 1350 made to fix this, as this feature was meant mostly for creating small 1351 excerpts. 1352 1353 See ``--stream-record`` for various caveats that mostly apply to this 1354 command too, as both use the same underlying code for writing the output 1355 file. 1356 1357 If ``<filename>`` is an empty string, an ongoing ``dump-cache`` is stopped. 1358 1359 If ``<end>`` is ``no``, then continuous dumping is enabled. Then, after 1360 dumping the existing parts of the cache, anything read from network is 1361 appended to the cache as well. This behaves similar to ``--stream-record`` 1362 (although it does not conflict with that option, and they can be both active 1363 at the same time). 1364 1365 If the ``<end>`` time is after the cache, the command will _not_ wait and 1366 write newly received data to it. 1367 1368 The end of the resulting file may be slightly damaged or incomplete at the 1369 end. (Not enough effort was made to ensure that the end lines up properly.) 1370 1371 Note that this command will finish only once dumping ends. That means it 1372 works similar to the ``screenshot`` command, just that it can block much 1373 longer. If continuous dumping is used, the command will not finish until 1374 playback is stopped, an error happens, another ``dump-cache`` command is 1375 run, or an API like ``mp.abort_async_command`` was called to explicitly stop 1376 the command. See `Synchronous vs. Asynchronous`_. 1377 1378 .. note:: 1379 1380 This was mostly created for network streams. For local files, there may 1381 be much better methods to create excerpts and such. There are tons of 1382 much more user-friendly Lua scripts, that will reencode parts of a file 1383 by spawning a separate instance of ``ffmpeg``. With network streams, 1384 this is not that easily possible, as the stream would have to be 1385 downloaded again. Even if ``--stream-record`` is used to record the 1386 stream to the local filesystem, there may be problems, because the 1387 recorded file is still written to. 1388 1389 This command is experimental, and all details about it may change in the 1390 future. 1391 1392``ab-loop-dump-cache <filename>`` 1393 Essentially calls ``dump-cache`` with the current AB-loop points as 1394 arguments. Like ``dump-cache``, this will overwrite the file at 1395 ``<filename>``. Likewise, if the B point is set to ``no``, it will enter 1396 continuous dumping after the existing cache was dumped. 1397 1398 The author reserves the right to remove this command if enough motivation 1399 is found to move this functionality to a trivial Lua script. 1400 1401``ab-loop-align-cache`` 1402 Re-adjust the A/B loop points to the start and end within the cache the 1403 ``ab-loop-dump-cache`` command will (probably) dump. Basically, it aligns 1404 the times on keyframes. The guess might be off especially at the end (due to 1405 granularity issues due to remuxing). If the cache shrinks in the meantime, 1406 the points set by the command will not be the effective parameters either. 1407 1408 This command has an even more uncertain future than ``ab-loop-dump-cache`` 1409 and might disappear without replacement if the author decides it's useless. 1410 1411Undocumented commands: ``ao-reload`` (experimental/internal). 1412 1413List of events 1414~~~~~~~~~~~~~~ 1415 1416This is a partial list of events. This section describes what 1417``mpv_event_to_node()`` returns, and which is what scripting APIs and the JSON 1418IPC sees. Note that the C API has separate C-level declarations with 1419``mpv_event``, which may be slightly different. 1420 1421Note that events are asynchronous: the player core continues running while 1422events are delivered to scripts and other clients. In some cases, you can hooks 1423to enforce synchronous execution. 1424 1425All events can have the following fields: 1426 1427``event`` 1428 Name as the event (as returned by ``mpv_event_name()``). 1429 1430``id`` 1431 The ``reply_userdata`` field (opaque user value). If ``reply_userdata`` is 0, 1432 the field is not added. 1433 1434``error`` 1435 Set to an error string (as returned by ``mpv_error_string()``). This field 1436 is missing if no error happened, or the event type does not report error. 1437 Most events leave this unset. 1438 1439This list uses the event name field value, and the C API symbol in brackets: 1440 1441``start-file`` (``MPV_EVENT_START_FILE``) 1442 Happens right before a new file is loaded. When you receive this, the 1443 player is loading the file (or possibly already done with it). 1444 1445 This has the following fields: 1446 1447 ``playlist_entry_id`` 1448 Playlist entry ID of the file being loaded now. 1449 1450``end-file`` (``MPV_EVENT_END_FILE``) 1451 Happens after a file was unloaded. Typically, the player will load the 1452 next file right away, or quit if this was the last file. 1453 1454 The event has the following fields: 1455 1456 ``reason`` 1457 Has one of these values: 1458 1459 ``eof`` 1460 The file has ended. This can (but doesn't have to) include 1461 incomplete files or broken network connections under 1462 circumstances. 1463 1464 ``stop`` 1465 Playback was ended by a command. 1466 1467 ``quit`` 1468 Playback was ended by sending the quit command. 1469 1470 ``error`` 1471 An error happened. In this case, an ``error`` field is present with 1472 the error string. 1473 1474 ``redirect`` 1475 Happens with playlists and similar. Details see 1476 ``MPV_END_FILE_REASON_REDIRECT`` in the C API. 1477 1478 ``unknown`` 1479 Unknown. Normally doesn't happen, unless the Lua API is out of sync 1480 with the C API. (Likewise, it could happen that your script gets 1481 reason strings that did not exist yet at the time your script was 1482 written.) 1483 1484 ``playlist_entry_id`` 1485 Playlist entry ID of the file that was being played or attempted to be 1486 played. This has the same value as the ``playlist_entry_id`` field in the 1487 corresponding ``start-file`` event. 1488 1489 ``file_error`` 1490 Set to mpv error string describing the approximate reason why playback 1491 failed. Unset if no error known. (In Lua scripting, this value was set 1492 on the ``error`` field directly. This is deprecated since mpv 0.33.0. 1493 In the future, this ``error`` field will be unset for this specific 1494 event.) 1495 1496 ``playlist_insert_id`` 1497 If loading ended, because the playlist entry to be played was for example 1498 a playlist, and the current playlist entry is replaced with a number of 1499 other entries. This may happen at least with MPV_END_FILE_REASON_REDIRECT 1500 (other event types may use this for similar but different purposes in the 1501 future). In this case, playlist_insert_id will be set to the playlist 1502 entry ID of the first inserted entry, and playlist_insert_num_entries to 1503 the total number of inserted playlist entries. Note this in this specific 1504 case, the ID of the last inserted entry is playlist_insert_id+num-1. 1505 Beware that depending on circumstances, you may observe the new playlist 1506 entries before seeing the event (e.g. reading the "playlist" property or 1507 getting a property change notification before receiving the event). 1508 If this is 0 in the C API, this field isn't added. 1509 1510 ``playlist_insert_num_entries`` 1511 See playlist_insert_id. Only present if playlist_insert_id is present. 1512 1513``file-loaded`` (``MPV_EVENT_FILE_LOADED``) 1514 Happens after a file was loaded and begins playback. 1515 1516``seek`` (``MPV_EVENT_SEEK``) 1517 Happens on seeking. (This might include cases when the player seeks 1518 internally, even without user interaction. This includes e.g. segment 1519 changes when playing ordered chapters Matroska files.) 1520 1521``playback-restart`` (``MPV_EVENT_PLAYBACK_RESTART``) 1522 Start of playback after seek or after file was loaded. 1523 1524``shutdown`` (``MPV_EVENT_SHUTDOWN``) 1525 Sent when the player quits, and the script should terminate. Normally 1526 handled automatically. See `Details on the script initialization and lifecycle`_. 1527 1528``log-message`` (``MPV_EVENT_LOG_MESSAGE``) 1529 Receives messages enabled with ``mpv_request_log_messages()`` (Lua: 1530 ``mp.enable_messages``). 1531 1532 This contains, in addition to the default event fields, the following 1533 fields: 1534 1535 ``prefix`` 1536 The module prefix, identifies the sender of the message. This is what 1537 the terminal player puts in front of the message text when using the 1538 ``--v`` option, and is also what is used for ``--msg-level``. 1539 1540 ``level`` 1541 The log level as string. See ``msg.log`` for possible log level names. 1542 Note that later versions of mpv might add new levels or remove 1543 (undocumented) existing ones. 1544 1545 ``text`` 1546 The log message. The text will end with a newline character. Sometimes 1547 it can contain multiple lines. 1548 1549 Keep in mind that these messages are meant to be hints for humans. You 1550 should not parse them, and prefix/level/text of messages might change 1551 any time. 1552 1553``hook`` 1554 The event has the following fields: 1555 1556 ``hook_id`` 1557 ID to pass to ``mpv_hook_continue()``. The Lua scripting wrapper 1558 provides a better API around this with ``mp.add_hook()``. 1559 1560``get-property-reply`` (``MPV_EVENT_GET_PROPERTY_REPLY``) 1561 See C API. 1562 1563``set-property-reply`` (``MPV_EVENT_SET_PROPERTY_REPLY``) 1564 See C API. 1565 1566``command-reply`` (``MPV_EVENT_COMMAND_REPLY``) 1567 This is one of the commands for which the ```error`` field is meaningful. 1568 1569 JSON IPC and Lua and possibly other backends treat this specially and may 1570 not pass the actual event to the user. See C API. 1571 1572 The event has the following fields: 1573 1574 ``result`` 1575 The result (on success) of any ``mpv_node`` type, if any. 1576 1577``client-message`` (``MPV_EVENT_CLIENT_MESSAGE``) 1578 Lua and possibly other backends treat this specially and may not pass the 1579 actual event to the user. 1580 1581 The event has the following fields: 1582 1583 ``args`` 1584 Array of strings with the message data. 1585 1586``video-reconfig`` (``MPV_EVENT_VIDEO_RECONFIG``) 1587 Happens on video output or filter reconfig. 1588 1589``audio-reconfig`` (``MPV_EVENT_AUDIO_RECONFIG``) 1590 Happens on audio output or filter reconfig. 1591 1592``property-change`` (``MPV_EVENT_PROPERTY_CHANGE``) 1593 Happens when a property that is being observed changes value. 1594 1595 The event has the following fields: 1596 1597 ``name`` 1598 The name of the property. 1599 1600 ``data`` 1601 The new value of the property. 1602 1603The following events also happen, but are deprecated: ``tracks-changed``, 1604``track-switched``, ``pause``, ``unpause``, ``metadata-update``, ``idle``, 1605``tick``, ``chapter-change``. Use ``mpv_observe_property()`` 1606(Lua: ``mp.observe_property()``) instead. 1607 1608Hooks 1609~~~~~ 1610 1611Hooks are synchronous events between player core and a script or similar. This 1612applies to client API (including the Lua scripting interface). Normally, 1613events are supposed to be asynchronous, and the hook API provides an awkward 1614and obscure way to handle events that require stricter coordination. There are 1615no API stability guarantees made. Not following the protocol exactly can make 1616the player freeze randomly. Basically, nobody should use this API. 1617 1618The C API is described in the header files. The Lua API is described in the 1619Lua section. 1620 1621Before a hook is actually invoked on an API clients, it will attempt to return 1622new values for all observed properties that were changed before the hook. This 1623may make it easier for an application to set defined "barriers" between property 1624change notifications by registering hooks. (That means these hooks will have an 1625effect, even if you do nothing and make them continue immediately.) 1626 1627The following hooks are currently defined: 1628 1629``on_load`` 1630 Called when a file is to be opened, before anything is actually done. 1631 For example, you could read and write the ``stream-open-filename`` 1632 property to redirect an URL to something else (consider support for 1633 streaming sites which rarely give the user a direct media URL), or 1634 you could set per-file options with by setting the property 1635 ``file-local-options/<option name>``. The player will wait until all 1636 hooks are run. 1637 1638 Ordered after ``start-file`` and before ``playback-restart``. 1639 1640``on_load_fail`` 1641 Called after after a file has been opened, but failed to. This can be 1642 used to provide a fallback in case native demuxers failed to recognize 1643 the file, instead of always running before the native demuxers like 1644 ``on_load``. Demux will only be retried if ``stream-open-filename`` 1645 was changed. If it fails again, this hook is _not_ called again, and 1646 loading definitely fails. 1647 1648 Ordered after ``on_load``, and before ``playback-restart`` and ``end-file``. 1649 1650``on_preloaded`` 1651 Called after a file has been opened, and before tracks are selected and 1652 decoders are created. This has some usefulness if an API users wants 1653 to select tracks manually, based on the set of available tracks. It's 1654 also useful to initialize ``--lavfi-complex`` in a specific way by API, 1655 without having to "probe" the available streams at first. 1656 1657 Note that this does not yet apply default track selection. Which operations 1658 exactly can be done and not be done, and what information is available and 1659 what is not yet available yet, is all subject to change. 1660 1661 Ordered after ``on_load_fail`` etc. and before ``playback-restart``. 1662 1663``on_unload`` 1664 Run before closing a file, and before actually uninitializing 1665 everything. It's not possible to resume playback in this state. 1666 1667 Ordered before ``end-file``. Will also happen in the error case (then after 1668 ``on_load_fail``). 1669 1670``on_before_start_file`` 1671 Run before a ``start-file`` event is sent. (If any client changes the 1672 current playlist entry, or sends a quit command to the player, the 1673 corresponding event will not actually happen after the hook returns.) 1674 Useful to drain property changes before a new file is loaded. 1675 1676``on_after_end_file`` 1677 Run after an ``end-file`` event. Useful to drain property changes after a 1678 file has finished. 1679 1680Input Command Prefixes 1681---------------------- 1682 1683These prefixes are placed between key name and the actual command. Multiple 1684prefixes can be specified. They are separated by whitespace. 1685 1686``osd-auto`` 1687 Use the default behavior for this command. This is the default for 1688 ``input.conf`` commands. Some libmpv/scripting/IPC APIs do not use this as 1689 default, but use ``no-osd`` instead. 1690``no-osd`` 1691 Do not use any OSD for this command. 1692``osd-bar`` 1693 If possible, show a bar with this command. Seek commands will show the 1694 progress bar, property changing commands may show the newly set value. 1695``osd-msg`` 1696 If possible, show an OSD message with this command. Seek command show 1697 the current playback time, property changing commands show the newly set 1698 value as text. 1699``osd-msg-bar`` 1700 Combine osd-bar and osd-msg. 1701``raw`` 1702 Do not expand properties in string arguments. (Like ``"${property-name}"``.) 1703 This is the default for some libmpv/scripting/IPC APIs. 1704``expand-properties`` 1705 All string arguments are expanded as described in `Property Expansion`_. 1706 This is the default for ``input.conf`` commands. 1707``repeatable`` 1708 For some commands, keeping a key pressed doesn't run the command repeatedly. 1709 This prefix forces enabling key repeat in any case. For a list of commands: 1710 the first command determines the repeatability of the whole list (up to and 1711 including version 0.33 - a list was always repeatable). 1712``async`` 1713 Allow asynchronous execution (if possible). Note that only a few commands 1714 will support this (usually this is explicitly documented). Some commands 1715 are asynchronous by default (or rather, their effects might manifest 1716 after completion of the command). The semantics of this flag might change 1717 in the future. Set it only if you don't rely on the effects of this command 1718 being fully realized when it returns. See `Synchronous vs. Asynchronous`_. 1719``sync`` 1720 Allow synchronous execution (if possible). Normally, all commands are 1721 synchronous by default, but some are asynchronous by default for 1722 compatibility with older behavior. 1723 1724All of the osd prefixes are still overridden by the global ``--osd-level`` 1725settings. 1726 1727Synchronous vs. Asynchronous 1728---------------------------- 1729 1730The ``async`` and ``sync`` prefix matter only for how the issuer of the command 1731waits on the completion of the command. Normally it does not affect how the 1732command behaves by itself. There are the following cases: 1733 1734- Normal input.conf commands are always run asynchronously. Slow running 1735 commands are queued up or run in parallel. 1736- "Multi" input.conf commands (1 key binding, concatenated with ``;``) will be 1737 executed in order, except for commands that are async (either prefixed with 1738 ``async``, or async by default for some commands). The async commands are 1739 run in a detached manner, possibly in parallel to the remaining sync commands 1740 in the list. 1741- Normal Lua and libmpv commands (e.g. ``mpv_command()``) are run in a blocking 1742 manner, unless the ``async`` prefix is used, or the command is async by 1743 default. This means in the sync case the caller will block, even if the core 1744 continues playback. Async mode runs the command in a detached manner. 1745- Async libmpv command API (e.g. ``mpv_command_async()``) never blocks the 1746 caller, and always notify their completion with a message. The ``sync`` and 1747 ``async`` prefixes make no difference. 1748- Lua also provides APIs for running async commands, which behave similar to the 1749 C counterparts. 1750- In all cases, async mode can still run commands in a synchronous manner, even 1751 in detached mode. This can for example happen in cases when a command does not 1752 have an asynchronous implementation. The async libmpv API still never blocks 1753 the caller in these cases. 1754 1755Before mpv 0.29.0, the ``async`` prefix was only used by screenshot commands, 1756and made them run the file saving code in a detached manner. This is the 1757default now, and ``async`` changes behavior only in the ways mentioned above. 1758 1759Currently the following commands have different waiting characteristics with 1760sync vs. async: sub-add, audio-add, sub-reload, audio-reload, 1761rescan-external-files, screenshot, screenshot-to-file, dump-cache, 1762ab-loop-dump-cache. 1763 1764Asynchronous command details 1765---------------------------- 1766 1767On the API level, every asynchronous command is bound to the context which 1768started it. For example, an asynchronous command started by ``mpv_command_async`` 1769is bound to the ``mpv_handle`` passed to the function. Only this ``mpv_handle`` 1770receives the completion notification (``MPV_EVENT_COMMAND_REPLY``), and only 1771this handle can abort a still running command directly. If the ``mpv_handle`` is 1772destroyed, any still running async. commands started by it are terminated. 1773 1774The scripting APIs and JSON IPC give each script/connection its own implicit 1775``mpv_handle``. 1776 1777If the player is closed, the core may abort all pending async. commands on its 1778own (like a forced ``mpv_abort_async_command()`` call for each pending command 1779on behalf of the API user). This happens at the same time ``MPV_EVENT_SHUTDOWN`` 1780is sent, and there is no way to prevent this. 1781 1782Input Sections 1783-------------- 1784 1785Input sections group a set of bindings, and enable or disable them at once. 1786In ``input.conf``, each key binding is assigned to an input section, rather 1787than actually having explicit text sections. 1788 1789See also: ``enable-section`` and ``disable-section`` commands. 1790 1791Predefined bindings: 1792 1793``default`` 1794 Bindings without input section are implicitly assigned to this section. It 1795 is enabled by default during normal playback. 1796``encode`` 1797 Section which is active in encoding mode. It is enabled exclusively, so 1798 that bindings in the ``default`` sections are ignored. 1799 1800Properties 1801---------- 1802 1803Properties are used to set mpv options during runtime, or to query arbitrary 1804information. They can be manipulated with the ``set``/``add``/``cycle`` 1805commands, and retrieved with ``show-text``, or anything else that uses property 1806expansion. (See `Property Expansion`_.) 1807 1808The property name is annotated with RW to indicate whether the property is 1809generally writable. 1810 1811If an option is referenced, the property will normally take/return exactly the 1812same values as the option. In these cases, properties are merely a way to change 1813an option at runtime. 1814 1815Property list 1816------------- 1817 1818.. note:: 1819 1820 Most options can be set as runtime via properties as well. Just remove the 1821 leading ``--`` from the option name. These are not documented below, see 1822 `OPTIONS`_ instead. Only properties which do not exist as option with the 1823 same name, or which have very different behavior from the options are 1824 documented below. 1825 1826 Properties marked as (RW) are writeable, while those that aren't are 1827 read-only. 1828 1829``audio-speed-correction``, ``video-speed-correction`` 1830 Factor multiplied with ``speed`` at which the player attempts to play the 1831 file. Usually it's exactly 1. (Display sync mode will make this useful.) 1832 1833 OSD formatting will display it in the form of ``+1.23456%``, with the number 1834 being ``(raw - 1) * 100`` for the given raw property value. 1835 1836``display-sync-active`` 1837 Whether ``--video-sync=display`` is actually active. 1838 1839``filename`` 1840 Currently played file, with path stripped. If this is an URL, try to undo 1841 percent encoding as well. (The result is not necessarily correct, but 1842 looks better for display purposes. Use the ``path`` property to get an 1843 unmodified filename.) 1844 1845 This has a sub-property: 1846 1847 ``filename/no-ext`` 1848 Like the ``filename`` property, but if the text contains a ``.``, strip 1849 all text after the last ``.``. Usually this removes the file extension. 1850 1851``file-size`` 1852 Length in bytes of the source file/stream. (This is the same as 1853 ``${stream-end}``. For segmented/multi-part files, this will return the 1854 size of the main or manifest file, whatever it is.) 1855 1856``estimated-frame-count`` 1857 Total number of frames in current file. 1858 1859 .. note:: This is only an estimate. (It's computed from two unreliable 1860 quantities: fps and stream length.) 1861 1862``estimated-frame-number`` 1863 Number of current frame in current stream. 1864 1865 .. note:: This is only an estimate. (It's computed from two unreliable 1866 quantities: fps and possibly rounded timestamps.) 1867 1868``pid`` 1869 Process-id of mpv. 1870 1871``path`` 1872 Full path of the currently played file. Usually this is exactly the same 1873 string you pass on the mpv command line or the ``loadfile`` command, even 1874 if it's a relative path. If you expect an absolute path, you will have to 1875 determine it yourself, for example by using the ``working-directory`` 1876 property. 1877 1878``stream-open-filename`` 1879 The full path to the currently played media. This is different from 1880 ``path`` only in special cases. In particular, if ``--ytdl=yes`` is used, 1881 and the URL is detected by ``youtube-dl``, then the script will set this 1882 property to the actual media URL. This property should be set only during 1883 the ``on_load`` or ``on_load_fail`` hooks, otherwise it will have no effect 1884 (or may do something implementation defined in the future). The property is 1885 reset if playback of the current media ends. 1886 1887``media-title`` 1888 If the currently played file has a ``title`` tag, use that. 1889 1890 Otherwise, return the ``filename`` property. 1891 1892``file-format`` 1893 Symbolic name of the file format. In some cases, this is a comma-separated 1894 list of format names, e.g. mp4 is ``mov,mp4,m4a,3gp,3g2,mj2`` (the list 1895 may grow in the future for any format). 1896 1897``current-demuxer`` 1898 Name of the current demuxer. (This is useless.) 1899 1900 (Renamed from ``demuxer``.) 1901 1902``stream-path`` 1903 Filename (full path) of the stream layer filename. (This is probably 1904 useless and is almost never different from ``path``.) 1905 1906``stream-pos`` 1907 Raw byte position in source stream. Technically, this returns the position 1908 of the most recent packet passed to a decoder. 1909 1910``stream-end`` 1911 Raw end position in bytes in source stream. 1912 1913``duration`` 1914 Duration of the current file in seconds. If the duration is unknown, the 1915 property is unavailable. Note that the file duration is not always exactly 1916 known, so this is an estimate. 1917 1918 This replaces the ``length`` property, which was deprecated after the 1919 mpv 0.9 release. (The semantics are the same.) 1920 1921``avsync`` 1922 Last A/V synchronization difference. Unavailable if audio or video is 1923 disabled. 1924 1925``total-avsync-change`` 1926 Total A-V sync correction done. Unavailable if audio or video is 1927 disabled. 1928 1929``decoder-frame-drop-count`` 1930 Video frames dropped by decoder, because video is too far behind audio (when 1931 using ``--framedrop=decoder``). Sometimes, this may be incremented in other 1932 situations, e.g. when video packets are damaged, or the decoder doesn't 1933 follow the usual rules. Unavailable if video is disabled. 1934 1935 ``drop-frame-count`` is a deprecated alias. 1936 1937``frame-drop-count`` 1938 Frames dropped by VO (when using ``--framedrop=vo``). 1939 1940 ``vo-drop-frame-count`` is a deprecated alias. 1941 1942``mistimed-frame-count`` 1943 Number of video frames that were not timed correctly in display-sync mode 1944 for the sake of keeping A/V sync. This does not include external 1945 circumstances, such as video rendering being too slow or the graphics 1946 driver somehow skipping a vsync. It does not include rounding errors either 1947 (which can happen especially with bad source timestamps). For example, 1948 using the ``display-desync`` mode should never change this value from 0. 1949 1950``vsync-ratio`` 1951 For how many vsyncs a frame is displayed on average. This is available if 1952 display-sync is active only. For 30 FPS video on a 60 Hz screen, this will 1953 be 2. This is the moving average of what actually has been scheduled, so 1954 24 FPS on 60 Hz will never remain exactly on 2.5, but jitter depending on 1955 the last frame displayed. 1956 1957``vo-delayed-frame-count`` 1958 Estimated number of frames delayed due to external circumstances in 1959 display-sync mode. Note that in general, mpv has to guess that this is 1960 happening, and the guess can be inaccurate. 1961 1962``percent-pos`` (RW) 1963 Position in current file (0-100). The advantage over using this instead of 1964 calculating it out of other properties is that it properly falls back to 1965 estimating the playback position from the byte position, if the file 1966 duration is not known. 1967 1968``time-pos`` (RW) 1969 Position in current file in seconds. 1970 1971``time-start`` 1972 Deprecated. Always returns 0. Before mpv 0.14, this used to return the start 1973 time of the file (could affect e.g. transport streams). See 1974 ``--rebase-start-time`` option. 1975 1976``time-remaining`` 1977 Remaining length of the file in seconds. Note that the file duration is not 1978 always exactly known, so this is an estimate. 1979 1980``audio-pts`` 1981 Current audio playback position in current file in seconds. Unlike time-pos, 1982 this updates more often than once per frame. For audio-only files, it is 1983 mostly equivalent to time-pos, while for video-only files this property is 1984 not available. 1985 1986``playtime-remaining`` 1987 ``time-remaining`` scaled by the current ``speed``. 1988 1989``playback-time`` (RW) 1990 Position in current file in seconds. Unlike ``time-pos``, the time is 1991 clamped to the range of the file. (Inaccurate file durations etc. could 1992 make it go out of range. Useful on attempts to seek outside of the file, 1993 as the seek target time is considered the current position during seeking.) 1994 1995``chapter`` (RW) 1996 Current chapter number. The number of the first chapter is 0. 1997 1998``edition`` (RW) 1999 Current MKV edition number. Setting this property to a different value will 2000 restart playback. The number of the first edition is 0. 2001 2002 Before mpv 0.31.0, this showed the actual edition selected at runtime, if 2003 you didn't set the option or property manually. With mpv 0.31.0 and later, 2004 this strictly returns the user-set option or property value, and the 2005 ``current-edition`` property was added to return the runtime selected 2006 edition (this matters with ``--edition=auto``, the default). 2007 2008``current-edition`` 2009 Currently selected edition. This property is unavailable if no file is 2010 loaded, or the file has no editions. (Matroska files make a difference 2011 between having no editions and a single edition, which will be reflected by 2012 the property, although in practice it does not matter.) 2013 2014``chapters`` 2015 Number of chapters. 2016 2017``editions`` 2018 Number of MKV editions. 2019 2020``edition-list`` 2021 List of editions, current entry marked. Currently, the raw property value 2022 is useless. 2023 2024 This has a number of sub-properties. Replace ``N`` with the 0-based edition 2025 index. 2026 2027 ``edition-list/count`` 2028 Number of editions. If there are no editions, this can be 0 or 1 (1 2029 if there's a useless dummy edition). 2030 2031 ``edition-list/N/id`` (RW) 2032 Edition ID as integer. Use this to set the ``edition`` property. 2033 Currently, this is the same as the edition index. 2034 2035 ``edition-list/N/default`` 2036 Whether this is the default edition. 2037 2038 ``edition-list/N/title`` 2039 Edition title as stored in the file. Not always available. 2040 2041 When querying the property with the client API using ``MPV_FORMAT_NODE``, 2042 or with Lua ``mp.get_property_native``, this will return a mpv_node with 2043 the following contents: 2044 2045 :: 2046 2047 MPV_FORMAT_NODE_ARRAY 2048 MPV_FORMAT_NODE_MAP (for each edition) 2049 "id" MPV_FORMAT_INT64 2050 "title" MPV_FORMAT_STRING 2051 "default" MPV_FORMAT_FLAG 2052 2053``metadata`` 2054 Metadata key/value pairs. 2055 2056 If the property is accessed with Lua's ``mp.get_property_native``, this 2057 returns a table with metadata keys mapping to metadata values. If it is 2058 accessed with the client API, this returns a ``MPV_FORMAT_NODE_MAP``, 2059 with tag keys mapping to tag values. 2060 2061 For OSD, it returns a formatted list. Trying to retrieve this property as 2062 a raw string doesn't work. 2063 2064 This has a number of sub-properties: 2065 2066 ``metadata/by-key/<key>`` 2067 Value of metadata entry ``<key>``. 2068 2069 ``metadata/list/count`` 2070 Number of metadata entries. 2071 2072 ``metadata/list/N/key`` 2073 Key name of the Nth metadata entry. (The first entry is ``0``). 2074 2075 ``metadata/list/N/value`` 2076 Value of the Nth metadata entry. 2077 2078 ``metadata/<key>`` 2079 Old version of ``metadata/by-key/<key>``. Use is discouraged, because 2080 the metadata key string could conflict with other sub-properties. 2081 2082 The layout of this property might be subject to change. Suggestions are 2083 welcome how exactly this property should work. 2084 2085 When querying the property with the client API using ``MPV_FORMAT_NODE``, 2086 or with Lua ``mp.get_property_native``, this will return a mpv_node with 2087 the following contents: 2088 2089 :: 2090 2091 MPV_FORMAT_NODE_MAP 2092 (key and string value for each metadata entry) 2093 2094``filtered-metadata`` 2095 Like ``metadata``, but includes only fields listed in the ``--display-tags`` 2096 option. This is the same set of tags that is printed to the terminal. 2097 2098``chapter-metadata`` 2099 Metadata of current chapter. Works similar to ``metadata`` property. It 2100 also allows the same access methods (using sub-properties). 2101 2102 Per-chapter metadata is very rare. Usually, only the chapter name 2103 (``title``) is set. 2104 2105 For accessing other information, like chapter start, see the 2106 ``chapter-list`` property. 2107 2108``vf-metadata/<filter-label>`` 2109 Metadata added by video filters. Accessed by the filter label, 2110 which, if not explicitly specified using the ``@filter-label:`` syntax, 2111 will be ``<filter-name>NN``. 2112 2113 Works similar to ``metadata`` property. It allows the same access 2114 methods (using sub-properties). 2115 2116 An example of this kind of metadata are the cropping parameters 2117 added by ``--vf=lavfi=cropdetect``. 2118 2119``af-metadata/<filter-label>`` 2120 Equivalent to ``vf-metadata/<filter-label>``, but for audio filters. 2121 2122``idle-active`` 2123 Returns ``yes``/true if no file is loaded, but the player is staying around 2124 because of the ``--idle`` option. 2125 2126 (Renamed from ``idle``.) 2127 2128``core-idle`` 2129 Whether the playback core is paused. This can differ from ``pause`` in 2130 special situations, such as when the player pauses itself due to low 2131 network cache. 2132 2133 This also returns ``yes``/true if playback is restarting or if nothing is 2134 playing at all. In other words, it's only ``no``/false if there's actually 2135 video playing. (Behavior since mpv 0.7.0.) 2136 2137``cache-speed`` 2138 Current I/O read speed between the cache and the lower layer (like network). 2139 This gives the number bytes per seconds over a 1 second window (using 2140 the type ``MPV_FORMAT_INT64`` for the client API). 2141 2142 This is the same as ``demuxer-cache-state/raw-input-rate``. 2143 2144``demuxer-cache-duration`` 2145 Approximate duration of video buffered in the demuxer, in seconds. The 2146 guess is very unreliable, and often the property will not be available 2147 at all, even if data is buffered. 2148 2149``demuxer-cache-time`` 2150 Approximate time of video buffered in the demuxer, in seconds. Same as 2151 ``demuxer-cache-duration`` but returns the last timestamp of buffered 2152 data in demuxer. 2153 2154``demuxer-cache-idle`` 2155 Whether the demuxer is idle, which means that the demuxer cache is filled 2156 to the requested amount, and is currently not reading more data. 2157 2158``demuxer-cache-state`` 2159 Each entry in ``seekable-ranges`` represents a region in the demuxer cache 2160 that can be seeked to, with a ``start`` and ``end`` fields containing the 2161 respective timestamps. If there are multiple demuxers active, this only 2162 returns information about the "main" demuxer, but might be changed in 2163 future to return unified information about all demuxers. The ranges are in 2164 arbitrary order. Often, ranges will overlap for a bit, before being joined. 2165 In broken corner cases, ranges may overlap all over the place. 2166 2167 The end of a seek range is usually smaller than the value returned by the 2168 ``demuxer-cache-time`` property, because that property returns the guessed 2169 buffering amount, while the seek ranges represent the buffered data that 2170 can actually be used for cached seeking. 2171 2172 ``bof-cached`` indicates whether the seek range with the lowest timestamp 2173 points to the beginning of the stream (BOF). This implies you cannot seek 2174 before this position at all. ``eof-cached`` indicates whether the seek range 2175 with the highest timestamp points to the end of the stream (EOF). If both 2176 ``bof-cached`` and ``eof-cached`` are true, and there's only 1 cache range, 2177 the entire stream is cached. 2178 2179 ``fw-bytes`` is the number of bytes of packets buffered in the range 2180 starting from the current decoding position. This is a rough estimate 2181 (may not account correctly for various overhead), and stops at the 2182 demuxer position (it ignores seek ranges after it). 2183 2184 ``file-cache-bytes`` is the number of bytes stored in the file cache. This 2185 includes all overhead, and possibly unused data (like pruned data). This 2186 member is missing if the file cache wasn't enabled with 2187 ``--cache-on-disk=yes``. 2188 2189 ``cache-end`` is ``demuxer-cache-time``. Missing if unavailable. 2190 2191 ``reader-pts`` is the approximate timestamp of the start of the buffered 2192 range. Missing if unavailable. 2193 2194 ``cache-duration`` is ``demuxer-cache-duration``. Missing if unavailable. 2195 2196 ``raw-input-rate`` is the estimated input rate of the network layer (or any 2197 other byte-oriented input layer) in bytes per second. May be inaccurate or 2198 missing. 2199 2200 When querying the property with the client API using ``MPV_FORMAT_NODE``, 2201 or with Lua ``mp.get_property_native``, this will return a mpv_node with 2202 the following contents: 2203 2204 :: 2205 2206 MPV_FORMAT_NODE_MAP 2207 "seekable-ranges" MPV_FORMAT_NODE_ARRAY 2208 MPV_FORMAT_NODE_MAP 2209 "start" MPV_FORMAT_DOUBLE 2210 "end" MPV_FORMAT_DOUBLE 2211 "bof-cached" MPV_FORMAT_FLAG 2212 "eof-cached" MPV_FORMAT_FLAG 2213 "fw-bytes" MPV_FORMAT_INT64 2214 "file-cache-bytes" MPV_FORMAT_INT64 2215 "cache-end" MPV_FORMAT_DOUBLE 2216 "reader-pts" MPV_FORMAT_DOUBLE 2217 "cache-duration" MPV_FORMAT_DOUBLE 2218 "raw-input-rate" MPV_FORMAT_INT64 2219 2220 Other fields (might be changed or removed in the future): 2221 2222 ``eof`` 2223 Whether the reader thread has hit the end of the file. 2224 2225 ``underrun`` 2226 Whether the reader thread could not satisfy a decoder's request for a 2227 new packet. 2228 2229 ``idle`` 2230 Whether the thread is currently not reading. 2231 2232 ``total-bytes`` 2233 Sum of packet bytes (plus some overhead estimation) of the entire packet 2234 queue, including cached seekable ranges. 2235 2236``demuxer-via-network`` 2237 Whether the stream demuxed via the main demuxer is most likely played via 2238 network. What constitutes "network" is not always clear, might be used for 2239 other types of untrusted streams, could be wrong in certain cases, and its 2240 definition might be changing. Also, external files (like separate audio 2241 files or streams) do not influence the value of this property (currently). 2242 2243``demuxer-start-time`` 2244 The start time reported by the demuxer in fractional seconds. 2245 2246``paused-for-cache`` 2247 Whether playback is paused because of waiting for the cache. 2248 2249``cache-buffering-state`` 2250 The percentage (0-100) of the cache fill status until the player will 2251 unpause (related to ``paused-for-cache``). 2252 2253``eof-reached`` 2254 Whether the end of playback was reached. Note that this is usually 2255 interesting only if ``--keep-open`` is enabled, since otherwise the player 2256 will immediately play the next file (or exit or enter idle mode), and in 2257 these cases the ``eof-reached`` property will logically be cleared 2258 immediately after it's set. 2259 2260``seeking`` 2261 Whether the player is currently seeking, or otherwise trying to restart 2262 playback. (It's possible that it returns ``yes``/true while a file is 2263 loaded. This is because the same underlying code is used for seeking and 2264 resyncing.) 2265 2266``mixer-active`` 2267 Whether the audio mixer is active. 2268 2269 This option is relatively useless. Before mpv 0.18.1, it could be used to 2270 infer behavior of the ``volume`` property. 2271 2272``ao-volume`` (RW) 2273 System volume. This property is available only if mpv audio output is 2274 currently active, and only if the underlying implementation supports volume 2275 control. What this option does depends on the API. For example, on ALSA 2276 this usually changes system-wide audio, while with PulseAudio this controls 2277 per-application volume. 2278 2279``ao-mute`` (RW) 2280 Similar to ``ao-volume``, but controls the mute state. May be unimplemented 2281 even if ``ao-volume`` works. 2282 2283``audio-codec`` 2284 Audio codec selected for decoding. 2285 2286``audio-codec-name`` 2287 Audio codec. 2288 2289``audio-params`` 2290 Audio format as output by the audio decoder. 2291 This has a number of sub-properties: 2292 2293 ``audio-params/format`` 2294 The sample format as string. This uses the same names as used in other 2295 places of mpv. 2296 2297 ``audio-params/samplerate`` 2298 Samplerate. 2299 2300 ``audio-params/channels`` 2301 The channel layout as a string. This is similar to what the 2302 ``--audio-channels`` accepts. 2303 2304 ``audio-params/hr-channels`` 2305 As ``channels``, but instead of the possibly cryptic actual layout 2306 sent to the audio device, return a hopefully more human readable form. 2307 (Usually only ``audio-out-params/hr-channels`` makes sense.) 2308 2309 ``audio-params/channel-count`` 2310 Number of audio channels. This is redundant to the ``channels`` field 2311 described above. 2312 2313 When querying the property with the client API using ``MPV_FORMAT_NODE``, 2314 or with Lua ``mp.get_property_native``, this will return a mpv_node with 2315 the following contents: 2316 2317 :: 2318 2319 MPV_FORMAT_NODE_MAP 2320 "format" MPV_FORMAT_STRING 2321 "samplerate" MPV_FORMAT_INT64 2322 "channels" MPV_FORMAT_STRING 2323 "channel-count" MPV_FORMAT_INT64 2324 "hr-channels" MPV_FORMAT_STRING 2325 2326``audio-out-params`` 2327 Same as ``audio-params``, but the format of the data written to the audio 2328 API. 2329 2330``colormatrix`` 2331 Redirects to ``video-params/colormatrix``. This parameter (as well as 2332 similar ones) can be overridden with the ``format`` video filter. 2333 2334``colormatrix-input-range`` 2335 See ``colormatrix``. 2336 2337``colormatrix-primaries`` 2338 See ``colormatrix``. 2339 2340``hwdec`` (RW) 2341 Reflects the ``--hwdec`` option. 2342 2343 Writing to it may change the currently used hardware decoder, if possible. 2344 (Internally, the player may reinitialize the decoder, and will perform a 2345 seek to refresh the video properly.) You can watch the other hwdec 2346 properties to see whether this was successful. 2347 2348 Unlike in mpv 0.9.x and before, this does not return the currently active 2349 hardware decoder. Since mpv 0.18.0, ``hwdec-current`` is available for 2350 this purpose. 2351 2352``hwdec-current`` 2353 The current hardware decoding in use. If decoding is active, return one of 2354 the values used by the ``hwdec`` option/property. ``no``/false indicates 2355 software decoding. If no decoder is loaded, the property is unavailable. 2356 2357``hwdec-interop`` 2358 This returns the currently loaded hardware decoding/output interop driver. 2359 This is known only once the VO has opened (and possibly later). With some 2360 VOs (like ``gpu``), this might be never known in advance, but only when 2361 the decoder attempted to create the hw decoder successfully. (Using 2362 ``--gpu-hwdec-interop`` can load it eagerly.) If there are multiple 2363 drivers loaded, they will be separated by ``,``. 2364 2365 If no VO is active or no interop driver is known, this property is 2366 unavailable. 2367 2368 This does not necessarily use the same values as ``hwdec``. There can be 2369 multiple interop drivers for the same hardware decoder, depending on 2370 platform and VO. 2371 2372``video-format`` 2373 Video format as string. 2374 2375``video-codec`` 2376 Video codec selected for decoding. 2377 2378``width``, ``height`` 2379 Video size. This uses the size of the video as decoded, or if no video 2380 frame has been decoded yet, the (possibly incorrect) container indicated 2381 size. 2382 2383``video-params`` 2384 Video parameters, as output by the decoder (with overrides like aspect 2385 etc. applied). This has a number of sub-properties: 2386 2387 ``video-params/pixelformat`` 2388 The pixel format as string. This uses the same names as used in other 2389 places of mpv. 2390 2391 ``video-params/hw-pixelformat`` 2392 The underlying pixel format as string. This is relevant for some cases 2393 of hardware decoding and unavailable otherwise. 2394 2395 ``video-params/average-bpp`` 2396 Average bits-per-pixel as integer. Subsampled planar formats use a 2397 different resolution, which is the reason this value can sometimes be 2398 odd or confusing. Can be unavailable with some formats. 2399 2400 ``video-params/w``, ``video-params/h`` 2401 Video size as integers, with no aspect correction applied. 2402 2403 ``video-params/dw``, ``video-params/dh`` 2404 Video size as integers, scaled for correct aspect ratio. 2405 2406 ``video-params/aspect`` 2407 Display aspect ratio as float. 2408 2409 ``video-params/par`` 2410 Pixel aspect ratio. 2411 2412 ``video-params/colormatrix`` 2413 The colormatrix in use as string. (Exact values subject to change.) 2414 2415 ``video-params/colorlevels`` 2416 The colorlevels as string. (Exact values subject to change.) 2417 2418 ``video-params/primaries`` 2419 The primaries in use as string. (Exact values subject to change.) 2420 2421 ``video-params/gamma`` 2422 The gamma function in use as string. (Exact values subject to change.) 2423 2424 ``video-params/sig-peak`` 2425 The video file's tagged signal peak as float. 2426 2427 ``video-params/light`` 2428 The light type in use as a string. (Exact values subject to change.) 2429 2430 ``video-params/chroma-location`` 2431 Chroma location as string. (Exact values subject to change.) 2432 2433 ``video-params/rotate`` 2434 Intended display rotation in degrees (clockwise). 2435 2436 ``video-params/stereo-in`` 2437 Source file stereo 3D mode. (See the ``format`` video filter's 2438 ``stereo-in`` option.) 2439 2440 ``video-params/alpha`` 2441 Alpha type. If the format has no alpha channel, this will be unavailable 2442 (but in future releases, it could change to ``no``). If alpha is 2443 present, this is set to ``straight`` or ``premul``. 2444 2445 When querying the property with the client API using ``MPV_FORMAT_NODE``, 2446 or with Lua ``mp.get_property_native``, this will return a mpv_node with 2447 the following contents: 2448 2449 :: 2450 2451 MPV_FORMAT_NODE_MAP 2452 "pixelformat" MPV_FORMAT_STRING 2453 "hw-pixelformat" MPV_FORMAT_STRING 2454 "w" MPV_FORMAT_INT64 2455 "h" MPV_FORMAT_INT64 2456 "dw" MPV_FORMAT_INT64 2457 "dh" MPV_FORMAT_INT64 2458 "aspect" MPV_FORMAT_DOUBLE 2459 "par" MPV_FORMAT_DOUBLE 2460 "colormatrix" MPV_FORMAT_STRING 2461 "colorlevels" MPV_FORMAT_STRING 2462 "primaries" MPV_FORMAT_STRING 2463 "gamma" MPV_FORMAT_STRING 2464 "sig-peak" MPV_FORMAT_DOUBLE 2465 "light" MPV_FORMAT_STRING 2466 "chroma-location" MPV_FORMAT_STRING 2467 "rotate" MPV_FORMAT_INT64 2468 "stereo-in" MPV_FORMAT_STRING 2469 "average-bpp" MPV_FORMAT_INT64 2470 "alpha" MPV_FORMAT_STRING 2471 2472``dwidth``, ``dheight`` 2473 Video display size. This is the video size after filters and aspect scaling 2474 have been applied. The actual video window size can still be different 2475 from this, e.g. if the user resized the video window manually. 2476 2477 These have the same values as ``video-out-params/dw`` and 2478 ``video-out-params/dh``. 2479 2480``video-dec-params`` 2481 Exactly like ``video-params``, but no overrides applied. 2482 2483``video-out-params`` 2484 Same as ``video-params``, but after video filters have been applied. If 2485 there are no video filters in use, this will contain the same values as 2486 ``video-params``. Note that this is still not necessarily what the video 2487 window uses, since the user can change the window size, and all real VOs 2488 do their own scaling independently from the filter chain. 2489 2490 Has the same sub-properties as ``video-params``. 2491 2492``video-frame-info`` 2493 Approximate information of the current frame. Note that if any of these 2494 are used on OSD, the information might be off by a few frames due to OSD 2495 redrawing and frame display being somewhat disconnected, and you might 2496 have to pause and force a redraw. 2497 2498 This has a number of sub-properties: 2499 2500 ``video-frame-info/picture-type`` 2501 The type of the picture. It can be "I" (intra), "P" (predicted), "B" 2502 (bi-dir predicted) or unavailable. 2503 2504 ``video-frame-info/interlaced`` 2505 Whether the content of the frame is interlaced. 2506 2507 ``video-frame-info/tff`` 2508 If the content is interlaced, whether the top field is displayed first. 2509 2510 ``video-frame-info/repeat`` 2511 Whether the frame must be delayed when decoding. 2512 2513``container-fps`` 2514 Container FPS. This can easily contain bogus values. For videos that use 2515 modern container formats or video codecs, this will often be incorrect. 2516 2517 (Renamed from ``fps``.) 2518 2519``estimated-vf-fps`` 2520 Estimated/measured FPS of the video filter chain output. (If no filters 2521 are used, this corresponds to decoder output.) This uses the average of 2522 the 10 past frame durations to calculate the FPS. It will be inaccurate 2523 if frame-dropping is involved (such as when framedrop is explicitly 2524 enabled, or after precise seeking). Files with imprecise timestamps (such 2525 as Matroska) might lead to unstable results. 2526 2527``window-scale`` (RW) 2528 Window size multiplier. Setting this will resize the video window to the 2529 values contained in ``dwidth`` and ``dheight`` multiplied with the value 2530 set with this property. Setting ``1`` will resize to original video size 2531 (or to be exact, the size the video filters output). ``2`` will set the 2532 double size, ``0.5`` halves the size. 2533 2534 Note that setting a value identical to its previous value will not resize 2535 the window. That's because this property mirrors the ``window-scale`` 2536 option, and setting an option to its previous value is ignored. If this 2537 value is set while the window is in a fullscreen, the multiplier is not 2538 applied until the window is taken out of that state. Writing this property 2539 to a maximized window can unmaximize the window depending on the OS and 2540 window manager. If the window does not unmaximize, the multiplier will be 2541 applied if the user unmaximizes the window later. 2542 2543 See ``current-window-scale`` for the value derived from the actual window 2544 size. 2545 2546 Since mpv 0.31.0, this always returns the previously set value (or the 2547 default value), instead of the value implied by the actual window size. 2548 Before mpv 0.31.0, this returned what ``current-window-scale`` returns now, 2549 after the window was created. 2550 2551``current-window-scale`` (RW) 2552 The ``window-scale`` value calculated from the current window size. This 2553 has the same value as ``window-scale`` if the window size was not changed 2554 since setting the option, and the window size was not restricted in other 2555 ways. If the window is fullscreened, this will return the scale value 2556 calculated from the last non-fullscreen size of the window. The property 2557 is unavailable if no video is active. 2558 2559 When setting this property in the fullscreen or maximized state, the behavior 2560 is the same as window-scale. In all ther cases, setting the value of this 2561 property will always resize the window. This does not affect the value of 2562 ``window-scale``. 2563 2564``focused`` 2565 Whether the window has focus. Might not be supported by all VOs. 2566 2567``display-names`` 2568 Names of the displays that the mpv window covers. On X11, these 2569 are the xrandr names (LVDS1, HDMI1, DP1, VGA1, etc.). On Windows, these 2570 are the GDI names (\\.\DISPLAY1, \\.\DISPLAY2, etc.) and the first display 2571 in the list will be the one that Windows considers associated with the 2572 window (as determined by the MonitorFromWindow API.) On macOS these are the 2573 Display Product Names as used in the System Information and only one display 2574 name is returned since a window can only be on one screen. 2575 2576``display-fps`` 2577 The refresh rate of the current display. Currently, this is the lowest FPS 2578 of any display covered by the video, as retrieved by the underlying system 2579 APIs (e.g. xrandr on X11). It is not the measured FPS. It's not necessarily 2580 available on all platforms. Note that any of the listed facts may change 2581 any time without a warning. 2582 2583 Writing to this property is deprecated. It has the same effect as writing to 2584 ``override-display-fps``. Since mpv 0.31.0, this property is unavailable 2585 if no display FPS was reported (e.g. if no video is active), while in older 2586 versions, it returned the ``--display-fps`` option value. 2587 2588``estimated-display-fps`` 2589 The actual rate at which display refreshes seem to occur, measured by 2590 system time. Only available if display-sync mode (as selected by 2591 ``--video-sync``) is active. 2592 2593``vsync-jitter`` 2594 Estimated deviation factor of the vsync duration. 2595 2596``display-width``, ``display-height`` 2597 The current display's horizontal and vertical resolution in pixels. Whether 2598 or not these values update as the mpv window changes displays depends on 2599 the windowing backend. It may not be available on all platforms. 2600 2601``display-hidpi-scale`` 2602 The HiDPI scale factor as reported by the windowing backend. If no VO is 2603 active, or if the VO does not report a value, this property is unavailable. 2604 It may be saner to report an absolute DPI, however, this is the way HiDPI 2605 support is implemented on most OS APIs. See also ``--hidpi-window-scale``. 2606 2607``video-aspect`` (RW) 2608 Deprecated. This is tied to ``--video-aspect-override``, but always 2609 reports the current video aspect if video is active. 2610 2611 The read and write components of this option can be split up into 2612 ``video-params/aspect`` and ``video-aspect-override`` respectively. 2613 2614``osd-width``, ``osd-height`` 2615 Last known OSD width (can be 0). This is needed if you want to use the 2616 ``overlay-add`` command. It gives you the actual OSD/window size (not 2617 including decorations drawn by the OS window manager). 2618 2619 Alias to ``osd-dimensions/w`` and ``osd-dimensions/h``. 2620 2621``osd-par`` 2622 Last known OSD display pixel aspect (can be 0). 2623 2624 Alias to ``osd-dimensions/osd-par``. 2625 2626``osd-dimensions`` 2627 Last known OSD dimensions. 2628 2629 Has the following sub-properties (which can be read as ``MPV_FORMAT_NODE`` 2630 or Lua table with ``mp.get_property_native``): 2631 2632 ``osd-dimensions/w`` 2633 Size of the VO window in OSD render units (usually pixels, but may be 2634 scaled pixels with VOs like ``xv``). 2635 2636 ``osd-dimensions/h`` 2637 Size of the VO window in OSD render units, 2638 2639 ``osd-dimensions/par`` 2640 Pixel aspect ratio of the OSD (usually 1). 2641 2642 ``osd-dimensions/aspect`` 2643 Display aspect ratio of the VO window. (Computing from the properties 2644 above.) 2645 2646 ``osd-dimensions/mt``, ``osd-dimensions/mb``, ``osd-dimensions/ml``, ``osd-dimensions/mr`` 2647 OSD to video margins (top, bottom, left, right). This describes the 2648 area into which the video is rendered. 2649 2650 Any of these properties may be unavailable or set to dummy values if the 2651 VO window is not created or visible. 2652 2653``mouse-pos`` 2654 Read-only - last known mouse position, normalizd to OSD dimensions. 2655 2656 Has the following sub-properties (which can be read as ``MPV_FORMAT_NODE`` 2657 or Lua table with ``mp.get_property_native``): 2658 2659 ``mouse-pos/x``, ``mouse-pos/y`` 2660 Last known coordinates of the mouse pointer. 2661 2662 ``mouse-pos/hover`` 2663 Boolean - whether the mouse pointer hovers the video window. The 2664 coordinates should be ignored when this value is false, because the 2665 video backends update them only when the pointer hovers the window. 2666 2667``sub-text`` 2668 The current subtitle text regardless of sub visibility. Formatting is 2669 stripped. If the subtitle is not text-based (i.e. DVD/BD subtitles), an 2670 empty string is returned. 2671 2672 This property is experimental and might be removed in the future. 2673 2674``sub-text-ass`` 2675 Like ``sub-text``, but return the text in ASS format. Text subtitles in 2676 other formats are converted. For native ASS subtitles, events that do 2677 not contain any text (but vector drawings etc.) are not filtered out. If 2678 multiple events match with the current playback time, they are concatenated 2679 with line breaks. Contains only the "Text" part of the events. 2680 2681 This property is not enough to render ASS subtitles correctly, because ASS 2682 header and per-event metadata are not returned. You likely need to do 2683 further filtering on the returned string to make it useful. 2684 2685 This property is experimental and might be removed in the future. 2686 2687``secondary-sub-text`` 2688 Same as ``sub-text``, but for the secondary subtitles. 2689 2690``sub-start`` 2691 The current subtitle start time (in seconds). If there's multiple current 2692 subtitles, returns the first start time. If no current subtitle is present 2693 null is returned instead. 2694 2695``secondary-sub-start`` 2696 Same as ``sub-start``, but for the secondary subtitles. 2697 2698``sub-end`` 2699 The current subtitle end time (in seconds). If there's multiple current 2700 subtitles, return the last end time. If no current subtitle is present, or 2701 if it's present but has unknown or incorrect duration, null is returned 2702 instead. 2703 2704``secondary-sub-end`` 2705 Same as ``sub-end``, but for the secondary subtitles. 2706 2707``playlist-pos`` (RW) 2708 Current position on playlist. The first entry is on position 0. Writing to 2709 this property may start playback at the new position. 2710 2711 In some cases, this is not necessarily the currently playing file. See 2712 explanation of ``current`` and ``playing`` flags in ``playlist``. 2713 2714 If there the playlist is empty, or if it's non-empty, but no entry is 2715 "current", this property returns -1. Likewise, writing -1 will put the 2716 player into idle mode (or exit playback if idle mode is not enabled). If an 2717 out of range index is written to the property, this behaves as if writing -1. 2718 (Before mpv 0.33.0, instead of returning -1, this property was unavailable 2719 if no playlist entry was current.) 2720 2721 Writing the current value back to the property is subject to change. 2722 Currently, it will restart playback of the playlist entry. But in the 2723 future, writing the current value will be ignored. Use the 2724 ``playlist-play-index`` command to get guaranteed behavior. 2725 2726``playlist-pos-1`` (RW) 2727 Same as ``playlist-pos``, but 1-based. 2728 2729``playlist-current-pos`` (RW) 2730 Index of the "current" item on playlist. This usually, but not necessarily, 2731 the currently playing item (see ``playlist-playing-pos``). Depending on the 2732 exact internal state of the player, it may refer to the playlist item to 2733 play next, or the playlist item used to determine what to play next. 2734 2735 For reading, this is exactly the same as ``playlist-pos``. 2736 2737 For writing, this *only* sets the position of the "current" item, without 2738 stopping playback of the current file (or starting playback, if this is done 2739 in idle mode). Use -1 to remove the current flag. 2740 2741 This property is only vaguely useful. If set during playback, it will 2742 typically cause the playlist entry *after* it to be played next. Another 2743 possibly odd observable state is that if ``playlist-next`` is run during 2744 playback, this property is set to the playlist entry to play next (unlike 2745 the previous case). There is an internal flag that decides whether the 2746 current playlist entry or the next one should be played, and this flag is 2747 currently inaccessible for API users. (Whether this behavior will kept is 2748 possibly subject to change.) 2749 2750``playlist-playing-pos`` 2751 Index of the "playing" item on playlist. A playlist item is "playing" if 2752 it's being loaded, actually playing, or being unloaded. This property is set 2753 during the ``MPV_EVENT_START_FILE`` (``start-file``) and the 2754 ``MPV_EVENT_START_END`` (``end-file``) events. Outside of that, it returns 2755 -1. If the playlist entry was somehow removed during playback, but playback 2756 hasn't stopped yet, or is in progress of being stopped, it also returns -1. 2757 (This can happen at least during state transitions.) 2758 2759 In the "playing" state, this is usually the same as ``playlist-pos``, except 2760 during state changes, or if ``playlist-current-pos`` was written explicitly. 2761 2762``playlist-count`` 2763 Number of total playlist entries. 2764 2765``playlist`` 2766 Playlist, current entry marked. Currently, the raw property value is 2767 useless. 2768 2769 This has a number of sub-properties. Replace ``N`` with the 0-based playlist 2770 entry index. 2771 2772 ``playlist/count`` 2773 Number of playlist entries (same as ``playlist-count``). 2774 2775 ``playlist/N/filename`` 2776 Filename of the Nth entry. 2777 2778 ``playlist/N/playing`` 2779 ``yes``/true if the ``playlist-playing-pos`` property points to this 2780 entry, ``no``/false or unavailable otherwise. 2781 2782 ``playlist/N/current`` 2783 ``yes``/true if the ``playlist-current-pos`` property points to this 2784 entry, ``no``/false or unavailable otherwise. 2785 2786 ``playlist/N/title`` 2787 Name of the Nth entry. Only available if the playlist file contains 2788 such fields, and only if mpv's parser supports it for the given 2789 playlist format. 2790 2791 ``playlist/N/id`` 2792 Unique ID for this entry. This is an automatically assigned integer ID 2793 that is unique for the entire life time of the current mpv core 2794 instance. Other commands, events, etc. use this as ``playlist_entry_id`` 2795 fields. 2796 2797 When querying the property with the client API using ``MPV_FORMAT_NODE``, 2798 or with Lua ``mp.get_property_native``, this will return a mpv_node with 2799 the following contents: 2800 2801 :: 2802 2803 MPV_FORMAT_NODE_ARRAY 2804 MPV_FORMAT_NODE_MAP (for each playlist entry) 2805 "filename" MPV_FORMAT_STRING 2806 "current" MPV_FORMAT_FLAG (might be missing; since mpv 0.7.0) 2807 "playing" MPV_FORMAT_FLAG (same) 2808 "title" MPV_FORMAT_STRING (optional) 2809 "id" MPV_FORMAT_INT64 2810 2811``track-list`` 2812 List of audio/video/sub tracks, current entry marked. Currently, the raw 2813 property value is useless. 2814 2815 This has a number of sub-properties. Replace ``N`` with the 0-based track 2816 index. 2817 2818 ``track-list/count`` 2819 Total number of tracks. 2820 2821 ``track-list/N/id`` 2822 The ID as it's used for ``-sid``/``--aid``/``--vid``. This is unique 2823 within tracks of the same type (sub/audio/video), but otherwise not. 2824 2825 ``track-list/N/type`` 2826 String describing the media type. One of ``audio``, ``video``, ``sub``. 2827 2828 ``track-list/N/src-id`` 2829 Track ID as used in the source file. Not always available. (It is 2830 missing if the format has no native ID, if the track is a pseudo-track 2831 that does not exist in this way in the actual file, or if the format 2832 is handled by libavformat, and the format was not whitelisted as having 2833 track IDs.) 2834 2835 ``track-list/N/title`` 2836 Track title as it is stored in the file. Not always available. 2837 2838 ``track-list/N/lang`` 2839 Track language as identified by the file. Not always available. 2840 2841 ``track-list/N/image`` 2842 ``yes``/true if this is a video track that consists of a single 2843 picture, ``no``/false or unavailable otherwise. The heuristic used to 2844 determine if a stream is an image doesn't attempt to detect images in 2845 codecs normally used for videos. Otherwise, it is reliable. 2846 2847 ``track-list/N/albumart`` 2848 ``yes``/true if this is an image embedded in an audio file or external 2849 cover art, ``no``/false or unavailable otherwise. 2850 2851 ``track-list/N/default`` 2852 ``yes``/true if the track has the default flag set in the file, 2853 ``no``/false or unavailable otherwise. 2854 2855 ``track-list/N/forced`` 2856 ``yes``/true if the track has the forced flag set in the file, 2857 ``no``/false or unavailable otherwise. 2858 2859 ``track-list/N/codec`` 2860 The codec name used by this track, for example ``h264``. Unavailable 2861 in some rare cases. 2862 2863 ``track-list/N/external`` 2864 ``yes``/true if the track is an external file, ``no``/false or 2865 unavailable otherwise. This is set for separate subtitle files. 2866 2867 ``track-list/N/external-filename`` 2868 The filename if the track is from an external file, unavailable 2869 otherwise. 2870 2871 ``track-list/N/selected`` 2872 ``yes``/true if the track is currently decoded, ``no``/false or 2873 unavailable otherwise. 2874 2875 ``track-list/N/main-selection`` 2876 It indicates the selection order of tracks for the same type. 2877 If a track is not selected, or is selected by the ``--lavfi-complex``, 2878 it is not available. For subtitle tracks, ``0`` represents the ``sid``, 2879 and ``1`` represents the ``secondary-sid``. 2880 2881 ``track-list/N/ff-index`` 2882 The stream index as usually used by the FFmpeg utilities. Note that 2883 this can be potentially wrong if a demuxer other than libavformat 2884 (``--demuxer=lavf``) is used. For mkv files, the index will usually 2885 match even if the default (builtin) demuxer is used, but there is 2886 no hard guarantee. 2887 2888 ``track-list/N/decoder-desc`` 2889 If this track is being decoded, the human-readable decoder name, 2890 2891 ``track-list/N/demux-w``, ``track-list/N/demux-h`` 2892 Video size hint as indicated by the container. (Not always accurate.) 2893 2894 ``track-list/N/demux-channel-count`` 2895 Number of audio channels as indicated by the container. (Not always 2896 accurate - in particular, the track could be decoded as a different 2897 number of channels.) 2898 2899 ``track-list/N/demux-channels`` 2900 Channel layout as indicated by the container. (Not always accurate.) 2901 2902 ``track-list/N/demux-samplerate`` 2903 Audio sample rate as indicated by the container. (Not always accurate.) 2904 2905 ``track-list/N/demux-fps`` 2906 Video FPS as indicated by the container. (Not always accurate.) 2907 2908 ``track-list/N/demux-bitrate`` 2909 Audio average bitrate, in bits per second. (Not always accurate.) 2910 2911 ``track-list/N/demux-rotation`` 2912 Video clockwise rotation metadata, in degrees. 2913 2914 ``track-list/N/demux-par`` 2915 Pixel aspect ratio. 2916 2917 ``track-list/N/audio-channels`` (deprecated) 2918 Deprecated alias for ``track-list/N/demux-channel-count``. 2919 2920 ``track-list/N/replaygain-track-peak``, ``track-list/N/replaygain-track-gain`` 2921 Per-track replaygain values. Only available for audio tracks with 2922 corresponding information stored in the source file. 2923 2924 ``track-list/N/replaygain-album-peak``, ``track-list/N/replaygain-album-gain`` 2925 Per-album replaygain values. If the file has per-track but no per-album 2926 information, the per-album values will be copied from the per-track 2927 values currently. It's possible that future mpv versions will make 2928 these properties unavailable instead in this case. 2929 2930 When querying the property with the client API using ``MPV_FORMAT_NODE``, 2931 or with Lua ``mp.get_property_native``, this will return a mpv_node with 2932 the following contents: 2933 2934 :: 2935 2936 MPV_FORMAT_NODE_ARRAY 2937 MPV_FORMAT_NODE_MAP (for each track) 2938 "id" MPV_FORMAT_INT64 2939 "type" MPV_FORMAT_STRING 2940 "src-id" MPV_FORMAT_INT64 2941 "title" MPV_FORMAT_STRING 2942 "lang" MPV_FORMAT_STRING 2943 "image" MPV_FORMAT_FLAG 2944 "albumart" MPV_FORMAT_FLAG 2945 "default" MPV_FORMAT_FLAG 2946 "forced" MPV_FORMAT_FLAG 2947 "selected" MPV_FORMAT_FLAG 2948 "main-selection" MPV_FORMAT_INT64 2949 "external" MPV_FORMAT_FLAG 2950 "external-filename" MPV_FORMAT_STRING 2951 "codec" MPV_FORMAT_STRING 2952 "ff-index" MPV_FORMAT_INT64 2953 "decoder-desc" MPV_FORMAT_STRING 2954 "demux-w" MPV_FORMAT_INT64 2955 "demux-h" MPV_FORMAT_INT64 2956 "demux-channel-count" MPV_FORMAT_INT64 2957 "demux-channels" MPV_FORMAT_STRING 2958 "demux-samplerate" MPV_FORMAT_INT64 2959 "demux-fps" MPV_FORMAT_DOUBLE 2960 "demux-bitrate" MPV_FORMAT_INT64 2961 "demux-rotation" MPV_FORMAT_INT64 2962 "demux-par" MPV_FORMAT_DOUBLE 2963 "audio-channels" MPV_FORMAT_INT64 2964 "replaygain-track-peak" MPV_FORMAT_DOUBLE 2965 "replaygain-track-gain" MPV_FORMAT_DOUBLE 2966 "replaygain-album-peak" MPV_FORMAT_DOUBLE 2967 "replaygain-album-gain" MPV_FORMAT_DOUBLE 2968 2969``current-tracks/...`` 2970 This gives access to currently selected tracks. It redirects to the correct 2971 entry in ``track-list``. 2972 2973 The following sub-entries are defined: ``video``, ``audio``, ``sub``, 2974 ``sub2`` 2975 2976 For example, ``current-tracks/audio/lang`` returns the current audio track's 2977 language field (the same value as ``track-list/N/lang``). 2978 2979 If tracks of the requested type are selected via ``--lavfi-complex``, the 2980 first one is returned. 2981 2982``chapter-list`` 2983 List of chapters, current entry marked. Currently, the raw property value 2984 is useless. 2985 2986 This has a number of sub-properties. Replace ``N`` with the 0-based chapter 2987 index. 2988 2989 ``chapter-list/count`` 2990 Number of chapters. 2991 2992 ``chapter-list/N/title`` 2993 Chapter title as stored in the file. Not always available. 2994 2995 ``chapter-list/N/time`` 2996 Chapter start time in seconds as float. 2997 2998 When querying the property with the client API using ``MPV_FORMAT_NODE``, 2999 or with Lua ``mp.get_property_native``, this will return a mpv_node with 3000 the following contents: 3001 3002 :: 3003 3004 MPV_FORMAT_NODE_ARRAY 3005 MPV_FORMAT_NODE_MAP (for each chapter) 3006 "title" MPV_FORMAT_STRING 3007 "time" MPV_FORMAT_DOUBLE 3008 3009``af``, ``vf`` (RW) 3010 See ``--vf``/``--af`` and the ``vf``/``af`` command. 3011 3012 When querying the property with the client API using ``MPV_FORMAT_NODE``, 3013 or with Lua ``mp.get_property_native``, this will return a mpv_node with 3014 the following contents: 3015 3016 :: 3017 3018 MPV_FORMAT_NODE_ARRAY 3019 MPV_FORMAT_NODE_MAP (for each filter entry) 3020 "name" MPV_FORMAT_STRING 3021 "label" MPV_FORMAT_STRING [optional] 3022 "enabled" MPV_FORMAT_FLAG [optional] 3023 "params" MPV_FORMAT_NODE_MAP [optional] 3024 "key" MPV_FORMAT_STRING 3025 "value" MPV_FORMAT_STRING 3026 3027 It's also possible to write the property using this format. 3028 3029``seekable`` 3030 Whether it's generally possible to seek in the current file. 3031 3032``partially-seekable`` 3033 Whether the current file is considered seekable, but only because the cache 3034 is active. This means small relative seeks may be fine, but larger seeks 3035 may fail anyway. Whether a seek will succeed or not is generally not known 3036 in advance. 3037 3038 If this property returns ``yes``/true, so will ``seekable``. 3039 3040``playback-abort`` 3041 Whether playback is stopped or is to be stopped. (Useful in obscure 3042 situations like during ``on_load`` hook processing, when the user can stop 3043 playback, but the script has to explicitly end processing.) 3044 3045``cursor-autohide`` (RW) 3046 See ``--cursor-autohide``. Setting this to a new value will always update 3047 the cursor, and reset the internal timer. 3048 3049``osd-sym-cc`` 3050 Inserts the current OSD symbol as opaque OSD control code (cc). This makes 3051 sense only with the ``show-text`` command or options which set OSD messages. 3052 The control code is implementation specific and is useless for anything else. 3053 3054``osd-ass-cc`` 3055 ``${osd-ass-cc/0}`` disables escaping ASS sequences of text in OSD, 3056 ``${osd-ass-cc/1}`` enables it again. By default, ASS sequences are 3057 escaped to avoid accidental formatting, and this property can disable 3058 this behavior. Note that the properties return an opaque OSD control 3059 code, which only makes sense for the ``show-text`` command or options 3060 which set OSD messages. 3061 3062 .. admonition:: Example 3063 3064 - ``--osd-msg3='This is ${osd-ass-cc/0}{\\b1}bold text'`` 3065 - ``show-text "This is ${osd-ass-cc/0}{\\b1}bold text"`` 3066 3067 Any ASS override tags as understood by libass can be used. 3068 3069 Note that you need to escape the ``\`` character, because the string is 3070 processed for C escape sequences before passing it to the OSD code. See 3071 `Flat command syntax`_ for details. 3072 3073 A list of tags can be found here: http://docs.aegisub.org/latest/ASS_Tags/ 3074 3075``vo-configured`` 3076 Whether the VO is configured right now. Usually this corresponds to whether 3077 the video window is visible. If the ``--force-window`` option is used, this 3078 usually always returns ``yes``/true. 3079 3080``vo-passes`` 3081 Contains introspection about the VO's active render passes and their 3082 execution times. Not implemented by all VOs. 3083 3084 This is further subdivided into two frame types, ``vo-passes/fresh`` for 3085 fresh frames (which have to be uploaded, scaled, etc.) and 3086 ``vo-passes/redraw`` for redrawn frames (which only have to be re-painted). 3087 The number of passes for any given subtype can change from frame to frame, 3088 and should not be relied upon. 3089 3090 Each frame type has a number of further sub-properties. Replace ``TYPE`` 3091 with the frame type, ``N`` with the 0-based pass index, and ``M`` with the 3092 0-based sample index. 3093 3094 ``vo-passes/TYPE/count`` 3095 Number of passes. 3096 3097 ``vo-passes/TYPE/N/desc`` 3098 Human-friendy description of the pass. 3099 3100 ``vo-passes/TYPE/N/last`` 3101 Last measured execution time, in nanoseconds. 3102 3103 ``vo-passes/TYPE/N/avg`` 3104 Average execution time of this pass, in nanoseconds. The exact 3105 timeframe varies, but it should generally be a handful of seconds. 3106 3107 ``vo-passes/TYPE/N/peak`` 3108 The peak execution time (highest value) within this averaging range, in 3109 nanoseconds. 3110 3111 ``vo-passes/TYPE/N/count`` 3112 The number of samples for this pass. 3113 3114 ``vo-passes/TYPE/N/samples/M`` 3115 The raw execution time of a specific sample for this pass, in 3116 nanoseconds. 3117 3118 When querying the property with the client API using ``MPV_FORMAT_NODE``, 3119 or with Lua ``mp.get_property_native``, this will return a mpv_node with 3120 the following contents: 3121 3122 :: 3123 3124 MPV_FORMAT_NODE_MAP 3125 "TYPE" MPV_FORMAT_NODE_ARRAY 3126 MPV_FORMAT_NODE_MAP 3127 "desc" MPV_FORMAT_STRING 3128 "last" MPV_FORMAT_INT64 3129 "avg" MPV_FORMAT_INT64 3130 "peak" MPV_FORMAT_INT64 3131 "count" MPV_FORMAT_INT64 3132 "samples" MPV_FORMAT_NODE_ARRAY 3133 MP_FORMAT_INT64 3134 3135 Note that directly accessing this structure via subkeys is not supported, 3136 the only access is through aforementioned ``MPV_FORMAT_NODE``. 3137 3138``perf-info`` 3139 Further performance data. Querying this property triggers internal 3140 collection of some data, and may slow down the player. Each query will reset 3141 some internal state. Property change notification doesn't and won't work. 3142 All of this may change in the future, so don't use this. The builtin 3143 ``stats`` script is supposed to be the only user; since it's bundled and 3144 built with the source code, it can use knowledge of mpv internal to render 3145 the information properly. See ``stats`` script description for some details. 3146 3147``video-bitrate``, ``audio-bitrate``, ``sub-bitrate`` 3148 Bitrate values calculated on the packet level. This works by dividing the 3149 bit size of all packets between two keyframes by their presentation 3150 timestamp distance. (This uses the timestamps are stored in the file, so 3151 e.g. playback speed does not influence the returned values.) In particular, 3152 the video bitrate will update only per keyframe, and show the "past" 3153 bitrate. To make the property more UI friendly, updates to these properties 3154 are throttled in a certain way. 3155 3156 The unit is bits per second. OSD formatting turns these values in kilobits 3157 (or megabits, if appropriate), which can be prevented by using the 3158 raw property value, e.g. with ``${=video-bitrate}``. 3159 3160 Note that the accuracy of these properties is influenced by a few factors. 3161 If the underlying demuxer rewrites the packets on demuxing (done for some 3162 file formats), the bitrate might be slightly off. If timestamps are bad 3163 or jittery (like in Matroska), even constant bitrate streams might show 3164 fluctuating bitrate. 3165 3166 How exactly these values are calculated might change in the future. 3167 3168 In earlier versions of mpv, these properties returned a static (but bad) 3169 guess using a completely different method. 3170 3171``packet-video-bitrate``, ``packet-audio-bitrate``, ``packet-sub-bitrate`` 3172 Old and deprecated properties for ``video-bitrate``, ``audio-bitrate``, 3173 ``sub-bitrate``. They behave exactly the same, but return a value in 3174 kilobits. Also, they don't have any OSD formatting, though the same can be 3175 achieved with e.g. ``${=video-bitrate}``. 3176 3177 These properties shouldn't be used anymore. 3178 3179``audio-device-list`` 3180 The list of discovered audio devices. This is mostly for use with the 3181 client API, and reflects what ``--audio-device=help`` with the command line 3182 player returns. 3183 3184 When querying the property with the client API using ``MPV_FORMAT_NODE``, 3185 or with Lua ``mp.get_property_native``, this will return a mpv_node with 3186 the following contents: 3187 3188 :: 3189 3190 MPV_FORMAT_NODE_ARRAY 3191 MPV_FORMAT_NODE_MAP (for each device entry) 3192 "name" MPV_FORMAT_STRING 3193 "description" MPV_FORMAT_STRING 3194 3195 The ``name`` is what is to be passed to the ``--audio-device`` option (and 3196 often a rather cryptic audio API-specific ID), while ``description`` is 3197 human readable free form text. The description is set to the device name 3198 (minus mpv-specific ``<driver>/`` prefix) if no description is available 3199 or the description would have been an empty string. 3200 3201 The special entry with the name set to ``auto`` selects the default audio 3202 output driver and the default device. 3203 3204 The property can be watched with the property observation mechanism in 3205 the client API and in Lua scripts. (Technically, change notification is 3206 enabled the first time this property is read.) 3207 3208``audio-device`` (RW) 3209 Set the audio device. This directly reads/writes the ``--audio-device`` 3210 option, but on write accesses, the audio output will be scheduled for 3211 reloading. 3212 3213 Writing this property while no audio output is active will not automatically 3214 enable audio. (This is also true in the case when audio was disabled due to 3215 reinitialization failure after a previous write access to ``audio-device``.) 3216 3217 This property also doesn't tell you which audio device is actually in use. 3218 3219 How these details are handled may change in the future. 3220 3221``current-vo`` 3222 Current video output driver (name as used with ``--vo``). 3223 3224``current-ao`` 3225 Current audio output driver (name as used with ``--ao``). 3226 3227``shared-script-properties`` (RW) 3228 This is a key/value map of arbitrary strings shared between scripts for 3229 general use. The player itself does not use any data in it (although some 3230 builtin scripts may). The property is not preserved across player restarts. 3231 3232 This is very primitive, inefficient, and annoying to use. It's a makeshift 3233 solution which could go away any time (for example, when a better solution 3234 becomes available). This is also why this property has an annoying name. You 3235 should avoid using it, unless you absolutely have to. 3236 3237 Lua scripting has helpers starting with ``utils.shared_script_property_``. 3238 They are undocumented because you should not use this property. If you still 3239 think you must, you should use the helpers instead of the property directly. 3240 3241 You are supposed to use the ``change-list`` command to modify the contents. 3242 Reading, modifying, and writing the property manually could data loss if two 3243 scripts update different keys at the same time due to lack of 3244 synchronization. The Lua helpers take care of this. 3245 3246 (There is no way to ensure synchronization if two scripts try to update the 3247 same key at the same time.) 3248 3249``working-directory`` 3250 The working directory of the mpv process. Can be useful for JSON IPC users, 3251 because the command line player usually works with relative paths. 3252 3253``protocol-list`` 3254 List of protocol prefixes potentially recognized by the player. They are 3255 returned without trailing ``://`` suffix (which is still always required). 3256 In some cases, the protocol will not actually be supported (consider 3257 ``https`` if ffmpeg is not compiled with TLS support). 3258 3259``decoder-list`` 3260 List of decoders supported. This lists decoders which can be passed to 3261 ``--vd`` and ``--ad``. 3262 3263 ``codec`` 3264 Canonical codec name, which identifies the format the decoder can 3265 handle. 3266 3267 ``driver`` 3268 The name of the decoder itself. Often, this is the same as ``codec``. 3269 Sometimes it can be different. It is used to distinguish multiple 3270 decoders for the same codec. 3271 3272 ``description`` 3273 Human readable description of the decoder and codec. 3274 3275 When querying the property with the client API using ``MPV_FORMAT_NODE``, 3276 or with Lua ``mp.get_property_native``, this will return a mpv_node with 3277 the following contents: 3278 3279 :: 3280 3281 MPV_FORMAT_NODE_ARRAY 3282 MPV_FORMAT_NODE_MAP (for each decoder entry) 3283 "codec" MPV_FORMAT_STRING 3284 "driver" MPV_FORMAT_STRING 3285 "description" MPV_FORMAT_STRING 3286 3287``encoder-list`` 3288 List of libavcodec encoders. This has the same format as ``decoder-list``. 3289 The encoder names (``driver`` entries) can be passed to ``--ovc`` and 3290 ``--oac`` (without the ``lavc:`` prefix required by ``--vd`` and ``--ad``). 3291 3292``demuxer-lavf-list`` 3293 List of available libavformat demuxers' names. This can be used to check 3294 for support for a specific format or use with ``--demuxer-lavf-format``. 3295 3296``input-key-list`` 3297 List of `Key names`_, same as output by ``--input-keylist``. 3298 3299``mpv-version`` 3300 The mpv version/copyright string. Depending on how the binary was built, it 3301 might contain either a release version, or just a git hash. 3302 3303``mpv-configuration`` 3304 The configuration arguments which were passed to the build system 3305 (typically the way ``./waf configure ...`` was invoked). 3306 3307``ffmpeg-version`` 3308 The contents of the ``av_version_info()`` API call. This is a string which 3309 identifies the build in some way, either through a release version number, 3310 or a git hash. This applies to Libav as well (the property is still named 3311 the same.) This property is unavailable if mpv is linked against older 3312 FFmpeg and Libav versions. 3313 3314``libass-version`` 3315 The value of ``ass_library_version()``. This is an integer, encoded in a 3316 somewhat weird form (apparently "hex BCD"), indicating the release version 3317 of the libass library linked to mpv. 3318 3319``options/<name>`` (RW) 3320 The value of option ``--<name>``. Most options can be changed at runtime by 3321 writing to this property. Note that many options require reloading the file 3322 for changes to take effect. If there is an equivalent property, prefer 3323 setting the property instead. 3324 3325 There shouldn't be any reason to access ``options/<name>`` instead of 3326 ``<name>``, except in situations in which the properties have different 3327 behavior or conflicting semantics. 3328 3329``file-local-options/<name>`` (RW) 3330 Similar to ``options/<name>``, but when setting an option through this 3331 property, the option is reset to its old value once the current file has 3332 stopped playing. Trying to write an option while no file is playing (or 3333 is being loaded) results in an error. 3334 3335 (Note that if an option is marked as file-local, even ``options/`` will 3336 access the local value, and the ``old`` value, which will be restored on 3337 end of playback, cannot be read or written until end of playback.) 3338 3339``option-info/<name>`` 3340 Additional per-option information. 3341 3342 This has a number of sub-properties. Replace ``<name>`` with the name of 3343 a top-level option. No guarantee of stability is given to any of these 3344 sub-properties - they may change radically in the feature. 3345 3346 ``option-info/<name>/name`` 3347 The name of the option. 3348 3349 ``option-info/<name>/type`` 3350 The name of the option type, like ``String`` or ``Integer``. For many 3351 complex types, this isn't very accurate. 3352 3353 ``option-info/<name>/set-from-commandline`` 3354 Whether the option was set from the mpv command line. What this is set 3355 to if the option is e.g. changed at runtime is left undefined (meaning 3356 it could change in the future). 3357 3358 ``option-info/<name>/set-locally`` 3359 Whether the option was set per-file. This is the case with 3360 automatically loaded profiles, file-dir configs, and other cases. It 3361 means the option value will be restored to the value before playback 3362 start when playback ends. 3363 3364 ``option-info/<name>/default-value`` 3365 The default value of the option. May not always be available. 3366 3367 ``option-info/<name>/min``, ``option-info/<name>/max`` 3368 Integer minimum and maximum values allowed for the option. Only 3369 available if the options are numeric, and the minimum/maximum has been 3370 set internally. It's also possible that only one of these is set. 3371 3372 ``option-info/<name>/choices`` 3373 If the option is a choice option, the possible choices. Choices that 3374 are integers may or may not be included (they can be implied by ``min`` 3375 and ``max``). Note that options which behave like choice options, but 3376 are not actual choice options internally, may not have this info 3377 available. 3378 3379``property-list`` 3380 The list of top-level properties. 3381 3382``profile-list`` 3383 The list of profiles and their contents. This is highly 3384 implementation-specific, and may change any time. Currently, it returns an 3385 array of options for each profile. Each option has a name and a value, with 3386 the value currently always being a string. Note that the options array is 3387 not a map, as order matters and duplicate entries are possible. Recursive 3388 profiles are not expanded, and show up as special ``profile`` options. 3389 3390``command-list`` 3391 The list of input commands. This returns an array of maps, where each map 3392 node represents a command. This map currently only has a single entry: 3393 ``name`` for the name of the command. (This property is supposed to be a 3394 replacement for ``--input-cmdlist``. The option dumps some more 3395 information, but it's a valid feature request to extend this property if 3396 needed.) 3397 3398``input-bindings`` 3399 The list of current input key bindings. This returns an array of maps, 3400 where each map node represents a binding for a single key/command. This map 3401 has the following entries: 3402 3403 ``key`` 3404 The key name. This is normalized and may look slightly different from 3405 how it was specified in the source (e.g. in input.conf). 3406 3407 ``cmd`` 3408 The command mapped to the key. (Currently, this is exactly the same 3409 string as specified in the source, other than stripping whitespace and 3410 comments. It's possible that it will be normalized in the future.) 3411 3412 ``is_weak`` 3413 If set to true, any existing and active user bindings will take priority. 3414 3415 ``owner`` 3416 If this entry exists, the name of the script (or similar) which added 3417 this binding. 3418 3419 ``section`` 3420 Name of the section this binding is part of. This is a rarely used 3421 mechanism. This entry may be removed or change meaning in the future. 3422 3423 ``priority`` 3424 A number. Bindings with a higher value are preferred over bindings 3425 with a lower value. If the value is negative, this binding is inactive 3426 and will not be triggered by input. Note that mpv does not use this 3427 value internally, and matching of bindings may work slightly differently 3428 in some cases. In addition, this value is dynamic and can change around 3429 at runtime. 3430 3431 ``comment`` 3432 If available, the comment following the command on the same line. (For 3433 example, the input.conf entry ``f cycle bla # toggle bla`` would 3434 result in an entry with ``comment = "toggle bla", cmd = "cycle bla"``.) 3435 3436 This property is read-only, and change notification is not supported. 3437 Currently, there is no mechanism to change key bindings at runtime, other 3438 than scripts adding or removing their own bindings. 3439 3440Inconsistencies between options and properties 3441---------------------------------------------- 3442 3443You can access (almost) all options as properties, though there are some 3444caveats with some properties (due to historical reasons): 3445 3446``vid``, ``aid``, ``sid`` 3447 While playback is active, these return the actually active tracks. For 3448 example, if you set ``aid=5``, and the currently played file contains no 3449 audio track with ID 5, the ``aid`` property will return ``no``. 3450 3451 Before mpv 0.31.0, you could set existing tracks at runtime only. 3452 3453``display-fps`` 3454 This inconsistent behavior is deprecated. Post-deprecation, the reported 3455 value and the option value are cleanly separated (``override-display-fps`` 3456 for the option value). 3457 3458``vf``, ``af`` 3459 If you set the properties during playback, and the filter chain fails to 3460 reinitialize, the option will be set, but the runtime filter chain does not 3461 change. On the other hand, the next video to be played will fail, because 3462 the initial filter chain cannot be created. 3463 3464 This behavior changed in mpv 0.31.0. Before this, the new value was rejected 3465 *iff* a video (for ``vf``) or an audio (for ``af``) track was active. If 3466 playback was not active, the behavior was the same as the current one. 3467 3468``playlist`` 3469 The property is read-only and returns the current internal playlist. The 3470 option is for loading playlist during command line parsing. For client API 3471 uses, you should use the ``loadlist`` command instead. 3472 3473``profile``, ``include`` 3474 These are write-only, and will perform actions as they are written to, 3475 exactly as if they were used on the mpv CLI commandline. Their only use is 3476 when using libmpv before ``mpv_initialize()``, which in turn is probably 3477 only useful in encoding mode. Normal libmpv users should use other 3478 mechanisms, such as the ``apply-profile`` command, and the 3479 ``mpv_load_config_file`` API function. Avoid these properties. 3480 3481Property Expansion 3482------------------ 3483 3484All string arguments to input commands as well as certain options (like 3485``--term-playing-msg``) are subject to property expansion. Note that property 3486expansion does not work in places where e.g. numeric parameters are expected. 3487(For example, the ``add`` command does not do property expansion. The ``set`` 3488command is an exception and not a general rule.) 3489 3490.. admonition:: Example for input.conf 3491 3492 ``i show-text "Filename: ${filename}"`` 3493 shows the filename of the current file when pressing the ``i`` key 3494 3495Whether property expansion is enabled by default depends on which API is used 3496(see `Flat command syntax`_, `Commands specified as arrays`_ and `Named 3497arguments`_), but it can always be enabled with the ``expand-properties`` 3498prefix or disabled with the ``raw`` prefix, as described in `Input Command 3499Prefixes`_. 3500 3501The following expansions are supported: 3502 3503``${NAME}`` 3504 Expands to the value of the property ``NAME``. If retrieving the property 3505 fails, expand to an error string. (Use ``${NAME:}`` with a trailing 3506 ``:`` to expand to an empty string instead.) 3507 If ``NAME`` is prefixed with ``=``, expand to the raw value of the property 3508 (see section below). 3509``${NAME:STR}`` 3510 Expands to the value of the property ``NAME``, or ``STR`` if the 3511 property cannot be retrieved. ``STR`` is expanded recursively. 3512``${?NAME:STR}`` 3513 Expands to ``STR`` (recursively) if the property ``NAME`` is available. 3514``${!NAME:STR}`` 3515 Expands to ``STR`` (recursively) if the property ``NAME`` cannot be 3516 retrieved. 3517``${?NAME==VALUE:STR}`` 3518 Expands to ``STR`` (recursively) if the property ``NAME`` expands to a 3519 string equal to ``VALUE``. You can prefix ``NAME`` with ``=`` in order to 3520 compare the raw value of a property (see section below). If the property 3521 is unavailable, or other errors happen when retrieving it, the value is 3522 never considered equal. 3523 Note that ``VALUE`` can't contain any of the characters ``:`` or ``}``. 3524 Also, it is possible that escaping with ``"`` or ``%`` might be added in 3525 the future, should the need arise. 3526``${!NAME==VALUE:STR}`` 3527 Same as with the ``?`` variant, but ``STR`` is expanded if the value is 3528 not equal. (Using the same semantics as with ``?``.) 3529``$$`` 3530 Expands to ``$``. 3531``$}`` 3532 Expands to ``}``. (To produce this character inside recursive 3533 expansion.) 3534``$>`` 3535 Disable property expansion and special handling of ``$`` for the rest 3536 of the string. 3537 3538In places where property expansion is allowed, C-style escapes are often 3539accepted as well. Example: 3540 3541 - ``\n`` becomes a newline character 3542 - ``\\`` expands to ``\`` 3543 3544Raw and Formatted Properties 3545---------------------------- 3546 3547Normally, properties are formatted as human-readable text, meant to be 3548displayed on OSD or on the terminal. It is possible to retrieve an unformatted 3549(raw) value from a property by prefixing its name with ``=``. These raw values 3550can be parsed by other programs and follow the same conventions as the options 3551associated with the properties. 3552 3553.. admonition:: Examples 3554 3555 - ``${time-pos}`` expands to ``00:14:23`` (if playback position is at 14 3556 minutes 23 seconds) 3557 - ``${=time-pos}`` expands to ``863.4`` (same time, plus 400 milliseconds - 3558 milliseconds are normally not shown in the formatted case) 3559 3560Sometimes, the difference in amount of information carried by raw and formatted 3561property values can be rather big. In some cases, raw values have more 3562information, like higher precision than seconds with ``time-pos``. Sometimes 3563it is the other way around, e.g. ``aid`` shows track title and language in the 3564formatted case, but only the track number if it is raw. 3565