1mpv 2### 3 4############## 5a media player 6############## 7 8:Copyright: GPLv2+ 9:Manual section: 1 10:Manual group: multimedia 11 12.. contents:: Table of Contents 13 14SYNOPSIS 15======== 16 17| **mpv** [options] [file|URL|PLAYLIST|-] 18| **mpv** [options] files 19 20DESCRIPTION 21=========== 22 23**mpv** is a media player based on MPlayer and mplayer2. It supports a wide variety of video 24file formats, audio and video codecs, and subtitle types. Special input URL 25types are available to read input from a variety of sources other than disk 26files. Depending on platform, a variety of different video and audio output 27methods are supported. 28 29Usage examples to get you started quickly can be found at the end of this man 30page. 31 32 33INTERACTIVE CONTROL 34=================== 35 36mpv has a fully configurable, command-driven control layer which allows you 37to control mpv using keyboard, mouse, or remote control (there is no 38LIRC support - configure remotes as input devices instead). 39 40See the ``--input-`` options for ways to customize it. 41 42The following listings are not necessarily complete. See ``etc/input.conf`` for 43a list of default bindings. User ``input.conf`` files and Lua scripts can 44define additional key bindings. 45 46See also ``--input-test`` for interactive binding details by key, and the 47`stats`_ built-in script for key bindings list (including print to terminal). 48 49Keyboard Control 50---------------- 51 52LEFT and RIGHT 53 Seek backward/forward 5 seconds. Shift+arrow does a 1 second exact seek 54 (see ``--hr-seek``). 55 56UP and DOWN 57 Seek forward/backward 1 minute. Shift+arrow does a 5 second exact seek (see 58 ``--hr-seek``). 59 60Ctrl+LEFT and Ctrl+RIGHT 61 Seek to the previous/next subtitle. Subject to some restrictions and 62 might not always work; see ``sub-seek`` command. 63 64Ctrl+Shift+Left and Ctrl+Shift+Right 65 Adjust subtitle delay so that the next or previous subtitle is displayed 66 now. This is especially useful to sync subtitles to audio. 67 68[ and ] 69 Decrease/increase current playback speed by 10%. 70 71{ and } 72 Halve/double current playback speed. 73 74BACKSPACE 75 Reset playback speed to normal. 76 77Shift+BACKSPACE 78 Undo the last seek. This works only if the playlist entry was not changed. 79 Hitting it a second time will go back to the original position. 80 See ``revert-seek`` command for details. 81 82Shift+Ctrl+BACKSPACE 83 Mark the current position. This will then be used by ``Shift+BACKSPACE`` 84 as revert position (once you seek back, the marker will be reset). You can 85 use this to seek around in the file and then return to the exact position 86 where you left off. 87 88< and > 89 Go backward/forward in the playlist. 90 91ENTER 92 Go forward in the playlist. 93 94p / SPACE 95 Pause (pressing again unpauses). 96 97\. 98 Step forward. Pressing once will pause, every consecutive press will 99 play one frame and then go into pause mode again. 100 101, 102 Step backward. Pressing once will pause, every consecutive press will 103 play one frame in reverse and then go into pause mode again. 104 105q 106 Stop playing and quit. 107 108Q 109 Like ``q``, but store the current playback position. Playing the same file 110 later will resume at the old playback position if possible. 111 112/ and * 113 Decrease/increase volume. 114 1159 and 0 116 Decrease/increase volume. 117 118m 119 Mute sound. 120 121\_ 122 Cycle through the available video tracks. 123 124\# 125 Cycle through the available audio tracks. 126 127f 128 Toggle fullscreen (see also ``--fs``). 129 130ESC 131 Exit fullscreen mode. 132 133T 134 Toggle stay-on-top (see also ``--ontop``). 135 136w and W 137 Decrease/increase pan-and-scan range. The ``e`` key does the same as 138 ``W`` currently, but use is discouraged. 139 140o (also P) 141 Show progression bar, elapsed time and total duration on the OSD. 142 143O 144 Toggle OSD states between normal and playback time/duration. 145 146v 147 Toggle subtitle visibility. 148 149j and J 150 Cycle through the available subtitles. 151 152z and Z 153 Adjust subtitle delay by +/- 0.1 seconds. The ``x`` key does the same as 154 ``Z`` currently, but use is discouraged. 155 156l 157 Set/clear A-B loop points. See ``ab-loop`` command for details. 158 159L 160 Toggle infinite looping. 161 162Ctrl + and Ctrl - 163 Adjust audio delay (A/V sync) by +/- 0.1 seconds. 164 165Shift+g and Shift+f 166 Adjust subtitle font size by +/- 10%. 167 168u 169 Switch between applying no style overrides to SSA/ASS subtitles, and 170 overriding them almost completely with the normal subtitle style. See 171 ``--sub-ass-override`` for more info. 172 173V 174 Toggle subtitle VSFilter aspect compatibility mode. See 175 ``--sub-ass-vsfilter-aspect-compat`` for more info. 176 177r and R 178 Move subtitles up/down. The ``t`` key does the same as ``R`` currently, but 179 use is discouraged. 180 181s 182 Take a screenshot. 183 184S 185 Take a screenshot, without subtitles. (Whether this works depends on VO 186 driver support.) 187 188Ctrl s 189 Take a screenshot, as the window shows it (with subtitles, OSD, and scaled 190 video). 191 192PGUP and PGDWN 193 Seek to the beginning of the previous/next chapter. In most cases, 194 "previous" will actually go to the beginning of the current chapter; see 195 ``--chapter-seek-threshold``. 196 197Shift+PGUP and Shift+PGDWN 198 Seek backward or forward by 10 minutes. (This used to be mapped to 199 PGUP/PGDWN without Shift.) 200 201d 202 Activate/deactivate deinterlacer. 203 204A 205 Cycle aspect ratio override. 206 207Ctrl h 208 Toggle hardware video decoding on/off. 209 210Alt+LEFT, Alt+RIGHT, Alt+UP, Alt+DOWN 211 Move the video rectangle (panning). 212 213Alt + and Alt - 214 Combining ``Alt`` with the ``+`` or ``-`` keys changes video zoom. 215 216Alt+BACKSPACE 217 Reset the pan/zoom settings. 218 219F8 220 Show the playlist and the current position in it (useful only if a UI window 221 is used, broken on the terminal). 222 223F9 224 Show the list of audio and subtitle streams (useful only if a UI window is 225 used, broken on the terminal). 226 227i and I 228 Show/toggle an overlay displaying statistics about the currently playing 229 file such as codec, framerate, number of dropped frames and so on. See 230 `STATS`_ for more information. 231 232del 233 Cycle OSC visibility between never / auto (mouse-move) / always 234 235\` 236 Show the console. (ESC closes it again. See `CONSOLE`_.) 237 238(The following keys are valid only when using a video output that supports the 239corresponding adjustment.) 240 2411 and 2 242 Adjust contrast. 243 2443 and 4 245 Adjust brightness. 246 2475 and 6 248 Adjust gamma. 249 2507 and 8 251 Adjust saturation. 252 253Alt+0 (and command+0 on macOS) 254 Resize video window to half its original size. 255 256Alt+1 (and command+1 on macOS) 257 Resize video window to its original size. 258 259Alt+2 (and command+2 on macOS) 260 Resize video window to double its original size. 261 262command + f (macOS only) 263 Toggle fullscreen (see also ``--fs``). 264 265(The following keys are valid if you have a keyboard with multimedia keys.) 266 267PAUSE 268 Pause. 269 270STOP 271 Stop playing and quit. 272 273PREVIOUS and NEXT 274 Seek backward/forward 1 minute. 275 276 277If you miss some older key bindings, look at ``etc/restore-old-bindings.conf`` 278in the mpv git repository. 279 280Mouse Control 281------------- 282 283Left double click 284 Toggle fullscreen on/off. 285 286Right click 287 Toggle pause on/off. 288 289Forward/Back button 290 Skip to next/previous entry in playlist. 291 292Wheel up/down 293 Seek forward/backward 10 seconds. 294 295Wheel left/right 296 Decrease/increase volume. 297 298 299USAGE 300===== 301 302Command line arguments starting with ``-`` are interpreted as options, 303everything else as filenames or URLs. All options except *flag* options (or 304choice options which include ``yes``) require a parameter in the form 305``--option=value``. 306 307One exception is the lone ``-`` (without anything else), which means media data 308will be read from stdin. Also, ``--`` (without anything else) will make the 309player interpret all following arguments as filenames, even if they start with 310``-``. (To play a file named ``-``, you need to use ``./-``.) 311 312Every *flag* option has a *no-flag* counterpart, e.g. the opposite of the 313``--fs`` option is ``--no-fs``. ``--fs=yes`` is same as ``--fs``, ``--fs=no`` 314is the same as ``--no-fs``. 315 316If an option is marked as *(XXX only)*, it will only work in combination with 317the *XXX* option or if *XXX* is compiled in. 318 319Legacy option syntax 320-------------------- 321 322The ``--option=value`` syntax is not strictly enforced, and the alternative 323legacy syntax ``-option value`` and ``-option=value`` will also work. This is 324mostly for compatibility with MPlayer. Using these should be avoided. Their 325semantics can change any time in the future. 326 327For example, the alternative syntax will consider an argument following the 328option a filename. ``mpv -fs no`` will attempt to play a file named ``no``, 329because ``--fs`` is a flag option that requires no parameter. If an option 330changes and its parameter becomes optional, then a command line using the 331alternative syntax will break. 332 333Until mpv 0.31.0, there was no difference whether an option started with ``--`` 334or a single ``-``. Newer mpv releases strictly expect that you pass the option 335value after a ``=``. For example, before ``mpv --log-file f.txt`` would write 336a log to ``f.txt``, but now this command line fails, as ``--log-file`` expects 337an option value, and ``f.txt`` is simply considered a normal file to be played 338(as in ``mpv f.txt``). 339 340The future plan is that ``-option value`` will not work anymore, and options 341with a single ``-`` behave the same as ``--`` options. 342 343Escaping spaces and other special characters 344-------------------------------------------- 345 346Keep in mind that the shell will partially parse and mangle the arguments you 347pass to mpv. For example, you might need to quote or escape options and 348filenames: 349 350 ``mpv "filename with spaces.mkv" --title="window title"`` 351 352It gets more complicated if the suboption parser is involved. The suboption 353parser puts several options into a single string, and passes them to a 354component at once, instead of using multiple options on the level of the 355command line. 356 357The suboption parser can quote strings with ``"`` and ``[...]``. 358Additionally, there is a special form of quoting with ``%n%`` described below. 359 360For example, assume the hypothetical ``foo`` filter can take multiple options: 361 362 ``mpv test.mkv --vf=foo:option1=value1:option2:option3=value3,bar`` 363 364This passes ``option1`` and ``option3`` to the ``foo`` filter, with ``option2`` 365as flag (implicitly ``option2=yes``), and adds a ``bar`` filter after that. If 366an option contains spaces or characters like ``,`` or ``:``, you need to quote 367them: 368 369 ``mpv '--vf=foo:option1="option value with spaces",bar'`` 370 371Shells may actually strip some quotes from the string passed to the commandline, 372so the example quotes the string twice, ensuring that mpv receives the ``"`` 373quotes. 374 375The ``[...]`` form of quotes wraps everything between ``[`` and ``]``. It's 376useful with shells that don't interpret these characters in the middle of 377an argument (like bash). These quotes are balanced (since mpv 0.9.0): the ``[`` 378and ``]`` nest, and the quote terminates on the last ``]`` that has no matching 379``[`` within the string. (For example, ``[a[b]c]`` results in ``a[b]c``.) 380 381The fixed-length quoting syntax is intended for use with external 382scripts and programs. 383 384It is started with ``%`` and has the following format:: 385 386 %n%string_of_length_n 387 388.. admonition:: Examples 389 390 ``mpv '--vf=foo:option1=%11%quoted text' test.avi`` 391 392 Or in a script: 393 394 ``mpv --vf=foo:option1=%`expr length "$NAME"`%"$NAME" test.avi`` 395 396Note: where applicable with JSON-IPC, ``%n%`` is the length in UTF-8 bytes, 397after decoding the JSON data. 398 399Suboptions passed to the client API are also subject to escaping. Using 400``mpv_set_option_string()`` is exactly like passing ``--name=data`` to the 401command line (but without shell processing of the string). Some options 402support passing values in a more structured way instead of flat strings, and 403can avoid the suboption parsing mess. For example, ``--vf`` supports 404``MPV_FORMAT_NODE``, which lets you pass suboptions as a nested data structure 405of maps and arrays. 406 407Paths 408----- 409 410Some care must be taken when passing arbitrary paths and filenames to mpv. For 411example, paths starting with ``-`` will be interpreted as options. Likewise, 412if a path contains the sequence ``://``, the string before that might be 413interpreted as protocol prefix, even though ``://`` can be part of a legal 414UNIX path. To avoid problems with arbitrary paths, you should be sure that 415absolute paths passed to mpv start with ``/``, and prefix relative paths with 416``./``. 417 418Using the ``file://`` pseudo-protocol is discouraged, because it involves 419strange URL unescaping rules. 420 421The name ``-`` itself is interpreted as stdin, and will cause mpv to disable 422console controls. (Which makes it suitable for playing data piped to stdin.) 423 424The special argument ``--`` can be used to stop mpv from interpreting the 425following arguments as options. 426 427When using the client API, you should strictly avoid using ``mpv_command_string`` 428for invoking the ``loadfile`` command, and instead prefer e.g. ``mpv_command`` 429to avoid the need for filename escaping. 430 431For paths passed to suboptions, the situation is further complicated by the 432need to escape special characters. To work this around, the path can be 433additionally wrapped in the fixed-length syntax, e.g. ``%n%string_of_length_n`` 434(see above). 435 436Some mpv options interpret paths starting with ``~``. 437Currently, the prefix ``~~home/`` expands to the mpv configuration directory 438(usually ``~/.config/mpv/``). 439``~/`` expands to the user's home directory. (The trailing ``/`` is always 440required.) The following paths are currently recognized: 441 442================ =============================================================== 443Name Meaning 444================ =============================================================== 445``~~/`` If the subpath exists in any of the mpv's config directories 446 the path of the existing file/dir is returned. Otherwise this 447 is equivalent to ``~~home/``. 448 Note that if --no-config is used ``~~/foobar`` will resolve to 449 ``foobar`` which can be unexpected. 450``~/`` user home directory root (similar to shell, ``$HOME``) 451``~~home/`` mpv config dir (for example ``~/.config/mpv/``) 452``~~global/`` the global config path, if available (not on win32) 453``~~osxbundle/`` the macOS bundle resource path (macOS only) 454``~~desktop/`` the path to the desktop (win32, macOS) 455``~~exe_dir/`` win32 only: the path to the directory containing the exe (for 456 config file purposes; ``$MPV_HOME`` overrides it) 457``~~old_home/`` do not use 458================ =============================================================== 459 460 461Per-File Options 462---------------- 463 464When playing multiple files, any option given on the command line usually 465affects all files. Example:: 466 467 mpv --a file1.mkv --b file2.mkv --c 468 469=============== =========================== 470File Active options 471=============== =========================== 472file1.mkv ``--a --b --c`` 473file2.mkv ``--a --b --c`` 474=============== =========================== 475 476(This is different from MPlayer and mplayer2.) 477 478Also, if any option is changed at runtime (via input commands), they are not 479reset when a new file is played. 480 481Sometimes, it is useful to change options per-file. This can be achieved by 482adding the special per-file markers ``--{`` and ``--}``. (Note that you must 483escape these on some shells.) Example:: 484 485 mpv --a file1.mkv --b --\{ --c file2.mkv --d file3.mkv --e --\} file4.mkv --f 486 487=============== =========================== 488File Active options 489=============== =========================== 490file1.mkv ``--a --b --f`` 491file2.mkv ``--a --b --f --c --d --e`` 492file3.mkv ``--a --b --f --c --d --e`` 493file4.mkv ``--a --b --f`` 494=============== =========================== 495 496Additionally, any file-local option changed at runtime is reset when the current 497file stops playing. If option ``--c`` is changed during playback of 498``file2.mkv``, it is reset when advancing to ``file3.mkv``. This only affects 499file-local options. The option ``--a`` is never reset here. 500 501 502List Options 503------------ 504 505Some options which store lists of option values can have action suffixes. For 506example, the ``--display-tags`` option takes a ``,``-separated list of tags, but 507the option also allows you to append a single tag with ``--display-tags-append``, 508and the tag name can for example contain a literal ``,`` without the need for 509escaping. 510 511String list and path list options 512~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 513 514String lists are separated by ``,``. The strings are not parsed or interpreted 515by the option system itself. However, most 516 517Path or file list options use ``:`` (Unix) or ``;`` (Windows) as separator, 518instead of ``,``. 519 520They support the following operations: 521 522============= =============================================== 523Suffix Meaning 524============= =============================================== 525-set Set a list of items (using the list separator, escaped with backslash) 526-append Append single item (does not interpret escapes) 527-add Append 1 or more items (same syntax as -set) 528-pre Prepend 1 or more items (same syntax as -set) 529-clr Clear the option (remove all items) 530-remove Delete item if present (does not interpret escapes) 531-del Delete 1 or more items by integer index (deprecated) 532-toggle Append an item, or remove if if it already exists (no escapes) 533============= =============================================== 534 535``-append`` is meant as a simple way to append a single item without having 536to escape the argument (you may still need to escape on the shell level). 537 538Key/value list options 539~~~~~~~~~~~~~~~~~~~~~~ 540 541A key/value list is a list of key/value string pairs. In programming languages, 542this type of data structure is often called a map or a dictionary. The order 543normally does not matter, although in some cases the order might matter. 544 545They support the following operations: 546 547============= =============================================== 548Suffix Meaning 549============= =============================================== 550-set Set a list of items (using ``,`` as separator) 551-append Append a single item (escapes for the key, no escapes for the value) 552-add Append 1 or more items (same syntax as -set) 553-remove Delete item by key if present (does not interpret escapes) 554============= =============================================== 555 556Keys are unique within the list. If an already present key is set, the existing 557key is removed before the new value is appended. 558 559If you want to pass a value without interpreting it for escapes or ``,``, it is 560recommended to use the ``-add`` variant. When using libmpv, prefer using 561``MPV_FORMAT_NODE_MAP``; when using a scripting backend or the JSON IPC, use an 562appropriate structured data type. 563 564Prior to mpv 0.33, ``:`` was also recognized as separator by ``-set``. 565 566Filter options 567~~~~~~~~~~~~~~ 568 569This is a very complex option type for the ``--af`` and ``--vf`` options only. 570They often require complicated escaping. See `VIDEO FILTERS`_ for details. They 571support the following operations: 572 573============= =============================================== 574Suffix Meaning 575============= =============================================== 576-set Set a list of filters (using ``,`` as separator) 577-append Append single filter 578-add Append 1 or more filters (same syntax as -set) 579-pre Prepend 1 or more filters (same syntax as -set) 580-clr Clear the option (remove all filters) 581-remove Delete filter if present 582-del Delete 1 or more filters by integer index or filter label (deprecated) 583-toggle Append a filter, or remove if if it already exists 584-help Pseudo operation that prints a help text to the terminal 585============= =============================================== 586 587General 588~~~~~~~ 589 590Without suffix, the operation used is normally ``-set``. 591 592Although some operations allow specifying multiple items, using this is strongly 593discouraged and deprecated, except for ``-set``. There is a chance that 594operations like ``-add`` and ``-pre`` will work like ``-append`` and accept a 595single, unescaped item only (so the ``,`` separator will not be interpreted and 596is passed on as part of the value). 597 598Some options (like ``--sub-file``, ``--audio-file``, ``--glsl-shader``) are 599aliases for the proper option with ``-append`` action. For example, 600``--sub-file`` is an alias for ``--sub-files-append``. 601 602Options of this type can be changed at runtime using the ``change-list`` 603command, which takes the suffix (without the ``-``) as separate operation 604parameter. 605 606CONFIGURATION FILES 607=================== 608 609Location and Syntax 610------------------- 611 612You can put all of the options in configuration files which will be read every 613time mpv is run. The system-wide configuration file 'mpv.conf' is in your 614configuration directory (e.g. ``/etc/mpv`` or ``/usr/local/etc/mpv``), the 615user-specific one is ``~/.config/mpv/mpv.conf``. For details and platform 616specifics (in particular Windows paths) see the `FILES`_ section. 617 618User-specific options override system-wide options and options given on the 619command line override either. The syntax of the configuration files is 620``option=value``. Everything after a *#* is considered a comment. Options 621that work without values can be enabled by setting them to *yes* and disabled by 622setting them to *no*. Even suboptions can be specified in this way. 623 624.. admonition:: Example configuration file 625 626 :: 627 628 # Use GPU-accelerated video output by default. 629 vo=gpu 630 # Use quotes for text that can contain spaces: 631 term-status-msg="Time: ${time-pos}" 632 633Escaping spaces and special characters 634-------------------------------------- 635 636This is done like with command line options. The shell is not involved here, 637but option values still need to be quoted as a whole if it contains certain 638characters like spaces. A config entry can be quoted with ``"``, 639as well as with the fixed-length syntax (``%n%``) mentioned before. This is like 640passing the exact contents of the quoted string as command line option. C-style 641escapes are currently _not_ interpreted on this level, although some options do 642this manually. (This is a mess and should probably be changed at some point.) 643 644Putting Command Line Options into the Configuration File 645-------------------------------------------------------- 646 647Almost all command line options can be put into the configuration file. Here 648is a small guide: 649 650======================= ======================== 651Option Configuration file entry 652======================= ======================== 653``--flag`` ``flag`` 654``-opt val`` ``opt=val`` 655``--opt=val`` ``opt=val`` 656``-opt "has spaces"`` ``opt="has spaces"`` 657======================= ======================== 658 659File-specific Configuration Files 660--------------------------------- 661 662You can also write file-specific configuration files. If you wish to have a 663configuration file for a file called 'video.avi', create a file named 664'video.avi.conf' with the file-specific options in it and put it in 665``~/.config/mpv/``. You can also put the configuration file in the same directory 666as the file to be played. Both require you to set the ``--use-filedir-conf`` 667option (either on the command line or in your global config file). If a 668file-specific configuration file is found in the same directory, no 669file-specific configuration is loaded from ``~/.config/mpv``. In addition, the 670``--use-filedir-conf`` option enables directory-specific configuration files. 671For this, mpv first tries to load a mpv.conf from the same directory 672as the file played and then tries to load any file-specific configuration. 673 674 675Profiles 676-------- 677 678To ease working with different configurations, profiles can be defined in the 679configuration files. A profile starts with its name in square brackets, 680e.g. ``[my-profile]``. All following options will be part of the profile. A 681description (shown by ``--profile=help``) can be defined with the 682``profile-desc`` option. To end the profile, start another one or use the 683profile name ``default`` to continue with normal options. 684 685You can list profiles with ``--profile=help``, and show the contents of a 686profile with ``--show-profile=<name>`` (replace ``<name>`` with the profile 687name). You can apply profiles on start with the ``--profile=<name>`` option, 688or at runtime with the ``apply-profile <name>`` command. 689 690.. admonition:: Example mpv config file with profiles 691 692 :: 693 694 # normal top-level option 695 fullscreen=yes 696 697 # a profile that can be enabled with --profile=big-cache 698 [big-cache] 699 cache=yes 700 demuxer-max-bytes=123400KiB 701 demuxer-readahead-secs=20 702 703 [slow] 704 profile-desc="some profile name" 705 # reference a builtin profile 706 profile=gpu-hq 707 708 [fast] 709 vo=vdpau 710 711 # using a profile again extends it 712 [slow] 713 framedrop=no 714 # you can also include other profiles 715 profile=big-cache 716 717Runtime profiles 718---------------- 719 720Profiles can be set at runtime with ``apply-profile`` command. Since this 721operation is "destructive" (every item in a profile is simply set as an 722option, overwriting the previous value), you can't just enable and disable 723profiles again. 724 725As a partial remedy, there is a way to make profiles save old option values 726before overwriting them with the profile values, and then restoring the old 727values at a later point using ``apply-profile <profile-name> restore``. 728 729This can be enabled with the ``profile-restore`` option, which takes one of 730the following options: 731 732 ``default`` 733 Does nothing, and nothing can be restored (default). 734 735 ``copy`` 736 When applying a profile, copy the old values of all profile options to a 737 backup before setting them from the profile. These options are reset to 738 their old values using the backup when restoring. 739 740 Every profile has its own list of backed up values. If the backup 741 already exists (e.g. if ``apply-profile name`` was called more than 742 once in a row), the existing backup is no changed. The restore operation 743 will remove the backup. 744 745 It's important to know that restoring does not "undo" setting an option, 746 but simply copies the old option value. Consider for example ``vf-add``, 747 appends an entry to ``vf``. This mechanism will simply copy the entire 748 ``vf`` list, and does _not_ execute the inverse of ``vf-add`` (that 749 would be ``vf-remove``) on restoring. 750 751 Note that if a profile contains recursive profiles (via the ``profile`` 752 option), the options in these recursive profiles are treated as if they 753 were part of this profile. The referenced profile's backup list is not 754 used when creating or using the backup. Restoring a profile does not 755 restore referenced profiles, only the options of referenced profiles (as 756 if they were part of the main profile). 757 758 ``copy-equal`` 759 Similar to ``copy``, but restore an option only if it has the same value 760 as the value effectively set by the profile. This tries to deal with 761 the situation when the user does not want the option to be reset after 762 interactively changing it. 763 764.. admonition:: Example 765 766 :: 767 768 [something] 769 profile-restore=copy-equal 770 vf-add=rotate=90 771 772 Then running these commands will result in behavior as commented: 773 774 :: 775 776 set vf vflip 777 apply-profile something 778 vf-add=hflip 779 apply-profile something 780 # vf == vflip,rotate=90,hflip,rotate=90 781 apply-profile something restore 782 # vf == vflip 783 784Conditional auto profiles 785------------------------- 786 787Profiles which have the ``profile-cond`` option set are applied automatically 788if the associated condition matches (unless auto profiles are disabled). The 789option takes a string, which is interpreted as Lua condition. If evaluating the 790expression returns true, the profile is applied, if it returns false, it is 791ignored. This Lua code execution is not sandboxed. 792 793Any variables in condition expressions can reference properties. If an 794identifier is not already defined by Lua or mpv, it is interpreted as property. 795For example, ``pause`` would return the current pause status. You cannot 796reference properties with ``-`` this way since that would denote a subtraction, 797but if the variable name contains any ``_`` characters, they are turned into 798``-``. For example, ``playback_time`` would return the property 799``playback-time``. 800 801A more robust way to access properties is using ``p.property_name`` or 802``get("property-name", default_value)``. The automatic variable to property 803magic will break if a new identifier with the same name is introduced (for 804example, if a function named ``pause()`` were added, ``pause`` would return a 805function value instead of the value of the ``pause`` property). 806 807Note that if a property is not available, it will return ``nil``, which can 808cause errors if used in expressions. These are logged in verbose mode, and the 809expression is considered to be false. 810 811Whenever a property referenced by a profile condition changes, the condition 812is re-evaluated. If the return value of the condition changes from false or 813error to true, the profile is applied. 814 815This mechanism tries to "unapply" profiles once the condition changes from true 816to false. If you want to use this, you need to set ``profile-restore`` for the 817profile. Another possibility it to create another profile with an inverse 818condition to undo the other profile. 819 820Recursive profiles can be used. But it is discouraged to reference other 821conditional profiles in a conditional profile, since this can lead to tricky 822and unintuitive behavior. 823 824.. admonition:: Example 825 826 Make only HD video look funny: 827 828 :: 829 830 [something] 831 profile-desc=HD video sucks 832 profile-cond=width >= 1280 833 hue=-50 834 835 If you want the profile to be reverted if the condition goes to false again, 836 you can set ``profile-restore``: 837 838 :: 839 840 [something] 841 profile-desc=Mess up video when entering fullscreen 842 profile-cond=fullscreen 843 profile-restore=copy 844 vf-add=rotate=90 845 846 This appends the ``rotate`` filter to the video filter chain when entering 847 fullscreen. When leaving fullscreen, the ``vf`` option is set to the value 848 it had before entering fullscreen. Note that this would also remove any 849 other filters that were added during fullscreen mode by the user. Avoiding 850 this is trickier, and could for example be solved by adding a second profile 851 with an inverse condition and operation: 852 853 :: 854 855 [something] 856 profile-cond=fullscreen 857 vf-add=@rot:rotate=90 858 859 [something-inv] 860 profile-cond=not fullscreen 861 vf-remove=@rot 862 863.. warning:: 864 865 Every time an involved property changes, the condition is evaluated again. 866 If your condition uses ``p.playback_time`` for example, the condition is 867 re-evaluated approximately on every video frame. This is probably slow. 868 869This feature is managed by an internal Lua script. Conditions are executed as 870Lua code within this script. Its environment contains at least the following 871things: 872 873``(function environment table)`` 874 Every Lua function has an environment table. This is used for identifier 875 access. There is no named Lua symbol for it; it is implicit. 876 877 The environment does "magic" accesses to mpv properties. If an identifier 878 is not already defined in ``_G``, it retrieves the mpv property of the same 879 name. Any occurrences of ``_`` in the name are replaced with ``-`` before 880 reading the property. The returned value is as retrieved by 881 ``mp.get_property_native(name)``. Internally, a cache of property values, 882 updated by observing the property is used instead, so properties that are 883 not observable will be stuck at the initial value forever. 884 885 If you want to access properties, that actually contain ``_`` in the name, 886 use ``get()`` (which does not perform transliteration). 887 888 Internally, the environment table has a ``__index`` meta method set, which 889 performs the access logic. 890 891``p`` 892 A "magic" table similar to the environment table. Unlike the latter, this 893 does not prefer accessing variables defined in ``_G`` - it always accesses 894 properties. 895 896``get(name [, def])`` 897 Read a property and return its value. If the property value is ``nil`` (e.g. 898 if the property does not exist), ``def`` is returned. 899 900 This is superficially similar to ``mp.get_property_native(name)``. An 901 important difference is that this accesses the property cache, and enables 902 the change detection logic (which is essential to the dynamic runtime 903 behavior of auto profiles). Also, it does not return an error value as 904 second return value. 905 906 The "magic" tables mentioned above use this function as backend. It does not 907 perform the ``_`` transliteration. 908 909In addition, the same environment as in a blank mpv Lua script is present. For 910example, ``math`` is defined and gives access to the Lua standard math library. 911 912.. warning:: 913 914 This feature is subject to change indefinitely. You might be forced to 915 adjust your profiles on mpv updates. 916 917Legacy auto profiles 918-------------------- 919 920Some profiles are loaded automatically using a legacy mechanism. The following 921example demonstrates this: 922 923.. admonition:: Auto profile loading 924 925 :: 926 927 [extension.mkv] 928 profile-desc="profile for .mkv files" 929 vf=vflip 930 931The profile name follows the schema ``type.name``, where type can be 932``protocol`` for the input/output protocol in use (see ``--list-protocols``), 933and ``extension`` for the extension of the path of the currently played file 934(*not* the file format). 935 936This feature is very limited, and is considered soft-deprecated. Use conditional 937auto profiles. 938 939Using mpv from other programs or scripts 940======================================== 941 942There are three choices for using mpv from other programs or scripts: 943 944 1. Calling it as UNIX process. If you do this, *do not parse terminal output*. 945 The terminal output is intended for humans, and may change any time. In 946 addition, terminal behavior itself may change any time. Compatibility 947 cannot be guaranteed. 948 949 Your code should work even if you pass ``--no-terminal``. Do not attempt 950 to simulate user input by sending terminal control codes to mpv's stdin. 951 If you need interactive control, using ``--input-ipc-server`` is 952 recommended. This gives you access to the `JSON IPC`_ over unix domain 953 sockets (or named pipes on Windows). 954 955 Depending on what you do, passing ``--no-config`` or ``--config-dir`` may 956 be a good idea to avoid conflicts with the normal mpv user configuration 957 intended for CLI playback. 958 959 Using ``--input-ipc-server`` is also suitable for purposes like remote 960 control (however, the IPC protocol itself is not "secure" and not 961 intended to be so). 962 963 2. Using libmpv. This is generally recommended when mpv is used as playback 964 backend for a completely different application. The provided C API is 965 very close to CLI mechanisms and the scripting API. 966 967 Note that even though libmpv has different defaults, it can be configured 968 to work exactly like the CLI player (except command line parsing is 969 unavailable). 970 971 See `EMBEDDING INTO OTHER PROGRAMS (LIBMPV)`_. 972 973 3. As a user script (`LUA SCRIPTING`_, `JAVASCRIPT`_, `C PLUGINS`_). This is 974 recommended when the goal is to "enhance" the CLI player. Scripts get 975 access to the entire client API of mpv. 976 977 This is the standard way to create third-party extensions for the player. 978 979All these access the client API, which is the sum of the various mechanisms 980provided by the player core, as documented here: `OPTIONS`_, 981`List of Input Commands`_, `Properties`_, `List of events`_ (also see C API), 982`Hooks`_. 983 984TAKING SCREENSHOTS 985================== 986 987Screenshots of the currently played file can be taken using the 'screenshot' 988input mode command, which is by default bound to the ``s`` key. Files named 989``mpv-shotNNNN.jpg`` will be saved in the working directory, using the first 990available number - no files will be overwritten. In pseudo-GUI mode, the 991screenshot will be saved somewhere else. See `PSEUDO GUI MODE`_. 992 993A screenshot will usually contain the unscaled video contents at the end of the 994video filter chain and subtitles. By default, ``S`` takes screenshots without 995subtitles, while ``s`` includes subtitles. 996 997Unlike with MPlayer, the ``screenshot`` video filter is not required. This 998filter was never required in mpv, and has been removed. 999 1000TERMINAL STATUS LINE 1001==================== 1002 1003During playback, mpv shows the playback status on the terminal. It looks like 1004something like this: 1005 1006 ``AV: 00:03:12 / 00:24:25 (13%) A-V: -0.000`` 1007 1008The status line can be overridden with the ``--term-status-msg`` option. 1009 1010The following is a list of things that can show up in the status line. Input 1011properties, that can be used to get the same information manually, are also 1012listed. 1013 1014- ``AV:`` or ``V:`` (video only) or ``A:`` (audio only) 1015- The current time position in ``HH:MM:SS`` format (``playback-time`` property) 1016- The total file duration (absent if unknown) (``duration`` property) 1017- Playback speed, e.g. ``x2.0``. Only visible if the speed is not normal. This 1018 is the user-requested speed, and not the actual speed (usually they should 1019 be the same, unless playback is too slow). (``speed`` property.) 1020- Playback percentage, e.g. ``(13%)``. How much of the file has been played. 1021 Normally calculated out of playback position and duration, but can fallback 1022 to other methods (like byte position) if these are not available. 1023 (``percent-pos`` property.) 1024- The audio/video sync as ``A-V: 0.000``. This is the difference between 1025 audio and video time. Normally it should be 0 or close to 0. If it's growing, 1026 it might indicate a playback problem. (``avsync`` property.) 1027- Total A/V sync change, e.g. ``ct: -0.417``. Normally invisible. Can show up 1028 if there is audio "missing", or not enough frames can be dropped. Usually 1029 this will indicate a problem. (``total-avsync-change`` property.) 1030- Encoding state in ``{...}``, only shown in encoding mode. 1031- Display sync state. If display sync is active (``display-sync-active`` 1032 property), this shows ``DS: 2.500/13``, where the first number is average 1033 number of vsyncs per video frame (e.g. 2.5 when playing 24Hz videos on 60Hz 1034 screens), which might jitter if the ratio doesn't round off, or there are 1035 mistimed frames (``vsync-ratio``), and the second number of estimated number 1036 of vsyncs which took too long (``vo-delayed-frame-count`` property). The 1037 latter is a heuristic, as it's generally not possible to determine this with 1038 certainty. 1039- Dropped frames, e.g. ``Dropped: 4``. Shows up only if the count is not 0. Can 1040 grow if the video framerate is higher than that of the display, or if video 1041 rendering is too slow. May also be incremented on "hiccups" and when the video 1042 frame couldn't be displayed on time. (``frame-drop-count`` property.) 1043 If the decoder drops frames, the number of decoder-dropped frames is appended 1044 to the display as well, e.g.: ``Dropped: 4/34``. This happens only if 1045 decoder frame dropping is enabled with the ``--framedrop`` options. 1046 (``decoder-frame-drop-count`` property.) 1047- Cache state, e.g. ``Cache: 2s/134KB``. Visible if the stream cache is enabled. 1048 The first value shows the amount of video buffered in the demuxer in seconds, 1049 the second value shows the estimated size of the buffered amount in kilobytes. 1050 (``demuxer-cache-duration`` and ``demuxer-cache-state`` properties.) 1051 1052 1053LOW LATENCY PLAYBACK 1054==================== 1055 1056mpv is optimized for normal video playback, meaning it actually tries to buffer 1057as much data as it seems to make sense. This will increase latency. Reducing 1058latency is possible only by specifically disabling features which increase 1059latency. 1060 1061The builtin ``low-latency`` profile tries to apply some of the options which can 1062reduce latency. You can use ``--profile=low-latency`` to apply all of them. You 1063can list the contents with ``--show-profile=low-latency`` (some of the options 1064are quite obscure, and may change every mpv release). 1065 1066Be aware that some of the options can reduce playback quality. 1067 1068Most latency is actually caused by inconvenient timing behavior. You can disable 1069this with ``--untimed``, but it will likely break, unless the stream has no 1070audio, and the input feeds data to the player at a constant rate. 1071 1072Another common problem is with MJPEG streams. These do not signal the correct 1073framerate. Using ``--untimed`` or ``--no-correct-pts --fps=60`` might help. 1074 1075For livestreams, data can build up due to pausing the stream, due to slightly 1076lower playback rate, or "buffering" pauses. If the demuxer cache is enabled, 1077these can be skipped manually. The experimental ``drop-buffers`` command can 1078be used to discard any buffered data, though it's very disruptive. 1079 1080In some cases, manually tuning TCP buffer sizes and such can help to reduce 1081latency. 1082 1083Additional options that can be tried: 1084 1085- ``--opengl-glfinish=yes``, can reduce buffering in the graphics driver 1086- ``--opengl-swapinterval=0``, same 1087- ``--vo=xv``, same 1088- without audio ``--framedrop=no --speed=1.01`` may help for live sources 1089 (results can be mixed) 1090 1091 1092PROTOCOLS 1093========= 1094 1095``http://...``, ``https://``, ... 1096 1097 Many network protocols are supported, but the protocol prefix must always 1098 be specified. mpv will never attempt to guess whether a filename is 1099 actually a network address. A protocol prefix is always required. 1100 1101 Note that not all prefixes are documented here. Undocumented prefixes are 1102 either aliases to documented protocols, or are just redirections to 1103 protocols implemented and documented in FFmpeg. 1104 1105 ``data:`` is supported in FFmpeg (not in Libav), but needs to be in the 1106 format ``data://``. This is done to avoid ambiguity with filenames. You 1107 can also prefix it with ``lavf://`` or ``ffmpeg://``. 1108 1109``ytdl://...`` 1110 1111 By default, the youtube-dl hook script only looks at http(s) URLs. Prefixing 1112 an URL with ``ytdl://`` forces it to be always processed by the script. This 1113 can also be used to invoke special youtube-dl functionality like playing a 1114 video by ID or invoking search. 1115 1116 Keep in mind that you can't pass youtube-dl command line options by this, 1117 and you have to use ``--ytdl-raw-options`` instead. 1118 1119``-`` 1120 1121 Play data from stdin. 1122 1123``smb://PATH`` 1124 1125 Play a path from Samba share. (Requires FFmpeg support.) 1126 1127``bd://[title][/device]`` ``--bluray-device=PATH`` 1128 1129 Play a Blu-ray disc. Since libbluray 1.0.1, you can read from ISO files 1130 by passing them to ``--bluray-device``. 1131 1132 ``title`` can be: ``longest`` or ``first`` (selects the default 1133 playlist); ``mpls/<number>`` (selects <number>.mpls playlist); 1134 ``<number>`` (select playlist with the same index). mpv will list 1135 the available playlists on loading. 1136 1137 ``bluray://`` is an alias. 1138 1139``dvd://[title][/device]`` ``--dvd-device=PATH`` 1140 1141 Play a DVD. DVD menus are not supported. If no title is given, the longest 1142 title is auto-selected. Without ``--dvd-device``, it will probably try 1143 to open an actual optical drive, if available and implemented for the OS. 1144 1145 ``dvdnav://`` is an old alias for ``dvd://`` and does exactly the same 1146 thing. 1147 1148``dvb://[cardnumber@]channel`` ``--dvbin-...`` 1149 1150 Digital TV via DVB. (Linux only.) 1151 1152``mf://[filemask|@listfile]`` ``--mf-...`` 1153 1154 Play a series of images as video. 1155 1156``cdda://[device]`` ``--cdrom-device=PATH`` ``--cdda-...`` 1157 1158 Play CD. 1159 1160``lavf://...`` 1161 1162 Access any FFmpeg/Libav libavformat protocol. Basically, this passed the 1163 string after the ``//`` directly to libavformat. 1164 1165``av://type:options`` 1166 1167 This is intended for using libavdevice inputs. ``type`` is the libavdevice 1168 demuxer name, and ``options`` is the (pseudo-)filename passed to the 1169 demuxer. 1170 1171 .. admonition:: Example 1172 1173 :: 1174 1175 mpv av://v4l2:/dev/video0 --profile=low-latency --untimed 1176 1177 This plays video from the first v4l input with nearly the lowest latency 1178 possible. It's a good replacement for the removed ``tv://`` input. 1179 Using ``--untimed`` is a hack to output a captured frame immediately, 1180 instead of respecting the input framerate. (There may be better ways to 1181 handle this in the future.) 1182 1183 ``avdevice://`` is an alias. 1184 1185``file://PATH`` 1186 1187 A local path as URL. Might be useful in some special use-cases. Note that 1188 ``PATH`` itself should start with a third ``/`` to make the path an 1189 absolute path. 1190 1191``appending://PATH`` 1192 1193 Play a local file, but assume it's being appended to. This is useful for 1194 example for files that are currently being downloaded to disk. This will 1195 block playback, and stop playback only if no new data was appended after 1196 a timeout of about 2 seconds. 1197 1198 Using this is still a bit of a bad idea, because there is no way to detect 1199 if a file is actually being appended, or if it's still written. If you're 1200 trying to play the output of some program, consider using a pipe 1201 (``something | mpv -``). If it really has to be a file on disk, use tail to 1202 make it wait forever, e.g. ``tail -f -c +0 file.mkv | mpv -``. 1203 1204``fd://123`` 1205 1206 Read data from the given file descriptor (for example 123). This is similar 1207 to piping data to stdin via ``-``, but can use an arbitrary file descriptor. 1208 mpv may modify some file descriptor properties when the stream layer "opens" 1209 it. 1210 1211``fdclose://123`` 1212 1213 Like ``fd://``, but the file descriptor is closed after use. When using this 1214 you need to ensure that the same fd URL will only be used once. 1215 1216``edl://[edl specification as in edl-mpv.rst]`` 1217 1218 Stitch together parts of multiple files and play them. 1219 1220``slice://start[-end]@URL`` 1221 1222 Read a slice of a stream. 1223 1224 ``start`` and ``end`` represent a byte range and accept 1225 suffixes such as ``KiB`` and ``MiB``. ``end`` is optional. 1226 1227 if ``end`` starts with ``+``, it is considered as offset from ``start``. 1228 1229 Only works with seekable streams. 1230 1231 Examples:: 1232 1233 mpv slice://1g-2g@cap.ts 1234 1235 This starts reading from cap.ts after seeking 1 GiB, then 1236 reads until reaching 2 GiB or end of file. 1237 1238 mpv slice://1g-+2g@cap.ts 1239 1240 This starts reading from cap.ts after seeking 1 GiB, then 1241 reads until reaching 3 GiB or end of file. 1242 1243 mpv slice://100m@appending://cap.ts 1244 1245 This starts reading from cap.ts after seeking 100MiB, then 1246 reads until end of file. 1247 1248``null://`` 1249 1250 Simulate an empty file. If opened for writing, it will discard all data. 1251 The ``null`` demuxer will specifically pass autoprobing if this protocol 1252 is used (while it's not automatically invoked for empty files). 1253 1254``memory://data`` 1255 1256 Use the ``data`` part as source data. 1257 1258``hex://data`` 1259 1260 Like ``memory://``, but the string is interpreted as hexdump. 1261 1262PSEUDO GUI MODE 1263=============== 1264 1265mpv has no official GUI, other than the OSC (`ON SCREEN CONTROLLER`_), which 1266is not a full GUI and is not meant to be. However, to compensate for the lack 1267of expected GUI behavior, mpv will in some cases start with some settings 1268changed to behave slightly more like a GUI mode. 1269 1270Currently this happens only in the following cases: 1271 1272- if started using the ``mpv.desktop`` file on Linux (e.g. started from menus 1273 or file associations provided by desktop environments) 1274- if started from explorer.exe on Windows (technically, if it was started on 1275 Windows, and all of the stdout/stderr/stdin handles are unset) 1276- started out of the bundle on macOS 1277- if you manually use ``--player-operation-mode=pseudo-gui`` on the command line 1278 1279This mode applies options from the builtin profile ``builtin-pseudo-gui``, but 1280only if these haven't been set in the user's config file or on the command line, 1281which is the main difference to using ``--profile=builtin-pseudo-gui``. 1282 1283The profile is currently defined as follows: 1284 1285:: 1286 1287 [builtin-pseudo-gui] 1288 terminal=no 1289 force-window=yes 1290 idle=once 1291 screenshot-directory=~~desktop/ 1292 1293The ``pseudo-gui`` profile exists for compatibility. The options in the 1294``pseudo-gui`` profile are applied unconditionally. In addition, the profile 1295makes sure to enable the pseudo-GUI mode, so that ``--profile=pseudo-gui`` 1296works like in older mpv releases: 1297 1298:: 1299 1300 [pseudo-gui] 1301 player-operation-mode=pseudo-gui 1302 1303.. warning:: 1304 1305 Currently, you can extend the ``pseudo-gui`` profile in the config file the 1306 normal way. This is deprecated. In future mpv releases, the behavior might 1307 change, and not apply your additional settings, and/or use a different 1308 profile name. 1309 1310Linux desktop issues 1311==================== 1312 1313This subsection describes common problems on the Linux desktop. None of these 1314problems exist on systems like Windows or macOS. 1315 1316Disabling Screensaver 1317--------------------- 1318 1319By default, mpv tries to disable the OS screensaver during playback (only if 1320a VO using the OS GUI API is active). ``--stop-screensaver=no`` disables this. 1321 1322A common problem is that Linux desktop environments ignore the standard 1323screensaver APIs on which mpv relies. In particular, mpv uses the Screen Saver 1324extension (XSS) on X11, and the idle-inhibit on Wayland. 1325 1326GNOME is one of the worst offenders, and ignores even the now widely supported 1327idle-inhibit protocol. (This is either due to a combination of malice and 1328incompetence, but since implementing this protocol would only take a few lines 1329of code, it is most likely the former. You will also notice how GNOME advocates 1330react offended whenever their sabotage is pointed out, which indicates either 1331hypocrisy, or even worse ignorance.) 1332 1333Such incompatible desktop environments (i.e. which ignore standards) typically 1334require using a DBus API. This is ridiculous in several ways. The immediate 1335practical problem is that it would require adding a quite unwieldy dependency 1336for a DBus library, somehow integrating its mainloop into mpv, and other 1337generally unacceptable things. 1338 1339However, since mpv does not officially support GNOME, this is not much of a 1340problem. If you are one of those miserable users who want to use mpv on GNOME, 1341report a bug on the GNOME issue tracker: 1342https://gitlab.gnome.org/groups/GNOME/-/issues 1343 1344Alternatively, you may be able to write a Lua script that calls the 1345``xdg-screensaver`` command line program. (By the way, this a command line 1346program is an utterly horrible kludge that tries to identify your DE, and then 1347tries to send the correct DBus command via a DBus CLI tool.) If you find the 1348idea of having to write a script just so your screensaver doesn't kick in 1349ridiculous, do not use GNOME, or use GNOME video software instead of mpv (good 1350luck). 1351 1352Before mpv 0.33.0, the X11 backend ran ``xdg-screensaver reset`` in 10 second 1353intervals when not paused. This hack was removed in 0.33.0. 1354 1355.. include:: options.rst 1356 1357.. include:: ao.rst 1358 1359.. include:: vo.rst 1360 1361.. include:: af.rst 1362 1363.. include:: vf.rst 1364 1365.. include:: encode.rst 1366 1367.. include:: input.rst 1368 1369.. include:: osc.rst 1370 1371.. include:: stats.rst 1372 1373.. include:: console.rst 1374 1375.. include:: lua.rst 1376 1377.. include:: javascript.rst 1378 1379.. include:: ipc.rst 1380 1381.. include:: changes.rst 1382 1383.. include:: libmpv.rst 1384 1385ENVIRONMENT VARIABLES 1386===================== 1387 1388There are a number of environment variables that can be used to control the 1389behavior of mpv. 1390 1391``HOME``, ``XDG_CONFIG_HOME`` 1392 Used to determine mpv config directory. If ``XDG_CONFIG_HOME`` is not set, 1393 ``$HOME/.config/mpv`` is used. 1394 1395 ``$HOME/.mpv`` is always added to the list of config search paths with a 1396 lower priority. 1397 1398``MPV_HOME`` 1399 Directory where mpv looks for user settings. Overrides ``HOME``, and mpv 1400 will try to load the config file as ``$MPV_HOME/mpv.conf``. 1401 1402``MPV_VERBOSE`` (see also ``-v`` and ``--msg-level``) 1403 Set the initial verbosity level across all message modules (default: 0). 1404 This is an integer, and the resulting verbosity corresponds to the number 1405 of ``--v`` options passed to the command line. 1406 1407``MPV_LEAK_REPORT`` 1408 If set to ``1``, enable internal talloc leak reporting. If set to another 1409 value, disable leak reporting. If unset, use the default, which normally is 1410 ``0``. If mpv was built with ``--enable-ta-leak-report``, the default is 1411 ``1``. If leak reporting was disabled at compile time (``NDEBUG`` in 1412 custom ``CFLAGS``), this environment variable is ignored. 1413 1414``LADSPA_PATH`` 1415 Specifies the search path for LADSPA plugins. If it is unset, fully 1416 qualified path names must be used. 1417 1418``DISPLAY`` 1419 Standard X11 display name to use. 1420 1421FFmpeg/Libav: 1422 This library accesses various environment variables. However, they are not 1423 centrally documented, and documenting them is not our job. Therefore, this 1424 list is incomplete. 1425 1426 Notable environment variables: 1427 1428 ``http_proxy`` 1429 URL to proxy for ``http://`` and ``https://`` URLs. 1430 1431 ``no_proxy`` 1432 List of domain patterns for which no proxy should be used. 1433 List entries are separated by ``,``. Patterns can include ``*``. 1434 1435libdvdcss: 1436 ``DVDCSS_CACHE`` 1437 Specify a directory in which to store title key values. This will 1438 speed up descrambling of DVDs which are in the cache. The 1439 ``DVDCSS_CACHE`` directory is created if it does not exist, and a 1440 subdirectory is created named after the DVD's title or manufacturing 1441 date. If ``DVDCSS_CACHE`` is not set or is empty, libdvdcss will use 1442 the default value which is ``${HOME}/.dvdcss/`` under Unix and 1443 the roaming application data directory (``%APPDATA%``) under 1444 Windows. The special value "off" disables caching. 1445 1446 ``DVDCSS_METHOD`` 1447 Sets the authentication and decryption method that libdvdcss will use 1448 to read scrambled discs. Can be one of ``title``, ``key`` or ``disc``. 1449 1450 key 1451 is the default method. libdvdcss will use a set of calculated 1452 player keys to try to get the disc key. This can fail if the drive 1453 does not recognize any of the player keys. 1454 1455 disc 1456 is a fallback method when key has failed. Instead of using player 1457 keys, libdvdcss will crack the disc key using a brute force 1458 algorithm. This process is CPU intensive and requires 64 MB of 1459 memory to store temporary data. 1460 1461 title 1462 is the fallback when all other methods have failed. It does not 1463 rely on a key exchange with the DVD drive, but rather uses a crypto 1464 attack to guess the title key. On rare cases this may fail because 1465 there is not enough encrypted data on the disc to perform a 1466 statistical attack, but on the other hand it is the only way to 1467 decrypt a DVD stored on a hard disc, or a DVD with the wrong region 1468 on an RPC2 drive. 1469 1470 ``DVDCSS_RAW_DEVICE`` 1471 Specify the raw device to use. Exact usage will depend on your 1472 operating system, the Linux utility to set up raw devices is raw(8) 1473 for instance. Please note that on most operating systems, using a raw 1474 device requires highly aligned buffers: Linux requires a 2048 bytes 1475 alignment (which is the size of a DVD sector). 1476 1477 ``DVDCSS_VERBOSE`` 1478 Sets the libdvdcss verbosity level. 1479 1480 :0: Outputs no messages at all. 1481 :1: Outputs error messages to stderr. 1482 :2: Outputs error messages and debug messages to stderr. 1483 1484 ``DVDREAD_NOKEYS`` 1485 Skip retrieving all keys on startup. Currently disabled. 1486 1487 ``HOME`` 1488 FIXME: Document this. 1489 1490 1491EXIT CODES 1492========== 1493 1494Normally **mpv** returns 0 as exit code after finishing playback successfully. 1495If errors happen, the following exit codes can be returned: 1496 1497 :1: Error initializing mpv. This is also returned if unknown options are 1498 passed to mpv. 1499 :2: The file passed to mpv couldn't be played. This is somewhat fuzzy: 1500 currently, playback of a file is considered to be successful if 1501 initialization was mostly successful, even if playback fails 1502 immediately after initialization. 1503 :3: There were some files that could be played, and some files which 1504 couldn't (using the definition of success from above). 1505 :4: Quit due to a signal, Ctrl+c in a VO window (by default), or from the 1506 default quit key bindings in encoding mode. 1507 1508Note that quitting the player manually will always lead to exit code 0, 1509overriding the exit code that would be returned normally. Also, the ``quit`` 1510input command can take an exit code: in this case, that exit code is returned. 1511 1512FILES 1513===== 1514 1515For Windows-specifics, see `FILES ON WINDOWS`_ section. 1516 1517``/usr/local/etc/mpv/mpv.conf`` 1518 mpv system-wide settings (depends on ``--prefix`` passed to configure - mpv 1519 in default configuration will use ``/usr/local/etc/mpv/`` as config 1520 directory, while most Linux distributions will set it to ``/etc/mpv/``). 1521 1522``~/.config/mpv`` 1523 The standard configuration directory. This can be overridden by environment 1524 variables, in ascending order: 1525 1526 :1: If ``$XDG_CONFIG_HOME`` is set, then the derived configuration directory 1527 will be ``$XDG_CONFIG_HOME/mpv``. 1528 :2: If ``$MPV_HOME`` is set, then the derived configuration directory will be 1529 ``$MPV_HOME``. 1530 1531 If this directory, nor the original configuration directory (see below) do 1532 not exist, mpv tries to create this directory automatically. 1533 1534``~/.mpv/`` 1535 The original (pre 0.5.0) configuration directory. It will continue to be 1536 read if present. 1537 1538 If both this directory and the standard configuration directory are 1539 present, configuration will be read from both with the standard 1540 configuration directory content taking precedence. However, you should 1541 fully migrate to the standard directory and a warning will be shown in 1542 this situation. 1543 1544``~/.config/mpv/mpv.conf`` 1545 mpv user settings (see `CONFIGURATION FILES`_ section) 1546 1547``~/.config/mpv/input.conf`` 1548 key bindings (see `INPUT.CONF`_ section) 1549 1550``~/.config/mpv/fonts.conf`` 1551 Fontconfig fonts.conf that is customized for mpv. You should include system 1552 fonts.conf in this file or mpv would not know about fonts that you already 1553 have in the system. 1554 1555 Only available when libass is built with fontconfig. 1556 1557``~/.config/mpv/subfont.ttf`` 1558 fallback subtitle font 1559 1560``~/.config/mpv/fonts/`` 1561 Font files in this directory are used by mpv/libass for subtitles. Useful 1562 if you do not want to install fonts to your system. Note that files in this 1563 directory are loaded into memory before being used by mpv. If you have a 1564 lot of fonts, consider using fonts.conf (see above) to include additional 1565 fonts, which is more memory-efficient. 1566 1567``~/.config/mpv/scripts/`` 1568 All files in this directory are loaded as if they were passed to the 1569 ``--script`` option. They are loaded in alphabetical order. 1570 1571 The ``--load-scripts=no`` option disables loading these files. 1572 1573 See `Script location`_ for details. 1574 1575``~/.config/mpv/watch_later/`` 1576 Contains temporary config files needed for resuming playback of files with 1577 the watch later feature. See for example the ``Q`` key binding, or the 1578 ``quit-watch-later`` input command. 1579 1580 Each file is a small config file which is loaded if the corresponding media 1581 file is loaded. It contains the playback position and some (not necessarily 1582 all) settings that were changed during playback. The filenames are hashed 1583 from the full paths of the media files. It's in general not possible to 1584 extract the media filename from this hash. However, you can set the 1585 ``--write-filename-in-watch-later-config`` option, and the player will 1586 add the media filename to the contents of the resume config file. 1587 1588``~/.config/mpv/script-opts/osc.conf`` 1589 This is loaded by the OSC script. See the `ON SCREEN CONTROLLER`_ docs 1590 for details. 1591 1592 Other files in this directory are specific to the corresponding scripts 1593 as well, and the mpv core doesn't touch them. 1594 1595FILES ON WINDOWS 1596================ 1597 1598On win32 (if compiled with MinGW, but not Cygwin), the default config file 1599locations are different. They are generally located under ``%APPDATA%/mpv/``. 1600For example, the path to mpv.conf is ``%APPDATA%/mpv/mpv.conf``, which maps to 1601a system and user-specific path, for example 1602 1603 ``C:\users\USERNAME\AppData\Roaming\mpv\mpv.conf`` 1604 1605You can find the exact path by running ``echo %APPDATA%\mpv\mpv.conf`` in cmd.exe. 1606 1607Other config files (such as ``input.conf``) are in the same directory. See the 1608`FILES`_ section above. 1609 1610The environment variable ``$MPV_HOME`` completely overrides these, like on 1611UNIX. 1612 1613If a directory named ``portable_config`` next to the mpv.exe exists, all 1614config will be loaded from this directory only. Watch later config files are 1615written to this directory as well. (This exists on Windows only and is redundant 1616with ``$MPV_HOME``. However, since Windows is very scripting unfriendly, a 1617wrapper script just setting ``$MPV_HOME``, like you could do it on other 1618systems, won't work. ``portable_config`` is provided for convenience to get 1619around this restriction.) 1620 1621Config files located in the same directory as ``mpv.exe`` are loaded with 1622lower priority. Some config files are loaded only once, which means that 1623e.g. of 2 ``input.conf`` files located in two config directories, only the 1624one from the directory with higher priority will be loaded. 1625 1626A third config directory with the lowest priority is the directory named ``mpv`` 1627in the same directory as ``mpv.exe``. This used to be the directory with the 1628highest priority, but is now discouraged to use and might be removed in the 1629future. 1630 1631Note that mpv likes to mix ``/`` and ``\`` path separators for simplicity. 1632kernel32.dll accepts this, but cmd.exe does not. 1633