1MPV(1) multimedia MPV(1)
2
6 mpv - a media player
7
9 mpv [options] [file|URL|PLAYLIST|-]
10 mpv [options] files
11
14 mpv is a media player based on MPlayer and mplayer2. It supports a wide
15 variety of video file formats, audio and video codecs, and subtitle
16 types. Special input URL types are available to read input from a vari‐
17 ety of sources other than disk files. Depending on platform, a variety
18 of different video and audio output methods are supported.
19 Usage examples to get you started quickly can be found at the end of
21 this man page.
22
24 mpv has a fully configurable, command-driven control layer which allows
25 you to control mpv using keyboard, mouse, or remote control (there is
26 no LIRC support - configure remotes as input devices instead).
27 See the --input- options for ways to customize it.
29 The following listings are not necessarily complete. See etc/input.conf
31 in the mpv source files for a list of default bindings. User input.conf
32 files and Lua scripts can define additional key bindings.
33 See COMMAND INTERFACE and Key names sections for more details on con‐
35 figuring keybindings.
36 See also --input-test for interactive binding details by key, and the
38 stats built-in script for key bindings list (including print to termi‐
39 nal).
40 Keyboard Control
42 LEFT and RIGHT
43 Seek backward/forward 5 seconds. Shift+arrow does a 1 second ex‐
44 act seek (see --hr-seek).
45 UP and DOWN
47 Seek forward/backward 1 minute. Shift+arrow does a 5 second ex‐
48 act seek (see --hr-seek).
49 Ctrl+LEFT and Ctrl+RIGHT
51 Seek to the previous/next subtitle. Subject to some restrictions
52 and might not always work; see sub-seek command.
53 Ctrl+Shift+Left and Ctrl+Shift+Right
55 Adjust subtitle delay so that the next or previous subtitle is
56 displayed now. This is especially useful to sync subtitles to
57 audio.
58 [ and ]
60 Decrease/increase current playback speed by 10%.
61 { and }
63 Halve/double current playback speed.
64 BACKSPACE
66 Reset playback speed to normal.
67 Shift+BACKSPACE
69 Undo the last seek. This works only if the playlist entry was
70 not changed. Hitting it a second time will go back to the orig‐
71 inal position. See revert-seek command for details.
72 Shift+Ctrl+BACKSPACE
74 Mark the current position. This will then be used by
75 Shift+BACKSPACE as revert position (once you seek back, the
76 marker will be reset). You can use this to seek around in the
77 file and then return to the exact position where you left off.
78 < and >
80 Go backward/forward in the playlist.
81 ENTER Go forward in the playlist.
83 p / SPACE
85 Pause (pressing again unpauses).
86 . Step forward. Pressing once will pause, every consecutive press
88 will play one frame and then go into pause mode again.
89 , Step backward. Pressing once will pause, every consecutive press
91 will play one frame in reverse and then go into pause mode
92 again.
93 q Stop playing and quit.
95 Q Like q, but store the current playback position. Playing the
97 same file later will resume at the old playback position if pos‐
98 sible. See RESUMING PLAYBACK.
99 / and *
101 Decrease/increase volume.
102 9 and 0
104 Decrease/increase volume.
105 m Mute sound.
107 _ Cycle through the available video tracks.
109 # Cycle through the available audio tracks.
111 E Cycle through the available Editions.
113 f Toggle fullscreen (see also --fs).
115 ESC Exit fullscreen mode.
117 T Toggle stay-on-top (see also --ontop).
119 w and W
121 Decrease/increase pan-and-scan range. The e key does the same as
122 W currently, but use is discouraged.
123 o (also P)
125 Show progression bar, elapsed time and total duration on the
126 OSD.
127 O Toggle OSD states between normal and playback time/duration.
129 v Toggle subtitle visibility.
131 j and J
133 Cycle through the available subtitles.
134 z and Z
136 Adjust subtitle delay by +/- 0.1 seconds. The x key does the
137 same as Z currently, but use is discouraged.
138 l Set/clear A-B loop points. See ab-loop command for details.
140 L Toggle infinite looping.
142 Ctrl + and Ctrl -
144 Adjust audio delay (A/V sync) by +/- 0.1 seconds.
145 Shift+g and Shift+f
147 Adjust subtitle font size by +/- 10%.
148 u Switch between applying no style overrides to SSA/ASS subtitles,
150 and overriding them almost completely with the normal subtitle
151 style. See --sub-ass-override for more info.
152 V Toggle subtitle VSFilter aspect compatibility mode. See
154 --sub-ass-vsfilter-aspect-compat for more info.
155 r and R
157 Move subtitles up/down. The t key does the same as R currently,
158 but use is discouraged.
159 s Take a screenshot.
161 S Take a screenshot, without subtitles. (Whether this works de‐
163 pends on VO driver support.)
164 Ctrl s Take a screenshot, as the window shows it (with subtitles, OSD,
166 and scaled video).
167 PGUP and PGDWN
169 Seek to the beginning of the previous/next chapter. In most
170 cases, "previous" will actually go to the beginning of the cur‐
171 rent chapter; see --chapter-seek-threshold.
172 Shift+PGUP and Shift+PGDWN
174 Seek backward or forward by 10 minutes. (This used to be mapped
175 to PGUP/PGDWN without Shift.)
176 d Activate/deactivate deinterlacer.
178 A Cycle aspect ratio override.
180 Ctrl h Toggle hardware video decoding on/off.
182 Alt+LEFT, Alt+RIGHT, Alt+UP, Alt+DOWN
184 Move the video rectangle (panning).
185 Alt + and Alt -
187 Combining Alt with the + or - keys changes video zoom.
188 Alt+BACKSPACE
190 Reset the pan/zoom settings.
191 F8 Show the playlist and the current position in it (useful only if
193 a UI window is used, broken on the terminal).
194 F9 Show the list of audio and subtitle streams (useful only if a UI
196 window is used, broken on the terminal).
197 i and I
199 Show/toggle an overlay displaying statistics about the currently
200 playing file such as codec, framerate, number of dropped frames
201 and so on. See STATS for more information.
202 del Cycle OSC visibility between never / auto (mouse-move) / always
204 ` Show the console. (ESC closes it again. See CONSOLE.)
206 (The following keys are valid only when using a video output that sup‐
208 ports the corresponding adjustment.)
209 1 and 2
211 Adjust contrast.
212 3 and 4
214 Adjust brightness.
215 5 and 6
217 Adjust gamma.
218 7 and 8
220 Adjust saturation.
221 Alt+0 (and command+0 on macOS)
223 Resize video window to half its original size.
224 Alt+1 (and command+1 on macOS)
226 Resize video window to its original size.
227 Alt+2 (and command+2 on macOS)
229 Resize video window to double its original size.
230 command + f (macOS only)
232 Toggle fullscreen (see also --fs).
233 (The following keys are valid if you have a keyboard with multimedia
235 keys.)
236 PAUSE Pause.
238 STOP Stop playing and quit.
240 PREVIOUS and NEXT
242 Seek backward/forward 1 minute.
243 If you miss some older key bindings, look at etc/restore-old-bind‐
245 ings.conf in the mpv git repository.
246 Mouse Control
248 Left double click
249 Toggle fullscreen on/off.
250 Right click
252 Toggle pause on/off.
253 Forward/Back button
255 Skip to next/previous entry in playlist.
256 Wheel up/down
258 Seek forward/backward 10 seconds.
259 Wheel left/right
261 Decrease/increase volume.
262
264 Command line arguments starting with - are interpreted as options, ev‐
265 erything else as filenames or URLs. All options except flag options (or
266 choice options which include yes) require a parameter in the form --op‐
267 tion=value.
268 One exception is the lone - (without anything else), which means media
270 data will be read from stdin. Also, -- (without anything else) will
271 make the player interpret all following arguments as filenames, even if
272 they start with -. (To play a file named -, you need to use ./-.)
273 Every flag option has a no-flag counterpart, e.g. the opposite of the
275 --fs option is --no-fs. --fs=yes is same as --fs, --fs=no is the same
276 as --no-fs.
277 If an option is marked as (XXX only), it will only work in combination
279 with the XXX option or if XXX is compiled in.
280 Legacy option syntax
282 The --option=value syntax is not strictly enforced, and the alternative
283 legacy syntax -option value and -option=value will also work. This is
284 mostly for compatibility with MPlayer. Using these should be avoided.
285 Their semantics can change any time in the future.
286 For example, the alternative syntax will consider an argument following
288 the option a filename. mpv -fs no will attempt to play a file named no,
289 because --fs is a flag option that requires no parameter. If an option
290 changes and its parameter becomes optional, then a command line using
291 the alternative syntax will break.
292 Until mpv 0.31.0, there was no difference whether an option started
294 with -- or a single -. Newer mpv releases strictly expect that you pass
295 the option value after a =. For example, before mpv --log-file f.txt
296 would write a log to f.txt, but now this command line fails, as
297 --log-file expects an option value, and f.txt is simply considered a
298 normal file to be played (as in mpv f.txt).
299 The future plan is that -option value will not work anymore, and op‐
301 tions with a single - behave the same as -- options.
302 Escaping spaces and other special characters
304 Keep in mind that the shell will partially parse and mangle the argu‐
305 ments you pass to mpv. For example, you might need to quote or escape
306 options and filenames:
307 mpv "filename with spaces.mkv" --title="window title"
308 It gets more complicated if the suboption parser is involved. The sub‐
310 option parser puts several options into a single string, and passes
311 them to a component at once, instead of using multiple options on the
312 level of the command line.
313 The suboption parser can quote strings with " and [...]. Additionally,
315 there is a special form of quoting with %n% described below.
316 For example, assume the hypothetical foo filter can take multiple op‐
318 tions:
319 mpv test.mkv --vf=foo:option1=value1:option2:option3=value3,bar
320 This passes option1 and option3 to the foo filter, with option2 as flag
322 (implicitly option2=yes), and adds a bar filter after that. If an op‐
323 tion contains spaces or characters like , or :, you need to quote them:
324 mpv '--vf=foo:option1="option value with spaces",bar'
325 Shells may actually strip some quotes from the string passed to the
327 commandline, so the example quotes the string twice, ensuring that mpv
328 receives the " quotes.
329 The [...] form of quotes wraps everything between [ and ]. It's useful
331 with shells that don't interpret these characters in the middle of an
332 argument (like bash). These quotes are balanced (since mpv 0.9.0): the
333 [ and ] nest, and the quote terminates on the last ] that has no match‐
334 ing [ within the string. (For example, [a[b]c] results in a[b]c.)
335 The fixed-length quoting syntax is intended for use with external
337 scripts and programs.
338 It is started with % and has the following format:
340 %n%string_of_length_n
342 Examples
344 mpv '--vf=foo:option1=%11%quoted text' test.avi
346 Or in a script:
348 mpv --vf=foo:option1=%`expr length "$NAME"`%"$NAME" test.avi
350 Note: where applicable with JSON-IPC, %n% is the length in UTF-8 bytes,
352 after decoding the JSON data.
353 Suboptions passed to the client API are also subject to escaping. Using
355 mpv_set_option_string() is exactly like passing --name=data to the com‐
356 mand line (but without shell processing of the string). Some options
357 support passing values in a more structured way instead of flat
358 strings, and can avoid the suboption parsing mess. For example, --vf
359 supports MPV_FORMAT_NODE, which lets you pass suboptions as a nested
360 data structure of maps and arrays.
361 Paths
363 Some care must be taken when passing arbitrary paths and filenames to
364 mpv. For example, paths starting with - will be interpreted as options.
365 Likewise, if a path contains the sequence ://, the string before that
366 might be interpreted as protocol prefix, even though :// can be part of
367 a legal UNIX path. To avoid problems with arbitrary paths, you should
368 be sure that absolute paths passed to mpv start with /, and prefix rel‐
369 ative paths with ./.
370 Using the file:// pseudo-protocol is discouraged, because it involves
372 strange URL unescaping rules.
373 The name - itself is interpreted as stdin, and will cause mpv to dis‐
375 able console controls. (Which makes it suitable for playing data piped
376 to stdin.)
377 The special argument -- can be used to stop mpv from interpreting the
379 following arguments as options.
380 When using the client API, you should strictly avoid using mpv_com‐
382 mand_string for invoking the loadfile command, and instead prefer e.g.
383 mpv_command to avoid the need for filename escaping.
384 For paths passed to suboptions, the situation is further complicated by
386 the need to escape special characters. To work this around, the path
387 can be additionally wrapped in the fixed-length syntax, e.g.
388 %n%string_of_length_n (see above).
389 Some mpv options interpret paths starting with ~. Currently, the pre‐
391 fix ~~home/ expands to the mpv configuration directory (usually ~/.con‐
392 fig/mpv/). ~/ expands to the user's home directory. (The trailing / is
393 always required.) The following paths are currently recognized:
394 ┌─────────────┬────────────────────────────┐
396 │Name │ Meaning │
397 └─────────────┴────────────────────────────┘
398 │~~/ │ If the subpath exists in │
404 │ │ any of the mpv's config │
405 │ │ directories the path of │
406 │ │ the existing file/dir is │
407 │ │ returned. Otherwise this │
408 │ │ is equivalent to ~~home/. │
409 │ │ Note that if --no-config │
410 │ │ is used ~~/foobar will re‐ │
411 │ │ solve to foobar which can │
412 │ │ be unexpected. │
413 ├─────────────┼────────────────────────────┤
414 │~/ │ user home directory root │
415 │ │ (similar to shell, $HOME) │
416 ├─────────────┼────────────────────────────┤
417 │~~home/ │ mpv config dir (for exam‐ │
418 │ │ ple ~/.config/mpv/) │
419 ├─────────────┼────────────────────────────┤
420 │~~global/ │ the global config path, if │
421 │ │ available (not on win32) │
422 ├─────────────┼────────────────────────────┤
423 │~~osxbundle/ │ the macOS bundle resource │
424 │ │ path (macOS only) │
425 ├─────────────┼────────────────────────────┤
426 │~~desktop/ │ the path to the desktop │
427 │ │ (win32, macOS) │
428 ├─────────────┼────────────────────────────┤
429 │~~exe_dir/ │ win32 only: the path to │
430 │ │ the directory containing │
431 │ │ the exe (for config file │
432 │ │ purposes; $MPV_HOME over‐ │
433 │ │ rides it) │
434 ├─────────────┼────────────────────────────┤
435 │~~old_home/ │ do not use │
436 └─────────────┴────────────────────────────┘
437 Per-File Options
439 When playing multiple files, any option given on the command line usu‐
440 ally affects all files. Example:
441 mpv --a file1.mkv --b file2.mkv --c
443 ┌──────────┬────────────────┐
445 │File │ Active options │
446 ├──────────┼────────────────┤
447 │file1.mkv │ --a --b --c │
448 ├──────────┼────────────────┤
449 │file2.mkv │ --a --b --c │
450 └──────────┴────────────────┘
451 (This is different from MPlayer and mplayer2.)
453 Also, if any option is changed at runtime (via input commands), they
455 are not reset when a new file is played.
456 Sometimes, it is useful to change options per-file. This can be
458 achieved by adding the special per-file markers --{ and --}. (Note that
459 you must escape these on some shells.) Example:
460 mpv --a file1.mkv --b --\{ --c file2.mkv --d file3.mkv --e --\} file4.mkv --f
462 ┌──────────┬─────────────────────────┐
464 │File │ Active options │
465 ├──────────┼─────────────────────────┤
466 │file1.mkv │ --a --b --f │
467 └──────────┴─────────────────────────┘
468 │file2.mkv │ --a --b --f --c --d --e │
471 ├──────────┼─────────────────────────┤
472 │file3.mkv │ --a --b --f --c --d --e │
473 ├──────────┼─────────────────────────┤
474 │file4.mkv │ --a --b --f │
475 └──────────┴─────────────────────────┘
476 Additionally, any file-local option changed at runtime is reset when
478 the current file stops playing. If option --c is changed during play‐
479 back of file2.mkv, it is reset when advancing to file3.mkv. This only
480 affects file-local options. The option --a is never reset here.
481 List Options
483 Some options which store lists of option values can have action suf‐
484 fixes. For example, the --display-tags option takes a ,-separated list
485 of tags, but the option also allows you to append a single tag with
486 --display-tags-append, and the tag name can for example contain a lit‐
487 eral , without the need for escaping.
488 String list and path list options
490 String lists are separated by ,. The strings are not parsed or inter‐
491 preted by the option system itself. However, most
492 Path or file list options use : (Unix) or ; (Windows) as separator, in‐
494 stead of ,.
495 They support the following operations:
497 ┌────────┬────────────────────────────┐
499 │Suffix │ Meaning │
500 ├────────┼────────────────────────────┤
501 │-set │ Set a list of items (using │
502 │ │ the list separator, es‐ │
503 │ │ caped with backslash) │
504 ├────────┼────────────────────────────┤
505 │-append │ Append single item (does │
506 │ │ not interpret escapes) │
507 ├────────┼────────────────────────────┤
508 │-add │ Append 1 or more items │
509 │ │ (same syntax as -set) │
510 ├────────┼────────────────────────────┤
511 │-pre │ Prepend 1 or more items │
512 │ │ (same syntax as -set) │
513 ├────────┼────────────────────────────┤
514 │-clr │ Clear the option (remove │
515 │ │ all items) │
516 ├────────┼────────────────────────────┤
517 │-remove │ Delete item if present │
518 │ │ (does not interpret es‐ │
519 │ │ capes) │
520 ├────────┼────────────────────────────┤
521 │-del │ Delete 1 or more items by │
522 │ │ integer index (deprecated) │
523 ├────────┼────────────────────────────┤
524 │-toggle │ Append an item, or remove │
525 │ │ if if it already exists │
526 │ │ (no escapes) │
527 └────────┴────────────────────────────┘
528 -append is meant as a simple way to append a single item without having
530 to escape the argument (you may still need to escape on the shell
531 level).
532 Key/value list options
534 A key/value list is a list of key/value string pairs. In programming
535 languages, this type of data structure is often called a map or a dic‐
536 tionary. The order normally does not matter, although in some cases the
537 order might matter.
538 They support the following operations:
540 ┌────────┬────────────────────────────┐
542 │Suffix │ Meaning │
543 ├────────┼────────────────────────────┤
544 │-set │ Set a list of items (using │
545 │ │ , as separator) │
546 ├────────┼────────────────────────────┤
547 │-append │ Append a single item (es‐ │
548 │ │ capes for the key, no es‐ │
549 │ │ capes for the value) │
550 ├────────┼────────────────────────────┤
551 │-add │ Append 1 or more items │
552 │ │ (same syntax as -set) │
553 ├────────┼────────────────────────────┤
554 │-remove │ Delete item by key if │
555 │ │ present (does not inter‐ │
556 │ │ pret escapes) │
557 └────────┴────────────────────────────┘
558 Keys are unique within the list. If an already present key is set, the
560 existing key is removed before the new value is appended.
561 If you want to pass a value without interpreting it for escapes or ,,
563 it is recommended to use the -add variant. When using libmpv, prefer
564 using MPV_FORMAT_NODE_MAP; when using a scripting backend or the JSON
565 IPC, use an appropriate structured data type.
566 Prior to mpv 0.33, : was also recognized as separator by -set.
568 Filter options
570 This is a very complex option type for the --af and --vf options only.
571 They often require complicated escaping. See VIDEO FILTERS for details.
572 They support the following operations:
573 ┌────────┬────────────────────────────┐
575 │Suffix │ Meaning │
576 ├────────┼────────────────────────────┤
577 │-set │ Set a list of filters (us‐ │
578 │ │ ing , as separator) │
579 ├────────┼────────────────────────────┤
580 │-append │ Append single filter │
581 ├────────┼────────────────────────────┤
582 │-add │ Append 1 or more filters │
583 │ │ (same syntax as -set) │
584 ├────────┼────────────────────────────┤
585 │-pre │ Prepend 1 or more filters │
586 │ │ (same syntax as -set) │
587 ├────────┼────────────────────────────┤
588 │-clr │ Clear the option (remove │
589 │ │ all filters) │
590 ├────────┼────────────────────────────┤
591 │-remove │ Delete filter if present │
592 ├────────┼────────────────────────────┤
593 │-del │ Delete 1 or more filters │
594 │ │ by integer index or filter │
595 │ │ label (deprecated) │
596 ├────────┼────────────────────────────┤
597 │-toggle │ Append a filter, or remove │
598 │ │ if if it already exists │
599 └────────┴────────────────────────────┘
600 │-help │ Pseudo operation that │
605 │ │ prints a help text to the │
606 │ │ terminal │
607 └────────┴────────────────────────────┘
608 General
610 Without suffix, the operation used is normally -set.
611 Although some operations allow specifying multiple items, using this is
613 strongly discouraged and deprecated, except for -set. There is a chance
614 that operations like -add and -pre will work like -append and accept a
615 single, unescaped item only (so the , separator will not be interpreted
616 and is passed on as part of the value).
617 Some options (like --sub-file, --audio-file, --glsl-shader) are aliases
619 for the proper option with -append action. For example, --sub-file is
620 an alias for --sub-files-append.
621 Options of this type can be changed at runtime using the change-list
623 command, which takes the suffix (without the -) as separate operation
624 parameter.
625
627 Location and Syntax
628 You can put all of the options in configuration files which will be
629 read every time mpv is run. The system-wide configuration file
630 'mpv.conf' is in your configuration directory (e.g. /etc/mpv or
631 /usr/local/etc/mpv), the user-specific one is ~/.config/mpv/mpv.conf.
632 For details and platform specifics (in particular Windows paths) see
633 the FILES section.
634 User-specific options override system-wide options and options given on
636 the command line override either. The syntax of the configuration files
637 is option=value. Everything after a # is considered a comment. Options
638 that work without values can be enabled by setting them to yes and dis‐
639 abled by setting them to no. Even suboptions can be specified in this
640 way.
641 Example configuration file
643 # Use GPU-accelerated video output by default.
645 vo=gpu
646 # Use quotes for text that can contain spaces:
647 term-status-msg="Time: ${time-pos}"
648 Escaping spaces and special characters
650 This is done like with command line options. The shell is not involved
651 here, but option values still need to be quoted as a whole if it con‐
652 tains certain characters like spaces. A config entry can be quoted with
653 ", as well as with the fixed-length syntax (%n%) mentioned before. This
654 is like passing the exact contents of the quoted string as command line
655 option. C-style escapes are currently _not_ interpreted on this level,
656 although some options do this manually. (This is a mess and should
657 probably be changed at some point.)
658 Putting Command Line Options into the Configuration File
660 Almost all command line options can be put into the configuration file.
661 Here is a small guide:
662 ┌──────────────────┬──────────────────────────┐
664 │Option │ Configuration file entry │
665 ├──────────────────┼──────────────────────────┤
666 │--flag │ flag │
667 ├──────────────────┼──────────────────────────┤
668 │-opt val │ opt=val │
669 └──────────────────┴──────────────────────────┘
670 │--opt=val │ opt=val │
672 ├──────────────────┼──────────────────────────┤
673 │-opt "has spaces" │ opt="has spaces" │
674 └──────────────────┴──────────────────────────┘
675 File-specific Configuration Files
677 You can also write file-specific configuration files. If you wish to
678 have a configuration file for a file called 'video.avi', create a file
679 named 'video.avi.conf' with the file-specific options in it and put it
680 in ~/.config/mpv/. You can also put the configuration file in the same
681 directory as the file to be played. Both require you to set the
682 --use-filedir-conf option (either on the command line or in your global
683 config file). If a file-specific configuration file is found in the
684 same directory, no file-specific configuration is loaded from ~/.con‐
685 fig/mpv. In addition, the --use-filedir-conf option enables direc‐
686 tory-specific configuration files. For this, mpv first tries to load a
687 mpv.conf from the same directory as the file played and then tries to
688 load any file-specific configuration.
689 Profiles
691 To ease working with different configurations, profiles can be defined
692 in the configuration files. A profile starts with its name in square
693 brackets, e.g. [my-profile]. All following options will be part of the
694 profile. A description (shown by --profile=help) can be defined with
695 the profile-desc option. To end the profile, start another one or use
696 the profile name default to continue with normal options.
697 You can list profiles with --profile=help, and show the contents of a
699 profile with --show-profile=<name> (replace <name> with the profile
700 name). You can apply profiles on start with the --profile=<name> op‐
701 tion, or at runtime with the apply-profile <name> command.
702 Example mpv config file with profiles
704 # normal top-level option
706 fullscreen=yes
707 # a profile that can be enabled with --profile=big-cache
709 [big-cache]
710 cache=yes
711 demuxer-max-bytes=123400KiB
712 demuxer-readahead-secs=20
713 [slow]
715 profile-desc="some profile name"
716 # reference a builtin profile
717 profile=gpu-hq
718 [fast]
720 vo=vdpau
721 # using a profile again extends it
723 [slow]
724 framedrop=no
725 # you can also include other profiles
726 profile=big-cache
727 Runtime profiles
729 Profiles can be set at runtime with apply-profile command. Since this
730 operation is "destructive" (every item in a profile is simply set as an
731 option, overwriting the previous value), you can't just enable and dis‐
732 able profiles again.
733 As a partial remedy, there is a way to make profiles save old option
735 values before overwriting them with the profile values, and then
736 restoring the old values at a later point using apply-profile <pro‐
737 file-name> restore.
738 This can be enabled with the profile-restore option, which takes one of
740 the following options:
741 default
743 Does nothing, and nothing can be restored (default).
744 copy When applying a profile, copy the old values of all profile
746 options to a backup before setting them from the profile.
747 These options are reset to their old values using the backup
748 when restoring.
749 Every profile has its own list of backed up values. If the
751 backup already exists (e.g. if apply-profile name was called
752 more than once in a row), the existing backup is no changed.
753 The restore operation will remove the backup.
754 It's important to know that restoring does not "undo" setting
756 an option, but simply copies the old option value. Consider
757 for example vf-add, appends an entry to vf. This mechanism
758 will simply copy the entire vf list, and does _not_ execute
759 the inverse of vf-add (that would be vf-remove) on restoring.
760 Note that if a profile contains recursive profiles (via the
762 profile option), the options in these recursive profiles are
763 treated as if they were part of this profile. The referenced
764 profile's backup list is not used when creating or using the
765 backup. Restoring a profile does not restore referenced pro‐
766 files, only the options of referenced profiles (as if they
767 were part of the main profile).
768 copy-equal
770 Similar to copy, but restore an option only if it has the
771 same value as the value effectively set by the profile. This
772 tries to deal with the situation when the user does not want
773 the option to be reset after interactively changing it.
774 Example
776 [something]
778 profile-restore=copy-equal
779 vf-add=rotate=PI/2 # rotate by 90 degrees
780 Then running these commands will result in behavior as commented:
782 set vf vflip
784 apply-profile something
785 vf add hflip
786 apply-profile something
787 # vf == vflip,rotate=PI/2,hflip,rotate=PI/2
788 apply-profile something restore
789 # vf == vflip
790 Conditional auto profiles
792 Profiles which have the profile-cond option set are applied automati‐
793 cally if the associated condition matches (unless auto profiles are
794 disabled). The option takes a string, which is interpreted as Lua con‐
795 dition. If evaluating the expression returns true, the profile is ap‐
796 plied, if it returns false, it is ignored. This Lua code execution is
797 not sandboxed.
798 Any variables in condition expressions can reference properties. If an
800 identifier is not already defined by Lua or mpv, it is interpreted as
801 property. For example, pause would return the current pause status.
802 You cannot reference properties with - this way since that would denote
803 a subtraction, but if the variable name contains any _ characters, they
804 are turned into -. For example, playback_time would return the property
805 playback-time.
806 A more robust way to access properties is using p.property_name or
808 get("property-name", default_value). The automatic variable to property
809 magic will break if a new identifier with the same name is introduced
810 (for example, if a function named pause() were added, pause would re‐
811 turn a function value instead of the value of the pause property).
812 Note that if a property is not available, it will return nil, which can
814 cause errors if used in expressions. These are logged in verbose mode,
815 and the expression is considered to be false.
816 Whenever a property referenced by a profile condition changes, the con‐
818 dition is re-evaluated. If the return value of the condition changes
819 from false or error to true, the profile is applied.
820 This mechanism tries to "unapply" profiles once the condition changes
822 from true to false. If you want to use this, you need to set pro‐
823 file-restore for the profile. Another possibility it to create another
824 profile with an inverse condition to undo the other profile.
825 Recursive profiles can be used. But it is discouraged to reference
827 other conditional profiles in a conditional profile, since this can
828 lead to tricky and unintuitive behavior.
829 Example
831 Make only HD video look funny:
833 [something]
835 profile-desc=HD video sucks
836 profile-cond=width >= 1280
837 hue=-50
838 If you want the profile to be reverted if the condition goes to
840 false again, you can set profile-restore:
841 [something]
843 profile-desc=Mess up video when entering fullscreen
844 profile-cond=fullscreen
845 profile-restore=copy
846 vf-add=rotate=PI/2 # rotate by 90 degrees
847 This appends the rotate filter to the video filter chain when enter‐
849 ing fullscreen. When leaving fullscreen, the vf option is set to the
850 value it had before entering fullscreen. Note that this would also
851 remove any other filters that were added during fullscreen mode by
852 the user. Avoiding this is trickier, and could for example be solved
853 by adding a second profile with an inverse condition and operation:
854 [something]
856 profile-cond=fullscreen
857 vf-add=@rot:rotate=PI/2
858 [something-inv]
860 profile-cond=not fullscreen
861 vf-remove=@rot
862 WARNING:
864 Every time an involved property changes, the condition is evaluated
865 again. If your condition uses p.playback_time for example, the con‐
866 dition is re-evaluated approximately on every video frame. This is
867 probably slow.
868 This feature is managed by an internal Lua script. Conditions are exe‐
870 cuted as Lua code within this script. Its environment contains at least
871 the following things:
872 (function environment table)
874 Every Lua function has an environment table. This is used for
875 identifier access. There is no named Lua symbol for it; it is
876 implicit.
877 The environment does "magic" accesses to mpv properties. If an
879 identifier is not already defined in _G, it retrieves the mpv
880 property of the same name. Any occurrences of _ in the name are
881 replaced with - before reading the property. The returned value
882 is as retrieved by mp.get_property_native(name). Internally, a
883 cache of property values, updated by observing the property is
884 used instead, so properties that are not observable will be
885 stuck at the initial value forever.
886 If you want to access properties, that actually contain _ in the
888 name, use get() (which does not perform transliteration).
889 Internally, the environment table has a __index meta method set,
891 which performs the access logic.
892 p A "magic" table similar to the environment table. Unlike the
894 latter, this does not prefer accessing variables defined in _G -
895 it always accesses properties.
896 get(name [, def])
898 Read a property and return its value. If the property value is
899 nil (e.g. if the property does not exist), def is returned.
900 This is superficially similar to mp.get_property_native(name).
902 An important difference is that this accesses the property
903 cache, and enables the change detection logic (which is essen‐
904 tial to the dynamic runtime behavior of auto profiles). Also, it
905 does not return an error value as second return value.
906 The "magic" tables mentioned above use this function as backend.
908 It does not perform the _ transliteration.
909 In addition, the same environment as in a blank mpv Lua script is
911 present. For example, math is defined and gives access to the Lua stan‐
912 dard math library.
913 WARNING:
915 This feature is subject to change indefinitely. You might be forced
916 to adjust your profiles on mpv updates.
917 Legacy auto profiles
919 Some profiles are loaded automatically using a legacy mechanism. The
920 following example demonstrates this:
921 Auto profile loading
923 [extension.mkv]
925 profile-desc="profile for .mkv files"
926 vf=vflip
927 The profile name follows the schema type.name, where type can be proto‐
929 col for the input/output protocol in use (see --list-protocols), and
930 extension for the extension of the path of the currently played file
931 (not the file format).
932 This feature is very limited, and is considered soft-deprecated. Use
934 conditional auto profiles.
935
937 There are three choices for using mpv from other programs or scripts:
938 1. Calling it as UNIX process. If you do this, do not parse terminal
940 output. The terminal output is intended for humans, and may
941 change any time. In addition, terminal behavior itself may change
942 any time. Compatibility cannot be guaranteed.
943 Your code should work even if you pass --no-terminal. Do not at‐
945 tempt to simulate user input by sending terminal control codes to
946 mpv's stdin. If you need interactive control, using --in‐
947 put-ipc-server is recommended. This gives you access to the JSON
948 IPC over unix domain sockets (or named pipes on Windows).
949 Depending on what you do, passing --no-config or --config-dir may
951 be a good idea to avoid conflicts with the normal mpv user con‐
952 figuration intended for CLI playback.
953 Using --input-ipc-server is also suitable for purposes like re‐
955 mote control (however, the IPC protocol itself is not "secure"
956 and not intended to be so).
957 2. Using libmpv. This is generally recommended when mpv is used as
959 playback backend for a completely different application. The pro‐
960 vided C API is very close to CLI mechanisms and the scripting
961 API.
962 Note that even though libmpv has different defaults, it can be
964 configured to work exactly like the CLI player (except command
965 line parsing is unavailable).
966 See EMBEDDING INTO OTHER PROGRAMS (LIBMPV).
968 3. As a user script (LUA SCRIPTING, JAVASCRIPT, C PLUGINS). This is
970 recommended when the goal is to "enhance" the CLI player. Scripts
971 get access to the entire client API of mpv.
972 This is the standard way to create third-party extensions for the
974 player.
975 All these access the client API, which is the sum of the various mecha‐
977 nisms provided by the player core, as documented here: OPTIONS, List of
978 Input Commands, Properties, List of events (also see C API), Hooks.
979
981 Screenshots of the currently played file can be taken using the
982 'screenshot' input mode command, which is by default bound to the s
983 key. Files named mpv-shotNNNN.jpg will be saved in the working direc‐
984 tory, using the first available number - no files will be overwritten.
985 In pseudo-GUI mode, the screenshot will be saved somewhere else. See
986 PSEUDO GUI MODE.
987 A screenshot will usually contain the unscaled video contents at the
989 end of the video filter chain and subtitles. By default, S takes
990 screenshots without subtitles, while s includes subtitles.
991 Unlike with MPlayer, the screenshot video filter is not required. This
993 filter was never required in mpv, and has been removed.
994
996 During playback, mpv shows the playback status on the terminal. It
997 looks like something like this:
998 AV: 00:03:12 / 00:24:25 (13%) A-V: -0.000
999 The status line can be overridden with the --term-status-msg option.
1001 The following is a list of things that can show up in the status line.
1003 Input properties, that can be used to get the same information manu‐
1004 ally, are also listed.
1005 • AV: or V: (video only) or A: (audio only)
1007 • The current time position in HH:MM:SS format (playback-time property)
1009 • The total file duration (absent if unknown) (duration property)
1011 • Playback speed, e.g. x2.0. Only visible if the speed is not normal.
1013 This is the user-requested speed, and not the actual speed (usually
1014 they should be the same, unless playback is too slow). (speed prop‐
1015 erty.)
1016 • Playback percentage, e.g. (13%). How much of the file has been
1018 played. Normally calculated out of playback position and duration,
1019 but can fallback to other methods (like byte position) if these are
1020 not available. (percent-pos property.)
1021 • The audio/video sync as A-V: 0.000. This is the difference between
1023 audio and video time. Normally it should be 0 or close to 0. If it's
1024 growing, it might indicate a playback problem. (avsync property.)
1025 • Total A/V sync change, e.g. ct: -0.417. Normally invisible. Can show
1027 up if there is audio "missing", or not enough frames can be dropped.
1028 Usually this will indicate a problem. (total-avsync-change property.)
1029 • Encoding state in {...}, only shown in encoding mode.
1031 • Display sync state. If display sync is active (display-sync-active
1033 property), this shows DS: 2.500/13, where the first number is average
1034 number of vsyncs per video frame (e.g. 2.5 when playing 24Hz videos
1035 on 60Hz screens), which might jitter if the ratio doesn't round off,
1036 or there are mistimed frames (vsync-ratio), and the second number of
1037 estimated number of vsyncs which took too long (vo-de‐
1038 layed-frame-count property). The latter is a heuristic, as it's gen‐
1039 erally not possible to determine this with certainty.
1040 • Dropped frames, e.g. Dropped: 4. Shows up only if the count is not 0.
1042 Can grow if the video framerate is higher than that of the display,
1043 or if video rendering is too slow. May also be incremented on "hic‐
1044 cups" and when the video frame couldn't be displayed on time.
1045 (frame-drop-count property.) If the decoder drops frames, the number
1046 of decoder-dropped frames is appended to the display as well, e.g.:
1047 Dropped: 4/34. This happens only if decoder frame dropping is enabled
1048 with the --framedrop options. (decoder-frame-drop-count property.)
1049 • Cache state, e.g. Cache: 2s/134KB. Visible if the stream cache is
1051 enabled. The first value shows the amount of video buffered in the
1052 demuxer in seconds, the second value shows the estimated size of the
1053 buffered amount in kilobytes. (demuxer-cache-duration and de‐
1054 muxer-cache-state properties.)
1055
1057 mpv is optimized for normal video playback, meaning it actually tries
1058 to buffer as much data as it seems to make sense. This will increase
1059 latency. Reducing latency is possible only by specifically disabling
1060 features which increase latency.
1061 The builtin low-latency profile tries to apply some of the options
1063 which can reduce latency. You can use --profile=low-latency to apply
1064 all of them. You can list the contents with --show-profile=low-latency
1065 (some of the options are quite obscure, and may change every mpv re‐
1066 lease).
1067 Be aware that some of the options can reduce playback quality.
1069 Most latency is actually caused by inconvenient timing behavior. You
1071 can disable this with --untimed, but it will likely break, unless the
1072 stream has no audio, and the input feeds data to the player at a con‐
1073 stant rate.
1074 Another common problem is with MJPEG streams. These do not signal the
1076 correct framerate. Using --untimed or --no-correct-pts --fps=60 might
1077 help.
1078 For livestreams, data can build up due to pausing the stream, due to
1080 slightly lower playback rate, or "buffering" pauses. If the demuxer
1081 cache is enabled, these can be skipped manually. The experimental
1082 drop-buffers command can be used to discard any buffered data, though
1083 it's very disruptive.
1084 In some cases, manually tuning TCP buffer sizes and such can help to
1086 reduce latency.
1087 Additional options that can be tried:
1089 • --opengl-glfinish=yes, can reduce buffering in the graphics driver
1091 • --opengl-swapinterval=0, same
1093 • --vo=xv, same
1095 • without audio --framedrop=no --speed=1.01 may help for live sources
1097 (results can be mixed)
1098
1100 mpv is capable of storing the playback position of the currently play‐
1101 ing file and resume from there the next time that file is played. This
1102 is done with the commands quit-watch-later (bound to Shift+Q by de‐
1103 fault) and write-watch-later-config, and with the --save-posi‐
1104 tion-on-quit option.
1105 The difference between always quitting with a key bound to
1107 quit-watch-later and using --save-position-on-quit is that the latter
1108 will save the playback position even when mpv is closed with a method
1109 other than a keybinding, for example if you shutdown your system with‐
1110 out closing mpv beforehand, unless of course mpv is terminated abruptly
1111 and doesn't have the time to save (e.g. with the KILL Unix signal).
1112 mpv also stores options other than the playback position when they have
1114 been modified after playback began, for example the volume and the
1115 fullscreen state, and restores their values the next time the file is
1116 played. Which options are saved can be configured with the
1117 --watch-later-options option.
1118 When playing multiple playlist entries, mpv checks if one them has a
1120 resume config file associated, and if it finds one it restarts playback
1121 from it. For example, if you use quit-watch-later on the 5th episode of
1122 a show, and later play all the episodes, mpv will automatically resume
1123 playback from episode 5.
1124 More options to configure this functionality are listed in Watch Later.
1126
1128 http://..., https://, ...
1129 Many network protocols are supported, but the protocol prefix must
1130 always be specified. mpv will never attempt to guess whether a file‐
1131 name is actually a network address. A protocol prefix is always re‐
1132 quired.
1133 Note that not all prefixes are documented here. Undocumented pre‐
1135 fixes are either aliases to documented protocols, or are just redi‐
1136 rections to protocols implemented and documented in FFmpeg.
1137 data: is supported in FFmpeg (not in Libav), but needs to be in the
1139 format data://. This is done to avoid ambiguity with filenames. You
1140 can also prefix it with lavf:// or ffmpeg://.
1141 ytdl://...
1143 By default, the youtube-dl hook script only looks at http(s) URLs.
1144 Prefixing an URL with ytdl:// forces it to be always processed by
1145 the script. This can also be used to invoke special youtube-dl func‐
1146 tionality like playing a video by ID or invoking search.
1147 Keep in mind that you can't pass youtube-dl command line options by
1149 this, and you have to use --ytdl-raw-options instead.
1150 -
1152 Play data from stdin.
1153 smb://PATH
1155 Play a path from Samba share. (Requires FFmpeg support.)
1156 bd://[title][/device] --bluray-device=PATH
1158 Play a Blu-ray disc. Since libbluray 1.0.1, you can read from ISO
1159 files by passing them to --bluray-device.
1160 title can be: longest or first (selects the default playlist);
1162 mpls/<number> (selects <number>.mpls playlist); <number> (select
1163 playlist with the same index). mpv will list the available playlists
1164 on loading.
1165 bluray:// is an alias.
1167 dvd://[title][/device] --dvd-device=PATH
1169 Play a DVD. DVD menus are not supported. If no title is given, the
1170 longest title is auto-selected. Without --dvd-device, it will proba‐
1171 bly try to open an actual optical drive, if available and imple‐
1172 mented for the OS.
1173 dvdnav:// is an old alias for dvd:// and does exactly the same
1175 thing.
1176 dvb://[cardnumber@]channel --dvbin-...
1178 Digital TV via DVB. (Linux only.)
1179 mf://[filemask|@listfile] --mf-...
1181 Play a series of images as video.
1182 cdda://[device] --cdrom-device=PATH --cdda-...
1184 Play CD.
1185 lavf://...
1187 Access any FFmpeg/Libav libavformat protocol. Basically, this passed
1188 the string after the // directly to libavformat.
1189 av://type:options
1191 This is intended for using libavdevice inputs. type is the libavde‐
1192 vice demuxer name, and options is the (pseudo-)filename passed to
1193 the demuxer.
1194 Example
1196 mpv av://v4l2:/dev/video0 --profile=low-latency --untimed
1198 This plays video from the first v4l input with nearly the lowest
1200 latency possible. It's a good replacement for the removed tv://
1201 input. Using --untimed is a hack to output a captured frame im‐
1202 mediately, instead of respecting the input framerate. (There may
1203 be better ways to handle this in the future.)
1204 avdevice:// is an alias.
1206 file://PATH
1208 A local path as URL. Might be useful in some special use-cases. Note
1209 that PATH itself should start with a third / to make the path an ab‐
1210 solute path.
1211 appending://PATH
1213 Play a local file, but assume it's being appended to. This is useful
1214 for example for files that are currently being downloaded to disk.
1215 This will block playback, and stop playback only if no new data was
1216 appended after a timeout of about 2 seconds.
1217 Using this is still a bit of a bad idea, because there is no way to
1219 detect if a file is actually being appended, or if it's still writ‐
1220 ten. If you're trying to play the output of some program, consider
1221 using a pipe (something | mpv -). If it really has to be a file on
1222 disk, use tail to make it wait forever, e.g. tail -f -c +0 file.mkv
1223 | mpv -.
1224 fd://123
1226 Read data from the given file descriptor (for example 123). This is
1227 similar to piping data to stdin via -, but can use an arbitrary file
1228 descriptor. mpv may modify some file descriptor properties when the
1229 stream layer "opens" it.
1230 fdclose://123
1232 Like fd://, but the file descriptor is closed after use. When using
1233 this you need to ensure that the same fd URL will only be used once.
1234 edl://[edl specification as in edl-mpv.rst]
1236 Stitch together parts of multiple files and play them.
1237 slice://start[-end]@URL
1239 Read a slice of a stream.
1240 start and end represent a byte range and accept suffixes such as KiB
1242 and MiB. end is optional.
1243 if end starts with +, it is considered as offset from start.
1245 Only works with seekable streams.
1247 Examples:
1249 mpv slice://1g-2g@cap.ts
1251 This starts reading from cap.ts after seeking 1 GiB, then
1253 reads until reaching 2 GiB or end of file.
1254 mpv slice://1g-+2g@cap.ts
1256 This starts reading from cap.ts after seeking 1 GiB, then
1258 reads until reaching 3 GiB or end of file.
1259 mpv slice://100m@appending://cap.ts
1261 This starts reading from cap.ts after seeking 100MiB, then
1263 reads until end of file.
1264 null://
1266 Simulate an empty file. If opened for writing, it will discard all
1267 data. The null demuxer will specifically pass autoprobing if this
1268 protocol is used (while it's not automatically invoked for empty
1269 files).
1270 memory://data
1272 Use the data part as source data.
1273 hex://data
1275 Like memory://, but the string is interpreted as hexdump.
1276
1278 mpv has no official GUI, other than the OSC (ON SCREEN CONTROLLER),
1279 which is not a full GUI and is not meant to be. However, to compensate
1280 for the lack of expected GUI behavior, mpv will in some cases start
1281 with some settings changed to behave slightly more like a GUI mode.
1282 Currently this happens only in the following cases:
1284 • if started using the mpv.desktop file on Linux (e.g. started from
1286 menus or file associations provided by desktop environments)
1287 • if started from explorer.exe on Windows (technically, if it was
1289 started on Windows, and all of the stdout/stderr/stdin handles are
1290 unset)
1291 • started out of the bundle on macOS
1293 • if you manually use --player-operation-mode=pseudo-gui on the command
1295 line
1296 This mode applies options from the builtin profile builtin-pseudo-gui,
1298 but only if these haven't been set in the user's config file or on the
1299 command line, which is the main difference to using --pro‐
1300 file=builtin-pseudo-gui.
1301 The profile is currently defined as follows:
1303 [builtin-pseudo-gui]
1305 terminal=no
1306 force-window=yes
1307 idle=once
1308 screenshot-directory=~~desktop/
1309 The pseudo-gui profile exists for compatibility. The options in the
1311 pseudo-gui profile are applied unconditionally. In addition, the pro‐
1312 file makes sure to enable the pseudo-GUI mode, so that --pro‐
1313 file=pseudo-gui works like in older mpv releases:
1314 [pseudo-gui]
1316 player-operation-mode=pseudo-gui
1317 WARNING:
1319 Currently, you can extend the pseudo-gui profile in the config file
1320 the normal way. This is deprecated. In future mpv releases, the be‐
1321 havior might change, and not apply your additional settings, and/or
1322 use a different profile name.
1323
1325 This subsection describes common problems on the Linux desktop. None of
1326 these problems exist on systems like Windows or macOS.
1327 Disabling Screensaver
1329 By default, mpv tries to disable the OS screensaver during playback
1330 (only if a VO using the OS GUI API is active). --stop-screensaver=no
1331 disables this.
1332 A common problem is that Linux desktop environments ignore the standard
1334 screensaver APIs on which mpv relies. In particular, mpv uses the
1335 Screen Saver extension (XSS) on X11, and the idle-inhibit protocol on
1336 Wayland.
1337 GNOME in particular still ignores the idle-inhibit protocol, and has
1339 its own D-Bus interfaces for display power management, which mpv does
1340 not support.
1341 Before mpv 0.33.0, the X11 backend ran xdg-screensaver reset in 10 sec‐
1343 ond intervals when not paused in order to support screensaver inhibi‐
1344 tion in these environments. This functionality was removed in 0.33.0,
1345 but it is possible to call the xdg-screensaver command line program
1346 from a user script instead.
1347
1349 Track Selection
1350 --alang=<languagecode[,languagecode,...]>
1351 Specify a priority list of audio languages to use. Different
1352 container formats employ different language codes. DVDs use ISO
1353 639-1 two-letter language codes, Matroska, MPEG-TS and NUT use
1354 ISO 639-2 three-letter language codes, while OGM uses a
1355 free-form identifier. See also --aid.
1356 This is a string list option. See List Options for details.
1358 Examples
1360 • mpv dvd://1 --alang=hu,en chooses the Hungarian language
1362 track on a DVD and falls back on English if Hungarian is
1363 not available.
1364 • mpv --alang=jpn example.mkv plays a Matroska file with Ja‐
1366 panese audio.
1367 --slang=<languagecode[,languagecode,...]>
1369 Specify a priority list of subtitle languages to use. Different
1370 container formats employ different language codes. DVDs use ISO
1371 639-1 two letter language codes, Matroska uses ISO 639-2 three
1372 letter language codes while OGM uses a free-form identifier. See
1373 also --sid.
1374 This is a string list option. See List Options for details.
1376 Examples
1378 • mpv dvd://1 --slang=hu,en chooses the Hungarian subtitle
1380 track on a DVD and falls back on English if Hungarian is
1381 not available.
1382 • mpv --slang=jpn example.mkv plays a Matroska file with Ja‐
1384 panese subtitles.
1385 --vlang=<...>
1387 Equivalent to --alang and --slang, for video tracks.
1388 This is a string list option. See List Options for details.
1390 --aid=<ID|auto|no>
1392 Select audio track. auto selects the default, no disables audio.
1393 See also --alang. mpv normally prints available audio tracks on
1394 the terminal when starting playback of a file.
1395 --audio is an alias for --aid.
1397 --aid=no or --audio=no or --no-audio disables audio playback.
1399 (The latter variant does not work with the client API.)
1400 NOTE:
1402 The track selection options (--aid but also --sid and the
1403 others) sometimes expose behavior that may appear strange.
1404 Also, the behavior tends to change around with each mpv re‐
1405 lease.
1406 The track selection properties will return the option value
1408 outside of playback (as expected), but during playback, the
1409 affective track selection is returned. For example, with
1410 --aid=auto, the aid property will suddenly return 2 after
1411 playback initialization (assuming the file has at least 2 au‐
1412 dio tracks, and the second is the default).
1413 At mpv 0.32.0 (and some releases before), if you passed a
1415 track value for which a corresponding track didn't exist
1416 (e.g. --aid=2 and there was only 1 audio track), the aid
1417 property returned no. However if another audio track was
1418 added during playback, and you tried to set the aid property
1419 to 2, nothing happened, because the aid option still had the
1420 value 2, and writing the same value has no effect.
1421 With mpv 0.33.0, the behavior was changed. Now track selec‐
1423 tion options are reset to auto at playback initialization, if
1424 the option had tries to select a track that does not exist.
1425 The same is done if the track exists, but fails to initial‐
1426 ize. The consequence is that unlike before mpv 0.33.0, the
1427 user's track selection parameters are clobbered in certain
1428 situations.
1429 Also since mpv 0.33.0, trying to select a track by number
1431 will strictly select this track. Before this change, trying
1432 to select a track which did not exist would fall back to
1433 track default selection at playback initialization. The new
1434 behavior is more consistent.
1435 Setting a track selection property at runtime, and then play‐
1437 ing a new file might reset the track selection to defaults,
1438 if the fingerprint of the track list of the new file is dif‐
1439 ferent.
1440 Be aware of tricky combinations of all of all of the above:
1442 for example, mpv --aid=2 file_with_2_audio_tracks.mkv
1443 file_with_1_audio_track.mkv would first play the correct
1444 track, and the second file without audio. If you then go
1445 back the first file, its first audio track will be played,
1446 and the second file is played with audio. If you do the same
1447 thing again but instead of using --aid=2 you run set aid 2
1448 while the file is playing, then changing to the second file
1449 will play its audio track. This is because runtime selection
1450 enables the fingerprint heuristic.
1451 Most likely this is not the end.
1453 --sid=<ID|auto|no>
1455 Display the subtitle stream specified by <ID>. auto selects the
1456 default, no disables subtitles.
1457 --sub is an alias for --sid.
1459 --sid=no or --sub=no or --no-sub disables subtitle decoding.
1461 (The latter variant does not work with the client API.)
1462 --vid=<ID|auto|no>
1464 Select video channel. auto selects the default, no disables
1465 video.
1466 --video is an alias for --vid.
1468 --vid=no or --video=no or --no-video disables video playback.
1470 (The latter variant does not work with the client API.)
1471 If video is disabled, mpv will try to download the audio only if
1473 media is streamed with youtube-dl, because it saves bandwidth.
1474 This is done by setting the ytdl_format to "bestaudio/best" in
1475 the ytdl_hook.lua script.
1476 --edition=<ID|auto>
1478 (Matroska files only) Specify the edition (set of chapters) to
1479 use, where 0 is the first. If set to auto (the default), mpv
1480 will choose the first edition declared as a default, or if there
1481 is no default, the first edition defined.
1482 --track-auto-selection=<yes|no>
1484 Enable the default track auto-selection (default: yes). Enabling
1485 this will make the player select streams according to --aid,
1486 --alang, and others. If it is disabled, no tracks are selected.
1487 In addition, the player will not exit if no tracks are selected,
1488 and wait instead (this wait mode is similar to pausing, but the
1489 pause option is not set).
1490 This is useful with --lavfi-complex: you can start playback in
1492 this mode, and then set select tracks at runtime by setting the
1493 filter graph. Note that if --lavfi-complex is set before play‐
1494 back is started, the referenced tracks are always selected.
1495 --subs-with-matching-audio=<yes|no>
1497 When autoselecting a subtitle track, select a non-forced one
1498 even if the selected audio stream matches your preferred subti‐
1499 tle language (default: yes). Disable this if you'd like to only
1500 show subtitles for foreign audio or onscreen text.
1501 Playback Control
1503 --start=<relative time>
1504 Seek to given time position.
1505 The general format for times is [+|-][[hh:]mm:]ss[.ms]. If the
1507 time is prefixed with -, the time is considered relative from
1508 the end of the file (as signaled by the demuxer/the file). A +
1509 is usually ignored (but see below).
1510 The following alternative time specifications are recognized:
1512 pp% seeks to percent position pp (0-100).
1514 #c seeks to chapter number c. (Chapters start from 1.)
1516 none resets any previously set option (useful for libmpv).
1518 If --rebase-start-time=no is given, then prefixing times with +
1520 makes the time relative to the start of the file. A timestamp
1521 without prefix is considered an absolute time, i.e. should seek
1522 to a frame with a timestamp as the file contains it. As a bug,
1523 but also a hidden feature, putting 1 or more spaces before the +
1524 or - always interprets the time as absolute, which can be used
1525 to seek to negative timestamps (useful for debugging at most).
1526 Examples
1528 --start=+56, --start=00:56
1530 Seeks to the start time + 56 seconds.
1531 --start=-56, --start=-00:56
1533 Seeks to the end time - 56 seconds.
1534 --start=01:10:00
1536 Seeks to 1 hour 10 min.
1537 --start=50%
1539 Seeks to the middle of the file.
1540 --start=30 --end=40
1542 Seeks to 30 seconds, plays 10 seconds, and exits.
1543 --start=-3:20 --length=10
1545 Seeks to 3 minutes and 20 seconds before the end of
1546 the file, plays 10 seconds, and exits.
1547 --start='#2' --end='#4'
1549 Plays chapters 2 and 3, and exits.
1550 --end=<relative time>
1552 Stop at given time. Use --length if the time should be relative
1553 to --start. See --start for valid option values and examples.
1554 --length=<relative time>
1556 Stop after a given time relative to the start time. See --start
1557 for valid option values and examples.
1558 If both --end and --length are provided, playback will stop when
1560 it reaches either of the two endpoints.
1561 Obscurity note: this does not work correctly if --re‐
1563 base-start-time=no, and the specified time is not an "absolute"
1564 time, as defined in the --start option description.
1565 --rebase-start-time=<yes|no>
1567 Whether to move the file start time to 00:00:00 (default: yes).
1568 This is less awkward for files which start at a random time‐
1569 stamp, such as transport streams. On the other hand, if there
1570 are timestamp resets, the resulting behavior can be rather
1571 weird. For this reason, and in case you are actually interested
1572 in the real timestamps, this behavior can be disabled with no.
1573 --speed=<0.01-100>
1575 Slow down or speed up playback by the factor given as parameter.
1576 If --audio-pitch-correction (on by default) is used, playing
1578 with a speed higher than normal automatically inserts the
1579 scaletempo2 audio filter.
1580 --pause
1582 Start the player in paused state.
1583 --shuffle
1585 Play files in random order.
1586 --playlist-start=<auto|index>
1588 Set which file on the internal playlist to start playback with.
1589 The index is an integer, with 0 meaning the first file. The
1590 value auto means that the selection of the entry to play is left
1591 to the playback resume mechanism (default). If an entry with the
1592 given index doesn't exist, the behavior is unspecified and might
1593 change in future mpv versions. The same applies if the playlist
1594 contains further playlists (don't expect any reasonable behav‐
1595 ior). Passing a playlist file to mpv should work with this op‐
1596 tion, though. E.g. mpv playlist.m3u --playlist-start=123 will
1597 work as expected, as long as playlist.m3u does not link to fur‐
1598 ther playlists.
1599 The value no is a deprecated alias for auto.
1601 --playlist=<filename>
1603 Play files according to a playlist file. Supports some common
1604 formats. If no format is detected, it will be treated as list of
1605 files, separated by newline characters. You may need this option
1606 to load plaintext files as a playlist. Note that XML playlist
1607 formats are not supported.
1608 This option forces --demuxer=playlist to interpret the playlist
1610 file. Some playlist formats, notably CUE and optical disc for‐
1611 mats, need to use different demuxers and will not work with this
1612 option. They still can be played directly, without using this
1613 option.
1614 You can play playlists directly, without this option. Before mpv
1616 version 0.31.0, this option disabled any security mechanisms
1617 that might be in place, but since 0.31.0 it uses the same secu‐
1618 rity mechanisms as playing a playlist file directly. If you
1619 trust the playlist file, you can disable any security checks
1620 with --load-unsafe-playlists. Because playlists can load other
1621 playlist entries, consider applying this option only to the
1622 playlist itself and not its entries, using something along these
1623 lines:
1624 mpv --{ --playlist=filename --load-unsafe-playlists --}
1625 WARNING:
1627 The way older versions of mpv played playlist files via
1628 --playlist was not safe against maliciously constructed
1629 files. Such files may trigger harmful actions. This has been
1630 the case for all verions of mpv prior to 0.31.0, and all
1631 MPlayer versions, but unfortunately this fact was not well
1632 documented earlier, and some people have even misguidedly
1633 recommended the use of --playlist with untrusted sources. Do
1634 NOT use --playlist with random internet sources or files you
1635 do not trust if you are not sure your mpv is at least 0.31.0.
1636 In particular, playlists can contain entries using protocols
1638 other than local files, such as special protocols like avde‐
1639 vice:// (which are inherently unsafe).
1640 --chapter-merge-threshold=<number>
1642 Threshold for merging almost consecutive ordered chapter parts
1643 in milliseconds (default: 100). Some Matroska files with ordered
1644 chapters have inaccurate chapter end timestamps, causing a small
1645 gap between the end of one chapter and the start of the next one
1646 when they should match. If the end of one playback part is less
1647 than the given threshold away from the start of the next one
1648 then keep playing video normally over the chapter change instead
1649 of doing a seek.
1650 --chapter-seek-threshold=<seconds>
1652 Distance in seconds from the beginning of a chapter within which
1653 a backward chapter seek will go to the previous chapter (de‐
1654 fault: 5.0). Past this threshold, a backward chapter seek will
1655 go to the beginning of the current chapter instead. A negative
1656 value means always go back to the previous chapter.
1657 --hr-seek=<no|absolute|yes|default>
1659 Select when to use precise seeks that are not limited to
1660 keyframes. Such seeks require decoding video from the previous
1661 keyframe up to the target position and so can take some time de‐
1662 pending on decoding performance. For some video formats, precise
1663 seeks are disabled. This option selects the default choice to
1664 use for seeks; it is possible to explicitly override that de‐
1665 fault in the definition of key bindings and in input commands.
1666 no Never use precise seeks.
1668 absolute
1670 Use precise seeks if the seek is to an absolute position
1671 in the file, such as a chapter seek, but not for relative
1672 seeks like the default behavior of arrow keys.
1673 default
1675 Like absolute, but enable hr-seeks in audio-only cases.
1676 The exact behavior is implementation specific and may
1677 change with new releases (default).
1678 yes Use precise seeks whenever possible.
1680 always Same as yes (for compatibility).
1682 --hr-seek-demuxer-offset=<seconds>
1684 This option exists to work around failures to do precise seeks
1685 (as in --hr-seek) caused by bugs or limitations in the demuxers
1686 for some file formats. Some demuxers fail to seek to a keyframe
1687 before the given target position, going to a later position in‐
1688 stead. The value of this option is subtracted from the time
1689 stamp given to the demuxer. Thus, if you set this option to 1.5
1690 and try to do a precise seek to 60 seconds, the demuxer is told
1691 to seek to time 58.5, which hopefully reduces the chance that it
1692 erroneously goes to some time later than 60 seconds. The down‐
1693 side of setting this option is that precise seeks become slower,
1694 as video between the earlier demuxer position and the real tar‐
1695 get may be unnecessarily decoded.
1696 --hr-seek-framedrop=<yes|no>
1698 Allow the video decoder to drop frames during seek, if these
1699 frames are before the seek target. If this is enabled, precise
1700 seeking can be faster, but if you're using video filters which
1701 modify timestamps or add new frames, it can lead to precise
1702 seeking skipping the target frame. This e.g. can break frame
1703 backstepping when deinterlacing is enabled.
1704 Default: yes
1706 --index=<mode>
1708 Controls how to seek in files. Note that if the index is missing
1709 from a file, it will be built on the fly by default, so you
1710 don't need to change this. But it might help with some broken
1711 files.
1712 default
1714 use an index if the file has one, or build it if missing
1715 recreate
1717 don't read or use the file's index
1718 NOTE:
1720 This option only works if the underlying media supports seek‐
1721 ing (i.e. not with stdin, pipe, etc).
1722 --load-unsafe-playlists
1724 Load URLs from playlists which are considered unsafe (default:
1725 no). This includes special protocols and anything that doesn't
1726 refer to normal files. Local files and HTTP links on the other
1727 hand are always considered safe.
1728 In addition, if a playlist is loaded while this is set, the
1730 added playlist entries are not marked as originating from net‐
1731 work or potentially unsafe location. (Instead, the behavior is
1732 as if the playlist entries were provided directly to mpv command
1733 line or loadfile command.)
1734 --access-references=<yes|no>
1736 Follow any references in the file being opened (default: yes).
1737 Disabling this is helpful if the file is automatically scanned
1738 (e.g. thumbnail generation). If the thumbnail scanner for exam‐
1739 ple encounters a playlist file, which contains network URLs, and
1740 the scanner should not open these, enabling this option will
1741 prevent it. This option also disables ordered chapters, mov ref‐
1742 erence files, opening of archives, and a number of other fea‐
1743 tures.
1744 On older FFmpeg versions, this will not work in some cases. Some
1746 FFmpeg demuxers might not respect this option.
1747 This option does not prevent opening of paired subtitle files
1749 and such. Use --autoload-files=no to prevent this.
1750 This option does not always work if you open non-files (for ex‐
1752 ample using dvd://directory would open a whole bunch of files in
1753 the given directory). Prefixing the filename with ./ if it
1754 doesn't start with a / will avoid this.
1755 --loop-playlist=<N|inf|force|no>, --loop-playlist
1757 Loops playback N times. A value of 1 plays it one time (de‐
1758 fault), 2 two times, etc. inf means forever. no is the same as 1
1759 and disables looping. If several files are specified on command
1760 line, the entire playlist is looped. --loop-playlist is the same
1761 as --loop-playlist=inf.
1762 The force mode is like inf, but does not skip playlist entries
1764 which have been marked as failing. This means the player might
1765 waste CPU time trying to loop a file that doesn't exist. But it
1766 might be useful for playing webradios under very bad network
1767 conditions.
1768 --loop-file=<N|inf|no>, --loop=<N|inf|no>
1770 Loop a single file N times. inf means forever, no means normal
1771 playback. For compatibility, --loop-file and --loop-file=yes are
1772 also accepted, and are the same as --loop-file=inf.
1773 The difference to --loop-playlist is that this doesn't loop the
1775 playlist, just the file itself. If the playlist contains only a
1776 single file, the difference between the two option is that this
1777 option performs a seek on loop, instead of reloading the file.
1778 NOTE:
1780 --loop-file counts the number of times it causes the player
1781 to seek to the beginning of the file, not the number of full
1782 playthroughs. This means --loop-file=1 will end up playing
1783 the file twice. Contrast with --loop-playlist, which counts
1784 the number of full playthroughs.
1785 --loop is an alias for this option.
1787 --ab-loop-a=<time>, --ab-loop-b=<time>
1789 Set loop points. If playback passes the b timestamp, it will
1790 seek to the a timestamp. Seeking past the b point doesn't loop
1791 (this is intentional).
1792 If a is after b, the behavior is as if the points were given in
1794 the right order, and the player will seek to b after crossing
1795 through a. This is different from old behavior, where looping
1796 was disabled (and as a bug, looped back to a on the end of the
1797 file).
1798 If either options are set to no (or unset), looping is disabled.
1800 This is different from old behavior, where an unset a implied
1801 the start of the file, and an unset b the end of the file.
1802 The loop-points can be adjusted at runtime with the correspond‐
1804 ing properties. See also ab-loop command.
1805 --ab-loop-count=<N|inf>
1807 Run A-B loops only N times, then ignore the A-B loop points (de‐
1808 fault: inf). Every finished loop iteration will decrement this
1809 option by 1 (unless it is set to inf or 0). inf means that loop‐
1810 ing goes on forever. If this option is set to 0, A-B looping is
1811 ignored, and even the ab-loop command will not enable looping
1812 again (the command will show (disabled) on the OSD message if
1813 both loop points are set, but ab-loop-count is 0).
1814 --ordered-chapters, --no-ordered-chapters
1816 Enabled by default. Disable support for Matroska ordered chap‐
1817 ters. mpv will not load or search for video segments from other
1818 files, and will also ignore any chapter order specified for the
1819 main file.
1820 --ordered-chapters-files=<playlist-file>
1822 Loads the given file as playlist, and tries to use the files
1823 contained in it as reference files when opening a Matroska file
1824 that uses ordered chapters. This overrides the normal mechanism
1825 for loading referenced files by scanning the same directory the
1826 main file is located in.
1827 Useful for loading ordered chapter files that are not located on
1829 the local filesystem, or if the referenced files are in differ‐
1830 ent directories.
1831 Note: a playlist can be as simple as a text file containing
1833 filenames separated by newlines.
1834 --chapters-file=<filename>
1836 Load chapters from this file, instead of using the chapter meta‐
1837 data found in the main file.
1838 This accepts a media file (like mkv) or even a pseudo-format
1840 like ffmetadata and uses its chapters to replace the current
1841 file's chapters. This doesn't work with OGM or XML chapters di‐
1842 rectly.
1843 --sstep=<sec>
1845 Skip <sec> seconds after every frame.
1846 NOTE:
1848 Without --hr-seek, skipping will snap to keyframes.
1849 --stop-playback-on-init-failure=<yes|no>
1851 Stop playback if either audio or video fails to initialize (de‐
1852 fault: no). With no, playback will continue in video-only or
1853 audio-only mode if one of them fails. This doesn't affect play‐
1854 back of audio-only or video-only files.
1855 --play-dir=<forward|+|backward|->
1857 Control the playback direction (default: forward). Setting back‐
1858 ward will attempt to play the file in reverse direction, with
1859 decreasing playback time. If this is set on playback starts,
1860 playback will start from the end of the file. If this is changed
1861 at during playback, a hr-seek will be issued to change the di‐
1862 rection.
1863 + and - are aliases for forward and backward.
1865 The rest of this option description pertains to the backward
1867 mode.
1868 NOTE:
1870 Backward playback is extremely fragile. It may not always
1871 work, is much slower than forward playback, and breaks cer‐
1872 tain other features. How well it works depends mainly on the
1873 file being played. Generally, it will show good results (or
1874 results at all) only if the stars align.
1875 mpv, as well as most media formats, were designed for forward
1877 playback only. Backward playback is bolted on top of mpv, and
1878 tries to make a medium effort to make backward playback work.
1879 Depending on your use-case, another tool may work much better.
1880 Backward playback is not exactly a 1st class feature. Implemen‐
1882 tation tradeoffs were made, that are bad for backward playback,
1883 but in turn do not cause disadvantages for normal playback. Var‐
1884 ious possible optimizations are not implemented in order to keep
1885 the complexity down. Normally, a media player is highly
1886 pipelined (future data is prepared in separate threads, so it is
1887 available in realtime when the next stage needs it), but back‐
1888 ward playback will essentially stall the pipeline at various
1889 random points.
1890 For example, for intra-only codecs are trivially backward
1892 playable, and tools built around them may make efficient use of
1893 them (consider video editors or camera viewers). mpv won't be
1894 efficient in this case, because it uses its generic backward
1895 playback algorithm, that on top of it is not very optimized.
1896 If you just want to quickly go backward through the video and
1898 just show "keyframes", just use forward playback, and hold down
1899 the left cursor key (which on CLI with default config sends many
1900 small relative seek commands).
1901 The implementation consists of mostly 3 parts:
1903 • Backward demuxing. This relies on the demuxer cache, so the
1905 demuxer cache should (or must, didn't test it) be enabled, and
1906 its size will affect performance. If the cache is too small or
1907 too large, quadratic runtime behavior may result.
1908 • Backward decoding. The decoder library used (libavcodec) does
1910 not support this. It is emulated by feeding bits of data in
1911 forward, putting the result in a queue, returning the queue
1912 data to the VO in reverse, and then starting over at an ear‐
1913 lier position. This can require buffering an extreme amount of
1914 decoded data, and also completely breaks pipelining.
1915 • Backward output. This is relatively simple, because the de‐
1917 coder returns the frames in the needed order. However, this
1918 may cause various problems because filters see audio and video
1919 going backward.
1920 Known problems:
1922 • It's fragile. If anything doesn't work, random non-useful be‐
1924 havior may occur. In simple cases, the player will just play
1925 nonsense and artifacts. In other cases, it may get stuck or
1926 heat the CPU. (Exceeding memory usage significantly beyond the
1927 user-set limits would be a bug, though.)
1928 • Performance and resource usage isn't good. In part this is in‐
1930 herent to backward playback of normal media formats, and in
1931 parts due to implementation choices and tradeoffs.
1932 • This is extremely reliant on good demuxer behavior. Although
1934 backward demuxing requires no special demuxer support, it is
1935 required that the demuxer performs seeks reliably, fulfills
1936 some specific requirements about packet metadata, and has de‐
1937 terministic behavior.
1938 • Starting playback exactly from the end may or may not work,
1940 depending on seeking behavior and file duration detection.
1941 • Some container formats, audio, and video codecs are not sup‐
1943 ported due to their behavior. There is no list, and the player
1944 usually does not detect them. Certain live streams (including
1945 TV captures) may exhibit problems in particular, as well as
1946 some lossy audio codecs. h264 intra-refresh is known not to
1947 work due to problems with libavcodec. WAV and some other raw
1948 audio formats tend to have problems - there are hacks for
1949 dealing with them, which may or may not work.
1950 • Backward demuxing of subtitles is not supported. Subtitle dis‐
1952 play still works for some external text subtitle formats.
1953 (These are fully read into memory, and only backward display
1954 is needed.) Text subtitles that are cached in the subtitle
1955 renderer also have a chance to be displayed correctly.
1956 • Some features dealing with playback of broken or hard to deal
1958 with files will not work fully (such as timestamp correction).
1959 • If demuxer low level seeks (i.e. seeking the actual demuxer
1961 instead of just within the demuxer cache) are performed by
1962 backward playback, the created seek ranges may not join, be‐
1963 cause not enough overlap is achieved.
1964 • Trying to use this with hardware video decoding will probably
1966 exhaust all your GPU memory and then crash a thing or two. Or
1967 it will fail because --hwdec-extra-frames will certainly be
1968 set too low.
1969 • Stream recording is broken. --stream-record may keep working
1971 if you backward play within a cached region only.
1972 • Relative seeks may behave weird. Small seeks backward (towards
1974 smaller time, i.e. seek -1) may not really seek properly, and
1975 audio will remain muted for a while. Using hr-seek is recom‐
1976 mended, which should have none of these problems.
1977 • Some things are just weird. For example, while seek commands
1979 manipulate playback time in the expected way (provided they
1980 work correctly), the framestep commands are transposed. Back‐
1981 stepping will perform very expensive work to step forward by 1
1982 frame.
1983 Tuning:
1985 • Remove all --vf/--af filters you have set. Disable hardware
1987 decoding. Disable idiotic nonsense like SPDIF passthrough.
1988 • Increasing --video-reversal-buffer might help if reversal
1990 queue overflow is reported, which may happen in high bitrate
1991 video, or video with large GOP. Hardware decoding mostly ig‐
1992 nores this, and you need to increase --hwdec-extra-frames in‐
1993 stead (until you get playback without logged errors).
1994 • The demuxer cache is essential for backward demuxing. Make
1996 sure to set --cache=yes. The cache size might matter. If it's
1997 too small, a queue overflow will be logged, and backward play‐
1998 back cannot continue, or it performs too many low level seeks.
1999 If it's too large, implementation tradeoffs may cause general
2000 performance issues. Use --demuxer-max-bytes to potentially in‐
2001 crease the amount of packets the demuxer layer can queue for
2002 reverse demuxing (basically it's the --video-reversal-buffer
2003 equivalent for the demuxer layer).
2004 • Setting --vd-queue-enable=yes can help a lot to make playback
2006 smooth (once it works).
2007 • --demuxer-backward-playback-step also factors into how many
2009 seeks may be performed, and whether backward demuxing could
2010 break due to queue overflow. If it's set too high, the back‐
2011 step operation needs to search through more packets all the
2012 time, even if the cache is large enough.
2013 • Setting --demuxer-cache-wait may be useful to cache the entire
2015 file into the demuxer cache. Set --demuxer-max-bytes to a
2016 large size to make sure it can read the entire cache; --de‐
2017 muxer-max-back-bytes should also be set to a large size to
2018 prevent that tries to trim the cache.
2019 • If audio artifacts are audible, even though the AO does not
2021 underrun, increasing --audio-backward-overlap might help in
2022 some cases.
2023 --video-reversal-buffer=<bytesize>, --audio-reversal-buffer=<bytesize>
2025 For backward decoding. Backward decoding decodes forward in
2026 steps, and then reverses the decoder output. These options con‐
2027 trol the approximate maximum amount of bytes that can be
2028 buffered. The main use of this is to avoid unbounded resource
2029 usage; during normal backward playback, it's not supposed to hit
2030 the limit, and if it does, it will drop frames and complain
2031 about it.
2032 Use this option if you get reversal queue overflow errors during
2034 backward playback. Increase the size until the warning disap‐
2035 pears. Usually, the video buffer will overflow first, especially
2036 if it's high resolution video.
2037 This does not work correctly if video hardware decoding is used.
2039 The video frame size will not include the referenced GPU and
2040 driver memory. Some hardware decoders may also be limited by
2041 --hwdec-extra-frames.
2042 How large the queue size needs to be depends entirely on the way
2044 the media was encoded. Audio typically requires a very small
2045 buffer, while video can require excessively large buffers.
2046 (Technically, this allows the last frame to exceed the limit.
2048 Also, this does not account for other buffered frames, such as
2049 inside the decoder or the video output.)
2050 This does not affect demuxer cache behavior at all.
2052 See --list-options for defaults and value range. <bytesize> op‐
2054 tions accept suffixes such as KiB and MiB.
2055 --video-backward-overlap=<auto|number>, --audio-backward-over‐
2057 lap=<auto|number>
2058 Number of overlapping keyframe ranges to use for backward decod‐
2059 ing (default: auto) ("keyframe" to be understood as in the
2060 mpv/ffmpeg specific meaning). Backward decoding works by for‐
2061 ward decoding in small steps. Some codecs cannot restart decod‐
2062 ing from any packet (even if it's marked as seek point), which
2063 becomes noticeable with backward decoding (in theory this is a
2064 problem with seeking too, but --hr-seek-demuxer-offset can fix
2065 it for seeking). In particular, MDCT based audio codecs are af‐
2066 fected.
2067 The solution is to feed a previous packet to the decoder each
2069 time, and then discard the output. This option controls how many
2070 packets to feed. The auto choice is currently hardcoded to 0 for
2071 video, and uses 1 for lossy audio, 0 for lossless audio. For
2072 some specific lossy audio codecs, this is set to 2.
2073 --video-backward-overlap can potentially handle intra-refresh
2075 video, depending on the exact conditions. You may have to use
2076 the --vd-lavc-show-all option as well.
2077 --video-backward-batch=<number>, --audio-backward-batch=<number>
2079 Number of keyframe ranges to decode at once when backward decod‐
2080 ing (default: 1 for video, 10 for audio). Another pointless tun‐
2081 ing parameter nobody should use. This should affect performance
2082 only. In theory, setting a number higher than 1 for audio will
2083 reduce overhead due to less frequent backstep operations and
2084 less redundant decoding work due to fewer decoded overlap frames
2085 (see --audio-backward-overlap). On the other hand, it requires a
2086 larger reversal buffer, and could make playback less smooth due
2087 to breaking pipelining (e.g. by decoding a lot, and then doing
2088 nothing for a while).
2089 It probably never makes sense to set --video-backward-batch. But
2091 in theory, it could help with intra-only video codecs by reduc‐
2092 ing backstep operations.
2093 --demuxer-backward-playback-step=<seconds>
2095 Number of seconds the demuxer should seek back to get new pack‐
2096 ets during backward playback (default: 60). This is useful for
2097 tuning backward playback, see --play-dir for details.
2098 Setting this to a very low value or 0 may make the player think
2100 seeking is broken, or may make it perform multiple seeks.
2101 Setting this to a high value may lead to quadratic runtime be‐
2103 havior.
2104 Program Behavior
2106 --help, --h
2107 Show short summary of options.
2108 You can also pass a string to this option, which will list all
2110 top-level options which contain the string in the name, e.g.
2111 --h=scale for all options that contain the word scale. The spe‐
2112 cial string * lists all top-level options.
2113 -v Increment verbosity level, one level for each -v found on the
2115 command line.
2116 --version, -V
2118 Print version string and exit.
2119 --no-config
2121 Do not load default configuration files. This prevents loading
2122 of both the user-level and system-wide mpv.conf and input.conf
2123 files. Other configuration files are blocked as well, such as
2124 resume playback files.
2125 NOTE:
2127 Files explicitly requested by command line options, like
2128 --include or --use-filedir-conf, will still be loaded.
2129 See also: --config-dir.
2131 --list-options
2133 Prints all available options.
2134 --list-properties
2136 Print a list of the available properties.
2137 --list-protocols
2139 Print a list of the supported protocols.
2140 --log-file=<path>
2142 Opens the given path for writing, and print log messages to it.
2143 Existing files will be truncated. The log level is at least -v
2144 -v, but can be raised via --msg-level (the option cannot lower
2145 it below the forced minimum log level).
2146 A special case is the macOS bundle, it will create a log file at
2148 ~/Library/Logs/mpv.log by default.
2149 --config-dir=<path>
2151 Force a different configuration directory. If this is set, the
2152 given directory is used to load configuration files, and all
2153 other configuration directories are ignored. This means the
2154 global mpv configuration directory as well as per-user directo‐
2155 ries are ignored, and overrides through environment variables
2156 (MPV_HOME) are also ignored.
2157 Note that the --no-config option takes precedence over this op‐
2159 tion.
2160 --dump-stats=<filename>
2162 Write certain statistics to the given file. The file is trun‐
2163 cated on opening. The file will contain raw samples, each with a
2164 timestamp. To make this file into a readable, the script
2165 TOOLS/stats-conv.py can be used (which currently displays it as
2166 a graph).
2167 This option is useful for debugging only.
2169 --idle=<no|yes|once>
2171 Makes mpv wait idly instead of quitting when there is no file to
2172 play. Mostly useful in input mode, where mpv can be controlled
2173 through input commands. (Default: no)
2174 once will only idle at start and let the player close once the
2176 first playlist has finished playing back.
2177 --include=<configuration-file>
2179 Specify configuration file to be parsed after the default ones.
2180 --load-scripts=<yes|no>
2182 If set to no, don't auto-load scripts from the scripts configu‐
2183 ration subdirectory (usually ~/.config/mpv/scripts/). (Default:
2184 yes)
2185 --script=<filename>, --scripts=file1.lua:file2.lua:...
2187 Load a Lua script. The second option allows you to load multiple
2188 scripts by separating them with the path separator (: on Unix, ;
2189 on Windows).
2190 --scripts is a path list option. See List Options for details.
2192 --script-opts=key1=value1,key2=value2,...
2194 Set options for scripts. A script can query an option by key. If
2195 an option is used and what semantics the option value has de‐
2196 pends entirely on the loaded scripts. Values not claimed by any
2197 scripts are ignored.
2198 This is a key/value list option. See List Options for details.
2200 --merge-files
2202 Pretend that all files passed to mpv are concatenated into a
2203 single, big file. This uses timeline/EDL support internally.
2204 --profile=<profile1,profile2,...>
2206 Use the given profile(s), --profile=help displays a list of the
2207 defined profiles.
2208 --reset-on-next-file=<all|option1,option2,...>
2210 Normally, mpv will try to keep all settings when playing the
2211 next file on the playlist, even if they were changed by the user
2212 during playback. (This behavior is the opposite of MPlayer's,
2213 which tries to reset all settings when starting next file.)
2214 Default: Do not reset anything.
2216 This can be changed with this option. It accepts a list of op‐
2218 tions, and mpv will reset the value of these options on playback
2219 start to the initial value. The initial value is either the de‐
2220 fault value, or as set by the config file or command line.
2221 In some cases, this might not work as expected. For example,
2223 --volume will only be reset if it is explicitly set in the con‐
2224 fig file or the command line.
2225 The special name all resets as many options as possible.
2227 This is a string list option. See List Options for details.
2229 Examples
2231 • --reset-on-next-file=pause Reset pause mode when switching
2233 to the next file.
2234 • --reset-on-next-file=fullscreen,speed Reset fullscreen and
2236 playback speed settings if they were changed during play‐
2237 back.
2238 • --reset-on-next-file=all Try to reset all settings that
2240 were changed during playback.
2241 --show-profile=<profile>
2243 Show the description and content of a profile. Lists all pro‐
2244 files if no parameter is provided.
2245 --use-filedir-conf
2247 Look for a file-specific configuration file in the same direc‐
2248 tory as the file that is being played. See File-specific Config‐
2249 uration Files.
2250 WARNING:
2252 May be dangerous if playing from untrusted media.
2253 --ytdl, --no-ytdl
2255 Enable the youtube-dl hook-script. It will look at the input
2256 URL, and will play the video located on the website. This works
2257 with many streaming sites, not just the one that the script is
2258 named after. This requires a recent version of youtube-dl to be
2259 installed on the system. (Enabled by default.)
2260 If the script can't do anything with an URL, it will do nothing.
2262 This accepts a set of options, which can be passed to it with
2264 the --script-opts option (using ytdl_hook- as prefix):
2265 try_ytdl_first=<yes|no>
2267 If 'yes' will try parsing the URL with youtube-dl first,
2268 instead of the default where it's only after mpv failed
2269 to open it. This mostly depends on whether most of your
2270 URLs need youtube-dl parsing.
2271 exclude=<URL1|URL2|...
2273 A |-separated list of URL patterns which mpv should not
2274 use with youtube-dl. The patterns are matched after the
2275 http(s):// part of the URL.
2276 ^ matches the beginning of the URL, $ matches its end,
2278 and you should use % before any of the characters
2279 ^$()%|,.[]*+-? to match that character.
2280 Examples
2282 • --script-opts=ytdl_hook-exclude='^youtube%.com' will
2284 exclude any URL that starts with http://youtube.com
2285 or https://youtube.com.
2286 • --script-opts=ytdl_hook-exclude='%.mkv$|%.mp4$' will
2288 exclude any URL that ends with .mkv or .mp4.
2289 See more lua patterns here:
2291 https://www.lua.org/manual/5.1/manual.html#5.4.1
2292 all_formats=<yes|no>
2294 If 'yes' will attempt to add all formats found reported
2295 by youtube-dl (default: no). Each format is added as a
2296 separate track. In addition, they are delay-loaded, and
2297 actually opened only when a track is selected (this
2298 should keep load times as low as without this option).
2299 It adds average bitrate metadata, if available, which
2301 means you can use --hls-bitrate to decide which track to
2302 select. (HLS used to be the only format whose alternative
2303 quality streams were exposed in a similar way, thus the
2304 option name.)
2305 Tracks which represent formats that were selected by
2307 youtube-dl as default will have the default flag set.
2308 This means mpv should generally still select formats cho‐
2309 sen with --ytdl-format by default.
2310 Although this mechanism makes it possible to switch
2312 streams at runtime, it's not suitable for this purpose
2313 for various technical reasons. (It's slow, which can't be
2314 really fixed.) In general, this option is not useful, and
2315 was only added to show that it's possible.
2316 There are two cases that must be considered when doing
2318 quality/bandwidth selection:
2319 1. Completely separate audio and video streams
2321 (DASH-like). Each of these streams contain either
2322 only audio or video, so you can mix and combine au‐
2323 dio/video bandwidths without restriction. This in‐
2324 tuitively matches best with the concept of select‐
2325 ing quality by track (what all_formats is supposed
2326 to do).
2327 2. Separate sets of muxed audio and video streams.
2329 Each version of the media contains both an audio
2330 and video stream, and they are interleaved. In or‐
2331 der not to waste bandwidth, you should only select
2332 one of these versions (if, for example, you select
2333 an audio stream, then video will be downloaded,
2334 even if you selected video from a different
2335 stream).
2336 mpv will still represent them as separate tracks,
2338 but will set the title of each track to muxed-N,
2339 where N is replaced with the youtube-dl format ID
2340 of the originating stream.
2341 Some sites will mix 1. and 2., but we assume that they do
2343 so for compatibility reasons, and there is no reason to
2344 use them at all.
2345 force_all_formats=<yes|no>
2347 If set to 'yes', and all_formats is also set to 'yes',
2348 this will try to represent all youtube-dl reported for‐
2349 mats as tracks, even if mpv would normally use the direct
2350 URL reported by it (default: yes).
2351 It appears this normally makes a difference if youtube-dl
2353 works on a master HLS playlist.
2354 If this is set to 'no', this specific kind of stream is
2356 treated like all_formats is set to 'no', and the stream
2357 selection as done by youtube-dl (via --ytdl-format) is
2358 used.
2359 use_manifests=<yes|no>
2361 Make mpv use the master manifest URL for formats like HLS
2362 and DASH, if available, allowing for video/audio selec‐
2363 tion in runtime (default: no). It's disabled ("no") by
2364 default for performance reasons.
2365 ytdl_path=youtube-dl
2367 Configure paths to youtube-dl's executable or a compati‐
2368 ble fork's. The paths should be separated by : on Unix
2369 and ; on Windows. mpv looks in order for the configured
2370 paths in PATH and in mpv's config directory. The de‐
2371 faults are "yt-dlp", "yt-dlp_x86" and "youtube-dl". On
2372 Windows the suffix extension ".exe" is always appended.
2373 Why do the option names mix _ and -?
2375 I have no idea.
2377 --ytdl-format=<ytdl|best|worst|mp4|webm|...>
2379 Video format/quality that is directly passed to youtube-dl. The
2380 possible values are specific to the website and the video, for a
2381 given url the available formats can be found with the command
2382 youtube-dl --list-formats URL. See youtube-dl's documentation
2383 for available aliases. (Default: bestvideo+bestaudio/best)
2384 The ytdl value does not pass a --format option to youtube-dl at
2386 all, and thus does not override its default. Note that sometimes
2387 youtube-dl returns a format that mpv cannot use, and in these
2388 cases the mpv default may work better.
2389 --ytdl-raw-options=<key>=<value>[,<key>=<value>[,...]]
2391 Pass arbitrary options to youtube-dl. Parameter and argument
2392 should be passed as a key-value pair. Options without argument
2393 must include =.
2394 There is no sanity checking so it's possible to break things
2396 (i.e. passing invalid parameters to youtube-dl).
2397 A proxy URL can be passed for youtube-dl to use it in parsing
2399 the website. This is useful for geo-restricted URLs. After
2400 youtube-dl parsing, some URLs also require a proxy for playback,
2401 so this can pass that proxy information to mpv. Take note that
2402 SOCKS proxies aren't supported and https URLs also bypass the
2403 proxy. This is a limitation in FFmpeg.
2404 This is a key/value list option. See List Options for details.
2406 Example
2408 • --ytdl-raw-options=username=user,password=pass
2410 • --ytdl-raw-options=force-ipv6=
2412 • --ytdl-raw-options=proxy=[http://127.0.0.1:3128]
2414 • --ytdl-raw-options-append=proxy=http://127.0.0.1:3128
2416 --load-stats-overlay=<yes|no>
2418 Enable the builtin script that shows useful playback information
2419 on a key binding (default: yes). By default, the i key is used
2420 (I to make the overlay permanent).
2421 --load-osd-console=<yes|no>
2423 Enable the built-in script that shows a console on a key binding
2424 and lets you enter commands (default: yes). The ` key is used to
2425 show the console by default, and ESC to hide it again.
2426 --load-auto-profiles=<yes|no|auto>
2428 Enable the builtin script that does auto profiles (default:
2429 auto). See Conditional auto profiles for details. auto will load
2430 the script, but immediately unload it if there are no condi‐
2431 tional profiles.
2432 --player-operation-mode=<cplayer|pseudo-gui>
2434 For enabling "pseudo GUI mode", which means that the defaults
2435 for some options are changed. This option should not normally be
2436 used directly, but only by mpv internally, or mpv-provided
2437 scripts, config files, or .desktop files. See PSEUDO GUI MODE
2438 for details.
2439 Watch Later
2441 --save-position-on-quit
2442 Always save the current playback position on quit. When this
2443 file is played again later, the player will seek to the old
2444 playback position on start. This does not happen if playback of
2445 a file is stopped in any other way than quitting. For example,
2446 going to the next file in the playlist will not save the posi‐
2447 tion, and start playback at beginning the next time the file is
2448 played.
2449 This behavior is disabled by default, but is always available
2451 when quitting the player with Shift+Q.
2452 See RESUMING PLAYBACK.
2454 --watch-later-directory=<path>
2456 The directory in which to store the "watch later" temporary
2457 files.
2458 The default is a subdirectory named "watch_later" underneath the
2460 config directory (usually ~/.config/mpv/).
2461 --no-resume-playback
2463 Do not restore playback position from the watch_later configura‐
2464 tion subdirectory (usually ~/.config/mpv/watch_later/).
2465 --resume-playback-check-mtime
2467 Only restore the playback position from the watch_later configu‐
2468 ration subdirectory (usually ~/.config/mpv/watch_later/) if the
2469 file's modification time is the same as at the time of saving.
2470 This may prevent skipping forward in files with the same name
2471 which have different content. (Default: no)
2472 --watch-later-options=option1,option2,...
2474 The options that are saved in "watch later" files if they have
2475 been changed since when mpv started. These values will be re‐
2476 stored the next time the files are played. The playback position
2477 is always saved as start, so adding start to this list has no
2478 effect.
2479 When removing options, existing watch later data won't be modi‐
2481 fied and will still be applied fully, but new watch later data
2482 won't contain these options.
2483 This is a string list option. See List Options for details.
2485 Examples
2487 • --watch-later-options-remove=fullscreen The fullscreen
2489 state won't be saved to watch later files.
2490 • --watch-later-options-remove=volume --watch-later-op‐
2492 tions-remove=mute The volume and mute state won't be saved
2493 to watch later files.
2494 • --watch-later-options-clr No option will be saved to watch
2496 later files except the starting position.
2497 --write-filename-in-watch-later-config
2499 Prepend the watch later config files with the name of the file
2500 they refer to. This is simply written as comment on the top of
2501 the file.
2502 WARNING:
2504 This option may expose privacy-sensitive information and is
2505 thus disabled by default.
2506 --ignore-path-in-watch-later-config
2508 Ignore path (i.e. use filename only) when using watch later fea‐
2509 ture. (Default: disabled)
2510 Video
2512 --vo=<driver>
2513 Specify the video output backend to be used. See VIDEO OUTPUT
2514 DRIVERS for details and descriptions of available drivers.
2515 --vd=<...>
2517 Specify a priority list of video decoders to be used, according
2518 to their family and name. See --ad for further details. Both of
2519 these options use the same syntax and semantics; the only dif‐
2520 ference is that they operate on different codec lists.
2521 NOTE:
2523 See --vd=help for a full list of available decoders.
2524 --vf=<filter1[=parameter1:parameter2:...],filter2,...>
2526 Specify a list of video filters to apply to the video stream.
2527 See VIDEO FILTERS for details and descriptions of the available
2528 filters. The option variants --vf-add, --vf-pre, --vf-del and
2529 --vf-clr exist to modify a previously specified list, but you
2530 should not need these for typical use.
2531 --untimed
2533 Do not sleep when outputting video frames. Useful for benchmarks
2534 when used with --no-audio.
2535 --framedrop=<mode>
2537 Skip displaying some frames to maintain A/V sync on slow sys‐
2538 tems, or playing high framerate video on video outputs that have
2539 an upper framerate limit.
2540 The argument selects the drop methods, and can be one of the
2542 following:
2543 <no> Disable any frame dropping. Not recommended, for testing
2545 only.
2546 <vo> Drop late frames on video output (default). This still
2548 decodes and filters all frames, but doesn't render them
2549 on the VO. Drops are indicated in the terminal status
2550 line as Dropped: field.
2551 In audio sync. mode, this drops frames that are outdated
2553 at the time of display. If the decoder is too slow, in
2554 theory all frames would have to be dropped (because all
2555 frames are too late) - to avoid this, frame dropping
2556 stops if the effective framerate is below 10 FPS.
2557 In display-sync. modes (see --video-sync), this affects
2559 only how A/V drops or repeats frames. If this mode is
2560 disabled, A/V desync will in theory not affect video
2561 scheduling anymore (much like the display-resample-desync
2562 mode). However, even if disabled, frames will still be
2563 skipped (i.e. dropped) according to the ratio between
2564 video and display frequencies.
2565 This is the recommended mode, and the default.
2567 <decoder>
2569 Old, decoder-based framedrop mode. (This is the same as
2570 --framedrop=yes in mpv 0.5.x and before.) This tells the
2571 decoder to skip frames (unless they are needed to decode
2572 future frames). May help with slow systems, but can pro‐
2573 duce unwatchable choppy output, or even freeze the dis‐
2574 play completely.
2575 This uses a heuristic which may not make sense, and in
2577 general cannot achieve good results, because the de‐
2578 coder's frame dropping cannot be controlled in a predict‐
2579 able manner. Not recommended.
2580 Even if you want to use this, prefer decoder+vo for bet‐
2582 ter results.
2583 The --vd-lavc-framedrop option controls what frames to
2585 drop.
2586 <decoder+vo>
2588 Enable both modes. Not recommended. Better than just de‐
2589 coder mode.
2590 NOTE:
2592 --vo=vdpau has its own code for the vo framedrop mode. Slight
2593 differences to other VOs are possible.
2594 --video-latency-hacks=<yes|no>
2596 Enable some things which tend to reduce video latency by 1 or 2
2597 frames (default: no). Note that this option might be removed
2598 without notice once the player's timing code does not inherently
2599 need to do these things anymore.
2600 This does:
2602 • Use the demuxer reported FPS for frame dropping. This avoids
2604 the player needing to decode 1 frame in advance, lowering to‐
2605 tal latency in effect. This also means that if the demuxer re‐
2606 ported FPS is wrong, or the video filter chain changes FPS
2607 (e.g. deinterlacing), then it could drop too many or not
2608 enough frames.
2609 • Disable waiting for the first video frame. Normally the player
2611 waits for the first video frame to be fully rendered before
2612 starting playback properly. Some VOs will lazily initialize
2613 stuff when rendering the first frame, so if this is not done,
2614 there is some likeliness that the VO has to drop some frames
2615 if rendering the first frame takes longer than needed.
2616 --override-display-fps=<fps>
2618 Set the display FPS used with the --video-sync=display-* modes.
2619 By default, a detected value is used. Keep in mind that setting
2620 an incorrect value (even if slightly incorrect) can ruin video
2621 playback. On multi-monitor systems, there is a chance that the
2622 detected value is from the wrong monitor.
2623 Set this option only if you have reason to believe the automati‐
2625 cally determined value is wrong.
2626 --display-fps=<fps>
2628 Deprecated alias for --override-display-fps.
2629 --hwdec=<api>
2631 Specify the hardware video decoding API that should be used if
2632 possible. Whether hardware decoding is actually done depends on
2633 the video codec. If hardware decoding is not possible, mpv will
2634 fall back on software decoding.
2635 Hardware decoding is not enabled by default, to keep the
2637 out-of-the-box configuration as reliable as possible. However,
2638 when using modern hardware, hardware video decoding should work
2639 correctly, offering reduced CPU usage, and possibly lower power
2640 consumption. On older systems, it may be necessary to use hard‐
2641 ware decoding due to insufficient CPU resources; and even on
2642 modern systems, sufficiently complex content (eg: 4K60 AV1) may
2643 require it.
2644 NOTE:
2646 Use the Ctrl+h shortcut to toggle hardware decoding at run‐
2647 time. It toggles this option between auto and no.
2648 If you decide you want to use hardware decoding by default,
2650 the general recommendation is to try out decoding with the
2651 command line option, and prove to yourself that it works as
2652 desired for the content you care about. After that, you can
2653 add it to your config file.
2654 When testing, you should start by using hwdec=auto-safe as it
2656 will limit itself to choosing from hwdecs that are actively
2657 supported by the development team. If that doesn't result in
2658 working hardware decoding, you can try hwdec=auto to have it
2659 attempt to load every possible hwdec, but if auto-safe didn't
2660 work, you will probably need to know exactly which hwdec
2661 matches your hardware and read up on that entry below.
2662 If auto-safe or auto produced the desired results, we recom‐
2664 mend just sticking with that and only setting a specific
2665 hwdec in your config file if it is really necessary.
2666 If you use the Ubuntu package, keep in mind that their
2668 /etc/mpv/mpv.conf contains hwdec=vaapi, which is less than
2669 ideal as it may not be the right choice for your system, and
2670 it may end up using an inefficient wrapper library under the
2671 covers. We recommend removing this line or deleting the file
2672 altogether.
2673 NOTE:
2675 Even if enabled, hardware decoding is still only white-listed
2676 for some codecs. See --hwdec-codecs to enable hardware decod‐
2677 ing in more cases.
2678 Which method to choose?
2680 • If you only want to enable hardware decoding at runtime,
2682 don't set the parameter, or put hwdec=no into your mpv.conf
2683 (relevant on distros which force-enable it by default, such
2684 as on Ubuntu). Use the Ctrl+h default binding to enable it
2685 at runtime.
2686 • If you're not sure, but want hardware decoding always en‐
2688 abled by default, put hwdec=auto-safe into your mpv.conf,
2689 and acknowledge that this may cause problems.
2690 • If you want to test available hardware decoding methods,
2692 pass --hwdec=auto --hwdec-codecs=all and look at the termi‐
2693 nal output.
2694 • If you're a developer, or want to perform elaborate tests,
2696 you may need any of the other possible option values.
2697 <api> can be one of the following:
2699 no always use software decoding (default)
2701 auto forcibly enable any hw decoder found (see below)
2703 yes exactly the same as auto
2705 auto-safe
2707 enable any whitelisted hw decoder (see below)
2708 auto-copy
2710 enable best hw decoder with copy-back (see below)
2711 Actively supported hwdecs:
2713 d3d11va
2715 requires --vo=gpu with --gpu-context=d3d11 or --gpu-con‐
2716 text=angle (Windows 8+ only)
2717 d3d11va-copy
2719 copies video back to system RAM (Windows 8+ only)
2720 videotoolbox
2722 requires --vo=gpu (macOS 10.8 and up), or --vo=libmpv
2723 (iOS 9.0 and up)
2724 videotoolbox-copy
2726 copies video back into system RAM (macOS 10.8 or iOS 9.0
2727 and up)
2728 vaapi requires --vo=gpu, --vo=vaapi or --vo=dmabuf-wayland
2730 (Linux only)
2731 vaapi-copy
2733 copies video back into system RAM (Linux with some GPUs
2734 only)
2735 nvdec requires --vo=gpu (Any platform CUDA is available)
2737 nvdec-copy
2739 copies video back to system RAM (Any platform CUDA is
2740 available)
2741 drm requires --vo=gpu (Linux only)
2743 drm-copy
2745 copies video back to system RAM (Linux ony)
2746 Other hwdecs (only use if you know you have to):
2748 dxva2 requires --vo=gpu with --gpu-context=d3d11, --gpu-con‐
2750 text=angle or --gpu-context=dxinterop (Windows only)
2751 dxva2-copy
2753 copies video back to system RAM (Windows only)
2754 vdpau requires --vo=gpu with X11, or --vo=vdpau (Linux only)
2756 vdpau-copy
2758 copies video back into system RAM (Linux with some GPUs
2759 only)
2760 mediacodec
2762 requires --vo=gpu --gpu-context=android or --vo=media‐
2763 codec_embed (Android only)
2764 mediacodec-copy
2766 copies video back to system RAM (Android only)
2767 mmal requires --vo=gpu (Raspberry Pi only - default if avail‐
2769 able)
2770 mmal-copy
2772 copies video back to system RAM (Raspberry Pi only)
2773 cuda requires --vo=gpu (Any platform CUDA is available)
2775 cuda-copy
2777 copies video back to system RAM (Any platform CUDA is
2778 available)
2779 crystalhd
2781 copies video back to system RAM (Any platform supported
2782 by hardware)
2783 rkmpp requires --vo=gpu (some RockChip devices only)
2785 auto tries to automatically enable hardware decoding using the
2787 first available method. This still depends what VO you are us‐
2788 ing. For example, if you are not using --vo=gpu or --vo=vdpau,
2789 vdpau decoding will never be enabled. Also note that if the
2790 first found method doesn't actually work, it will always fall
2791 back to software decoding, instead of trying the next method
2792 (might matter on some Linux systems).
2793 auto-safe is similar to auto, but allows only whitelisted meth‐
2795 ods that are considered "safe". This is supposed to be a reason‐
2796 able way to enable hardware decdoding by default in a config
2797 file (even though you shouldn't do that anyway; prefer runtime
2798 enabling with Ctrl+h). Unlike auto, this will not try to enable
2799 unknown or known-to-be-bad methods. In addition, this may dis‐
2800 able hardware decoding in other situations when it's known to
2801 cause problems, but currently this mechanism is quite primitive.
2802 (As an example for something that still causes problems: certain
2803 combinations of HEVC and Intel chips on Windows tend to cause
2804 mpv to crash, most likely due to driver bugs.)
2805 auto-copy-safe selects the union of methods selected with
2807 auto-safe and auto-copy.
2808 auto-copy selects only modes that copy the video data back to
2810 system memory after decoding. This selects modes like vaapi-copy
2811 (and so on). If none of these work, hardware decoding is dis‐
2812 abled. This mode is usually guaranteed to incur no additional
2813 quality loss compared to software decoding (assuming modern
2814 codecs and an error free video stream), and will allow CPU pro‐
2815 cessing with video filters. This mode works with all video fil‐
2816 ters and VOs.
2817 Because these copy the decoded video back to system RAM, they're
2819 often less efficient than the direct modes, and may not help too
2820 much over software decoding if you are short on CPU resources.
2821 NOTE:
2823 Most non-copy methods only work with the OpenGL GPU backend.
2824 Currently, only the vaapi, nvdec and cuda methods work with
2825 Vulkan.
2826 The vaapi mode, if used with --vo=gpu, requires Mesa 11, and
2828 most likely works with Intel and AMD GPUs only. It also requires
2829 the opengl EGL backend.
2830 nvdec and nvdec-copy are the newest, and recommended method to
2832 do hardware decoding on Nvidia GPUs.
2833 cuda and cuda-copy are an older implementation of hardware de‐
2835 coding on Nvidia GPUs that uses Nvidia's bitstream parsers
2836 rather than FFmpeg's. This can lead to feature deficiencies,
2837 such as incorrect playback of HDR content, and nvdec/nvdec-copy
2838 should always be preferred unless you specifically need Nvidia's
2839 deinterlacing algorithms. To use this deinterlacing you must
2840 pass the option: vd-lavc-o=deint=[weave|bob|adaptive]. Pass
2841 weave (or leave the option unset) to not attempt any deinterlac‐
2842 ing.
2843 Quality reduction with hardware decoding
2845 In theory, hardware decoding does not reduce video
2847 quality (at least for the codecs h264 and HEVC). How‐
2848 ever, due to restrictions in video output APIs, as
2849 well as bugs in the actual hardware decoders, there
2850 can be some loss, or even blatantly incorrect results.
2851 This has largely ceased to be a problem with modern
2852 hardware, but there is a lot of hardware out there, so
2853 caveat emptor. Known problems are discussed below, but
2854 the list cannot be considered exhaustive, as even
2855 hwdecs that work well on certain hardware generations
2856 may be problematic on other ones.
2857 In some cases, RGB conversion is forced, which means
2859 the RGB conversion is performed by the hardware decod‐
2860 ing API, instead of the shaders used by --vo=gpu. This
2861 means certain colorspaces may not display correctly,
2862 and certain filtering (such as debanding) cannot be
2863 applied in an ideal way. This will also usually force
2864 the use of low quality chroma scalers instead of the
2865 one specified by --cscale. In other cases, hardware
2866 decoding can also reduce the bit depth of the decoded
2867 image, which can introduce banding or precision loss
2868 for 10-bit files.
2869 vdpau always does RGB conversion in hardware, which
2871 does not support newer colorspaces like BT.2020 cor‐
2872 rectly. However, vdpau doesn't support 10 bit or HDR
2873 encodings, so these limitations are unlikely to be
2874 relevant.
2875 dxva2 is not safe. It appears to always use BT.601 for
2877 forced RGB conversion, but actual behavior depends on
2878 the GPU drivers. Some drivers appear to convert to
2879 limited range RGB, which gives a faded appearance. In
2880 addition to driver-specific behavior, global system
2881 settings might affect this additionally. This can give
2882 incorrect results even with completely ordinary video
2883 sources.
2884 rpi always uses the hardware overlay renderer, even
2886 with --vo=gpu.
2887 mediacodec is not safe. It forces RGB conversion (not
2889 with -copy) and how well it handles non-standard col‐
2890 orspaces is not known. In the rare cases where 10-bit
2891 is supported the bit depth of the output will be re‐
2892 duced to 8.
2893 cuda should usually be safe, but depending on how a
2895 file/stream has been mixed, it has been reported to
2896 corrupt the timestamps causing glitched, flashing
2897 frames. It can also sometimes cause massive framedrops
2898 for unknown reasons. Caution is advised, and nvdec
2899 should always be preferred.
2900 crystalhd is not safe. It always converts to 4:2:2
2902 YUV, which may be lossy, depending on how chroma
2903 sub-sampling is done during conversion. It also dis‐
2904 cards the top left pixel of each frame for some rea‐
2905 son.
2906 If you run into any weird decoding issues, frame
2908 glitches or discoloration, and you have --hwdec turned
2909 on, the first thing you should try is disabling it.
2910 --gpu-hwdec-interop=<auto|all|no|name>
2912 This option is for troubleshooting hwdec interop issues. Since
2913 it's a debugging option, its semantics may change at any time.
2914 This is useful for the gpu and libmpv VOs for selecting which
2916 hwdec interop context to use exactly. Effectively it also can be
2917 used to block loading of certain backends.
2918 If set to auto (default), the behavior depends on the VO: for
2920 gpu, it does nothing, and the interop context is loaded on de‐
2921 mand (when the decoder probes for --hwdec support). For libmpv,
2922 which has has no on-demand loading, this is equivalent to all.
2923 The empty string is equivalent to auto.
2925 If set to all, it attempts to load all interop contexts at GL
2927 context creation time.
2928 Other than that, a specific backend can be set, and the list of
2930 them can be queried with help (mpv CLI only).
2931 Runtime changes to this are ignored (the current option value is
2933 used whenever the renderer is created).
2934 The old aliases --opengl-hwdec-interop and --hwdec-preload are
2936 barely related to this anymore, but will be somewhat compatible
2937 in some cases.
2938 --hwdec-extra-frames=<N>
2940 Number of GPU frames hardware decoding should preallocate (de‐
2941 fault: see --list-options output). If this is too low, frame al‐
2942 location may fail during decoding, and video frames might get
2943 dropped and/or corrupted. Setting it too high simply wastes GPU
2944 memory and has no advantages.
2945 This value is used only for hardware decoding APIs which require
2947 preallocating surfaces (known examples include d3d11va and
2948 vaapi). For other APIs, frames are allocated as needed. The de‐
2949 tails depend on the libavcodec implementations of the hardware
2950 decoders.
2951 The required number of surfaces depends on dynamic runtime situ‐
2953 ations. The default is a fixed value that is thought to be suf‐
2954 ficient for most uses. But in certain situations, it may not be
2955 enough.
2956 --hwdec-image-format=<name>
2958 Set the internal pixel format used by hardware decoding via
2959 --hwdec (default no). The special value no selects an implemen‐
2960 tation specific standard format. Most decoder implementations
2961 support only one format, and will fail to initialize if the for‐
2962 mat is not supported.
2963 Some implementations might support multiple formats. In particu‐
2965 lar, videotoolbox is known to require uyvy422 for good perfor‐
2966 mance on some older hardware. d3d11va can always use yuv420p,
2967 which uses an opaque format, with likely no advantages.
2968 --cuda-decode-device=<auto|0..>
2970 Choose the GPU device used for decoding when using the cuda or
2971 nvdec hwdecs with the OpenGL GPU backend, and with the cuda-copy
2972 or nvdec-copy hwdecs in all cases.
2973 For the OpenGL GPU backend, the default device used for decoding
2975 is the one being used to provide gpu output (and in the vast ma‐
2976 jority of cases, only one GPU will be present).
2977 For the copy hwdecs, the default device will be the first device
2979 enumerated by the CUDA libraries - however that is done.
2980 For the Vulkan GPU backend, decoding must always happen on the
2982 display device, and this option has no effect.
2983 --vaapi-device=<device file>
2985 Choose the DRM device for vaapi-copy. This should be the path to
2986 a DRM device file. (Default: /dev/dri/renderD128)
2987 --panscan=<0.0-1.0>
2989 Enables pan-and-scan functionality (cropping the sides of e.g. a
2990 16:9 video to make it fit a 4:3 display without black bands).
2991 The range controls how much of the image is cropped. May not
2992 work with all video output drivers.
2993 This option has no effect if --video-unscaled option is used.
2995 --video-aspect-override=<ratio|no>
2997 Override video aspect ratio, in case aspect information is in‐
2998 correct or missing in the file being played.
2999 These values have special meaning:
3001 0 disable aspect ratio handling, pretend the video has
3003 square pixels
3004 no same as 0
3006 -1 use the video stream or container aspect (default)
3008 But note that handling of these special values might change in
3010 the future.
3011 Examples
3013 • --video-aspect-override=4:3 or --video-aspect-over‐
3015 ride=1.3333
3016 • --video-aspect-override=16:9 or --video-aspect-over‐
3018 ride=1.7777
3019 • --no-video-aspect-override or --video-aspect-override=no
3021 --video-aspect-method=<bitstream|container>
3023 This sets the default video aspect determination method (if the
3024 aspect is _not_ overridden by the user with --video-aspect-over‐
3025 ride or others).
3026 container
3028 Strictly prefer the container aspect ratio. This is ap‐
3029 parently the default behavior with VLC, at least with Ma‐
3030 troska. Note that if the container has no aspect ratio
3031 set, the behavior is the same as with bitstream.
3032 bitstream
3034 Strictly prefer the bitstream aspect ratio, unless the
3035 bitstream aspect ratio is not set. This is apparently the
3036 default behavior with XBMC/kodi, at least with Matroska.
3037 The current default for mpv is container.
3039 Normally you should not set this. Try the various choices if you
3041 encounter video that has the wrong aspect ratio in mpv, but
3042 seems to be correct in other players.
3043 --video-unscaled=<no|yes|downscale-big>
3045 Disable scaling of the video. If the window is larger than the
3046 video, black bars are added. Otherwise, the video is cropped,
3047 unless the option is set to downscale-big, in which case the
3048 video is fit to window. The video still can be influenced by the
3049 other --video-... options. This option disables the effect of
3050 --panscan.
3051 Note that the scaler algorithm may still be used, even if the
3053 video isn't scaled. For example, this can influence chroma con‐
3054 version. The video will also still be scaled in one dimension if
3055 the source uses non-square pixels (e.g. anamorphic widescreen
3056 DVDs).
3057 This option is disabled if the --no-keepaspect option is used.
3059 --video-pan-x=<value>, --video-pan-y=<value>
3061 Moves the displayed video rectangle by the given value in the X
3062 or Y direction. The unit is in fractions of the size of the
3063 scaled video (the full size, even if parts of the video are not
3064 visible due to panscan or other options).
3065 For example, displaying a 1280x720 video fullscreen on a
3067 1680x1050 screen with --video-pan-x=-0.1 would move the video
3068 168 pixels to the left (making 128 pixels of the source video
3069 invisible).
3070 This option is disabled if the --no-keepaspect option is used.
3072 --video-rotate=<0-359|no>
3074 Rotate the video clockwise, in degrees. If no is given, the
3075 video is never rotated, even if the file has rotation metadata.
3076 (The rotation value is added to the rotation metadata, which
3077 means the value 0 would rotate the video according to the rota‐
3078 tion metadata.)
3079 When using hardware decoding without copy-back, only 90° steps
3081 work, while software decoding and hardware decoding methods that
3082 copy the video back to system memory support all values between
3083 0 and 359.
3084 --video-zoom=<value>
3086 Adjust the video display scale factor by the given value. The
3087 parameter is given log 2. For example, --video-zoom=0 is un‐
3088 scaled, --video-zoom=1 is twice the size, --video-zoom=-2 is one
3089 fourth of the size, and so on.
3090 This option is disabled if the --no-keepaspect option is used.
3092 --video-scale-x=<value>, --video-scale-y=<value>
3094 Multiply the video display size with the given value (default:
3095 1.0). If a non-default value is used, this will be different
3096 from the window size, so video will be either cut off, or black
3097 bars are added.
3098 This value is multiplied with the value derived from
3100 --video-zoom and the normal video aspect ratio. This option is
3101 disabled if the --no-keepaspect option is used.
3102 --video-align-x=<-1-1>, --video-align-y=<-1-1>
3104 Moves the video rectangle within the black borders, which are
3105 usually added to pad the video to screen if video and screen as‐
3106 pect ratios are different. --video-align-y=-1 would move the
3107 video to the top of the screen (leaving a border only on the
3108 bottom), a value of 0 centers it (default), and a value of 1
3109 would put the video at the bottom of the screen.
3110 If video and screen aspect match perfectly, these options do
3112 nothing.
3113 This option is disabled if the --no-keepaspect option is used.
3115 --video-margin-ratio-left=<val>, --video-margin-ratio-right=<val>,
3117 --video-margin-ratio-top=<val>, --video-margin-ratio-bottom=<val>
3118 Set extra video margins on each border (default: 0). Each value
3119 is a ratio of the window size, using a range 0.0-1.0. For exam‐
3120 ple, setting the option --video-margin-ratio-right=0.2 at a win‐
3121 dow size of 1000 pixels will add a 200 pixels border on the
3122 right side of the window.
3123 The video is "boxed" by these margins. The window size is not
3125 changed. In particular it does not enlarge the window, and the
3126 margins will cause the video to be downscaled by default. This
3127 may or may not change in the future.
3128 The margins are applied after 90° video rotation, but before any
3130 other video transformations.
3131 This option is disabled if the --no-keepaspect option is used.
3133 Subtitles still may use the margins, depending on --sub-use-mar‐
3135 gins and similar options.
3136 These options were created for the OSC. Some odd decisions, such
3138 as making the margin values a ratio (instead of pixels), were
3139 made for the sake of the OSC. It's possible that these options
3140 may be replaced by ones that are more generally useful. The be‐
3141 havior of these options may change to fit OSC requirements bet‐
3142 ter, too.
3143 --correct-pts, --no-correct-pts
3145 --no-correct-pts switches mpv to a mode where video timing is
3146 determined using a fixed framerate value (either using the --fps
3147 option, or using file information). Sometimes, files with very
3148 broken timestamps can be played somewhat well in this mode. Note
3149 that video filters, subtitle rendering, seeking (including
3150 hr-seeks and backstepping), and audio synchronization can be
3151 completely broken in this mode.
3152 --fps=<float>
3154 Override video framerate. Useful if the original value is wrong
3155 or missing.
3156 NOTE:
3158 Works in --no-correct-pts mode only.
3159 --deinterlace=<yes|no>
3161 Enable or disable interlacing (default: no). Interlaced video
3162 shows ugly comb-like artifacts, which are visible on fast move‐
3163 ment. Enabling this typically inserts the yadif video filter in
3164 order to deinterlace the video, or lets the video output apply
3165 deinterlacing if supported.
3166 This behaves exactly like the deinterlace input property (usu‐
3168 ally mapped to d).
3169 Keep in mind that this will conflict with manually inserted
3171 deinterlacing filters, unless you take care. (Since mpv 0.27.0,
3172 even the hardware deinterlace filters will conflict. Also since
3173 that version, --deinterlace=auto was removed, which used to mean
3174 that the default interlacing option of possibly inserted video
3175 filters was used.)
3176 Note that this will make video look worse if it's not actually
3178 interlaced.
3179 --frames=<number>
3181 Play/convert only first <number> video frames, then quit.
3182 --frames=0 loads the file, but immediately quits before initial‐
3184 izing playback. (Might be useful for scripts which just want to
3185 determine some file properties.)
3186 For audio-only playback, any value greater than 0 will quit
3188 playback immediately after initialization. The value 0 works as
3189 with video.
3190 --video-output-levels=<outputlevels>
3192 RGB color levels used with YUV to RGB conversion. Normally, out‐
3193 put devices such as PC monitors use full range color levels.
3194 However, some TVs and video monitors expect studio RGB levels.
3195 Providing full range output to a device expecting studio level
3196 input results in crushed blacks and whites, the reverse in dim
3197 gray blacks and dim whites.
3198 Not all VOs support this option. Some will silently ignore it.
3200 Available color ranges are:
3202 auto automatic selection (equals to full range) (default)
3204 limited
3206 limited range (16-235 per component), studio levels
3207 full full range (0-255 per component), PC levels
3209 NOTE:
3211 It is advisable to use your graphics driver's color range op‐
3212 tion instead, if available.
3213 --hwdec-codecs=<codec1,codec2,...|all>
3215 Allow hardware decoding for a given list of codecs only. The
3216 special value all always allows all codecs.
3217 You can get the list of allowed codecs with mpv --vd=help. Re‐
3219 move the prefix, e.g. instead of lavc:h264 use h264.
3220 By default, this is set to h264,vc1,hevc,vp8,vp9,av1. Note that
3222 the hardware acceleration special codecs like h264_vdpau are not
3223 relevant anymore, and in fact have been removed from Libav in
3224 this form.
3225 This is usually only needed with broken GPUs, where a codec is
3227 reported as supported, but decoding causes more problems than it
3228 solves.
3229 Example
3231 mpv --hwdec=vdpau --vo=vdpau --hwdec-codecs=h264,mpeg2video
3233 Enable vdpau decoding for h264 and mpeg2 only.
3234 --vd-lavc-check-hw-profile=<yes|no>
3236 Check hardware decoder profile (default: yes). If no is set, the
3237 highest profile of the hardware decoder is unconditionally se‐
3238 lected, and decoding is forced even if the profile of the video
3239 is higher than that. The result is most likely broken decoding,
3240 but may also help if the detected or reported profiles are some‐
3241 how incorrect.
3242 --vd-lavc-software-fallback=<yes|no|N>
3244 Fallback to software decoding if the hardware-accelerated de‐
3245 coder fails (default: 3). If this is a number, then fallback
3246 will be triggered if N frames fail to decode in a row. 1 is
3247 equivalent to yes.
3248 Setting this to a higher number might break the playback start
3250 fallback: if a fallback happens, parts of the file will be
3251 skipped, approximately by to the number of packets that could
3252 not be decoded. Values below an unspecified count will not have
3253 this problem, because mpv retains the packets.
3254 --vd-lavc-film-grain=<auto|cpu|gpu>
3256 Enables film grain application on the GPU. If video decoding is
3257 done on the CPU, doing film grain application on the GPU can
3258 speed up decoding. This option can also help hardware decoding,
3259 as it can reduce the number of frame copies done.
3260 By default, it's set to auto, so if the VO supports film grain
3262 application, then it will be treated as gpu. If the VO does not
3263 support this, then it will be treated as cpu, regardless of the
3264 setting. Currently, only gpu-next supports film grain applica‐
3265 tion.
3266 --vd-lavc-dr=<yes|no>
3268 Enable direct rendering (default: yes). If this is set to yes,
3269 the video will be decoded directly to GPU video memory (or stag‐
3270 ing buffers). This can speed up video upload, and may help with
3271 large resolutions or slow hardware. This works only with the
3272 following VOs:
3273 • gpu: requires at least OpenGL 4.4 or Vulkan.
3275 • libmpv: The libmpv render API has optional support.
3277 Using video filters of any kind that write to the image data (or
3279 output newly allocated frames) will silently disable the DR code
3280 path.
3281 --vd-lavc-bitexact
3283 Only use bit-exact algorithms in all decoding steps (for codec
3284 testing).
3285 --vd-lavc-fast (MPEG-1/2 and H.264 only)
3287 Enable optimizations which do not comply with the format speci‐
3288 fication and potentially cause problems, like simpler dequanti‐
3289 zation, simpler motion compensation, assuming use of the default
3290 quantization matrix, assuming YUV 4:2:0 and skipping a few
3291 checks to detect damaged bitstreams.
3292 --vd-lavc-o=<key>=<value>[,<key>=<value>[,...]]
3294 Pass AVOptions to libavcodec decoder. Note, a patch to make the
3295 o= unneeded and pass all unknown options through the AVOption
3296 system is welcome. A full list of AVOptions can be found in the
3297 FFmpeg manual.
3298 Some options which used to be direct options can be set with
3300 this mechanism, like bug, gray, idct, ec, vismv, skip_top (was
3301 st), skip_bottom (was sb), debug.
3302 This is a key/value list option. See List Options for details.
3304 Example
3306 --vd-lavc-o=debug=pict
3308 --vd-lavc-show-all=<yes|no>
3310 Show even broken/corrupt frames (default: no). If this option is
3311 set to no, libavcodec won't output frames that were either de‐
3312 coded before an initial keyframe was decoded, or frames that are
3313 recognized as corrupted.
3314 --vd-lavc-skiploopfilter=<skipvalue> (H.264, HEVC only)
3316 Skips the loop filter (AKA deblocking) during decoding. Since
3317 the filtered frame is supposed to be used as reference for de‐
3318 coding dependent frames, this has a worse effect on quality than
3319 not doing deblocking on e.g. MPEG-2 video. But at least for high
3320 bitrate HDTV, this provides a big speedup with little visible
3321 quality loss. Codecs other than H.264 or HEVC may have partial
3322 support for this option (often only all and none).
3323 <skipvalue> can be one of the following:
3325 none Never skip.
3327 default
3329 Skip useless processing steps (e.g. 0 size packets in
3330 AVI).
3331 nonref Skip frames that are not referenced (i.e. not used for
3333 decoding other frames, the error cannot "build up").
3334 bidir Skip B-Frames.
3336 nonkey Skip all frames except keyframes.
3338 all Skip all frames.
3340 --vd-lavc-skipidct=<skipvalue> (MPEG-1/2/4 only)
3342 Skips the IDCT step. This degrades quality a lot in almost all
3343 cases (see skiploopfilter for available skip values).
3344 --vd-lavc-skipframe=<skipvalue>
3346 Skips decoding of frames completely. Big speedup, but jerky mo‐
3347 tion and sometimes bad artifacts (see skiploopfilter for avail‐
3348 able skip values).
3349 --vd-lavc-framedrop=<skipvalue>
3351 Set framedropping mode used with --framedrop (see skiploopfilter
3352 for available skip values).
3353 --vd-lavc-threads=<N>
3355 Number of threads to use for decoding. Whether threading is ac‐
3356 tually supported depends on codec (default: 0). 0 means autode‐
3357 tect number of cores on the machine and use that, up to the max‐
3358 imum of 16. You can set more than 16 threads manually.
3359 --vd-lavc-assume-old-x264=<yes|no>
3361 Assume the video was encoded by an old, buggy x264 version (de‐
3362 fault: no). Normally, this is autodetected by libavcodec. But
3363 if the bitstream contains no x264 version info (or it was some‐
3364 how skipped), and the stream was in fact encoded by an old x264
3365 version (build 150 or earlier), and if the stream uses 4:4:4
3366 chroma, then libavcodec will by default show corrupted video.
3367 This option sets the libavcodec x264_build option to 150, which
3368 means that if the stream contains no version info, or was not
3369 encoded by x264 at all, it assumes it was encoded by the old
3370 version. Enabling this option is pretty safe if you want your
3371 broken files to work, but in theory this can break on streams
3372 not encoded by x264, or if a stream encoded by a newer x264 ver‐
3373 sion contains no version info.
3374 --swapchain-depth=<N>
3376 Allow up to N in-flight frames. This essentially controls the
3377 frame latency. Increasing the swapchain depth can improve pipe‐
3378 lining and prevent missed vsyncs, but increases visible latency.
3379 This option only mandates an upper limit, the implementation can
3380 use a lower latency than requested internally. A setting of 1
3381 means that the VO will wait for every frame to become visible
3382 before starting to render the next frame. (Default: 3)
3383 Audio
3385 --audio-pitch-correction=<yes|no>
3386 If this is enabled (default), playing with a speed different
3387 from normal automatically inserts the scaletempo2 audio filter.
3388 For details, see audio filter section.
3389 --audio-device=<name>
3391 Use the given audio device. This consists of the audio output
3392 name, e.g. alsa, followed by /, followed by the audio output
3393 specific device name. The default value for this option is auto,
3394 which tries every audio output in preference order with the de‐
3395 fault device.
3396 You can list audio devices with --audio-device=help. This out‐
3398 puts the device name in quotes, followed by a description. The
3399 device name is what you have to pass to the --audio-device op‐
3400 tion. The list of audio devices can be retrieved by API by using
3401 the audio-device-list property.
3402 While the option normally takes one of the strings as indicated
3404 by the methods above, you can also force the device for most AOs
3405 by building it manually. For example name/foobar forces the AO
3406 name to use the device foobar. However, the --ao option will
3407 strictly force a specific AO. To avoid confusion, don't use --ao
3408 and --audio-device together.
3409 Example for ALSA
3411 MPlayer and mplayer2 required you to replace any ','
3413 with '.' and any ':' with '=' in the ALSA device name.
3414 For example, to use the device named dmix:default, you
3415 had to do:
3416 -ao alsa:device=dmix=default
3417 In mpv you could instead use:
3419 --audio-device=alsa/dmix:default
3420 --audio-exclusive=<yes|no>
3422 Enable exclusive output mode. In this mode, the system is usu‐
3423 ally locked out, and only mpv will be able to output audio.
3424 This only works for some audio outputs, such as wasapi and core‐
3426 audio. Other audio outputs silently ignore this options. They
3427 either have no concept of exclusive mode, or the mpv side of the
3428 implementation is missing.
3429 --audio-fallback-to-null=<yes|no>
3431 If no audio device can be opened, behave as if --ao=null was
3432 given. This is useful in combination with --audio-device: in‐
3433 stead of causing an error if the selected device does not exist,
3434 the client API user (or a Lua script) could let playback con‐
3435 tinue normally, and check the current-ao and audio-device-list
3436 properties to make high-level decisions about how to continue.
3437 --ao=<driver>
3439 Specify the audio output drivers to be used. See AUDIO OUTPUT
3440 DRIVERS for details and descriptions of available drivers.
3441 --af=<filter1[=parameter1:parameter2:...],filter2,...>
3443 Specify a list of audio filters to apply to the audio stream.
3444 See AUDIO FILTERS for details and descriptions of the available
3445 filters. The option variants --af-add, --af-pre, --af-del and
3446 --af-clr exist to modify a previously specified list, but you
3447 should not need these for typical use.
3448 --audio-spdif=<codecs>
3450 List of codecs for which compressed audio passthrough should be
3451 used. This works for both classic S/PDIF and HDMI.
3452 Possible codecs are ac3, dts, dts-hd, eac3, truehd. Multiple
3454 codecs can be specified by separating them with ,. dts refers to
3455 low bitrate DTS core, while dts-hd refers to DTS MA (receiver
3456 and OS support varies). If both dts and dts-hd are specified, it
3457 behaves equivalent to specifying dts-hd only.
3458 In earlier mpv versions you could use --ad to force the spdif
3460 wrapper. This does not work anymore.
3461 Warning
3463 There is not much reason to use this. HDMI supports
3465 uncompressed multichannel PCM, and mpv supports loss‐
3466 less DTS-HD decoding via FFmpeg's new DCA decoder
3467 (based on libdcadec).
3468 --ad=<decoder1,decoder2,...[-]>
3470 Specify a priority list of audio decoders to be used, according
3471 to their decoder name. When determining which decoder to use,
3472 the first decoder that matches the audio format is selected. If
3473 that is unavailable, the next decoder is used. Finally, it tries
3474 all other decoders that are not explicitly selected or rejected
3475 by the option.
3476 - at the end of the list suppresses fallback on other available
3478 decoders not on the --ad list. + in front of an entry forces the
3479 decoder. Both of these should not normally be used, because they
3480 break normal decoder auto-selection! Both of these methods are
3481 deprecated.
3482 Examples
3484 --ad=mp3float
3486 Prefer the FFmpeg/Libav mp3float decoder over all
3487 other MP3 decoders.
3488 --ad=help
3490 List all available decoders.
3491 Warning
3493 Enabling compressed audio passthrough (AC3 and DTS via
3495 SPDIF/HDMI) with this option is not possible. Use
3496 --audio-spdif instead.
3497 --volume=<value>
3499 Set the startup volume. 0 means silence, 100 means no volume re‐
3500 duction or amplification. Negative values can be passed for com‐
3501 patibility, but are treated as 0.
3502 Since mpv 0.18.1, this always controls the internal mixer (aka
3504 "softvol").
3505 --replaygain=<no|track|album>
3507 Adjust volume gain according to replaygain values stored in the
3508 file metadata. With --replaygain=no (the default), perform no
3509 adjustment. With --replaygain=track, apply track gain. With
3510 --replaygain=album, apply album gain if present and fall back to
3511 track gain otherwise.
3512 --replaygain-preamp=<db>
3514 Pre-amplification gain in dB to apply to the selected replaygain
3515 gain (default: 0).
3516 --replaygain-clip=<yes|no>
3518 Prevent clipping caused by replaygain by automatically lowering
3519 the gain (default). Use --replaygain-clip=no to disable this.
3520 --replaygain-fallback=<db>
3522 Gain in dB to apply if the file has no replay gain tags. This
3523 option is always applied if the replaygain logic is somehow in‐
3524 active. If this is applied, no other replaygain options are ap‐
3525 plied.
3526 --audio-delay=<sec>
3528 Audio delay in seconds (positive or negative float value). Posi‐
3529 tive values delay the audio, and negative values delay the
3530 video.
3531 --mute=<yes|no|auto>
3533 Set startup audio mute status (default: no).
3534 auto is a deprecated possible value that is equivalent to no.
3536 See also: --volume.
3538 --softvol=<no|yes|auto>
3540 Deprecated/unfunctional. Before mpv 0.18.1, this used to control
3541 whether to use the volume controls of the audio output driver or
3542 the internal mpv volume filter.
3543 The current behavior is that softvol is always enabled, i.e. as
3545 if this option is set to yes. The other behaviors are not avail‐
3546 able anymore, although auto almost matches current behavior in
3547 most cases.
3548 The no behavior is still partially available through the ao-vol‐
3550 ume and ao-mute properties. But there are no options to reset
3551 these.
3552 --audio-demuxer=<[+]name>
3554 Use this audio demuxer type when using --audio-file. Use a '+'
3555 before the name to force it; this will skip some checks. Give
3556 the demuxer name as printed by --audio-demuxer=help.
3557 --ad-lavc-ac3drc=<level>
3559 Select the Dynamic Range Compression level for AC-3 audio
3560 streams. <level> is a float value ranging from 0 to 1, where 0
3561 means no compression (which is the default) and 1 means full
3562 compression (make loud passages more silent and vice versa).
3563 Values up to 6 are also accepted, but are purely experimental.
3564 This option only shows an effect if the AC-3 stream contains the
3565 required range compression information.
3566 The standard mandates that DRC is enabled by default, but mpv
3568 (and some other players) ignore this for the sake of better au‐
3569 dio quality.
3570 --ad-lavc-downmix=<yes|no>
3572 Whether to request audio channel downmixing from the decoder
3573 (default: no). Some decoders, like AC-3, AAC and DTS, can remix
3574 audio on decoding. The requested number of output channels is
3575 set with the --audio-channels option. Useful for playing sur‐
3576 round audio on a stereo system.
3577 --ad-lavc-threads=<0-16>
3579 Number of threads to use for decoding. Whether threading is ac‐
3580 tually supported depends on codec. As of this writing, it's sup‐
3581 ported for some lossless codecs only. 0 means autodetect number
3582 of cores on the machine and use that, up to the maximum of 16
3583 (default: 1).
3584 --ad-lavc-o=<key>=<value>[,<key>=<value>[,...]]
3586 Pass AVOptions to libavcodec decoder. Note, a patch to make the
3587 o= unneeded and pass all unknown options through the AVOption
3588 system is welcome. A full list of AVOptions can be found in the
3589 FFmpeg manual.
3590 This is a key/value list option. See List Options for details.
3592 --ad-spdif-dtshd=<yes|no>, --dtshd, --no-dtshd
3594 If DTS is passed through, use DTS-HD.
3595 Warning
3597 This and enabling passthrough via --ad are deprecated
3599 in favor of using --audio-spdif=dts-hd.
3600 --audio-channels=<auto-safe|auto|layouts>
3602 Control which audio channels are output (e.g. surround vs.
3603 stereo). There are the following possibilities:
3604 •
3606 --audio-channels=auto-safe
3608 Use the system's preferred channel layout. If there is
3609 none (such as when accessing a hardware device instead
3610 of the system mixer), force stereo. Some audio outputs
3611 might simply accept any layout and do downmixing on
3612 their own.
3613 This is the default.
3615 •
3617 --audio-channels=auto
3619 Send the audio device whatever it accepts, preferring
3620 the audio's original channel layout. Can cause issues
3621 with HDMI (see the warning below).
3622 •
3624 --audio-channels=layout1,layout2,...
3626 List of ,-separated channel layouts which should be al‐
3627 lowed. Technically, this only adjusts the filter chain
3628 output to the best matching layout in the list, and
3629 passes the result to the audio API. It's possible that
3630 the audio API will select a different channel layout.
3631 Using this mode is recommended for direct hardware out‐
3633 put, especially over HDMI (see HDMI warning below).
3634 •
3636 --audio-channels=<stereo|mono>
3638 Force a downmix to stereo or mono. These are spe‐
3639 cial-cases of the previous item. (See paragraphs below
3640 for implications.)
3641 If a list of layouts is given, each item can be either an ex‐
3643 plicit channel layout name (like 5.1), or a channel number.
3644 Channel numbers refer to default layouts, e.g. 2 channels refer
3645 to stereo, 6 refers to 5.1.
3646 See --audio-channels=help output for defined default layouts.
3648 This also lists speaker names, which can be used to express ar‐
3649 bitrary channel layouts (e.g. fl-fr-lfe is 2.1).
3650 If the list of channel layouts has only 1 item, the decoder is
3652 asked to produce according output. This sometimes triggers de‐
3653 coder-downmix, which might be different from the normal mpv
3654 downmix. (Only some decoders support remixing audio, like AC-3,
3655 AAC or DTS. You can use --ad-lavc-downmix=no to make the decoder
3656 always output its native layout.) One consequence is that --au‐
3657 dio-channels=stereo triggers decoder downmix, while auto or
3658 auto-safe never will, even if they end up selecting stereo. This
3659 happens because the decision whether to use decoder downmix hap‐
3660 pens long before the audio device is opened.
3661 If the channel layout of the media file (i.e. the decoder) and
3663 the AO's channel layout don't match, mpv will attempt to insert
3664 a conversion filter. You may need to change the channel layout
3665 of the system mixer to achieve your desired output as mpv does
3666 not have control over it. Another work-around for this on some
3667 AOs is to use --audio-exclusive=yes to circumvent the system
3668 mixer entirely.
3669 Warning
3671 Using auto can cause issues when using audio over
3673 HDMI. The OS will typically report all channel layouts
3674 that _can_ go over HDMI, even if the receiver does not
3675 support them. If a receiver gets an unsupported chan‐
3676 nel layout, random things can happen, such as dropping
3677 the additional channels, or adding noise.
3678 You are recommended to set an explicit whitelist of
3680 the layouts you want. For example, most A/V receivers
3681 connected via HDMI and that can do 7.1 would be
3682 served by: --audio-channels=7.1,5.1,stereo
3683 --audio-display=<no|embedded-first|external-first>
3685 Determines whether to display cover art when playing audio files
3686 and with what priority. It will display the first image found,
3687 and additional images are available as video tracks.
3688 no Disable display of video entirely when playing audio
3690 files.
3691 embedded-first
3693 Display embedded images and external cover art, giving
3694 priority to embedded images (default).
3695 external-first
3697 Display embedded images and external cover art, giving
3698 priority to external files.
3699 This option has no influence on files with normal video tracks.
3701 --audio-files=<files>
3703 Play audio from an external file while viewing a video.
3704 This is a path list option. See List Options for details.
3706 --audio-file=<file>
3708 CLI/config file only alias for --audio-files-append. Each use of
3709 this option will add a new audio track. The details are similar
3710 to how --sub-file works.
3711 --audio-format=<format>
3713 Select the sample format used for output from the audio filter
3714 layer to the sound card. The values that <format> can adopt are
3715 listed below in the description of the format audio filter.
3716 --audio-samplerate=<Hz>
3718 Select the output sample rate to be used (of course sound cards
3719 have limits on this). If the sample frequency selected is dif‐
3720 ferent from that of the current media, the lavrresample audio
3721 filter will be inserted into the audio filter layer to compen‐
3722 sate for the difference.
3723 --gapless-audio=<no|yes|weak>
3725 Try to play consecutive audio files with no silence or disrup‐
3726 tion at the point of file change. Default: weak.
3727 no Disable gapless audio.
3729 yes The audio device is opened using parameters chosen for
3731 the first file played and is then kept open for gapless
3732 playback. This means that if the first file for example
3733 has a low sample rate, then the following files may get
3734 resampled to the same low sample rate, resulting in re‐
3735 duced sound quality. If you play files with different pa‐
3736 rameters, consider using options such as --audio-sampler‐
3737 ate and --audio-format to explicitly select what the
3738 shared output format will be.
3739 weak Normally, the audio device is kept open (using the format
3741 it was first initialized with). If the audio format the
3742 decoder output changes, the audio device is closed and
3743 reopened. This means that you will normally get gapless
3744 audio with files that were encoded using the same set‐
3745 tings, but might not be gapless in other cases. The ex‐
3746 act conditions under which the audio device is kept open
3747 is an implementation detail, and can change from version
3748 to version. Currently, the device is kept even if the
3749 sample format changes, but the sample formats are con‐
3750 vertible. If video is still going on when there is still
3751 audio, trying to use gapless is also explicitly given up.
3752 NOTE:
3754 This feature is implemented in a simple manner and relies on
3755 audio output device buffering to continue playback while mov‐
3756 ing from one file to another. If playback of the new file
3757 starts slowly, for example because it is played from a remote
3758 network location or because you have specified cache settings
3759 that require time for the initial cache fill, then the
3760 buffered audio may run out before playback of the new file
3761 can start.
3762 --initial-audio-sync, --no-initial-audio-sync
3764 When starting a video file or after events such as seeking, mpv
3765 will by default modify the audio stream to make it start from
3766 the same timestamp as video, by either inserting silence at the
3767 start or cutting away the first samples. Disabling this option
3768 makes the player behave like older mpv versions did: video and
3769 audio are both started immediately even if their start time‐
3770 stamps differ, and then video timing is gradually adjusted if
3771 necessary to reach correct synchronization later.
3772 --volume-max=<100.0-1000.0>, --softvol-max=<...>
3774 Set the maximum amplification level in percent (default: 130). A
3775 value of 130 will allow you to adjust the volume up to about
3776 double the normal level.
3777 --softvol-max is a deprecated alias and should not be used.
3779 --audio-file-auto=<no|exact|fuzzy|all>, --no-audio-file-auto
3781 Load additional audio files matching the video filename. The pa‐
3782 rameter specifies how external audio files are matched.
3783 no Don't automatically load external audio files (default).
3785 exact Load the media filename with audio file extension.
3787 fuzzy Load all audio files containing the media filename.
3789 all Load all audio files in the current and --au‐
3791 dio-file-paths directories.
3792 --audio-file-paths=<path1:path2:...>
3794 Equivalent to --sub-file-paths option, but for auto-loaded audio
3795 files.
3796 This is a path list option. See List Options for details.
3798 --audio-client-name=<name>
3800 The application name the player reports to the audio API. Can be
3801 useful if you want to force a different audio profile (e.g. with
3802 PulseAudio), or to set your own application name when using
3803 libmpv.
3804 --audio-buffer=<seconds>
3806 Set the audio output minimum buffer. The audio device might ac‐
3807 tually create a larger buffer if it pleases. If the device cre‐
3808 ates a smaller buffer, additional audio is buffered in an addi‐
3809 tional software buffer.
3810 Making this larger will make soft-volume and other filters react
3812 slower, introduce additional issues on playback speed change,
3813 and block the player on audio format changes. A smaller buffer
3814 might lead to audio dropouts.
3815 This option should be used for testing only. If a non-default
3817 value helps significantly, the mpv developers should be con‐
3818 tacted.
3819 Default: 0.2 (200 ms).
3821 --audio-stream-silence=<yes|no>
3823 Cash-grab consumer audio hardware (such as A/V receivers) often
3824 ignore initial audio sent over HDMI. This can happen every time
3825 audio over HDMI is stopped and resumed. In order to compensate
3826 for this, you can enable this option to not to stop and restart
3827 audio on seeks, and fill the gaps with silence. Likewise, when
3828 pausing playback, audio is not stopped, and silence is played
3829 while paused. Note that if no audio track is selected, the audio
3830 device will still be closed immediately.
3831 Not all AOs support this.
3833 Warning
3835 This modifies certain subtle player behavior, like
3837 A/V-sync and underrun handling. Enabling this option
3838 is strongly discouraged.
3839 --audio-wait-open=<secs>
3841 This makes sense for use with --audio-stream-silence=yes. If
3842 this option is given, the player will wait for the given amount
3843 of seconds after opening the audio device before sending actual
3844 audio data to it. Useful if your expensive hardware discards the
3845 first 1 or 2 seconds of audio data sent to it. If --au‐
3846 dio-stream-silence=yes is not set, this option will likely just
3847 waste time.
3848 Subtitles
3850 NOTE:
3851 Changing styling and position does not work with all subtitles. Im‐
3852 age-based subtitles (DVD, Bluray/PGS, DVB) cannot changed for funda‐
3853 mental reasons. Subtitles in ASS format are normally not changed
3854 intentionally, but overriding them can be controlled with
3855 --sub-ass-override.
3856 Previously some options working on text subtitles were called
3858 --sub-text-*, they are now named --sub-*, and those specifically for
3859 ASS have been renamed from --ass-* to --sub-ass-*. They are now all
3860 in this section.
3861 --sub-demuxer=<[+]name>
3863 Force subtitle demuxer type for --sub-file. Give the demuxer
3864 name as printed by --sub-demuxer=help.
3865 --sub-delay=<sec>
3867 Delays subtitles by <sec> seconds. Can be negative.
3868 --sub-files=<file-list>, --sub-file=<filename>
3870 Add a subtitle file to the list of external subtitles.
3871 If you use --sub-file only once, this subtitle file is displayed
3873 by default.
3874 If --sub-file is used multiple times, the subtitle to use can be
3876 switched at runtime by cycling subtitle tracks. It's possible to
3877 show two subtitles at once: use --sid to select the first subti‐
3878 tle index, and --secondary-sid to select the second index. (The
3879 index is printed on the terminal output after the --sid= in the
3880 list of streams.)
3881 --sub-files is a path list option (see List Options for de‐
3883 tails), and can take multiple file names separated by : (Unix)
3884 or ; (Windows), while --sub-file takes a single filename, but
3885 can be used multiple times to add multiple files. Technically,
3886 --sub-file is a CLI/config file only alias for --sub-files-ap‐
3887 pend.
3888 --secondary-sid=<ID|auto|no>
3890 Select a secondary subtitle stream. This is similar to --sid. If
3891 a secondary subtitle is selected, it will be rendered as topti‐
3892 tle (i.e. on the top of the screen) alongside the normal subti‐
3893 tle, and provides a way to render two subtitles at once.
3894 There are some caveats associated with this feature. For exam‐
3896 ple, bitmap subtitles will always be rendered in their usual po‐
3897 sition, so selecting a bitmap subtitle as secondary subtitle
3898 will result in overlapping subtitles. Secondary subtitles are
3899 never shown on the terminal if video is disabled.
3900 NOTE:
3902 Styling and interpretation of any formatting tags is disabled
3903 for the secondary subtitle. Internally, the same mechanism as
3904 --no-sub-ass is used to strip the styling.
3905 NOTE:
3907 If the main subtitle stream contains formatting tags which
3908 display the subtitle at the top of the screen, it will over‐
3909 lap with the secondary subtitle. To prevent this, you could
3910 use --no-sub-ass to disable styling in the main subtitle
3911 stream.
3912 --sub-scale=<0-100>
3914 Factor for the text subtitle font size (default: 1).
3915 NOTE:
3917 This affects ASS subtitles as well, and may lead to incorrect
3918 subtitle rendering. Use with care, or use --sub-font-size in‐
3919 stead.
3920 --sub-scale-by-window=<yes|no>
3922 Whether to scale subtitles with the window size (default: yes).
3923 If this is disabled, changing the window size won't change the
3924 subtitle font size.
3925 Like --sub-scale, this can break ASS subtitles.
3927 --sub-scale-with-window=<yes|no>
3929 Make the subtitle font size relative to the window, instead of
3930 the video. This is useful if you always want the same font
3931 size, even if the video doesn't cover the window fully, e.g. be‐
3932 cause screen aspect and window aspect mismatch (and the player
3933 adds black bars).
3934 Default: yes.
3936 This option is misnamed. The difference to the confusingly simi‐
3938 lar sounding option --sub-scale-by-window is that
3939 --sub-scale-with-window still scales with the approximate window
3940 size, while the other option disables this scaling.
3941 Affects plain text subtitles only (or ASS if --sub-ass-override
3943 is set high enough).
3944 --sub-ass-scale-with-window=<yes|no>
3946 Like --sub-scale-with-window, but affects subtitles in ASS for‐
3947 mat only. Like --sub-scale, this can break ASS subtitles.
3948 Default: no.
3950 --embeddedfonts=<yes|no>
3952 Use fonts embedded in Matroska container files and ASS scripts
3953 (default: yes). These fonts can be used for SSA/ASS subtitle
3954 rendering.
3955 --sub-pos=<0-150>
3957 Specify the position of subtitles on the screen. The value is
3958 the vertical position of the subtitle in % of the screen height.
3959 100 is the original position, which is often not the absolute
3960 bottom of the screen, but with some margin between the bottom
3961 and the subtitle. Values above 100 move the subtitle further
3962 down.
3963 Warning
3965 Text subtitles (as opposed to image subtitles) may be
3967 cut off if the value of the option is above 100. This
3968 is a libass restriction.
3969 This affects ASS subtitles as well, and may lead to
3971 incorrect subtitle rendering in addition to the prob‐
3972 lem above.
3973 Using --sub-margin-y can achieve this in a better way.
3975 --sub-speed=<0.1-10.0>
3977 Multiply the subtitle event timestamps with the given value. Can
3978 be used to fix the playback speed for frame-based subtitle for‐
3979 mats. Affects text subtitles only.
3980 Example
3982 --sub-speed=25/23.976 plays frame based subtitles
3984 which have been loaded assuming a framerate of 23.976
3985 at 25 FPS.
3986 --sub-ass-force-style=<[Style.]Param=Value[,...]>
3988 Override some style or script info parameters.
3989 This is a string list option. See List Options for details.
3991 Examples
3993 • --sub-ass-force-style=FontName=Arial,Default.Bold=1
3995 • --sub-ass-force-style=PlayResY=768
3997 NOTE:
3999 Using this option may lead to incorrect subtitle rendering.
4000 --sub-ass-hinting=<none|light|normal|native>
4002 Set font hinting type. <type> can be:
4003 none no hinting (default)
4005 light FreeType autohinter, light mode
4007 normal FreeType autohinter, normal mode
4009 native font native hinter
4011 Warning
4013 Enabling hinting can lead to mispositioned text (in
4015 situations it's supposed to match up video back‐
4016 ground), or reduce the smoothness of animations with
4017 some badly authored ASS scripts. It is recommended to
4018 not use this option, unless really needed.
4019 --sub-ass-line-spacing=<value>
4021 Set line spacing value for SSA/ASS renderer.
4022 --sub-ass-shaper=<simple|complex>
4024 Set the text layout engine used by libass.
4025 simple uses Fribidi only, fast, doesn't render some languages
4027 correctly
4028 complex
4030 uses HarfBuzz, slower, wider language support
4031 complex is the default. If libass hasn't been compiled against
4033 HarfBuzz, libass silently reverts to simple.
4034 --sub-ass-styles=<filename>
4036 Load all SSA/ASS styles found in the specified file and use them
4037 for rendering text subtitles. The syntax of the file is exactly
4038 like the [V4 Styles] / [V4+ Styles] section of SSA/ASS.
4039 NOTE:
4041 Using this option may lead to incorrect subtitle rendering.
4042 --sub-ass-override=<yes|no|force|scale|strip>
4044 Control whether user style overrides should be applied. Note
4045 that all of these overrides try to be somewhat smart about fig‐
4046 uring out whether or not a subtitle is considered a "sign".
4047 no Render subtitles as specified by the subtitle scripts,
4049 without overrides.
4050 yes Apply all the --sub-ass-* style override options. Chang‐
4052 ing the default for any of these options can lead to in‐
4053 correct subtitle rendering (default).
4054 force Like yes, but also force all --sub-* options. Can break
4056 rendering easily.
4057 scale Like yes, but also apply --sub-scale.
4059 strip Radically strip all ASS tags and styles from the subti‐
4061 tle. This is equivalent to the old --no-ass /
4062 --no-sub-ass options.
4063 This also controls some bitmap subtitle overrides, as well as
4065 HTML tags in formats like SRT, despite the name of the option.
4066 --sub-ass-force-margins
4068 Enables placing toptitles and subtitles in black borders when
4069 they are available, if the subtitles are in the ASS format.
4070 Default: no.
4072 --sub-use-margins
4074 Enables placing toptitles and subtitles in black borders when
4075 they are available, if the subtitles are in a plain text format
4076 (or ASS if --sub-ass-override is set high enough).
4077 Default: yes.
4079 Renamed from --sub-ass-use-margins. To place ASS subtitles in
4081 the borders too (like the old option did), also add
4082 --sub-ass-force-margins.
4083 --sub-ass-vsfilter-aspect-compat=<yes|no>
4085 Stretch SSA/ASS subtitles when playing anamorphic videos for
4086 compatibility with traditional VSFilter behavior. This switch
4087 has no effect when the video is stored with square pixels.
4088 The renderer historically most commonly used for the SSA/ASS
4090 subtitle formats, VSFilter, had questionable behavior that re‐
4091 sulted in subtitles being stretched too if the video was stored
4092 in anamorphic format that required scaling for display. This
4093 behavior is usually undesirable and newer VSFilter versions may
4094 behave differently. However, many existing scripts compensate
4095 for the stretching by modifying things in the opposite direc‐
4096 tion. Thus, if such scripts are displayed "correctly", they
4097 will not appear as intended. This switch enables emulation of
4098 the old VSFilter behavior (undesirable but expected by many ex‐
4099 isting scripts).
4100 Enabled by default.
4102 --sub-ass-vsfilter-blur-compat=<yes|no>
4104 Scale \blur tags by video resolution instead of script resolu‐
4105 tion (enabled by default). This is bug in VSFilter, which ac‐
4106 cording to some, can't be fixed anymore in the name of compati‐
4107 bility.
4108 Note that this uses the actual video resolution for calculating
4110 the offset scale factor, not what the video filter chain or the
4111 video output use.
4112 --sub-ass-vsfilter-color-compat=<basic|full|force-601|no>
4114 Mangle colors like (xy-)vsfilter do (default: basic). Histori‐
4115 cally, VSFilter was not color space aware. This was no problem
4116 as long as the color space used for SD video (BT.601) was used.
4117 But when everything switched to HD (BT.709), VSFilter was still
4118 converting RGB colors to BT.601, rendered them into the video
4119 frame, and handled the frame to the video output, which would
4120 use BT.709 for conversion to RGB. The result were mangled subti‐
4121 tle colors. Later on, bad hacks were added on top of the ASS
4122 format to control how colors are to be mangled.
4123 basic Handle only BT.601->BT.709 mangling, if the subtitles
4125 seem to indicate that this is required (default).
4126 full Handle the full YCbCr Matrix header with all video color
4128 spaces supported by libass and mpv. This might lead to
4129 bad breakages in corner cases and is not strictly needed
4130 for compatibility (hopefully), which is why this is not
4131 default.
4132 force-601
4134 Force BT.601->BT.709 mangling, regardless of subtitle
4135 headers or video color space.
4136 no Disable color mangling completely. All colors are RGB.
4138 Choosing anything other than no will make the subtitle color de‐
4140 pend on the video color space, and it's for example in theory
4141 not possible to reuse a subtitle script with another video file.
4142 The --sub-ass-override option doesn't affect how this option is
4143 interpreted.
4144 --stretch-dvd-subs=<yes|no>
4146 Stretch DVD subtitles when playing anamorphic videos for better
4147 looking fonts on badly mastered DVDs. This switch has no effect
4148 when the video is stored with square pixels - which for DVD in‐
4149 put cannot be the case though.
4150 Many studios tend to use bitmap fonts designed for square pixels
4152 when authoring DVDs, causing the fonts to look stretched on
4153 playback on DVD players. This option fixes them, however at the
4154 price of possibly misaligning some subtitles (e.g. sign transla‐
4155 tions).
4156 Disabled by default.
4158 --stretch-image-subs-to-screen=<yes|no>
4160 Stretch DVD and other image subtitles to the screen, ignoring
4161 the video margins. This has a similar effect as --sub-use-mar‐
4162 gins for text subtitles, except that the text itself will be
4163 stretched, not only just repositioned. (At least in general it
4164 is unavoidable, as an image bitmap can in theory consist of a
4165 single bitmap covering the whole screen, and the player won't
4166 know where exactly the text parts are located.)
4167 This option does not display subtitles correctly. Use with care.
4169 Disabled by default.
4171 --image-subs-video-resolution=<yes|no>
4173 Override the image subtitle resolution with the video resolution
4174 (default: no). Normally, the subtitle canvas is fit into the
4175 video canvas (e.g. letterboxed). Setting this option uses the
4176 video size as subtitle canvas size. Can be useful to test broken
4177 subtitles, which often happen when the video was trancoded,
4178 while attempting to keep the old subtitles.
4179 --sub-ass, --no-sub-ass
4181 Render ASS subtitles natively (enabled by default).
4182 NOTE:
4184 This has been deprecated by --sub-ass-override=strip. You
4185 also may need --embeddedfonts=no to get the same behavior.
4186 Also, using --sub-ass-override=style should give better re‐
4187 sults without breaking subtitles too much.
4188 If --no-sub-ass is specified, all tags and style declarations
4190 are stripped and ignored on display. The subtitle renderer uses
4191 the font style as specified by the --sub- options instead.
4192 NOTE:
4194 Using --no-sub-ass may lead to incorrect or completely broken
4195 rendering of ASS/SSA subtitles. It can sometimes be useful to
4196 forcibly override the styling of ASS subtitles, but should be
4197 avoided in general.
4198 --sub-auto=<no|exact|fuzzy|all>, --no-sub-auto
4200 Load additional subtitle files matching the video filename. The
4201 parameter specifies how external subtitle files are matched. ex‐
4202 act is enabled by default.
4203 no Don't automatically load external subtitle files.
4205 exact Load the media filename with subtitle file extension and
4207 possibly language suffixes (default).
4208 fuzzy Load all subs containing the media filename.
4210 all Load all subs in the current and --sub-file-paths direc‐
4212 tories.
4213 --sub-codepage=<codepage>
4215 You can use this option to specify the subtitle codepage.
4216 uchardet will be used to guess the charset. (If mpv was not com‐
4217 piled with uchardet, then utf-8 is the effective default.)
4218 The default value for this option is auto, which enables autode‐
4220 tection.
4221 The following steps are taken to determine the final codepage,
4223 in order:
4224 • if the specific codepage has a +, use that codepage
4226 • if the data looks like UTF-8, assume it is UTF-8
4228 • if --sub-codepage is set to a specific codepage, use that
4230 • run uchardet, and if successful, use that
4232 • otherwise, use UTF-8-BROKEN
4234 Examples
4236 • --sub-codepage=latin2 Use Latin 2 if input is not UTF-8.
4238 • --sub-codepage=+cp1250 Always force recoding to cp1250.
4240 The pseudo codepage UTF-8-BROKEN is used internally. If it's
4242 set, subtitles are interpreted as UTF-8 with "Latin 1" as fall‐
4243 back for bytes which are not valid UTF-8 sequences. iconv is
4244 never involved in this mode.
4245 This option changed in mpv 0.23.0. Support for the old syntax
4247 was fully removed in mpv 0.24.0.
4248 NOTE:
4250 This works for text subtitle files only. Other types of sub‐
4251 titles (in particular subtitles in mkv files) are always as‐
4252 sumed to be UTF-8.
4253 --sub-fix-timing=<yes|no>
4255 Adjust subtitle timing is to remove minor gaps or overlaps be‐
4256 tween subtitles (if the difference is smaller than 210 ms, the
4257 gap or overlap is removed).
4258 --sub-forced-only=<auto|yes|no>
4260 Display only forced subtitles for the DVD subtitle stream se‐
4261 lected by e.g. --slang (default: auto). When set to auto, en‐
4262 abled when the --subs-with-matching-audio option is on and a
4263 non-forced stream is selected. Enabling this will hide all sub‐
4264 titles in streams that don't make a distinction between forced
4265 and unforced events within a stream.
4266 --sub-fps=<rate>
4268 Specify the framerate of the subtitle file (default: video fps).
4269 Affects text subtitles only.
4270 NOTE:
4272 <rate> > video fps speeds the subtitles up for frame-based
4273 subtitle files and slows them down for time-based ones.
4274 See also: --sub-speed.
4276 --sub-gauss=<0.0-3.0>
4278 Apply Gaussian blur to image subtitles (default: 0). This can
4279 help to make pixelated DVD/Vobsubs look nicer. A value other
4280 than 0 also switches to software subtitle scaling. Might be
4281 slow.
4282 NOTE:
4284 Never applied to text subtitles.
4285 --sub-gray
4287 Convert image subtitles to grayscale. Can help to make yellow
4288 DVD/Vobsubs look nicer.
4289 NOTE:
4291 Never applied to text subtitles.
4292 --sub-paths=<path1:path2:...>
4294 Deprecated, use --sub-file-paths.
4295 --sub-file-paths=<path-list>
4297 Specify extra directories to search for subtitles matching the
4298 video. Multiple directories can be separated by ":" (";" on
4299 Windows). Paths can be relative or absolute. Relative paths are
4300 interpreted relative to video file directory. If the file is a
4301 URL, only absolute paths and sub configuration subdirectory will
4302 be scanned.
4303 Example
4305 Assuming that /path/to/video/video.avi is played and
4307 --sub-file-paths=sub:subtitles is specified, mpv
4308 searches for subtitle files in these directories:
4309 • /path/to/video/
4311 • /path/to/video/sub/
4313 • /path/to/video/subtitles/
4315 • the sub configuration subdirectory (usually ~/.con‐
4317 fig/mpv/sub/)
4318 This is a path list option. See List Options for details.
4320 --sub-visibility, --no-sub-visibility
4322 Can be used to disable display of subtitles, but still select
4323 and decode them.
4324 --secondary-sub-visibility, --no-secondary-sub-visibility
4326 Can be used to disable display of secondary subtitles, but still
4327 select and decode them.
4328 --sub-clear-on-seek
4330 (Obscure, rarely useful.) Can be used to play broken mkv files
4331 with duplicate ReadOrder fields. ReadOrder is the first field in
4332 a Matroska-style ASS subtitle packets. It should be unique, and
4333 libass uses it for fast elimination of duplicates. This option
4334 disables caching of subtitles across seeks, so after a seek
4335 libass can't eliminate subtitle packets with the same ReadOrder
4336 as earlier packets.
4337 --teletext-page=<1-999>
4339 This works for dvb_teletext subtitle streams, and if FFmpeg has
4340 been compiled with support for it.
4341 --sub-past-video-end
4343 After the last frame of video, if this option is enabled, subti‐
4344 tles will continue to update based on audio timestamps. Other‐
4345 wise, the subtitles for the last video frame will stay onscreen.
4346 Default: disabled
4348 --sub-font=<name>
4350 Specify font to use for subtitles that do not themselves specify
4351 a particular font. The default is sans-serif.
4352 Examples
4354 • --sub-font='Bitstream Vera Sans'
4356 • --sub-font='Comic Sans MS'
4358 NOTE:
4360 The --sub-font option (and many other style related --sub-
4361 options) are ignored when ASS-subtitles are rendered, unless
4362 the --no-sub-ass option is specified.
4363 This used to support fontconfig patterns. Starting with
4365 libass 0.13.0, this stopped working.
4366 --sub-font-size=<size>
4368 Specify the sub font size. The unit is the size in scaled pixels
4369 at a window height of 720. The actual pixel size is scaled with
4370 the window height: if the window height is larger or smaller
4371 than 720, the actual size of the text increases or decreases as
4372 well.
4373 Default: 55.
4375 --sub-back-color=<color>
4377 See --sub-color. Color used for sub text background. You can use
4378 --sub-shadow-offset to change its size relative to the text.
4379 --sub-blur=<0..20.0>
4381 Gaussian blur factor. 0 means no blur applied (default).
4382 --sub-bold=<yes|no>
4384 Format text on bold.
4385 --sub-italic=<yes|no>
4387 Format text on italic.
4388 --sub-border-color=<color>
4390 See --sub-color. Color used for the sub font border.
4391 --sub-border-size=<size>
4393 Size of the sub font border in scaled pixels (see
4394 --sub-font-size for details). A value of 0 disables borders.
4395 Default: 3.
4397 --sub-color=<color>
4399 Specify the color used for unstyled text subtitles.
4400 The color is specified in the form r/g/b, where each color com‐
4402 ponent is specified as number in the range 0.0 to 1.0. It's also
4403 possible to specify the transparency by using r/g/b/a, where the
4404 alpha value 0 means fully transparent, and 1.0 means opaque. If
4405 the alpha component is not given, the color is 100% opaque.
4406 Passing a single number to the option sets the sub to gray, and
4408 the form gray/a lets you specify alpha additionally.
4409 Examples
4411 • --sub-color=1.0/0.0/0.0 set sub to opaque red
4413 • --sub-color=1.0/0.0/0.0/0.75 set sub to opaque red with 75%
4415 alpha
4416 • --sub-color=0.5/0.75 set sub to 50% gray with 75% alpha
4418 Alternatively, the color can be specified as a RGB hex triplet
4420 in the form #RRGGBB, where each 2-digit group expresses a color
4421 value in the range 0 (00) to 255 (FF). For example, #FF0000 is
4422 red. This is similar to web colors. Alpha is given with #AAR‐
4423 RGGBB.
4424 Examples
4426 • --sub-color='#FF0000' set sub to opaque red
4428 • --sub-color='#C0808080' set sub to 50% gray with 75% alpha
4430 --sub-margin-x=<size>
4432 Left and right screen margin for the subs in scaled pixels (see
4433 --sub-font-size for details).
4434 This option specifies the distance of the sub to the left, as
4436 well as at which distance from the right border long sub text
4437 will be broken.
4438 Default: 25.
4440 --sub-margin-y=<size>
4442 Top and bottom screen margin for the subs in scaled pixels (see
4443 --sub-font-size for details).
4444 This option specifies the vertical margins of unstyled text sub‐
4446 titles. If you just want to raise the vertical subtitle posi‐
4447 tion, use --sub-pos.
4448 Default: 22.
4450 --sub-align-x=<left|center|right>
4452 Control to which corner of the screen text subtitles should be
4453 aligned to (default: center).
4454 Never applied to ASS subtitles, except in --no-sub-ass mode.
4456 Likewise, this does not apply to image subtitles.
4457 --sub-align-y=<top|center|bottom>
4459 Vertical position (default: bottom). Details see --sub-align-x.
4460 --sub-justify=<auto|left|center|right>
4462 Control how multi line subs are justified irrespective of where
4463 they are aligned (default: auto which justifies as defined by
4464 --sub-align-x). Left justification is recommended to make the
4465 subs easier to read as it is easier for the eyes.
4466 --sub-ass-justify=<yes|no>
4468 Applies justification as defined by --sub-justify on ASS subti‐
4469 tles if --sub-ass-override is not set to no. Default: no.
4470 --sub-shadow-color=<color>
4472 See --sub-color. Color used for sub text shadow.
4473 NOTE:
4475 ignored when --sub-back-color is specified (or more exactly:
4476 when that option is not set to completely transparent).
4477 --sub-shadow-offset=<size>
4479 Displacement of the sub text shadow in scaled pixels (see
4480 --sub-font-size for details). A value of 0 disables shadows.
4481 Default: 0.
4483 --sub-spacing=<size>
4485 Horizontal sub font spacing in scaled pixels (see
4486 --sub-font-size for details). This value is added to the normal
4487 letter spacing. Negative values are allowed.
4488 Default: 0.
4490 --sub-filter-sdh=<yes|no>
4492 Applies filter removing subtitle additions for the deaf or
4493 hard-of-hearing (SDH). This is intended for English, but may in
4494 part work for other languages too. The intention is that it can
4495 be always enabled so may not remove all parts added. It removes
4496 speaker labels (like MAN:), upper case text in parentheses and
4497 any text in brackets.
4498 Default: no.
4500 --sub-filter-sdh-harder=<yes|no>
4502 Do harder SDH filtering (if enabled by --sub-filter-sdh). Will
4503 also remove speaker labels and text within parentheses using
4504 both lower and upper case letters.
4505 Default: no.
4507 --sub-filter-regex-...=...
4509 Set a list of regular expressions to match on text subtitles,
4510 and remove any lines that match (default: empty). This is a
4511 string list option. See List Options for details. Normally, you
4512 should use --sub-filter-regex-append=<regex>, where each option
4513 use will append a new regular expression, without having to
4514 fight escaping problems.
4515 List items are matched in order. If a regular expression
4517 matches, the process is stopped, and the subtitle line is dis‐
4518 carded. The text matched against is, by default, the Text field
4519 of ASS events (if the subtitle format is different, it is always
4520 converted). This may include formatting tags. Matching is
4521 case-insensitive, but how this is done depends on the libc, and
4522 most likely works in ASCII only. It does not work on bitmap/im‐
4523 age subtitles. Unavailable on inferior OSes (requires POSIX
4524 regex support).
4525 Example
4527 --sub-filter-regex-append=opensubtitles\.org filters
4529 some ads.
4530 Technically, using a list for matching is redundant, since you
4532 could just use a single combined regular expression. But it
4533 helps with diagnosis, ease of use, and temporarily disabling or
4534 enabling individual filters.
4535 WARNING:
4537 This is experimental. The semantics most likely will change,
4538 and if you use this, you should be prepared to update the op‐
4539 tion later. Ideas include replacing the regexes with a very
4540 primitive and small subset of sed, or some method to control
4541 case-sensitivity.
4542 --sub-filter-jsre-...=...
4544 Same as --sub-filter-regex but with JavaScript regular expres‐
4545 sions. Shares/affected-by all --sub-filter-regex-* control op‐
4546 tions (see below), and also experimental. Requires only Java‐
4547 Script support.
4548 --sub-filter-regex-plain=<yes|no>
4550 Whether to first convert the ASS "Text" field to plain-text (de‐
4551 fault: no). This strips ASS tags and applies ASS directives,
4552 like \N to new-line. If the result is multi-line then the reg‐
4553 exp anchors ^ and $ match each line, but still any match dis‐
4554 cards all lines.
4555 --sub-filter-regex-warn=<yes|no>
4557 Log dropped lines with warning log level, instead of verbose
4558 (default: no). Helpful for testing.
4559 --sub-filter-regex-enable=<yes|no>
4561 Whether to enable regex filtering (default: yes). Note that if
4562 no regexes are added to the --sub-filter-regex list, setting
4563 this option to yes has no effect. It's meant to easily disable
4564 or enable filtering temporarily.
4565 --sub-create-cc-track=<yes|no>
4567 For every video stream, create a closed captions track (default:
4568 no). The only purpose is to make the track available for selec‐
4569 tion at the start of playback, instead of creating it lazily.
4570 This applies only to ATSC A53 Part 4 Closed Captions (displayed
4571 by mpv as subtitle tracks using the codec eia_608). The CC track
4572 is marked "default" and selected according to the normal subti‐
4573 tle track selection rules. You can then use --sid to explicitly
4574 select the correct track too.
4575 If the video stream contains no closed captions, or if no video
4577 is being decoded, the CC track will remain empty and will not
4578 show any text.
4579 --sub-font-provider=<auto|none|fontconfig>
4581 Which libass font provider backend to use (default: auto). auto
4582 will attempt to use the native font provider: fontconfig on
4583 Linux, CoreText on macOS, DirectWrite on Windows. fontconfig
4584 forces fontconfig, if libass was built with support (if not, it
4585 behaves like none).
4586 The none font provider effectively disables system fonts. It
4588 will still attempt to use embedded fonts (unless --embedded‐
4589 fonts=no is set; this is the same behavior as with all other
4590 font providers), subfont.ttf if provided, and fonts in the
4591 fonts sub-directory if provided. (The fallback is more strict
4592 than that of other font providers, and if a font name does not
4593 match, it may prefer not to render any text that uses the miss‐
4594 ing font.)
4595 Window
4597 --title=<string>
4598 Set the window title. This is used for the video window, and if
4599 possible, also sets the audio stream title.
4600 Properties are expanded. (See Property Expansion.)
4602 WARNING:
4604 There is a danger of this causing significant CPU usage, de‐
4605 pending on the properties used. Changing the window title is
4606 often a slow operation, and if the title changes every frame,
4607 playback can be ruined.
4608 --screen=<default|0-32>
4610 In multi-monitor configurations (i.e. a single desktop that
4611 spans across multiple displays), this option tells mpv which
4612 screen to display the video on.
4613 Note (X11)
4615 This option does not work properly with all window
4617 managers. In these cases, you can try to use --geome‐
4618 try to position the window explicitly. It's also pos‐
4619 sible that the window manager provides native features
4620 to control which screens application windows should
4621 use.
4622 See also --fs-screen.
4624 --screen-name=<string>
4626 In multi-monitor configurations, this option tells mpv which
4627 screen to display the video on based on the screen name from the
4628 video backend. The same caveats in the --screen option also ap‐
4629 ply here. This option is ignored and does nothing if --screen is
4630 explicitly set.
4631 --fullscreen, --fs
4633 Fullscreen playback.
4634 --fs-screen=<all|current|0-32>
4636 In multi-monitor configurations (i.e. a single desktop that
4637 spans across multiple displays), this option tells mpv which
4638 screen to go fullscreen to. If current is used mpv will fall‐
4639 back on what the user provided with the screen option.
4640 Note (X11)
4642 This option works properly only with window managers
4644 which understand the EWMH _NET_WM_FULLSCREEN_MONITORS
4645 hint.
4646 Note (macOS)
4648 all does not work on macOS and will behave like cur‐
4650 rent.
4651 See also --screen.
4653 --fs-screen-name=<string>
4655 In multi-monitor configurations, this option tells mpv which
4656 screen to go fullscreen to based on the screen name from the
4657 video backend. The same caveats in the --fs-screen option also
4658 apply here. This option is ignored and does nothing if
4659 --fs-screen is explicitly set.
4660 --keep-open=<yes|no|always>
4662 Do not terminate when playing or seeking beyond the end of the
4663 file, and there is no next file to be played (and --loop is not
4664 used). Instead, pause the player. When trying to seek beyond
4665 end of the file, the player will attempt to seek to the last
4666 frame.
4667 Normally, this will act like set pause yes on EOF, unless the
4669 --keep-open-pause=no option is set.
4670 The following arguments can be given:
4672 no If the current file ends, go to the next file or termi‐
4674 nate. (Default.)
4675 yes Don't terminate if the current file is the last playlist
4677 entry. Equivalent to --keep-open without arguments.
4678 always Like yes, but also applies to files before the last
4680 playlist entry. This means playback will never automati‐
4681 cally advance to the next file.
4682 NOTE:
4684 This option is not respected when using --frames. Explicitly
4685 skipping to the next file if the binding uses force will ter‐
4686 minate playback as well.
4687 Also, if errors or unusual circumstances happen, the player
4689 can quit anyway.
4690 Since mpv 0.6.0, this doesn't pause if there is a next file in
4692 the playlist, or the playlist is looped. Approximately, this
4693 will pause when the player would normally exit, but in practice
4694 there are corner cases in which this is not the case (e.g. mpv
4695 --keep-open file.mkv /dev/null will play file.mkv normally, then
4696 fail to open /dev/null, then exit). (In mpv 0.8.0, always was
4697 introduced, which restores the old behavior.)
4698 --keep-open-pause=<yes|no>
4700 If set to no, instead of pausing when --keep-open is active,
4701 just stop at end of file and continue playing forward when you
4702 seek backwards until end where it stops again. Default: yes.
4703 --image-display-duration=<seconds|inf>
4705 If the current file is an image, play the image for the given
4706 amount of seconds (default: 1). inf means the file is kept open
4707 forever (until the user stops playback manually).
4708 Unlike --keep-open, the player is not paused, but simply contin‐
4710 ues playback until the time has elapsed. (It should not use any
4711 resources during "playback".)
4712 This affects image files, which are defined as having only 1
4714 video frame and no audio. The player may recognize certain
4715 non-images as images, for example if --length is used to reduce
4716 the length to 1 frame, or if you seek to the last frame.
4717 This option does not affect the framerate used for mf:// or
4719 --merge-files. For that, use --mf-fps instead.
4720 Setting --image-display-duration hides the OSC and does not
4722 track playback time on the command-line output, and also does
4723 not duplicate the image frame when encoding. To force the player
4724 into "dumb mode" and actually count out seconds, or to duplicate
4725 the image when encoding, you need to use --demuxer=lavf --de‐
4726 muxer-lavf-o=loop=1, and use --length or --frames to stop after
4727 a particular time.
4728 --force-window=<yes|no|immediate>
4730 Create a video output window even if there is no video. This can
4731 be useful when pretending that mpv is a GUI application. Cur‐
4732 rently, the window always has the size 640x480, and is subject
4733 to --geometry, --autofit, and similar options.
4734 WARNING:
4736 The window is created only after initialization (to make sure
4737 default window placement still works if the video size is
4738 different from the --force-window default window size). This
4739 can be a problem if initialization doesn't work perfectly,
4740 such as when opening URLs with bad network connection, or
4741 opening broken video files. The immediate mode can be used to
4742 create the window always on program start, but this may cause
4743 other issues.
4744 --taskbar-progress, --no-taskbar-progress
4746 (Windows only) Enable/disable playback progress rendering in
4747 taskbar (Windows 7 and above).
4748 Enabled by default.
4750 --snap-window
4752 (Windows only) Snap the player window to screen edges.
4753 --ontop
4755 Makes the player window stay on top of other windows.
4756 On Windows, if combined with fullscreen mode, this causes mpv to
4758 be treated as exclusive fullscreen window that bypasses the
4759 Desktop Window Manager.
4760 --ontop-level=<window|system|desktop|level>
4762 (macOS only) Sets the level of an ontop window (default: win‐
4763 dow).
4764 window On top of all other windows.
4766 system On top of system elements like Taskbar, Menubar and Dock.
4768 desktop
4770 On top of the Dekstop behind windows and Desktop icons.
4771 level A level as integer.
4773 --focus-on-open, --no-focus-on-open
4775 (macOS only) Focus the video window on creation and makes it the
4776 front most window. This is on by default.
4777 --border, --no-border
4779 Play video with window border and decorations. Since this is on
4780 by default, use --no-border to disable the standard window deco‐
4781 rations.
4782 --on-all-workspaces
4784 (X11 and macOS only) Show the video window on all virtual desk‐
4785 tops.
4786 --geometry=<[W[xH]][+-x+-y][/WS]>, --geometry=<x:y>
4788 Adjust the initial window position or size. W and H set the win‐
4789 dow size in pixels. x and y set the window position, measured in
4790 pixels from the top-left corner of the screen to the top-left
4791 corner of the image being displayed. If a percentage sign (%) is
4792 given after the argument, it turns the value into a percentage
4793 of the screen size in that direction. Positions are specified
4794 similar to the standard X11 --geometry option format, in which
4795 e.g. +10-50 means "place 10 pixels from the left border and 50
4796 pixels from the lower border" and "--20+-10" means "place 20
4797 pixels beyond the right and 10 pixels beyond the top border". A
4798 trailing / followed by an integer denotes on which workspace
4799 (virtual desktop) the window should appear (X11 only).
4800 If an external window is specified using the --wid option, this
4802 option is ignored.
4803 The coordinates are relative to the screen given with --screen
4805 for the video output drivers that fully support --screen.
4806 NOTE:
4808 Generally only supported by GUI VOs. Ignored for encoding.
4809 Note (X11)
4811 This option does not work properly with all window
4813 managers.
4814 Examples
4816 50:40 Places the window at x=50, y=40.
4818 50%:50%
4820 Places the window in the middle of the screen.
4821 100%:100%
4823 Places the window at the bottom right corner of the
4824 screen.
4825 50% Sets the window width to half the screen width. Window
4827 height is set so that the window has the video aspect
4828 ratio.
4829 50%x50%
4831 Forces the window width and height to half the screen
4832 width and height. Will show black borders to compen‐
4833 sate for the video aspect ratio (with most VOs and
4834 without --no-keepaspect).
4835 50%+10+10/2
4837 Sets the window to half the screen widths, and posi‐
4838 tions it 10 pixels below/left of the top left corner
4839 of the screen, on the second workspace.
4840 See also --autofit and --autofit-larger for fitting the window
4842 into a given size without changing aspect ratio.
4843 --autofit=<[W[xH]]>
4845 Set the initial window size to a maximum size specified by WxH,
4846 without changing the window's aspect ratio. The size is measured
4847 in pixels, or if a number is followed by a percentage sign (%),
4848 in percents of the screen size.
4849 This option never changes the aspect ratio of the window. If the
4851 aspect ratio mismatches, the window's size is reduced until it
4852 fits into the specified size.
4853 Window position is not taken into account, nor is it modified by
4855 this option (the window manager still may place the window dif‐
4856 ferently depending on size). Use --geometry to change the window
4857 position. Its effects are applied after this option.
4858 See --geometry for details how this is handled with multi-moni‐
4860 tor setups.
4861 Use --autofit-larger instead if you just want to limit the maxi‐
4863 mum size of the window, rather than always forcing a window
4864 size.
4865 Use --geometry if you want to force both window width and height
4867 to a specific size.
4868 NOTE:
4870 Generally only supported by GUI VOs. Ignored for encoding.
4871 Examples
4873 70% Make the window width 70% of the screen size, keeping
4875 aspect ratio.
4876 1000 Set the window width to 1000 pixels, keeping aspect
4878 ratio.
4879 70%x60%
4881 Make the window as large as possible, without being
4882 wider than 70% of the screen width, or higher than 60%
4883 of the screen height.
4884 --autofit-larger=<[W[xH]]>
4886 This option behaves exactly like --autofit, except the window
4887 size is only changed if the window would be larger than the
4888 specified size.
4889 Example
4891 90%x80%
4893 If the video is larger than 90% of the screen width or
4894 80% of the screen height, make the window smaller un‐
4895 til either its width is 90% of the screen, or its
4896 height is 80% of the screen.
4897 --autofit-smaller=<[W[xH]]>
4899 This option behaves exactly like --autofit, except that it sets
4900 the minimum size of the window (just as --autofit-larger sets
4901 the maximum).
4902 Example
4904 500x500
4906 Make the window at least 500 pixels wide and 500 pix‐
4907 els high (depending on the video aspect ratio, the
4908 width or height will be larger than 500 in order to
4909 keep the aspect ratio the same).
4910 --window-scale=<factor>
4912 Resize the video window to a multiple (or fraction) of the video
4913 size. This option is applied before --autofit and other options
4914 are applied (so they override this option).
4915 For example, --window-scale=0.5 would show the window at half
4917 the video size.
4918 --window-minimized=<yes|no>
4920 Whether the video window is minimized or not. Setting this will
4921 minimize, or unminimize, the video window if the current VO sup‐
4922 ports it. Note that some VOs may support minimization while not
4923 supporting unminimization (eg: Wayland).
4924 Whether this option and --window-maximized work on program start
4926 or at runtime, and whether they're (at runtime) updated to re‐
4927 flect the actual window state, heavily depends on the VO and the
4928 windowing system. Some VOs simply do not implement them or parts
4929 of them, while other VOs may be restricted by the windowing sys‐
4930 tems (especially Wayland).
4931 --window-maximized=<yes|no>
4933 Whether the video window is maximized or not. Setting this will
4934 maximize, or unmaximize, the video window if the current VO sup‐
4935 ports it. See --window-minimized for further remarks.
4936 --cursor-autohide=<number|no|always>
4938 Make mouse cursor automatically hide after given number of mil‐
4939 liseconds. no will disable cursor autohide. always means the
4940 cursor will stay hidden.
4941 --cursor-autohide-fs-only
4943 If this option is given, the cursor is always visible in win‐
4944 dowed mode. In fullscreen mode, the cursor is shown or hidden
4945 according to --cursor-autohide.
4946 --no-fixed-vo, --fixed-vo
4948 --no-fixed-vo enforces closing and reopening the video window
4949 for multiple files (one (un)initialization for each file).
4950 --force-rgba-osd-rendering
4952 Change how some video outputs render the OSD and text subtitles.
4953 This does not change appearance of the subtitles and only has
4954 performance implications. For VOs which support native ASS ren‐
4955 dering (like gpu, vdpau, direct3d), this can be slightly faster
4956 or slower, depending on GPU drivers and hardware. For other VOs,
4957 this just makes rendering slower.
4958 --force-window-position
4960 Forcefully move mpv's video output window to default location
4961 whenever there is a change in video parameters, video stream or
4962 file. This used to be the default behavior. Currently only af‐
4963 fects X11 VOs.
4964 --no-keepaspect, --keepaspect
4966 --no-keepaspect will always stretch the video to window size,
4967 and will disable the window manager hints that force the window
4968 aspect ratio. (Ignored in fullscreen mode.)
4969 --no-keepaspect-window, --keepaspect-window
4971 --keepaspect-window (the default) will lock the window size to
4972 the video aspect. --no-keepaspect-window disables this behavior,
4973 and will instead add black bars if window aspect and video as‐
4974 pect mismatch. Whether this actually works depends on the VO
4975 backend. (Ignored in fullscreen mode.)
4976 --monitoraspect=<ratio>
4978 Set the aspect ratio of your monitor or TV screen. A value of 0
4979 disables a previous setting (e.g. in the config file). Overrides
4980 the --monitorpixelaspect setting if enabled.
4981 See also --monitorpixelaspect and --video-aspect-override.
4983 Examples
4985 • --monitoraspect=4:3 or --monitoraspect=1.3333
4987 • --monitoraspect=16:9 or --monitoraspect=1.7777
4989 --hidpi-window-scale, --no-hidpi-window-scale
4991 (macOS, Windows, X11, and Wayland only) Scale the window size
4992 according to the backing scale factor (default: yes). On regu‐
4993 lar HiDPI resolutions the window opens with double the size but
4994 appears as having the same size as on non-HiDPI resolutions.
4995 This is enabled by default on macOS.
4996 --native-fs, --no-native-fs
4998 (macOS only) Uses the native fullscreen mechanism of the OS (de‐
4999 fault: yes).
5000 --monitorpixelaspect=<ratio>
5002 Set the aspect of a single pixel of your monitor or TV screen
5003 (default: 1). A value of 1 means square pixels (correct for (al‐
5004 most?) all LCDs). See also --monitoraspect and --video-as‐
5005 pect-override.
5006 --stop-screensaver=<yes|no|always>
5008 Turns off the screensaver (or screen blanker and similar mecha‐
5009 nisms) at startup and turns it on again on exit (default: yes).
5010 When using yes, the screensaver will re-enable when playback is
5011 not active. always will always disable the screensaver. Note
5012 that stopping the screensaver is only possible if a video output
5013 is available (i.e. there is an open mpv window).
5014 This is not supported on all video outputs or platforms. Some‐
5016 times it is implemented, but does not work (especially with
5017 Linux "desktops"). Read the Disabling Screensaver section very
5018 carefully.
5019 --wid=<ID>
5021 This tells mpv to attach to an existing window. If a VO is se‐
5022 lected that supports this option, it will use that window for
5023 video output. mpv will scale the video to the size of this win‐
5024 dow, and will add black bars to compensate if the aspect ratio
5025 of the video is different.
5026 On X11, the ID is interpreted as a Window on X11. Unlike
5028 MPlayer/mplayer2, mpv always creates its own window, and sets
5029 the wid window as parent. The window will always be resized to
5030 cover the parent window fully. The value 0 is interpreted spe‐
5031 cially, and mpv will draw directly on the root window.
5032 On win32, the ID is interpreted as HWND. Pass it as value cast
5034 to intptr_t. mpv will create its own window, and set the wid
5035 window as parent, like with X11.
5036 On macOS/Cocoa, the ID is interpreted as NSView*. Pass it as
5038 value cast to intptr_t. mpv will create its own sub-view. Be‐
5039 cause macOS does not support window embedding of foreign pro‐
5040 cesses, this works only with libmpv, and will crash when used
5041 from the command line.
5042 On Android, the ID is interpreted as android.view.Surface. Pass
5044 it as a value cast to intptr_t. Use with --vo=mediacodec_embed
5045 and --hwdec=mediacodec for direct rendering using MediaCodec, or
5046 with --vo=gpu --gpu-context=android (with or without --hwdec=me‐
5047 diacodec).
5048 --no-window-dragging
5050 Don't move the window when clicking on it and moving the mouse
5051 pointer.
5052 --x11-name
5054 Set the window class name for X11-based video output methods.
5055 --x11-netwm=<yes|no|auto>
5057 (X11 only) Control the use of NetWM protocol features.
5058 This may or may not help with broken window managers. This pro‐
5060 vides some functionality that was implemented by the now removed
5061 --fstype option. Actually, it is not known to the developers to
5062 which degree this option was needed, so feedback is welcome.
5063 Specifically, yes will force use of NetWM fullscreen support,
5065 even if not advertised by the WM. This can be useful for WMs
5066 that are broken on purpose, like XMonad. (XMonad supposedly
5067 doesn't advertise fullscreen support, because Flash uses it. Ap‐
5068 parently, applications which want to use fullscreen anyway are
5069 supposed to either ignore the NetWM support hints, or provide a
5070 workaround. Shame on XMonad for deliberately breaking X proto‐
5071 cols (as if X isn't bad enough already).
5072 By default, NetWM support is autodetected (auto).
5074 This option might be removed in the future.
5076 --x11-bypass-compositor=<yes|no|fs-only|never>
5078 If set to yes, then ask the compositor to unredirect the mpv
5079 window (default: fs-only). This uses the _NET_WM_BYPASS_COMPOSI‐
5080 TOR hint.
5081 fs-only asks the window manager to disable the compositor only
5083 in fullscreen mode.
5084 no sets _NET_WM_BYPASS_COMPOSITOR to 0, which is the default
5086 value as declared by the EWMH specification, i.e. no change is
5087 done.
5088 never asks the window manager to never disable the compositor.
5090 --x11-present=<no|auto|yes>
5092 Whether or not to use presentation statistics from X11's presen‐
5093 tation extension (default: auto).
5094 mpv asks X11 for present events which it then may use for more
5096 accurate frame presentation. This only has an effect if
5097 --video-sync=display-... is being used.
5098 The auto option enumerates XRandr providers for autodetection.
5100 If amd, radeon, intel, or nouveau (the standard x86 Mesa driv‐
5101 ers) is found and nvidia is NOT found, presentation feedback is
5102 enabled. Other drivers are not assumed to work, so they are not
5103 enabled automatically.
5104 yes or no can still be passed regardless to enable/disable this
5106 mechanism in case there is good/bad behavior with whatever your
5107 combination of hardware/drivers/etc. happens to be.
5108 Disc Devices
5110 --cdrom-device=<path>
5111 Specify the CD-ROM device (default: /dev/cdrom).
5112 --dvd-device=<path>
5114 Specify the DVD device or .iso filename (default: /dev/dvd). You
5115 can also specify a directory that contains files previously
5116 copied directly from a DVD (with e.g. vobcopy).
5117 Example
5119 mpv dvd:// --dvd-device=/path/to/dvd/
5121 --bluray-device=<path>
5123 (Blu-ray only) Specify the Blu-ray disc location. Must be a di‐
5124 rectory with Blu-ray structure.
5125 Example
5127 mpv bd:// --bluray-device=/path/to/bd/
5129 --cdda-...
5131 These options can be used to tune the CD Audio reading feature
5132 of mpv.
5133 --cdda-speed=<value>
5135 Set CD spin speed.
5136 --cdda-paranoia=<0-2>
5138 Set paranoia level. Values other than 0 seem to break playback
5139 of anything but the first track.
5140 0 disable checking (default)
5142 1 overlap checking only
5144 2 full data correction and verification
5146 --cdda-sector-size=<value>
5148 Set atomic read size.
5149 --cdda-overlap=<value>
5151 Force minimum overlap search during verification to <value> sec‐
5152 tors.
5153 --cdda-toc-bias
5155 Assume that the beginning offset of track 1 as reported in the
5156 TOC will be addressed as LBA 0. Some discs need this for getting
5157 track boundaries correctly.
5158 --cdda-toc-offset=<value>
5160 Add <value> sectors to the values reported when addressing
5161 tracks. May be negative.
5162 --cdda-skip=<yes|no>
5164 (Never) accept imperfect data reconstruction.
5165 --cdda-cdtext=<yes|no>
5167 Print CD text. This is disabled by default, because it ruins
5168 performance with CD-ROM drives for unknown reasons.
5169 --dvd-speed=<speed>
5171 Try to limit DVD speed (default: 0, no change). DVD base speed
5172 is 1385 kB/s, so an 8x drive can read at speeds up to 11080
5173 kB/s. Slower speeds make the drive more quiet. For watching
5174 DVDs, 2700 kB/s should be quiet and fast enough. mpv resets the
5175 speed to the drive default value on close. Values of at least
5176 100 mean speed in kB/s. Values less than 100 mean multiples of
5177 1385 kB/s, i.e. --dvd-speed=8 selects 11080 kB/s.
5178 NOTE:
5180 You need write access to the DVD device to change the speed.
5181 --dvd-angle=<ID>
5183 Some DVDs contain scenes that can be viewed from multiple an‐
5184 gles. This option tells mpv which angle to use (default: 1).
5185 Equalizer
5187 --brightness=<-100-100>
5188 Adjust the brightness of the video signal (default: 0). Not sup‐
5189 ported by all video output drivers.
5190 --contrast=<-100-100>
5192 Adjust the contrast of the video signal (default: 0). Not sup‐
5193 ported by all video output drivers.
5194 --saturation=<-100-100>
5196 Adjust the saturation of the video signal (default: 0). You can
5197 get grayscale output with this option. Not supported by all
5198 video output drivers.
5199 --gamma=<-100-100>
5201 Adjust the gamma of the video signal (default: 0). Not supported
5202 by all video output drivers.
5203 --hue=<-100-100>
5205 Adjust the hue of the video signal (default: 0). You can get a
5206 colored negative of the image with this option. Not supported by
5207 all video output drivers.
5208 Demuxer
5210 --demuxer=<[+]name>
5211 Force demuxer type. Use a '+' before the name to force it; this
5212 will skip some checks. Give the demuxer name as printed by --de‐
5213 muxer=help.
5214 --demuxer-lavf-analyzeduration=<value>
5216 Maximum length in seconds to analyze the stream properties.
5217 --demuxer-lavf-probe-info=<yes|no|auto|nostreams>
5219 Whether to probe stream information (default: auto). Techni‐
5220 cally, this controls whether libavformat's avfor‐
5221 mat_find_stream_info() function is called. Usually it's safer to
5222 call it, but it can also make startup slower.
5223 The auto choice (the default) tries to skip this for a few
5225 know-safe whitelisted formats, while calling it for everything
5226 else.
5227 The nostreams choice only calls it if and only if the file seems
5229 to contain no streams after opening (helpful in cases when call‐
5230 ing the function is needed to detect streams at all, such as
5231 with FLV files).
5232 --demuxer-lavf-probescore=<1-100>
5234 Minimum required libavformat probe score. Lower values will re‐
5235 quire less data to be loaded (makes streams start faster), but
5236 makes file format detection less reliable. Can be used to force
5237 auto-detected libavformat demuxers, even if libavformat consid‐
5238 ers the detection not reliable enough. (Default: 26.)
5239 --demuxer-lavf-allow-mimetype=<yes|no>
5241 Allow deriving the format from the HTTP MIME type (default:
5242 yes). Set this to no in case playing things from HTTP mysteri‐
5243 ously fails, even though the same files work from local disk.
5244 This is default in order to reduce latency when opening HTTP
5246 streams.
5247 --demuxer-lavf-format=<name>
5249 Force a specific libavformat demuxer.
5250 --demuxer-lavf-hacks=<yes|no>
5252 By default, some formats will be handled differently from other
5253 formats by explicitly checking for them. Most of these compen‐
5254 sate for weird or imperfect behavior from libavformat demuxers.
5255 Passing no disables these. For debugging and testing only.
5256 --demuxer-lavf-o=<key>=<value>[,<key>=<value>[,...]]
5258 Pass AVOptions to libavformat demuxer.
5259 Note, a patch to make the o= unneeded and pass all unknown op‐
5261 tions through the AVOption system is welcome. A full list of
5262 AVOptions can be found in the FFmpeg manual. Note that some op‐
5263 tions may conflict with mpv options.
5264 This is a key/value list option. See List Options for details.
5266 Example
5268 --demuxer-lavf-o=fflags=+ignidx
5270 --demuxer-lavf-probesize=<value>
5272 Maximum amount of data to probe during the detection phase. In
5273 the case of MPEG-TS this value identifies the maximum number of
5274 TS packets to scan.
5275 --demuxer-lavf-buffersize=<value>
5277 Size of the stream read buffer allocated for libavformat in
5278 bytes (default: 32768). Lowering the size could lower latency.
5279 Note that libavformat might reallocate the buffer internally, or
5280 not fully use all of it.
5281 --demuxer-lavf-linearize-timestamps=<yes|no|auto>
5283 Attempt to linearize timestamp resets in demuxed streams (de‐
5284 fault: auto). This was tested only for single audio streams.
5285 It's unknown whether it works correctly for video (but likely
5286 won't). Note that the implementation is slightly incorrect ei‐
5287 ther way, and will introduce a discontinuity by about 1 codec
5288 frame size.
5289 The auto mode enables this for OGG audio stream. This covers the
5291 common and annoying case of OGG web radio streams. Some of these
5292 will reset timestamps to 0 every time a new song begins. This
5293 breaks the mpv seekable cache, which can't deal with timestamp
5294 resets. Note that FFmpeg/libavformat's seeking API can't deal
5295 with this either; it's likely that if this option breaks this
5296 even more, while if it's disabled, you can at least seek within
5297 the first song in the stream. Well, you won't get anything use‐
5298 ful either way if the seek is outside of mpv's cache.
5299 --demuxer-lavf-propagate-opts=<yes|no>
5301 Propagate FFmpeg-level options to recursively opened connections
5302 (default: yes). This is needed because FFmpeg will apply these
5303 settings to nested AVIO contexts automatically. On the other
5304 hand, this could break in certain situations - it's the FFmpeg
5305 API, you just can't win.
5306 This affects in particular the --timeout option and anything
5308 passed with --demuxer-lavf-o.
5309 If this option is deemed unnecessary at some point in the fu‐
5311 ture, it will be removed without notice.
5312 --demuxer-mkv-subtitle-preroll=<yes|index|no>, --mkv-subtitle-preroll
5314 Try harder to show embedded soft subtitles when seeking some‐
5315 where. Normally, it can happen that the subtitle at the seek
5316 target is not shown due to how some container file formats are
5317 designed. The subtitles appear only if seeking before or exactly
5318 to the position a subtitle first appears. To make this worse,
5319 subtitles are often timed to appear a very small amount before
5320 the associated video frame, so that seeking to the video frame
5321 typically does not demux the subtitle at that position.
5322 Enabling this option makes the demuxer start reading data a bit
5324 before the seek target, so that subtitles appear correctly. Note
5325 that this makes seeking slower, and is not guaranteed to always
5326 work. It only works if the subtitle is close enough to the seek
5327 target.
5328 Works with the internal Matroska demuxer only. Always enabled
5330 for absolute and hr-seeks, and this option changes behavior with
5331 relative or imprecise seeks only.
5332 You can use the --demuxer-mkv-subtitle-preroll-secs option to
5334 specify how much data the demuxer should pre-read at most in or‐
5335 der to find subtitle packets that may overlap. Setting this to 0
5336 will effectively disable this preroll mechanism. Setting a very
5337 large value can make seeking very slow, and an extremely large
5338 value would completely reread the entire file from start to seek
5339 target on every seek - seeking can become slower towards the end
5340 of the file. The details are messy, and the value is actually
5341 rounded down to the cluster with the previous video keyframe.
5342 Some files, especially files muxed with newer mkvmerge versions,
5344 have information embedded that can be used to determine what
5345 subtitle packets overlap with a seek target. In these cases, mpv
5346 will reduce the amount of data read to a minimum. (Although it
5347 will still read all data between the cluster that contains the
5348 first wanted subtitle packet, and the seek target.) If the index
5349 choice (which is the default) is specified, then prerolling will
5350 be done only if this information is actually available. If this
5351 method is used, the maximum amount of data to skip can be addi‐
5352 tionally controlled by --demuxer-mkv-subtitle-preroll-secs-index
5353 (it still uses the value of the option without -index if that is
5354 higher).
5355 See also --hr-seek-demuxer-offset option. This option can
5357 achieve a similar effect, but only if hr-seek is active. It
5358 works with any demuxer, but makes seeking much slower, as it has
5359 to decode audio and video data instead of just skipping over it.
5360 --mkv-subtitle-preroll is a deprecated alias.
5362 --demuxer-mkv-subtitle-preroll-secs=<value>
5364 See --demuxer-mkv-subtitle-preroll.
5365 --demuxer-mkv-subtitle-preroll-secs-index=<value>
5367 See --demuxer-mkv-subtitle-preroll.
5368 --demuxer-mkv-probe-start-time=<yes|no>
5370 Check the start time of Matroska files (default: yes). This sim‐
5371 ply reads the first cluster timestamps and assumes it is the
5372 start time. Technically, this also reads the first timestamp,
5373 which may increase latency by one frame (which may be relevant
5374 for live streams).
5375 --demuxer-mkv-probe-video-duration=<yes|no|full>
5377 When opening the file, seek to the end of it, and check what
5378 timestamp the last video packet has, and report that as file du‐
5379 ration. This is strictly for compatibility with Haali only. In
5380 this mode, it's possible that opening will be slower (especially
5381 when playing over http), or that behavior with broken files is
5382 much worse. So don't use this option.
5383 The yes mode merely uses the index and reads a small number of
5385 blocks from the end of the file. The full mode actually tra‐
5386 verses the entire file and can make a reliable estimate even
5387 without an index present (such as partial files).
5388 --demuxer-rawaudio-channels=<value>
5390 Number of channels (or channel layout) if --demuxer=rawaudio is
5391 used (default: stereo).
5392 --demuxer-rawaudio-format=<value>
5394 Sample format for --demuxer=rawaudio (default: s16le). Use
5395 --demuxer-rawaudio-format=help to get a list of all formats.
5396 --demuxer-rawaudio-rate=<value>
5398 Sample rate for --demuxer=rawaudio (default: 44 kHz).
5399 --demuxer-rawvideo-fps=<value>
5401 Rate in frames per second for --demuxer=rawvideo (default:
5402 25.0).
5403 --demuxer-rawvideo-w=<value>, --demuxer-rawvideo-h=<value>
5405 Image dimension in pixels for --demuxer=rawvideo.
5406 Example
5408 Play a raw YUV sample:
5410 mpv sample-720x576.yuv --demuxer=rawvideo \
5412 --demuxer-rawvideo-w=720 --demuxer-rawvideo-h=576
5413 --demuxer-rawvideo-format=<value>
5415 Color space (fourcc) in hex or string for --demuxer=rawvideo
5416 (default: YV12).
5417 --demuxer-rawvideo-mp-format=<value>
5419 Color space by internal video format for --demuxer=rawvideo. Use
5420 --demuxer-rawvideo-mp-format=help for a list of possible for‐
5421 mats.
5422 --demuxer-rawvideo-codec=<value>
5424 Set the video codec instead of selecting the rawvideo codec when
5425 using --demuxer=rawvideo. This uses the same values as codec
5426 names in --vd (but it does not accept decoder names).
5427 --demuxer-rawvideo-size=<value>
5429 Frame size in bytes when using --demuxer=rawvideo.
5430 --demuxer-cue-codepage=<codepage>
5432 Specify the CUE sheet codepage. (See --sub-codepage for de‐
5433 tails.)
5434 --demuxer-max-bytes=<bytesize>
5436 This controls how much the demuxer is allowed to buffer ahead.
5437 The demuxer will normally try to read ahead as much as neces‐
5438 sary, or as much is requested with --demuxer-readahead-secs. The
5439 option can be used to restrict the maximum readahead. This lim‐
5440 its excessive readahead in case of broken files or desynced
5441 playback. The demuxer will stop reading additional packets as
5442 soon as one of the limits is reached. (The limits still can be
5443 slightly overstepped due to technical reasons.)
5444 Set these limits higher if you get a packet queue overflow warn‐
5446 ing, and you think normal playback would be possible with a
5447 larger packet queue.
5448 See --list-options for defaults and value range. <bytesize> op‐
5450 tions accept suffixes such as KiB and MiB.
5451 --demuxer-max-back-bytes=<bytesize>
5453 This controls how much past data the demuxer is allowed to pre‐
5454 serve. This is useful only if the cache is enabled.
5455 Unlike the forward cache, there is no control how many seconds
5457 are actually cached - it will simply use as much memory this op‐
5458 tion allows. Setting this option to 0 will strictly disable any
5459 back buffer, but this will lead to the situation that the for‐
5460 ward seek range starts after the current playback position (as
5461 it removes past packets that are seek points).
5462 If the end of the file is reached, the remaining unused forward
5464 buffer space is "donated" to the backbuffer (unless the back‐
5465 buffer size is set to 0, or --demuxer-donate-buffer is set to
5466 no). This still limits the total cache usage to the sum of the
5467 forward and backward cache, and effectively makes better use of
5468 the total allowed memory budget. (The opposite does not happen:
5469 free backward buffer is never "donated" to the forward buffer.)
5470 Keep in mind that other buffers in the player (like decoders)
5472 will cause the demuxer to cache "future" frames in the back buf‐
5473 fer, which can skew the impression about how much data the back‐
5474 buffer contains.
5475 See --list-options for defaults and value range.
5477 --demuxer-donate-buffer=<yes|no>
5479 Whether to let the back buffer use part of the forward buffer
5480 (default: yes). If set to yes, the "donation" behavior de‐
5481 scribed in the option description for --demuxer-max-back-bytes
5482 is enabled. This means the back buffer may use up memory up to
5483 the sum of the forward and back buffer options, minus the active
5484 size of the forward buffer. If set to no, the options strictly
5485 limit the forward and back buffer sizes separately.
5486 Note that if the end of the file is reached, the buffered data
5488 stays the same, even if you seek back within the cache. This is
5489 because the back buffer is only reduced when new data is read.
5490 --demuxer-seekable-cache=<yes|no|auto>
5492 Debugging option to control whether seeking can use the demuxer
5493 cache (default: auto). Normally you don't ever need to set this;
5494 the default auto does the right thing and enables cache seeking
5495 it if --cache is set to yes (or is implied yes if --cache=auto).
5496 If enabled, short seek offsets will not trigger a low level de‐
5498 muxer seek (which means for example that slow network round
5499 trips or FFmpeg seek bugs can be avoided). If a seek cannot hap‐
5500 pen within the cached range, a low level seek will be triggered.
5501 Seeking outside of the cache will start a new cached range, but
5502 can discard the old cache range if the demuxer exhibits certain
5503 unsupported behavior.
5504 The special value auto means yes in the same situation as
5506 --cache-secs is used (i.e. when the stream appears to be a net‐
5507 work stream or the stream cache is enabled).
5508 --demuxer-force-retry-on-eof=<yes|no>
5510 Whether to keep retrying making the demuxer thread read more
5511 packets each time the decoder dequeues a packet, even if the end
5512 of the file was reached (default: no). This does not really make
5513 sense, but was the default behavior in mpv 0.32.0 and earlier.
5514 This option will be silently removed after a while, and exists
5515 only to restore the old behavior for testing, in case this was
5516 actually needed somewhere. This does _not_ help with files that
5517 are being appended to (in these cases use appending://, or dis‐
5518 able the cache).
5519 --demuxer-thread=<yes|no>
5521 Run the demuxer in a separate thread, and let it prefetch a cer‐
5522 tain amount of packets (default: yes). Having this enabled leads
5523 to smoother playback, enables features like prefetching, and
5524 prevents that stuck network freezes the player. On the other
5525 hand, it can add overhead, or the background prefetching can hog
5526 CPU resources.
5527 Disabling this option is not recommended. Use it for debugging
5529 only.
5530 --demuxer-termination-timeout=<seconds>
5532 Number of seconds the player should wait to shutdown the demuxer
5533 (default: 0.1). The player will wait up to this much time before
5534 it closes the stream layer forcefully. Forceful closing usually
5535 means the network I/O is given no chance to close its connec‐
5536 tions gracefully (of course the OS can still close TCP connec‐
5537 tions properly), and might result in annoying messages being
5538 logged, and in some cases, confused remote servers.
5539 This timeout is usually only applied when loading has finished
5541 properly. If loading is aborted by the user, or in some corner
5542 cases like removing external tracks sourced from network during
5543 playback, forceful closing is always used.
5544 --demuxer-readahead-secs=<seconds>
5546 If --demuxer-thread is enabled, this controls how much the de‐
5547 muxer should buffer ahead in seconds (default: 1). As long as no
5548 packet has a timestamp difference higher than the readahead
5549 amount relative to the last packet returned to the decoder, the
5550 demuxer keeps reading.
5551 Note that enabling the cache (such as --cache=yes, or if the in‐
5553 put is considered a network stream, and --cache=auto is used),
5554 this option is mostly ignored. (--cache-secs will override this.
5555 Technically, the maximum of both options is used.)
5556 The main purpose of this option is to limit the readhead for lo‐
5558 cal playback, since a large readahead value is not overly useful
5559 in this case.
5560 (This value tends to be fuzzy, because many file formats don't
5562 store linear timestamps.)
5563 --prefetch-playlist=<yes|no>
5565 Prefetch next playlist entry while playback of the current entry
5566 is ending (default: no).
5567 This does not prefill the cache with the video data of the next
5569 URL. Prefetching video data is supported only for the current
5570 playlist entry, and depends on the demuxer cache settings (on by
5571 default). This merely opens the URL of the next playlist entry
5572 as soon the current URL is fully read.
5573 This does not work with URLs resolved by the youtube-dl wrapper,
5575 and it won't.
5576 This can give subtly wrong results if per-file options are used,
5578 or if options are changed in the time window between prefetching
5579 start and next file played.
5580 This can occasionally make wrong prefetching decisions. For ex‐
5582 ample, it can't predict whether you go backwards in the
5583 playlist, and assumes you won't edit the playlist.
5584 Highly experimental.
5586 --force-seekable=<yes|no>
5588 If the player thinks that the media is not seekable (e.g. play‐
5589 ing from a pipe, or it's an http stream with a server that
5590 doesn't support range requests), seeking will be disabled. This
5591 option can forcibly enable it. For seeks within the cache,
5592 there's a good chance of success.
5593 --demuxer-cache-wait=<yes|no>
5595 Before starting playback, read data until either the end of the
5596 file was reached, or the demuxer cache has reached maximum ca‐
5597 pacity. Only once this is done, playback starts. This intention‐
5598 ally happens before the initial seek triggered with --start.
5599 This does not change any runtime behavior after the initial
5600 caching. This option is useless if the file cannot be cached
5601 completely.
5602 --rar-list-all-volumes=<yes|no>
5604 When opening multi-volume rar files, open all volumes to create
5605 a full list of contained files (default: no). If disabled, only
5606 the archive entries whose headers are located within the first
5607 volume are listed (and thus played when opening a .rar file with
5608 mpv). Doing so speeds up opening, and the typical idiotic
5609 use-case of playing uncompressed multi-volume rar files that
5610 contain a single media file is made faster.
5611 Opening is still slow, because for unknown, idiotic, and unnec‐
5613 essary reasons libarchive opens all volumes anyway when playing
5614 the main file, even though mpv iterated no archive entries yet.
5615 Input
5617 --native-keyrepeat
5618 Use system settings for keyrepeat delay and rate, instead of
5619 --input-ar-delay and --input-ar-rate. (Whether this applies de‐
5620 pends on the VO backend and how it handles keyboard input. Does
5621 not apply to terminal input.)
5622 --input-ar-delay
5624 Delay in milliseconds before we start to autorepeat a key (0 to
5625 disable).
5626 --input-ar-rate
5628 Number of key presses to generate per second on autorepeat.
5629 --input-conf=<filename>
5631 Specify input configuration file other than the default location
5632 in the mpv configuration directory (usually ~/.config/mpv/in‐
5633 put.conf).
5634 --no-input-default-bindings
5636 Disable default-level ("weak") key bindings. These are bindings
5637 which config files like input.conf can override. It currently
5638 affects the builtin key bindings, and keys which scripts bind
5639 using mp.add_key_binding (but not mp.add_forced_key_binding be‐
5640 cause this overrides input.conf).
5641 --no-input-builtin-bindings
5643 Disable loading of built-in key bindings during start-up. This
5644 option is applied only during (lib)mpv initialization, and if
5645 used then it will not be not possible to enable them later. May
5646 be useful to libmpv clients.
5647 --input-cmdlist
5649 Prints all commands that can be bound to keys.
5650 --input-doubleclick-time=<milliseconds>
5652 Time in milliseconds to recognize two consecutive button presses
5653 as a double-click (default: 300).
5654 --input-keylist
5656 Prints all keys that can be bound to commands.
5657 --input-key-fifo-size=<2-65000>
5659 Specify the size of the FIFO that buffers key events (default:
5660 7). If it is too small, some events may be lost. The main disad‐
5661 vantage of setting it to a very large value is that if you hold
5662 down a key triggering some particularly slow command then the
5663 player may be unresponsive while it processes all the queued
5664 commands.
5665 --input-test
5667 Input test mode. Instead of executing commands on key presses,
5668 mpv will show the keys and the bound commands on the OSD. Has to
5669 be used with a dummy video, and the normal ways to quit the
5670 player will not work (key bindings that normally quit will be
5671 shown on OSD only, just like any other binding). See INPUT.CONF.
5672 --input-terminal, --no-input-terminal
5674 --no-input-terminal prevents the player from reading key events
5675 from standard input. Useful when reading data from standard in‐
5676 put. This is automatically enabled when - is found on the com‐
5677 mand line. There are situations where you have to set it manu‐
5678 ally, e.g. if you open /dev/stdin (or the equivalent on your
5679 system), use stdin in a playlist or intend to read from stdin
5680 later on via the loadfile or loadlist input commands.
5681 --input-ipc-server=<filename>
5683 Enable the IPC support and create the listening socket at the
5684 given path.
5685 On Linux and Unix, the given path is a regular filesystem path.
5687 On Windows, named pipes are used, so the path refers to the pipe
5688 namespace (\\.\pipe\<name>). If the \\.\pipe\ prefix is missing,
5689 mpv will add it automatically before creating the pipe, so --in‐
5690 put-ipc-server=/tmp/mpv-socket and --in‐
5691 put-ipc-server=\\.\pipe\tmp\mpv-socket are equivalent for IPC on
5692 Windows.
5693 See JSON IPC for details.
5695 --input-ipc-client=fd://<N>
5697 Connect a single IPC client to the given FD. This is somewhat
5698 similar to --input-ipc-server, except no socket is created, and
5699 instead the passed FD is treated like a socket connection re‐
5700 ceived from accept(). In practice, you could pass either a FD
5701 created by socketpair(), or a pipe. In both cases, you must
5702 sure the FD is actually inherited by mpv (do not set the POSIX
5703 CLOEXEC flag).
5704 The player quits when the connection is closed.
5706 This is somewhat similar to the removed --input-file option, ex‐
5708 cept it supports only integer FDs, and cannot open actual paths.
5709 Example
5711 --input-ipc-client=fd://123
5713 NOTE:
5715 Does not and will not work on Windows.
5716 WARNING:
5718 Writing to the input-ipc-server option at runtime will start
5719 another instance of an IPC client handler for the in‐
5720 put-ipc-client option, because initialization is bundled, and
5721 this thing is stupid. This is a bug. Writing to in‐
5722 put-ipc-client at runtime will start another IPC client han‐
5723 dler for the new value, without stopping the old one, even if
5724 the FD value is the same (but the string is different e.g.
5725 due to whitespace). This is not a bug.
5726 --input-gamepad=<yes|no>
5728 Enable/disable SDL2 Gamepad support. Disabled by default.
5729 --input-cursor, --no-input-cursor
5731 Permit mpv to receive pointer events reported by the video out‐
5732 put driver. Necessary to use the OSC, or to select the buttons
5733 in DVD menus. Support depends on the VO in use.
5734 --input-media-keys=<yes|no>
5736 On systems where mpv can choose between receiving media keys or
5737 letting the system handle them - this option controls whether
5738 mpv should receive them.
5739 Default: yes (except for libmpv). macOS and Windows only, be‐
5741 cause elsewhere mpv doesn't have a choice - the system decides
5742 whether to send media keys to mpv. For instance, on X11 or Way‐
5743 land, system-wide media keys are not implemented. Whether media
5744 keys work when the mpv window is focused is implementation-de‐
5745 fined.
5746 --input-right-alt-gr, --no-input-right-alt-gr
5748 (Cocoa and Windows only) Use the right Alt key as Alt Gr to pro‐
5749 duce special characters. If disabled, count the right Alt as an
5750 Alt modifier key. Enabled by default.
5751 --input-vo-keyboard=<yes|no>
5753 Disable all keyboard input on for VOs which can't participate in
5754 proper keyboard input dispatching. May not affect all VOs. Gen‐
5755 erally useful for embedding only.
5756 On X11, a sub-window with input enabled grabs all keyboard input
5758 as long as it is 1. a child of a focused window, and 2. the
5759 mouse is inside of the sub-window. It can steal away all key‐
5760 board input from the application embedding the mpv window, and
5761 on the other hand, the mpv window will receive no input if the
5762 mouse is outside of the mpv window, even though mpv has focus.
5763 Modern toolkits work around this weird X11 behavior, but naively
5764 embedding foreign windows breaks it.
5765 The only way to handle this reasonably is using the XEmbed pro‐
5767 tocol, which was designed to solve these problems. GTK provides
5768 GtkSocket, which supports XEmbed. Qt doesn't seem to provide
5769 anything working in newer versions.
5770 If the embedder supports XEmbed, input should work with default
5772 settings and with this option disabled. Note that input-de‐
5773 fault-bindings is disabled by default in libmpv as well - it
5774 should be enabled if you want the mpv default key bindings.
5775 (This option was renamed from --input-x11-keyboard.)
5777 OSD
5779 --osc, --no-osc
5780 Whether to load the on-screen-controller (default: yes).
5781 --no-osd-bar, --osd-bar
5783 Disable display of the OSD bar.
5784 You can configure this on a per-command basis in input.conf us‐
5786 ing osd- prefixes, see Input Command Prefixes. If you want to
5787 disable the OSD completely, use --osd-level=0.
5788 --osd-on-seek=<no,bar,msg,msg-bar>
5790 Set what is displayed on the OSD during seeks. The default is
5791 bar.
5792 You can configure this on a per-command basis in input.conf us‐
5794 ing osd- prefixes, see Input Command Prefixes.
5795 --osd-duration=<time>
5797 Set the duration of the OSD messages in ms (default: 1000).
5798 --osd-font=<name>
5800 Specify font to use for OSD. The default is sans-serif.
5801 Examples
5803 • --osd-font='Bitstream Vera Sans'
5805 • --osd-font='Comic Sans MS'
5807 --osd-font-size=<size>
5809 Specify the OSD font size. See --sub-font-size for details.
5810 Default: 55.
5812 --osd-msg1=<string>
5814 Show this string as message on OSD with OSD level 1 (visible by
5815 default). The message will be visible by default, and as long
5816 as no other message covers it, and the OSD level isn't changed
5817 (see --osd-level). Expands properties; see Property Expansion.
5818 --osd-msg2=<string>
5820 Similar to --osd-msg1, but for OSD level 2. If this is an empty
5821 string (default), then the playback time is shown.
5822 --osd-msg3=<string>
5824 Similar to --osd-msg1, but for OSD level 3. If this is an empty
5825 string (default), then the playback time, duration, and some
5826 more information is shown.
5827 This is used for the show-progress command (by default mapped to
5829 P), and when seeking if enabled with --osd-on-seek or by osd-
5830 prefixes in input.conf (see Input Command Prefixes).
5831 --osd-status-msg is a legacy equivalent (but with a minor dif‐
5833 ference).
5834 --osd-status-msg=<string>
5836 Show a custom string during playback instead of the standard
5837 status text. This overrides the status text used for
5838 --osd-level=3, when using the show-progress command (by default
5839 mapped to P), and when seeking if enabled with --osd-on-seek or
5840 osd- prefixes in input.conf (see Input Command Prefixes). Ex‐
5841 pands properties. See Property Expansion.
5842 This option has been replaced with --osd-msg3. The only differ‐
5844 ence is that this option implicitly includes ${osd-sym-cc}. This
5845 option is ignored if --osd-msg3 is not empty.
5846 --osd-playing-msg=<string>
5848 Show a message on OSD when playback starts. The string is ex‐
5849 panded for properties, e.g. --osd-playing-msg='file: ${file‐
5850 name}' will show the message file: followed by a space and the
5851 currently played filename.
5852 See Property Expansion.
5854 --osd-playing-msg-duration=<time>
5856 Set the duration of osd-playing-msg in ms. If this is unset,
5857 osd-playing-msg stays on screen for the duration of osd-dura‐
5858 tion.
5859 --osd-bar-align-x=<-1-1>
5861 Position of the OSD bar. -1 is far left, 0 is centered, 1 is far
5862 right. Fractional values (like 0.5) are allowed.
5863 --osd-bar-align-y=<-1-1>
5865 Position of the OSD bar. -1 is top, 0 is centered, 1 is bottom.
5866 Fractional values (like 0.5) are allowed.
5867 --osd-bar-w=<1-100>
5869 Width of the OSD bar, in percentage of the screen width (de‐
5870 fault: 75). A value of 50 means the bar is half the screen
5871 wide.
5872 --osd-bar-h=<0.1-50>
5874 Height of the OSD bar, in percentage of the screen height (de‐
5875 fault: 3.125).
5876 --osd-back-color=<color>
5878 See --sub-color. Color used for OSD text background.
5879 --osd-blur=<0..20.0>
5881 Gaussian blur factor. 0 means no blur applied (default).
5882 --osd-bold=<yes|no>
5884 Format text on bold.
5885 --osd-italic=<yes|no>
5887 Format text on italic.
5888 --osd-border-color=<color>
5890 See --sub-color. Color used for the OSD font border.
5891 NOTE:
5893 ignored when --osd-back-color is specified (or more exactly:
5894 when that option is not set to completely transparent).
5895 --osd-border-size=<size>
5897 Size of the OSD font border in scaled pixels (see
5898 --sub-font-size for details). A value of 0 disables borders.
5899 Default: 3.
5901 --osd-color=<color>
5903 Specify the color used for OSD. See --sub-color for details.
5904 --osd-fractions
5906 Show OSD times with fractions of seconds (in millisecond preci‐
5907 sion). Useful to see the exact timestamp of a video frame.
5908 --osd-level=<0-3>
5910 Specifies which mode the OSD should start in.
5911 0 OSD completely disabled (subtitles only)
5913 1 enabled (shows up only on user interaction)
5915 2 enabled + current time visible by default
5917 3 enabled + --osd-status-msg (current time and status by
5919 default)
5920 --osd-margin-x=<size>
5922 Left and right screen margin for the OSD in scaled pixels (see
5923 --sub-font-size for details).
5924 This option specifies the distance of the OSD to the left, as
5926 well as at which distance from the right border long OSD text
5927 will be broken.
5928 Default: 25.
5930 --osd-margin-y=<size>
5932 Top and bottom screen margin for the OSD in scaled pixels (see
5933 --sub-font-size for details).
5934 This option specifies the vertical margins of the OSD.
5936 Default: 22.
5938 --osd-align-x=<left|center|right>
5940 Control to which corner of the screen OSD should be aligned to
5941 (default: left).
5942 --osd-align-y=<top|center|bottom>
5944 Vertical position (default: top). Details see --osd-align-x.
5945 --osd-scale=<factor>
5947 OSD font size multiplier, multiplied with --osd-font-size value.
5948 --osd-scale-by-window=<yes|no>
5950 Whether to scale the OSD with the window size (default: yes). If
5951 this is disabled, --osd-font-size and other OSD options that use
5952 scaled pixels are always in actual pixels. The effect is that
5953 changing the window size won't change the OSD font size.
5954 --osd-shadow-color=<color>
5956 See --sub-color. Color used for OSD shadow.
5957 --osd-shadow-offset=<size>
5959 Displacement of the OSD shadow in scaled pixels (see
5960 --sub-font-size for details). A value of 0 disables shadows.
5961 Default: 0.
5963 --osd-spacing=<size>
5965 Horizontal OSD/sub font spacing in scaled pixels (see
5966 --sub-font-size for details). This value is added to the normal
5967 letter spacing. Negative values are allowed.
5968 Default: 0.
5970 --video-osd=<yes|no>
5972 Enabled OSD rendering on the video window (default: yes). This
5973 can be used in situations where terminal OSD is preferred. If
5974 you just want to disable all OSD rendering, use --osd-level=0.
5975 It does not affect subtitles or overlays created by scripts (in
5977 particular, the OSC needs to be disabled with --no-osc).
5978 This option is somewhat experimental and could be replaced by
5980 another mechanism in the future.
5981 --osd-font-provider=<...>
5983 See --sub-font-provider for details and accepted values. Note
5984 that unlike subtitles, OSD never uses embedded fonts from media
5985 files.
5986 Screenshot
5988 --screenshot-format=<type>
5989 Set the image file type used for saving screenshots.
5990 Available choices:
5992 png PNG
5994 jpg JPEG (default)
5996 jpeg JPEG (alias for jpg)
5998 webp WebP
6000 jxl JPEG XL
6002 --screenshot-tag-colorspace=<yes|no>
6004 Tag screenshots with the appropriate colorspace.
6005 Note that not all formats are supported.
6007 Default: no.
6009 --screenshot-high-bit-depth=<yes|no>
6011 If possible, write screenshots with a bit depth similar to the
6012 source video (default: yes). This is interesting in particular
6013 for PNG, as this sometimes triggers writing 16 bit PNGs with
6014 huge file sizes. This will also include an unused alpha channel
6015 in the resulting files if 16 bit is used.
6016 --screenshot-template=<template>
6018 Specify the filename template used to save screenshots. The tem‐
6019 plate specifies the filename without file extension, and can
6020 contain format specifiers, which will be substituted when taking
6021 a screenshot. By default, the template is mpv-shot%n, which re‐
6022 sults in filenames like mpv-shot0012.png for example.
6023 The template can start with a relative or absolute path, in or‐
6025 der to specify a directory location where screenshots should be
6026 saved.
6027 If the final screenshot filename points to an already existing
6029 file, the file will not be overwritten. The screenshot will ei‐
6030 ther not be saved, or if the template contains %n, saved using
6031 different, newly generated filename.
6032 Allowed format specifiers:
6034 %[#][0X]n
6036 A sequence number, padded with zeros to length X (de‐
6037 fault: 04). E.g. passing the format %04n will yield 0012
6038 on the 12th screenshot. The number is incremented every
6039 time a screenshot is taken or if the file already exists.
6040 The length X must be in the range 0-9. With the optional
6041 # sign, mpv will use the lowest available number. For ex‐
6042 ample, if you take three screenshots--0001, 0002,
6043 0003--and delete the first two, the next two screenshots
6044 will not be 0004 and 0005, but 0001 and 0002 again.
6045 %f Filename of the currently played video.
6047 %F Same as %f, but strip the file extension, including the
6049 dot.
6050 %x Directory path of the currently played video. If the
6052 video is not on the filesystem (but e.g. http://), this
6053 expand to an empty string.
6054 %X{fallback}
6056 Same as %x, but if the video file is not on the filesys‐
6057 tem, return the fallback string inside the {...}.
6058 %p Current playback time, in the same format as used in the
6060 OSD. The result is a string of the form "HH:MM:SS". For
6061 example, if the video is at the time position 5 minutes
6062 and 34 seconds, %p will be replaced with "00:05:34".
6063 %P Similar to %p, but extended with the playback time in
6065 milliseconds. It is formatted as "HH:MM:SS.mmm", with
6066 "mmm" being the millisecond part of the playback time.
6067 NOTE:
6069 This is a simple way for getting unique per-frame
6070 timestamps. (Frame numbers would be more intuitive,
6071 but are not easily implementable because container
6072 formats usually use time stamps for identifying
6073 frames.)
6074 %wX Specify the current playback time using the format string
6076 X. %p is like %wH:%wM:%wS, and %P is like
6077 %wH:%wM:%wS.%wT.
6078 Valid format specifiers:
6080 %wH hour (padded with 0 to two digits)
6082 %wh hour (not padded)
6084 %wM minutes (00-59)
6086 %wm total minutes (includes hours, unlike %wM)
6088 %wS seconds (00-59)
6090 %ws total seconds (includes hours and minutes)
6092 %wf like %ws, but as float
6094 %wT milliseconds (000-999)
6096 %tX Specify the current local date/time using the format X.
6098 This format specifier uses the UNIX strftime() function
6099 internally, and inserts the result of passing "%X" to
6100 strftime. For example, %tm will insert the number of the
6101 current month as number. You have to use multiple %tX
6102 specifiers to build a full date/time string.
6103 %{prop[:fallback text]}
6105 Insert the value of the input property 'prop'. E.g.
6106 %{filename} is the same as %f. If the property does not
6107 exist or is not available, an error text is inserted, un‐
6108 less a fallback is specified.
6109 %% Replaced with the % character itself.
6111 --screenshot-directory=<path>
6113 Store screenshots in this directory. This path is joined with
6114 the filename generated by --screenshot-template. If the template
6115 filename is already absolute, the directory is ignored.
6116 If the directory does not exist, it is created on the first
6118 screenshot. If it is not a directory, an error is generated when
6119 trying to write a screenshot.
6120 This option is not set by default, and thus will write screen‐
6122 shots to the directory from which mpv was started. In pseudo-gui
6123 mode (see PSEUDO GUI MODE), this is set to the desktop.
6124 --screenshot-jpeg-quality=<0-100>
6126 Set the JPEG quality level. Higher means better quality. The de‐
6127 fault is 90.
6128 --screenshot-jpeg-source-chroma=<yes|no>
6130 Write JPEG files with the same chroma subsampling as the video
6131 (default: yes). If disabled, the libjpeg default is used.
6132 --screenshot-png-compression=<0-9>
6134 Set the PNG compression level. Higher means better compression.
6135 This will affect the file size of the written screenshot file
6136 and the time it takes to write a screenshot. Too high compres‐
6137 sion might occupy enough CPU time to interrupt playback. The de‐
6138 fault is 7.
6139 --screenshot-png-filter=<0-5>
6141 Set the filter applied prior to PNG compression. 0 is none, 1 is
6142 "sub", 2 is "up", 3 is "average", 4 is "Paeth", and 5 is
6143 "mixed". This affects the level of compression that can be
6144 achieved. For most images, "mixed" achieves the best compression
6145 ratio, hence it is the default.
6146 --screenshot-webp-lossless=<yes|no>
6148 Write lossless WebP files. --screenshot-webp-quality is ignored
6149 if this is set. The default is no.
6150 --screenshot-webp-quality=<0-100>
6152 Set the WebP quality level. Higher means better quality. The de‐
6153 fault is 75.
6154 --screenshot-webp-compression=<0-6>
6156 Set the WebP compression level. Higher means better compression,
6157 but takes more CPU time. Note that this also affects the screen‐
6158 shot quality when used with lossy WebP files. The default is 4.
6159 --screenshot-jxl-distance=<0-15>
6161 Set the JPEG XL Butteraugli distance. Lower means better qual‐
6162 ity. Lossless is 0.0, and 1.0 is approximately equivalent to
6163 JPEG quality 90 for photographic content. Use 0.1 for "visually
6164 lossless" screenshots. The default is 1.0.
6165 --screenshot-jxl-effort=<1-9>
6167 Set the JPEG XL compression effort. Higher effort (usually)
6168 means better compression, but takes more CPU time. The default
6169 is 3.
6170 --screenshot-sw=<yes|no>
6172 Whether to use software rendering for screenshots (default: no).
6173 If set to no, the screenshot will be rendered by the current VO
6175 if possible (only vo_gpu currently). The advantage is that this
6176 will (probably) always show up as in the video window, because
6177 the same code is used for rendering. But since the renderer
6178 needs to be reinitialized, this can be slow and interrupt play‐
6179 back. (Unless the window mode is used with the screenshot com‐
6180 mand.)
6181 If set to yes, the software scaler is used to convert the video
6183 to RGB (or whatever the target screenshot requires). In this
6184 case, conversion will run in a separate thread and will probably
6185 not interrupt playback. The software renderer may lack some ca‐
6186 pabilities, such as HDR rendering.
6187 Software Scaler
6189 --sws-scaler=<name>
6190 Specify the software scaler algorithm to be used with
6191 --vf=scale. This also affects video output drivers which lack
6192 hardware acceleration, e.g. x11. See also --vf=scale.
6193 To get a list of available scalers, run --sws-scaler=help.
6195 Default: bicubic.
6197 --sws-lgb=<0-100>
6199 Software scaler Gaussian blur filter (luma). See --sws-scaler.
6200 --sws-cgb=<0-100>
6202 Software scaler Gaussian blur filter (chroma). See --sws-scaler.
6203 --sws-ls=<-100-100>
6205 Software scaler sharpen filter (luma). See --sws-scaler.
6206 --sws-cs=<-100-100>
6208 Software scaler sharpen filter (chroma). See --sws-scaler.
6209 --sws-chs=<h>
6211 Software scaler chroma horizontal shifting. See --sws-scaler.
6212 --sws-cvs=<v>
6214 Software scaler chroma vertical shifting. See --sws-scaler.
6215 --sws-bitexact=<yes|no>
6217 Unknown functionality (default: no). Consult libswscale source
6218 code. The primary purpose of this, as far as libswscale API
6219 goes), is to produce exactly the same output for the same input
6220 on all platforms (output has the same "bits" everywhere, thus
6221 "bitexact"). Typically disables optimizations.
6222 --sws-fast=<yes|no>
6224 Allow optimizations that help with performance, but reduce qual‐
6225 ity (default: no).
6226 VOs like drm and x11 will benefit a lot from using --sws-fast.
6228 You may need to set other options, like --sws-scaler. The
6229 builtin sws-fast profile sets this option and some others to
6230 gain performance for reduced quality. Also see --sws-allow-zimg.
6231 --sws-allow-zimg=<yes|no>
6233 Allow using zimg (if the component using the internal swscale
6234 wrapper explicitly allows so) (default: yes). In this case, zimg
6235 may be used, if the internal zimg wrapper supports the input and
6236 output formats. It will silently or noisily fall back to libsws‐
6237 cale if one of these conditions does not apply.
6238 If zimg is used, the other --sws- options are ignored, and the
6240 --zimg- options are used instead.
6241 If the internal component using the swscale wrapper hooks up
6243 logging correctly, a verbose priority log message will indicate
6244 whether zimg is being used.
6245 Most things which need software conversion can make use of this.
6247 NOTE:
6249 Do note that zimg may be slower than libswscale. Usually,
6250 it's faster on x86 platforms, but slower on ARM (due to lack
6251 of ARM specific optimizations). The mpv zimg wrapper uses un‐
6252 optimized repacking for some formats, for which zimg cannot
6253 be blamed.
6254 --zimg-scaler=<point|bilinear|bicubic|spline16|spline36|lanczos>
6256 Zimg luma scaler to use (default: lanczos).
6257 --zimg-scaler-param-a=<default|float>, --zimg-scaler-param-b=<de‐
6259 fault|float>
6260 Set scaler parameters. By default, these are set to the special
6261 string default, which maps to a scaler-specific default value.
6262 Ignored if the scaler is not tunable.
6263 lanczos
6265 --zimg-scaler-param-a is the number of taps.
6266 bicubic
6268 a and b are the bicubic b and c parameters.
6269 --zimg-scaler-chroma=...
6271 Same as --zimg-scaler, for for chroma interpolation (default:
6272 bilinear).
6273 --zimg-scaler-chroma-param-a, --zimg-scaler-chroma-param-b
6275 Same as --zimg-scaler-param-a / --zimg-scaler-param-b, for
6276 chroma.
6277 --zimg-dither=<no|ordered|random|error-diffusion>
6279 Dithering (default: random).
6280 --zimg-threads=<auto|integer>
6282 Set the maximum number of threads to use for scaling (default:
6283 auto). auto uses the number of logical cores on the current ma‐
6284 chine. Note that the scaler may use less threads (or even just 1
6285 thread) depending on stuff. Passing a value of 1 disables
6286 threading and always scales the image in a single operation.
6287 Higher thread counts waste resources, but make it typically
6288 faster.
6289 Note that some zimg git versions had bugs that will corrupt the
6291 output if threads are used.
6292 --zimg-fast=<yes|no>
6294 Allow optimizations that help with performance, but reduce qual‐
6295 ity (default: yes). Currently, this may simplify gamma conver‐
6296 sion operations.
6297 Audio Resampler
6299 This controls the default options of any resampling done by mpv (but
6300 not within libavfilter, within the system audio API resampler, or any
6301 other places).
6302 It also sets the defaults for the lavrresample audio filter.
6304 --audio-resample-filter-size=<length>
6306 Length of the filter with respect to the lower sampling rate.
6307 (default: 16)
6308 --audio-resample-phase-shift=<count>
6310 Log2 of the number of polyphase entries. (..., 10->1024,
6311 11->2048, 12->4096, ...) (default: 10->1024)
6312 --audio-resample-cutoff=<cutoff>
6314 Cutoff frequency (0.0-1.0), default set depending upon filter
6315 length.
6316 --audio-resample-linear=<yes|no>
6318 If set then filters will be linearly interpolated between
6319 polyphase entries. (default: no)
6320 --audio-normalize-downmix=<yes|no>
6322 Enable/disable normalization if surround audio is downmixed to
6323 stereo (default: no). If this is disabled, downmix can cause
6324 clipping. If it's enabled, the output might be too quiet. It de‐
6325 pends on the source audio.
6326 Technically, this changes the normalize suboption of the lavrre‐
6328 sample audio filter, which performs the downmixing.
6329 If downmix happens outside of mpv for some reason, or in the de‐
6331 coder (decoder downmixing), or in the audio output (system
6332 mixer), this has no effect.
6333 --audio-resample-max-output-size=<length>
6335 Limit maximum size of audio frames filtered at once, in ms (de‐
6336 fault: 40). The output size size is limited in order to make
6337 resample speed changes react faster. This is necessary espe‐
6338 cially if decoders or filters output very large frame sizes
6339 (like some lossless codecs or some DRC filters). This option
6340 does not affect the resampling algorithm in any way.
6341 For testing/debugging only. Can be removed or changed any time.
6343 --audio-swresample-o=<string>
6345 Set AVOptions on the SwrContext or AVAudioResampleContext. These
6346 should be documented by FFmpeg or Libav.
6347 This is a key/value list option. See List Options for details.
6349 Terminal
6351 --quiet
6352 Make console output less verbose; in particular, prevents the
6353 status line (i.e. AV: 3.4 (00:00:03.37) / 5320.6 ...) from being
6354 displayed. Particularly useful on slow terminals or broken ones
6355 which do not properly handle carriage return (i.e. \r).
6356 See also: --really-quiet and --msg-level.
6358 --really-quiet
6360 Display even less output and status messages than with --quiet.
6361 --no-terminal, --terminal
6363 Disable any use of the terminal and stdin/stdout/stderr. This
6364 completely silences any message output.
6365 Unlike --really-quiet, this disables input and terminal initial‐
6367 ization as well.
6368 --no-msg-color
6370 Disable colorful console output on terminals.
6371 --msg-level=<module1=level1,module2=level2,...>
6373 Control verbosity directly for each module. The all module
6374 changes the verbosity of all the modules. The verbosity changes
6375 from this option are applied in order from left to right, and
6376 each item can override a previous one.
6377 Run mpv with --msg-level=all=trace to see all messages mpv out‐
6379 puts. You can use the module names printed in the output (pre‐
6380 fixed to each line in [...]) to limit the output to interesting
6381 modules.
6382 This also affects --log-file, and in certain cases libmpv API
6384 logging.
6385 NOTE:
6387 Some messages are printed before the command line is parsed
6388 and are therefore not affected by --msg-level. To control
6389 these messages, you have to use the MPV_VERBOSE environment
6390 variable; see ENVIRONMENT VARIABLES for details.
6391 Available levels:
6393 no complete silence
6395 fatal fatal messages only
6397 error error messages
6399 warn warning messages
6401 info informational messages
6403 status status messages (default)
6405 v verbose messages
6407 debug debug messages
6409 trace very noisy debug messages
6411 Example
6413 mpv --msg-level=ao/sndio=no
6415 Completely silences the output of ao_sndio, which uses the
6417 log prefix [ao/sndio].
6418 mpv --msg-level=all=warn,ao/alsa=error
6420 Only show warnings or worse, and let the ao_alsa output show
6422 errors only.
6423 --term-osd=<auto|no|force>
6425 Control whether OSD messages are shown on the console when no
6426 video output is available (default: auto).
6427 auto use terminal OSD if no video output active
6429 no disable terminal OSD
6431 force use terminal OSD even if video output active
6433 The auto mode also enables terminal OSD if --video-osd=no was
6435 set.
6436 --term-osd-bar, --no-term-osd-bar
6438 Enable printing a progress bar under the status line on the ter‐
6439 minal. (Disabled by default.)
6440 --term-osd-bar-chars=<string>
6442 Customize the --term-osd-bar feature. The string is expected to
6443 consist of 5 characters (start, left space, position indicator,
6444 right space, end). You can use Unicode characters, but note that
6445 double- width characters will not be treated correctly.
6446 Default: [-+-].
6448 --term-playing-msg=<string>
6450 Print out a string after starting playback. The string is ex‐
6451 panded for properties, e.g. --term-playing-msg='file: ${file‐
6452 name}' will print the string file: followed by a space and the
6453 currently played filename.
6454 See Property Expansion.
6456 --term-status-msg=<string>
6458 Print out a custom string during playback instead of the stan‐
6459 dard status line. Expands properties. See Property Expansion.
6460 --term-title=<string>
6462 Set the terminal title. Currently, this simply concatenates the
6463 escape sequence setting the window title with the provided
6464 (property expanded) string. This will mess up if the expanded
6465 string contain bytes that end the escape sequence, or if the
6466 terminal does not understand the sequence. The latter probably
6467 includes the regrettable win32.
6468 Expands properties. See Property Expansion.
6470 --msg-module
6472 Prepend module name to each console message.
6473 --msg-time
6475 Prepend timing information to each console message. The time is
6476 in seconds since the player process was started (technically,
6477 slightly later actually), using a monotonic time source depend‐
6478 ing on the OS. This is CLOCK_MONOTONIC on sane UNIX variants.
6479 Cache
6481 --cache=<yes|no|auto>
6482 Decide whether to use network cache settings (default: auto).
6483 If enabled, use up to --cache-secs for the cache size (but still
6485 limited to --demuxer-max-bytes), and make the cached data seek‐
6486 able (if possible). If disabled, --cache-pause and related are
6487 implicitly disabled.
6488 The auto choice enables this depending on whether the stream is
6490 thought to involve network accesses or other slow media (this is
6491 an imperfect heuristic).
6492 Before mpv 0.30.0, this used to accept a number, which specified
6494 the size of the cache in kilobytes. Use e.g. --cache --de‐
6495 muxer-max-bytes=123k instead.
6496 --no-cache
6498 Turn off input stream caching. See --cache.
6499 --cache-secs=<seconds>
6501 How many seconds of audio/video to prefetch if the cache is ac‐
6502 tive. This overrides the --demuxer-readahead-secs option if and
6503 only if the cache is enabled and the value is larger. The de‐
6504 fault value is set to something very high, so the actually
6505 achieved readahead will usually be limited by the value of the
6506 --demuxer-max-bytes option. Setting this option is usually only
6507 useful for limiting readahead.
6508 --cache-on-disk=<yes|no>
6510 Write packet data to a temporary file, instead of keeping them
6511 in memory. This makes sense only with --cache. If the normal
6512 cache is disabled, this option is ignored.
6513 You need to set --cache-dir to use this.
6515 The cache file is append-only. Even if the player appears to
6517 prune data, the file space freed by it is not reused. The cache
6518 file is deleted when playback is closed.
6519 Note that packet metadata is still kept in memory. --de‐
6521 muxer-max-bytes and related options are applied to metadata
6522 only. The size of this metadata varies, but 50 MB per hour of
6523 media is typical. The cache statistics will report this metadats
6524 size, instead of the size of the cache file. If the metadata
6525 hits the size limits, the metadata is pruned (but not the cache
6526 file).
6527 When the media is closed, the cache file is deleted. A cache
6529 file is generally worthless after the media is closed, and it's
6530 hard to retrieve any media data from it (it's not supported by
6531 design).
6532 If the option is enabled at runtime, the cache file is created,
6534 but old data will remain in the memory cache. If the option is
6535 disabled at runtime, old data remains in the disk cache, and the
6536 cache file is not closed until the media is closed. If the op‐
6537 tion is disabled and enabled again, it will continue to use the
6538 cache file that was opened first.
6539 --cache-dir=<path>
6541 Directory where to create temporary files (default: none).
6542 Currently, this is used for --cache-on-disk only.
6544 --cache-pause=<yes|no>
6546 Whether the player should automatically pause when the cache
6547 runs out of data and stalls decoding/playback (default: yes). If
6548 enabled, it will pause and unpause once more data is available,
6549 aka "buffering".
6550 --cache-pause-wait=<seconds>
6552 Number of seconds the packet cache should have buffered before
6553 starting playback again if "buffering" was entered (default: 1).
6554 This can be used to control how long the player rebuffers if
6555 --cache-pause is enabled, and the demuxer underruns. If the
6556 given time is higher than the maximum set with --cache-secs or
6557 --demuxer-readahead-secs, or prefetching ends before that for
6558 some other reason (like file end or maximum configured cache
6559 size reached), playback resumes earlier.
6560 --cache-pause-initial=<yes|no>
6562 Enter "buffering" mode before starting playback (default: no).
6563 This can be used to ensure playback starts smoothly, in exchange
6564 for waiting some time to prefetch network data (as controlled by
6565 --cache-pause-wait). For example, some common behavior is that
6566 playback starts, but network caches immediately underrun when
6567 trying to decode more data as playback progresses.
6568 Another thing that can happen is that the network prefetching is
6570 so CPU demanding (due to demuxing in the background) that play‐
6571 back drops frames at first. In these cases, it helps enabling
6572 this option, and setting --cache-secs and --cache-pause-wait to
6573 roughly the same value.
6574 This option also triggers when playback is restarted after seek‐
6576 ing.
6577 --cache-unlink-files=<immediate|whendone|no>
6579 Whether or when to unlink cache files (default: immediate). This
6580 affects cache files which are inherently temporary, and which
6581 make no sense to remain on disk after the player terminates.
6582 This is a debugging option.
6583 immediate
6585 Unlink cache file after they were created. The cache
6586 files won't be visible anymore, even though they're in
6587 use. This ensures they are guaranteed to be removed from
6588 disk when the player terminates, even if it crashes.
6589 whendone
6591 Delete cache files after they are closed.
6592 no Don't delete cache files. They will consume disk space
6594 without having a use.
6595 Currently, this is used for --cache-on-disk only.
6597 --stream-buffer-size=<bytesize>
6599 Size of the low level stream byte buffer (default: 128KB). This
6600 is used as buffer between demuxer and low level I/O (e.g. sock‐
6601 ets). Generally, this can be very small, and the main purpose is
6602 similar to the internal buffer FILE in the C standard library
6603 will have.
6604 Half of the buffer is always used for guaranteed seek back,
6606 which is important for unseekable input.
6607 There are known cases where this can help performance to set a
6609 large buffer:
6610 1. mp4 files. libavformat may trigger many small seeks in
6612 both directions, depending on how the file was muxed.
6613 2. Certain network filesystems, which do not have a cache,
6615 and where small reads can be inefficient.
6616 In other cases, setting this to a large value can reduce perfor‐
6618 mance.
6619 Usually, read accesses are at half the buffer size, but it may
6621 happen that accesses are done alternating with smaller and
6622 larger sizes (this is due to the internal ring buffer
6623 wrap-around).
6624 See --list-options for defaults and value range. <bytesize> op‐
6626 tions accept suffixes such as KiB and MiB.
6627 --vd-queue-enable=<yes|no>, --ad-queue-enable
6629 Enable running the video/audio decoder on a separate thread (de‐
6630 fault: no). If enabled, the decoder is run on a separate
6631 thread, and a frame queue is put between decoder and higher
6632 level playback logic. The size of the frame queue is defined by
6633 the other options below.
6634 This is probably quite pointless. libavcodec already has multi‐
6636 threaded decoding (enabled by default), which makes this largely
6637 unnecessary. It might help in some corner cases with high band‐
6638 width video that is slow to decode (in these cases libavcodec
6639 would block the playback logic, while using a decoding thread
6640 would distribute the decoding time evenly without affecting the
6641 playback logic). In other situations, it will simply make seek‐
6642 ing slower and use significantly more memory.
6643 The queue size is restricted by the other --vd-queue-... op‐
6645 tions. The final queue size is the minimum as indicated by the
6646 option with the lowest limit. Each decoder/track has its own
6647 queue that may use the full configured queue size.
6648 Most queue options can be changed at runtime. --vd-queue-enable
6650 itself (and the audio equivalent) update only if decoding is
6651 completely reinitialized. However, setting --vd-queue-max-sam‐
6652 ples=1 should almost lead to the same behavior as --vd-queue-en‐
6653 able=no, so that value can be used for effectively runtime en‐
6654 abling/disabling the queue.
6655 This should not be used with hardware decoding. It is possible
6657 to enable this for audio, but it makes even less sense.
6658 --vd-queue-max-bytes=<bytesize>, --ad-queue-max-bytes
6660 Maximum approximate allowed size of the queue. If exceeded, de‐
6661 coding will be stopped. The maximum size can be exceeded by
6662 about 1 frame.
6663 See --list-options for defaults and value range. <bytesize> op‐
6665 tions accept suffixes such as KiB and MiB.
6666 --vd-queue-max-samples=<int>, --ad-queue-max-samples
6668 Maximum number of frames (video) or samples (audio) of the
6669 queue. The audio size may be exceeded by about 1 frame.
6670 See --list-options for defaults and value range.
6672 --vd-queue-max-secs=<seconds>, --ad-queue-max-secs
6674 Maximum number of seconds of media in the queue. The special
6675 value 0 means no limit is set. The queue size may be exceeded by
6676 about 2 frames. Timestamp resets may lead to random queue size
6677 usage.
6678 See --list-options for defaults and value range.
6680 Network
6682 --user-agent=<string>
6683 Use <string> as user agent for HTTP streaming.
6684 --cookies, --no-cookies
6686 Support cookies when making HTTP requests. Disabled by default.
6687 --cookies-file=<filename>
6689 Read HTTP cookies from <filename>. The file is assumed to be in
6690 Netscape format.
6691 --http-header-fields=<field1,field2>
6693 Set custom HTTP fields when accessing HTTP stream.
6694 This is a string list option. See List Options for details.
6696 Example
6698 mpv --http-header-fields='Field1: value1','Field2: value2' \
6700 http://localhost:1234
6701 Will generate HTTP request:
6703 GET / HTTP/1.0
6705 Host: localhost:1234
6706 User-Agent: MPlayer
6707 Icy-MetaData: 1
6708 Field1: value1
6709 Field2: value2
6710 Connection: close
6711 --http-proxy=<proxy>
6713 URL of the HTTP/HTTPS proxy. If this is set, the http_proxy en‐
6714 vironment is ignored. The no_proxy environment variable is still
6715 respected. This option is silently ignored if it does not start
6716 with http://. Proxies are not used for https URLs. Setting this
6717 option does not try to make the ytdl script use the proxy.
6718 --tls-ca-file=<filename>
6720 Certificate authority database file for use with TLS. (Silently
6721 fails with older FFmpeg or Libav versions.)
6722 --tls-verify
6724 Verify peer certificates when using TLS (e.g. with https://...).
6725 (Silently fails with older FFmpeg or Libav versions.)
6726 --tls-cert-file
6728 A file containing a certificate to use in the handshake with the
6729 peer.
6730 --tls-key-file
6732 A file containing the private key for the certificate.
6733 --referrer=<string>
6735 Specify a referrer path or URL for HTTP requests.
6736 --network-timeout=<seconds>
6738 Specify the network timeout in seconds (default: 60 seconds).
6739 This affects at least HTTP. The special value 0 uses the FFm‐
6740 peg/Libav defaults. If a protocol is used which does not support
6741 timeouts, this option is silently ignored.
6742 WARNING:
6744 This breaks the RTSP protocol, because of inconsistent FFmpeg
6745 API regarding its internal timeout option. Not only does the
6746 RTSP timeout option accept different units (seconds instead
6747 of microseconds, causing mpv to pass it huge values), it will
6748 also overflow FFmpeg internal calculations. The worst is that
6749 merely setting the option will put RTSP into listening mode,
6750 which breaks any client uses. At time of this writing, the
6751 fix was not made effective yet. For this reason, this option
6752 is ignored (or should be ignored) on RTSP URLs. You can still
6753 set the timeout option directly with --demuxer-lavf-o.
6754 --rtsp-transport=<lavf|udp|udp_multicast|tcp|http>
6756 Select RTSP transport method (default: tcp). This selects the
6757 underlying network transport when playing rtsp://... URLs. The
6758 value lavf leaves the decision to libavformat.
6759 --hls-bitrate=<no|min|max|<rate>>
6761 If HLS streams are played, this option controls what streams are
6762 selected by default. The option allows the following parameters:
6763 no Don't do anything special. Typically, this will simply
6765 pick the first audio/video streams it can find.
6766 min Pick the streams with the lowest bitrate.
6768 max Same, but highest bitrate. (Default.)
6770 Additionally, if the option is a number, the stream with the
6772 highest rate equal or below the option value is selected.
6773 The bitrate as used is sent by the server, and there's no guar‐
6775 antee it's actually meaningful.
6776 DVB
6778 --dvbin-prog=<string>
6779 This defines the program to tune to. Usually, you may specify
6780 this by using a stream URI like "dvb://ZDF HD", but you can tune
6781 to a different channel by writing to this property at runtime.
6782 Also see dvbin-channel-switch-offset for more useful channel
6783 switching functionality.
6784 --dvbin-card=<0-15>
6786 Specifies using card number 0-15 (default: 0).
6787 --dvbin-file=<filename>
6789 Instructs mpv to read the channels list from <filename>. The de‐
6790 fault is in the mpv configuration directory (usually ~/.con‐
6791 fig/mpv) with the filename channels.conf.{sat,ter,cbl,atsc}
6792 (based on your card type) or channels.conf as a last resort.
6793 For DVB-S/2 cards, a VDR 1.7.x format channel list is recom‐
6794 mended as it allows tuning to DVB-S2 channels, enabling subti‐
6795 tles and decoding the PMT (which largely improves the demuxing).
6796 Classic mplayer format channel lists are still supported (with‐
6797 out these improvements), and for other card types, only limited
6798 VDR format channel list support is implemented (patches wel‐
6799 come). For channels with dynamic PID switching or incomplete
6800 channels.conf, --dvbin-full-transponder or the magic PID 8192
6801 are recommended.
6802 --dvbin-timeout=<1-30>
6804 Maximum number of seconds to wait when trying to tune a fre‐
6805 quency before giving up (default: 30).
6806 --dvbin-full-transponder=<yes|no>
6808 Apply no filters on program PIDs, only tune to frequency and
6809 pass full transponder to demuxer. The player frontend selects
6810 the streams from the full TS in this case, so the program which
6811 is shown initially may not match the chosen channel. Switching
6812 between the programs is possible by cycling the program prop‐
6813 erty. This is useful to record multiple programs on a single
6814 transponder, or to work around issues in the channels.conf. It
6815 is also recommended to use this for channels which switch PIDs
6816 on-the-fly, e.g. for regional news.
6817 Default: no
6819 --dvbin-channel-switch-offset=<integer>
6821 This value is not meant for setting via configuration, but used
6822 in channel switching. An input.conf can cycle this value up and
6823 down to perform channel switching. This number effectively gives
6824 the offset to the initially tuned to channel in the channel
6825 list.
6826 An example input.conf could contain: H cycle dvbin-chan‐
6828 nel-switch-offset up, K cycle dvbin-channel-switch-offset down
6829 ALSA audio output options
6831 --alsa-device=<device>
6832 Deprecated, use --audio-device (requires alsa/ prefix).
6833 --alsa-resample=yes
6835 Enable ALSA resampling plugin. (This is disabled by default, be‐
6836 cause some drivers report incorrect audio delay in some cases.)
6837 --alsa-mixer-device=<device>
6839 Set the mixer device used with ao-volume (default: default).
6840 --alsa-mixer-name=<name>
6842 Set the name of the mixer element (default: Master). This is for
6843 example PCM or Master.
6844 --alsa-mixer-index=<number>
6846 Set the index of the mixer channel (default: 0). Consider the
6847 output of "amixer scontrols", then the index is the number that
6848 follows the name of the element.
6849 --alsa-non-interleaved
6851 Allow output of non-interleaved formats (if the audio decoder
6852 uses this format). Currently disabled by default, because some
6853 popular ALSA plugins are utterly broken with non-interleaved
6854 formats.
6855 --alsa-ignore-chmap
6857 Don't read or set the channel map of the ALSA device - only re‐
6858 quest the required number of channels, and then pass the audio
6859 as-is to it. This option most likely should not be used. It can
6860 be useful for debugging, or for static setups with a specially
6861 engineered ALSA configuration (in this case you should always
6862 force the same layout with --audio-channels, or it will work
6863 only for files which use the layout implicit to your ALSA de‐
6864 vice).
6865 --alsa-buffer-time=<microseconds>
6867 Set the requested buffer time in microseconds. A value of 0
6868 skips requesting anything from the ALSA API. This and the
6869 --alsa-periods option uses the ALSA near functions to set the
6870 requested parameters. If doing so results in an empty configura‐
6871 tion set, setting these parameters is skipped.
6872 Both options control the buffer size. A low buffer size can lead
6874 to higher CPU usage and audio dropouts, while a high buffer size
6875 can lead to higher latency in volume changes and other filter‐
6876 ing.
6877 --alsa-periods=<number>
6879 Number of periods requested from the ALSA API. See --alsa-buf‐
6880 fer-time for further remarks.
6881 GPU renderer options
6883 The following video options are currently all specific to --vo=gpu,
6884 --vo=libmpv and --vo=gpu-next, which are the only VOs that implement
6885 them.
6886 --scale=<filter>
6888 The filter function to use when upscaling video.
6889 bilinear
6891 Bilinear hardware texture filtering (fastest, very low
6892 quality). This is the default for compatibility reasons.
6893 spline36
6895 Mid quality and speed. This is the default when using
6896 gpu-hq.
6897 lanczos
6899 Lanczos scaling. Provides mid quality and speed. Gener‐
6900 ally worse than spline36, but it results in a slightly
6901 sharper image which is good for some content types. The
6902 number of taps can be controlled with scale-radius, but
6903 is best left unchanged.
6904 (This filter is an alias for sinc-windowed sinc)
6906 ewa_lanczos
6908 Elliptic weighted average Lanczos scaling. Also known as
6909 Jinc. Relatively slow, but very good quality. The radius
6910 can be controlled with scale-radius. Increasing the ra‐
6911 dius makes the filter sharper but adds more ringing.
6912 (This filter is an alias for jinc-windowed jinc)
6914 ewa_lanczossharp
6916 A slightly sharpened version of ewa_lanczos, preconfig‐
6917 ured to use an ideal radius and parameter. If your hard‐
6918 ware can run it, this is probably what you should use by
6919 default.
6920 mitchell
6922 Mitchell-Netravali. The B and C parameters can be set
6923 with --scale-param1 and --scale-param2. This filter is
6924 very good at downscaling (see --dscale).
6925 oversample
6927 A version of nearest neighbour that (naively) oversamples
6928 pixels, so that pixels overlapping edges get linearly in‐
6929 terpolated instead of rounded. This essentially removes
6930 the small imperfections and judder artifacts caused by
6931 nearest-neighbour interpolation, in exchange for adding
6932 some blur. This filter is good at temporal interpolation,
6933 and also known as "smoothmotion" (see --tscale).
6934 linear A --tscale filter.
6936 There are some more filters, but most are not as useful. For a
6938 complete list, pass help as value, e.g.:
6939 mpv --scale=help
6941 --cscale=<filter>
6943 As --scale, but for interpolating chroma information. If the im‐
6944 age is not subsampled, this option is ignored entirely.
6945 --dscale=<filter>
6947 Like --scale, but apply these filters on downscaling instead. If
6948 this option is unset, the filter implied by --scale will be ap‐
6949 plied.
6950 --tscale=<filter>
6952 The filter used for interpolating the temporal axis (frames).
6953 This is only used if --interpolation is enabled. The only valid
6954 choices for --tscale are separable convolution filters (use
6955 --tscale=help to get a list). The default is mitchell.
6956 Common --tscale choices include oversample, linear, catmull_rom,
6958 mitchell, gaussian, or bicubic. These are listed in increasing
6959 order of smoothness/blurriness, with bicubic being the
6960 smoothest/blurriest and oversample being the sharpest/least
6961 smooth.
6962 --scale-param1=<value>, --scale-param2=<value>,
6964 --cscale-param1=<value>, --cscale-param2=<value>,
6965 --dscale-param1=<value>, --dscale-param2=<value>,
6966 --tscale-param1=<value>, --tscale-param2=<value>
6967 Set filter parameters. By default, these are set to the special
6968 string default, which maps to a scaler-specific default value.
6969 Ignored if the filter is not tunable. Currently, this affects
6970 the following filter parameters:
6971 bcspline
6973 Spline parameters (B and C). Defaults to 0.5 for both.
6974 gaussian
6976 Scale parameter (t). Increasing this makes the result
6977 blurrier. Defaults to 1.
6978 oversample
6980 Minimum distance to an edge before interpolation is used.
6981 Setting this to 0 will always interpolate edges, whereas
6982 setting it to 0.5 will never interpolate, thus behaving
6983 as if the regular nearest neighbour algorithm was used.
6984 Defaults to 0.0.
6985 --scale-blur=<value>, --scale-wblur=<value>, --cscale-blur=<value>,
6987 --cscale-wblur=<value>, --dscale-blur=<value>, --dscale-wblur=<value>,
6988 --tscale-blur=<value>, --tscale-wblur=<value>
6989 Kernel/window scaling factor (also known as a blur factor). De‐
6990 creasing this makes the result sharper, increasing it makes it
6991 blurrier (default 0). If set to 0, the kernel's preferred blur
6992 factor is used. Note that setting this too low (eg. 0.5) leads
6993 to bad results. It's generally recommended to stick to values
6994 between 0.8 and 1.2.
6995 --scale-clamp=<0.0-1.0>, --cscale-clamp, --dscale-clamp, --tscale-clamp
6997 Specifies a weight bias to multiply into negative coefficients.
6998 Specifying --scale-clamp=1 has the effect of removing negative
6999 weights completely, thus effectively clamping the value range to
7000 [0-1]. Values between 0.0 and 1.0 can be specified to apply only
7001 a moderate diminishment of negative weights. This is especially
7002 useful for --tscale, where it reduces excessive ringing arti‐
7003 facts in the temporal domain (which typically manifest them‐
7004 selves as short flashes or fringes of black, mostly around mov‐
7005 ing edges) in exchange for potentially adding more blur. The de‐
7006 fault for --tscale-clamp is 1.0, the others default to 0.0.
7007 --scale-cutoff=<value>, --cscale-cutoff=<value>, --dscale-cut‐
7009 off=<value>
7010 Cut off the filter kernel prematurely once the value range drops
7011 below this threshold. Doing so allows more aggressive pruning of
7012 skippable coefficients by disregarding parts of the LUT which
7013 are effectively zeroed out by the window function. Only affects
7014 polar (EWA) filters. The default is 0.001 for each, which is
7015 perceptually transparent but provides a 10%-20% speedup, depend‐
7016 ing on the exact radius and filter kernel chosen.
7017 --scale-taper=<value>, --scale-wtaper=<value>, --dscale-taper=<value>,
7019 --dscale-wtaper=<value>, --cscale-taper=<value>, --cscale-wta‐
7020 per=<value>, --tscale-taper=<value>, --tscale-wtaper=<value>
7021 Kernel/window taper factor. Increasing this flattens the filter
7022 function. Value range is 0 to 1. A value of 0 (the default)
7023 means no flattening, a value of 1 makes the filter completely
7024 flat (equivalent to a box function). Values in between mean
7025 that some portion will be flat and the actual filter function
7026 will be squeezed into the space in between.
7027 --scale-radius=<value>, --cscale-radius=<value>, --dscale-ra‐
7029 dius=<value>, --tscale-radius=<value>
7030 Set radius for tunable filters, must be a float number between
7031 0.5 and 16.0. Defaults to the filter's preferred radius if not
7032 specified. Doesn't work for every scaler and VO combination.
7033 Note that depending on filter implementation details and video
7035 scaling ratio, the radius that actually being used might be dif‐
7036 ferent (most likely being increased a bit).
7037 --scale-antiring=<value>, --cscale-antiring=<value>, --dscale-antir‐
7039 ing=<value>, --tscale-antiring=<value>
7040 Set the antiringing strength. This tries to eliminate ringing,
7041 but can introduce other artifacts in the process. Must be a
7042 float number between 0.0 and 1.0. The default value of 0.0 dis‐
7043 ables antiringing entirely.
7044 Note that this doesn't affect the special filters bilinear and
7046 bicubic_fast, nor does it affect any polar (EWA) scalers.
7047 --scale-window=<window>, --cscale-window=<window>, --dscale-win‐
7049 dow=<window>, --tscale-window=<window>
7050 (Advanced users only) Choose a custom windowing function for the
7051 kernel. Defaults to the filter's preferred window if unset. Use
7052 --scale-window=help to get a list of supported windowing func‐
7053 tions.
7054 --scale-wparam=<window>, --cscale-wparam=<window>,
7056 --cscale-wparam=<window>, --tscale-wparam=<window>
7057 (Advanced users only) Configure the parameter for the window
7058 function given by --scale-window etc. By default, these are set
7059 to the special string default, which maps to a window-specific
7060 default value. Ignored if the window is not tunable. Currently,
7061 this affects the following window parameters:
7062 kaiser Window parameter (alpha). Defaults to 6.33.
7064 blackman
7066 Window parameter (alpha). Defaults to 0.16.
7067 gaussian
7069 Scale parameter (t). Increasing this makes the window
7070 wider. Defaults to 1.
7071 --scaler-lut-size=<4..10>
7073 Set the size of the lookup texture for scaler kernels (default:
7074 6). The actual size of the texture is 2^N for an option value of
7075 N. So the lookup texture with the default setting uses 64 sam‐
7076 ples.
7077 All weights are linearly interpolated from those samples, so in‐
7079 creasing the size of lookup table might improve the accuracy of
7080 scaler.
7081 --scaler-resizes-only
7083 Disable the scaler if the video image is not resized. In that
7084 case, bilinear is used instead of whatever is set with --scale.
7085 Bilinear will reproduce the source image perfectly if no scaling
7086 is performed. Enabled by default. Note that this option never
7087 affects --cscale.
7088 --correct-downscaling
7090 When using convolution based filters, extend the filter size
7091 when downscaling. Increases quality, but reduces performance
7092 while downscaling.
7093 This will perform slightly sub-optimally for anamorphic video
7095 (but still better than without it) since it will extend the size
7096 to match only the milder of the scale factors between the axes.
7097 Note: this option is ignored when using bilinear downscaling
7099 (the default).
7100 --linear-downscaling
7102 Scale in linear light when downscaling. It should only be used
7103 with a --fbo-format that has at least 16 bit precision. This op‐
7104 tion has no effect on HDR content.
7105 --linear-upscaling
7107 Scale in linear light when upscaling. Like --linear-downscaling,
7108 it should only be used with a --fbo-format that has at least 16
7109 bits precisions. This is not usually recommended except for
7110 testing/specific purposes. Users are advised to either enable
7111 --sigmoid-upscaling or keep both options disabled (i.e. scaling
7112 in gamma light).
7113 --sigmoid-upscaling
7115 When upscaling, use a sigmoidal color transform to avoid empha‐
7116 sizing ringing artifacts. This is incompatible with and replaces
7117 --linear-upscaling. (Note that sigmoidization also requires lin‐
7118 earization, so the LINEAR rendering step fires in both cases)
7119 --sigmoid-center
7121 The center of the sigmoid curve used for --sigmoid-upscaling,
7122 must be a float between 0.0 and 1.0. Defaults to 0.75 if not
7123 specified.
7124 --sigmoid-slope
7126 The slope of the sigmoid curve used for --sigmoid-upscaling,
7127 must be a float between 1.0 and 20.0. Defaults to 6.5 if not
7128 specified.
7129 --interpolation
7131 Reduce stuttering caused by mismatches in the video fps and dis‐
7132 play refresh rate (also known as judder).
7133 WARNING:
7135 This requires setting the --video-sync option to one of the
7136 display- modes, or it will be silently disabled. This was
7137 not required before mpv 0.14.0.
7138 This essentially attempts to interpolate the missing frames by
7140 convoluting the video along the temporal axis. The filter used
7141 can be controlled using the --tscale setting.
7142 --interpolation-threshold=<0..1,-1>
7144 Threshold below which frame ratio interpolation gets disabled
7145 (default: 0.01). This is calculated as abs(disphz/vfps - 1) <
7146 threshold, where vfps is the speed-adjusted video FPS, and dis‐
7147 phz the display refresh rate. (The speed-adjusted video FPS is
7148 roughly equal to the normal video FPS, but with slowdown and
7149 speedup applied. This matters if you use --video-sync=dis‐
7150 play-resample to make video run synchronously to the display
7151 FPS, or if you change the speed property.)
7152 The default is intended to enable interpolation in scenarios
7154 where retiming with the --video-sync=display-* cannot adjust the
7155 speed of the video sufficiently for smooth playback. For example
7156 if a video is 60.00 FPS and your display refresh rate is 59.94
7157 Hz, interpolation will never be activated, since the mismatch is
7158 within 1% of the refresh rate. The default also handles the sce‐
7159 nario when mpv cannot determine the container FPS, such as dur‐
7160 ing certain live streams, and may dynamically toggle interpola‐
7161 tion on and off. In this scenario, the default would be to not
7162 use interpolation but rather to allow --video-sync=display-* to
7163 retime the video to match display refresh rate. See
7164 --video-sync-max-video-change for more information about how mpv
7165 will retime video.
7166 Also note that if you use e.g. --video-sync=display-vdrop, small
7168 deviations in the rate can disable interpolation and introduce a
7169 discontinuity every other minute.
7170 Set this to -1 to disable this logic.
7172 --interpolation-preserve
7174 Preserve the previous frames' interpolated results even when
7175 renderer parameters are changed - with the exception of options
7176 related to cropping and video placement, which always invalidate
7177 the cache. Enabling this option makes dynamic updates of ren‐
7178 derer settings slightly smoother at the cost of slightly higher
7179 latency in response to such changes. Defaults to on. (Only af‐
7180 fects --vo=gpu-next, note that --vo=gpu always invalidates in‐
7181 terpolated frames)
7182 --opengl-pbo
7184 Enable use of PBOs. On some drivers this can be faster, espe‐
7185 cially if the source video size is huge (e.g. so called "4K"
7186 video). On other drivers it might be slower or cause latency is‐
7187 sues.
7188 --dither-depth=<N|no|auto>
7190 Set dither target depth to N. Default: no.
7191 no Disable any dithering done by mpv.
7193 auto Automatic selection. If output bit depth cannot be de‐
7195 tected, 8 bits per component are assumed.
7196 8 Dither to 8 bit output.
7198 Note that the depth of the connected video display device cannot
7200 be detected. Often, LCD panels will do dithering on their own,
7201 which conflicts with this option and leads to ugly output.
7202 --dither-size-fruit=<2-8>
7204 Set the size of the dither matrix (default: 6). The actual size
7205 of the matrix is (2^N) x (2^N) for an option value of N, so a
7206 value of 6 gives a size of 64x64. The matrix is generated at
7207 startup time, and a large matrix can take rather long to compute
7208 (seconds).
7209 Used in --dither=fruit mode only.
7211 --dither=<fruit|ordered|error-diffusion|no>
7213 Select dithering algorithm (default: fruit). (Normally, the
7214 --dither-depth option controls whether dithering is enabled.)
7215 The error-diffusion option requires compute shader support. It
7217 also requires large amount of shared memory to run, the size of
7218 which depends on both the kernel (see --error-diffusion option
7219 below) and the height of video window. It will fallback to fruit
7220 dithering if there is no enough shared memory to run the shader.
7221 --temporal-dither
7223 Enable temporal dithering. (Only active if dithering is enabled
7224 in general.) This changes between 8 different dithering patterns
7225 on each frame by changing the orientation of the tiled dithering
7226 matrix. Unfortunately, this can lead to flicker on LCD displays,
7227 since these have a high reaction time.
7228 --temporal-dither-period=<1-128>
7230 Determines how often the dithering pattern is updated when
7231 --temporal-dither is in use. 1 (the default) will update on ev‐
7232 ery video frame, 2 on every other frame, etc.
7233 --error-diffusion=<kernel>
7235 The error diffusion kernel to use when --dither=error-diffusion
7236 is set.
7237 simple Propagate error to only two adjacent pixels. Fastest but
7239 low quality.
7240 sierra-lite
7242 Fast with reasonable quality. This is the default.
7243 floyd-steinberg
7245 Most notable error diffusion kernel.
7246 atkinson
7248 Looks different from other kernels because only fraction
7249 of errors will be propagated during dithering. A typical
7250 use case of this kernel is saving dithered screenshot (in
7251 window mode). This kernel produces slightly smaller file,
7252 with still reasonable dithering quality.
7253 There are other kernels (use --error-diffusion=help to list) but
7255 most of them are much slower and demanding even larger amount of
7256 shared memory. Among these kernels, burkes achieves a good bal‐
7257 ance between performance and quality, and probably is the one
7258 you want to try first.
7259 --gpu-debug
7261 Enables GPU debugging. What this means depends on the API type.
7262 For OpenGL, it calls glGetError(), and requests a debug context.
7263 For Vulkan, it enables validation layers.
7264 --opengl-swapinterval=<n>
7266 Interval in displayed frames between two buffer swaps. 1 is
7267 equivalent to enable VSYNC, 0 to disable VSYNC. Defaults to 1 if
7268 not specified.
7269 Note that this depends on proper OpenGL vsync support. On some
7271 platforms and drivers, this only works reliably when in
7272 fullscreen mode. It may also require driver-specific hacks if
7273 using multiple monitors, to ensure mpv syncs to the right one.
7274 Compositing window managers can also lead to bad results, as can
7275 missing or incorrect display FPS information (see --over‐
7276 ride-display-fps).
7277 --vulkan-device=<device name>
7279 The name of the Vulkan device to use for rendering and presenta‐
7280 tion. Use --vulkan-device=help to see the list of available de‐
7281 vices and their names. If left unspecified, the first enumerated
7282 hardware Vulkan device will be used.
7283 --vulkan-swap-mode=<mode>
7285 Controls the presentation mode of the vulkan swapchain. This is
7286 similar to the --opengl-swapinterval option.
7287 auto Use the preferred swapchain mode for the vulkan context.
7289 (Default)
7290 fifo Non-tearing, vsync blocked. Similar to "VSync on".
7292 fifo-relaxed
7294 Tearing, vsync blocked. Late frames will tear instead of
7295 stuttering.
7296 mailbox
7298 Non-tearing, not vsync blocked. Similar to "triple
7299 buffering".
7300 immediate
7302 Tearing, not vsync blocked. Similar to "VSync off".
7303 --vulkan-queue-count=<1..8>
7305 Controls the number of VkQueues used for rendering (limited by
7306 how many your device supports). In theory, using more queues
7307 could enable some parallelism between frames (when using a
7308 --swapchain-depth higher than 1), but it can also slow things
7309 down on hardware where there's no true parallelism between
7310 queues. (Default: 1)
7311 --vulkan-async-transfer
7313 Enables the use of async transfer queues on supported vulkan de‐
7314 vices. Using them allows transfer operations like texture up‐
7315 loads and blits to happen concurrently with the actual render‐
7316 ing, thus improving overall throughput and power consumption.
7317 Enabled by default, and should be relatively safe.
7318 --vulkan-async-compute
7320 Enables the use of async compute queues on supported vulkan de‐
7321 vices. Using this, in theory, allows out-of-order scheduling of
7322 compute shaders with graphics shaders, thus enabling the hard‐
7323 ware to do more effective work while waiting for pipeline bub‐
7324 bles and memory operations. Not beneficial on all GPUs. It's
7325 worth noting that if async compute is enabled, and the device
7326 supports more compute queues than graphics queues (bound by the
7327 restrictions set by --vulkan-queue-count), mpv will internally
7328 try and prefer the use of compute shaders over fragment shaders
7329 wherever possible. Enabled by default, although Nvidia users may
7330 want to disable it.
7331 --vulkan-display-display=<n>
7333 The index of the display, on the selected Vulkan device, to
7334 present on when using the displayvk GPU context. Use
7335 --vulkan-display-display=help to see the list of available dis‐
7336 plays. If left unspecified, the first enumerated display will be
7337 used.
7338 --vulkan-display-mode=<n>
7340 The index of the display mode, of the selected Vulkan display,
7341 to use when using the displayvk GPU context. Use --vulkan-dis‐
7342 play-mode=help to see the list of available modes. If left un‐
7343 specified, the first enumerated mode will be used.
7344 --vulkan-display-plane=<n>
7346 The index of the plane, on the selected Vulkan device, to
7347 present on when using the displayvk GPU context. Use
7348 --vulkan-display-plane=help to see the list of available planes.
7349 If left unspecified, the first enumerated plane will be used.
7350 --d3d11-exclusive-fs=<yes|no>
7352 Switches the D3D11 swap chain fullscreen state to 'fullscreen'
7353 when fullscreen video is requested. Also known as "exclusive
7354 fullscreen" or "D3D fullscreen" in other applications. Gives mpv
7355 full control of rendering on the swap chain's screen. Off by de‐
7356 fault.
7357 --d3d11-warp=<yes|no|auto>
7359 Use WARP (Windows Advanced Rasterization Platform) with the
7360 D3D11 GPU backend (default: auto). This is a high performance
7361 software renderer. By default, it is only used when the system
7362 has no hardware adapters that support D3D11. While the extended
7363 GPU features will work with WARP, they can be very slow.
7364 --d3d11-feature-level=<12_1|12_0|11_1|11_0|10_1|10_0|9_3|9_2|9_1>
7366 Select a specific feature level when using the D3D11 GPU back‐
7367 end. By default, the highest available feature level is used.
7368 This option can be used to select a lower feature level, which
7369 is mainly useful for debugging. Most extended GPU features will
7370 not work at 9_x feature levels.
7371 --d3d11-flip=<yes|no>
7373 Enable flip-model presentation, which avoids unnecessarily copy‐
7374 ing the backbuffer by sharing surfaces with the DWM (default:
7375 yes). This may cause performance issues with older drivers. If
7376 flip-model presentation is not supported (for example, on Win‐
7377 dows 7 without the platform update), mpv will automatically fall
7378 back to the older bitblt presentation model.
7379 --d3d11-sync-interval=<0..4>
7381 Schedule each frame to be presented for this number of VBlank
7382 intervals. (default: 1) Setting to 1 will enable VSync, setting
7383 to 0 will disable it.
7384 --d3d11-adapter=<adapter name|help>
7386 Select a specific D3D11 adapter to utilize for D3D11 rendering.
7387 Will pick the default adapter if unset. Alternatives are listed
7388 when the name "help" is given.
7389 Checks for matches based on the start of the string, case insen‐
7391 sitive. Thus, if the description of the adapter starts with the
7392 vendor name, that can be utilized as the selection parameter.
7393 Hardware decoders utilizing the D3D11 rendering abstraction's
7395 helper functionality to receive a device, such as D3D11VA or
7396 DXVA2's DXGI mode, will be affected by this choice.
7397 --d3d11-output-format=<auto|rgba8|bgra8|rgb10_a2|rgba16f>
7399 Select a specific D3D11 output format to utilize for D3D11 ren‐
7400 dering. "auto" is the default, which will pick either rgba8 or
7401 rgb10_a2 depending on the configured desktop bit depth. rgba16f
7402 and bgra8 are left out of the autodetection logic, and are
7403 available for manual testing.
7404 NOTE:
7406 Desktop bit depth querying is only available from an API
7407 available from Windows 10. Thus on older systems it will only
7408 automatically utilize the rgba8 output format.
7409 --d3d11-output-csp=<auto|srgb|linear|pq|bt.2020>
7411 Select a specific D3D11 output color space to utilize for D3D11
7412 rendering. "auto" is the default, which will select the color
7413 space of the desktop on which the swap chain is located.
7414 Values other than "srgb" and "pq" have had issues in testing, so
7416 they are mostly available for manual testing.
7417 NOTE:
7419 Swap chain color space configuration is only available from
7420 an API available from Windows 10. Thus on older systems it
7421 will not work.
7422 --d3d11va-zero-copy=<yes|no>
7424 By default, when using hardware decoding with --gpu-api=d3d11,
7425 the video image will be copied (GPU-to-GPU) from the decoder
7426 surface to a shader resource. Set this option to avoid that copy
7427 by sampling directly from the decoder image. This may increase
7428 performance and reduce power usage, but can cause the image to
7429 be sampled incorrectly on the bottom and right edges due to pad‐
7430 ding, and may invoke driver bugs, since Direct3D 11 technically
7431 does not allow sampling from a decoder surface (though most
7432 drivers support it.)
7433 Currently only relevant for --gpu-api=d3d11.
7435 --wayland-app-id=<string>
7437 Set the client app id for Wayland-based video output methods
7438 (default: mpv).
7439 --wayland-configure-bounds=<yes|no>
7441 Controls whether or not mpv opts into the configure bounds event
7442 if sent by the compositor (default: yes). This restricts the
7443 initial size of the mpv window to a certain maximum size in‐
7444 tended by the compositor. In most cases, this simply just pre‐
7445 vents the mpv window from being larger than the size of the mon‐
7446 itor when it first renders. This option will take precedence
7447 over any autofit or geometry type settings if the configure
7448 bounds are used.
7449 --wayland-disable-vsync=<yes|no>
7451 Disable mpv's internal vsync for Wayland-based video output (de‐
7452 fault: no). This is mainly useful for benchmarking wayland VOs
7453 when combined with video-sync=display-desync, --no-audio, and
7454 --untimed=yes.
7455 --wayland-edge-pixels-pointer=<value>
7457 Defines the size of an edge border (default: 10) to initiate
7458 client side resize events in the wayland contexts with the
7459 mouse. This is only active if there are no server side decora‐
7460 tions from the compositor.
7461 --wayland-edge-pixels-touch=<value>
7463 Defines the size of an edge border (default: 32) to initiate
7464 client side resizes events in the wayland contexts with touch
7465 events.
7466 --spirv-compiler=<compiler>
7468 Controls which compiler is used to translate GLSL to SPIR-V.
7469 This is (currently) only relevant for --gpu-api=vulkan and
7470 --gpu-api=d3d11. The possible choices are currently only:
7471 auto Use the first available compiler. (Default)
7473 shaderc
7475 Use libshaderc, which is an API wrapper around glslang.
7476 This is generally the most preferred, if available.
7477 NOTE:
7479 This option is deprecated, since there is only one reasonable
7480 value. It may be removed in the future.
7481 --glsl-shader=<file>, --glsl-shaders=<file-list>
7483 Custom GLSL hooks. These are a flexible way to add custom frag‐
7484 ment shaders, which can be injected at almost arbitrary points
7485 in the rendering pipeline, and access all previous intermediate
7486 textures.
7487 Each use of the --glsl-shader option will add another file to
7489 the internal list of shaders, while --glsl-shaders takes a list
7490 of files, and overwrites the internal list with it. The latter
7491 is a path list option (see List Options for details).
7492 Warning
7494 The syntax is not stable yet and may change any time.
7496 The general syntax of a user shader looks like this:
7498 //!METADATA ARGS...
7500 //!METADATA ARGS...
7501 vec4 hook() {
7503 ...
7504 return something;
7505 }
7506 //!METADATA ARGS...
7508 //!METADATA ARGS...
7509 ...
7511 Each section of metadata, along with the non-metadata lines af‐
7513 ter it, defines a single block. There are currently two types of
7514 blocks, HOOKs and TEXTUREs.
7515 A TEXTURE block can set the following options:
7517 TEXTURE <name> (required)
7519 The name of this texture. Hooks can then bind the texture
7520 under this name using BIND. This must be the first option
7521 of the texture block.
7522 SIZE <width> [<height>] [<depth>] (required)
7524 The dimensions of the texture. The height and depth are
7525 optional. The type of texture (1D, 2D or 3D) depends on
7526 the number of components specified.
7527 FORMAT <name> (required)
7529 The texture format for the samples. Supported texture
7530 formats are listed in debug logging when the gpu VO is
7531 initialized (look for Texture formats:). Usually, this
7532 follows OpenGL naming conventions. For example, rgb16
7533 provides 3 channels with normalized 16 bit components.
7534 One oddity are float formats: for example, rgba16f has 16
7535 bit internal precision, but the texture data is provided
7536 as 32 bit floats, and the driver converts the data on
7537 texture upload.
7538 Although format names follow a common naming convention,
7540 not all of them are available on all hardware, drivers,
7541 GL versions, and so on.
7542 FILTER <LINEAR|NEAREST>
7544 The min/magnification filter used when sampling from this
7545 texture.
7546 BORDER <CLAMP|REPEAT|MIRROR>
7548 The border wrapping mode used when sampling from this
7549 texture.
7550 Following the metadata is a string of bytes in hexadecimal nota‐
7552 tion that define the raw texture data, corresponding to the for‐
7553 mat specified by FORMAT, on a single line with no extra white‐
7554 space.
7555 A HOOK block can set the following options:
7557 HOOK <name> (required)
7559 The texture which to hook into. May occur multiple times
7560 within a metadata block, up to a predetermined limit. See
7561 below for a list of hookable textures.
7562 DESC <title>
7564 User-friendly description of the pass. This is the name
7565 used when representing this shader in the list of passes
7566 for property vo-passes.
7567 BIND <name>
7569 Loads a texture (either coming from mpv or from a TEXTURE
7570 block) and makes it available to the pass. When binding
7571 textures from mpv, this will also set up macros to facil‐
7572 itate accessing it properly. See below for a list. By de‐
7573 fault, no textures are bound. The special name HOOKED can
7574 be used to refer to the texture that triggered this pass.
7575 SAVE <name>
7577 Gives the name of the texture to save the result of this
7578 pass into. By default, this is set to the special name
7579 HOOKED which has the effect of overwriting the hooked
7580 texture.
7581 WIDTH <szexpr>, HEIGHT <szexpr>
7583 Specifies the size of the resulting texture for this
7584 pass. szexpr refers to an expression in RPN (reverse pol‐
7585 ish notation), using the operators + - * / > < !, float‐
7586 ing point literals, and references to sizes of existing
7587 texture (such as MAIN.width or CHROMA.height), OUTPUT, or
7588 NATIVE_CROPPED (size of an input texture cropped after
7589 pan-and-scan, video-align-x/y, video-pan-x/y, etc. and
7590 possibly prescaled). By default, these are set to
7591 HOOKED.w and HOOKED.h, espectively.
7592 WHEN <szexpr>
7594 Specifies a condition that needs to be true (non-zero)
7595 for the shader stage to be evaluated. If it fails, it
7596 will silently be omitted. (Note that a shader stage like
7597 this which has a dependency on an optional hook point can
7598 still cause that hook point to be saved, which has some
7599 minor overhead)
7600 OFFSET <ox oy | ALIGN>
7602 Indicates a pixel shift (offset) introduced by this pass.
7603 These pixel offsets will be accumulated and corrected
7604 during the next scaling pass (cscale or scale). The de‐
7605 fault values are 0 0 which correspond to no shift. Note
7606 that offsets are ignored when not overwriting the hooked
7607 texture.
7608 A special value of ALIGN will attempt to fix existing
7610 offset of HOOKED by align it with reference. It requires
7611 HOOKED to be resizable (see below). It works transpar‐
7612 ently with fragment shader. For compute shader, the pre‐
7613 defined texmap macro is required to handle coordinate
7614 mapping.
7615 COMPONENTS <n>
7617 Specifies how many components of this pass's output are
7618 relevant and should be stored in the texture, up to 4
7619 (rgba). By default, this value is equal to the number of
7620 components in HOOKED.
7621 COMPUTE <bw> <bh> [<tw> <th>]
7623 Specifies that this shader should be treated as a compute
7624 shader, with the block size bw and bh. The compute shader
7625 will be dispatched with however many blocks are necessary
7626 to completely tile over the output. Within each block,
7627 there will be tw*th threads, forming a single work group.
7628 In other words: tw and th specify the work group size,
7629 which can be different from the block size. So for exam‐
7630 ple, a compute shader with bw, bh = 32 and tw, th = 8
7631 running on a 500x500 texture would dispatch 16x16 blocks
7632 (rounded up), each with 8x8 threads.
7633 Compute shaders in mpv are treated a bit different from
7635 fragment shaders. Instead of defining a vec4 hook that
7636 produces an output sample, you directly define void hook
7637 which writes to a fixed writeonly image unit named
7638 out_image (this is bound by mpv) using imageStore. To
7639 help translate texture coordinates in the absence of ver‐
7640 tices, mpv provides a special function NAME_map(id) to
7641 map from the texel space of the output image to the tex‐
7642 ture coordinates for all bound textures. In particular,
7643 NAME_pos is equivalent to NAME_map(gl_GlobalInvoca‐
7644 tionID), although using this only really makes sense if
7645 (tw,th) == (bw,bh).
7646 Each bound mpv texture (via BIND) will make available the fol‐
7648 lowing definitions to that shader pass, where NAME is the name
7649 of the bound texture:
7650 vec4 NAME_tex(vec2 pos)
7652 The sampling function to use to access the texture at a
7653 certain spot (in texture coordinate space, range [0,1]).
7654 This takes care of any necessary normalization conver‐
7655 sions.
7656 vec4 NAME_texOff(vec2 offset)
7658 Sample the texture at a certain offset in pixels. This
7659 works like NAME_tex but additionally takes care of neces‐
7660 sary rotations, so that sampling at e.g. vec2(-1,0) is
7661 always one pixel to the left.
7662 vec2 NAME_pos
7664 The local texture coordinate of that texture, range
7665 [0,1].
7666 vec2 NAME_size
7668 The (rotated) size in pixels of the texture.
7669 mat2 NAME_rot
7671 The rotation matrix associated with this texture. (Ro‐
7672 tates pixel space to texture coordinates)
7673 vec2 NAME_pt
7675 The (unrotated) size of a single pixel, range [0,1].
7676 float NAME_mul
7678 The coefficient that needs to be multiplied into the tex‐
7679 ture contents in order to normalize it to the range
7680 [0,1].
7681 sampler NAME_raw
7683 The raw bound texture itself. The use of this should be
7684 avoided unless absolutely necessary.
7685 Normally, users should use either NAME_tex or NAME_texOff to
7687 read from the texture. For some shaders however , it can be bet‐
7688 ter for performance to do custom sampling from NAME_raw, in
7689 which case care needs to be taken to respect NAME_mul and
7690 NAME_rot.
7691 In addition to these parameters, the following uniforms are also
7693 globally available:
7694 float random
7696 A random number in the range [0-1], different per frame.
7697 int frame
7699 A simple count of frames rendered, increases by one per
7700 frame and never resets (regardless of seeks).
7701 vec2 input_size
7703 The size in pixels of the input image (possibly cropped
7704 and prescaled).
7705 vec2 target_size
7707 The size in pixels of the visible part of the scaled (and
7708 possibly cropped) image.
7709 vec2 tex_offset
7711 Texture offset introduced by user shaders or options like
7712 panscan, video-align-x/y, video-pan-x/y.
7713 Internally, vo_gpu may generate any number of the following tex‐
7715 tures. Whenever a texture is rendered and saved by vo_gpu, all
7716 of the passes that have hooked into it will run, in the order
7717 they were added by the user. This is a list of the legal hook
7718 points:
7719 RGB, LUMA, CHROMA, ALPHA, XYZ (resizable)
7721 Source planes (raw). Which of these fire depends on the
7722 image format of the source.
7723 CHROMA_SCALED, ALPHA_SCALED (fixed)
7725 Source planes (upscaled). These only fire on subsampled
7726 content.
7727 NATIVE (resizable)
7729 The combined image, in the source colorspace, before con‐
7730 version to RGB.
7731 MAINPRESUB (resizable)
7733 The image, after conversion to RGB, but before
7734 --blend-subtitles=video is applied.
7735 MAIN (resizable)
7737 The main image, after conversion to RGB but before up‐
7738 scaling.
7739 LINEAR (fixed)
7741 Linear light image, before scaling. This only fires when
7742 --linear-upscaling, --linear-downscaling or --sigmoid-up‐
7743 scaling is in effect.
7744 SIGMOID (fixed)
7746 Sigmoidized light, before scaling. This only fires when
7747 --sigmoid-upscaling is in effect.
7748 PREKERNEL (fixed)
7750 The image immediately before the scaler kernel runs.
7751 POSTKERNEL (fixed)
7753 The image immediately after the scaler kernel runs.
7754 SCALED (fixed)
7756 The final upscaled image, before color management.
7757 OUTPUT (fixed)
7759 The final output image, after color management but before
7760 dithering and drawing to screen.
7761 Only the textures labelled with resizable may be transformed by
7763 the pass. When overwriting a texture marked fixed, the WIDTH,
7764 HEIGHT and OFFSET must be left at their default values.
7765 --glsl-shader=<file>
7767 CLI/config file only alias for --glsl-shaders-append.
7768 --glsl-shader-opts=param1=value1,param2=value2,...
7770 Specifies the options to use for tunable shader parameters. You
7771 can target specific named shaders by prefixing the shader name
7772 with a /, e.g. shader/param=value. Without a prefix, parameters
7773 affect all shaders. The shader name is the base part of the
7774 shader filename, without the extension. (--vo=gpu-next only)
7775 --deband
7777 Enable the debanding algorithm. This greatly reduces the amount
7778 of visible banding, blocking and other quantization artifacts,
7779 at the expense of very slightly blurring some of the finest de‐
7780 tails. In practice, it's virtually always an improvement - the
7781 only reason to disable it would be for performance.
7782 --deband-iterations=<1..16>
7784 The number of debanding steps to perform per sample. Each step
7785 reduces a bit more banding, but takes time to compute. Note that
7786 the strength of each step falls off very quickly, so high num‐
7787 bers (>4) are practically useless. (Default 1)
7788 --deband-threshold=<0..4096>
7790 The debanding filter's cut-off threshold. Higher numbers in‐
7791 crease the debanding strength dramatically but progressively di‐
7792 minish image details. (Default 32)
7793 --deband-range=<1..64>
7795 The debanding filter's initial radius. The radius increases lin‐
7796 early for each iteration. A higher radius will find more gradi‐
7797 ents, but a lower radius will smooth more aggressively. (Default
7798 16)
7799 If you increase the --deband-iterations, you should probably de‐
7801 crease this to compensate.
7802 --deband-grain=<0..4096>
7804 Add some extra noise to the image. This significantly helps
7805 cover up remaining quantization artifacts. Higher numbers add
7806 more noise. (Default 48)
7807 --sharpen=<value>
7809 If set to a value other than 0, enable an unsharp masking fil‐
7810 ter. Positive values will sharpen the image (but add more ring‐
7811 ing and aliasing). Negative values will blur the image. If your
7812 GPU is powerful enough, consider alternatives like the ewa_lanc‐
7813 zossharp scale filter, or the --scale-blur option. (Only for
7814 --vo=gpu)
7815 --opengl-glfinish
7817 Call glFinish() before swapping buffers (default: disabled).
7818 Slower, but might improve results when doing framedropping. Can
7819 completely ruin performance. The details depend entirely on the
7820 OpenGL driver.
7821 --opengl-waitvsync
7823 Call glXWaitVideoSyncSGI after each buffer swap (default: dis‐
7824 abled). This may or may not help with video timing accuracy and
7825 frame drop. It's possible that this makes video output slower,
7826 or has no effect at all.
7827 X11/GLX only.
7829 --opengl-dwmflush=<no|windowed|yes|auto>
7831 Calls DwmFlush after swapping buffers on Windows (default:
7832 auto). It also sets SwapInterval(0) to ignore the OpenGL timing.
7833 Values are: no (disabled), windowed (only in windowed mode), yes
7834 (also in full screen).
7835 The value auto will try to determine whether the compositor is
7837 active, and calls DwmFlush only if it seems to be.
7838 This may help to get more consistent frame intervals, especially
7840 with high-fps clips - which might also reduce dropped frames.
7841 Typically, a value of windowed should be enough, since full
7842 screen may bypass the DWM.
7843 Windows only.
7845 --angle-d3d11-feature-level=<11_0|10_1|10_0|9_3>
7847 Selects a specific feature level when using the ANGLE backend
7848 with D3D11. By default, the highest available feature level is
7849 used. This option can be used to select a lower feature level,
7850 which is mainly useful for debugging. Note that OpenGL ES 3.0
7851 is only supported at feature level 10_1 or higher. Most ex‐
7852 tended OpenGL features will not work at lower feature levels
7853 (similar to --gpu-dumb-mode).
7854 Windows with ANGLE only.
7856 --angle-d3d11-warp=<yes|no|auto>
7858 Use WARP (Windows Advanced Rasterization Platform) when using
7859 the ANGLE backend with D3D11 (default: auto). This is a high
7860 performance software renderer. By default, it is used when the
7861 Direct3D hardware does not support Direct3D 11 feature level
7862 9_3. While the extended OpenGL features will work with WARP,
7863 they can be very slow.
7864 Windows with ANGLE only.
7866 --angle-egl-windowing=<yes|no|auto>
7868 Use ANGLE's built in EGL windowing functions to create a swap
7869 chain (default: auto). If this is set to no and the D3D11 ren‐
7870 derer is in use, ANGLE's built in swap chain will not be used
7871 and a custom swap chain that is optimized for video rendering
7872 will be created instead. If set to auto, a custom swap chain
7873 will be used for D3D11 and the built in swap chain will be used
7874 for D3D9. This option is mainly for debugging purposes, in case
7875 the custom swap chain has poor performance or does not work.
7876 If set to yes, the --angle-max-frame-latency, --an‐
7878 gle-swapchain-length and --angle-flip options will have no ef‐
7879 fect.
7880 Windows with ANGLE only.
7882 --angle-flip=<yes|no>
7884 Enable flip-model presentation, which avoids unnecessarily copy‐
7885 ing the backbuffer by sharing surfaces with the DWM (default:
7886 yes). This may cause performance issues with older drivers. If
7887 flip-model presentation is not supported (for example, on Win‐
7888 dows 7 without the platform update), mpv will automatically fall
7889 back to the older bitblt presentation model.
7890 If set to no, the --angle-swapchain-length option will have no
7892 effect.
7893 Windows with ANGLE only.
7895 --angle-renderer=<d3d9|d3d11|auto>
7897 Forces a specific renderer when using the ANGLE backend (de‐
7898 fault: auto). In auto mode this will pick D3D11 for systems that
7899 support Direct3D 11 feature level 9_3 or higher, and D3D9 other‐
7900 wise. This option is mainly for debugging purposes. Normally
7901 there is no reason to force a specific renderer, though --an‐
7902 gle-renderer=d3d9 may give slightly better performance on old
7903 hardware. Note that the D3D9 renderer only supports OpenGL ES
7904 2.0, so most extended OpenGL features will not work if this ren‐
7905 derer is selected (similar to --gpu-dumb-mode).
7906 Windows with ANGLE only.
7908 --macos-force-dedicated-gpu=<yes|no>
7910 Deactivates the automatic graphics switching and forces the ded‐
7911 icated GPU. (default: no)
7912 macOS only.
7914 --cocoa-cb-sw-renderer=<yes|no|auto>
7916 Use the Apple Software Renderer when using cocoa-cb (default:
7917 auto). If set to no the software renderer is never used and in‐
7918 stead fails when a the usual pixel format could not be created,
7919 yes will always only use the software renderer, and auto only
7920 falls back to the software renderer when the usual pixel format
7921 couldn't be created.
7922 macOS only.
7924 --cocoa-cb-10bit-context=<yes|no>
7926 Creates a 10bit capable pixel format for the context creation
7927 (default: yes). Instead of 8bit integer framebuffer a 16bit
7928 half-float framebuffer is requested.
7929 macOS only.
7931 --macos-title-bar-appearance=<appearance>
7933 Sets the appearance of the title bar (default: auto). Not all
7934 combinations of appearances and --macos-title-bar-material mate‐
7935 rials make sense or are unique. Appearances that are not sup‐
7936 ported by you current macOS version fall back to the default
7937 value. macOS and cocoa-cb only
7938 <appearance> can be one of the following:
7940 auto Detects the system settings and sets the title bar ap‐
7942 pearance appropriately. On macOS 10.14 it also detects
7943 run time changes.
7944 aqua The standard macOS Light appearance.
7946 darkAqua
7948 The standard macOS Dark appearance. (macOS 10.14+)
7949 vibrantLight
7951 Light vibrancy appearance with.
7952 vibrantDark
7954 Dark vibrancy appearance with.
7955 aquaHighContrast
7957 Light Accessibility appearance. (macOS 10.14+)
7958 darkAquaHighContrast
7960 Dark Accessibility appearance. (macOS 10.14+)
7961 vibrantLightHighContrast
7963 Light vibrancy Accessibility appearance. (macOS 10.14+)
7964 vibrantDarkHighContrast
7966 Dark vibrancy Accessibility appearance. (macOS 10.14+)
7967 --macos-title-bar-material=<material>
7969 Sets the material of the title bar (default: titlebar). All dep‐
7970 recated materials should not be used on macOS 10.14+ because
7971 their functionality is not guaranteed. Not all combinations of
7972 materials and --macos-title-bar-appearance appearances make
7973 sense or are unique. Materials that are not supported by you
7974 current macOS version fall back to the default value. macOS and
7975 cocoa-cb only
7976 <material> can be one of the following:
7978 titlebar
7980 The standard macOS titel bar material.
7981 selection
7983 The standard macOS selection material.
7984 menu The standard macOS menu material. (macOS 10.11+)
7986 popover
7988 The standard macOS popover material. (macOS 10.11+)
7989 sidebar
7991 The standard macOS sidebar material. (macOS 10.11+)
7992 headerView
7994 The standard macOS header view material. (macOS 10.14+)
7995 sheet The standard macOS sheet material. (macOS 10.14+)
7997 windowBackground
7999 The standard macOS window background material. (macOS
8000 10.14+)
8001 hudWindow
8003 The standard macOS hudWindow material. (macOS 10.14+)
8004 fullScreen
8006 The standard macOS full screen material. (macOS 10.14+)
8007 toolTip
8009 The standard macOS tool tip material. (macOS 10.14+)
8010 contentBackground
8012 The standard macOS content background material. (macOS
8013 10.14+)
8014 underWindowBackground
8016 The standard macOS under window background material.
8017 (macOS 10.14+)
8018 underPageBackground
8020 The standard macOS under page background material. (dep‐
8021 recated in macOS 10.14+)
8022 dark The standard macOS dark material. (deprecated in macOS
8024 10.14+)
8025 light The standard macOS light material. (macOS 10.14+)
8027 mediumLight
8029 The standard macOS mediumLight material. (macOS 10.11+,
8030 deprecated in macOS 10.14+)
8031 ultraDark
8033 The standard macOS ultraDark material. (macOS 10.11+
8034 deprecated in macOS 10.14+)
8035 --macos-title-bar-color=<color>
8037 Sets the color of the title bar (default: completely transpar‐
8038 ent). Is influenced by --macos-title-bar-appearance and
8039 --macos-title-bar-material. See --sub-color for color syntax.
8040 --macos-fs-animation-duration=<default|0-1000>
8042 Sets the fullscreen resize animation duration in ms (default:
8043 default). The default value is slightly less than the system's
8044 animation duration (500ms) to prevent some problems when the end
8045 of an async animation happens at the same time as the end of the
8046 system wide fullscreen animation. Setting anything higher than
8047 500ms will only prematurely cancel the resize animation after
8048 the system wide animation ended. The upper limit is still set at
8049 1000ms since it's possible that Apple or the user changes the
8050 system defaults. Anything higher than 1000ms though seems too
8051 long and shouldn't be set anyway. (macOS and cocoa-cb only)
8052 --macos-app-activation-policy=<regular|accessory|prohibited>
8054 Changes the App activation policy. With accessory the mpv icon
8055 in the Dock can be hidden. (default: regular)
8056 macOS only.
8058 --macos-geometry-calculation=<visible|whole>
8060 This changes the rectangle which is used to calculate the screen
8061 position and size of the window (default: visible). visible
8062 takes the the menu bar and Dock into account and the window is
8063 only positioned/sized within the visible screen frame rectangle,
8064 whole takes the whole screen frame rectangle and ignores the
8065 menu bar and Dock. Other previous restrictions still apply, like
8066 the window can't be placed on top of the menu bar etc.
8067 macOS only.
8069 --android-surface-size=<WxH>
8071 Set dimensions of the rendering surface used by the Android gpu
8072 context. Needs to be set by the embedding application if the
8073 dimensions change during runtime (i.e. if the device is ro‐
8074 tated), via the surfaceChanged callback.
8075 Android with --gpu-context=android only.
8077 --gpu-sw
8079 Continue even if a software renderer is detected.
8080 --gpu-context=<sys>
8082 The value auto (the default) selects the GPU context. You can
8083 also pass help to get a complete list of compiled in backends
8084 (sorted by autoprobe order).
8085 auto auto-select (default)
8087 cocoa Cocoa/macOS (deprecated, use --vo=libmpv instead)
8089 win Win32/WGL
8091 winvk VK_KHR_win32_surface
8093 angle Direct3D11 through the OpenGL ES translation layer ANGLE.
8095 This supports almost everything the win backend does (if
8096 the ANGLE build is new enough).
8097 dxinterop (experimental)
8099 Win32, using WGL for rendering and Direct3D 9Ex for pre‐
8100 sentation. Works on Nvidia and AMD. Newer Intel chips
8101 with the latest drivers may also work.
8102 d3d11 Win32, with native Direct3D 11 rendering.
8104 x11 X11/GLX
8106 x11vk VK_KHR_xlib_surface
8108 wayland
8110 Wayland/EGL
8111 waylandvk
8113 VK_KHR_wayland_surface
8114 drm DRM/EGL
8116 displayvk
8118 VK_KHR_display. This backend is roughly the Vukan equiva‐
8119 lent of DRM/EGL, allowing for direct rendering via Vulkan
8120 without a display manager.
8121 x11egl X11/EGL
8123 android
8125 Android/EGL. Requires --wid be set to an an‐
8126 droid.view.Surface.
8127 --gpu-api=<type>
8129 Controls which type of graphics APIs will be accepted:
8130 auto Use any available API (default)
8132 opengl Allow only OpenGL (requires OpenGL 2.1+ or GLES 2.0+)
8134 vulkan Allow only Vulkan (requires a valid/working --spirv-com‐
8136 piler)
8137 d3d11 Allow only --gpu-context=d3d11
8139 --opengl-es=<mode>
8141 Controls which type of OpenGL context will be accepted:
8142 auto Allow all types of OpenGL (default)
8144 yes Only allow GLES
8146 no Only allow desktop/core GL
8148 --fbo-format=<fmt>
8150 Selects the internal format of textures used for FBOs. The for‐
8151 mat can influence performance and quality of the video output.
8152 fmt can be one of: rgb8, rgb10, rgb10_a2, rgb16, rgb16f, rgb32f,
8153 rgba12, rgba16, rgba16f, rgba16hf, rgba32f.
8154 Default: auto, which first attempts to utilize 16bit float
8156 (rgba16f, rgba16hf), and falls back to rgba16 if those are not
8157 available. Finally, attempts to utilize rgb10_a2 or rgba8 if
8158 all of the previous formats are not available.
8159 --gamma-factor=<0.1..2.0>
8161 Set an additional raw gamma factor (default: 1.0). If gamma is
8162 adjusted in other ways (like with the --gamma option or key
8163 bindings and the gamma property), the value is multiplied with
8164 the other gamma value.
8165 This option is deprecated and may be removed in the future.
8167 --gamma-auto
8169 Automatically corrects the gamma value depending on ambient
8170 lighting conditions (adding a gamma boost for bright rooms).
8171 This option is deprecated and may be removed in the future.
8173 NOTE: Only implemented on macOS.
8175 --image-lut=<file>
8177 Specifies a custom LUT file (in Adobe .cube format) to apply to
8178 the colors during image decoding. The exact interpretation of
8179 the LUT depends on the value of --image-lut-type. (Only for
8180 --vo=gpu-next)
8181 --image-lut-type=<value>
8183 Controls the interpretation of color values fed to and from the
8184 LUT specified as --image-lut. Valid values are:
8185 auto Chooses the interpretation of the LUT automatically from
8187 tagged metadata, and otherwise falls back to native. (De‐
8188 fault)
8189 native Applied to the raw image contents in its native col‐
8191 orspace, before decoding to RGB. For example, for a HDR10
8192 image, this would be fed PQ-encoded YCbCr values in the
8193 range 0.0 - 1.0.
8194 normalized
8196 Applied to the normalized RGB image contents, after de‐
8197 coding from its native color encoding, but before lin‐
8198 earization.
8199 conversion
8201 Fully replaces the color decoding. A LUT of this type
8202 should ingest the image's native colorspace and output
8203 normalized non-linear RGB.
8204 --target-colorspace-hint
8206 Automatically configure the output colorspace of the display to
8207 pass through the input values of the stream (e.g. for HDR
8208 passthrough), if possible. Requires a supporting driver and
8209 --vo=gpu-next.
8210 --target-prim=<value>
8212 Specifies the primaries of the display. Video colors will be
8213 adapted to this colorspace when ICC color management is not be‐
8214 ing used. Valid values are:
8215 auto Disable any adaptation, except for atypical color spaces.
8217 Specifically, wide/unusual gamuts get automatically
8218 adapted to BT.709, while standard gamut (i.e. BT.601 and
8219 BT.709) content is not touched. (default)
8220 bt.470m
8222 ITU-R BT.470 M
8223 bt.601-525
8225 ITU-R BT.601 (525-line SD systems, eg. NTSC), SMPTE
8226 170M/240M
8227 bt.601-625
8229 ITU-R BT.601 (625-line SD systems, eg. PAL/SECAM), ITU-R
8230 BT.470 B/G
8231 bt.709 ITU-R BT.709 (HD), IEC 61966-2-4 (sRGB), SMPTE RP177 An‐
8233 nex B
8234 bt.2020
8236 ITU-R BT.2020 (UHD)
8237 apple Apple RGB
8239 adobe Adobe RGB (1998)
8241 prophoto
8243 ProPhoto RGB (ROMM)
8244 cie1931
8246 CIE 1931 RGB (not to be confused with CIE XYZ)
8247 dci-p3 DCI-P3 (Digital Cinema Colorspace), SMPTE RP431-2
8249 v-gamut
8251 Panasonic V-Gamut (VARICAM) primaries
8252 s-gamut
8254 Sony S-Gamut (S-Log) primaries
8255 --target-trc=<value>
8257 Specifies the transfer characteristics (gamma) of the display.
8258 Video colors will be adjusted to this curve when ICC color man‐
8259 agement is not being used. Valid values are:
8260 auto Disable any adaptation, except for atypical transfers.
8262 Specifically, HDR or linear light source material gets
8263 automatically converted to gamma 2.2, while SDR content
8264 is not touched. (default)
8265 bt.1886
8267 ITU-R BT.1886 curve (assuming infinite contrast)
8268 srgb IEC 61966-2-4 (sRGB)
8270 linear Linear light output
8272 gamma1.8
8274 Pure power curve (gamma 1.8), also used for Apple RGB
8275 gamma2.0
8277 Pure power curve (gamma 2.0)
8278 gamma2.2
8280 Pure power curve (gamma 2.2)
8281 gamma2.4
8283 Pure power curve (gamma 2.4)
8284 gamma2.6
8286 Pure power curve (gamma 2.6)
8287 gamma2.8
8289 Pure power curve (gamma 2.8), also used for BT.470-BG
8290 prophoto
8292 ProPhoto RGB (ROMM)
8293 pq ITU-R BT.2100 PQ (Perceptual quantizer) curve, aka SMPTE
8295 ST2084
8296 hlg ITU-R BT.2100 HLG (Hybrid Log-gamma) curve, aka ARIB
8298 STD-B67
8299 v-log Panasonic V-Log (VARICAM) curve
8301 s-log1 Sony S-Log1 curve
8303 s-log2 Sony S-Log2 curve
8305 NOTE:
8307 When using HDR output formats, mpv will encode to the speci‐
8308 fied curve but it will not set any HDMI flags or other sig‐
8309 nalling that might be required for the target device to cor‐
8310 rectly display the HDR signal. The user should independently
8311 guarantee this before using these signal formats for display.
8312 --target-peak=<auto|nits>
8314 Specifies the measured peak brightness of the output display, in
8315 cd/m^2 (AKA nits). The interpretation of this brightness depends
8316 on the configured --target-trc. In all cases, it imposes a limit
8317 on the signal values that will be sent to the display. If the
8318 source exceeds this brightness level, a tone mapping filter will
8319 be inserted. For HLG, it has the additional effect of
8320 parametrizing the inverse OOTF, in order to get colorimetrically
8321 consistent results with the mastering display. For SDR, or when
8322 using an ICC (profile (--icc-profile), setting this to a value
8323 above 203 essentially causes the display to be treated as if it
8324 were an HDR display in disguise. (See the note below)
8325 In auto mode (the default), the chosen peak is an appropriate
8327 value based on the TRC in use. For SDR curves, it uses 203. For
8328 HDR curves, it uses 203 * the transfer function's nominal peak.
8329 NOTE:
8331 When using an SDR transfer function, this is normally not
8332 needed, and setting it may lead to very unexpected results.
8333 The one time it is useful is if you want to calibrate a HDR
8334 display using traditional transfer functions and calibration
8335 equipment. In such cases, you can set your HDR display to a
8336 high brightness such as 800 cd/m^2, and then calibrate it to
8337 a standard curve like gamma2.8. Setting this value to 800
8338 would then instruct mpv to essentially treat it as an HDR
8339 display with the given peak. This may be a good alternative
8340 in environments where PQ or HLG input to the display is not
8341 possible, and makes it possible to use HDR displays with mpv
8342 regardless of operating system support for HDMI HDR metadata.
8343 In such a configuration, we highly recommend setting
8345 --tone-mapping to mobius or even clip.
8346 --target-lut=<file>
8348 Specifies a custom LUT file (in Adobe .cube format) to apply to
8349 the colors before display on-screen. This LUT is fed values in
8350 normalized RGB, after encoding into the target colorspace, so
8351 after the application of --target-trc. (Only for --vo=gpu-next)
8352 --tone-mapping=<value>
8354 Specifies the algorithm used for tone-mapping images onto the
8355 target display. This is relevant for both HDR->SDR conversion as
8356 well as gamut reduction (e.g. playing back BT.2020 content on a
8357 standard gamut display). Valid values are:
8358 auto Choose the best curve according to internal heuristics.
8360 (Default)
8361 clip Hard-clip any out-of-range values. Use this when you care
8363 about perfect color accuracy for in-range values at the
8364 cost of completely distorting out-of-range values. Not
8365 generally recommended.
8366 mobius Generalization of Reinhard to a Möbius transform with
8368 linear section. Smoothly maps out-of-range values while
8369 retaining contrast and colors for in-range material as
8370 much as possible. Use this when you care about color ac‐
8371 curacy more than detail preservation. This is somewhere
8372 in between clip and reinhard, depending on the value of
8373 --tone-mapping-param.
8374 reinhard
8376 Reinhard tone mapping algorithm. Very simple continuous
8377 curve. Preserves overall image brightness but uses non‐
8378 linear contrast, which results in flattening of details
8379 and degradation in color accuracy.
8380 hable Similar to reinhard but preserves both dark and bright
8382 details better (slightly sigmoidal), at the cost of
8383 slightly darkening / desaturating everything. Developed
8384 by John Hable for use in video games. Use this when you
8385 care about detail preservation more than color/brightness
8386 accuracy. This is roughly equivalent to --tone-map‐
8387 ping=reinhard --tone-mapping-param=0.24. If possible, you
8388 should also enable --hdr-compute-peak for the best re‐
8389 sults.
8390 bt.2390
8392 Perceptual tone mapping curve (EETF) specified in ITU-R
8393 Report BT.2390.
8394 gamma Fits a logarithmic transfer between the tone curves.
8396 linear Linearly stretches the entire reference gamut to (a lin‐
8398 ear multiple of) the display.
8399 spline Perceptually linear single-pivot polynomial.
8401 (--vo=gpu-next only)
8402 bt.2446a
8404 HDR<->SDR mapping specified in ITU-R Report BT.2446,
8405 method A. This is the recommended curve for well-mastered
8406 content. (--vo=gpu-next only)
8407 --tone-mapping-param=<value>
8409 Set tone mapping parameters. By default, this is set to the spe‐
8410 cial string default, which maps to an algorithm-specific default
8411 value. Ignored if the tone mapping algorithm is not tunable.
8412 This affects the following tone mapping algorithms:
8413 clip Specifies an extra linear coefficient to multiply into
8415 the signal before clipping. Defaults to 1.0.
8416 mobius Specifies the transition point from linear to mobius
8418 transform. Every value below this point is guaranteed to
8419 be mapped 1:1. The higher the value, the more accurate
8420 the result will be, at the cost of losing bright details.
8421 Defaults to 0.3, which due to the steep initial slope
8422 still preserves in-range colors fairly accurately.
8423 reinhard
8425 Specifies the local contrast coefficient at the display
8426 peak. Defaults to 0.5, which means that in-gamut values
8427 will be about half as bright as when clipping.
8428 bt.2390
8430 Specifies the offset for the knee point. Defaults to 1.0,
8431 which is higher than the value from the original ITU-R
8432 specification (0.5). (--vo=gpu-next only)
8433 gamma Specifies the exponent of the function. Defaults to 1.8.
8435 linear Specifies the scale factor to use while stretching. De‐
8437 faults to 1.0.
8438 spline Specifies the knee point (in PQ space). Defaults to 0.30.
8440 --inverse-tone-mapping
8442 If set, allows inverse tone mapping (expanding SDR to HDR). Not
8443 supported by all tone mapping curves. Use with caution.
8444 (--vo=gpu-next only)
8445 --tone-mapping-crosstalk=<0.0..0.30>
8447 If nonzero, apply an extra crosstalk matrix before tone mapping.
8448 Can help improve the appearance of strongly saturated monochro‐
8449 matic highlights. (Default: 0.04, only affects --vo=gpu-next)
8450 --tone-mapping-max-boost=<1.0..10.0>
8452 Upper limit for how much the tone mapping algorithm is allowed
8453 to boost the average brightness by over-exposing the image. The
8454 default value of 1.0 allows no additional brightness boost. A
8455 value of 2.0 would allow over-exposing by a factor of 2, and so
8456 on. Raising this setting can help reveal details that would oth‐
8457 erwise be hidden in dark scenes, but raising it too high will
8458 make dark scenes appear unnaturally bright. (--vo=gpu only)
8459 --tone-mapping-mode
8461 Controls how the tone mapping function is applied to colors.
8462 auto Choose the best mode automatically. (Default)
8464 rgb Tone-map per-channel (RGB). Has a tendency to severely
8466 distort colors, desaturate highlights, and is generally
8467 not very recommended. However, this is the mode used in
8468 many displays and TVs (especially early ones), and so
8469 sometimes it's needed to reproduce the artistic intent a
8470 film was mastered with.
8471 max Tone-map on the brightest component in the video. Has a
8473 tendency to lead to weirdly oversaturated colors, and
8474 loss of dark details.
8475 hybrid A hybrid approach that uses linear tone-mapping for mid‐
8477 tones and per-channel tone mapping for highlights.
8478 luma Luminance-based method from ITU-R BT.2446a, including
8480 fixed gamut reductions to account for brightness-related
8481 perceptual nonuniformity. (--vo=gpu-next only)
8482 --gamut-mapping-mode
8484 Specifies the algorithm used for reducing the gamut of images
8485 for the target display, after any tone mapping is done.
8486 auto Choose the best mode automatically. (Default)
8488 clip Hard-clip to the gamut (per-channel).
8490 warn Simply highlight out-of-gamut pixels.
8492 desaturate
8494 Chromatically desaturate out-of-gamut colors towards
8495 white.
8496 darken Linearly darken the entire image, then clip to the color
8498 volume. Unlike clip, this does not destroy detail in sat‐
8499 urated regions, but comes at the cost of sometimes sig‐
8500 nificantly lowering output brightness. (--vo=gpu-next
8501 only)
8502 --hdr-compute-peak=<auto|yes|no>
8504 Compute the HDR peak and frame average brightness per-frame in‐
8505 stead of relying on tagged metadata. These values are averaged
8506 over local regions as well as over several frames to prevent the
8507 value from jittering around too much. This option basically
8508 gives you dynamic, per-scene tone mapping. Requires compute
8509 shaders, which is a fairly recent OpenGL feature, and will prob‐
8510 ably also perform horribly on some drivers, so enable at your
8511 own risk. The special value auto (default) will enable HDR peak
8512 computation automatically if compute shaders and SSBOs are sup‐
8513 ported.
8514 --allow-delayed-peak-detect
8516 When using --hdr-compute-peak, allow delaying the detected peak
8517 by a frame when beneficial for performance. In particular, this
8518 is required to avoid an unnecessary FBO indirection when no ad‐
8519 vanced rendering is required otherwise. Has no effect if there
8520 already is an indirect pass, such as when advanced scaling is
8521 enabled. Defaults to on. (Only affects --vo=gpu-next, note that
8522 --vo=gpu always delays the peak.)
8523 --hdr-peak-decay-rate=<1.0..1000.0>
8525 The decay rate used for the HDR peak detection algorithm (de‐
8526 fault: 100.0). This is only relevant when --hdr-compute-peak is
8527 enabled. Higher values make the peak decay more slowly, leading
8528 to more stable values at the cost of more "eye adaptation"-like
8529 effects (although this is mitigated somewhat by
8530 --hdr-scene-threshold). A value of 1.0 (the lowest possible)
8531 disables all averaging, meaning each frame's value is used di‐
8532 rectly as measured, but doing this is not recommended for
8533 "noisy" sources since it may lead to excessive flicker. (In sig‐
8534 nal theory terms, this controls the time constant "tau" of an
8535 IIR low pass filter)
8536 --hdr-scene-threshold-low=<0.0..100.0>, --hdr-scene-thresh‐
8538 old-high=<0.0..100.0>
8539 The lower and upper thresholds (in dB) for a brightness differ‐
8540 ence to be considered a scene change (default: 5.5 low, 10.0
8541 high). This is only relevant when --hdr-compute-peak is enabled.
8542 Normally, small fluctuations in the frame brightness are compen‐
8543 sated for by the peak averaging mechanism, but for large jumps
8544 in the brightness this can result in the frame remaining too
8545 bright or too dark for up to several seconds, depending on the
8546 value of --hdr-peak-decay-rate. To counteract this, when the
8547 brightness between the running average and the current frame ex‐
8548 ceeds the low threshold, mpv will make the averaging filter more
8549 aggressive, up to the limit of the high threshold (at which
8550 point the filter becomes instant).
8551 --use-embedded-icc-profile
8553 Load the embedded ICC profile contained in media files such as
8554 PNG images. (Default: yes). Note that this option only works
8555 when also using a display ICC profile (--icc-profile or
8556 --icc-profile-auto), and also requires LittleCMS 2 support.
8557 --icc-profile=<file>
8559 Load an ICC profile and use it to transform video RGB to screen
8560 output. Needs LittleCMS 2 support compiled in. This option
8561 overrides the --target-prim, --target-trc and --icc-profile-auto
8562 options.
8563 --icc-profile-auto
8565 Automatically select the ICC display profile currently specified
8566 by the display settings of the operating system.
8567 NOTE: On Windows, the default profile must be an ICC profile.
8569 WCS profiles are not supported.
8570 Applications using libmpv with the render API need to provide
8572 the ICC profile via MPV_RENDER_PARAM_ICC_PROFILE.
8573 --icc-cache-dir=<dirname>
8575 Store and load the 3D LUTs created from the ICC profile in this
8576 directory. This can be used to speed up loading, since Lit‐
8577 tleCMS 2 can take a while to create a 3D LUT. Note that these
8578 files contain uncompressed LUTs. Their size depends on the
8579 --icc-3dlut-size, and can be very big.
8580 NOTE: This is not cleaned automatically, so old, unused cache
8582 files may stick around indefinitely.
8583 --icc-intent=<value>
8585 Specifies the ICC intent used for the color transformation (when
8586 using --icc-profile).
8587 0 perceptual
8589 1 relative colorimetric (default)
8591 2 saturation
8593 3 absolute colorimetric
8595 --icc-3dlut-size=<r>x<g>x<b>
8597 Size of the 3D LUT generated from the ICC profile in each dimen‐
8598 sion. Default is 64x64x64. Sizes may range from 2 to 512.
8599 --icc-force-contrast=<no|0-1000000|inf>
8601 Override the target device's detected contrast ratio by a spe‐
8602 cific value. This is detected automatically from the profile if
8603 possible, but for some profiles it might be missing, causing the
8604 contrast to be assumed as infinite. As a result, video may ap‐
8605 pear darker than intended. If this is the case, setting this op‐
8606 tion might help. This only affects BT.1886 content. The default
8607 of no means to use the profile values. The special value inf
8608 causes the BT.1886 curve to be treated as a pure power gamma 2.4
8609 function.
8610 --lut=<file>
8612 Specifies a custom LUT (in Adobe .cube format) to apply to the
8613 colors as part of color conversion. The exact interpretation de‐
8614 pends on the value of --lut-type. (Only for --vo=gpu-next)
8615 --lut-type=<value>
8617 Controls the interpretation of color values fed to and from the
8618 LUT specified as --lut. Valid values are:
8619 auto Chooses the interpretation of the LUT automatically from
8621 tagged metadata, and otherwise falls back to native. (De‐
8622 fault)
8623 native Applied to raw image contents in its native RGB col‐
8625 orspace (non-linear light), before conversion to the out‐
8626 put color space.
8627 normalized
8629 Applied to the normalized RGB image contents, in linear
8630 light, before conversion to the output color space.
8631 conversion
8633 Fully replaces the conversion from the image color space
8634 to the output color space. If such a LUT is present, it
8635 has the highest priority, and overrides any ICC profiles,
8636 as well as options related to tone mapping and output
8637 colorimetry (--target-prim, --target-trc etc.).
8638 --blend-subtitles=<yes|video|no>
8640 Blend subtitles directly onto upscaled video frames, before in‐
8641 terpolation and/or color management (default: no). Enabling this
8642 causes subtitles to be affected by --icc-profile, --target-prim,
8643 --target-trc, --interpolation, --gamma-factor and
8644 --glsl-shaders. It also increases subtitle performance when us‐
8645 ing --interpolation.
8646 The downside of enabling this is that it restricts subtitles to
8648 the visible portion of the video, so you can't have subtitles
8649 exist in the black margins below a video (for example).
8650 If video is selected, the behavior is similar to yes, but subs
8652 are drawn at the video's native resolution, and scaled along
8653 with the video.
8654 WARNING:
8656 This changes the way subtitle colors are handled. Normally,
8657 subtitle colors are assumed to be in sRGB and color managed
8658 as such. Enabling this makes them treated as being in the
8659 video's color space instead. This is good if you want things
8660 like softsubbed ASS signs to match the video colors, but may
8661 cause SRT subtitles or similar to look slightly off.
8662 --alpha=<blend-tiles|blend|yes|no>
8664 Decides what to do if the input has an alpha component.
8665 blend-tiles
8667 Blend the frame against a 16x16 gray/white tiles back‐
8668 ground (default).
8669 blend Blend the frame against the background color (--back‐
8671 ground, normally black).
8672 yes Try to create a framebuffer with alpha component. This
8674 only makes sense if the video contains alpha information
8675 (which is extremely rare) or if you make the background
8676 color transparent. May not be supported on all platforms.
8677 If alpha framebuffers are unavailable, it silently falls
8678 back on a normal framebuffer. Note that if you set the
8679 --fbo-format option to a non-default value, a format with
8680 alpha must be specified, or this won't work. Whether this
8681 really works depends on the windowing system and desktop
8682 environment.
8683 no Ignore alpha component.
8685 --opengl-rectangle-textures
8687 Force use of rectangle textures (default: no). Normally this
8688 shouldn't have any advantages over normal textures. Note that
8689 hardware decoding overrides this flag. Could be removed any
8690 time.
8691 --background=<color>
8693 Color used to draw parts of the mpv window not covered by video.
8694 See the --sub-color option for how colors are defined.
8695 --gpu-tex-pad-x, --gpu-tex-pad-y
8697 Enlarge the video source textures by this many pixels. For de‐
8698 bugging only (normally textures are sized exactly, but due to
8699 hardware decoding interop we may have to deal with additional
8700 padding, which can be tested with these options). Could be re‐
8701 moved any time.
8702 --opengl-early-flush=<yes|no|auto>
8704 Call glFlush() after rendering a frame and before attempting to
8705 display it (default: auto). Can fix stuttering in some cases, in
8706 other cases probably causes it. The auto mode will call
8707 glFlush() only if the renderer is going to wait for a while af‐
8708 ter rendering, instead of flipping GL front and backbuffers im‐
8709 mediately (i.e. it doesn't call it in display-sync mode).
8710 On macOS this is always deactivated because it only causes per‐
8712 formance problems and other regressions.
8713 --gpu-dumb-mode=<yes|no|auto>
8715 This mode is extremely restricted, and will disable most ex‐
8716 tended features. That includes high quality scalers and custom
8717 shaders!
8718 It is intended for hardware that does not support FBOs (includ‐
8720 ing GLES, which supports it insufficiently), or to get some more
8721 performance out of bad or old hardware.
8722 This mode is forced automatically if needed, and this option is
8724 mostly useful for debugging. The default of auto will enable it
8725 automatically if nothing uses features which require FBOs.
8726 This option might be silently removed in the future.
8728 --gpu-shader-cache-dir=<dirname>
8730 Store and load compiled GLSL shaders in this directory. Nor‐
8731 mally, shader compilation is very fast, so this is usually not
8732 needed. It mostly matters for GPU APIs that require internally
8733 recompiling shaders to other languages, for example anything
8734 based on ANGLE or Vulkan. Enabling this can improve startup per‐
8735 formance on these platforms.
8736 NOTE: This is not cleaned automatically, so old, unused cache
8738 files may stick around indefinitely.
8739 Miscellaneous
8741 --display-tags=tag1,tags2,...
8742 Set the list of tags that should be displayed on the terminal.
8743 Tags that are in the list, but are not present in the played
8744 file, will not be shown. If a value ends with *, all tags are
8745 matched by prefix (though there is no general globbing). Just
8746 passing * essentially filtering.
8747 The default includes a common list of tags, call mpv with
8749 --list-options to see it.
8750 This is a string list option. See List Options for details.
8752 --mc=<seconds/frame>
8754 Maximum A-V sync correction per frame (in seconds)
8755 --autosync=<factor>
8757 Gradually adjusts the A/V sync based on audio delay measure‐
8758 ments. Specifying --autosync=0, the default, will cause frame
8759 timing to be based entirely on audio delay measurements. Speci‐
8760 fying --autosync=1 will do the same, but will subtly change the
8761 A/V correction algorithm. An uneven video framerate in a video
8762 which plays fine with --no-audio can often be helped by setting
8763 this to an integer value greater than 1. The higher the value,
8764 the closer the timing will be to --no-audio. Try --autosync=30
8765 to smooth out problems with sound drivers which do not implement
8766 a perfect audio delay measurement. With this value, if large A/V
8767 sync offsets occur, they will only take about 1 or 2 seconds to
8768 settle out. This delay in reaction time to sudden A/V offsets
8769 should be the only side effect of turning this option on, for
8770 all sound drivers.
8771 --video-timing-offset=<seconds>
8773 Control how long before video display target time the frame
8774 should be rendered (default: 0.050). If a video frame should be
8775 displayed at a certain time, the VO will start rendering the
8776 frame earlier, and then will perform a blocking wait until the
8777 display time, and only then "swap" the frame to display. The
8778 rendering cannot start before the previous frame is displayed,
8779 so this value is implicitly limited by the video framerate. With
8780 normal video frame rates, the default value will ensure that
8781 rendering is always immediately started after the previous frame
8782 was displayed. On the other hand, setting a too high value can
8783 reduce responsiveness with low FPS value.
8784 This option is interesting for client API users using the render
8786 API because you can stop it from limiting your FPS (see mpv_ren‐
8787 der_context_render() documentation).
8788 This applies only to audio timing modes (e.g. --video-sync=au‐
8790 dio). In other modes (--video-sync=display-...), video timing
8791 relies on vsync blocking, and this option is not used.
8792 --video-sync=<audio|...>
8794 How the player synchronizes audio and video.
8795 If you use this option, you usually want to set it to dis‐
8797 play-resample to enable a timing mode that tries to not skip or
8798 repeat frames when for example playing 24fps video on a 24Hz
8799 screen.
8800 The modes starting with display- try to output video frames com‐
8802 pletely synchronously to the display, using the detected display
8803 vertical refresh rate as a hint how fast frames will be dis‐
8804 played on average. These modes change video speed slightly to
8805 match the display. See --video-sync-... options for fine tun‐
8806 ing. The robustness of this mode is further reduced by making a
8807 some idealized assumptions, which may not always apply in real‐
8808 ity. Behavior can depend on the VO and the system's video and
8809 audio drivers. Media files must use constant framerate. Sec‐
8810 tion-wise VFR might work as well with some container formats
8811 (but not e.g. mkv).
8812 Under some circumstances, the player automatically reverts to
8814 audio mode for some time or permanently. This can happen on very
8815 low framerate video, or if the framerate cannot be detected.
8816 Also in display-sync modes it can happen that interruptions to
8818 video playback (such as toggling fullscreen mode, or simply re‐
8819 sizing the window) will skip the video frames that should have
8820 been displayed, while audio mode will display them after the
8821 renderer has resumed (typically resulting in a short A/V desync
8822 and the video "catching up").
8823 Before mpv 0.30.0, there was a fallback to audio mode on severe
8825 A/V desync. This was changed for the sake of not sporadically
8826 stopping. Now, display-desync does what it promises and may
8827 desync with audio by an arbitrary amount, until it is manually
8828 fixed with a seek.
8829 These modes also require a vsync blocked presentation mode. For
8831 OpenGL, this translates to --opengl-swapinterval=1. For Vulkan,
8832 it translates to --vulkan-swap-mode=fifo (or fifo-relaxed).
8833 The modes with desync in their names do not attempt to keep au‐
8835 dio/video in sync. They will slowly (or quickly) desync, until
8836 e.g. the next seek happens. These modes are meant for testing,
8837 not serious use.
8838 audio Time video frames to audio. This is the most robust mode,
8840 because the player doesn't have to assume anything about
8841 how the display behaves. The disadvantage is that it can
8842 lead to occasional frame drops or repeats. If audio is
8843 disabled, this uses the system clock. This is the default
8844 mode.
8845 display-resample
8847 Resample audio to match the video. This mode will also
8848 try to adjust audio speed to compensate for other drift.
8849 (This means it will play the audio at a different speed
8850 every once in a while to reduce the A/V difference.)
8851 display-resample-vdrop
8853 Resample audio to match the video. Drop video frames to
8854 compensate for drift.
8855 display-resample-desync
8857 Like the previous mode, but no A/V compensation.
8858 display-vdrop
8860 Drop or repeat video frames to compensate desyncing
8861 video. (Although it should have the same effects as au‐
8862 dio, the implementation is very different.)
8863 display-adrop
8865 Drop or repeat audio data to compensate desyncing video.
8866 This mode will cause severe audio artifacts if the real
8867 monitor refresh rate is too different from the reported
8868 or forced rate. Since mpv 0.33.0, this acts on entire au‐
8869 dio frames, instead of single samples.
8870 display-desync
8872 Sync video to display, and let audio play on its own.
8873 desync Sync video according to system clock, and let audio play
8875 on its own.
8876 --video-sync-max-factor=<value>
8878 Maximum multiple for which to try to fit the video's FPS to the
8879 display's FPS (default: 5).
8880 For example, if this is set to 1, the video FPS is forced to an
8882 integer multiple of the display FPS, as long as the speed change
8883 does not exceed the value set by --video-sync-max-video-change.
8884 See --interpolation-threshold for how this option affects inter‐
8886 polation.
8887 This is mostly for testing, and the option may be randomly
8889 changed in the future without notice.
8890 --video-sync-max-video-change=<value>
8892 Maximum speed difference in percent that is applied to video
8893 with --video-sync=display-... (default: 1). Display sync mode
8894 will be disabled if the monitor and video refresh way do not
8895 match within the given range. It tries multiples as well: play‐
8896 ing 30 fps video on a 60 Hz screen will duplicate every second
8897 frame. Playing 24 fps video on a 60 Hz screen will play video in
8898 a 2-3-2-3-... pattern.
8899 The default settings are not loose enough to speed up 23.976 fps
8901 video to 25 fps. We consider the pitch change too extreme to al‐
8902 low this behavior by default. Set this option to a value of 5 to
8903 enable it.
8904 Note that in the --video-sync=display-resample mode, audio speed
8906 will additionally be changed by a small amount if necessary for
8907 A/V sync. See --video-sync-max-audio-change.
8908 --video-sync-max-audio-change=<value>
8910 Maximum additional speed difference in percent that is applied
8911 to audio with --video-sync=display-... (default: 0.125). Nor‐
8912 mally, the player plays the audio at the speed of the video. But
8913 if the difference between audio and video position is too high,
8914 e.g. due to drift or other timing errors, it will attempt to
8915 speed up or slow down audio by this additional factor. Too low
8916 values could lead to video frame dropping or repeating if the
8917 A/V desync cannot be compensated, too high values could lead to
8918 chaotic frame dropping due to the audio "overshooting" and skip‐
8919 ping multiple video frames before the sync logic can react.
8920 --mf-fps=<value>
8922 Framerate used when decoding from multiple PNG or JPEG files
8923 with mf:// (default: 1).
8924 --mf-type=<value>
8926 Input file type for mf:// (available: jpeg, png, tga, sgi). By
8927 default, this is guessed from the file extension.
8928 --stream-dump=<destination-filename>
8930 Instead of playing a file, read its byte stream and write it to
8931 the given destination file. The destination is overwritten. Can
8932 be useful to test network-related behavior.
8933 --stream-lavf-o=opt1=value1,opt2=value2,...
8935 Set AVOptions on streams opened with libavformat. Unknown or
8936 misspelled options are silently ignored. (They are mentioned in
8937 the terminal output in verbose mode, i.e. --v. In general we
8938 can't print errors, because other options such as e.g. user
8939 agent are not available with all protocols, and printing errors
8940 for unknown options would end up being too noisy.)
8941 This is a key/value list option. See List Options for details.
8943 --vo-mmcss-profile=<name>
8945 (Windows only.) Set the MMCSS profile for the video renderer
8946 thread (default: Playback).
8947 --priority=<prio>
8949 (Windows only.) Set process priority for mpv according to the
8950 predefined priorities available under Windows.
8951 Possible values of <prio>: idle|belownormal|normal|abovenor‐
8953 mal|high|realtime
8954 WARNING:
8956 Using realtime priority can cause system lockup.
8957 --force-media-title=<string>
8959 Force the contents of the media-title property to this value.
8960 Useful for scripts which want to set a title, without overriding
8961 the user's setting in --title.
8962 --external-files=<file-list>
8964 Load a file and add all of its tracks. This is useful to play
8965 different files together (for example audio from one file, video
8966 from another), or for advanced --lavfi-complex used (like play‐
8967 ing two video files at the same time).
8968 Unlike --sub-files and --audio-files, this includes all tracks,
8970 and does not cause default stream selection over the "proper"
8971 file. This makes it slightly less intrusive. (In mpv 0.28.0 and
8972 before, this was not quite strictly enforced.)
8973 This is a path list option. See List Options for details.
8975 --external-file=<file>
8977 CLI/config file only alias for --external-files-append. Each use
8978 of this option will add a new external file.
8979 --cover-art-files=<file-list>
8981 Use an external file as cover art while playing audio. This
8982 makes it appear on the track list and subject to automatic track
8983 selection. Options like --audio-display control whether such
8984 tracks are supposed to be selected.
8985 (The difference to loading a file with --external-files is that
8987 video tracks will be marked as being pictures, which affects the
8988 auto-selection method. If the passed file is a video, only the
8989 first frame will be decoded and displayed. Enabling the cover
8990 art track during playback may show a random frame if the source
8991 file is a video. Normally you're not supposed to pass videos to
8992 this option, so this paragraph describes the behavior coinciden‐
8993 tally resulting from implementation details.)
8994 This is a path list option. See List Options for details.
8996 --cover-art-file=<file>
8998 CLI/config file only alias for --cover-art-files-append. Each
8999 use of this option will add a new external file.
9000 --cover-art-auto=<no|exact|fuzzy|all>
9002 Whether to load _external_ cover art automatically. Similar to
9003 --sub-auto and --audio-file-auto. If a video already has tracks
9004 (which are not marked as cover art), external cover art will not
9005 be loaded.
9006 no Don't automatically load cover art.
9008 exact Load the media filename with an image file extension (de‐
9010 fault).
9011 fuzzy Load all cover art containing the media filename.
9013 all Load all images in the current directory.
9015 See --cover-art-files for details about what constitutes cover
9017 art.
9018 See --audio-display how to control display of cover art (this
9020 can be used to disable cover art that is part of the file).
9021 --cover-art-whitelist=<no|yes>
9023 Whether to load filenames in an internal whitelist, such as
9024 cover.jpg, as cover art. If cover-art-auto is set to no, the
9025 whitelisted filenames are never loaded even if this option is
9026 set to yes.
9027 Default: yes.
9029 --autoload-files=<yes|no>
9031 Automatically load/select external files (default: yes).
9032 If set to no, then do not automatically load external files as
9034 specified by --sub-auto, --audio-file-auto and --cover-art-auto.
9035 If external files are forcibly added (like with --sub-files),
9036 they will not be auto-selected.
9037 This does not affect playlist expansion, redirection, or other
9039 loading of referenced files like with ordered chapters.
9040 --record-file=<file>
9042 Deprecated, use --stream-record, or the dump-cache command.
9043 Record the current stream to the given target file. The target
9045 file will always be overwritten without asking.
9046 This was deprecated because it isn't very nice to use. For one,
9048 seeking while this is enabled will be directly reflected in the
9049 output, which was not useful and annoying.
9050 --stream-record=<file>
9052 Write received/read data from the demuxer to the given output
9053 file. The output file will always be overwritten without asking.
9054 The output format is determined by the extension of the output
9055 file.
9056 Switching streams or seeking during recording might result in
9058 recording being stopped and/or broken files. Use with care.
9059 Seeking outside of the demuxer cache will result in "skips" in
9061 the output file, but seeking within the demuxer cache should
9062 not affect recording. One exception is when you seek back far
9063 enough to exceed the forward buffering size, in which case the
9064 cache stops actively reading. This will return in dropped data
9065 if it's a live stream.
9066 If this is set at runtime, the old file is closed, and the new
9068 file is opened. Note that this will write only data that is ap‐
9069 pended at the end of the cache, and the already cached data can‐
9070 not be written. You can try the dump-cache command as an alter‐
9071 native.
9072 External files (--audio-file etc.) are ignored by this, it works
9074 on the "main" file only. Using this with files using ordered
9075 chapters or EDL files will also not work correctly in general.
9076 There are some glitches with this because it uses FFmpeg's
9078 libavformat for writing the output file. For example, it's typi‐
9079 cal that it will only work if the output format is the same as
9080 the input format. This is the case even if it works with the
9081 ffmpeg tool. One reason for this is that ffmpeg and its li‐
9082 braries contain certain hacks and workarounds for these issues,
9083 that are unavailable to outside users.
9084 This replaces --record-file. It is similar to the ancient/re‐
9086 moved --stream-capture/--capture options, and provides better
9087 behavior in most cases (i.e. actually works).
9088 --lavfi-complex=<string>
9090 Set a "complex" libavfilter filter, which means a single filter
9091 graph can take input from multiple source audio and video
9092 tracks. The graph can result in a single audio or video output
9093 (or both).
9094 Currently, the filter graph labels are used to select the par‐
9096 ticipating input tracks and audio/video output. The following
9097 rules apply:
9098 • A label of the form aidN selects audio track N as input (e.g.
9100 aid1).
9101 • A label of the form vidN selects video track N as input.
9103 • A label named ao will be connected to the audio output.
9105 • A label named vo will be connected to the video output.
9107 Each label can be used only once. If you want to use e.g. an au‐
9109 dio stream for multiple filters, you need to use the asplit fil‐
9110 ter. Multiple video or audio outputs are not possible, but you
9111 can use filters to merge them into one.
9112 It's not possible to change the tracks connected to the filter
9114 at runtime, unless you explicitly change the lavfi-complex prop‐
9115 erty and set new track assignments. When the graph is changed,
9116 the track selection is changed according to the used labels as
9117 well.
9118 Other tracks, as long as they're not connected to the filter,
9120 and the corresponding output is not connected to the filter, can
9121 still be freely changed with the normal methods.
9122 Note that the normal filter chains (--af, --vf) are applied be‐
9124 tween the complex graphs (e.g. ao label) and the actual output.
9125 Examples
9127 • --lavfi-complex='[aid1] [aid2] amix [ao]' Play audio track
9129 1 and 2 at the same time.
9130 • --lavfi-complex='[vid1] [vid2] vstack [vo]' Stack video
9132 track 1 and 2 and play them at the same time. Note that
9133 both tracks need to have the same width, or filter initial‐
9134 ization will fail (you can add scale filters before the vs‐
9135 tack filter to fix the size). To load a video track from
9136 another file, you can use --external-file=other.mkv.
9137 • --lavfi-complex='[aid1] asplit [t1] [ao] ; [t1] showvolume
9139 [t2] ; [vid1] [t2] overlay [vo]' Play audio track 1, and
9140 overlay the measured volume for each speaker over video
9141 track 1.
9142 • null:// --lavfi-complex='life [vo]' A libavfilter
9144 source-only filter (Conways' Life Game).
9145 See the FFmpeg libavfilter documentation for details on the
9147 available filters.
9148 --metadata-codepage=<codepage>
9150 Codepage for various input metadata (default: utf-8). This af‐
9151 fects how file tags, chapter titles, etc. are interpreted. You
9152 can for example set this to auto to enable autodetection of the
9153 codepage. (This is not the default because non-UTF-8 codepages
9154 are an obscure fringe use-case.)
9155 See --sub-codepage option on how codepages are specified and
9157 further details regarding autodetection and codepage conversion.
9158 (The underlying code is the same.)
9159 Conversion is not applied to metadata that is updated at run‐
9161 time.
9162 Debugging
9164 --unittest=<name>
9165 Run an internal unit test. There are multiple, and the name
9166 specifies which.
9167 The special value all-simple runs all tests which do not need
9169 further setup (other arguments and such). Some tests may need
9170 additional arguments to do anything useful.
9171 On success, the player binary exits with exit status 0, other‐
9173 wise it returns with an undefined non-0 exit status (it may
9174 crash or abort itself on test failures).
9175 This is only enabled if built with --enable-tests, and should
9177 normally be enabled and used by developers only.
9178
9180 Audio output drivers are interfaces to different audio output facili‐
9181 ties. The syntax is:
9182 --ao=<driver1,driver2,...[,]>
9184 Specify a priority list of audio output drivers to be used.
9185 If the list has a trailing ',', mpv will fall back on drivers not con‐
9187 tained in the list.
9188 NOTE:
9190 See --ao=help for a list of compiled-in audio output drivers. The
9191 driver --ao=alsa is preferred. --ao=pulse is preferred on systems
9192 where PulseAudio is used. On BSD systems, --ao=oss is preferred.
9193 Available audio output drivers are:
9195 alsa (Linux only)
9197 ALSA audio output driver
9198 See ALSA audio output options for options specific to this AO.
9200 WARNING:
9202 To get multichannel/surround audio, use --audio-chan‐
9203 nels=auto. The default for this option is auto-safe, which
9204 makes this audio output explicitly reject multichannel out‐
9205 put, as there is no way to detect whether a certain channel
9206 layout is actually supported.
9207 You can also try using the upmix plugin. This setup enables
9209 multichannel audio on the default device with automatic up‐
9210 mixing with shared access, so playing stereo and multichannel
9211 audio at the same time will work as expected.
9212 oss OSS audio output driver
9214 jack JACK (Jack Audio Connection Kit) audio output driver.
9216 The following global options are supported by this audio output:
9218 --jack-port=<name>
9220 Connects to the ports with the given name (default: phys‐
9221 ical ports).
9222 --jack-name=<client>
9224 Client name that is passed to JACK (default: mpv). Useful
9225 if you want to have certain connections established auto‐
9226 matically.
9227 --jack-autostart=<yes|no>
9229 Automatically start jackd if necessary (default: dis‐
9230 abled). Note that this tends to be unreliable and will
9231 flood stdout with server messages.
9232 --jack-connect=<yes|no>
9234 Automatically create connections to output ports (de‐
9235 fault: enabled). When enabled, the maximum number of
9236 output channels will be limited to the number of avail‐
9237 able output ports.
9238 --jack-std-channel-layout=<waveext|any>
9240 Select the standard channel layout (default: waveext).
9241 JACK itself has no notion of channel layouts (i.e. as‐
9242 signing which speaker a given channel is supposed to map
9243 to) - it just takes whatever the application outputs, and
9244 reroutes it to whatever the user defines. This means the
9245 user and the application are in charge of dealing with
9246 the channel layout. waveext uses WAVE_FORMAT_EXTENSIBLE
9247 order, which, even though it was defined by Microsoft, is
9248 the standard on many systems. The value any makes JACK
9249 accept whatever comes from the audio filter chain, re‐
9250 gardless of channel layout and without reordering. This
9251 mode is probably not very useful, other than for debug‐
9252 ging or when used with fixed setups.
9253 coreaudio (macOS only)
9255 Native macOS audio output driver using AudioUnits and the Core‐
9256 Audio sound server.
9257 Automatically redirects to coreaudio_exclusive when playing com‐
9259 pressed formats.
9260 The following global options are supported by this audio output:
9262 --coreaudio-change-physical-format=<yes|no>
9264 Change the physical format to one similar to the re‐
9265 quested audio format (default: no). This has the advan‐
9266 tage that multichannel audio output will actually work.
9267 The disadvantage is that it will change the system-wide
9268 audio settings. This is equivalent to changing the Format
9269 setting in the Audio Devices dialog in the Audio MIDI
9270 Setup utility. Note that this does not affect the se‐
9271 lected speaker setup.
9272 --coreaudio-spdif-hack=<yes|no>
9274 Try to pass through AC3/DTS data as PCM. This is useful
9275 for drivers which do not report AC3 support. It converts
9276 the AC3 data to float, and assumes the driver will do the
9277 inverse conversion, which means a typical A/V receiver
9278 will pick it up as compressed IEC framed AC3 stream, ig‐
9279 noring that it's marked as PCM. This disables normal AC3
9280 passthrough (even if the device reports it as supported).
9281 Use with extreme care.
9282 coreaudio_exclusive (macOS only)
9284 Native macOS audio output driver using direct device access and
9285 exclusive mode (bypasses the sound server).
9286 openal OpenAL audio output driver.
9288 --openal-num-buffers=<2-128>
9290 Specify the number of audio buffers to use. Lower values
9291 are better for lower CPU usage. Default: 4.
9292 --openal-num-samples=<256-32768>
9294 Specify the number of complete samples to use for each
9295 buffer. Higher values are better for lower CPU usage. De‐
9296 fault: 8192.
9297 --openal-direct-channels=<yes|no>
9299 Enable OpenAL Soft's direct channel extension when avail‐
9300 able to avoid tinting the sound with ambisonics or HRTF.
9301 Default: yes.
9302 pulse PulseAudio audio output driver
9304 The following global options are supported by this audio output:
9306 --pulse-host=<host>
9308 Specify the host to use. An empty <host> string uses a
9309 local connection, "localhost" uses network transfer (most
9310 likely not what you want).
9311 --pulse-buffer=<1-2000|native>
9313 Set the audio buffer size in milliseconds. A higher value
9314 buffers more data, and has a lower probability of buffer
9315 underruns. A smaller value makes the audio stream react
9316 faster, e.g. to playback speed changes.
9317 --pulse-latency-hacks=<yes|no>
9319 Enable hacks to workaround PulseAudio timing bugs (de‐
9320 fault: no). If enabled, mpv will do elaborate latency
9321 calculations on its own. If disabled, it will use
9322 PulseAudio automatically updated timing information. Dis‐
9323 abling this might help with e.g. networked audio or some
9324 plugins, while enabling it might help in some unknown
9325 situations (it used to be required to get good behavior
9326 on old PulseAudio versions).
9327 If you have stuttering video when using pulse, try to en‐
9329 able this option. (Or try to update PulseAudio.)
9330 --pulse-allow-suspended=<yes|no>
9332 Allow mpv to use PulseAudio even if the sink is suspended
9333 (default: no). Can be useful if PulseAudio is running as
9334 a bridge to jack and mpv has its sink-input set to the
9335 one jack is using.
9336 pipewire
9338 PipeWire audio output driver
9339 The following global options are supported by this audio output:
9341 --pipewire-buffer=<1-2000|native>
9343 Set the audio buffer size in milliseconds. A higher value
9344 buffers more data, and has a lower probability of buffer
9345 underruns. A smaller value makes the audio stream react
9346 faster, e.g. to playback speed changes.
9347 --pipewire-remote=<remote>
9349 Specify the PipeWire remote daemon name to connect to via
9350 local UNIX sockets. An empty <remote> string uses the
9351 default remote named pipewire-0.
9352 sdl SDL 1.2+ audio output driver. Should work on any platform sup‐
9354 ported by SDL 1.2, but may require the SDL_AUDIODRIVER environ‐
9355 ment variable to be set appropriately for your system.
9356 NOTE:
9358 This driver is for compatibility with extremely foreign envi‐
9359 ronments, such as systems where none of the other drivers are
9360 available.
9361 The following global options are supported by this audio output:
9363 --sdl-buflen=<length>
9365 Sets the audio buffer length in seconds. Is used only as
9366 a hint by the sound system. Playing a file with -v will
9367 show the requested and obtained exact buffer size. A
9368 value of 0 selects the sound system default.
9369 null Produces no audio output but maintains video playback speed. You
9371 can use --ao=null --ao-null-untimed for benchmarking.
9372 The following global options are supported by this audio output:
9374 --ao-null-untimed
9376 Do not simulate timing of a perfect audio device. This
9377 means audio decoding will go as fast as possible, instead
9378 of timing it to the system clock.
9379 --ao-null-buffer
9381 Simulated buffer length in seconds.
9382 --ao-null-outburst
9384 Simulated chunk size in samples.
9385 --ao-null-speed
9387 Simulated audio playback speed as a multiplier. Usually,
9388 a real audio device will not go exactly as fast as the
9389 system clock. It will deviate just a little, and this op‐
9390 tion helps to simulate this.
9391 --ao-null-latency
9393 Simulated device latency. This is additional to EOF.
9394 --ao-null-broken-eof
9396 Simulate broken audio drivers, which always add the fixed
9397 device latency to the reported audio playback position.
9398 --ao-null-broken-delay
9400 Simulate broken audio drivers, which don't report latency
9401 correctly.
9402 --ao-null-channel-layouts
9404 If not empty, this is a , separated list of channel lay‐
9405 outs the AO allows. This can be used to test channel lay‐
9406 out selection.
9407 --ao-null-format
9409 Force the audio output format the AO will accept. If un‐
9410 set accepts any.
9411 pcm Raw PCM/WAVE file writer audio output
9413 The following global options are supported by this audio output:
9415 --ao-pcm-waveheader=<yes|no>
9417 Include or do not include the WAVE header (default: in‐
9418 cluded). When not included, raw PCM will be generated.
9419 --ao-pcm-file=<filename>
9421 Write the sound to <filename> instead of the default au‐
9422 diodump.wav. If no-waveheader is specified, the default
9423 is audiodump.pcm.
9424 --ao-pcm-append=<yes|no>
9426 Append to the file, instead of overwriting it. Always use
9427 this with the no-waveheader option - with waveheader it's
9428 broken, because it will write a WAVE header every time
9429 the file is opened.
9430 sndio Audio output to the OpenBSD sndio sound system
9432 (Note: only supports mono, stereo, 4.0, 5.1 and 7.1 channel lay‐
9434 outs.)
9435 wasapi Audio output to the Windows Audio Session API.
9437
9439 Video output drivers are interfaces to different video output facili‐
9440 ties. The syntax is:
9441 --vo=<driver1,driver2,...[,]>
9443 Specify a priority list of video output drivers to be used.
9444 If the list has a trailing ,, mpv will fall back on drivers not con‐
9446 tained in the list.
9447 NOTE:
9449 See --vo=help for a list of compiled-in video output drivers.
9450 The recommended output driver is --vo=gpu, which is the default. All
9452 other drivers are for compatibility or special purposes. If the de‐
9453 fault does not work, it will fallback to other drivers (in the same
9454 order as listed by --vo=help).
9455 Available video output drivers are:
9457 gpu General purpose, customizable, GPU-accelerated video output
9459 driver. It supports extended scaling methods, dithering, color
9460 management, custom shaders, HDR, and more.
9461 See GPU renderer options for options specific to this VO.
9463 By default, it tries to use fast and fail-safe settings. Use the
9465 gpu-hq profile to use this driver with defaults set to high
9466 quality rendering. The profile can be applied with --pro‐
9467 file=gpu-hq and its contents can be viewed with --show-pro‐
9468 file=gpu-hq.
9469 This VO abstracts over several possible graphics APIs and win‐
9471 dowing contexts, which can be influenced using the --gpu-api and
9472 --gpu-context options.
9473 Hardware decoding over OpenGL-interop is supported to some de‐
9475 gree. Note that in this mode, some corner case might not be
9476 gracefully handled, and color space conversion and chroma upsam‐
9477 pling is generally in the hand of the hardware decoder APIs.
9478 gpu makes use of FBOs by default. Sometimes you can achieve bet‐
9480 ter quality or performance by changing the --fbo-format option
9481 to rgb16f, rgb32f or rgb. Known problems include Mesa/Intel not
9482 accepting rgb16, Mesa sometimes not being compiled with float
9483 texture support, and some macOS setups being very slow with
9484 rgb16 but fast with rgb32f. If you have problems, you can also
9485 try enabling the --gpu-dumb-mode=yes option.
9486 gpu-next
9488 Experimental video renderer based on libplacebo. This supports
9489 almost the same set of features as --vo=gpu. See GPU renderer
9490 options for a list.
9491 Should generally be faster and higher quality, but some features
9493 may still be missing or misbehave. Expect (and report!) bugs.
9494 See here for a list of known differences and bugs:
9495 https://github.com/mpv-player/mpv/wiki/GPU-Next-vs-GPU
9497 xv (X11 only)
9499 Uses the XVideo extension to enable hardware-accelerated dis‐
9500 play. This is the most compatible VO on X, but may be low-qual‐
9501 ity, and has issues with OSD and subtitle display.
9502 NOTE:
9504 This driver is for compatibility with old systems.
9505 The following global options are supported by this video output:
9507 --xv-adaptor=<number>
9509 Select a specific XVideo adapter (check xvinfo results).
9510 --xv-port=<number>
9512 Select a specific XVideo port.
9513 --xv-ck=<cur|use|set>
9515 Select the source from which the color key is taken (de‐
9516 fault: cur).
9517 cur The default takes the color key currently set in
9519 Xv.
9520 use Use but do not set the color key from mpv (use the
9522 --colorkey option to change it).
9523 set Same as use but also sets the supplied color key.
9525 --xv-ck-method=<none|man|bg|auto>
9527 Sets the color key drawing method (default: man).
9528 none Disables color-keying.
9530 man Draw the color key manually (reduces flicker in
9532 some cases).
9533 bg Set the color key as window background.
9535 auto Let Xv draw the color key.
9537 --xv-colorkey=<number>
9539 Changes the color key to an RGB value of your choice.
9540 0x000000 is black and 0xffffff is white.
9541 --xv-buffers=<number>
9543 Number of image buffers to use for the internal ring‐
9544 buffer (default: 2). Increasing this will use more mem‐
9545 ory, but might help with the X server not responding
9546 quickly enough if video FPS is close to or higher than
9547 the display refresh rate.
9548 x11 (X11 only)
9550 Shared memory video output driver without hardware acceleration
9551 that works whenever X11 is present.
9552 Since mpv 0.30.0, you may need to use --profile=sw-fast to get
9554 decent performance.
9555 NOTE:
9557 This is a fallback only, and should not be normally used.
9558 vdpau (X11 only)
9560 Uses the VDPAU interface to display and optionally also decode
9561 video. Hardware decoding is used with --hwdec=vdpau. Note that
9562 there is absolutely no reason to use this, other than compati‐
9563 bility. We strongly recommend that you use --vo=gpu with
9564 --hwdec=nvdec instead.
9565 NOTE:
9567 Earlier versions of mpv (and MPlayer, mplayer2) provided
9568 sub-options to tune vdpau post-processing, like deint,
9569 sharpen, denoise, chroma-deint, pullup, hqscaling. These
9570 sub-options are deprecated, and you should use the vdpaupp
9571 video filter instead.
9572 The following global options are supported by this video output:
9574 --vo-vdpau-sharpen=<-1-1>
9576 (Deprecated. See note about vdpaupp.)
9577 For positive values, apply a sharpening algorithm to the
9579 video, for negative values a blurring algorithm (default:
9580 0).
9581 --vo-vdpau-denoise=<0-1>
9583 (Deprecated. See note about vdpaupp.)
9584 Apply a noise reduction algorithm to the video (default:
9586 0; no noise reduction).
9587 --vo-vdpau-chroma-deint
9589 (Deprecated. See note about vdpaupp.)
9590 Makes temporal deinterlacers operate both on luma and
9592 chroma (default). Use no-chroma-deint to solely use luma
9593 and speed up advanced deinterlacing. Useful with slow
9594 video memory.
9595 --vo-vdpau-pullup
9597 (Deprecated. See note about vdpaupp.)
9598 Try to apply inverse telecine, needs motion adaptive tem‐
9600 poral deinterlacing.
9601 --vo-vdpau-hqscaling=<0-9>
9603 (Deprecated. See note about vdpaupp.)
9604 0 Use default VDPAU scaling (default).
9606 1-9 Apply high quality VDPAU scaling (needs capable
9608 hardware).
9609 --vo-vdpau-fps=<number>
9611 Override autodetected display refresh rate value (the
9612 value is needed for framedrop to allow video playback
9613 rates higher than display refresh rate, and for
9614 vsync-aware frame timing adjustments). Default 0 means
9615 use autodetected value. A positive value is interpreted
9616 as a refresh rate in Hz and overrides the autodetected
9617 value. A negative value disables all timing adjustment
9618 and framedrop logic.
9619 --vo-vdpau-composite-detect
9621 NVIDIA's current VDPAU implementation behaves somewhat
9622 differently under a compositing window manager and does
9623 not give accurate frame timing information. With this op‐
9624 tion enabled, the player tries to detect whether a com‐
9625 positing window manager is active. If one is detected,
9626 the player disables timing adjustments as if the user had
9627 specified fps=-1 (as they would be based on incorrect in‐
9628 put). This means timing is somewhat less accurate than
9629 without compositing, but with the composited mode behav‐
9630 ior of the NVIDIA driver, there is no hard playback speed
9631 limit even without the disabled logic. Enabled by de‐
9632 fault, use --vo-vdpau-composite-detect=no to disable.
9633 --vo-vdpau-queuetime-windowed=<number> and queuetime-fs=<number>
9635 Use VDPAU's presentation queue functionality to queue fu‐
9636 ture video frame changes at most this many milliseconds
9637 in advance (default: 50). See below for additional in‐
9638 formation.
9639 --vo-vdpau-output-surfaces=<2-15>
9641 Allocate this many output surfaces to display video
9642 frames (default: 3). See below for additional informa‐
9643 tion.
9644 --vo-vdpau-colorkey=<#RRGGBB|#AARRGGBB>
9646 Set the VDPAU presentation queue background color, which
9647 in practice is the colorkey used if VDPAU operates in
9648 overlay mode (default: #020507, some shade of black). If
9649 the alpha component of this value is 0, the default VDPAU
9650 colorkey will be used instead (which is usually green).
9651 --vo-vdpau-force-yuv
9653 Never accept RGBA input. This means mpv will insert a
9654 filter to convert to a YUV format before the VO. Some‐
9655 times useful to force availability of certain YUV-only
9656 features, like video equalizer or deinterlacing.
9657 Using the VDPAU frame queuing functionality controlled by the
9659 queuetime options makes mpv's frame flip timing less sensitive
9660 to system CPU load and allows mpv to start decoding the next
9661 frame(s) slightly earlier, which can reduce jitter caused by in‐
9662 dividual slow-to-decode frames. However, the NVIDIA graphics
9663 drivers can make other window behavior such as window moves
9664 choppy if VDPAU is using the blit queue (mainly happens if you
9665 have the composite extension enabled) and this feature is ac‐
9666 tive. If this happens on your system and it bothers you then you
9667 can set the queuetime value to 0 to disable this feature. The
9668 settings to use in windowed and fullscreen mode are separate be‐
9669 cause there should be no reason to disable this for fullscreen
9670 mode (as the driver issue should not affect the video itself).
9671 You can queue more frames ahead by increasing the queuetime val‐
9673 ues and the output_surfaces count (to ensure enough surfaces to
9674 buffer video for a certain time ahead you need at least as many
9675 surfaces as the video has frames during that time, plus two).
9676 This could help make video smoother in some cases. The main
9677 downsides are increased video RAM requirements for the surfaces
9678 and laggier display response to user commands (display changes
9679 only become visible some time after they're queued). The graph‐
9680 ics driver implementation may also have limits on the length of
9681 maximum queuing time or number of queued surfaces that work well
9682 or at all.
9683 direct3d (Windows only)
9685 Video output driver that uses the Direct3D interface.
9686 NOTE:
9688 This driver is for compatibility with systems that don't pro‐
9689 vide proper OpenGL drivers, and where ANGLE does not perform
9690 well.
9691 The following global options are supported by this video output:
9693 --vo-direct3d-disable-texture-align
9695 Normally texture sizes are always aligned to 16. With
9696 this option enabled, the video texture will always have
9697 exactly the same size as the video itself.
9698 Debug options. These might be incorrect, might be removed in the
9700 future, might crash, might cause slow downs, etc. Contact the
9701 developers if you actually need any of these for performance or
9702 proper operation.
9703 --vo-direct3d-force-power-of-2
9705 Always force textures to power of 2, even if the device
9706 reports non-power-of-2 texture sizes as supported.
9707 --vo-direct3d-texture-memory=<mode>
9709 Only affects operation with shaders/texturing enabled,
9710 and (E)OSD. Possible values:
9711 default (default)
9713 Use D3DPOOL_DEFAULT, with a D3DPOOL_SYSTEMMEM tex‐
9714 ture for locking. If the driver supports D3DDEV‐
9715 CAPS_TEXTURESYSTEMMEMORY, D3DPOOL_SYSTEMMEM is
9716 used directly.
9717 default-pool
9719 Use D3DPOOL_DEFAULT. (Like default, but never use
9720 a shadow-texture.)
9721 default-pool-shadow
9723 Use D3DPOOL_DEFAULT, with a D3DPOOL_SYSTEMMEM tex‐
9724 ture for locking. (Like default, but always force
9725 the shadow-texture.)
9726 managed
9728 Use D3DPOOL_MANAGED.
9729 scratch
9731 Use D3DPOOL_SCRATCH, with a D3DPOOL_SYSTEMMEM tex‐
9732 ture for locking.
9733 --vo-direct3d-swap-discard
9735 Use D3DSWAPEFFECT_DISCARD, which might be faster. Might
9736 be slower too, as it must(?) clear every frame.
9737 --vo-direct3d-exact-backbuffer
9739 Always resize the backbuffer to window size.
9740 sdl SDL 2.0+ Render video output driver, depending on system with or
9742 without hardware acceleration. Should work on all platforms sup‐
9743 ported by SDL 2.0. For tuning, refer to your copy of the file
9744 SDL_hints.h.
9745 NOTE:
9747 This driver is for compatibility with systems that don't pro‐
9748 vide proper graphics drivers.
9749 The following global options are supported by this video output:
9751 --sdl-sw
9753 Continue even if a software renderer is detected.
9754 --sdl-switch-mode
9756 Instruct SDL to switch the monitor video mode when going
9757 fullscreen.
9758 dmabuf-wayland
9760 Experimental Wayland output driver designed for use with either
9761 drm stateless or VA API hardware decoding. The driver is de‐
9762 signed to avoid any GPU to CPU copies, and to perform scaling
9763 and color space conversion using fixed-function hardware, if
9764 available, rather than GPU shaders. This frees up GPU resources
9765 for other tasks. Currently this driver is experimental and only
9766 works with the --hwdec=vaapi or hwdec=drm drivers; OSD is also
9767 not supported. Supported compositors : Weston and Sway.
9768 vaapi Intel VA API video output driver with support for hardware de‐
9770 coding. Note that there is absolutely no reason to use this,
9771 other than compatibility. This is low quality, and has issues
9772 with OSD. We strongly recommend that you use --vo=gpu with
9773 --hwdec=vaapi instead.
9774 The following global options are supported by this video output:
9776 --vo-vaapi-scaling=<algorithm>
9778 default
9780 Driver default (mpv default as well).
9781 fast Fast, but low quality.
9783 hq Unspecified driver dependent high-quality scaling,
9785 slow.
9786 nla non-linear anamorphic scaling
9788 --vo-vaapi-deint-mode=<mode>
9790 Select deinterlacing algorithm. Note that by default
9791 deinterlacing is initially always off, and needs to be
9792 enabled with the d key (default key binding for cycle
9793 deinterlace).
9794 This option doesn't apply if libva supports video post
9796 processing (vpp). In this case, the default for
9797 deint-mode is no, and enabling deinterlacing via user in‐
9798 teraction using the methods mentioned above actually in‐
9799 serts the vavpp video filter. If vpp is not actually sup‐
9800 ported with the libva backend in use, you can use this
9801 option to forcibly enable VO based deinterlacing.
9802 no Don't allow deinterlacing (default for newer
9804 libva).
9805 first-field
9807 Show only first field.
9808 bob bob deinterlacing (default for older libva).
9810 --vo-vaapi-scaled-osd=<yes|no>
9812 If enabled, then the OSD is rendered at video resolution
9813 and scaled to display resolution. By default, this is
9814 disabled, and the OSD is rendered at display resolution
9815 if the driver supports it.
9816 null Produces no video output. Useful for benchmarking.
9818 Usually, it's better to disable video with --no-video instead.
9820 The following global options are supported by this video output:
9822 --vo-null-fps=<value>
9824 Simulate display FPS. This artificially limits how many
9825 frames the VO accepts per second.
9826 caca Color ASCII art video output driver that works on a text con‐
9828 sole.
9829 NOTE:
9831 This driver is a joke.
9832 tct Color Unicode art video output driver that works on a text con‐
9834 sole. By default depends on support of true color by modern
9835 terminals to display the images at full color range, but
9836 256-colors output is also supported (see below). On Windows it
9837 requires an ansi terminal such as mintty.
9838 Since mpv 0.30.0, you may need to use --profile=sw-fast to get
9840 decent performance.
9841 Note: the TCT image output is not synchronized with other termi‐
9843 nal output from mpv, which can lead to broken images. The op‐
9844 tions --no-terminal or --really-quiet can help with that.
9845 --vo-tct-algo=<algo>
9847 Select how to write the pixels to the terminal.
9848 half-blocks
9850 Uses unicode LOWER HALF BLOCK character to achieve
9851 higher vertical resolution. (Default.)
9852 plain Uses spaces. Causes vertical resolution to drop
9854 twofolds, but in theory works in more places.
9855 --vo-tct-width=<width> --vo-tct-height=<height>
9857 Assume the terminal has the specified character width
9858 and/or height. These default to 80x25 if the terminal
9859 size cannot be determined.
9860 --vo-tct-256=<yes|no> (default: no)
9862 Use 256 colors - for terminals which don't support true
9863 color.
9864 sixel Graphical output for the terminal, using sixels. Tested with ml‐
9866 term and xterm.
9867 Note: the Sixel image output is not synchronized with other ter‐
9869 minal output from mpv, which can lead to broken images. The op‐
9870 tion --really-quiet can help with that, and is recommended.
9871 You may need to use --profile=sw-fast to get decent performance.
9873 Note: at the time of writing, xterm does not enable sixel by de‐
9875 fault - launching it as xterm -ti 340 is one way to enable it.
9876 Also, xterm does not display images bigger than 1000x1000 pixels
9877 by default.
9878 To render and align sixel images correctly, mpv needs to know
9880 the terminal size both in cells and in pixels. By default it
9881 tries to use values which the terminal reports, however, due to
9882 differences between terminals this is an error-prone process
9883 which cannot be automated with certainty - some terminals report
9884 the size in pixels including the padding - e.g. xterm, while
9885 others report the actual usable number of pixels - like mlterm.
9886 Additionally, they may behave differently when maximized or in
9887 fullscreen, and mpv cannot detect this state using standard
9888 methods.
9889 Sixel size and alignment options:
9891 --vo-sixel-cols=<columns>, --vo-sixel-rows=<rows> (default: 0)
9893 Specify the terminal size in character cells, otherwise
9894 (0) read it from the terminal, or fall back to 80x25.
9895 Note that mpv doesn't use the the last row with sixel be‐
9896 cause this seems to result in scrolling.
9897 --vo-sixel-width=<width>, --vo-sixel-height=<height> (default:
9899 0)
9900 Specify the available size in pixels, otherwise (0) read
9901 it from the terminal, or fall back to 320x240. Other than
9902 excluding the last line, the height is also further
9903 rounded down to a multiple of 6 (sixel unit height) to
9904 avoid overflowing below the designated size.
9905 --vo-sixel-left=<col>, --vo-sixel-top=<row> (default: 0)
9907 Specify the position in character cells where the image
9908 starts (1 is the first column or row). If 0 (default)
9909 then try to automatically determine it according to the
9910 other values and the image aspect ratio and zoom.
9911 --vo-sixel-pad-x=<pad_x>, --vo-sixel-pad-y=<pad_y> (default: -1)
9913 Used only when mpv reads the size in pixels from the ter‐
9914 minal. Specify the number of padding pixels (on one
9915 side) which are included at the size which the terminal
9916 reports. If -1 (default) then the number of pixels is
9917 rounded down to a multiple of number of cells (per axis),
9918 to take into account padding at the report - this only
9919 works correctly when the overall padding per axis is
9920 smaller than the number of cells.
9921 --vo-sixel-exit-clear=<yes|no> (default: yes)
9923 Whether or not to clear the terminal on quit. When set to
9924 no - the last sixel image stays on screen after quit,
9925 with the cursor following it.
9926 Sixel image quality options:
9928 --vo-sixel-dither=<algo>
9930 Selects the dither algorithm which libsixel should apply.
9931 Can be one of the below list as per libsixel's documenta‐
9932 tion.
9933 auto (Default)
9935 Let libsixel choose the dithering method.
9936 none Don't diffuse
9938 atkinson
9940 Diffuse with Bill Atkinson's method.
9941 fs Diffuse with Floyd-Steinberg method
9943 jajuni Diffuse with Jarvis, Judice & Ninke method
9945 stucki Diffuse with Stucki's method
9947 burkes Diffuse with Burkes' method
9949 arithmetic
9951 Positionally stable arithmetic dither
9952 xor Positionally stable arithmetic xor based dither
9954 --vo-sixel-fixedpalette=<yes|no> (default: yes)
9956 Use libsixel's built-in static palette using the XTERM256
9957 profile for dither. Fixed palette uses 256 colors for
9958 dithering. Note that using no (at the time of writing)
9959 will slow down xterm.
9960 --vo-sixel-reqcolors=<colors> (default: 256)
9962 Has no effect with fixed palette. Set up libsixel to use
9963 required number of colors for dynamic palette. This value
9964 depends on the terminal emulator as well. Xterm supports
9965 256 colors. Can set this to a lower value for faster per‐
9966 formance.
9967 --vo-sixel-threshold=<threshold> (default: -1)
9969 Has no effect with fixed palette. Defines the threshold
9970 to change the palette - as percentage of the number of
9971 colors, e.g. 20 will change the palette when the number
9972 of colors changed by 20%. It's a simple measure to reduce
9973 the number of palette changes, because it can be slow in
9974 some terminals (xterm). The default (-1) will choose a
9975 palette on every frame and will have better quality.
9976 image Output each frame into an image file in the current directory.
9978 Each file takes the frame number padded with leading zeros as
9979 name.
9980 The following global options are supported by this video output:
9982 --vo-image-format=<format>
9984 Select the image file format.
9985 jpg JPEG files, extension .jpg. (Default.)
9987 jpeg JPEG files, extension .jpeg.
9989 png PNG files.
9991 webp WebP files.
9993 --vo-image-png-compression=<0-9>
9995 PNG compression factor (speed vs. file size tradeoff)
9996 (default: 7)
9997 --vo-image-png-filter=<0-5>
9999 Filter applied prior to PNG compression (0 = none; 1 =
10000 sub; 2 = up; 3 = average; 4 = Paeth; 5 = mixed) (default:
10001 5)
10002 --vo-image-jpeg-quality=<0-100>
10004 JPEG quality factor (default: 90)
10005 --vo-image-jpeg-optimize=<0-100>
10007 JPEG optimization factor (default: 100)
10008 --vo-image-webp-lossless=<yes|no>
10010 Enable writing lossless WebP files (default: no)
10011 --vo-image-webp-quality=<0-100>
10013 WebP quality (default: 75)
10014 --vo-image-webp-compression=<0-6>
10016 WebP compression factor (default: 4)
10017 --vo-image-outdir=<dirname>
10019 Specify the directory to save the image files to (de‐
10020 fault: ./).
10021 libmpv For use with libmpv direct embedding. As a special case, on
10023 macOS it is used like a normal VO within mpv (cocoa-cb). Other‐
10024 wise useless in any other contexts. (See <mpv/render.h>.)
10025 This also supports many of the options the gpu VO has, depending
10027 on the backend.
10028 rpi (Raspberry Pi)
10030 Native video output on the Raspberry Pi using the MMAL API.
10031 This is deprecated. Use --vo=gpu instead, which is the default
10033 and provides the same functionality. The rpi VO will be removed
10034 in mpv 0.23.0. Its functionality was folded into --vo=gpu, which
10035 now uses RPI hardware decoding by treating it as a hardware
10036 overlay (without applying GL filtering). Also to be changed in
10037 0.23.0: the --fs flag will be reset to "no" by default (like on
10038 the other platforms).
10039 The following deprecated global options are supported by this
10041 video output:
10042 --rpi-display=<number>
10044 Select the display number on which the video overlay
10045 should be shown (default: 0).
10046 --rpi-layer=<number>
10048 Select the dispmanx layer on which the video overlay
10049 should be shown (default: -10). Note that mpv will also
10050 use the 2 layers above the selected layer, to handle the
10051 window background and OSD. Actual video rendering will
10052 happen on the layer above the selected layer.
10053 --rpi-background=<yes|no>
10055 Whether to render a black background behind the video
10056 (default: no). Normally it's better to kill the console
10057 framebuffer instead, which gives better performance.
10058 --rpi-osd=<yes|no>
10060 Enabled by default. If disabled with no, no OSD layer is
10061 created. This also means there will be no subtitles ren‐
10062 dered.
10063 drm (Direct Rendering Manager)
10065 Video output driver using Kernel Mode Setting / Direct Rendering
10066 Manager. Should be used when one doesn't want to install
10067 full-blown graphical environment (e.g. no X). Does not support
10068 hardware acceleration (if you need this, check the drm backend
10069 for gpu VO).
10070 Since mpv 0.30.0, you may need to use --profile=sw-fast to get
10072 decent performance.
10073 The following global options are supported by this video output:
10075 --drm-connector=[<gpu_number>.]<name>
10077 Select the connector to use (usually this is a monitor.)
10078 If <name> is empty or auto, mpv renders the output on the
10079 first available connector. Use --drm-connector=help to
10080 get a list of available connectors. The <gpu_number> ar‐
10081 gument can be used to disambiguate multiple graphic
10082 cards, but is deprecated in favor of --drm-device. (de‐
10083 fault: empty)
10084 --drm-device=<path>
10086 Select the DRM device file to use. If specified this
10087 overrides automatic card selection and any card number
10088 specified --drm-connector. (default: empty)
10089 --drm-mode=<preferred|highest|N|WxH[@R]>
10091 Mode to use (resolution and frame rate). Possible val‐
10092 ues:
10093 preferred
10095 Use the preferred mode for the screen on the se‐
10096 lected connector. (default)
10097 highest
10099 Use the mode with the highest resolution available
10100 on the selected connector.
10101 N Select mode by index.
10103 WxH[@R]
10105 Specify mode by width, height, and optionally re‐
10106 fresh rate. In case several modes match, selects
10107 the mode that comes first in the EDID list of
10108 modes.
10109 Use --drm-mode=help to get a list of available modes for
10111 all active connectors.
10112 --drm-atomic=<no|auto>
10114 Toggle use of atomic modesetting. Mostly useful for de‐
10115 bugging.
10116 no Use legacy modesetting.
10118 auto Use atomic modesetting, falling back to legacy
10120 modesetting if not available. (default)
10121 Note: Only affects gpu-context=drm. vo=drm supports
10123 legacy modesetting only.
10124 --drm-draw-plane=<primary|overlay|N>
10126 Select the DRM plane to which video and OSD is drawn to,
10127 under normal circumstances. The plane can be specified as
10128 primary, which will pick the first applicable primary
10129 plane; overlay, which will pick the first applicable
10130 overlay plane; or by index. The index is zero based, and
10131 related to the CRTC. (default: primary)
10132 When using this option with the drmprime-overlay hwdec
10134 interop, only the OSD is rendered to this plane.
10135 --drm-drmprime-video-plane=<primary|overlay|N>
10137 Select the DRM plane to use for video with the drm‐
10138 prime-overlay hwdec interop (used by e.g. the rkmpp hwdec
10139 on RockChip SoCs, and v4l2 hwdec:s on various other
10140 SoC:s). The plane is unused otherwise. This option ac‐
10141 cepts the same values as --drm-draw-plane. (default:
10142 overlay)
10143 To be able to successfully play 4K video on various SoCs
10145 you might need to set --drm-draw-plane=overlay --drm-drm‐
10146 prime-video-plane=primary and setting --drm-draw-sur‐
10147 face-size=1920x1080, to render the OSD at a lower resolu‐
10148 tion (the video when handled by the hwdec will be on the
10149 drmprime-video plane and at full 4K resolution)
10150 --drm-format=<xrgb8888|xrgb2101010>
10152 Select the DRM format to use (default: xrgb8888). This
10153 allows you to choose the bit depth of the DRM mode.
10154 xrgb8888 is your usual 24 bit per pixel/8 bits per chan‐
10155 nel packed RGB format with 8 bits of padding.
10156 xrgb2101010 is a packed 30 bits per pixel/10 bits per
10157 channel packed RGB format with 2 bits of padding.
10158 There are cases when xrgb2101010 will work with the drm
10160 VO, but not with the drm backend for the gpu VO. This is
10161 because with the gpu VO, in addition to requiring support
10162 in your DRM driver, requires support for xrgb2101010 in
10163 your EGL driver
10164 --drm-draw-surface-size=<[WxH]>
10166 Sets the size of the surface used on the draw plane. The
10167 surface will then be upscaled to the current screen reso‐
10168 lution. This option can be useful when used together with
10169 the drmprime-overlay hwdec interop at high resolutions,
10170 as it allows scaling the draw plane (which in this case
10171 only handles the OSD) down to a size the GPU can handle.
10172 When used without the drmprime-overlay hwdec interop this
10174 option will just cause the video to get rendered at a
10175 different resolution and then scaled to screen size.
10176 Note: this option is only available with DRM atomic sup‐
10178 port. (default: display resolution)
10179 --drm-vrr-enabled=<no|yes|auto>
10181 Toggle use of Variable Refresh Rate (VRR), aka Freesync
10182 or Adaptive Sync on compatible systems. VRR allows for
10183 the display to be refreshed at any rate within a range
10184 (usually ~40Hz-60Hz for 60Hz displays). This can help
10185 with playback of 24/25/50fps content. Support depends on
10186 the use of a compatible monitor, GPU, and a sufficiently
10187 new kernel with drivers that support the feature.
10188 no Do not attempt to enable VRR. (default)
10190 yes Attempt to enable VRR, whether the capability is
10192 reported or not.
10193 auto Attempt to enable VRR if support is reported.
10195 mediacodec_embed (Android)
10197 Renders IMGFMT_MEDIACODEC frames directly to an an‐
10198 droid.view.Surface. Requires --hwdec=mediacodec for hardware
10199 decoding, along with --vo=mediacodec_embed and
10200 --wid=(intptr_t)(*android.view.Surface).
10201 Since this video output driver uses native decoding and render‐
10203 ing routines, many of mpv's features (subtitle rendering,
10204 OSD/OSC, video filters, etc) are not available with this driver.
10205 To use hardware decoding with --vo=gpu instead, use --hwdec=me‐
10207 diacodec or mediacodec-copy along with --gpu-context=android.
10208 wlshm (Wayland only)
10210 Shared memory video output driver without hardware acceleration
10211 that works whenever Wayland is present.
10212 Since mpv 0.30.0, you may need to use --profile=sw-fast to get
10214 decent performance.
10215 NOTE:
10217 This is a fallback only, and should not be normally used.
10218
10220 Audio filters allow you to modify the audio stream and its properties.
10221 The syntax is:
10222 --af=...
10224 Setup a chain of audio filters. See --vf (VIDEO FILTERS) for the
10225 full syntax.
10226 NOTE:
10228 To get a full list of available audio filters, see --af=help.
10229 Also, keep in mind that most actual filters are available via the
10231 lavfi wrapper, which gives you access to most of libavfilter's fil‐
10232 ters. This includes all filters that have been ported from MPlayer
10233 to libavfilter.
10234 The --vf description describes how libavfilter can be used and how
10236 to workaround deprecated mpv filters.
10237 See --vf group of options for info on how --af-defaults, --af-add,
10239 --af-pre, --af-del, --af-clr, and possibly others work.
10240 Available filters are:
10242 lavcac3enc[=options]
10244 Encode multi-channel audio to AC-3 at runtime using libavcodec.
10245 Supports 16-bit native-endian input format, maximum 6 channels.
10246 The output is big-endian when outputting a raw AC-3 stream, na‐
10247 tive-endian when outputting to S/PDIF. If the input sample rate
10248 is not 48 kHz, 44.1 kHz or 32 kHz, it will be resampled to 48
10249 kHz.
10250 tospdif=<yes|no>
10252 Output raw AC-3 stream if no, output to S/PDIF for
10253 pass-through if yes (default).
10254 bitrate=<rate>
10256 The bitrate use for the AC-3 stream. Set it to 384 to get
10257 384 kbps.
10258 The default is 640. Some receivers might not be able to
10260 handle this.
10261 Valid values: 32, 40, 48, 56, 64, 80, 96, 112, 128, 160,
10263 192, 224, 256, 320, 384, 448, 512, 576, 640.
10264 The special value auto selects a default bitrate based on
10266 the input channel number:
10267 1ch 96
10269 2ch 192
10271 3ch 224
10273 4ch 384
10275 5ch 448
10277 6ch 448
10279 minch=<n>
10281 If the input channel number is less than <minch>, the
10282 filter will detach itself (default: 3).
10283 encoder=<name>
10285 Select the libavcodec encoder used. Currently, this
10286 should be an AC-3 encoder, and using another codec will
10287 fail horribly.
10288 format=format:srate:channels:out-srate:out-channels
10290 Does not do any format conversion itself. Rather, it may cause
10291 the filter system to insert necessary conversion filters before
10292 or after this filter if needed. It is primarily useful for con‐
10293 trolling the audio format going into other filters. To specify
10294 the format for audio output, see --audio-format, --audio-sam‐
10295 plerate, and --audio-channels. This filter is able to force a
10296 particular format, whereas --audio-* may be overridden by the ao
10297 based on output compatibility.
10298 All parameters are optional. The first 3 parameters restrict
10300 what the filter accepts as input. They will therefore cause con‐
10301 version filters to be inserted before this one. The out- param‐
10302 eters tell the filters or audio outputs following this filter
10303 how to interpret the data without actually doing a conversion.
10304 Setting these will probably just break things unless you really
10305 know you want this for some reason, such as testing or dealing
10306 with broken media.
10307 <format>
10309 Force conversion to this format. Use --af=format=for‐
10310 mat=help to get a list of valid formats.
10311 <srate>
10313 Force conversion to a specific sample rate. The rate is
10314 an integer, 48000 for example.
10315 <channels>
10317 Force mixing to a specific channel layout. See --au‐
10318 dio-channels option for possible values.
10319 <out-srate>
10321 <out-channels>
10323 NOTE: this filter used to be named force. The old format filter
10325 used to do conversion itself, unlike this one which lets the
10326 filter system handle the conversion.
10327 scaletempo[=option1:option2:...]
10329 Scales audio tempo without altering pitch, optionally synced to
10330 playback speed (default).
10331 This works by playing 'stride' ms of audio at normal speed then
10333 consuming 'stride*scale' ms of input audio. It pieces the
10334 strides together by blending 'overlap'% of stride with audio
10335 following the previous stride. It optionally performs a short
10336 statistical analysis on the next 'search' ms of audio to deter‐
10337 mine the best overlap position.
10338 scale=<amount>
10340 Nominal amount to scale tempo. Scales this amount in ad‐
10341 dition to speed. (default: 1.0)
10342 stride=<amount>
10344 Length in milliseconds to output each stride. Too high of
10345 a value will cause noticeable skips at high scale amounts
10346 and an echo at low scale amounts. Very low values will
10347 alter pitch. Increasing improves performance. (default:
10348 60)
10349 overlap=<percent>
10351 Percentage of stride to overlap. Decreasing improves per‐
10352 formance. (default: .20)
10353 search=<amount>
10355 Length in milliseconds to search for best overlap posi‐
10356 tion. Decreasing improves performance greatly. On slow
10357 systems, you will probably want to set this very low.
10358 (default: 14)
10359 speed=<tempo|pitch|both|none>
10361 Set response to speed change.
10362 tempo Scale tempo in sync with speed (default).
10364 pitch Reverses effect of filter. Scales pitch without
10366 altering tempo. Add this to your input.conf to
10367 step by musical semi-tones:
10368 [ multiply speed 0.9438743126816935
10370 ] multiply speed 1.059463094352953
10371 WARNING:
10373 Loses sync with video.
10374 both Scale both tempo and pitch.
10376 none Ignore speed changes.
10378 Examples
10380 mpv --af=scaletempo --speed=1.2 media.ogg
10382 Would play media at 1.2x normal speed, with audio at
10383 normal pitch. Changing playback speed would change au‐
10384 dio tempo to match.
10385 mpv --af=scaletempo=scale=1.2:speed=none --speed=1.2 me‐
10387 dia.ogg
10388 Would play media at 1.2x normal speed, with audio at
10389 normal pitch, but changing playback speed would have
10390 no effect on audio tempo.
10391 mpv --af=scaletempo=stride=30:overlap=.50:search=10 media.ogg
10393 Would tweak the quality and performance parameters.
10394 mpv --af=scaletempo=scale=1.2:speed=pitch audio.ogg
10396 Would play media at 1.2x normal speed, with audio at
10397 normal pitch. Changing playback speed would change
10398 pitch, leaving audio tempo at 1.2x.
10399 scaletempo2[=option1:option2:...]
10401 Scales audio tempo without altering pitch. The algorithm is
10402 ported from chromium and uses the Waveform Similarity Over‐
10403 lap-and-add (WSOLA) method. It seems to achieve a higher audio
10404 quality than scaletempo and rubberband.
10405 By default, the search-interval and window-size parameters have
10407 the same values as in chromium.
10408 min-speed=<speed>
10410 Mute audio if the playback speed is below <speed>. (de‐
10411 fault: 0.25)
10412 max-speed=<speed>
10414 Mute audio if the playback speed is above <speed> and
10415 <speed> != 0. (default: 4.0)
10416 search-interval=<amount>
10418 Length in milliseconds to search for best overlap posi‐
10419 tion. (default: 30)
10420 window-size=<amount>
10422 Length in milliseconds of the overlap-and-add window.
10423 (default: 20)
10424 rubberband
10426 High quality pitch correction with librubberband. This can be
10427 used in place of scaletempo, and will be used to adjust audio
10428 pitch when playing at speed different from normal. It can also
10429 be used to adjust audio pitch without changing playback speed.
10430 <pitch-scale>
10432 Sets the pitch scaling factor. Frequencies are multiplied
10433 by this value.
10434 This filter has a number of additional sub-options. You can list
10436 them with mpv --af=rubberband=help. This will also show the de‐
10437 fault values for each option. The options are not documented
10438 here, because they are merely passed to librubberband. Look at
10439 the librubberband documentation to learn what each option does:
10440 https://breakfastquay.com/rubberband/code-doc/classRubberBand_1_1RubberBandStretcher.html
10441 (The mapping of the mpv rubberband filter sub-option names and
10442 values to those of librubberband follows a simple pattern: "Op‐
10443 tion" + Name + Value.)
10444 This filter supports the following af-command commands:
10446 set-pitch
10448 Set the <pitch-scale> argument dynamically. This can be
10449 used to change the playback pitch at runtime. Note that
10450 speed is controlled using the standard speed property,
10451 not af-command.
10452 multiply-pitch <factor>
10454 Multiply the current value of <pitch-scale> dynamically.
10455 For example: 0.5 to go down by an octave, 1.5 to go up by
10456 a perfect fifth. If you want to go up or down by
10457 semi-tones, use 1.059463094352953 and 0.9438743126816935
10458 lavfi=graph
10460 Filter audio using FFmpeg's libavfilter.
10461 <graph>
10463 Libavfilter graph. See lavfi video filter for details -
10464 the graph syntax is the same.
10465 WARNING:
10467 Don't forget to quote libavfilter graphs as described
10468 in the lavfi video filter section.
10469 o=<string>
10471 AVOptions.
10472 fix-pts=<yes|no>
10474 Determine PTS based on sample count (default: no). If
10475 this is enabled, the player won't rely on libavfilter
10476 passing through PTS accurately. Instead, it pass a sam‐
10477 ple count as PTS to libavfilter, and compute the PTS used
10478 by mpv based on that and the input PTS. This helps with
10479 filters which output a recomputed PTS instead of the
10480 original PTS (including filters which require the PTS to
10481 start at 0). mpv normally expects filters to not touch
10482 the PTS (or only to the extent of changing frame bound‐
10483 aries), so this is not the default, but it will be needed
10484 to use broken filters. In practice, these broken filters
10485 will either cause slow A/V desync over time (with some
10486 files), or break playback completely if you seek or start
10487 playback from the middle of a file.
10488 drop This filter drops or repeats audio frames to adapt to playback
10490 speed. It always operates on full audio frames, because it was
10491 made to handle SPDIF (compressed audio passthrough). This is
10492 used automatically if the --video-sync=display-adrop option is
10493 used. Do not use this filter (or the given option); they are ex‐
10494 tremely low quality.
10495
10497 Video filters allow you to modify the video stream and its properties.
10498 All of the information described in this section applies to audio fil‐
10499 ters as well (generally using the prefix --af instead of --vf).
10500 The exact syntax is:
10502 --vf=<filter1[=parameter1:parameter2:...],filter2,...>
10504 Setup a chain of video filters. This consists on the filter
10505 name, and an option list of parameters after =. The parameters
10506 are separated by : (not ,, as that starts a new filter entry).
10507 Before the filter name, a label can be specified with @name:,
10509 where name is an arbitrary user-given name, which identifies the
10510 filter. This is only needed if you want to toggle the filter at
10511 runtime.
10512 A ! before the filter name means the filter is disabled by de‐
10514 fault. It will be skipped on filter creation. This is also use‐
10515 ful for runtime filter toggling.
10516 See the vf command (and toggle sub-command) for further explana‐
10518 tions and examples.
10519 The general filter entry syntax is:
10521 ["@"<label-name>":"] ["!"] <filter-name> [ "=" <filter-param‐
10522 eter-list> ]
10523 or for the special "toggle" syntax (see vf command):
10525 "@"<label-name>
10526 and the filter-parameter-list:
10528 <filter-parameter> | <filter-parameter> "," <filter-parame‐
10529 ter-list>
10530 and filter-parameter:
10532 ( <param-name> "=" <param-value> ) | <param-value>
10533 param-value can further be quoted in [ / ] in case the value
10535 contains characters like , or =. This is used in particular with
10536 the lavfi filter, which uses a very similar syntax as mpv
10537 (MPlayer historically) to specify filters and their parameters.
10538 Filters can be manipulated at run time. You can use @ labels as de‐
10540 scribed above in combination with the vf command (see COMMAND INTER‐
10541 FACE) to get more control over this. Initially disabled filters with !
10542 are useful for this as well.
10543 You can also set defaults for each filter. The defaults are applied be‐
10545 fore the normal filter parameters. This is deprecated and never worked
10546 for the libavfilter bridge.
10547 --vf-defaults=<filter1[=parameter1:parameter2:...],filter2,...>
10549 Set defaults for each filter. (Deprecated. --af-defaults is dep‐
10550 recated as well.)
10551 NOTE:
10553 To get a full list of available video filters, see --vf=help and
10554 https://ffmpeg.org/ffmpeg-filters.html .
10555 Also, keep in mind that most actual filters are available via the
10557 lavfi wrapper, which gives you access to most of libavfilter's fil‐
10558 ters. This includes all filters that have been ported from MPlayer
10559 to libavfilter.
10560 Most builtin filters are deprecated in some ways, unless they're
10562 only available in mpv (such as filters which deal with mpv
10563 specifics, or which are implemented in mpv only).
10564 If a filter is not builtin, the lavfi-bridge will be automatically
10566 tried. This bridge does not support help output, and does not verify
10567 parameters before the filter is actually used. Although the mpv syn‐
10568 tax is rather similar to libavfilter's, it's not the same. (Which
10569 means not everything accepted by vf_lavfi's graph option will be ac‐
10570 cepted by --vf.)
10571 You can also prefix the filter name with lavfi- to force the wrap‐
10573 per. This is helpful if the filter name collides with a deprecated
10574 mpv builtin filter. For example --vf=lavfi-scale=args would use
10575 libavfilter's scale filter over mpv's deprecated builtin one.
10576 Video filters are managed in lists. There are a few commands to manage
10578 the filter list.
10579 --vf-append=filter
10581 Appends the filter given as arguments to the filter list.
10582 --vf-add=filter
10584 Appends the filter given as arguments to the filter list. (Pass‐
10585 ing multiple filters is currently still possible, but depre‐
10586 cated.)
10587 --vf-pre=filter
10589 Prepends the filters given as arguments to the filter list.
10590 (Passing multiple filters is currently still possible, but dep‐
10591 recated.)
10592 --vf-remove=filter
10594 Deletes the filter from the list. The filter can be either given
10595 the way it was added (filter name and its full argument list),
10596 or by label (prefixed with @). Matching of filters works as fol‐
10597 lows: if either of the compared filters has a label set, only
10598 the labels are compared. If none of the filters have a label,
10599 the filter name, arguments, and argument order are compared.
10600 (Passing multiple filters is currently still possible, but dep‐
10601 recated.)
10602 -vf-toggle=filter
10604 Add the given filter to the list if it was not present yet, or
10605 remove it from the list if it was present. Matching of filters
10606 works as described in --vf-remove.
10607 --vf-del=filter
10609 Sort of like --vf-remove, but also accepts an index number. In‐
10610 dex numbers start at 0, negative numbers address the end of the
10611 list (-1 is the last). Deprecated.
10612 --vf-clr
10614 Completely empties the filter list.
10615 With filters that support it, you can access parameters by their name.
10617 --vf=<filter>=help
10619 Prints the parameter names and parameter value ranges for a par‐
10620 ticular filter.
10621 Available mpv-only filters are:
10623 format=fmt=<value>:colormatrix=<value>:...
10625 Applies video parameter overrides, with optional conversion. By
10626 default, this overrides the video's parameters without conver‐
10627 sion (except for the fmt parameter), but can be made to perform
10628 an appropriate conversion with convert=yes for parameters for
10629 which conversion is supported.
10630 <fmt> Image format name, e.g. rgb15, bgr24, 420p, etc. (de‐
10632 fault: don't change).
10633 This filter always performs conversion to the given for‐
10635 mat.
10636 NOTE:
10638 For a list of available formats, use --vf=for‐
10639 mat=fmt=help.
10640 <convert=yes|no>
10642 Force conversion of color parameters (default: no).
10643 If this is disabled (the default), the only conversion
10645 that is possibly performed is format conversion if <fmt>
10646 is set. All other parameters (like <colormatrix>) are
10647 forced without conversion. This mode is typically useful
10648 when files have been incorrectly tagged.
10649 If this is enabled, libswscale or zimg is used if any of
10651 the parameters mismatch. zimg is used of the input/output
10652 image formats are supported by mpv's zimg wrapper, and if
10653 --sws-allow-zimg=yes is used. Both libraries may not sup‐
10654 port all kinds of conversions. This typically results in
10655 silent incorrect conversion. zimg has in many cases a
10656 better chance of performing the conversion correctly.
10657 In both cases, the color parameters are set on the output
10659 stage of the image format conversion (if fmt was set).
10660 The difference is that with convert=no, the color parame‐
10661 ters are not passed on to the converter.
10662 If input and output video parameters are the same, con‐
10664 version is always skipped.
10665 Examples
10667 mpv test.mkv --vf=format:colormatrix=ycgco
10669 Results in incorrect colors (if test.mkv was
10670 tagged correctly).
10671 mpv test.mkv --vf=format:colormatrix=ycgco:convert=yes
10673 --sws-allow-zimg
10674 Results in true conversion to ycgco, assuming
10675 the renderer supports it (--vo=gpu normally
10676 does). You can add --vo=xv to force a VO which
10677 definitely does not support it, which should
10678 show incorrect colors as confirmation.
10679 Using --sws-allow-zimg=no (or disabling zimg at
10681 build time) will use libswscale, which cannot
10682 perform this conversion as of this writing.
10683 <colormatrix>
10685 Controls the YUV to RGB color space conversion when play‐
10686 ing video. There are various standards. Normally, BT.601
10687 should be used for SD video, and BT.709 for HD video.
10688 (This is done by default.) Using incorrect color space
10689 results in slightly under or over saturated and shifted
10690 colors.
10691 These options are not always supported. Different video
10693 outputs provide varying degrees of support. The gpu and
10694 vdpau video output drivers usually offer full support.
10695 The xv output can set the color space if the system video
10696 driver supports it, but not input and output levels. The
10697 scale video filter can configure color space and input
10698 levels, but only if the output format is RGB (if the
10699 video output driver supports RGB output, you can force
10700 this with -vf scale,format=rgba).
10701 If this option is set to auto (which is the default), the
10703 video's color space flag will be used. If that flag is
10704 unset, the color space will be selected automatically.
10705 This is done using a simple heuristic that attempts to
10706 distinguish SD and HD video. If the video is larger than
10707 1279x576 pixels, BT.709 (HD) will be used; otherwise
10708 BT.601 (SD) is selected.
10709 Available color spaces are:
10711 auto automatic selection (default)
10713 bt.601 ITU-R BT.601 (SD)
10715 bt.709 ITU-R BT.709 (HD)
10717 bt.2020-ncl
10719 ITU-R BT.2020 non-constant luminance system
10720 bt.2020-cl
10722 ITU-R BT.2020 constant luminance system
10723 smpte-240m
10725 SMPTE-240M
10726 <colorlevels>
10728 YUV color levels used with YUV to RGB conversion. This
10729 option is only necessary when playing broken files which
10730 do not follow standard color levels or which are flagged
10731 wrong. If the video does not specify its color range, it
10732 is assumed to be limited range.
10733 The same limitations as with <colormatrix> apply.
10735 Available color ranges are:
10737 auto automatic selection (normally limited range) (de‐
10739 fault)
10740 limited
10742 limited range (16-235 for luma, 16-240 for chroma)
10743 full full range (0-255 for both luma and chroma)
10745 <primaries>
10747 RGB primaries the source file was encoded with. Normally
10748 this should be set in the file header, but when playing
10749 broken or mistagged files this can be used to override
10750 the setting.
10751 This option only affects video output drivers that per‐
10753 form color management, for example gpu with the tar‐
10754 get-prim or icc-profile suboptions set.
10755 If this option is set to auto (which is the default), the
10757 video's primaries flag will be used. If that flag is un‐
10758 set, the color space will be selected automatically, us‐
10759 ing the following heuristics: If the <colormatrix> is set
10760 or determined as BT.2020 or BT.709, the corresponding
10761 primaries are used. Otherwise, if the video height is ex‐
10762 actly 576 (PAL), BT.601-625 is used. If it's exactly 480
10763 or 486 (NTSC), BT.601-525 is used. If the video resolu‐
10764 tion is anything else, BT.709 is used.
10765 Available primaries are:
10767 auto automatic selection (default)
10769 bt.601-525
10771 ITU-R BT.601 (SD) 525-line systems (NTSC, SMPTE-C)
10772 bt.601-625
10774 ITU-R BT.601 (SD) 625-line systems (PAL, SECAM)
10775 bt.709 ITU-R BT.709 (HD) (same primaries as sRGB)
10777 bt.2020
10779 ITU-R BT.2020 (UHD)
10780 apple Apple RGB
10782 adobe Adobe RGB (1998)
10784 prophoto
10786 ProPhoto RGB (ROMM)
10787 cie1931
10789 CIE 1931 RGB
10790 dci-p3 DCI-P3 (Digital Cinema)
10792 v-gamut
10794 Panasonic V-Gamut primaries
10795 <gamma>
10797 Gamma function the source file was encoded with. Normally
10798 this should be set in the file header, but when playing
10799 broken or mistagged files this can be used to override
10800 the setting.
10801 This option only affects video output drivers that per‐
10803 form color management.
10804 If this option is set to auto (which is the default), the
10806 gamma will be set to BT.1886 for YCbCr content, sRGB for
10807 RGB content and Linear for XYZ content.
10808 Available gamma functions are:
10810 auto automatic selection (default)
10812 bt.1886
10814 ITU-R BT.1886 (EOTF corresponding to
10815 BT.601/BT.709/BT.2020)
10816 srgb IEC 61966-2-4 (sRGB)
10818 linear Linear light
10820 gamma1.8
10822 Pure power curve (gamma 1.8)
10823 gamma2.0
10825 Pure power curve (gamma 2.0)
10826 gamma2.2
10828 Pure power curve (gamma 2.2)
10829 gamma2.4
10831 Pure power curve (gamma 2.4)
10832 gamma2.6
10834 Pure power curve (gamma 2.6)
10835 gamma2.8
10837 Pure power curve (gamma 2.8)
10838 prophoto
10840 ProPhoto RGB (ROMM) curve
10841 pq ITU-R BT.2100 PQ (Perceptual quantizer) curve
10843 hlg ITU-R BT.2100 HLG (Hybrid Log-gamma) curve
10845 v-log Panasonic V-Log transfer curve
10847 s-log1 Sony S-Log1 transfer curve
10849 s-log2 Sony S-Log2 transfer curve
10851 <sig-peak>
10853 Reference peak illumination for the video file, relative
10854 to the signal's reference white level. This is mostly in‐
10855 teresting for HDR, but it can also be used tone map SDR
10856 content to simulate a different exposure. Normally in‐
10857 ferred from tags such as MaxCLL or mastering metadata.
10858 The default of 0.0 will default to the source's nominal
10860 peak luminance.
10861 <light>
10863 Light type of the scene. This is mostly correctly in‐
10864 ferred based on the gamma function, but it can be use‐
10865 ful to override this when viewing raw camera footage
10866 (e.g. V-Log), which is normally scene-referred instead
10867 of display-referred.
10868 Available light types are:
10870 auto Automatic selection (default)
10872 display
10874 Display-referred light (most content)
10875 hlg Scene-referred using the HLG OOTF (e.g. HLG con‐
10877 tent)
10878 709-1886
10880 Scene-referred using the BT709+BT1886 interaction
10881 gamma1.2
10883 Scene-referred using a pure power OOTF (gamma=1.2)
10884 <dolbyvision=yes|no>
10886 Whether or not to include Dolby Vision metadata (default:
10887 yes). If disabled, any Dolby Vision metadata will be
10888 stripped from frames.
10889 <film-grain=yes|no>
10891 Whether or not to include film grain metadata (default:
10892 yes). If disabled, any film grain metadata will be
10893 stripped from frames.
10894 <stereo-in>
10896 Set the stereo mode the video is assumed to be encoded
10897 in. Use --vf=format:stereo-in=help to list all available
10898 modes. Check with the stereo3d filter documentation to
10899 see what the names mean.
10900 <stereo-out>
10902 Set the stereo mode the video should be displayed as.
10903 Takes the same values as the stereo-in option.
10904 <rotate>
10906 Set the rotation the video is assumed to be encoded with
10907 in degrees. The special value -1 uses the input format.
10908 <w>, <h>
10910 If not 0, perform conversion to the given size. Ignored
10911 if convert=yes is not set.
10912 <dw>, <dh>
10914 Set the display size. Note that setting the display size
10915 such that the video is scaled in both directions instead
10916 of just changing the aspect ratio is an implementation
10917 detail, and might change later.
10918 <dar> Set the display aspect ratio of the video frame. This is
10920 a float, but values such as [16:9] can be passed too
10921 ([...] for quoting to prevent the option parser from in‐
10922 terpreting the : character).
10923 <force-scaler=auto|zimg|sws>
10925 Force a specific scaler backend, if applicable. This is a
10926 debug option and could go away any time.
10927 <alpha=auto|straight|premul>
10929 Set the kind of alpha the video uses. Undefined effect if
10930 the image format has no alpha channel (could be ignored
10931 or cause an error, depending on how mpv internals
10932 evolve). Setting this may or may not cause downstream im‐
10933 age processing to treat alpha differently, depending on
10934 support. With convert and zimg used, this will convert
10935 the alpha. libswscale and other FFmpeg components com‐
10936 pletely ignore this.
10937 lavfi=graph[:sws-flags[:o=opts]]
10939 Filter video using FFmpeg's libavfilter.
10940 <graph>
10942 The libavfilter graph string. The filter must have a sin‐
10943 gle video input pad and a single video output pad.
10944 See https://ffmpeg.org/ffmpeg-filters.html for syntax and
10946 available filters.
10947 WARNING:
10949 If you want to use the full filter syntax with this
10950 option, you have to quote the filter graph in order to
10951 prevent mpv's syntax and the filter graph syntax from
10952 clashing. To prevent a quoting and escaping mess, con‐
10953 sider using --lavfi-complex if you know which video
10954 track you want to use from the input file. (There is
10955 only one video track for nearly all video files any‐
10956 way.)
10957 Examples
10959 --vf=lavfi=[gradfun=20:30,vflip]
10961 gradfun filter with nonsense parameters, fol‐
10962 lowed by a vflip filter. (This demonstrates how
10963 libavfilter takes a graph and not just a single
10964 filter.) The filter graph string is quoted with
10965 [ and ]. This requires no additional quoting or
10966 escaping with some shells (like bash), while
10967 others (like zsh) require additional " quotes
10968 around the option string.
10969 '--vf=lavfi="gradfun=20:30,vflip"'
10971 Same as before, but uses quoting that should be
10972 safe with all shells. The outer ' quotes make
10973 sure that the shell does not remove the "
10974 quotes needed by mpv.
10975 '--vf=lavfi=graph="gradfun=ra‐
10977 dius=30:strength=20,vflip"'
10978 Same as before, but uses named parameters for
10979 everything.
10980 <sws-flags>
10982 If libavfilter inserts filters for pixel format conver‐
10983 sion, this option gives the flags which should be passed
10984 to libswscale. This option is numeric and takes a
10985 bit-wise combination of SWS_ flags.
10986 See https://git.videolan.org/?p=ffmpeg.git;a=blob;f=lib‐
10988 swscale/swscale.h.
10989 <o> Set AVFilterGraph options. These should be documented by
10991 FFmpeg.
10992 Example
10994 '--vf=lavfi=yadif:o="threads=2,thread_type=slice"'
10996 forces a specific threading configuration.
10997 sub=[=bottom-margin:top-margin]
10999 Moves subtitle rendering to an arbitrary point in the filter
11000 chain, or force subtitle rendering in the video filter as op‐
11001 posed to using video output OSD support.
11002 <bottom-margin>
11004 Adds a black band at the bottom of the frame. The SSA/ASS
11005 renderer can place subtitles there (with --sub-use-mar‐
11006 gins).
11007 <top-margin>
11009 Black band on the top for toptitles (with --sub-use-mar‐
11010 gins).
11011 Examples
11013 --vf=sub,eq
11015 Moves sub rendering before the eq filter. This will
11016 put both subtitle colors and video under the influence
11017 of the video equalizer settings.
11018 vapoursynth=file:buffered-frames:concurrent-frames
11020 Loads a VapourSynth filter script. This is intended for streamed
11021 processing: mpv actually provides a source filter, instead of
11022 using a native VapourSynth video source. The mpv source will an‐
11023 swer frame requests only within a small window of frames (the
11024 size of this window is controlled with the buffered-frames pa‐
11025 rameter), and requests outside of that will return errors. As
11026 such, you can't use the full power of VapourSynth, but you can
11027 use certain filters.
11028 WARNING:
11030 Do not use this filter, unless you have expert knowledge in
11031 VapourSynth, and know how to fix bugs in the mpv VapourSynth
11032 wrapper code.
11033 If you just want to play video generated by VapourSynth (i.e.
11035 using a native VapourSynth video source), it's better to use
11036 vspipe and a pipe or FIFO to feed the video to mpv. The same ap‐
11037 plies if the filter script requires random frame access (see
11038 buffered-frames parameter).
11039 file Filename of the script source. Currently, this is always
11041 a python script (.vpy in VapourSynth convention).
11042 The variable video_in is set to the mpv video source, and
11044 it is expected that the script reads video from it. (Oth‐
11045 erwise, mpv will decode no video, and the video packet
11046 queue will overflow, eventually leading to only audio
11047 playing, or worse.)
11048 The filter graph created by the script is also expected
11050 to pass through timestamps using the _DurationNum and
11051 _DurationDen frame properties.
11052 See the end of the option list for a full list of script
11054 variables defined by mpv.
11055 Example:
11057 import vapoursynth as vs
11059 from vapoursynth import core
11060 core.std.AddBorders(video_in, 10, 10, 20, 20).set_output()
11061 WARNING:
11063 The script will be reloaded on every seek. This is
11064 done to reset the filter properly on discontinuities.
11065 buffered-frames
11067 Maximum number of decoded video frames that should be
11068 buffered before the filter (default: 4). This specifies
11069 the maximum number of frames the script can request in
11070 backward direction.
11071 E.g. if buffered-frames=5, and the script just requested
11073 frame 15, it can still request frame 10, but frame 9 is
11074 not available anymore. If it requests frame 30, mpv will
11075 decode 15 more frames, and keep only frames 25-30.
11076 The only reason why this buffer exists is to serve the
11078 random access requests the VapourSynth filter can make.
11079 The VapourSynth API has a getFrameAsync function, which
11081 takes an absolute frame number. Source filters must re‐
11082 spond to all requests. For example, a source filter can
11083 request frame 2432, and then frame 3. Source filters
11084 typically implement this by pre-indexing the entire file.
11085 mpv on the other hand is stream oriented, and does not
11087 allow filters to seek. (And it would not make sense to
11088 allow it, because it would ruin performance.) Filters get
11089 frames sequentially in playback direction, and cannot re‐
11090 quest them out of order.
11091 To compensate for this mismatch, mpv allows the filter to
11093 access frames within a certain window. buffered-frames
11094 controls the size of this window. Most VapourSynth fil‐
11095 ters happen to work with this, because mpv requests
11096 frames sequentially increasing from it, and most filters
11097 only require frames "close" to the requested frame.
11098 If the filter requests a frame that has a higher frame
11100 number than the highest buffered frame, new frames will
11101 be decoded until the requested frame number is reached.
11102 Excessive frames will be flushed out in a FIFO manner
11103 (there are only at most buffered-frames in this buffer).
11104 If the filter requests a frame that has a lower frame
11106 number than the lowest buffered frame, the request cannot
11107 be satisfied, and an error is returned to the filter.
11108 This kind of error is not supposed to happen in a
11109 "proper" VapourSynth environment. What exactly happens
11110 depends on the filters involved.
11111 Increasing this buffer will not improve performance.
11113 Rather, it will waste memory, and slow down seeks (when
11114 enough frames to fill the buffer need to be decoded at
11115 once). It is only needed to prevent the error described
11116 in the previous paragraph.
11117 How many frames a filter requires depends on filter im‐
11119 plementation details, and mpv has no way of knowing. A
11120 scale filter might need only 1 frame, an interpolation
11121 filter may require a small number of frames, and the Re‐
11122 verse filter will require an infinite number of frames.
11123 If you want reliable operation to the full extend
11125 VapourSynth is capable, use vspipe.
11126 The actual number of buffered frames also depends on the
11128 value of the concurrent-frames option. Currently, both
11129 option values are multiplied to get the final buffer
11130 size.
11131 concurrent-frames
11133 Number of frames that should be requested in parallel.
11134 The level of concurrency depends on the filter and how
11135 quickly mpv can decode video to feed the filter. This
11136 value should probably be proportional to the number of
11137 cores on your machine. Most time, making it higher than
11138 the number of cores can actually make it slower.
11139 Technically, mpv will call the VapourSynth getFrameAsync
11141 function in a loop, until there are concurrent-frames
11142 frames that have not been returned by the filter yet.
11143 This also assumes that the rest of the mpv filter chain
11144 reads the output of the vapoursynth filter quickly
11145 enough. (For example, if you pause the player, filtering
11146 will stop very soon, because the filtered frames are
11147 waiting in a queue.)
11148 Actual concurrency depends on many other factors.
11150 By default, this uses the special value auto, which sets
11152 the option to the number of detected logical CPU cores.
11153 The following .vpy script variables are defined by mpv:
11155 video_in
11157 The mpv video source as vapoursynth clip. Note that this
11158 has an incorrect (very high) length set, which confuses
11159 many filters. This is necessary, because the true number
11160 of frames is unknown. You can use the Trim filter on the
11161 clip to reduce the length.
11162 video_in_dw, video_in_dh
11164 Display size of the video. Can be different from video
11165 size if the video does not use square pixels (e.g. DVD).
11166 container_fps
11168 FPS value as reported by file headers. This value can be
11169 wrong or completely broken (e.g. 0 or NaN). Even if the
11170 value is correct, if another filter changes the real FPS
11171 (by dropping or inserting frames), the value of this
11172 variable will not be useful. Note that the --fps command
11173 line option overrides this value.
11174 Useful for some filters which insist on having a FPS.
11176 display_fps
11178 Refresh rate of the current display. Note that this value
11179 can be 0.
11180 vavpp VA-API video post processing. Requires the system to support
11182 VA-API, i.e. Linux/BSD only. Works with --vo=vaapi and --vo=gpu
11183 only. Currently deinterlaces. This filter is automatically in‐
11184 serted if deinterlacing is requested (either using the d key, by
11185 default mapped to the command cycle deinterlace, or the --dein‐
11186 terlace option).
11187 deint=<method>
11189 Select the deinterlacing algorithm.
11190 no Don't perform deinterlacing.
11192 auto Select the best quality deinterlacing algorithm
11194 (default). This goes by the order of the options
11195 as documented, with motion-compensated being con‐
11196 sidered best quality.
11197 first-field
11199 Show only first field.
11200 bob bob deinterlacing.
11202 weave, motion-adaptive, motion-compensated
11204 Advanced deinterlacing algorithms. Whether these
11205 actually work depends on the GPU hardware, the GPU
11206 drivers, driver bugs, and mpv bugs.
11207 <interlaced-only>
11209 no Deinterlace all frames (default).
11211 yes Only deinterlace frames marked as interlaced.
11213 reversal-bug=<yes|no>
11215 no Use the API as it was interpreted by older Mesa
11217 drivers. While this interpretation was more obvi‐
11218 ous and intuitive, it was apparently wrong, and
11219 not shared by Intel driver developers.
11220 yes Use Intel interpretation of surface forward and
11222 backwards references (default). This is what Intel
11223 drivers and newer Mesa drivers expect. Matters
11224 only for the advanced deinterlacing algorithms.
11225 vdpaupp
11227 VDPAU video post processing. Works with --vo=vdpau and --vo=gpu
11228 only. This filter is automatically inserted if deinterlacing is
11229 requested (either using the d key, by default mapped to the com‐
11230 mand cycle deinterlace, or the --deinterlace option). When en‐
11231 abling deinterlacing, it is always preferred over software dein‐
11232 terlacer filters if the vdpau VO is used, and also if gpu is
11233 used and hardware decoding was activated at least once (i.e. vd‐
11234 pau was loaded).
11235 sharpen=<-1-1>
11237 For positive values, apply a sharpening algorithm to the
11238 video, for negative values a blurring algorithm (default:
11239 0).
11240 denoise=<0-1>
11242 Apply a noise reduction algorithm to the video (default:
11243 0; no noise reduction).
11244 deint=<yes|no>
11246 Whether deinterlacing is enabled (default: no). If en‐
11247 abled, it will use the mode selected with deint-mode.
11248 deint-mode=<first-field|bob|temporal|temporal-spatial>
11250 Select deinterlacing mode (default: temporal).
11251 Note that there's currently a mechanism that allows the
11253 vdpau VO to change the deint-mode of auto-inserted vd‐
11254 paupp filters. To avoid confusion, it's recommended not
11255 to use the --vo=vdpau suboptions related to filtering.
11256 first-field
11258 Show only first field.
11259 bob Bob deinterlacing.
11261 temporal
11263 Motion-adaptive temporal deinterlacing. May lead
11264 to A/V desync with slow video hardware and/or high
11265 resolution.
11266 temporal-spatial
11268 Motion-adaptive temporal deinterlacing with
11269 edge-guided spatial interpolation. Needs fast
11270 video hardware.
11271 chroma-deint
11273 Makes temporal deinterlacers operate both on luma and
11274 chroma (default). Use no-chroma-deint to solely use luma
11275 and speed up advanced deinterlacing. Useful with slow
11276 video memory.
11277 pullup Try to apply inverse telecine, needs motion adaptive tem‐
11279 poral deinterlacing.
11280 interlaced-only=<yes|no>
11282 If yes, only deinterlace frames marked as interlaced (de‐
11283 fault: no).
11284 hqscaling=<0-9>
11286 0 Use default VDPAU scaling (default).
11288 1-9 Apply high quality VDPAU scaling (needs capable
11290 hardware).
11291 d3d11vpp
11293 Direct3D 11 video post processing. Currently requires D3D11
11294 hardware decoding for use.
11295 deint=<yes|no>
11297 Whether deinterlacing is enabled (default: no).
11298 interlaced-only=<yes|no>
11300 If yes, only deinterlace frames marked as interlaced (de‐
11301 fault: no).
11302 mode=<blend|bob|adaptive|mocomp|ivctc|none>
11304 Tries to select a video processor with the given process‐
11305 ing capability. If a video processor supports multiple
11306 capabilities, it is not clear which algorithm is actually
11307 selected. none always falls back. On most if not all
11308 hardware, this option will probably do nothing, because a
11309 video processor usually supports all modes or none.
11310 fingerprint=...
11312 Compute video frame fingerprints and provide them as metadata.
11313 Actually, it currently barely deserved to be called fingerprint,
11314 because it does not compute "proper" fingerprints, only tiny
11315 downscaled images (but which can be used to compute image hashes
11316 or for similarity matching).
11317 The main purpose of this filter is to support the skip-logo.lua
11319 script. If this script is dropped, or mpv ever gains a way to
11320 load user-defined filters (other than VapourSynth), this filter
11321 will be removed. Due to the "special" nature of this filter, it
11322 will be removed without warning.
11323 The intended way to read from the filter is using vf-metadata
11325 (also see clear-on-query filter parameter). The property will
11326 return a list of key/value pairs as follows:
11327 fp0.pts = 1.2345
11329 fp0.hex = 1234abcdef...bcde
11330 fp1.pts = 1.4567
11331 fp1.hex = abcdef1234...6789
11332 ...
11333 fpN.pts = ...
11334 fpN.hex = ...
11335 type = gray-hex-16x16
11336 Each fp<N> entry is for a frame. The pts entry specifies the
11338 timestamp of the frame (within the filter chain; in simple cases
11339 this is the same as the display timestamp). The hex field is the
11340 hex encoded fingerprint, whose size and meaning depend on the
11341 type filter option. The type field has the same value as the
11342 option the filter was created with.
11343 This returns the frames that were filtered since the last query
11345 of the property. If clear-on-query=no was set, a query doesn't
11346 reset the list of frames. In both cases, a maximum of 10 frames
11347 is returned. If there are more frames, the oldest frames are
11348 discarded. Frames are returned in filter order.
11349 (This doesn't return a structured list for the per-frame details
11351 because the internals of the vf-metadata mechanism suck. The re‐
11352 turned format may change in the future.)
11353 This filter uses zimg for speed and profit. However, it will
11355 fallback to libswscale in a number of situations: lesser pixel
11356 formats, unaligned data pointers or strides, or if zimg fails to
11357 initialize for unknown reasons. In these cases, the filter will
11358 use more CPU. Also, it will output different fingerprints, be‐
11359 cause libswscale cannot perform the full range expansion we nor‐
11360 mally request from zimg. As a consequence, the filter may be
11361 slower and not work correctly in random situations.
11362 type=...
11364 What fingerprint to compute. Available types are:
11365 gray-hex-8x8
11367 grayscale, 8 bit, 8x8 size
11368 gray-hex-16x16
11370 grayscale, 8 bit, 16x16 size (default)
11371 Both types simply remove all colors, downscale the image,
11373 concatenate all pixel values to a byte array, and convert
11374 the array to a hex string.
11375 clear-on-query=yes|no
11377 Clear the list of frame fingerprints if the vf-metadata
11378 property for this filter is queried (default: yes). This
11379 requires some care by the user. Some types of accesses
11380 might query the filter multiple times, which leads to
11381 lost frames.
11382 print=yes|no
11384 Print computed fingerprints to the terminal (default:
11385 no). This is mostly for testing and such. Scripts should
11386 use vf-metadata to read information from this filter in‐
11387 stead.
11388 gpu=...
11390 Convert video to RGB using the OpenGL renderer normally used
11391 with --vo=gpu. This requires that the EGL implementation sup‐
11392 ports off-screen rendering on the default display. (This is the
11393 case with Mesa.)
11394 Sub-options:
11396 w=<pixels>, h=<pixels>
11398 Size of the output in pixels (default: 0). If not posi‐
11399 tive, this will use the size of the first filtered input
11400 frame.
11401 WARNING:
11403 This is highly experimental. Performance is bad, and it will
11404 not work everywhere in the first place. Some features are not
11405 supported.
11406 WARNING:
11408 This does not do OSD rendering. If you see OSD, then it has
11409 been rendered by the VO backend. (Subtitles are rendered by
11410 the gpu filter, if possible.)
11411 WARNING:
11413 If you use this with encoding mode, keep in mind that encod‐
11414 ing mode will convert the RGB filter's output back to yuv420p
11415 in software, using the configured software scaler. Using zimg
11416 might improve this, but in any case it might go against your
11417 goals when using this filter.
11418 WARNING:
11420 Do not use this with --vo=gpu. It will apply filtering twice,
11421 since most --vo=gpu options are unconditionally applied to
11422 the gpu filter. There is no mechanism in mpv to prevent this.
11423
11425 You can encode files from one format/codec to another using this facil‐
11426 ity.
11427 --o=<filename>
11429 Enables encoding mode and specifies the output file name.
11430 --of=<format>
11432 Specifies the output format (overrides autodetection by the file
11433 name extension of the file specified by -o). See --of=help for a
11434 full list of supported formats.
11435 --ofopts=<options>
11437 Specifies the output format options for libavformat. See
11438 --ofopts=help for a full list of supported options.
11439 This is a key/value list option. See List Options for details.
11441 --ofopts-add=<option>
11443 Appends the option given as an argument to the options
11444 list. (Passing multiple options is currently still possi‐
11445 ble, but deprecated.)
11446 --ofopts=""
11448 Completely empties the options list.
11449 --oac=<codec>
11451 Specifies the output audio codec. See --oac=help for a full list
11452 of supported codecs.
11453 --oaoffset=<value>
11455 Shifts audio data by the given time (in seconds) by adding/re‐
11456 moving samples at the start. Deprecated.
11457 --oacopts=<options>
11459 Specifies the output audio codec options for libavcodec. See
11460 --oacopts=help for a full list of supported options.
11461 Example
11463 "--oac=libmp3lame --oacopts=b=128000"
11465 selects 128 kbps MP3 encoding.
11466 This is a key/value list option. See List Options for details.
11468 --oacopts-add=<option>
11470 Appends the option given as an argument to the options
11471 list. (Passing multiple options is currently still possi‐
11472 ble, but deprecated.)
11473 --oacopts=""
11475 Completely empties the options list.
11476 --oafirst
11478 Force the audio stream to become the first stream in the output.
11479 By default, the order is unspecified. Deprecated.
11480 --ovc=<codec>
11482 Specifies the output video codec. See --ovc=help for a full list
11483 of supported codecs.
11484 --ovoffset=<value>
11486 Shifts video data by the given time (in seconds) by shifting the
11487 pts values. Deprecated.
11488 --ovcopts=<options>
11490 Specifies the output video codec options for libavcodec. See
11491 --ovcopts=help for a full list of supported options.
11492 Examples
11494 "--ovc=mpeg4 --ovcopts=qscale=5"
11496 selects constant quantizer scale 5 for MPEG-4 encod‐
11497 ing.
11498 "--ovc=libx264 --ovcopts=crf=23"
11500 selects VBR quality factor 23 for H.264 encoding.
11501 This is a key/value list option. See List Options for details.
11503 --ovcopts-add=<option>
11505 Appends the option given as an argument to the options
11506 list. (Passing multiple options is currently still possi‐
11507 ble, but deprecated.)
11508 --ovcopts=""
11510 Completely empties the options list.
11511 --ovfirst
11513 Force the video stream to become the first stream in the output.
11514 By default, the order is unspecified. Deprecated.
11515 --orawts
11517 Copies input pts to the output video (not supported by some out‐
11518 put container formats, e.g. AVI). In this mode, discontinuities
11519 are not fixed and all pts are passed through as-is. Never seek
11520 backwards or use multiple input files in this mode!
11521 --no-ocopy-metadata
11523 Turns off copying of metadata from input files to output files
11524 when encoding (which is enabled by default).
11525 --oset-metadata=<metadata-tag[,metadata-tag,...]>
11527 Specifies metadata to include in the output file. Supported
11528 keys vary between output formats. For example, Matroska (MKV)
11529 and FLAC allow almost arbitrary keys, while support in MP4 and
11530 MP3 is more limited.
11531 This is a key/value list option. See List Options for details.
11533 Example
11535 "--oset-metadata=title="Output title",comment="Another tag""
11537 adds a title and a comment to the output file.
11538 --oremove-metadata=<metadata-tag[,metadata-tag,...]>
11540 Specifies metadata to exclude from the output file when copying
11541 from the input file.
11542 This is a string list option. See List Options for details.
11544 Example
11546 "--oremove-metadata=comment,genre"
11548 excludes copying of the the comment and genre tags to
11549 the output file.
11550
11552 The mpv core can be controlled with commands and properties. A number
11553 of ways to interact with the player use them: key bindings (in‐
11554 put.conf), OSD (showing information with properties), JSON IPC, the
11555 client API (libmpv), and the classic slave mode.
11556 input.conf
11558 The input.conf file consists of a list of key bindings, for example:
11559 s screenshot # take a screenshot with the s key
11561 LEFT seek 15 # map the left-arrow key to seeking forward by 15 seconds
11562 Each line maps a key to an input command. Keys are specified with their
11564 literal value (upper case if combined with Shift), or a name for spe‐
11565 cial keys. For example, a maps to the a key without shift, and A maps
11566 to a with shift.
11567 The file is located in the mpv configuration directory (normally at
11569 ~/.config/mpv/input.conf depending on platform). The default bindings
11570 are defined here:
11571 https://github.com/mpv-player/mpv/blob/master/etc/input.conf
11573 A list of special keys can be obtained with
11575 mpv --input-keylist
11576 In general, keys can be combined with Shift, Ctrl and Alt:
11578 ctrl+q quit
11580 mpv can be started in input test mode, which displays key bindings and
11582 the commands they're bound to on the OSD, instead of executing the com‐
11583 mands:
11584 mpv --input-test --force-window --idle
11586 (Only closing the window will make mpv exit, pressing normal keys will
11588 merely display the binding, even if mapped to quit.)
11589 Also see Key names.
11591 input.conf syntax
11593 [Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] <command> ( ; <command>
11594 )*
11595 Note that by default, the right Alt key can be used to create special
11597 characters, and thus does not register as a modifier. The option
11598 --no-input-right-alt-gr changes this behavior.
11599 Newlines always start a new binding. # starts a comment (outside of
11601 quoted string arguments). To bind commands to the # key, SHARP can be
11602 used.
11603 <key> is either the literal character the key produces (ASCII or Uni‐
11605 code character), or a symbolic name (as printed by --input-keylist).
11606 <section> (braced with { and }) is the input section for this command.
11608 <command> is the command itself. It consists of the command name and
11610 multiple (or none) arguments, all separated by whitespace. String argu‐
11611 ments should be quoted, typically with ". See Flat command syntax.
11612 You can bind multiple commands to one key. For example:
11614 a show-text "command 1" ; show-text "command 2"
11615 It's also possible to bind a command to a sequence of keys:
11618 a-b-c show-text "command run after a, b, c have been pressed"
11619 (This is not shown in the general command syntax.)
11622 If a or a-b or b are already bound, this will run the first command
11624 that matches, and the multi-key command will never be called. Interme‐
11625 diate keys can be remapped to ignore in order to avoid this issue. The
11626 maximum number of (non-modifier) keys for combinations is currently 4.
11627 Key names
11629 All mouse and keyboard input is to converted to mpv-specific key names.
11630 Key names are either special symbolic identifiers representing a physi‐
11631 cal key, or a text key names, which are unicode code points encoded as
11632 UTF-8. These are what keyboard input would normally produce, for exam‐
11633 ple a for the A key. As a consequence, mpv uses input translated by the
11634 current OS keyboard layout, rather than physical scan codes.
11635 Currently there is the hardcoded assumption that every text key can be
11637 represented as a single unicode code point (in NFKC form).
11638 All key names can be combined with the modifiers Shift, Ctrl, Alt,
11640 Meta. They must be prefixed to the actual key name, where each modifier
11641 is followed by a + (for example ctrl+q).
11642 The Shift modifier requires some attention. For instance Shift+2 should
11644 usually be specified as key-name @ at input.conf, and similarly the
11645 combination Alt+Shift+2 is usually Alt+@, etc. Special key names like
11646 Shift+LEFT work as expected. If in doubt - use --input-test to check
11647 how a key/combination is seen by mpv.
11648 Symbolic key names and modifier names are case-insensitive. Unicode key
11650 names are case-sensitive because input bindings typically respect the
11651 shift key.
11652 Another type of key names are hexadecimal key names, that serve as
11654 fallback for special keys that are neither unicode, nor have a special
11655 mpv defined name. They will break as soon as mpv adds proper names for
11656 them, but can enable you to use a key at all if that does not happen.
11657 All symbolic names are listed by --input-keylist. --input-test is a
11659 special mode that prints all input on the OSD.
11660 Comments on some symbolic names:
11662 KP* Keypad names. Behavior varies by backend (whether they implement
11664 this, and on how they treat numlock), but typically, mpv tries
11665 to map keys on the keypad to separate names, even if they pro‐
11666 duce the same text as normal keys.
11667 MOUSE_BTN*, MBTN*
11669 Various mouse buttons.
11670 Depending on backend, the mouse wheel might also be represented
11672 as a button. In addition, MOUSE_BTN3 to MOUSE_BTN6 are depre‐
11673 cated aliases for WHEEL_UP, WHEEL_DOWN, WHEEL_LEFT, WHEEL_RIGHT.
11674 MBTN* are aliases for MOUSE_BTN*.
11676 WHEEL_*
11678 Mouse wheels (typically).
11679 AXIS_* Deprecated aliases for WHEEL_*.
11681 *_DBL Mouse button double clicks.
11683 MOUSE_MOVE, MOUSE_ENTER, MOUSE_LEAVE
11685 Emitted by mouse move events. Enter/leave happens when the mouse
11686 enters or leave the mpv window (or the current mouse region, us‐
11687 ing the deprecated mouse region input section mechanism).
11688 CLOSE_WIN
11690 Pseudo key emitted when closing the mpv window using the OS win‐
11691 dow manager (for example, by clicking the close button in the
11692 window title bar).
11693 GAMEPAD_*
11695 Keys emitted by the SDL gamepad backend.
11696 UNMAPPED
11698 Pseudo-key that matches any unmapped key. (You should probably
11699 avoid this if possible, because it might change behavior or get
11700 removed in the future.)
11701 ANY_UNICODE
11703 Pseudo-key that matches any key that produces text. (You should
11704 probably avoid this if possible, because it might change behav‐
11705 ior or get removed in the future.)
11706 Flat command syntax
11708 This is the syntax used in input.conf, and referred to "input.conf syn‐
11709 tax" in a number of other places.
11710 <command> ::= [<prefixes>] <command_name> (<argument>)*
11712 <argument> ::= (<unquoted> | " <double_quoted> " | ' <single_quoted> ' | `X <custom_quoted> X`)
11713 command_name is an unquoted string with the command name itself. See
11716 List of Input Commands for a list.
11717 Arguments are separated by whitespaces even if the command expects only
11719 one argument. Arguments with whitespaces or other special characters
11720 must be quoted, or the command cannot be parsed correctly.
11721 Double quotes interpret JSON/C-style escaping, like \t or \" or \\.
11723 JSON escapes according to RFC 8259, minus surrogate pair escapes. This
11724 is the only form which allows newlines at the value - as \n.
11725 Single quotes take the content literally, and cannot include the sin‐
11727 gle-quote character at the value.
11728 Custom quotes also take the content literally, but are more flexible
11730 than single quotes. They start with ` (back-quote) followed by any
11731 ASCII character, and end at the first occurance of the same pair in re‐
11732 verse order, e.g. `-foo-` or ``bar``. The final pair sequence is not
11733 allowed at the value - in these examples -` and `` respectively. In the
11734 second example the last character of the value also can't be a
11735 back-quote.
11736 Mixed quoting at the same argument, like 'foo'"bar", is not supported.
11738 Note that argument parsing and property expansion happen at different
11740 stages. First, arguments are determined as described above, and then,
11741 where applicable, properties are expanded - regardless of argument
11742 quoting. However, expansion can still be prevented with the raw prefix
11743 or $>. See Input Command Prefixes and Property Expansion.
11744 Commands specified as arrays
11746 This applies to certain APIs, such as mp.commandv() or mp.command_na‐
11747 tive() (with array parameters) in Lua scripting, or mpv_command() or
11748 mpv_command_node() (with MPV_FORMAT_NODE_ARRAY) in the C libmpv client
11749 API.
11750 The command as well as all arguments are passed as a single array. Sim‐
11752 ilar to the Flat command syntax, you can first pass prefixes as strings
11753 (each as separate array item), then the command name as string, and
11754 then each argument as string or a native value.
11755 Since these APIs pass arguments as separate strings or native values,
11757 they do not expect quotes, and do support escaping. Technically, there
11758 is the input.conf parser, which first splits the command string into
11759 arguments, and then invokes argument parsers for each argument. The in‐
11760 put.conf parser normally handles quotes and escaping. The array command
11761 APIs mentioned above pass strings directly to the argument parsers, or
11762 can sidestep them by the ability to pass non-string values.
11763 Property expansion is disabled by default for these APIs. This can be
11765 changed with the expand-properties prefix. See Input Command Prefixes.
11766 Sometimes commands have string arguments, that in turn are actually
11768 parsed by other components (e.g. filter strings with vf add) - in these
11769 cases, you you would have to double-escape in input.conf, but not with
11770 the array APIs.
11771 For complex commands, consider using Named arguments instead, which
11773 should give slightly more compatibility. Some commands do not support
11774 named arguments and inherently take an array, though.
11775 Named arguments
11777 This applies to certain APIs, such as mp.command_native() (with tables
11778 that have string keys) in Lua scripting, or mpv_command_node() (with
11779 MPV_FORMAT_NODE_MAP) in the C libmpv client API.
11780 The name of the command is provided with a name string field. The name
11782 of each command is defined in each command description in the List of
11783 Input Commands. --input-cmdlist also lists them. See the subprocess
11784 command for an example.
11785 Some commands do not support named arguments (e.g. run command). You
11787 need to use APIs that pass arguments as arrays.
11788 Named arguments are not supported in the "flat" input.conf syntax,
11790 which means you cannot use them for key bindings in input.conf at all.
11791 Property expansion is disabled by default for these APIs. This can be
11793 changed with the expand-properties prefix. See Input Command Prefixes.
11794 List of Input Commands
11796 Commands with parameters have the parameter name enclosed in < / >.
11797 Don't add those to the actual command. Optional arguments are enclosed
11798 in [ / ]. If you don't pass them, they will be set to a default value.
11799 Remember to quote string arguments in input.conf (see Flat command syn‐
11801 tax).
11802 ignore Use this to "block" keys that should be unbound, and do nothing.
11804 Useful for disabling default bindings, without disabling all
11805 bindings with --no-input-default-bindings.
11806 seek <target> [<flags>]
11808 Change the playback position. By default, seeks by a relative
11809 amount of seconds.
11810 The second argument consists of flags controlling the seek mode:
11812 relative (default)
11814 Seek relative to current position (a negative value seeks
11815 backwards).
11816 absolute
11818 Seek to a given time (a negative value starts from the
11819 end of the file).
11820 absolute-percent
11822 Seek to a given percent position.
11823 relative-percent
11825 Seek relative to current position in percent.
11826 keyframes
11828 Always restart playback at keyframe boundaries (fast).
11829 exact Always do exact/hr/precise seeks (slow).
11831 Multiple flags can be combined, e.g.: absolute+keyframes.
11833 By default, keyframes is used for relative, relative-percent,
11835 and absolute-percent seeks, while exact is used for absolute
11836 seeks.
11837 Before mpv 0.9, the keyframes and exact flags had to be passed
11839 as 3rd parameter (essentially using a space instead of +). The
11840 3rd parameter is still parsed, but is considered deprecated.
11841 revert-seek [<flags>]
11843 Undoes the seek command, and some other commands that seek (but
11844 not necessarily all of them). Calling this command once will
11845 jump to the playback position before the seek. Calling it a sec‐
11846 ond time undoes the revert-seek command itself. This only works
11847 within a single file.
11848 The first argument is optional, and can change the behavior:
11850 mark Mark the current time position. The next normal re‐
11852 vert-seek command will seek back to this point, no matter
11853 how many seeks happened since last time.
11854 mark-permanent
11856 If set, mark the current position, and do not change the
11857 mark position before the next revert-seek command that
11858 has mark or mark-permanent set (or playback of the cur‐
11859 rent file ends). Until this happens, revert-seek will al‐
11860 ways seek to the marked point. This flag cannot be com‐
11861 bined with mark.
11862 Using it without any arguments gives you the default behavior.
11864 frame-step
11866 Play one frame, then pause. Does nothing with audio-only play‐
11867 back.
11868 frame-back-step
11870 Go back by one frame, then pause. Note that this can be very
11871 slow (it tries to be precise, not fast), and sometimes fails to
11872 behave as expected. How well this works depends on whether pre‐
11873 cise seeking works correctly (e.g. see the --hr-seek-de‐
11874 muxer-offset option). Video filters or other video post-process‐
11875 ing that modifies timing of frames (e.g. deinterlacing) should
11876 usually work, but might make backstepping silently behave incor‐
11877 rectly in corner cases. Using --hr-seek-framedrop=no should
11878 help, although it might make precise seeking slower.
11879 This does not work with audio-only playback.
11881 set <name> <value>
11883 Set the given property or option to the given value.
11884 add <name> [<value>]
11886 Add the given value to the property or option. On overflow or
11887 underflow, clamp the property to the maximum. If <value> is
11888 omitted, assume 1.
11889 cycle <name> [<value>]
11891 Cycle the given property or option. The second argument can be
11892 up or down to set the cycle direction. On overflow, set the
11893 property back to the minimum, on underflow set it to the maxi‐
11894 mum. If up or down is omitted, assume up.
11895 Whether or not key-repeat is enabled by default depends on the
11897 property. Currently properties with continuous values are re‐
11898 peatable by default (like volume), while discrete values are not
11899 (like osd-level).
11900 multiply <name> <value>
11902 Similar to add, but multiplies the property or option with the
11903 numeric value.
11904 screenshot <flags>
11906 Take a screenshot.
11907 Multiple flags are available (some can be combined with +):
11909 <subtitles> (default)
11911 Save the video image, in its original resolution, and
11912 with subtitles. Some video outputs may still include the
11913 OSD in the output under certain circumstances.
11914 <video>
11916 Like subtitles, but typically without OSD or subtitles.
11917 The exact behavior depends on the selected video output.
11918 <window>
11920 Save the contents of the mpv window. Typically scaled,
11921 with OSD and subtitles. The exact behavior depends on the
11922 selected video output, and if no support is available,
11923 this will act like video.
11924 <each-frame>
11926 Take a screenshot each frame. Issue this command again to
11927 stop taking screenshots. Note that you should disable
11928 frame-dropping when using this mode - or you might re‐
11929 ceive duplicate images in cases when a frame was dropped.
11930 This flag can be combined with the other flags, e.g.
11931 video+each-frame.
11932 Older mpv versions required passing single and each-frame as
11934 second argument (and did not have flags). This syntax is still
11935 understood, but deprecated and might be removed in the future.
11936 If you combine this command with another one using ;, you can
11938 use the async flag to make encoding/writing the image file asyn‐
11939 chronous. For normal standalone commands, this is always asyn‐
11940 chronous, and the flag has no effect. (This behavior changed
11941 with mpv 0.29.0.)
11942 screenshot-to-file <filename> <flags>
11944 Take a screenshot and save it to a given file. The format of the
11945 file will be guessed by the extension (and --screenshot-format
11946 is ignored - the behavior when the extension is missing or un‐
11947 known is arbitrary).
11948 The second argument is like the first argument to screenshot and
11950 supports subtitles, video, window.
11951 If the file already exists, it's overwritten.
11953 Like all input command parameters, the filename is subject to
11955 property expansion as described in Property Expansion.
11956 playlist-next <flags>
11958 Go to the next entry on the playlist.
11959 First argument:
11961 weak (default)
11963 If the last file on the playlist is currently played, do
11964 nothing.
11965 force Terminate playback if there are no more files on the
11967 playlist.
11968 playlist-prev <flags>
11970 Go to the previous entry on the playlist.
11971 First argument:
11973 weak (default)
11975 If the first file on the playlist is currently played, do
11976 nothing.
11977 force Terminate playback if the first file is being played.
11979 playlist-play-index <integer|current|none>
11981 Start (or restart) playback of the given playlist index. In ad‐
11982 dition to the 0-based playlist entry index, it supports the fol‐
11983 lowing values:
11984 <current>
11986 The current playlist entry (as in playlist-current-pos)
11987 will be played again (unload and reload). If none is set,
11988 playback is stopped. (In corner cases, playlist-cur‐
11989 rent-pos can point to a playlist entry even if playback
11990 is currently inactive,
11991 <none> Playback is stopped. If idle mode (--idle) is enabled,
11993 the player will enter idle mode, otherwise it will exit.
11994 This command is similar to loadfile in that it only manipulates
11996 the state of what to play next, without waiting until the cur‐
11997 rent file is unloaded, and the next one is loaded.
11998 Setting playlist-pos or similar properties can have a similar
12000 effect to this command. However, it's more explicit, and guaran‐
12001 tees that playback is restarted if for example the new playlist
12002 entry is the same as the previous one.
12003 loadfile <url> [<flags> [<options>]]
12005 Load the given file or URL and play it. Technically, this is
12006 just a playlist manipulation command (which either replaces the
12007 playlist or appends an entry to it). Actual file loading happens
12008 independently. For example, a loadfile command that replaces the
12009 current file with a new one returns before the current file is
12010 stopped, and the new file even begins loading.
12011 Second argument:
12013 <replace> (default)
12015 Stop playback of the current file, and play the new file
12016 immediately.
12017 <append>
12019 Append the file to the playlist.
12020 <append-play>
12022 Append the file, and if nothing is currently playing,
12023 start playback. (Always starts with the added file, even
12024 if the playlist was not empty before running this com‐
12025 mand.)
12026 The third argument is a list of options and values which should
12028 be set while the file is playing. It is of the form
12029 opt1=value1,opt2=value2,... When using the client API, this can
12030 be a MPV_FORMAT_NODE_MAP (or a Lua table), however the values
12031 themselves must be strings currently. These options are set dur‐
12032 ing playback, and restored to the previous value at end of play‐
12033 back (see Per-File Options).
12034 loadlist <url> [<flags>]
12036 Load the given playlist file or URL (like --playlist).
12037 Second argument:
12039 <replace> (default)
12041 Stop playback and replace the internal playlist with the
12042 new one.
12043 <append>
12045 Append the new playlist at the end of the current inter‐
12046 nal playlist.
12047 <append-play>
12049 Append the new playlist, and if nothing is currently
12050 playing, start playback. (Always starts with the new
12051 playlist, even if the internal playlist was not empty be‐
12052 fore running this command.)
12053 playlist-clear
12055 Clear the playlist, except the currently played file.
12056 playlist-remove <index>
12058 Remove the playlist entry at the given index. Index values start
12059 counting with 0. The special value current removes the current
12060 entry. Note that removing the current entry also stops playback
12061 and starts playing the next entry.
12062 playlist-move <index1> <index2>
12064 Move the playlist entry at index1, so that it takes the place of
12065 the entry index2. (Paradoxically, the moved playlist entry will
12066 not have the index value index2 after moving if index1 was lower
12067 than index2, because index2 refers to the target entry, not the
12068 index the entry will have after moving.)
12069 playlist-shuffle
12071 Shuffle the playlist. This is similar to what is done on start
12072 if the --shuffle option is used.
12073 playlist-unshuffle
12075 Attempt to revert the previous playlist-shuffle command. This
12076 works only once (multiple successive playlist-unshuffle commands
12077 do nothing). May not work correctly if new recursive playlists
12078 have been opened since a playlist-shuffle command.
12079 run <command> [<arg1> [<arg2> [...]]]
12081 Run the given command. Unlike in MPlayer/mplayer2 and earlier
12082 versions of mpv (0.2.x and older), this doesn't call the shell.
12083 Instead, the command is run directly, with each argument passed
12084 separately. Each argument is expanded like in Property Expan‐
12085 sion.
12086 This command has a variable number of arguments, and cannot be
12088 used with named arguments.
12089 The program is run in a detached way. mpv doesn't wait until the
12091 command is completed, but continues playback right after spawn‐
12092 ing it.
12093 To get the old behavior, use /bin/sh and -c as the first two ar‐
12095 guments.
12096 Example
12098 run "/bin/sh" "-c" "echo ${title} > /tmp/playing"
12100 This is not a particularly good example, because it
12102 doesn't handle escaping, and a specially prepared file
12103 might allow an attacker to execute arbitrary shell
12104 commands. It is recommended to write a small shell
12105 script, and call that with run.
12106 subprocess
12108 Similar to run, but gives more control about process execution
12109 to the caller, and does does not detach the process.
12110 You can avoid blocking until the process terminates by running
12112 this command asynchronously. (For example mp.command_na‐
12113 tive_async() in Lua scripting.)
12114 This has the following named arguments. The order of them is not
12116 guaranteed, so you should always call them with named arguments,
12117 see Named arguments.
12118 args (MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING])
12120 Array of strings with the command as first argument, and
12121 subsequent command line arguments following. This is just
12122 like the run command argument list.
12123 The first array entry is either an absolute path to the
12125 executable, or a filename with no path components, in
12126 which case the executable is searched in the directories
12127 in the PATH environment variable. On Unix, this is equiv‐
12128 alent to posix_spawnp and execvp behavior.
12129 playback_only (MPV_FORMAT_FLAG)
12131 Boolean indicating whether the process should be killed
12132 when playback of the current playlist entry terminates
12133 (optional, default: true). If enabled, stopping playback
12134 will automatically kill the process, and you can't start
12135 it outside of playback.
12136 capture_size (MPV_FORMAT_INT64)
12138 Integer setting the maximum number of stdout plus stderr
12139 bytes that can be captured (optional, default: 64MB). If
12140 the number of bytes exceeds this, capturing is stopped.
12141 The limit is per captured stream.
12142 capture_stdout (MPV_FORMAT_FLAG)
12144 Capture all data the process outputs to stdout and return
12145 it once the process ends (optional, default: no).
12146 capture_stderr (MPV_FORMAT_FLAG)
12148 Same as capture_stdout, but for stderr.
12149 detach (MPV_FORMAT_FLAG)
12151 Whether to run the process in detached mode (optional,
12152 default: no). In this mode, the process is run in a new
12153 process session, and the command does not wait for the
12154 process to terminate. If neither capture_stdout nor cap‐
12155 ture_stderr have been set to true, the command returns
12156 immediately after the new process has been started, oth‐
12157 erwise the command will read as long as the pipes are
12158 open.
12159 env (MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING])
12161 Set a list of environment variables for the new process
12162 (default: empty). If an empty list is passed, the envi‐
12163 ronment of the mpv process is used instead. (Unlike the
12164 underlying OS mechanisms, the mpv command cannot start a
12165 process with empty environment. Fortunately, that is com‐
12166 pletely useless.) The format of the list is as in the ex‐
12167 ecle() syscall. Each string item defines an environment
12168 variable as in NAME=VALUE.
12169 On Lua, you may use utils.get_env_list() to retrieve the
12171 current environment if you e.g. simply want to add a new
12172 variable.
12173 stdin_data (MPV_FORMAT_STRING)
12175 Feed the given string to the new process' stdin. Since
12176 this is a string, you cannot pass arbitrary binary data.
12177 If the process terminates or closes the pipe before all
12178 data is written, the remaining data is silently dis‐
12179 carded. Probably does not work on win32.
12180 passthrough_stdin (MPV_FORMAT_FLAG)
12182 If enabled, wire the new process' stdin to mpv's stdin
12183 (default: no). Before mpv 0.33.0, this argument did not
12184 exist, but the behavior was as if this was set to true.
12185 The command returns the following result (as MPV_FOR‐
12187 MAT_NODE_MAP):
12188 status (MPV_FORMAT_INT64)
12190 Typically this is the process exit code (0 or positive)
12191 if the process terminates normally, or negative for other
12192 errors (failed to start, terminated by mpv, and others).
12193 The meaning of negative values is undefined, other than
12194 meaning error (and does not correspond to OS low level
12195 exit status values).
12196 On Windows, it can happen that a negative return value is
12198 returned even if the process terminates normally, because
12199 the win32 UINT exit code is assigned to an int variable
12200 before being set as int64_t field in the result map. This
12201 might be fixed later.
12202 stdout (MPV_FORMAT_BYTE_ARRAY)
12204 Captured stdout stream, limited to capture_size.
12205 stderr (MPV_FORMAT_BYTE_ARRAY)
12207 Same as stdout, but for stderr.
12208 error_string (MPV_FORMAT_STRING)
12210 Empty string if the process terminated normally. The
12211 string killed if the process was terminated in an unusual
12212 way. The string init if the process could not be started.
12213 On Windows, killed is only returned when the process has
12215 been killed by mpv as a result of playback_only being set
12216 to true.
12217 killed_by_us (MPV_FORMAT_FLAG)
12219 Whether the process has been killed by mpv, for example
12220 as a result of playback_only being set to true, aborting
12221 the command (e.g. by mp.abort_async_command()), or if the
12222 player is about to exit.
12223 Note that the command itself will always return success as long
12225 as the parameters are correct. Whether the process could be
12226 spawned or whether it was somehow killed or returned an error
12227 status has to be queried from the result value.
12228 This command can be asynchronously aborted via API. Also see
12230 Asynchronous command details. Only the run command can start
12231 processes in a truly detached way.
12232 NOTE:
12234 The subprocess will always be terminated on player exit if it
12235 wasn't started in detached mode, even if playback_only is
12236 false.
12237 Warning
12239 Don't forget to set the playback_only field to false
12241 if you want the command to run while the player is in
12242 idle mode, or if you don't want the end of playback to
12243 kill the command.
12244 Example
12246 local r = mp.command_native({
12248 name = "subprocess",
12249 playback_only = false,
12250 capture_stdout = true,
12251 args = {"cat", "/proc/cpuinfo"},
12252 })
12253 if r.status == 0 then
12254 print("result: " .. r.stdout)
12255 end
12256 This is a fairly useless Lua example, which demonstrates how
12258 to run a process in a blocking manner, and retrieving its
12259 stdout output.
12260 quit [<code>]
12262 Exit the player. If an argument is given, it's used as process
12263 exit code.
12264 quit-watch-later [<code>]
12266 Exit player, and store current playback position. Playing that
12267 file later will seek to the previous position on start. The (op‐
12268 tional) argument is exactly as in the quit command. See RESUMING
12269 PLAYBACK.
12270 sub-add <url> [<flags> [<title> [<lang>]]]
12272 Load the given subtitle file or stream. By default, it is se‐
12273 lected as current subtitle after loading.
12274 The flags argument is one of the following values:
12276 <select>
12278 Select the subtitle immediately (default).
12279 <auto>
12281 Don't select the subtitle. (Or in some special situations,
12282 let the default stream selection mechanism decide.)
12283 <cached>
12285 Select the subtitle. If a subtitle with the same filename was
12286 already added, that one is selected, instead of loading a du‐
12287 plicate entry. (In this case, title/language are ignored,
12288 and if the was changed since it was loaded, these changes
12289 won't be reflected.)
12290 The title argument sets the track title in the UI.
12292 The lang argument sets the track language, and can also influ‐
12294 ence stream selection with flags set to auto.
12295 sub-remove [<id>]
12297 Remove the given subtitle track. If the id argument is missing,
12298 remove the current track. (Works on external subtitle files
12299 only.)
12300 sub-reload [<id>]
12302 Reload the given subtitle tracks. If the id argument is missing,
12303 reload the current track. (Works on external subtitle files
12304 only.)
12305 This works by unloading and re-adding the subtitle track.
12307 sub-step <skip> <flags>
12309 Change subtitle timing such, that the subtitle event after the
12310 next <skip> subtitle events is displayed. <skip> can be negative
12311 to step backwards.
12312 Secondary argument:
12314 primary (default)
12316 Steps through the primary subtitles.
12317 secondary
12319 Steps through the secondary subtitles.
12320 sub-seek <skip> <flags>
12322 Seek to the next (skip set to 1) or the previous (skip set to
12323 -1) subtitle. This is similar to sub-step, except that it seeks
12324 video and audio instead of adjusting the subtitle delay.
12325 Secondary argument:
12327 primary (default)
12329 Seeks through the primary subtitles.
12330 secondary
12332 Seeks through the secondary subtitles.
12333 For embedded subtitles (like with Matroska), this works only
12335 with subtitle events that have already been displayed, or are
12336 within a short prefetch range.
12337 print-text <text>
12339 Print text to stdout. The string can contain properties (see
12340 Property Expansion). Take care to put the argument in quotes.
12341 show-text <text> [<duration>|-1 [<level>]]
12343 Show text on the OSD. The string can contain properties, which
12344 are expanded as described in Property Expansion. This can be
12345 used to show playback time, filename, and so on.
12346 <duration>
12348 The time in ms to show the message for. By default, it
12349 uses the same value as --osd-duration.
12350 <level>
12352 The minimum OSD level to show the text at (see
12353 --osd-level).
12354 expand-text <string>
12356 Property-expand the argument and return the expanded string.
12357 This can be used only through the client API or from a script
12358 using mp.command_native. (see Property Expansion).
12359 expand-path "<string>"
12361 Expand a path's double-tilde placeholders into a platform-spe‐
12362 cific path. As expand-text, this can only be used through the
12363 client API or from a script using mp.command_native.
12364 Example
12366 mp.osd_message(mp.command_native({"expand-path",
12368 "~~home/"}))
12369 This line of Lua would show the location of the user's
12371 mpv configuration directory on the OSD.
12372 show-progress
12374 Show the progress bar, the elapsed time and the total duration
12375 of the file on the OSD.
12376 write-watch-later-config
12378 Write the resume config file that the quit-watch-later command
12379 writes, but continue playback normally.
12380 delete-watch-later-config [<filename>]
12382 Delete any existing resume config file that was written by
12383 quit-watch-later or write-watch-later-config. If a filename is
12384 specified, then the deleted config is for that file; otherwise,
12385 it is the same one as would be written by quit-watch-later or
12386 write-watch-later-config in the current circumstance.
12387 stop [<flags>]
12389 Stop playback and clear playlist. With default settings, this is
12390 essentially like quit. Useful for the client API: playback can
12391 be stopped without terminating the player.
12392 The first argument is optional, and supports the following
12394 flags:
12395 keep-playlist
12397 Do not clear the playlist.
12398 mouse <x> <y> [<button> [<mode>]]
12400 Send a mouse event with given coordinate (<x>, <y>).
12401 Second argument:
12403 <button>
12405 The button number of clicked mouse button. This should be
12406 one of 0-19. If <button> is omitted, only the position
12407 will be updated.
12408 Third argument:
12410 <single> (default)
12412 The mouse event represents regular single click.
12413 <double>
12415 The mouse event represents double-click.
12416 keypress <name>
12418 Send a key event through mpv's input handler, triggering what‐
12419 ever behavior is configured to that key. name uses the in‐
12420 put.conf naming scheme for keys and modifiers. Useful for the
12421 client API: key events can be sent to libmpv to handle inter‐
12422 nally.
12423 keydown <name>
12425 Similar to keypress, but sets the KEYDOWN flag so that if the
12426 key is bound to a repeatable command, it will be run repeatedly
12427 with mpv's key repeat timing until the keyup command is called.
12428 keyup [<name>]
12430 Set the KEYUP flag, stopping any repeated behavior that had been
12431 triggered. name is optional. If name is not given or is an empty
12432 string, KEYUP will be set on all keys. Otherwise, KEYUP will
12433 only be set on the key specified by name.
12434 keybind <name> <command>
12436 Binds a key to an input command. command must be a complete com‐
12437 mand containing all the desired arguments and flags. Both name
12438 and command use the input.conf naming scheme. This is primarily
12439 useful for the client API.
12440 audio-add <url> [<flags> [<title> [<lang>]]]
12442 Load the given audio file. See sub-add command.
12443 audio-remove [<id>]
12445 Remove the given audio track. See sub-remove command.
12446 audio-reload [<id>]
12448 Reload the given audio tracks. See sub-reload command.
12449 video-add <url> [<flags> [<title> [<lang> [<albumart>]]]]
12451 Load the given video file. See sub-add command for common op‐
12452 tions.
12453 albumart (MPV_FORMAT_FLAG)
12455 If enabled, mpv will load the given video as album art.
12456 video-remove [<id>]
12458 Remove the given video track. See sub-remove command.
12459 video-reload [<id>]
12461 Reload the given video tracks. See sub-reload command.
12462 rescan-external-files [<mode>]
12464 Rescan external files according to the current --sub-auto, --au‐
12465 dio-file-auto and --cover-art-auto settings. This can be used to
12466 auto-load external files after the file was loaded.
12467 The mode argument is one of the following:
12469 <reselect> (default)
12471 Select the default audio and subtitle streams, which typ‐
12472 ically selects external files with the highest prefer‐
12473 ence. (The implementation is not perfect, and could be
12474 improved on request.)
12475 <keep-selection>
12477 Do not change current track selections.
12478 Input Commands that are Possibly Subject to Change
12480 af <operation> <value>
12481 Change audio filter chain. See vf command.
12482 vf <operation> <value>
12484 Change video filter chain.
12485 The semantics are exactly the same as with option parsing (see
12487 VIDEO FILTERS). As such the text below is a redundant and incom‐
12488 plete summary.
12489 The first argument decides what happens:
12491 <set> Overwrite the previous filter chain with the new one.
12493 <add> Append the new filter chain to the previous one.
12495 <toggle>
12497 Check if the given filter (with the exact parameters) is
12498 already in the video chain. If it is, remove the filter.
12499 If it isn't, add the filter. (If several filters are
12500 passed to the command, this is done for each filter.)
12501 A special variant is combining this with labels, and us‐
12503 ing @name without filter name and parameters as filter
12504 entry. This toggles the enable/disable flag.
12505 <remove>
12507 Like toggle, but always remove the given filter from the
12508 chain.
12509 <del> Remove the given filters from the video chain. Unlike in
12511 the other cases, the second parameter is a comma sepa‐
12512 rated list of filter names or integer indexes. 0 would
12513 denote the first filter. Negative indexes start from the
12514 last filter, and -1 denotes the last filter. Deprecated,
12515 use remove.
12516 <clr> Remove all filters. Note that like the other sub-com‐
12518 mands, this does not control automatically inserted fil‐
12519 ters.
12520 The argument is always needed. E.g. in case of clr use vf clr
12522 "".
12523 You can assign labels to filter by prefixing them with @name:
12525 (where name is a user-chosen arbitrary identifier). Labels can
12526 be used to refer to filters by name in all of the filter chain
12527 modification commands. For add, using an already used label
12528 will replace the existing filter.
12529 The vf command shows the list of requested filters on the OSD
12531 after changing the filter chain. This is roughly equivalent to
12532 show-text ${vf}. Note that auto-inserted filters for format con‐
12533 version are not shown on the list, only what was requested by
12534 the user.
12535 Normally, the commands will check whether the video chain is
12537 recreated successfully, and will undo the operation on failure.
12538 If the command is run before video is configured (can happen if
12539 the command is run immediately after opening a file and before a
12540 video frame is decoded), this check can't be run. Then it can
12541 happen that creating the video chain fails.
12542 Example for input.conf
12544 • a vf set vflip turn the video upside-down on the a key
12546 • b vf set "" remove all video filters on b
12548 • c vf toggle gradfun toggle debanding on c
12550 Example how to toggle disabled filters at runtime
12552 • Add something like vf-add=@deband:!gradfun to mpv.conf.
12554 The @deband: is the label, an arbitrary, user-given name
12555 for this filter entry. The ! before the filter name dis‐
12556 ables the filter by default. Everything after this is the
12557 normal filter name and possibly filter parameters, like in
12558 the normal --vf syntax.
12559 • Add a vf toggle @deband to input.conf. This toggles the
12561 "disabled" flag for the filter with the label deband when
12562 the a key is hit.
12563 cycle-values [<"!reverse">] <property> <value1> [<value2> [...]]
12565 Cycle through a list of values. Each invocation of the command
12566 will set the given property to the next value in the list. The
12567 command will use the current value of the property/option, and
12568 use it to determine the current position in the list of values.
12569 Once it has found it, it will set the next value in the list
12570 (wrapping around to the first item if needed).
12571 This command has a variable number of arguments, and cannot be
12573 used with named arguments.
12574 The special argument !reverse can be used to cycle the value
12576 list in reverse. The only advantage is that you don't need to
12577 reverse the value list yourself when adding a second key binding
12578 for cycling backwards.
12579 enable-section <name> [<flags>]
12581 This command is deprecated, except for mpv-internal uses.
12582 Enable all key bindings in the named input section.
12584 The enabled input sections form a stack. Bindings in sections on
12586 the top of the stack are preferred to lower sections. This com‐
12587 mand puts the section on top of the stack. If the section was
12588 already on the stack, it is implicitly removed beforehand. (A
12589 section cannot be on the stack more than once.)
12590 The flags parameter can be a combination (separated by +) of the
12592 following flags:
12593 <exclusive>
12595 All sections enabled before the newly enabled section are
12596 disabled. They will be re-enabled as soon as all exclu‐
12597 sive sections above them are removed. In other words, the
12598 new section shadows all previous sections.
12599 <allow-hide-cursor>
12601 This feature can't be used through the public API.
12602 <allow-vo-dragging>
12604 Same.
12605 disable-section <name>
12607 This command is deprecated, except for mpv-internal uses.
12608 Disable the named input section. Undoes enable-section.
12610 define-section <name> <contents> [<flags>]
12612 This command is deprecated, except for mpv-internal uses.
12613 Create a named input section, or replace the contents of an al‐
12615 ready existing input section. The contents parameter uses the
12616 same syntax as the input.conf file (except that using the sec‐
12617 tion syntax in it is not allowed), including the need to sepa‐
12618 rate bindings with a newline character.
12619 If the contents parameter is an empty string, the section is re‐
12621 moved.
12622 The section with the name default is the normal input section.
12624 In general, input sections have to be enabled with the en‐
12626 able-section command, or they are ignored.
12627 The last parameter has the following meaning:
12629 <default> (also used if parameter omitted)
12631 Use a key binding defined by this section only if the
12632 user hasn't already bound this key to a command.
12633 <force>
12635 Always bind a key. (The input section that was made ac‐
12636 tive most recently wins if there are ambiguities.)
12637 This command can be used to dispatch arbitrary keys to a script
12639 or a client API user. If the input section defines script-bind‐
12640 ing commands, it is also possible to get separate events on key
12641 up/down, and relatively detailed information about the key
12642 state. The special key name unmapped can be used to match any
12643 unmapped key.
12644 overlay-add <id> <x> <y> <file> <offset> <fmt> <w> <h> <stride>
12646 Add an OSD overlay sourced from raw data. This might be useful
12647 for scripts and applications controlling mpv, and which want to
12648 display things on top of the video window.
12649 Overlays are usually displayed in screen resolution, but with
12651 some VOs, the resolution is reduced to that of the video's. You
12652 can read the osd-width and osd-height properties. At least with
12653 --vo-xv and anamorphic video (such as DVD), osd-par should be
12654 read as well, and the overlay should be aspect-compensated.
12655 This has the following named arguments. The order of them is not
12657 guaranteed, so you should always call them with named arguments,
12658 see Named arguments.
12659 id is an integer between 0 and 63 identifying the overlay ele‐
12661 ment. The ID can be used to add multiple overlay parts, update a
12662 part by using this command with an already existing ID, or to
12663 remove a part with overlay-remove. Using a previously unused ID
12664 will add a new overlay, while reusing an ID will update it.
12665 x and y specify the position where the OSD should be displayed.
12667 file specifies the file the raw image data is read from. It can
12669 be either a numeric UNIX file descriptor prefixed with @ (e.g.
12670 @4), or a filename. The file will be mapped into memory with
12671 mmap(), copied, and unmapped before the command returns (changed
12672 in mpv 0.18.1).
12673 It is also possible to pass a raw memory address for use as bit‐
12675 map memory by passing a memory address as integer prefixed with
12676 an & character. Passing the wrong thing here will crash the
12677 player. This mode might be useful for use with libmpv. The off‐
12678 set parameter is simply added to the memory address (since mpv
12679 0.8.0, ignored before).
12680 offset is the byte offset of the first pixel in the source file.
12682 (The current implementation always mmap's the whole file from
12683 position 0 to the end of the image, so large offsets should be
12684 avoided. Before mpv 0.8.0, the offset was actually passed di‐
12685 rectly to mmap, but it was changed to make using it easier.)
12686 fmt is a string identifying the image format. Currently, only
12688 bgra is defined. This format has 4 bytes per pixels, with 8 bits
12689 per component. The least significant 8 bits are blue, and the
12690 most significant 8 bits are alpha (in little endian, the compo‐
12691 nents are B-G-R-A, with B as first byte). This uses premulti‐
12692 plied alpha: every color component is already multiplied with
12693 the alpha component. This means the numeric value of each compo‐
12694 nent is equal to or smaller than the alpha component. (Violating
12695 this rule will lead to different results with different VOs: nu‐
12696 meric overflows resulting from blending broken alpha values is
12697 considered something that shouldn't happen, and consequently im‐
12698 plementations don't ensure that you get predictable behavior in
12699 this case.)
12700 w, h, and stride specify the size of the overlay. w is the visi‐
12702 ble width of the overlay, while stride gives the width in bytes
12703 in memory. In the simple case, and with the bgra format,
12704 stride==4*w. In general, the total amount of memory accessed is
12705 stride * h. (Technically, the minimum size would be stride * (h
12706 - 1) + w * 4, but for simplicity, the player will access all
12707 stride * h bytes.)
12708 NOTE:
12710 Before mpv 0.18.1, you had to do manual "double buffering"
12711 when updating an overlay by replacing it with a different
12712 memory buffer. Since mpv 0.18.1, the memory is simply copied
12713 and doesn't reference any of the memory indicated by the com‐
12714 mand's arguments after the commend returns. If you want to
12715 use this command before mpv 0.18.1, reads the old docs to see
12716 how to handle this correctly.
12717 overlay-remove <id>
12719 Remove an overlay added with overlay-add and the same ID. Does
12720 nothing if no overlay with this ID exists.
12721 osd-overlay
12723 Add/update/remove an OSD overlay.
12724 (Although this sounds similar to overlay-add, osd-overlay is for
12726 text overlays, while overlay-add is for bitmaps. Maybe over‐
12727 lay-add will be merged into osd-overlay to remove this oddity.)
12728 You can use this to add text overlays in ASS format. ASS has ad‐
12730 vanced positioning and rendering tags, which can be used to ren‐
12731 der almost any kind of vector graphics.
12732 This command accepts the following parameters:
12734 id Arbitrary integer that identifies the overlay. Multiple
12736 overlays can be added by calling this command with dif‐
12737 ferent id parameters. Calling this command with the same
12738 id replaces the previously set overlay.
12739 There is a separate namespace for each libmpv client
12741 (i.e. IPC connection, script), so IDs can be made up and
12742 assigned by the API user without conflicting with other
12743 API users.
12744 If the libmpv client is destroyed, all overlays associ‐
12746 ated with it are also deleted. In particular, connecting
12747 via --input-ipc-server, adding an overlay, and discon‐
12748 necting will remove the overlay immediately again.
12749 format String that gives the type of the overlay. Accepts the
12751 following values (HTML rendering of this is broken, view
12752 the generated manpage instead, or the raw RST source):
12753 ass-events
12755 The data parameter is a string. The string is
12756 split on the newline character. Every line is
12757 turned into the Text part of a Dialogue ASS event.
12758 Timing is unused (but behavior of timing dependent
12759 ASS tags may change in future mpv versions).
12760 Note that it's better to put multiple lines into
12762 data, instead of adding multiple OSD overlays.
12763 This provides 2 ASS Styles. OSD contains the text
12765 style as defined by the current --osd-... options.
12766 Default is similar, and contains style that OSD
12767 would have if all options were set to the default.
12768 In addition, the res_x and res_y options specify
12770 the value of the ASS PlayResX and PlayResY header
12771 fields. If res_y is set to 0, PlayResY is initial‐
12772 ized to an arbitrary default value (but note that
12773 the default for this command is 720, not 0). If
12774 res_x is set to 0, PlayResX is set based on res_y
12775 such that a virtual ASS pixel has a square pixel
12776 aspect ratio.
12777 none Special value that causes the overlay to be re‐
12779 moved. Most parameters other than id and format
12780 are mostly ignored.
12781 data String defining the overlay contents according to the
12783 format parameter.
12784 res_x, res_y
12786 Used if format is set to ass-events (see description
12787 there). Optional, defaults to 0/720.
12788 z The Z order of the overlay. Optional, defaults to 0.
12790 Note that Z order between different overlays of different
12792 formats is static, and cannot be changed (currently, this
12793 means that bitmap overlays added by overlay-add are al‐
12794 ways on top of the ASS overlays added by osd-overlay). In
12795 addition, the builtin OSD components are always below any
12796 of the custom OSD. (This includes subtitles of any kind
12797 as well as text rendered by show-text.)
12798 It's possible that future mpv versions will randomly
12800 change how Z order between different OSD formats and
12801 builtin OSD is handled.
12802 hidden If set to true, do not display this (default: false).
12804 compute_bounds
12806 If set to true, attempt to determine bounds and write
12807 them to the command's result value as x0, x1, y0, y1 rec‐
12808 tangle (default: false). If the rectangle is empty, not
12809 known, or somehow degenerate, it is not set. x1/y1 is the
12810 coordinate of the bottom exclusive corner of the rectan‐
12811 gle.
12812 The result value may depend on the VO window size, and is
12814 based on the last known window size at the time of the
12815 call. This means the results may be different from what
12816 is actually rendered.
12817 For ass-events, the result rectangle is recomputed to
12819 PlayRes coordinates (res_x/res_y). If window size is not
12820 known, a fallback is chosen.
12821 You should be aware that this mechanism is very ineffi‐
12823 cient, as it renders the full result, and then uses the
12824 bounding box of the rendered bitmap list (even if hidden
12825 is set). It will flush various caches. Its results also
12826 depend on the used libass version.
12827 This feature is experimental, and may change in some way
12829 again.
12830 NOTE:
12832 Always use named arguments (mpv_command_node()). Lua scripts
12833 should use the mp.create_osd_overlay() helper instead of in‐
12834 voking this command directly.
12835 script-message [<arg1> [<arg2> [...]]]
12837 Send a message to all clients, and pass it the following list of
12838 arguments. What this message means, how many arguments it
12839 takes, and what the arguments mean is fully up to the receiver
12840 and the sender. Every client receives the message, so be careful
12841 about name clashes (or use script-message-to).
12842 This command has a variable number of arguments, and cannot be
12844 used with named arguments.
12845 script-message-to <target> [<arg1> [<arg2> [...]]]
12847 Same as script-message, but send it only to the client named
12848 <target>. Each client (scripts etc.) has a unique name. For ex‐
12849 ample, Lua scripts can get their name via mp.get_script_name().
12850 Note that client names only consist of alphanumeric characters
12851 and _.
12852 This command has a variable number of arguments, and cannot be
12854 used with named arguments.
12855 script-binding <name>
12857 Invoke a script-provided key binding. This can be used to remap
12858 key bindings provided by external Lua scripts.
12859 The argument is the name of the binding.
12861 It can optionally be prefixed with the name of the script, using
12863 / as separator, e.g. script-binding scriptname/bindingname. Note
12864 that script names only consist of alphanumeric characters and _.
12865 For completeness, here is how this command works internally. The
12867 details could change any time. On any matching key event,
12868 script-message-to or script-message is called (depending on
12869 whether the script name is included), with the following argu‐
12870 ments:
12871 1. The string key-binding.
12873 2. The name of the binding (as established above).
12875 3. The key state as string (see below).
12877 4. The key name (since mpv 0.15.0).
12879 5. The text the key would produce, or empty string if not appli‐
12881 cable.
12882 The 5th argument is only set if no modifiers are present (using
12884 the shift key with a letter is normally not emitted as having a
12885 modifier, and results in upper case text instead, but some back‐
12886 ends may mess up).
12887 The key state consists of 2 characters:
12889 1. One of d (key was pressed down), u (was released), r (key is
12891 still down, and was repeated; only if key repeat is enabled
12892 for this binding), p (key was pressed; happens if up/down
12893 can't be tracked).
12894 2. Whether the event originates from the mouse, either m (mouse
12896 button) or - (something else).
12897 Future versions can add more arguments and more key state char‐
12899 acters to support more input peculiarities.
12900 ab-loop
12902 Cycle through A-B loop states. The first command will set the A
12903 point (the ab-loop-a property); the second the B point, and the
12904 third will clear both points.
12905 drop-buffers
12907 Drop audio/video/demuxer buffers, and restart from fresh. Might
12908 help with unseekable streams that are going out of sync. This
12909 command might be changed or removed in the future.
12910 screenshot-raw [<flags>]
12912 Return a screenshot in memory. This can be used only through the
12913 client API. The MPV_FORMAT_NODE_MAP returned by this command has
12914 the w, h, stride fields set to obvious contents. The format
12915 field is set to bgr0 by default. This format is organized as
12916 B8G8R8X8 (where B is the LSB). The contents of the padding X are
12917 undefined. The data field is of type MPV_FORMAT_BYTE_ARRAY with
12918 the actual image data. The image is freed as soon as the result
12919 mpv_node is freed. As usual with client API semantics, you are
12920 not allowed to write to the image data.
12921 The stride is the number of bytes from a pixel at (x0, y0) to
12923 the pixel at (x0, y0 + 1). This can be larger than w * 4 if the
12924 image was cropped, or if there is padding. This number can be
12925 negative as well. You access a pixel with byte_index = y *
12926 stride + x * 4 (assuming the bgr0 format).
12927 The flags argument is like the first argument to screenshot and
12929 supports subtitles, video, window.
12930 vf-command <label> <command> <argument>
12932 Send a command to the filter with the given <label>. Use all to
12933 send it to all filters at once. The command and argument string
12934 is filter specific. Currently, this only works with the lavfi
12935 filter - see the libavfilter documentation for which commands a
12936 filter supports.
12937 Note that the <label> is a mpv filter label, not a libavfilter
12939 filter name.
12940 af-command <label> <command> <argument>
12942 Same as vf-command, but for audio filters.
12943 apply-profile <name> [<mode>]
12945 Apply the contents of a named profile. This is like using pro‐
12946 file=name in a config file, except you can map it to a key bind‐
12947 ing to change it at runtime.
12948 The mode argument:
12950 default
12952 Apply the profile. Default if the argument is omitted.
12953 restore
12955 Restore options set by a previous apply-profile command
12956 for this profile. Only works if the profile has pro‐
12957 file-restore set to a relevant mode. Prints a warning if
12958 nothing could be done. See Runtime profiles for details.
12959 load-script <filename>
12961 Load a script, similar to the --script option. Whether this
12962 waits for the script to finish initialization or not changed
12963 multiple times, and the future behavior is left undefined.
12964 On success, returns a mpv_node with a client_id field set to the
12966 return value of the mpv_client_id() API call of the newly cre‐
12967 ated script handle.
12968 change-list <name> <operation> <value>
12970 This command changes list options as described in List Options.
12971 The <name> parameter is the normal option name, while <opera‐
12972 tion> is the suffix or action used on the option.
12973 Some operations take no value, but the command still requires
12975 the value parameter. In these cases, the value must be an empty
12976 string.
12977 Example
12979 change-list glsl-shaders append file.glsl
12981 Add a filename to the glsl-shaders list. The command
12983 line equivalent is --glsl-shaders-append=file.glsl or
12984 alternatively --glsl-shader=file.glsl.
12985 dump-cache <start> <end> <filename>
12987 Dump the current cache to the given filename. The <filename>
12988 file is overwritten if it already exists. <start> and <end> give
12989 the time range of what to dump. If no data is cached at the
12990 given time range, nothing may be dumped (creating a file with no
12991 packets).
12992 Dumping a larger part of the cache will freeze the player. No
12994 effort was made to fix this, as this feature was meant mostly
12995 for creating small excerpts.
12996 See --stream-record for various caveats that mostly apply to
12998 this command too, as both use the same underlying code for writ‐
12999 ing the output file.
13000 If <filename> is an empty string, an ongoing dump-cache is
13002 stopped.
13003 If <end> is no, then continuous dumping is enabled. Then, after
13005 dumping the existing parts of the cache, anything read from net‐
13006 work is appended to the cache as well. This behaves similar to
13007 --stream-record (although it does not conflict with that option,
13008 and they can be both active at the same time).
13009 If the <end> time is after the cache, the command will _not_
13011 wait and write newly received data to it.
13012 The end of the resulting file may be slightly damaged or incom‐
13014 plete at the end. (Not enough effort was made to ensure that the
13015 end lines up properly.)
13016 Note that this command will finish only once dumping ends. That
13018 means it works similar to the screenshot command, just that it
13019 can block much longer. If continuous dumping is used, the com‐
13020 mand will not finish until playback is stopped, an error hap‐
13021 pens, another dump-cache command is run, or an API like
13022 mp.abort_async_command was called to explicitly stop the com‐
13023 mand. See Synchronous vs. Asynchronous.
13024 NOTE:
13026 This was mostly created for network streams. For local files,
13027 there may be much better methods to create excerpts and such.
13028 There are tons of much more user-friendly Lua scripts, that
13029 will reencode parts of a file by spawning a separate instance
13030 of ffmpeg. With network streams, this is not that easily pos‐
13031 sible, as the stream would have to be downloaded again. Even
13032 if --stream-record is used to record the stream to the local
13033 filesystem, there may be problems, because the recorded file
13034 is still written to.
13035 This command is experimental, and all details about it may
13037 change in the future.
13038 ab-loop-dump-cache <filename>
13040 Essentially calls dump-cache with the current AB-loop points as
13041 arguments. Like dump-cache, this will overwrite the file at
13042 <filename>. Likewise, if the B point is set to no, it will enter
13043 continuous dumping after the existing cache was dumped.
13044 The author reserves the right to remove this command if enough
13046 motivation is found to move this functionality to a trivial Lua
13047 script.
13048 ab-loop-align-cache
13050 Re-adjust the A/B loop points to the start and end within the
13051 cache the ab-loop-dump-cache command will (probably) dump. Basi‐
13052 cally, it aligns the times on keyframes. The guess might be off
13053 especially at the end (due to granularity issues due to remux‐
13054 ing). If the cache shrinks in the meantime, the points set by
13055 the command will not be the effective parameters either.
13056 This command has an even more uncertain future than
13058 ab-loop-dump-cache and might disappear without replacement if
13059 the author decides it's useless.
13060 Undocumented commands: ao-reload (experimental/internal).
13062 List of events
13064 This is a partial list of events. This section describes what
13065 mpv_event_to_node() returns, and which is what scripting APIs and the
13066 JSON IPC sees. Note that the C API has separate C-level declarations
13067 with mpv_event, which may be slightly different.
13068 Note that events are asynchronous: the player core continues running
13070 while events are delivered to scripts and other clients. In some cases,
13071 you can hooks to enforce synchronous execution.
13072 All events can have the following fields:
13074 event Name as the event (as returned by mpv_event_name()).
13076 id The reply_userdata field (opaque user value). If reply_userdata
13078 is 0, the field is not added.
13079 error Set to an error string (as returned by mpv_error_string()). This
13081 field is missing if no error happened, or the event type does
13082 not report error. Most events leave this unset.
13083 This list uses the event name field value, and the C API symbol in
13085 brackets:
13086 start-file (MPV_EVENT_START_FILE)
13088 Happens right before a new file is loaded. When you receive
13089 this, the player is loading the file (or possibly already done
13090 with it).
13091 This has the following fields:
13093 playlist_entry_id
13095 Playlist entry ID of the file being loaded now.
13096 end-file (MPV_EVENT_END_FILE)
13098 Happens after a file was unloaded. Typically, the player will
13099 load the next file right away, or quit if this was the last
13100 file.
13101 The event has the following fields:
13103 reason Has one of these values:
13105 eof The file has ended. This can (but doesn't have to)
13107 include incomplete files or broken network connec‐
13108 tions under circumstances.
13109 stop Playback was ended by a command.
13111 quit Playback was ended by sending the quit command.
13113 error An error happened. In this case, an error field is
13115 present with the error string.
13116 redirect
13118 Happens with playlists and similar. Details see
13119 MPV_END_FILE_REASON_REDIRECT in the C API.
13120 unknown
13122 Unknown. Normally doesn't happen, unless the Lua
13123 API is out of sync with the C API. (Likewise, it
13124 could happen that your script gets reason strings
13125 that did not exist yet at the time your script was
13126 written.)
13127 playlist_entry_id
13129 Playlist entry ID of the file that was being played or
13130 attempted to be played. This has the same value as the
13131 playlist_entry_id field in the corresponding start-file
13132 event.
13133 file_error
13135 Set to mpv error string describing the approximate reason
13136 why playback failed. Unset if no error known. (In Lua
13137 scripting, this value was set on the error field di‐
13138 rectly. This is deprecated since mpv 0.33.0. In the fu‐
13139 ture, this error field will be unset for this specific
13140 event.)
13141 playlist_insert_id
13143 If loading ended, because the playlist entry to be played
13144 was for example a playlist, and the current playlist en‐
13145 try is replaced with a number of other entries. This may
13146 happen at least with MPV_END_FILE_REASON_REDIRECT (other
13147 event types may use this for similar but different pur‐
13148 poses in the future). In this case, playlist_insert_id
13149 will be set to the playlist entry ID of the first in‐
13150 serted entry, and playlist_insert_num_entries to the to‐
13151 tal number of inserted playlist entries. Note this in
13152 this specific case, the ID of the last inserted entry is
13153 playlist_insert_id+num-1. Beware that depending on cir‐
13154 cumstances, you may observe the new playlist entries be‐
13155 fore seeing the event (e.g. reading the "playlist" prop‐
13156 erty or getting a property change notification before re‐
13157 ceiving the event). If this is 0 in the C API, this
13158 field isn't added.
13159 playlist_insert_num_entries
13161 See playlist_insert_id. Only present if playlist_in‐
13162 sert_id is present.
13163 file-loaded (MPV_EVENT_FILE_LOADED)
13165 Happens after a file was loaded and begins playback.
13166 seek (MPV_EVENT_SEEK)
13168 Happens on seeking. (This might include cases when the player
13169 seeks internally, even without user interaction. This includes
13170 e.g. segment changes when playing ordered chapters Matroska
13171 files.)
13172 playback-restart (MPV_EVENT_PLAYBACK_RESTART)
13174 Start of playback after seek or after file was loaded.
13175 shutdown (MPV_EVENT_SHUTDOWN)
13177 Sent when the player quits, and the script should terminate.
13178 Normally handled automatically. See Details on the script ini‐
13179 tialization and lifecycle.
13180 log-message (MPV_EVENT_LOG_MESSAGE)
13182 Receives messages enabled with mpv_request_log_messages() (Lua:
13183 mp.enable_messages).
13184 This contains, in addition to the default event fields, the fol‐
13186 lowing fields:
13187 prefix The module prefix, identifies the sender of the message.
13189 This is what the terminal player puts in front of the
13190 message text when using the --v option, and is also what
13191 is used for --msg-level.
13192 level The log level as string. See msg.log for possible log
13194 level names. Note that later versions of mpv might add
13195 new levels or remove (undocumented) existing ones.
13196 text The log message. The text will end with a newline charac‐
13198 ter. Sometimes it can contain multiple lines.
13199 Keep in mind that these messages are meant to be hints for hu‐
13201 mans. You should not parse them, and prefix/level/text of mes‐
13202 sages might change any time.
13203 hook The event has the following fields:
13205 hook_id
13207 ID to pass to mpv_hook_continue(). The Lua scripting
13208 wrapper provides a better API around this with
13209 mp.add_hook().
13210 get-property-reply (MPV_EVENT_GET_PROPERTY_REPLY)
13212 See C API.
13213 set-property-reply (MPV_EVENT_SET_PROPERTY_REPLY)
13215 See C API.
13216 command-reply (MPV_EVENT_COMMAND_REPLY)
13218 This is one of the commands for which the `error field is mean‐
13219 ingful.
13220 JSON IPC and Lua and possibly other backends treat this spe‐
13222 cially and may not pass the actual event to the user. See C API.
13223 The event has the following fields:
13225 result The result (on success) of any mpv_node type, if any.
13227 client-message (MPV_EVENT_CLIENT_MESSAGE)
13229 Lua and possibly other backends treat this specially and may not
13230 pass the actual event to the user.
13231 The event has the following fields:
13233 args Array of strings with the message data.
13235 video-reconfig (MPV_EVENT_VIDEO_RECONFIG)
13237 Happens on video output or filter reconfig.
13238 audio-reconfig (MPV_EVENT_AUDIO_RECONFIG)
13240 Happens on audio output or filter reconfig.
13241 property-change (MPV_EVENT_PROPERTY_CHANGE)
13243 Happens when a property that is being observed changes value.
13244 The event has the following fields:
13246 name The name of the property.
13248 data The new value of the property.
13250 The following events also happen, but are deprecated: idle, tick Use
13252 mpv_observe_property() (Lua: mp.observe_property()) instead.
13253 Hooks
13255 Hooks are synchronous events between player core and a script or simi‐
13256 lar. This applies to client API (including the Lua scripting inter‐
13257 face). Normally, events are supposed to be asynchronous, and the hook
13258 API provides an awkward and obscure way to handle events that require
13259 stricter coordination. There are no API stability guarantees made. Not
13260 following the protocol exactly can make the player freeze randomly. Ba‐
13261 sically, nobody should use this API.
13262 The C API is described in the header files. The Lua API is described in
13264 the Lua section.
13265 Before a hook is actually invoked on an API clients, it will attempt to
13267 return new values for all observed properties that were changed before
13268 the hook. This may make it easier for an application to set defined
13269 "barriers" between property change notifications by registering hooks.
13270 (That means these hooks will have an effect, even if you do nothing and
13271 make them continue immediately.)
13272 The following hooks are currently defined:
13274 on_load
13276 Called when a file is to be opened, before anything is actually
13277 done. For example, you could read and write the
13278 stream-open-filename property to redirect an URL to something
13279 else (consider support for streaming sites which rarely give the
13280 user a direct media URL), or you could set per-file options with
13281 by setting the property file-local-options/<option name>. The
13282 player will wait until all hooks are run.
13283 Ordered after start-file and before playback-restart.
13285 on_load_fail
13287 Called after after a file has been opened, but failed to. This
13288 can be used to provide a fallback in case native demuxers failed
13289 to recognize the file, instead of always running before the na‐
13290 tive demuxers like on_load. Demux will only be retried if
13291 stream-open-filename was changed. If it fails again, this hook
13292 is _not_ called again, and loading definitely fails.
13293 Ordered after on_load, and before playback-restart and end-file.
13295 on_preloaded
13297 Called after a file has been opened, and before tracks are se‐
13298 lected and decoders are created. This has some usefulness if an
13299 API users wants to select tracks manually, based on the set of
13300 available tracks. It's also useful to initialize --lavfi-complex
13301 in a specific way by API, without having to "probe" the avail‐
13302 able streams at first.
13303 Note that this does not yet apply default track selection. Which
13305 operations exactly can be done and not be done, and what infor‐
13306 mation is available and what is not yet available yet, is all
13307 subject to change.
13308 Ordered after on_load_fail etc. and before playback-restart.
13310 on_unload
13312 Run before closing a file, and before actually uninitializing
13313 everything. It's not possible to resume playback in this state.
13314 Ordered before end-file. Will also happen in the error case
13316 (then after on_load_fail).
13317 on_before_start_file
13319 Run before a start-file event is sent. (If any client changes
13320 the current playlist entry, or sends a quit command to the
13321 player, the corresponding event will not actually happen after
13322 the hook returns.) Useful to drain property changes before a
13323 new file is loaded.
13324 on_after_end_file
13326 Run after an end-file event. Useful to drain property changes
13327 after a file has finished.
13328 Input Command Prefixes
13330 These prefixes are placed between key name and the actual command. Mul‐
13331 tiple prefixes can be specified. They are separated by whitespace.
13332 osd-auto
13334 Use the default behavior for this command. This is the default
13335 for input.conf commands. Some libmpv/scripting/IPC APIs do not
13336 use this as default, but use no-osd instead.
13337 no-osd Do not use any OSD for this command.
13339 osd-bar
13341 If possible, show a bar with this command. Seek commands will
13342 show the progress bar, property changing commands may show the
13343 newly set value.
13344 osd-msg
13346 If possible, show an OSD message with this command. Seek command
13347 show the current playback time, property changing commands show
13348 the newly set value as text.
13349 osd-msg-bar
13351 Combine osd-bar and osd-msg.
13352 raw Do not expand properties in string arguments. (Like "${prop‐
13354 erty-name}".) This is the default for some libmpv/scripting/IPC
13355 APIs.
13356 expand-properties
13358 All string arguments are expanded as described in Property Ex‐
13359 pansion. This is the default for input.conf commands.
13360 repeatable
13362 For some commands, keeping a key pressed doesn't run the command
13363 repeatedly. This prefix forces enabling key repeat in any case.
13364 For a list of commands: the first command determines the re‐
13365 peatability of the whole list (up to and including version 0.33
13366 - a list was always repeatable).
13367 async Allow asynchronous execution (if possible). Note that only a few
13369 commands will support this (usually this is explicitly docu‐
13370 mented). Some commands are asynchronous by default (or rather,
13371 their effects might manifest after completion of the command).
13372 The semantics of this flag might change in the future. Set it
13373 only if you don't rely on the effects of this command being
13374 fully realized when it returns. See Synchronous vs. Asynchro‐
13375 nous.
13376 sync Allow synchronous execution (if possible). Normally, all com‐
13378 mands are synchronous by default, but some are asynchronous by
13379 default for compatibility with older behavior.
13380 All of the osd prefixes are still overridden by the global --osd-level
13382 settings.
13383 Synchronous vs. Asynchronous
13385 The async and sync prefix matter only for how the issuer of the command
13386 waits on the completion of the command. Normally it does not affect how
13387 the command behaves by itself. There are the following cases:
13388 • Normal input.conf commands are always run asynchronously. Slow run‐
13390 ning commands are queued up or run in parallel.
13391 • "Multi" input.conf commands (1 key binding, concatenated with ;) will
13393 be executed in order, except for commands that are async (either pre‐
13394 fixed with async, or async by default for some commands). The async
13395 commands are run in a detached manner, possibly in parallel to the
13396 remaining sync commands in the list.
13397 • Normal Lua and libmpv commands (e.g. mpv_command()) are run in a
13399 blocking manner, unless the async prefix is used, or the command is
13400 async by default. This means in the sync case the caller will block,
13401 even if the core continues playback. Async mode runs the command in a
13402 detached manner.
13403 • Async libmpv command API (e.g. mpv_command_async()) never blocks the
13405 caller, and always notify their completion with a message. The sync
13406 and async prefixes make no difference.
13407 • Lua also provides APIs for running async commands, which behave simi‐
13409 lar to the C counterparts.
13410 • In all cases, async mode can still run commands in a synchronous man‐
13412 ner, even in detached mode. This can for example happen in cases when
13413 a command does not have an asynchronous implementation. The async
13414 libmpv API still never blocks the caller in these cases.
13415 Before mpv 0.29.0, the async prefix was only used by screenshot com‐
13417 mands, and made them run the file saving code in a detached manner.
13418 This is the default now, and async changes behavior only in the ways
13419 mentioned above.
13420 Currently the following commands have different waiting characteristics
13422 with sync vs. async: sub-add, audio-add, sub-reload, audio-reload, res‐
13423 can-external-files, screenshot, screenshot-to-file, dump-cache,
13424 ab-loop-dump-cache.
13425 Asynchronous command details
13427 On the API level, every asynchronous command is bound to the context
13428 which started it. For example, an asynchronous command started by
13429 mpv_command_async is bound to the mpv_handle passed to the function.
13430 Only this mpv_handle receives the completion notification
13431 (MPV_EVENT_COMMAND_REPLY), and only this handle can abort a still run‐
13432 ning command directly. If the mpv_handle is destroyed, any still run‐
13433 ning async. commands started by it are terminated.
13434 The scripting APIs and JSON IPC give each script/connection its own im‐
13436 plicit mpv_handle.
13437 If the player is closed, the core may abort all pending async. commands
13439 on its own (like a forced mpv_abort_async_command() call for each pend‐
13440 ing command on behalf of the API user). This happens at the same time
13441 MPV_EVENT_SHUTDOWN is sent, and there is no way to prevent this.
13442 Input Sections
13444 Input sections group a set of bindings, and enable or disable them at
13445 once. In input.conf, each key binding is assigned to an input section,
13446 rather than actually having explicit text sections.
13447 See also: enable-section and disable-section commands.
13449 Predefined bindings:
13451 default
13453 Bindings without input section are implicitly assigned to this
13454 section. It is enabled by default during normal playback.
13455 encode Section which is active in encoding mode. It is enabled exclu‐
13457 sively, so that bindings in the default sections are ignored.
13458 Properties
13460 Properties are used to set mpv options during runtime, or to query ar‐
13461 bitrary information. They can be manipulated with the set/add/cycle
13462 commands, and retrieved with show-text, or anything else that uses
13463 property expansion. (See Property Expansion.)
13464 The property name is annotated with RW to indicate whether the property
13466 is generally writable.
13467 If an option is referenced, the property will normally take/return ex‐
13469 actly the same values as the option. In these cases, properties are
13470 merely a way to change an option at runtime.
13471 Property list
13473 NOTE:
13474 Most options can be set at runtime via properties as well. Just re‐
13475 move the leading -- from the option name. These are not documented
13476 below, see OPTIONS instead. Only properties which do not exist as
13477 option with the same name, or which have very different behavior
13478 from the options are documented below.
13479 Properties marked as (RW) are writeable, while those that aren't are
13481 read-only.
13482 audio-speed-correction, video-speed-correction
13484 Factor multiplied with speed at which the player attempts to
13485 play the file. Usually it's exactly 1. (Display sync mode will
13486 make this useful.)
13487 OSD formatting will display it in the form of +1.23456%, with
13489 the number being (raw - 1) * 100 for the given raw property
13490 value.
13491 display-sync-active
13493 Whether --video-sync=display is actually active.
13494 filename
13496 Currently played file, with path stripped. If this is an URL,
13497 try to undo percent encoding as well. (The result is not neces‐
13498 sarily correct, but looks better for display purposes. Use the
13499 path property to get an unmodified filename.)
13500 This has a sub-property:
13502 filename/no-ext
13504 Like the filename property, but if the text contains a .,
13505 strip all text after the last .. Usually this removes the
13506 file extension.
13507 file-size
13509 Length in bytes of the source file/stream. (This is the same as
13510 ${stream-end}. For segmented/multi-part files, this will return
13511 the size of the main or manifest file, whatever it is.)
13512 estimated-frame-count
13514 Total number of frames in current file.
13515 NOTE:
13517 This is only an estimate. (It's computed from two unreliable
13518 quantities: fps and stream length.)
13519 estimated-frame-number
13521 Number of current frame in current stream.
13522 NOTE:
13524 This is only an estimate. (It's computed from two unreliable
13525 quantities: fps and possibly rounded timestamps.)
13526 pid Process-id of mpv.
13528 path Full path of the currently played file. Usually this is exactly
13530 the same string you pass on the mpv command line or the loadfile
13531 command, even if it's a relative path. If you expect an absolute
13532 path, you will have to determine it yourself, for example by us‐
13533 ing the working-directory property.
13534 stream-open-filename
13536 The full path to the currently played media. This is different
13537 from path only in special cases. In particular, if --ytdl=yes is
13538 used, and the URL is detected by youtube-dl, then the script
13539 will set this property to the actual media URL. This property
13540 should be set only during the on_load or on_load_fail hooks,
13541 otherwise it will have no effect (or may do something implemen‐
13542 tation defined in the future). The property is reset if playback
13543 of the current media ends.
13544 media-title
13546 If the currently played file has a title tag, use that.
13547 Otherwise, return the filename property.
13549 file-format
13551 Symbolic name of the file format. In some cases, this is a
13552 comma-separated list of format names, e.g. mp4 is
13553 mov,mp4,m4a,3gp,3g2,mj2 (the list may grow in the future for any
13554 format).
13555 current-demuxer
13557 Name of the current demuxer. (This is useless.)
13558 (Renamed from demuxer.)
13560 stream-path
13562 Filename (full path) of the stream layer filename. (This is
13563 probably useless and is almost never different from path.)
13564 stream-pos
13566 Raw byte position in source stream. Technically, this returns
13567 the position of the most recent packet passed to a decoder.
13568 stream-end
13570 Raw end position in bytes in source stream.
13571 duration
13573 Duration of the current file in seconds. If the duration is un‐
13574 known, the property is unavailable. Note that the file duration
13575 is not always exactly known, so this is an estimate.
13576 This replaces the length property, which was deprecated after
13578 the mpv 0.9 release. (The semantics are the same.)
13579 avsync Last A/V synchronization difference. Unavailable if audio or
13581 video is disabled.
13582 total-avsync-change
13584 Total A-V sync correction done. Unavailable if audio or video is
13585 disabled.
13586 decoder-frame-drop-count
13588 Video frames dropped by decoder, because video is too far behind
13589 audio (when using --framedrop=decoder). Sometimes, this may be
13590 incremented in other situations, e.g. when video packets are
13591 damaged, or the decoder doesn't follow the usual rules. Unavail‐
13592 able if video is disabled.
13593 drop-frame-count is a deprecated alias.
13595 frame-drop-count
13597 Frames dropped by VO (when using --framedrop=vo).
13598 vo-drop-frame-count is a deprecated alias.
13600 mistimed-frame-count
13602 Number of video frames that were not timed correctly in dis‐
13603 play-sync mode for the sake of keeping A/V sync. This does not
13604 include external circumstances, such as video rendering being
13605 too slow or the graphics driver somehow skipping a vsync. It
13606 does not include rounding errors either (which can happen espe‐
13607 cially with bad source timestamps). For example, using the dis‐
13608 play-desync mode should never change this value from 0.
13609 vsync-ratio
13611 For how many vsyncs a frame is displayed on average. This is
13612 available if display-sync is active only. For 30 FPS video on a
13613 60 Hz screen, this will be 2. This is the moving average of what
13614 actually has been scheduled, so 24 FPS on 60 Hz will never re‐
13615 main exactly on 2.5, but jitter depending on the last frame dis‐
13616 played.
13617 vo-delayed-frame-count
13619 Estimated number of frames delayed due to external circumstances
13620 in display-sync mode. Note that in general, mpv has to guess
13621 that this is happening, and the guess can be inaccurate.
13622 percent-pos (RW)
13624 Position in current file (0-100). The advantage over using this
13625 instead of calculating it out of other properties is that it
13626 properly falls back to estimating the playback position from the
13627 byte position, if the file duration is not known.
13628 time-pos (RW)
13630 Position in current file in seconds.
13631 time-start
13633 Deprecated. Always returns 0. Before mpv 0.14, this used to re‐
13634 turn the start time of the file (could affect e.g. transport
13635 streams). See --rebase-start-time option.
13636 time-remaining
13638 Remaining length of the file in seconds. Note that the file du‐
13639 ration is not always exactly known, so this is an estimate.
13640 audio-pts
13642 Current audio playback position in current file in seconds. Un‐
13643 like time-pos, this updates more often than once per frame. For
13644 audio-only files, it is mostly equivalent to time-pos, while for
13645 video-only files this property is not available.
13646 playtime-remaining
13648 time-remaining scaled by the current speed.
13649 playback-time (RW)
13651 Position in current file in seconds. Unlike time-pos, the time
13652 is clamped to the range of the file. (Inaccurate file durations
13653 etc. could make it go out of range. Useful on attempts to seek
13654 outside of the file, as the seek target time is considered the
13655 current position during seeking.)
13656 chapter (RW)
13658 Current chapter number. The number of the first chapter is 0.
13659 edition (RW)
13661 Current MKV edition number. Setting this property to a different
13662 value will restart playback. The number of the first edition is
13663 0.
13664 Before mpv 0.31.0, this showed the actual edition selected at
13666 runtime, if you didn't set the option or property manually. With
13667 mpv 0.31.0 and later, this strictly returns the user-set option
13668 or property value, and the current-edition property was added to
13669 return the runtime selected edition (this matters with --edi‐
13670 tion=auto, the default).
13671 current-edition
13673 Currently selected edition. This property is unavailable if no
13674 file is loaded, or the file has no editions. (Matroska files
13675 make a difference between having no editions and a single edi‐
13676 tion, which will be reflected by the property, although in prac‐
13677 tice it does not matter.)
13678 chapters
13680 Number of chapters.
13681 editions
13683 Number of MKV editions.
13684 edition-list
13686 List of editions, current entry marked. Currently, the raw prop‐
13687 erty value is useless.
13688 This has a number of sub-properties. Replace N with the 0-based
13690 edition index.
13691 edition-list/count
13693 Number of editions. If there are no editions, this can be
13694 0 or 1 (1 if there's a useless dummy edition).
13695 edition-list/N/id (RW)
13697 Edition ID as integer. Use this to set the edition prop‐
13698 erty. Currently, this is the same as the edition index.
13699 edition-list/N/default
13701 Whether this is the default edition.
13702 edition-list/N/title
13704 Edition title as stored in the file. Not always avail‐
13705 able.
13706 When querying the property with the client API using MPV_FOR‐
13708 MAT_NODE, or with Lua mp.get_property_native, this will return a
13709 mpv_node with the following contents:
13710 MPV_FORMAT_NODE_ARRAY
13712 MPV_FORMAT_NODE_MAP (for each edition)
13713 "id" MPV_FORMAT_INT64
13714 "title" MPV_FORMAT_STRING
13715 "default" MPV_FORMAT_FLAG
13716 metadata
13718 Metadata key/value pairs.
13719 If the property is accessed with Lua's mp.get_property_native,
13721 this returns a table with metadata keys mapping to metadata val‐
13722 ues. If it is accessed with the client API, this returns a
13723 MPV_FORMAT_NODE_MAP, with tag keys mapping to tag values.
13724 For OSD, it returns a formatted list. Trying to retrieve this
13726 property as a raw string doesn't work.
13727 This has a number of sub-properties:
13729 metadata/by-key/<key>
13731 Value of metadata entry <key>.
13732 metadata/list/count
13734 Number of metadata entries.
13735 metadata/list/N/key
13737 Key name of the Nth metadata entry. (The first entry is
13738 0).
13739 metadata/list/N/value
13741 Value of the Nth metadata entry.
13742 metadata/<key>
13744 Old version of metadata/by-key/<key>. Use is discouraged,
13745 because the metadata key string could conflict with other
13746 sub-properties.
13747 The layout of this property might be subject to change. Sugges‐
13749 tions are welcome how exactly this property should work.
13750 When querying the property with the client API using MPV_FOR‐
13752 MAT_NODE, or with Lua mp.get_property_native, this will return a
13753 mpv_node with the following contents:
13754 MPV_FORMAT_NODE_MAP
13756 (key and string value for each metadata entry)
13757 filtered-metadata
13759 Like metadata, but includes only fields listed in the --dis‐
13760 play-tags option. This is the same set of tags that is printed
13761 to the terminal.
13762 chapter-metadata
13764 Metadata of current chapter. Works similar to metadata property.
13765 It also allows the same access methods (using sub-properties).
13766 Per-chapter metadata is very rare. Usually, only the chapter
13768 name (title) is set.
13769 For accessing other information, like chapter start, see the
13771 chapter-list property.
13772 vf-metadata/<filter-label>
13774 Metadata added by video filters. Accessed by the filter label,
13775 which, if not explicitly specified using the @filter-label: syn‐
13776 tax, will be <filter-name>NN.
13777 Works similar to metadata property. It allows the same access
13779 methods (using sub-properties).
13780 An example of this kind of metadata are the cropping parameters
13782 added by --vf=lavfi=cropdetect.
13783 af-metadata/<filter-label>
13785 Equivalent to vf-metadata/<filter-label>, but for audio filters.
13786 idle-active
13788 Returns yes/true if no file is loaded, but the player is staying
13789 around because of the --idle option.
13790 (Renamed from idle.)
13792 core-idle
13794 Whether the playback core is paused. This can differ from pause
13795 in special situations, such as when the player pauses itself due
13796 to low network cache.
13797 This also returns yes/true if playback is restarting or if noth‐
13799 ing is playing at all. In other words, it's only no/false if
13800 there's actually video playing. (Behavior since mpv 0.7.0.)
13801 cache-speed
13803 Current I/O read speed between the cache and the lower layer
13804 (like network). This gives the number bytes per seconds over a
13805 1 second window (using the type MPV_FORMAT_INT64 for the client
13806 API).
13807 This is the same as demuxer-cache-state/raw-input-rate.
13809 demuxer-cache-duration
13811 Approximate duration of video buffered in the demuxer, in sec‐
13812 onds. The guess is very unreliable, and often the property will
13813 not be available at all, even if data is buffered.
13814 demuxer-cache-time
13816 Approximate time of video buffered in the demuxer, in seconds.
13817 Same as demuxer-cache-duration but returns the last timestamp of
13818 buffered data in demuxer.
13819 demuxer-cache-idle
13821 Whether the demuxer is idle, which means that the demuxer cache
13822 is filled to the requested amount, and is currently not reading
13823 more data.
13824 demuxer-cache-state
13826 Each entry in seekable-ranges represents a region in the demuxer
13827 cache that can be seeked to, with a start and end fields con‐
13828 taining the respective timestamps. If there are multiple demux‐
13829 ers active, this only returns information about the "main" de‐
13830 muxer, but might be changed in future to return unified informa‐
13831 tion about all demuxers. The ranges are in arbitrary order. Of‐
13832 ten, ranges will overlap for a bit, before being joined. In
13833 broken corner cases, ranges may overlap all over the place.
13834 The end of a seek range is usually smaller than the value re‐
13836 turned by the demuxer-cache-time property, because that property
13837 returns the guessed buffering amount, while the seek ranges rep‐
13838 resent the buffered data that can actually be used for cached
13839 seeking.
13840 bof-cached indicates whether the seek range with the lowest
13842 timestamp points to the beginning of the stream (BOF). This im‐
13843 plies you cannot seek before this position at all. eof-cached
13844 indicates whether the seek range with the highest timestamp
13845 points to the end of the stream (EOF). If both bof-cached and
13846 eof-cached are true, and there's only 1 cache range, the entire
13847 stream is cached.
13848 fw-bytes is the number of bytes of packets buffered in the range
13850 starting from the current decoding position. This is a rough es‐
13851 timate (may not account correctly for various overhead), and
13852 stops at the demuxer position (it ignores seek ranges after it).
13853 file-cache-bytes is the number of bytes stored in the file
13855 cache. This includes all overhead, and possibly unused data
13856 (like pruned data). This member is missing if the file cache
13857 wasn't enabled with --cache-on-disk=yes.
13858 cache-end is demuxer-cache-time. Missing if unavailable.
13860 reader-pts is the approximate timestamp of the start of the
13862 buffered range. Missing if unavailable.
13863 cache-duration is demuxer-cache-duration. Missing if unavail‐
13865 able.
13866 raw-input-rate is the estimated input rate of the network layer
13868 (or any other byte-oriented input layer) in bytes per second.
13869 May be inaccurate or missing.
13870 When querying the property with the client API using MPV_FOR‐
13872 MAT_NODE, or with Lua mp.get_property_native, this will return a
13873 mpv_node with the following contents:
13874 MPV_FORMAT_NODE_MAP
13876 "seekable-ranges" MPV_FORMAT_NODE_ARRAY
13877 MPV_FORMAT_NODE_MAP
13878 "start" MPV_FORMAT_DOUBLE
13879 "end" MPV_FORMAT_DOUBLE
13880 "bof-cached" MPV_FORMAT_FLAG
13881 "eof-cached" MPV_FORMAT_FLAG
13882 "fw-bytes" MPV_FORMAT_INT64
13883 "file-cache-bytes" MPV_FORMAT_INT64
13884 "cache-end" MPV_FORMAT_DOUBLE
13885 "reader-pts" MPV_FORMAT_DOUBLE
13886 "cache-duration" MPV_FORMAT_DOUBLE
13887 "raw-input-rate" MPV_FORMAT_INT64
13888 Other fields (might be changed or removed in the future):
13890 eof Whether the reader thread has hit the end of the file.
13892 underrun
13894 Whether the reader thread could not satisfy a decoder's
13895 request for a new packet.
13896 idle Whether the thread is currently not reading.
13898 total-bytes
13900 Sum of packet bytes (plus some overhead estimation) of
13901 the entire packet queue, including cached seekable
13902 ranges.
13903 demuxer-via-network
13905 Whether the stream demuxed via the main demuxer is most likely
13906 played via network. What constitutes "network" is not always
13907 clear, might be used for other types of untrusted streams, could
13908 be wrong in certain cases, and its definition might be changing.
13909 Also, external files (like separate audio files or streams) do
13910 not influence the value of this property (currently).
13911 demuxer-start-time
13913 The start time reported by the demuxer in fractional seconds.
13914 paused-for-cache
13916 Whether playback is paused because of waiting for the cache.
13917 cache-buffering-state
13919 The percentage (0-100) of the cache fill status until the player
13920 will unpause (related to paused-for-cache).
13921 eof-reached
13923 Whether the end of playback was reached. Note that this is usu‐
13924 ally interesting only if --keep-open is enabled, since otherwise
13925 the player will immediately play the next file (or exit or enter
13926 idle mode), and in these cases the eof-reached property will
13927 logically be cleared immediately after it's set.
13928 seeking
13930 Whether the player is currently seeking, or otherwise trying to
13931 restart playback. (It's possible that it returns yes/true while
13932 a file is loaded. This is because the same underlying code is
13933 used for seeking and resyncing.)
13934 mixer-active
13936 Whether the audio mixer is active.
13937 This option is relatively useless. Before mpv 0.18.1, it could
13939 be used to infer behavior of the volume property.
13940 ao-volume (RW)
13942 System volume. This property is available only if mpv audio out‐
13943 put is currently active, and only if the underlying implementa‐
13944 tion supports volume control. What this option does depends on
13945 the API. For example, on ALSA this usually changes system-wide
13946 audio, while with PulseAudio this controls per-application vol‐
13947 ume.
13948 ao-mute (RW)
13950 Similar to ao-volume, but controls the mute state. May be unim‐
13951 plemented even if ao-volume works.
13952 audio-codec
13954 Audio codec selected for decoding.
13955 audio-codec-name
13957 Audio codec.
13958 audio-params
13960 Audio format as output by the audio decoder. This has a number
13961 of sub-properties:
13962 audio-params/format
13964 The sample format as string. This uses the same names as
13965 used in other places of mpv.
13966 audio-params/samplerate
13968 Samplerate.
13969 audio-params/channels
13971 The channel layout as a string. This is similar to what
13972 the --audio-channels accepts.
13973 audio-params/hr-channels
13975 As channels, but instead of the possibly cryptic actual
13976 layout sent to the audio device, return a hopefully more
13977 human readable form. (Usually only au‐
13978 dio-out-params/hr-channels makes sense.)
13979 audio-params/channel-count
13981 Number of audio channels. This is redundant to the chan‐
13982 nels field described above.
13983 When querying the property with the client API using MPV_FOR‐
13985 MAT_NODE, or with Lua mp.get_property_native, this will return a
13986 mpv_node with the following contents:
13987 MPV_FORMAT_NODE_MAP
13989 "format" MPV_FORMAT_STRING
13990 "samplerate" MPV_FORMAT_INT64
13991 "channels" MPV_FORMAT_STRING
13992 "channel-count" MPV_FORMAT_INT64
13993 "hr-channels" MPV_FORMAT_STRING
13994 audio-out-params
13996 Same as audio-params, but the format of the data written to the
13997 audio API.
13998 colormatrix
14000 Redirects to video-params/colormatrix. This parameter (as well
14001 as similar ones) can be overridden with the format video filter.
14002 colormatrix-input-range
14004 See colormatrix.
14005 colormatrix-primaries
14007 See colormatrix.
14008 hwdec (RW)
14010 Reflects the --hwdec option.
14011 Writing to it may change the currently used hardware decoder, if
14013 possible. (Internally, the player may reinitialize the decoder,
14014 and will perform a seek to refresh the video properly.) You can
14015 watch the other hwdec properties to see whether this was suc‐
14016 cessful.
14017 Unlike in mpv 0.9.x and before, this does not return the cur‐
14019 rently active hardware decoder. Since mpv 0.18.0, hwdec-current
14020 is available for this purpose.
14021 hwdec-current
14023 The current hardware decoding in use. If decoding is active, re‐
14024 turn one of the values used by the hwdec option/property.
14025 no/false indicates software decoding. If no decoder is loaded,
14026 the property is unavailable.
14027 hwdec-interop
14029 This returns the currently loaded hardware decoding/output in‐
14030 terop driver. This is known only once the VO has opened (and
14031 possibly later). With some VOs (like gpu), this might be never
14032 known in advance, but only when the decoder attempted to create
14033 the hw decoder successfully. (Using --gpu-hwdec-interop can load
14034 it eagerly.) If there are multiple drivers loaded, they will be
14035 separated by ,.
14036 If no VO is active or no interop driver is known, this property
14038 is unavailable.
14039 This does not necessarily use the same values as hwdec. There
14041 can be multiple interop drivers for the same hardware decoder,
14042 depending on platform and VO.
14043 video-format
14045 Video format as string.
14046 video-codec
14048 Video codec selected for decoding.
14049 width, height
14051 Video size. This uses the size of the video as decoded, or if no
14052 video frame has been decoded yet, the (possibly incorrect) con‐
14053 tainer indicated size.
14054 video-params
14056 Video parameters, as output by the decoder (with overrides like
14057 aspect etc. applied). This has a number of sub-properties:
14058 video-params/pixelformat
14060 The pixel format as string. This uses the same names as
14061 used in other places of mpv.
14062 video-params/hw-pixelformat
14064 The underlying pixel format as string. This is relevant
14065 for some cases of hardware decoding and unavailable oth‐
14066 erwise.
14067 video-params/average-bpp
14069 Average bits-per-pixel as integer. Subsampled planar for‐
14070 mats use a different resolution, which is the reason this
14071 value can sometimes be odd or confusing. Can be unavail‐
14072 able with some formats.
14073 video-params/w, video-params/h
14075 Video size as integers, with no aspect correction ap‐
14076 plied.
14077 video-params/dw, video-params/dh
14079 Video size as integers, scaled for correct aspect ratio.
14080 video-params/aspect
14082 Display aspect ratio as float.
14083 video-params/par
14085 Pixel aspect ratio.
14086 video-params/colormatrix
14088 The colormatrix in use as string. (Exact values subject
14089 to change.)
14090 video-params/colorlevels
14092 The colorlevels as string. (Exact values subject to
14093 change.)
14094 video-params/primaries
14096 The primaries in use as string. (Exact values subject to
14097 change.)
14098 video-params/gamma
14100 The gamma function in use as string. (Exact values sub‐
14101 ject to change.)
14102 video-params/sig-peak
14104 The video file's tagged signal peak as float.
14105 video-params/light
14107 The light type in use as a string. (Exact values subject
14108 to change.)
14109 video-params/chroma-location
14111 Chroma location as string. (Exact values subject to
14112 change.)
14113 video-params/rotate
14115 Intended display rotation in degrees (clockwise).
14116 video-params/stereo-in
14118 Source file stereo 3D mode. (See the format video fil‐
14119 ter's stereo-in option.)
14120 video-params/alpha
14122 Alpha type. If the format has no alpha channel, this will
14123 be unavailable (but in future releases, it could change
14124 to no). If alpha is present, this is set to straight or
14125 premul.
14126 When querying the property with the client API using MPV_FOR‐
14128 MAT_NODE, or with Lua mp.get_property_native, this will return a
14129 mpv_node with the following contents:
14130 MPV_FORMAT_NODE_MAP
14132 "pixelformat" MPV_FORMAT_STRING
14133 "hw-pixelformat" MPV_FORMAT_STRING
14134 "w" MPV_FORMAT_INT64
14135 "h" MPV_FORMAT_INT64
14136 "dw" MPV_FORMAT_INT64
14137 "dh" MPV_FORMAT_INT64
14138 "aspect" MPV_FORMAT_DOUBLE
14139 "par" MPV_FORMAT_DOUBLE
14140 "colormatrix" MPV_FORMAT_STRING
14141 "colorlevels" MPV_FORMAT_STRING
14142 "primaries" MPV_FORMAT_STRING
14143 "gamma" MPV_FORMAT_STRING
14144 "sig-peak" MPV_FORMAT_DOUBLE
14145 "light" MPV_FORMAT_STRING
14146 "chroma-location" MPV_FORMAT_STRING
14147 "rotate" MPV_FORMAT_INT64
14148 "stereo-in" MPV_FORMAT_STRING
14149 "average-bpp" MPV_FORMAT_INT64
14150 "alpha" MPV_FORMAT_STRING
14151 dwidth, dheight
14153 Video display size. This is the video size after filters and as‐
14154 pect scaling have been applied. The actual video window size can
14155 still be different from this, e.g. if the user resized the video
14156 window manually.
14157 These have the same values as video-out-params/dw and
14159 video-out-params/dh.
14160 video-dec-params
14162 Exactly like video-params, but no overrides applied.
14163 video-out-params
14165 Same as video-params, but after video filters have been applied.
14166 If there are no video filters in use, this will contain the same
14167 values as video-params. Note that this is still not necessarily
14168 what the video window uses, since the user can change the window
14169 size, and all real VOs do their own scaling independently from
14170 the filter chain.
14171 Has the same sub-properties as video-params.
14173 video-frame-info
14175 Approximate information of the current frame. Note that if any
14176 of these are used on OSD, the information might be off by a few
14177 frames due to OSD redrawing and frame display being somewhat
14178 disconnected, and you might have to pause and force a redraw.
14179 This has a number of sub-properties:
14181 video-frame-info/picture-type
14183 The type of the picture. It can be "I" (intra), "P" (pre‐
14184 dicted), "B" (bi-dir predicted) or unavailable.
14185 video-frame-info/interlaced
14187 Whether the content of the frame is interlaced.
14188 video-frame-info/tff
14190 If the content is interlaced, whether the top field is
14191 displayed first.
14192 video-frame-info/repeat
14194 Whether the frame must be delayed when decoding.
14195 container-fps
14197 Container FPS. This can easily contain bogus values. For videos
14198 that use modern container formats or video codecs, this will of‐
14199 ten be incorrect.
14200 (Renamed from fps.)
14202 estimated-vf-fps
14204 Estimated/measured FPS of the video filter chain output. (If no
14205 filters are used, this corresponds to decoder output.) This uses
14206 the average of the 10 past frame durations to calculate the FPS.
14207 It will be inaccurate if frame-dropping is involved (such as
14208 when framedrop is explicitly enabled, or after precise seeking).
14209 Files with imprecise timestamps (such as Matroska) might lead to
14210 unstable results.
14211 window-scale (RW)
14213 Window size multiplier. Setting this will resize the video win‐
14214 dow to the values contained in dwidth and dheight multiplied
14215 with the value set with this property. Setting 1 will resize to
14216 original video size (or to be exact, the size the video filters
14217 output). 2 will set the double size, 0.5 halves the size.
14218 Note that setting a value identical to its previous value will
14220 not resize the window. That's because this property mirrors the
14221 window-scale option, and setting an option to its previous value
14222 is ignored. If this value is set while the window is in a
14223 fullscreen, the multiplier is not applied until the window is
14224 taken out of that state. Writing this property to a maximized
14225 window can unmaximize the window depending on the OS and window
14226 manager. If the window does not unmaximize, the multiplier will
14227 be applied if the user unmaximizes the window later.
14228 See current-window-scale for the value derived from the actual
14230 window size.
14231 Since mpv 0.31.0, this always returns the previously set value
14233 (or the default value), instead of the value implied by the ac‐
14234 tual window size. Before mpv 0.31.0, this returned what cur‐
14235 rent-window-scale returns now, after the window was created.
14236 current-window-scale (RW)
14238 The window-scale value calculated from the current window size.
14239 This has the same value as window-scale if the window size was
14240 not changed since setting the option, and the window size was
14241 not restricted in other ways. If the window is fullscreened,
14242 this will return the scale value calculated from the last
14243 non-fullscreen size of the window. The property is unavailable
14244 if no video is active.
14245 When setting this property in the fullscreen or maximized state,
14247 the behavior is the same as window-scale. In all ther cases,
14248 setting the value of this property will always resize the win‐
14249 dow. This does not affect the value of window-scale.
14250 focused
14252 Whether the window has focus. Might not be supported by all VOs.
14253 display-names
14255 Names of the displays that the mpv window covers. On X11, these
14256 are the xrandr names (LVDS1, HDMI1, DP1, VGA1, etc.). On Win‐
14257 dows, these are the GDI names (\.DISPLAY1, \.DISPLAY2, etc.) and
14258 the first display in the list will be the one that Windows con‐
14259 siders associated with the window (as determined by the Monitor‐
14260 FromWindow API.) On macOS these are the Display Product Names as
14261 used in the System Information and only one display name is re‐
14262 turned since a window can only be on one screen.
14263 display-fps
14265 The refresh rate of the current display. Currently, this is the
14266 lowest FPS of any display covered by the video, as retrieved by
14267 the underlying system APIs (e.g. xrandr on X11). It is not the
14268 measured FPS. It's not necessarily available on all platforms.
14269 Note that any of the listed facts may change any time without a
14270 warning.
14271 Writing to this property is deprecated. It has the same effect
14273 as writing to override-display-fps. Since mpv 0.31.0, this prop‐
14274 erty is unavailable if no display FPS was reported (e.g. if no
14275 video is active), while in older versions, it returned the
14276 --display-fps option value.
14277 estimated-display-fps
14279 The actual rate at which display refreshes seem to occur, mea‐
14280 sured by system time. Only available if display-sync mode (as
14281 selected by --video-sync) is active.
14282 vsync-jitter
14284 Estimated deviation factor of the vsync duration.
14285 display-width, display-height
14287 The current display's horizontal and vertical resolution in pix‐
14288 els. Whether or not these values update as the mpv window
14289 changes displays depends on the windowing backend. It may not be
14290 available on all platforms.
14291 display-hidpi-scale
14293 The HiDPI scale factor as reported by the windowing backend. If
14294 no VO is active, or if the VO does not report a value, this
14295 property is unavailable. It may be saner to report an absolute
14296 DPI, however, this is the way HiDPI support is implemented on
14297 most OS APIs. See also --hidpi-window-scale.
14298 video-aspect (RW)
14300 Deprecated. This is tied to --video-aspect-override, but always
14301 reports the current video aspect if video is active.
14302 The read and write components of this option can be split up
14304 into video-params/aspect and video-aspect-override respectively.
14305 osd-width, osd-height
14307 Last known OSD width (can be 0). This is needed if you want to
14308 use the overlay-add command. It gives you the actual OSD/window
14309 size (not including decorations drawn by the OS window manager).
14310 Alias to osd-dimensions/w and osd-dimensions/h.
14312 osd-par
14314 Last known OSD display pixel aspect (can be 0).
14315 Alias to osd-dimensions/osd-par.
14317 osd-dimensions
14319 Last known OSD dimensions.
14320 Has the following sub-properties (which can be read as MPV_FOR‐
14322 MAT_NODE or Lua table with mp.get_property_native):
14323 osd-dimensions/w
14325 Size of the VO window in OSD render units (usually pix‐
14326 els, but may be scaled pixels with VOs like xv).
14327 osd-dimensions/h
14329 Size of the VO window in OSD render units,
14330 osd-dimensions/par
14332 Pixel aspect ratio of the OSD (usually 1).
14333 osd-dimensions/aspect
14335 Display aspect ratio of the VO window. (Computing from
14336 the properties above.)
14337 osd-dimensions/mt, osd-dimensions/mb, osd-dimensions/ml, osd-di‐
14339 mensions/mr
14340 OSD to video margins (top, bottom, left, right). This de‐
14341 scribes the area into which the video is rendered.
14342 Any of these properties may be unavailable or set to dummy val‐
14344 ues if the VO window is not created or visible.
14345 mouse-pos
14347 Read-only - last known mouse position, normalizd to OSD dimen‐
14348 sions.
14349 Has the following sub-properties (which can be read as MPV_FOR‐
14351 MAT_NODE or Lua table with mp.get_property_native):
14352 mouse-pos/x, mouse-pos/y
14354 Last known coordinates of the mouse pointer.
14355 mouse-pos/hover
14357 Boolean - whether the mouse pointer hovers the video win‐
14358 dow. The coordinates should be ignored when this value is
14359 false, because the video backends update them only when
14360 the pointer hovers the window.
14361 sub-text
14363 The current subtitle text regardless of sub visibility. Format‐
14364 ting is stripped. If the subtitle is not text-based (i.e. DVD/BD
14365 subtitles), an empty string is returned.
14366 This property is experimental and might be removed in the fu‐
14368 ture.
14369 sub-text-ass
14371 Like sub-text, but return the text in ASS format. Text subtitles
14372 in other formats are converted. For native ASS subtitles, events
14373 that do not contain any text (but vector drawings etc.) are not
14374 filtered out. If multiple events match with the current playback
14375 time, they are concatenated with line breaks. Contains only the
14376 "Text" part of the events.
14377 This property is not enough to render ASS subtitles correctly,
14379 because ASS header and per-event metadata are not returned. You
14380 likely need to do further filtering on the returned string to
14381 make it useful.
14382 This property is experimental and might be removed in the fu‐
14384 ture.
14385 secondary-sub-text
14387 Same as sub-text, but for the secondary subtitles.
14388 sub-start
14390 The current subtitle start time (in seconds). If there's multi‐
14391 ple current subtitles, returns the first start time. If no cur‐
14392 rent subtitle is present null is returned instead.
14393 secondary-sub-start
14395 Same as sub-start, but for the secondary subtitles.
14396 sub-end
14398 The current subtitle end time (in seconds). If there's multiple
14399 current subtitles, return the last end time. If no current sub‐
14400 title is present, or if it's present but has unknown or incor‐
14401 rect duration, null is returned instead.
14402 secondary-sub-end
14404 Same as sub-end, but for the secondary subtitles.
14405 playlist-pos (RW)
14407 Current position on playlist. The first entry is on position 0.
14408 Writing to this property may start playback at the new position.
14409 In some cases, this is not necessarily the currently playing
14411 file. See explanation of current and playing flags in playlist.
14412 If there the playlist is empty, or if it's non-empty, but no en‐
14414 try is "current", this property returns -1. Likewise, writing -1
14415 will put the player into idle mode (or exit playback if idle
14416 mode is not enabled). If an out of range index is written to the
14417 property, this behaves as if writing -1. (Before mpv 0.33.0,
14418 instead of returning -1, this property was unavailable if no
14419 playlist entry was current.)
14420 Writing the current value back to the property is subject to
14422 change. Currently, it will restart playback of the playlist en‐
14423 try. But in the future, writing the current value will be ig‐
14424 nored. Use the playlist-play-index command to get guaranteed be‐
14425 havior.
14426 playlist-pos-1 (RW)
14428 Same as playlist-pos, but 1-based.
14429 playlist-current-pos (RW)
14431 Index of the "current" item on playlist. This usually, but not
14432 necessarily, the currently playing item (see playlist-play‐
14433 ing-pos). Depending on the exact internal state of the player,
14434 it may refer to the playlist item to play next, or the playlist
14435 item used to determine what to play next.
14436 For reading, this is exactly the same as playlist-pos.
14438 For writing, this only sets the position of the "current" item,
14440 without stopping playback of the current file (or starting play‐
14441 back, if this is done in idle mode). Use -1 to remove the cur‐
14442 rent flag.
14443 This property is only vaguely useful. If set during playback, it
14445 will typically cause the playlist entry after it to be played
14446 next. Another possibly odd observable state is that if
14447 playlist-next is run during playback, this property is set to
14448 the playlist entry to play next (unlike the previous case).
14449 There is an internal flag that decides whether the current
14450 playlist entry or the next one should be played, and this flag
14451 is currently inaccessible for API users. (Whether this behavior
14452 will kept is possibly subject to change.)
14453 playlist-playing-pos
14455 Index of the "playing" item on playlist. A playlist item is
14456 "playing" if it's being loaded, actually playing, or being un‐
14457 loaded. This property is set during the MPV_EVENT_START_FILE
14458 (start-file) and the MPV_EVENT_START_END (end-file) events. Out‐
14459 side of that, it returns -1. If the playlist entry was somehow
14460 removed during playback, but playback hasn't stopped yet, or is
14461 in progress of being stopped, it also returns -1. (This can
14462 happen at least during state transitions.)
14463 In the "playing" state, this is usually the same as
14465 playlist-pos, except during state changes, or if playlist-cur‐
14466 rent-pos was written explicitly.
14467 playlist-count
14469 Number of total playlist entries.
14470 playlist
14472 Playlist, current entry marked. Currently, the raw property
14473 value is useless.
14474 This has a number of sub-properties. Replace N with the 0-based
14476 playlist entry index.
14477 playlist/count
14479 Number of playlist entries (same as playlist-count).
14480 playlist/N/filename
14482 Filename of the Nth entry.
14483 playlist/N/playing
14485 yes/true if the playlist-playing-pos property points to
14486 this entry, no/false or unavailable otherwise.
14487 playlist/N/current
14489 yes/true if the playlist-current-pos property points to
14490 this entry, no/false or unavailable otherwise.
14491 playlist/N/title
14493 Name of the Nth entry. Only available if the playlist
14494 file contains such fields, and only if mpv's parser sup‐
14495 ports it for the given playlist format.
14496 playlist/N/id
14498 Unique ID for this entry. This is an automatically as‐
14499 signed integer ID that is unique for the entire life time
14500 of the current mpv core instance. Other commands, events,
14501 etc. use this as playlist_entry_id fields.
14502 When querying the property with the client API using MPV_FOR‐
14504 MAT_NODE, or with Lua mp.get_property_native, this will return a
14505 mpv_node with the following contents:
14506 MPV_FORMAT_NODE_ARRAY
14508 MPV_FORMAT_NODE_MAP (for each playlist entry)
14509 "filename" MPV_FORMAT_STRING
14510 "current" MPV_FORMAT_FLAG (might be missing; since mpv 0.7.0)
14511 "playing" MPV_FORMAT_FLAG (same)
14512 "title" MPV_FORMAT_STRING (optional)
14513 "id" MPV_FORMAT_INT64
14514 track-list
14516 List of audio/video/sub tracks, current entry marked. Currently,
14517 the raw property value is useless.
14518 This has a number of sub-properties. Replace N with the 0-based
14520 track index.
14521 track-list/count
14523 Total number of tracks.
14524 track-list/N/id
14526 The ID as it's used for -sid/--aid/--vid. This is unique
14527 within tracks of the same type (sub/audio/video), but
14528 otherwise not.
14529 track-list/N/type
14531 String describing the media type. One of audio, video,
14532 sub.
14533 track-list/N/src-id
14535 Track ID as used in the source file. Not always avail‐
14536 able. (It is missing if the format has no native ID, if
14537 the track is a pseudo-track that does not exist in this
14538 way in the actual file, or if the format is handled by
14539 libavformat, and the format was not whitelisted as having
14540 track IDs.)
14541 track-list/N/title
14543 Track title as it is stored in the file. Not always
14544 available.
14545 track-list/N/lang
14547 Track language as identified by the file. Not always
14548 available.
14549 track-list/N/image
14551 yes/true if this is a video track that consists of a sin‐
14552 gle picture, no/false or unavailable otherwise. The
14553 heuristic used to determine if a stream is an image
14554 doesn't attempt to detect images in codecs normally used
14555 for videos. Otherwise, it is reliable.
14556 track-list/N/albumart
14558 yes/true if this is an image embedded in an audio file or
14559 external cover art, no/false or unavailable otherwise.
14560 track-list/N/default
14562 yes/true if the track has the default flag set in the
14563 file, no/false or unavailable otherwise.
14564 track-list/N/forced
14566 yes/true if the track has the forced flag set in the
14567 file, no/false or unavailable otherwise.
14568 track-list/N/codec
14570 The codec name used by this track, for example h264. Un‐
14571 available in some rare cases.
14572 track-list/N/external
14574 yes/true if the track is an external file, no/false or
14575 unavailable otherwise. This is set for separate subtitle
14576 files.
14577 track-list/N/external-filename
14579 The filename if the track is from an external file, un‐
14580 available otherwise.
14581 track-list/N/selected
14583 yes/true if the track is currently decoded, no/false or
14584 unavailable otherwise.
14585 track-list/N/main-selection
14587 It indicates the selection order of tracks for the same
14588 type. If a track is not selected, or is selected by the
14589 --lavfi-complex, it is not available. For subtitle
14590 tracks, 0 represents the sid, and 1 represents the sec‐
14591 ondary-sid.
14592 track-list/N/ff-index
14594 The stream index as usually used by the FFmpeg utilities.
14595 Note that this can be potentially wrong if a demuxer
14596 other than libavformat (--demuxer=lavf) is used. For mkv
14597 files, the index will usually match even if the default
14598 (builtin) demuxer is used, but there is no hard guaran‐
14599 tee.
14600 track-list/N/decoder-desc
14602 If this track is being decoded, the human-readable de‐
14603 coder name,
14604 track-list/N/demux-w, track-list/N/demux-h
14606 Video size hint as indicated by the container. (Not al‐
14607 ways accurate.)
14608 track-list/N/demux-channel-count
14610 Number of audio channels as indicated by the container.
14611 (Not always accurate - in particular, the track could be
14612 decoded as a different number of channels.)
14613 track-list/N/demux-channels
14615 Channel layout as indicated by the container. (Not always
14616 accurate.)
14617 track-list/N/demux-samplerate
14619 Audio sample rate as indicated by the container. (Not al‐
14620 ways accurate.)
14621 track-list/N/demux-fps
14623 Video FPS as indicated by the container. (Not always ac‐
14624 curate.)
14625 track-list/N/demux-bitrate
14627 Audio average bitrate, in bits per second. (Not always
14628 accurate.)
14629 track-list/N/demux-rotation
14631 Video clockwise rotation metadata, in degrees.
14632 track-list/N/demux-par
14634 Pixel aspect ratio.
14635 track-list/N/audio-channels (deprecated)
14637 Deprecated alias for track-list/N/demux-channel-count.
14638 track-list/N/replaygain-track-peak, track-list/N/replay‐
14640 gain-track-gain
14641 Per-track replaygain values. Only available for audio
14642 tracks with corresponding information stored in the
14643 source file.
14644 track-list/N/replaygain-album-peak, track-list/N/replaygain-al‐
14646 bum-gain
14647 Per-album replaygain values. If the file has per-track
14648 but no per-album information, the per-album values will
14649 be copied from the per-track values currently. It's pos‐
14650 sible that future mpv versions will make these properties
14651 unavailable instead in this case.
14652 When querying the property with the client API using MPV_FOR‐
14654 MAT_NODE, or with Lua mp.get_property_native, this will return a
14655 mpv_node with the following contents:
14656 MPV_FORMAT_NODE_ARRAY
14658 MPV_FORMAT_NODE_MAP (for each track)
14659 "id" MPV_FORMAT_INT64
14660 "type" MPV_FORMAT_STRING
14661 "src-id" MPV_FORMAT_INT64
14662 "title" MPV_FORMAT_STRING
14663 "lang" MPV_FORMAT_STRING
14664 "image" MPV_FORMAT_FLAG
14665 "albumart" MPV_FORMAT_FLAG
14666 "default" MPV_FORMAT_FLAG
14667 "forced" MPV_FORMAT_FLAG
14668 "selected" MPV_FORMAT_FLAG
14669 "main-selection" MPV_FORMAT_INT64
14670 "external" MPV_FORMAT_FLAG
14671 "external-filename" MPV_FORMAT_STRING
14672 "codec" MPV_FORMAT_STRING
14673 "ff-index" MPV_FORMAT_INT64
14674 "decoder-desc" MPV_FORMAT_STRING
14675 "demux-w" MPV_FORMAT_INT64
14676 "demux-h" MPV_FORMAT_INT64
14677 "demux-channel-count" MPV_FORMAT_INT64
14678 "demux-channels" MPV_FORMAT_STRING
14679 "demux-samplerate" MPV_FORMAT_INT64
14680 "demux-fps" MPV_FORMAT_DOUBLE
14681 "demux-bitrate" MPV_FORMAT_INT64
14682 "demux-rotation" MPV_FORMAT_INT64
14683 "demux-par" MPV_FORMAT_DOUBLE
14684 "audio-channels" MPV_FORMAT_INT64
14685 "replaygain-track-peak" MPV_FORMAT_DOUBLE
14686 "replaygain-track-gain" MPV_FORMAT_DOUBLE
14687 "replaygain-album-peak" MPV_FORMAT_DOUBLE
14688 "replaygain-album-gain" MPV_FORMAT_DOUBLE
14689 current-tracks/...
14691 This gives access to currently selected tracks. It redirects to
14692 the correct entry in track-list.
14693 The following sub-entries are defined: video, audio, sub, sub2
14695 For example, current-tracks/audio/lang returns the current audio
14697 track's language field (the same value as track-list/N/lang).
14698 If tracks of the requested type are selected via --lavfi-com‐
14700 plex, the first one is returned.
14701 chapter-list (RW)
14703 List of chapters, current entry marked. Currently, the raw prop‐
14704 erty value is useless.
14705 This has a number of sub-properties. Replace N with the 0-based
14707 chapter index.
14708 chapter-list/count
14710 Number of chapters.
14711 chapter-list/N/title
14713 Chapter title as stored in the file. Not always avail‐
14714 able.
14715 chapter-list/N/time
14717 Chapter start time in seconds as float.
14718 When querying the property with the client API using MPV_FOR‐
14720 MAT_NODE, or with Lua mp.get_property_native, this will return a
14721 mpv_node with the following contents:
14722 MPV_FORMAT_NODE_ARRAY
14724 MPV_FORMAT_NODE_MAP (for each chapter)
14725 "title" MPV_FORMAT_STRING
14726 "time" MPV_FORMAT_DOUBLE
14727 af, vf (RW)
14729 See --vf/--af and the vf/af command.
14730 When querying the property with the client API using MPV_FOR‐
14732 MAT_NODE, or with Lua mp.get_property_native, this will return a
14733 mpv_node with the following contents:
14734 MPV_FORMAT_NODE_ARRAY
14736 MPV_FORMAT_NODE_MAP (for each filter entry)
14737 "name" MPV_FORMAT_STRING
14738 "label" MPV_FORMAT_STRING [optional]
14739 "enabled" MPV_FORMAT_FLAG [optional]
14740 "params" MPV_FORMAT_NODE_MAP [optional]
14741 "key" MPV_FORMAT_STRING
14742 "value" MPV_FORMAT_STRING
14743 It's also possible to write the property using this format.
14745 seekable
14747 Whether it's generally possible to seek in the current file.
14748 partially-seekable
14750 Whether the current file is considered seekable, but only be‐
14751 cause the cache is active. This means small relative seeks may
14752 be fine, but larger seeks may fail anyway. Whether a seek will
14753 succeed or not is generally not known in advance.
14754 If this property returns yes/true, so will seekable.
14756 playback-abort
14758 Whether playback is stopped or is to be stopped. (Useful in ob‐
14759 scure situations like during on_load hook processing, when the
14760 user can stop playback, but the script has to explicitly end
14761 processing.)
14762 cursor-autohide (RW)
14764 See --cursor-autohide. Setting this to a new value will always
14765 update the cursor, and reset the internal timer.
14766 osd-sym-cc
14768 Inserts the current OSD symbol as opaque OSD control code (cc).
14769 This makes sense only with the show-text command or options
14770 which set OSD messages. The control code is implementation spe‐
14771 cific and is useless for anything else.
14772 osd-ass-cc
14774 ${osd-ass-cc/0} disables escaping ASS sequences of text in OSD,
14775 ${osd-ass-cc/1} enables it again. By default, ASS sequences are
14776 escaped to avoid accidental formatting, and this property can
14777 disable this behavior. Note that the properties return an opaque
14778 OSD control code, which only makes sense for the show-text com‐
14779 mand or options which set OSD messages.
14780 Example
14782 • --osd-msg3='This is ${osd-ass-cc/0}{\\b1}bold text'
14784 • show-text "This is ${osd-ass-cc/0}{\\b1}bold text"
14786 Any ASS override tags as understood by libass can be used.
14788 Note that you need to escape the \ character, because the string
14790 is processed for C escape sequences before passing it to the OSD
14791 code. See Flat command syntax for details.
14792 A list of tags can be found here:
14794 https://aeg-dev.github.io/AegiSite/docs/3.2/ass_tags/
14795 vo-configured
14797 Whether the VO is configured right now. Usually this corresponds
14798 to whether the video window is visible. If the --force-window
14799 option is used, this usually always returns yes/true.
14800 vo-passes
14802 Contains introspection about the VO's active render passes and
14803 their execution times. Not implemented by all VOs.
14804 This is further subdivided into two frame types, vo-passes/fresh
14806 for fresh frames (which have to be uploaded, scaled, etc.) and
14807 vo-passes/redraw for redrawn frames (which only have to be
14808 re-painted). The number of passes for any given subtype can
14809 change from frame to frame, and should not be relied upon.
14810 Each frame type has a number of further sub-properties. Replace
14812 TYPE with the frame type, N with the 0-based pass index, and M
14813 with the 0-based sample index.
14814 vo-passes/TYPE/count
14816 Number of passes.
14817 vo-passes/TYPE/N/desc
14819 Human-friendy description of the pass.
14820 vo-passes/TYPE/N/last
14822 Last measured execution time, in nanoseconds.
14823 vo-passes/TYPE/N/avg
14825 Average execution time of this pass, in nanoseconds. The
14826 exact timeframe varies, but it should generally be a
14827 handful of seconds.
14828 vo-passes/TYPE/N/peak
14830 The peak execution time (highest value) within this aver‐
14831 aging range, in nanoseconds.
14832 vo-passes/TYPE/N/count
14834 The number of samples for this pass.
14835 vo-passes/TYPE/N/samples/M
14837 The raw execution time of a specific sample for this
14838 pass, in nanoseconds.
14839 When querying the property with the client API using MPV_FOR‐
14841 MAT_NODE, or with Lua mp.get_property_native, this will return a
14842 mpv_node with the following contents:
14843 MPV_FORMAT_NODE_MAP
14845 "TYPE" MPV_FORMAT_NODE_ARRAY
14846 MPV_FORMAT_NODE_MAP
14847 "desc" MPV_FORMAT_STRING
14848 "last" MPV_FORMAT_INT64
14849 "avg" MPV_FORMAT_INT64
14850 "peak" MPV_FORMAT_INT64
14851 "count" MPV_FORMAT_INT64
14852 "samples" MPV_FORMAT_NODE_ARRAY
14853 MP_FORMAT_INT64
14854 Note that directly accessing this structure via subkeys is not
14856 supported, the only access is through aforementioned MPV_FOR‐
14857 MAT_NODE.
14858 perf-info
14860 Further performance data. Querying this property triggers inter‐
14861 nal collection of some data, and may slow down the player. Each
14862 query will reset some internal state. Property change notifica‐
14863 tion doesn't and won't work. All of this may change in the fu‐
14864 ture, so don't use this. The builtin stats script is supposed to
14865 be the only user; since it's bundled and built with the source
14866 code, it can use knowledge of mpv internal to render the infor‐
14867 mation properly. See stats script description for some details.
14868 video-bitrate, audio-bitrate, sub-bitrate
14870 Bitrate values calculated on the packet level. This works by di‐
14871 viding the bit size of all packets between two keyframes by
14872 their presentation timestamp distance. (This uses the timestamps
14873 are stored in the file, so e.g. playback speed does not influ‐
14874 ence the returned values.) In particular, the video bitrate will
14875 update only per keyframe, and show the "past" bitrate. To make
14876 the property more UI friendly, updates to these properties are
14877 throttled in a certain way.
14878 The unit is bits per second. OSD formatting turns these values
14880 in kilobits (or megabits, if appropriate), which can be pre‐
14881 vented by using the raw property value, e.g. with ${=video-bi‐
14882 trate}.
14883 Note that the accuracy of these properties is influenced by a
14885 few factors. If the underlying demuxer rewrites the packets on
14886 demuxing (done for some file formats), the bitrate might be
14887 slightly off. If timestamps are bad or jittery (like in Ma‐
14888 troska), even constant bitrate streams might show fluctuating
14889 bitrate.
14890 How exactly these values are calculated might change in the fu‐
14892 ture.
14893 In earlier versions of mpv, these properties returned a static
14895 (but bad) guess using a completely different method.
14896 packet-video-bitrate, packet-audio-bitrate, packet-sub-bitrate
14898 Old and deprecated properties for video-bitrate, audio-bitrate,
14899 sub-bitrate. They behave exactly the same, but return a value in
14900 kilobits. Also, they don't have any OSD formatting, though the
14901 same can be achieved with e.g. ${=video-bitrate}.
14902 These properties shouldn't be used anymore.
14904 audio-device-list
14906 The list of discovered audio devices. This is mostly for use
14907 with the client API, and reflects what --audio-device=help with
14908 the command line player returns.
14909 When querying the property with the client API using MPV_FOR‐
14911 MAT_NODE, or with Lua mp.get_property_native, this will return a
14912 mpv_node with the following contents:
14913 MPV_FORMAT_NODE_ARRAY
14915 MPV_FORMAT_NODE_MAP (for each device entry)
14916 "name" MPV_FORMAT_STRING
14917 "description" MPV_FORMAT_STRING
14918 The name is what is to be passed to the --audio-device option
14920 (and often a rather cryptic audio API-specific ID), while de‐
14921 scription is human readable free form text. The description is
14922 set to the device name (minus mpv-specific <driver>/ prefix) if
14923 no description is available or the description would have been
14924 an empty string.
14925 The special entry with the name set to auto selects the default
14927 audio output driver and the default device.
14928 The property can be watched with the property observation mecha‐
14930 nism in the client API and in Lua scripts. (Technically, change
14931 notification is enabled the first time this property is read.)
14932 audio-device (RW)
14934 Set the audio device. This directly reads/writes the --audio-de‐
14935 vice option, but on write accesses, the audio output will be
14936 scheduled for reloading.
14937 Writing this property while no audio output is active will not
14939 automatically enable audio. (This is also true in the case when
14940 audio was disabled due to reinitialization failure after a pre‐
14941 vious write access to audio-device.)
14942 This property also doesn't tell you which audio device is actu‐
14944 ally in use.
14945 How these details are handled may change in the future.
14947 current-vo
14949 Current video output driver (name as used with --vo).
14950 current-ao
14952 Current audio output driver (name as used with --ao).
14953 shared-script-properties (RW)
14955 This is a key/value map of arbitrary strings shared between
14956 scripts for general use. The player itself does not use any data
14957 in it (although some builtin scripts may). The property is not
14958 preserved across player restarts.
14959 This is very primitive, inefficient, and annoying to use. It's a
14961 makeshift solution which could go away any time (for example,
14962 when a better solution becomes available). This is also why this
14963 property has an annoying name. You should avoid using it, unless
14964 you absolutely have to.
14965 Lua scripting has helpers starting with
14967 utils.shared_script_property_. They are undocumented because
14968 you should not use this property. If you still think you must,
14969 you should use the helpers instead of the property directly.
14970 You are supposed to use the change-list command to modify the
14972 contents. Reading, modifying, and writing the property manually
14973 could data loss if two scripts update different keys at the same
14974 time due to lack of synchronization. The Lua helpers take care
14975 of this.
14976 (There is no way to ensure synchronization if two scripts try to
14978 update the same key at the same time.)
14979 working-directory
14981 The working directory of the mpv process. Can be useful for JSON
14982 IPC users, because the command line player usually works with
14983 relative paths.
14984 protocol-list
14986 List of protocol prefixes potentially recognized by the player.
14987 They are returned without trailing :// suffix (which is still
14988 always required). In some cases, the protocol will not actually
14989 be supported (consider https if ffmpeg is not compiled with TLS
14990 support).
14991 decoder-list
14993 List of decoders supported. This lists decoders which can be
14994 passed to --vd and --ad.
14995 codec Canonical codec name, which identifies the format the de‐
14997 coder can handle.
14998 driver The name of the decoder itself. Often, this is the same
15000 as codec. Sometimes it can be different. It is used to
15001 distinguish multiple decoders for the same codec.
15002 description
15004 Human readable description of the decoder and codec.
15005 When querying the property with the client API using MPV_FOR‐
15007 MAT_NODE, or with Lua mp.get_property_native, this will return a
15008 mpv_node with the following contents:
15009 MPV_FORMAT_NODE_ARRAY
15011 MPV_FORMAT_NODE_MAP (for each decoder entry)
15012 "codec" MPV_FORMAT_STRING
15013 "driver" MPV_FORMAT_STRING
15014 "description" MPV_FORMAT_STRING
15015 encoder-list
15017 List of libavcodec encoders. This has the same format as de‐
15018 coder-list. The encoder names (driver entries) can be passed to
15019 --ovc and --oac (without the lavc: prefix required by --vd and
15020 --ad).
15021 demuxer-lavf-list
15023 List of available libavformat demuxers' names. This can be used
15024 to check for support for a specific format or use with --de‐
15025 muxer-lavf-format.
15026 input-key-list
15028 List of Key names, same as output by --input-keylist.
15029 mpv-version
15031 The mpv version/copyright string. Depending on how the binary
15032 was built, it might contain either a release version, or just a
15033 git hash.
15034 mpv-configuration
15036 The configuration arguments which were passed to the build sys‐
15037 tem (typically the way ./waf configure ... was invoked).
15038 ffmpeg-version
15040 The contents of the av_version_info() API call. This is a string
15041 which identifies the build in some way, either through a release
15042 version number, or a git hash. This applies to Libav as well
15043 (the property is still named the same.) This property is un‐
15044 available if mpv is linked against older FFmpeg and Libav ver‐
15045 sions.
15046 libass-version
15048 The value of ass_library_version(). This is an integer, encoded
15049 in a somewhat weird form (apparently "hex BCD"), indicating the
15050 release version of the libass library linked to mpv.
15051 options/<name> (RW)
15053 The value of option --<name>. Most options can be changed at
15054 runtime by writing to this property. Note that many options re‐
15055 quire reloading the file for changes to take effect. If there is
15056 an equivalent property, prefer setting the property instead.
15057 There shouldn't be any reason to access options/<name> instead
15059 of <name>, except in situations in which the properties have
15060 different behavior or conflicting semantics.
15061 file-local-options/<name> (RW)
15063 Similar to options/<name>, but when setting an option through
15064 this property, the option is reset to its old value once the
15065 current file has stopped playing. Trying to write an option
15066 while no file is playing (or is being loaded) results in an er‐
15067 ror.
15068 (Note that if an option is marked as file-local, even options/
15070 will access the local value, and the old value, which will be
15071 restored on end of playback, cannot be read or written until end
15072 of playback.)
15073 option-info/<name>
15075 Additional per-option information.
15076 This has a number of sub-properties. Replace <name> with the
15078 name of a top-level option. No guarantee of stability is given
15079 to any of these sub-properties - they may change radically in
15080 the feature.
15081 option-info/<name>/name
15083 The name of the option.
15084 option-info/<name>/type
15086 The name of the option type, like String or Integer. For
15087 many complex types, this isn't very accurate.
15088 option-info/<name>/set-from-commandline
15090 Whether the option was set from the mpv command line.
15091 What this is set to if the option is e.g. changed at run‐
15092 time is left undefined (meaning it could change in the
15093 future).
15094 option-info/<name>/set-locally
15096 Whether the option was set per-file. This is the case
15097 with automatically loaded profiles, file-dir configs, and
15098 other cases. It means the option value will be restored
15099 to the value before playback start when playback ends.
15100 option-info/<name>/default-value
15102 The default value of the option. May not always be avail‐
15103 able.
15104 option-info/<name>/min, option-info/<name>/max
15106 Integer minimum and maximum values allowed for the op‐
15107 tion. Only available if the options are numeric, and the
15108 minimum/maximum has been set internally. It's also possi‐
15109 ble that only one of these is set.
15110 option-info/<name>/choices
15112 If the option is a choice option, the possible choices.
15113 Choices that are integers may or may not be included
15114 (they can be implied by min and max). Note that options
15115 which behave like choice options, but are not actual
15116 choice options internally, may not have this info avail‐
15117 able.
15118 property-list
15120 The list of top-level properties.
15121 profile-list
15123 The list of profiles and their contents. This is highly imple‐
15124 mentation-specific, and may change any time. Currently, it re‐
15125 turns an array of options for each profile. Each option has a
15126 name and a value, with the value currently always being a
15127 string. Note that the options array is not a map, as order mat‐
15128 ters and duplicate entries are possible. Recursive profiles are
15129 not expanded, and show up as special profile options.
15130 The profile-restore field is currently missing if it holds the
15132 default value (either because it was not set, or set explicitly
15133 to default), but in the future it might hold the value default.
15134 command-list
15136 The list of input commands. This returns an array of maps, where
15137 each map node represents a command. This map currently only has
15138 a single entry: name for the name of the command. (This property
15139 is supposed to be a replacement for --input-cmdlist. The option
15140 dumps some more information, but it's a valid feature request to
15141 extend this property if needed.)
15142 input-bindings
15144 The list of current input key bindings. This returns an array of
15145 maps, where each map node represents a binding for a single
15146 key/command. This map has the following entries:
15147 key The key name. This is normalized and may look slightly
15149 different from how it was specified in the source (e.g.
15150 in input.conf).
15151 cmd The command mapped to the key. (Currently, this is ex‐
15153 actly the same string as specified in the source, other
15154 than stripping whitespace and comments. It's possible
15155 that it will be normalized in the future.)
15156 is_weak
15158 If set to true, any existing and active user bindings
15159 will take priority.
15160 owner If this entry exists, the name of the script (or similar)
15162 which added this binding.
15163 section
15165 Name of the section this binding is part of. This is a
15166 rarely used mechanism. This entry may be removed or
15167 change meaning in the future.
15168 priority
15170 A number. Bindings with a higher value are preferred over
15171 bindings with a lower value. If the value is negative,
15172 this binding is inactive and will not be triggered by in‐
15173 put. Note that mpv does not use this value internally,
15174 and matching of bindings may work slightly differently in
15175 some cases. In addition, this value is dynamic and can
15176 change around at runtime.
15177 comment
15179 If available, the comment following the command on the
15180 same line. (For example, the input.conf entry f cycle bla
15181 # toggle bla would result in an entry with comment =
15182 "toggle bla", cmd = "cycle bla".)
15183 This property is read-only, and change notification is not sup‐
15185 ported. Currently, there is no mechanism to change key bindings
15186 at runtime, other than scripts adding or removing their own
15187 bindings.
15188 Inconsistencies between options and properties
15190 You can access (almost) all options as properties, though there are
15191 some caveats with some properties (due to historical reasons):
15192 vid, aid, sid
15194 While playback is active, these return the actually active
15195 tracks. For example, if you set aid=5, and the currently played
15196 file contains no audio track with ID 5, the aid property will
15197 return no.
15198 Before mpv 0.31.0, you could set existing tracks at runtime
15200 only.
15201 display-fps
15203 This inconsistent behavior is deprecated. Post-deprecation, the
15204 reported value and the option value are cleanly separated (over‐
15205 ride-display-fps for the option value).
15206 vf, af If you set the properties during playback, and the filter chain
15208 fails to reinitialize, the option will be set, but the runtime
15209 filter chain does not change. On the other hand, the next video
15210 to be played will fail, because the initial filter chain cannot
15211 be created.
15212 This behavior changed in mpv 0.31.0. Before this, the new value
15214 was rejected iff a video (for vf) or an audio (for af) track was
15215 active. If playback was not active, the behavior was the same as
15216 the current one.
15217 playlist
15219 The property is read-only and returns the current internal
15220 playlist. The option is for loading playlist during command line
15221 parsing. For client API uses, you should use the loadlist com‐
15222 mand instead.
15223 profile, include
15225 These are write-only, and will perform actions as they are writ‐
15226 ten to, exactly as if they were used on the mpv CLI commandline.
15227 Their only use is when using libmpv before mpv_initialize(),
15228 which in turn is probably only useful in encoding mode. Normal
15229 libmpv users should use other mechanisms, such as the apply-pro‐
15230 file command, and the mpv_load_config_file API function. Avoid
15231 these properties.
15232 Property Expansion
15234 All string arguments to input commands as well as certain options (like
15235 --term-playing-msg) are subject to property expansion. Note that prop‐
15236 erty expansion does not work in places where e.g. numeric parameters
15237 are expected. (For example, the add command does not do property ex‐
15238 pansion. The set command is an exception and not a general rule.)
15239 Example for input.conf
15241 i show-text "Filename: ${filename}"
15243 shows the filename of the current file when pressing the i
15244 key
15245 Whether property expansion is enabled by default depends on which API
15247 is used (see Flat command syntax, Commands specified as arrays and
15248 Named arguments), but it can always be enabled with the expand-proper‐
15249 ties prefix or disabled with the raw prefix, as described in Input Com‐
15250 mand Prefixes.
15251 The following expansions are supported:
15253 ${NAME}
15255 Expands to the value of the property NAME. If retrieving the
15256 property fails, expand to an error string. (Use ${NAME:} with a
15257 trailing : to expand to an empty string instead.) If NAME is
15258 prefixed with =, expand to the raw value of the property (see
15259 section below).
15260 ${NAME:STR}
15262 Expands to the value of the property NAME, or STR if the prop‐
15263 erty cannot be retrieved. STR is expanded recursively.
15264 ${?NAME:STR}
15266 Expands to STR (recursively) if the property NAME is available.
15267 ${!NAME:STR}
15269 Expands to STR (recursively) if the property NAME cannot be re‐
15270 trieved.
15271 ${?NAME==VALUE:STR}
15273 Expands to STR (recursively) if the property NAME expands to a
15274 string equal to VALUE. You can prefix NAME with = in order to
15275 compare the raw value of a property (see section below). If the
15276 property is unavailable, or other errors happen when retrieving
15277 it, the value is never considered equal. Note that VALUE can't
15278 contain any of the characters : or }. Also, it is possible that
15279 escaping with " or % might be added in the future, should the
15280 need arise.
15281 ${!NAME==VALUE:STR}
15283 Same as with the ? variant, but STR is expanded if the value is
15284 not equal. (Using the same semantics as with ?.)
15285 $$ Expands to $.
15287 $} Expands to }. (To produce this character inside recursive expan‐
15289 sion.)
15290 $> Disable property expansion and special handling of $ for the
15292 rest of the string.
15293 In places where property expansion is allowed, C-style escapes are of‐
15295 ten accepted as well. Example:
15296 • \n becomes a newline character
15298 • \\ expands to \
15300 Raw and Formatted Properties
15302 Normally, properties are formatted as human-readable text, meant to be
15303 displayed on OSD or on the terminal. It is possible to retrieve an un‐
15304 formatted (raw) value from a property by prefixing its name with =.
15305 These raw values can be parsed by other programs and follow the same
15306 conventions as the options associated with the properties.
15307 Examples
15309 • ${time-pos} expands to 00:14:23 (if playback position is at 14
15311 minutes 23 seconds)
15312 • ${=time-pos} expands to 863.4 (same time, plus 400 milliseconds -
15314 milliseconds are normally not shown in the formatted case)
15315 Sometimes, the difference in amount of information carried by raw and
15317 formatted property values can be rather big. In some cases, raw values
15318 have more information, like higher precision than seconds with
15319 time-pos. Sometimes it is the other way around, e.g. aid shows track
15320 title and language in the formatted case, but only the track number if
15321 it is raw.
15322
15324 The On Screen Controller (short: OSC) is a minimal GUI integrated with
15325 mpv to offer basic mouse-controllability. It is intended to make inter‐
15326 action easier for new users and to enable precise and direct seeking.
15327 The OSC is enabled by default if mpv was compiled with Lua support. It
15329 can be disabled entirely using the --osc=no option.
15330 Using the OSC
15332 By default, the OSC will show up whenever the mouse is moved inside the
15333 player window and will hide if the mouse is not moved outside the OSC
15334 for 0.5 seconds or if the mouse leaves the window.
15335 The Interface
15337 +---------+----------+------------------------------------------+----------+
15338 | pl prev | pl next | title | cache |
15339 +------+--+---+------+---------+-----------+------+-------+-----+-----+----+
15340 | play | skip | skip | time | seekbar | time | audio | sub | vol | fs |
15341 | | back | frwd | elapsed | | left | | | | |
15342 +------+------+------+---------+-----------+------+-------+-----+-----+----+
15343 pl prev
15345 ┌──────────────┬────────────────────────────┐
15347 │left-click │ play previous file in │
15348 │ │ playlist │
15349 ├──────────────┼────────────────────────────┤
15350 │right-click │ show playlist │
15351 ├──────────────┼────────────────────────────┤
15352 │shift+L-click │ show playlist │
15353 └──────────────┴────────────────────────────┘
15354 pl next
15356 ┌──────────────┬────────────────────────────┐
15358 │left-click │ play next file in playlist │
15359 ├──────────────┼────────────────────────────┤
15360 │right-click │ show playlist │
15361 ├──────────────┼────────────────────────────┤
15362 │shift+L-click │ show playlist │
15363 └──────────────┴────────────────────────────┘
15364 title
15366 Displays current media-title, filename, custom title, or target chapter
15367 name while hovering the seekbar.
15368 ┌────────────┬────────────────────────────┐
15371 │left-click │ show playlist position and │
15372 │ │ length and full title │
15373 ├────────────┼────────────────────────────┤
15374 │right-click │ show filename │
15375 └────────────┴────────────────────────────┘
15376 cache
15378 Shows current cache fill status
15379 play
15382 ┌───────────┬───────────────────┐
15384 │left-click │ toggle play/pause │
15385 └───────────┴───────────────────┘
15386 skip back
15388 ┌──────────────┬────────────────────────────┐
15390 │left-click │ go to beginning of chapter │
15391 │ │ / previous chapter │
15392 ├──────────────┼────────────────────────────┤
15393 │right-click │ show chapters │
15394 ├──────────────┼────────────────────────────┤
15395 │shift+L-click │ show chapters │
15396 └──────────────┴────────────────────────────┘
15397 skip frwd
15399 ┌──────────────┬────────────────────┐
15401 │left-click │ go to next chapter │
15402 ├──────────────┼────────────────────┤
15403 │right-click │ show chapters │
15404 ├──────────────┼────────────────────┤
15405 │shift+L-click │ show chapters │
15406 └──────────────┴────────────────────┘
15407 time elapsed
15409 Shows current playback position timestamp
15410 ┌───────────┬────────────────────────────┐
15413 │left-click │ toggle displaying time‐ │
15414 │ │ codes with milliseconds │
15415 └───────────┴────────────────────────────┘
15416 seekbar
15418 Indicates current playback position and position of chapters
15419 ┌───────────┬──────────────────┐
15422 │left-click │ seek to position │
15423 └───────────┴──────────────────┘
15424 time left
15426 Shows remaining playback time timestamp
15427 ┌───────────┬────────────────────────────┐
15434 │left-click │ toggle between total and │
15435 │ │ remaining time │
15436 └───────────┴────────────────────────────┘
15437 audio and sub
15439 Displays selected track and amount of available tracks
15440 ┌──────────────┬────────────────────────────┐
15443 │left-click │ cycle audio/sub tracks │
15444 │ │ forward │
15445 ├──────────────┼────────────────────────────┤
15446 │right-click │ cycle audio/sub tracks │
15447 │ │ backwards │
15448 ├──────────────┼────────────────────────────┤
15449 │shift+L-click │ show available audio/sub │
15450 │ │ tracks │
15451 └──────────────┴────────────────────────────┘
15452 vol
15454 ┌────────────┬────────────────┐
15456 │left-click │ toggle mute │
15457 ├────────────┼────────────────┤
15458 │mouse wheel │ volume up/down │
15459 └────────────┴────────────────┘
15460 fs
15462 ┌───────────┬───────────────────┐
15464 │left-click │ toggle fullscreen │
15465 └───────────┴───────────────────┘
15466 Key Bindings
15468 These key bindings are active by default if nothing else is already
15469 bound to these keys. In case of collision, the function needs to be
15470 bound to a different key. See the Script Commands section.
15471 ┌────┬────────────────────────────┐
15473 │del │ Cycles visibility between │
15474 │ │ never / auto (mouse-move) │
15475 │ │ / always │
15476 └────┴────────────────────────────┘
15477 Configuration
15479 The OSC offers limited configuration through a config file
15480 script-opts/osc.conf placed in mpv's user dir and through the
15481 --script-opts command-line option. Options provided through the com‐
15482 mand-line will override those from the config file.
15483 Config Syntax
15485 The config file must exactly follow the following syntax:
15486 # this is a comment
15488 optionA=value1
15489 optionB=value2
15490 # can only be used at the beginning of a line and there may be no spa‐
15492 ces around the = or anywhere else.
15493 Command-line Syntax
15495 To avoid collisions with other scripts, all options need to be prefixed
15496 with osc-.
15497 Example:
15499 --script-opts=osc-optionA=value1,osc-optionB=value2
15501 Configurable Options
15503 layout Default: bottombar
15504 The layout for the OSC. Currently available are: box, slimbox,
15506 bottombar and topbar. Default pre-0.21.0 was 'box'.
15507 seekbarstyle
15509 Default: bar
15510 Sets the style of the playback position marker and overall shape
15512 of the seekbar: bar, diamond or knob.
15513 seekbarhandlesize
15515 Default: 0.6
15516 Size ratio of the seek handle if seekbarstyle is set to dimaond
15518 or knob. This is relative to the full height of the seekbar.
15519 seekbarkeyframes
15521 Default: yes
15522 Controls the mode used to seek when dragging the seekbar. If set
15524 to yes, default seeking mode is used (usually keyframes, but
15525 player defaults and heuristics can change it to exact). If set
15526 to no, exact seeking on mouse drags will be used instead.
15527 Keyframes are preferred, but exact seeks may be useful in cases
15528 where keyframes cannot be found. Note that using exact seeks can
15529 potentially make mouse dragging much slower.
15530 seekrangestyle
15532 Default: inverted
15533 Display seekable ranges on the seekbar. bar shows them on the
15535 full height of the bar, line as a thick line and inverted as a
15536 thin line that is inverted over playback position markers. none
15537 will hide them. Additionally, slider will show a permanent han‐
15538 dle inside the seekbar with cached ranges marked inside. Note
15539 that these will look differently based on the seekbarstyle op‐
15540 tion. Also, slider does not work with seekbarstyle set to bar.
15541 seekrangeseparate
15543 Default: yes
15544 Controls whether to show line-style seekable ranges on top of
15546 the seekbar or separately if seekbarstyle is set to bar.
15547 seekrangealpha
15549 Default: 200
15550 Alpha of the seekable ranges, 0 (opaque) to 255 (fully transpar‐
15552 ent).
15553 deadzonesize
15555 Default: 0.5
15556 Size of the deadzone. The deadzone is an area that makes the
15558 mouse act like leaving the window. Movement there won't make the
15559 OSC show up and it will hide immediately if the mouse enters it.
15560 The deadzone starts at the window border opposite to the OSC and
15561 the size controls how much of the window it will span. Values
15562 between 0.0 and 1.0, where 0 means the OSC will always popup
15563 with mouse movement in the window, and 1 means the OSC will only
15564 show up when the mouse hovers it. Default pre-0.21.0 was 0.
15565 minmousemove
15567 Default: 0
15568 Minimum amount of pixels the mouse has to move between ticks to
15570 make the OSC show up. Default pre-0.21.0 was 3.
15571 showwindowed
15573 Default: yes
15574 Enable the OSC when windowed
15576 showfullscreen
15578 Default: yes
15579 Enable the OSC when fullscreen
15581 idlescreen
15583 Default: yes
15584 Show the mpv logo and message when idle
15586 scalewindowed
15588 Default: 1.0
15589 Scale factor of the OSC when windowed.
15591 scalefullscreen
15593 Default: 1.0
15594 Scale factor of the OSC when fullscreen
15596 scaleforcedwindow
15598 Default: 2.0
15599 Scale factor of the OSC when rendered on a forced (dummy) window
15601 vidscale
15603 Default: yes
15604 Scale the OSC with the video no tries to keep the OSC size con‐
15606 stant as much as the window size allows
15607 valign Default: 0.8
15609 Vertical alignment, -1 (top) to 1 (bottom)
15611 halign Default: 0.0
15613 Horizontal alignment, -1 (left) to 1 (right)
15615 barmargin
15617 Default: 0
15618 Margin from bottom (bottombar) or top (topbar), in pixels
15620 boxalpha
15622 Default: 80
15623 Alpha of the background box, 0 (opaque) to 255 (fully transpar‐
15625 ent)
15626 hidetimeout
15628 Default: 500
15629 Duration in ms until the OSC hides if no mouse movement, must
15631 not be negative
15632 fadeduration
15634 Default: 200
15635 Duration of fade out in ms, 0 = no fade
15637 title Default: ${media-title}
15639 String that supports property expansion that will be displayed
15641 as OSC title. ASS tags are escaped, and newlines and trailing
15642 slashes are stripped.
15643 tooltipborder
15645 Default: 1
15646 Size of the tooltip outline when using bottombar or topbar lay‐
15648 outs
15649 timetotal
15651 Default: no
15652 Show total time instead of time remaining
15654 timems Default: no
15656 Display timecodes with milliseconds
15658 tcspace
15660 Default: 100 (allowed: 50-200)
15661 Adjust space reserved for timecodes (current time and time re‐
15663 maining) in the bottombar and topbar layouts. The timecode width
15664 depends on the font, and with some fonts the spacing near the
15665 timecodes becomes too small. Use values above 100 to increase
15666 that spacing, or below 100 to decrease it.
15667 visibility
15669 Default: auto (auto hide/show on mouse move)
15670 Also supports never and always
15672 boxmaxchars
15674 Default: 80
15675 Max chars for the osc title at the box layout. mpv does not mea‐
15677 sure the text width on screen and so it needs to limit it by
15678 number of chars. The default is conservative to allow wide fonts
15679 to be used without overflow. However, with many common fonts a
15680 bigger number can be used. YMMV.
15681 boxvideo
15683 Default: no
15684 Whether to overlay the osc over the video (no), or to box the
15686 video within the areas not covered by the osc (yes). If this op‐
15687 tion is set, the osc may overwrite the --video-margin-ratio-*
15688 options, even if the user has set them. (It will not overwrite
15689 them if all of them are set to default values.) Additionally,
15690 visibility must be set to always. Otherwise, this option does
15691 nothing.
15692 Currently, this is supported for the bottombar and topbar layout
15694 only. The other layouts do not change if this option is set.
15695 Separately, if window controls are present (see below), they
15696 will be affected regardless of which osc layout is in use.
15697 The border is static and appears even if the OSC is configured
15699 to appear only on mouse interaction. If the OSC is invisible,
15700 the border is simply filled with the background color (black by
15701 default).
15702 This currently still makes the OSC overlap with subtitles (if
15704 the --sub-use-margins option is set to yes, the default). This
15705 may be fixed later.
15706 This does not work correctly with video outputs like --vo=xv,
15708 which render OSD into the unscaled video.
15709 windowcontrols
15711 Default: auto (Show window controls if there is no window bor‐
15712 der)
15713 Whether to show window management controls over the video, and
15715 if so, which side of the window to place them. This may be de‐
15716 sirable when the window has no decorations, either because they
15717 have been explicitly disabled (border=no) or because the current
15718 platform doesn't support them (eg: gnome-shell with wayland).
15719 The set of window controls is fixed, offering minimize, maxi‐
15721 mize, and quit. Not all platforms implement minimize and maxi‐
15722 mize, but quit will always work.
15723 windowcontrols_alignment
15725 Default: right
15726 If window controls are shown, indicates which side should they
15728 be aligned to.
15729 Supports left and right which will place the controls on those
15731 respective sides.
15732 greenandgrumpy
15734 Default: no
15735 Set to yes to reduce festivity (i.e. disable santa hat in Decem‐
15737 ber.)
15738 livemarkers
15740 Default: yes
15741 Update chapter markers positions on duration changes, e.g. live
15743 streams. The updates are unoptimized - consider disabling it on
15744 very low-end systems.
15745 chapters_osd, playlist_osd
15747 Default: yes
15748 Whether to display the chapters/playlist at the OSD when
15750 left-clicking the next/previous OSC buttons, respectively.
15751 chapter_fmt
15753 Default: Chapter: %s
15754 Template for the chapter-name display when hovering the seekbar.
15756 Use no to disable chapter display on hover. Otherwise it's a lua
15757 string.format template and %s is replaced with the actual name.
15758 unicodeminus
15760 Default: no
15761 Use a Unicode minus sign instead of an ASCII hyphen when dis‐
15763 playing the remaining playback time.
15764 Script Commands
15766 The OSC script listens to certain script commands. These commands can
15767 bound in input.conf, or sent by other scripts.
15768 osc-message
15770 Show a message on screen using the OSC. First argument is the
15771 message, second the duration in seconds.
15772 osc-visibility
15774 Controls visibility mode never / auto (on mouse move) / always
15775 and also cycle to cycle between the modes
15776 Example
15778 You could put this into input.conf to hide the OSC with the a key and
15780 to set auto mode (the default) with b:
15781 a script-message osc-visibility never
15783 b script-message osc-visibility auto
15784 osc-idlescreen
15786 Controls the visibility of the mpv logo on idle. Valid arguments
15787 are yes, no, and cycle to toggle between yes and no.
15788 osc-playlist, osc-chapterlist, osc-tracklist
15790 Shows a limited view of the respective type of list using the
15791 OSC. First argument is duration in seconds.
15792
15794 This builtin script displays information and statistics for the cur‐
15795 rently played file. It is enabled by default if mpv was compiled with
15796 Lua support. It can be disabled entirely using the --load-stats-over‐
15797 lay=no option.
15798 Usage
15800 The following key bindings are active by default unless something else
15801 is already bound to them:
15802 ┌──┬────────────────────────────┐
15804 │i │ Show stats for a fixed du‐ │
15805 │ │ ration │
15806 ├──┼────────────────────────────┤
15807 │I │ Toggle stats (shown until │
15808 │ │ toggled again) │
15809 └──┴────────────────────────────┘
15810 While the stats are visible on screen the following key bindings are
15812 active, regardless of existing bindings. They allow you to switch be‐
15813 tween pages of stats:
15814 ┌──┬────────────────────────────┐
15816 │1 │ Show usual stats │
15817 ├──┼────────────────────────────┤
15818 │2 │ Show frame timings │
15819 │ │ (scroll) │
15820 ├──┼────────────────────────────┤
15821 │3 │ Input cache stats │
15822 ├──┼────────────────────────────┤
15823 │4 │ Active key bindings │
15824 │ │ (scroll) │
15825 ├──┼────────────────────────────┤
15826 │0 │ Internal stuff (scroll) │
15827 └──┴────────────────────────────┘
15828 On pages which support scroll, these key bindings are also active:
15830 ┌─────┬──────────────────────┐
15832 │UP │ Scroll one line up │
15833 ├─────┼──────────────────────┤
15834 │DOWN │ Scroll one line down │
15835 └─────┴──────────────────────┘
15836 Font
15838 For optimal visual experience, a font with support for many font
15839 weights and monospaced digits is recommended. By default, the open
15840 source font Source Sans Pro is used.
15841 Configuration
15843 This script can be customized through a config file
15844 script-opts/stats.conf placed in mpv's user directory and through the
15845 --script-opts command-line option. The configuration syntax is de‐
15846 scribed in ON SCREEN CONTROLLER.
15847 Configurable Options
15849 key_page_1
15850 Default: 1
15851 key_page_2
15853 Default: 2
15854 key_page_3
15856 Default: 3
15857 key_page_4
15859 Default: 4
15860 key_page_0
15862 Default: 0
15863 Key bindings for page switching while stats are displayed.
15865 key_scroll_up
15867 Default: UP
15868 key_scroll_down
15870 Default: DOWN
15871 scroll_lines
15873 Default: 1
15874 Scroll key bindings and number of lines to scroll on pages which
15876 support it.
15877 duration
15879 Default: 4
15880 How long the stats are shown in seconds (oneshot).
15882 redraw_delay
15884 Default: 1
15885 How long it takes to refresh the displayed stats in seconds
15887 (toggling).
15888 persistent_overlay
15890 Default: no
15891 When no, other scripts printing text to the screen can overwrite
15893 the displayed stats. When yes, displayed stats are persistently
15894 shown for the respective duration. This can result in overlap‐
15895 ping text when multiple scripts decide to print text at the same
15896 time.
15897 plot_perfdata
15899 Default: yes
15900 Show graphs for performance data (page 2).
15902 plot_vsync_ratio
15904 Default: yes
15905 plot_vsync_jitter
15907 Default: yes
15908 Show graphs for vsync and jitter values (page 1). Only when tog‐
15910 gled.
15911 flush_graph_data
15913 Default: yes
15914 Clear data buffers used for drawing graphs when toggling.
15916 font Default: Source Sans Pro
15918 Font name. Should support as many font weights as possible for
15920 optimal visual experience.
15921 font_mono
15923 Default: Source Sans Pro
15924 Font name for parts where monospaced characters are necessary to
15926 align text. Currently, monospaced digits are sufficient.
15927 font_size
15929 Default: 8
15930 Font size used to render text.
15932 font_color
15934 Default: FFFFFF
15935 Font color.
15937 border_size
15939 Default: 0.8
15940 Size of border drawn around the font.
15942 border_color
15944 Default: 262626
15945 Color of drawn border.
15947 alpha Default: 11
15949 Transparency for drawn text.
15951 plot_bg_border_color
15953 Default: 0000FF
15954 Border color used for drawing graphs.
15956 plot_bg_color
15958 Default: 262626
15959 Background color used for drawing graphs.
15961 plot_color
15963 Default: FFFFFF
15964 Color used for drawing graphs.
15966 Note: colors are given as hexadecimal values and use ASS tag order:
15968 BBGGRR (blue green red).
15969 Different key bindings
15971 Additional keys can be configured in input.conf to display the stats:
15972 e script-binding stats/display-stats
15974 E script-binding stats/display-stats-toggle
15975 And to display a certain page directly:
15977 i script-binding stats/display-page-1
15979 e script-binding stats/display-page-2
15980 Active key bindings page
15982 Lists the active key bindings and the commands they're bound to, ex‐
15983 cluding the interactive keys of the stats script itself. See also --in‐
15984 put-test for more detailed view of each binding.
15985 The keys are grouped automatically using a simple analysis of the com‐
15987 mand string, and one should not expect documentation-level grouping ac‐
15988 curacy, however, it should still be reasonably useful.
15989 Using --idle --script-opts=stats-bindlist=yes will print the list to
15991 the terminal and quit immediately. By default long lines are shortened
15992 to 79 chars, and terminal escape sequences are enabled. A different
15993 length limit can be set by changing yes to a number (at least 40), and
15994 escape sequences can be disabled by adding - before the value, e.g.
15995 ...=-yes or ...=-120.
15996 Like with --input-test, the list includes bindings from input.conf and
15998 from user scripts. Use --no-config to list only built-in bindings.
15999 Internal stuff page
16001 Most entries shown on this page have rather vague meaning. Likely none
16002 of this is useful for you. Don't attempt to use it. Forget its exis‐
16003 tence.
16004 Selecting this for the first time will start collecting some internal
16006 performance data. That means performance will be slightly lower than
16007 normal for the rest of the time the player is running (even if the
16008 stats page is closed). Note that the stats page itself uses a lot of
16009 CPU and even GPU resources, and may have a heavy impact on performance.
16010 The displayed information is accumulated over the redraw delay (shown
16012 as poll-time field).
16013 This adds entries for each Lua script. If there are too many scripts
16015 running, parts of the list will simply be out of the screen, but it can
16016 be scrolled.
16017 If the underlying platform does not support pthread per thread times,
16019 the displayed times will be 0 or something random (I suspect that at
16020 time of this writing, only Linux provides the correct via pthread APIs
16021 for per thread times).
16022 Most entries are added lazily and only during data collection, which is
16024 why entries may pop up randomly after some time. It's also why the mem‐
16025 ory usage entries for scripts that have been inactive since the start
16026 of data collection are missing.
16027 Memory usage is approximate and does not reflect internal fragmenta‐
16029 tion.
16030 JS scripts memory reporting is disabled by default because collecting
16032 the data at the JS side has an overhead. It can be enabled by exporting
16033 the env var MPV_LEAK_REPORT=1 before starting mpv, and will increase JS
16034 memory usage.
16035 If entries have /time and /cpu variants, the former gives the real time
16037 (monotonic clock), while the latter the thread CPU time (only if the
16038 corresponding pthread API works and is supported).
16039
16041 The console is a REPL for mpv input commands. It is displayed on the
16042 video window. It also shows log messages. It can be disabled entirely
16043 using the --load-osd-console=no option.
16044 Keybindings
16046 ` Show the console.
16047 ESC Hide the console.
16049 ENTER, Ctrl+J and Ctrl+M
16051 Run the typed command.
16052 Shift+ENTER
16054 Type a literal newline character.
16055 LEFT and Ctrl+B
16057 Move the cursor to the previous character.
16058 RIGHT and Ctrl+F
16060 Move the cursor to the next character.
16061 Ctrl+LEFT and Alt+B
16063 Move the cursor to the beginning of the current word, or if be‐
16064 tween words, to the beginning of the previous word.
16065 Ctrl+RIGHT and Alt+F
16067 Move the cursor to the end of the current word, or if between
16068 words, to the end of the next word.
16069 HOME and Ctrl+A
16071 Move the cursor to the start of the current line.
16072 END and Ctrl+E
16074 Move the cursor to the end of the current line.
16075 BACKSPACE and Ctrl+H
16077 Delete the previous character.
16078 Ctrl+D Hide the console if the current line is empty, otherwise delete
16080 the next character.
16081 Ctrl+BACKSPACE and Ctrl+W
16083 Delete text from the cursor to the beginning of the current
16084 word, or if between words, to the beginning of the previous
16085 word.
16086 Ctrl+DEL and Alt+D
16088 Delete text from the cursor to the end of the current word, or
16089 if between words, to the end of the next word.
16090 Ctrl+U Delete text from the cursor to the beginning of the current
16092 line.
16093 Ctrl+K Delete text from the cursor to the end of the current line.
16095 Ctrl+C Clear the current line.
16097 UP and Ctrl+P
16099 Move back in the command history.
16100 DOWN and Ctrl+N
16102 Move forward in the command history.
16103 PGUP Go to the first command in the history.
16105 PGDN Stop navigating the command history.
16107 INSERT Toggle insert mode.
16109 Ctrl+V Paste text (uses the clipboard on X11 and Wayland).
16111 Shift+INSERT
16113 Paste text (uses the primary selection on X11 and Wayland).
16114 TAB and Ctrl+I
16116 Complete the command or property name at the cursor.
16117 Ctrl+L Clear all log messages from the console.
16119 Commands
16121 script-message-to console type <text> [<cursor_pos>]
16122 Show the console and pre-fill it with the provided text, option‐
16123 ally specifying the initial cursor position as a positive inte‐
16124 ger starting from 1.
16125 Example for input.conf
16127 % script-message-to console type "seek absolute-per‐
16129 cent" 6
16130 Known issues
16132 • Pasting text is slow on Windows
16133 • Non-ASCII keyboard input has restrictions
16135 • The cursor keys move between Unicode code-points, not grapheme clus‐
16137 ters
16138 Configuration
16140 This script can be customized through a config file script-opts/con‐
16141 sole.conf placed in mpv's user directory and through the --script-opts
16142 command-line option. The configuration syntax is described in ON SCREEN
16143 CONTROLLER.
16144 Key bindings can be changed in a standard way, see for example
16146 stats.lua documentation.
16147 Configurable Options
16149 scale Default: 1
16150 All drawing is scaled by this value, including the text borders
16152 and the cursor.
16153 If the VO backend in use has HiDPI scale reporting implemented,
16155 the option value is scaled with the reported HiDPI scale.
16156 font Default: unset (picks a hardcoded font depending on detected
16158 platform)
16159 Set the font used for the REPL and the console. This probably
16161 doesn't have to be a monospaced font.
16162 font_size
16164 Default: 16
16165 Set the font size used for the REPL and the console. This will
16167 be multiplied by "scale".
16168 history_dedup
16170 Default: true
16171 Remove duplicate entries in history as to only keep the latest
16173 one.
16174
16176 mpv can load Lua scripts. (See Script location.)
16177 mpv provides the built-in module mp, which contains functions to send
16179 commands to the mpv core and to retrieve information about playback
16180 state, user settings, file information, and so on.
16181 These scripts can be used to control mpv in a similar way to slave
16183 mode. Technically, the Lua code uses the client API internally.
16184 Example
16186 A script which leaves fullscreen mode when the player is paused:
16187 function on_pause_change(name, value)
16189 if value == true then
16190 mp.set_property("fullscreen", "no")
16191 end
16192 end
16193 mp.observe_property("pause", "bool", on_pause_change)
16194 Script location
16196 Scripts can be passed to the --script option, and are automatically
16197 loaded from the scripts subdirectory of the mpv configuration directory
16198 (usually ~/.config/mpv/scripts/).
16199 A script can be a single file. The file extension is used to select the
16201 scripting backend to use for it. For Lua, it is .lua. If the extension
16202 is not recognized, an error is printed. (If an error happens, the ex‐
16203 tension is either mistyped, or the backend was not compiled into your
16204 mpv binary.)
16205 mpv internally loads the script's name by stripping the .lua extension
16207 and replacing all nonalphanumeric characters with _. E.g., my-tools.lua
16208 becomes my_tools. If there are several scripts with the same name, it
16209 is made unique by appending a number. This is the name returned by
16210 mp.get_script_name().
16211 Entries with .disable extension are always ignored.
16213 If a script is a directory (either if a directory is passed to
16215 --script, or any sub-directories in the script directory, such as for
16216 example ~/.config/mpv/scripts/something/), then the directory repre‐
16217 sents a single script. The player will try to load a file named main.x,
16218 where x is replaced with the file extension. For example, if main.lua
16219 exists, it is loaded with the Lua scripting backend.
16220 You must not put any other files or directories that start with main.
16222 into the script's top level directory. If the script directory contains
16223 for example both main.lua and main.js, only one of them will be loaded
16224 (and which one depends on mpv internals that may change any time).
16225 Likewise, if there is for example main.foo, your script will break as
16226 soon as mpv adds a backend that uses the .foo file extension.
16227 mpv also appends the top level directory of the script to the start of
16229 Lua's package path so you can import scripts from there too. Be aware
16230 that this will shadow Lua libraries that use the same package path.
16231 (Single file scripts do not include mpv specific directory the Lua
16232 package path. This was silently changed in mpv 0.32.0.)
16233 Using a script directory is the recommended way to package a script
16235 that consists of multiple source files, or requires other files (you
16236 can use mp.get_script_directory() to get the location and e.g. load
16237 data files).
16238 Making a script a git repository, basically a repository which contains
16240 a main.lua` file in the root directory, makes scripts easily updateable
16241 (without the dangers of auto-updates). Another suggestion is to use git
16242 submodules to share common files or libraries.
16243 Details on the script initialization and lifecycle
16245 Your script will be loaded by the player at program start from the
16246 scripts configuration subdirectory, or from a path specified with the
16247 --script option. Some scripts are loaded internally (like --osc). Each
16248 script runs in its own thread. Your script is first run "as is", and
16249 once that is done, the event loop is entered. This event loop will dis‐
16250 patch events received by mpv and call your own event handlers which you
16251 have registered with mp.register_event, or timers added with
16252 mp.add_timeout or similar. Note that since the script starts execution
16253 concurrently with player initialization, some properties may not be
16254 populated with meaningful values until the relevant subsystems have
16255 initialized.
16256 When the player quits, all scripts will be asked to terminate. This
16258 happens via a shutdown event, which by default will make the event loop
16259 return. If your script got into an endless loop, mpv will probably be‐
16260 have fine during playback, but it won't terminate when quitting, be‐
16261 cause it's waiting on your script.
16262 Internally, the C code will call the Lua function mp_event_loop after
16264 loading a Lua script. This function is normally defined by the default
16265 prelude loaded before your script (see player/lua/defaults.lua in the
16266 mpv sources). The event loop will wait for events and dispatch events
16267 registered with mp.register_event. It will also handle timers added
16268 with mp.add_timeout and similar (by waiting with a timeout).
16269 Since mpv 0.6.0, the player will wait until the script is fully loaded
16271 before continuing normal operation. The player considers a script as
16272 fully loaded as soon as it starts waiting for mpv events (or it exits).
16273 In practice this means the player will more or less hang until the
16274 script returns from the main chunk (and mp_event_loop is called), or
16275 the script calls mp_event_loop or mp.dispatch_events directly. This is
16276 done to make it possible for a script to fully setup event handlers
16277 etc. before playback actually starts. In older mpv versions, this hap‐
16278 pened asynchronously. With mpv 0.29.0, this changes slightly, and it
16279 merely waits for scripts to be loaded in this manner before starting
16280 playback as part of the player initialization phase. Scripts run though
16281 initialization in parallel. This might change again.
16282 mp functions
16284 The mp module is preloaded, although it can be loaded manually with re‐
16285 quire 'mp'. It provides the core client API.
16286 mp.command(string)
16288 Run the given command. This is similar to the commands used in
16289 input.conf. See List of Input Commands.
16290 By default, this will show something on the OSD (depending on
16292 the command), as if it was used in input.conf. See Input Command
16293 Prefixes how to influence OSD usage per command.
16294 Returns true on success, or nil, error on error.
16296 mp.commandv(arg1, arg2, ...)
16298 Similar to mp.command, but pass each command argument as sepa‐
16299 rate parameter. This has the advantage that you don't have to
16300 care about quoting and escaping in some cases.
16301 Example:
16303 mp.command("loadfile " .. filename .. " append")
16305 mp.commandv("loadfile", filename, "append")
16306 These two commands are equivalent, except that the first version
16308 breaks if the filename contains spaces or certain special char‐
16309 acters.
16310 Note that properties are not expanded. You can use either
16312 mp.command, the expand-properties prefix, or the mp.get_property
16313 family of functions.
16314 Unlike mp.command, this will not use OSD by default either (ex‐
16316 cept for some OSD-specific commands).
16317 mp.command_native(table [,def])
16319 Similar to mp.commandv, but pass the argument list as table.
16320 This has the advantage that in at least some cases, arguments
16321 can be passed as native types. It also allows you to use named
16322 argument.
16323 If the table is an array, each array item is like an argument in
16325 mp.commandv() (but can be a native type instead of a string).
16326 If the table contains string keys, it's interpreted as command
16328 with named arguments. This requires at least an entry with the
16329 key name to be present, which must be a string, and contains the
16330 command name. The special entry _flags is optional, and if
16331 present, must be an array of Input Command Prefixes to apply.
16332 All other entries are interpreted as arguments.
16333 Returns a result table on success (usually empty), or def, error
16335 on error. def is the second parameter provided to the function,
16336 and is nil if it's missing.
16337 mp.command_native_async(table [,fn])
16339 Like mp.command_native(), but the command is ran asynchronously
16340 (as far as possible), and upon completion, fn is called. fn has
16341 three arguments: fn(success, result, error):
16342 success
16344 Always a Boolean and is true if the command was
16345 successful, otherwise false.
16346 result The result value (can be nil) in case of success, nil
16348 otherwise (as returned by mp.command_native()).
16349 error The error string in case of an error, nil otherwise.
16351 Returns a table with undefined contents, which can be used as
16353 argument for mp.abort_async_command.
16354 If starting the command failed for some reason, nil, error is
16356 returned, and fn is called indicating failure, using the same
16357 error value.
16358 fn is always called asynchronously, even if the command failed
16360 to start.
16361 mp.abort_async_command(t)
16363 Abort a mp.command_native_async call. The argument is the return
16364 value of that command (which starts asynchronous execution of
16365 the command). Whether this works and how long it takes depends
16366 on the command and the situation. The abort call itself is asyn‐
16367 chronous. Does not return anything.
16368 mp.get_property(name [,def])
16370 Return the value of the given property as string. These are the
16371 same properties as used in input.conf. See Properties for a list
16372 of properties. The returned string is formatted similar to
16373 ${=name} (see Property Expansion).
16374 Returns the string on success, or def, error on error. def is
16376 the second parameter provided to the function, and is nil if
16377 it's missing.
16378 mp.get_property_osd(name [,def])
16380 Similar to mp.get_property, but return the property value for‐
16381 matted for OSD. This is the same string as printed with ${name}
16382 when used in input.conf.
16383 Returns the string on success, or def, error on error. def is
16385 the second parameter provided to the function, and is an empty
16386 string if it's missing. Unlike get_property(), assigning the re‐
16387 turn value to a variable will always result in a string.
16388 mp.get_property_bool(name [,def])
16390 Similar to mp.get_property, but return the property value as
16391 Boolean.
16392 Returns a Boolean on success, or def, error on error.
16394 mp.get_property_number(name [,def])
16396 Similar to mp.get_property, but return the property value as
16397 number.
16398 Note that while Lua does not distinguish between integers and
16400 floats, mpv internals do. This function simply request a double
16401 float from mpv, and mpv will usually convert integer property
16402 values to float.
16403 Returns a number on success, or def, error on error.
16405 mp.get_property_native(name [,def])
16407 Similar to mp.get_property, but return the property value using
16408 the best Lua type for the property. Most time, this will return
16409 a string, Boolean, or number. Some properties (for example chap‐
16410 ter-list) are returned as tables.
16411 Returns a value on success, or def, error on error. Note that
16413 nil might be a possible, valid value too in some corner cases.
16414 mp.set_property(name, value)
16416 Set the given property to the given string value. See
16417 mp.get_property and Properties for more information about prop‐
16418 erties.
16419 Returns true on success, or nil, error on error.
16421 mp.set_property_bool(name, value)
16423 Similar to mp.set_property, but set the given property to the
16424 given Boolean value.
16425 mp.set_property_number(name, value)
16427 Similar to mp.set_property, but set the given property to the
16428 given numeric value.
16429 Note that while Lua does not distinguish between integers and
16431 floats, mpv internals do. This function will test whether the
16432 number can be represented as integer, and if so, it will pass an
16433 integer value to mpv, otherwise a double float.
16434 mp.set_property_native(name, value)
16436 Similar to mp.set_property, but set the given property using its
16437 native type.
16438 Since there are several data types which cannot represented na‐
16440 tively in Lua, this might not always work as expected. For exam‐
16441 ple, while the Lua wrapper can do some guesswork to decide
16442 whether a Lua table is an array or a map, this would fail with
16443 empty tables. Also, there are not many properties for which it
16444 makes sense to use this, instead of set_property, set_prop‐
16445 erty_bool, set_property_number. For these reasons, this func‐
16446 tion should probably be avoided for now, except for properties
16447 that use tables natively.
16448 mp.get_time()
16450 Return the current mpv internal time in seconds as a number.
16451 This is basically the system time, with an arbitrary offset.
16452 mp.add_key_binding(key, name|fn [,fn [,flags]])
16454 Register callback to be run on a key binding. The binding will
16455 be mapped to the given key, which is a string describing the
16456 physical key. This uses the same key names as in input.conf, and
16457 also allows combinations (e.g. ctrl+a). If the key is empty or
16458 nil, no physical key is registered, but the user still can cre‐
16459 ate own bindings (see below).
16460 After calling this function, key presses will cause the function
16462 fn to be called (unless the user remapped the key with another
16463 binding).
16464 The name argument should be a short symbolic string. It allows
16466 the user to remap the key binding via input.conf using the
16467 script-message command, and the name of the key binding (see be‐
16468 low for an example). The name should be unique across other
16469 bindings in the same script - if not, the previous binding with
16470 the same name will be overwritten. You can omit the name, in
16471 which case a random name is generated internally. (Omitting
16472 works as follows: either pass nil for name, or pass the fn argu‐
16473 ment in place of the name. The latter is not recommended and is
16474 handled for compatibility only.)
16475 The last argument is used for optional flags. This is a table,
16477 which can have the following entries:
16478 repeatable
16480 If set to true, enables key repeat for this specific
16481 binding.
16482 complex
16484 If set to true, then fn is called on both key up and
16485 down events (as well as key repeat, if enabled), with
16486 the first argument being a table. This table has the
16487 following entries (and may contain undocumented ones):
16488 event Set to one of the strings down, repeat, up
16490 or press (the latter if key up/down can't
16491 be tracked).
16492 is_mouse
16494 Boolean Whether the event was caused by a
16495 mouse button.
16496 key_name
16498 The name of they key that triggered this,
16499 or nil if invoked artificially. If the key
16500 name is unknown, it's an empty string.
16501 key_text
16503 Text if triggered by a text key, otherwise
16504 nil. See description of script-binding com‐
16505 mand for details (this field is equivalent
16506 to the 5th argument).
16507 Internally, key bindings are dispatched via the script-mes‐
16509 sage-to or script-binding input commands and mp.regis‐
16510 ter_script_message.
16511 Trying to map multiple commands to a key will essentially prefer
16513 a random binding, while the other bindings are not called. It is
16514 guaranteed that user defined bindings in the central input.conf
16515 are preferred over bindings added with this function (but see
16516 mp.add_forced_key_binding).
16517 Example:
16519 function something_handler()
16521 print("the key was pressed")
16522 end
16523 mp.add_key_binding("x", "something", something_handler)
16524 This will print the message the key was pressed when x was
16526 pressed.
16527 The user can remap these key bindings. Then the user has to put
16529 the following into their input.conf to remap the command to the
16530 y key:
16531 y script-binding something
16533 This will print the message when the key y is pressed. (x will
16535 still work, unless the user remaps it.)
16536 You can also explicitly send a message to a named script only.
16538 Assume the above script was using the filename fooscript.lua:
16539 y script-binding fooscript/something
16541 mp.add_forced_key_binding(...)
16543 This works almost the same as mp.add_key_binding, but registers
16544 the key binding in a way that will overwrite the user's custom
16545 bindings in their input.conf. (mp.add_key_binding overwrites de‐
16546 fault key bindings only, but not those by the user's in‐
16547 put.conf.)
16548 mp.remove_key_binding(name)
16550 Remove a key binding added with mp.add_key_binding or
16551 mp.add_forced_key_binding. Use the same name as you used when
16552 adding the bindings. It's not possible to remove bindings for
16553 which you omitted the name.
16554 mp.register_event(name, fn)
16556 Call a specific function when an event happens. The event name
16557 is a string, and the function fn is a Lua function value.
16558 Some events have associated data. This is put into a Lua table
16560 and passed as argument to fn. The Lua table by default contains
16561 a name field, which is a string containing the event name. If
16562 the event has an error associated, the error field is set to a
16563 string describing the error, on success it's not set.
16564 If multiple functions are registered for the same event, they
16566 are run in registration order, which the first registered func‐
16567 tion running before all the other ones.
16568 Returns true if such an event exists, false otherwise.
16570 See Events and List of events for details.
16572 mp.unregister_event(fn)
16574 Undo mp.register_event(..., fn). This removes all event handlers
16575 that are equal to the fn parameter. This uses normal Lua == com‐
16576 parison, so be careful when dealing with closures.
16577 mp.observe_property(name, type, fn)
16579 Watch a property for changes. If the property name is changed,
16580 then the function fn(name) will be called. type can be nil, or
16581 be set to one of none, native, bool, string, or number. none is
16582 the same as nil. For all other values, the new value of the
16583 property will be passed as second argument to fn, using
16584 mp.get_property_<type> to retrieve it. This means if type is for
16585 example string, fn is roughly called as in fn(name, mp.get_prop‐
16586 erty_string(name)).
16587 If possible, change events are coalesced. If a property is
16589 changed a bunch of times in a row, only the last change triggers
16590 the change function. (The exact behavior depends on timing and
16591 other things.)
16592 If a property is unavailable, or on error, the value argument to
16594 fn is nil. (The observe_property() call always succeeds, even if
16595 a property does not exist.)
16596 In some cases the function is not called even if the property
16598 changes. This depends on the property, and it's a valid feature
16599 request to ask for better update handling of a specific prop‐
16600 erty.
16601 If the type is none or nil, sporadic property change events are
16603 possible. This means the change function fn can be called even
16604 if the property doesn't actually change.
16605 You always get an initial change notification. This is meant to
16607 initialize the user's state to the current value of the prop‐
16608 erty.
16609 mp.unobserve_property(fn)
16611 Undo mp.observe_property(..., fn). This removes all property
16612 handlers that are equal to the fn parameter. This uses normal
16613 Lua == comparison, so be careful when dealing with closures.
16614 mp.add_timeout(seconds, fn)
16616 Call the given function fn when the given number of seconds has
16617 elapsed. Note that the number of seconds can be fractional. For
16618 now, the timer's resolution may be as low as 50 ms, although
16619 this will be improved in the future.
16620 This is a one-shot timer: it will be removed when it's fired.
16622 Returns a timer object. See mp.add_periodic_timer for details.
16624 mp.add_periodic_timer(seconds, fn)
16626 Call the given function periodically. This is like mp.add_time‐
16627 out, but the timer is re-added after the function fn is run.
16628 Returns a timer object. The timer object provides the following
16630 methods:
16631 stop() Disable the timer. Does nothing if the timer is
16633 already disabled. This will remember the current
16634 elapsed time when stopping, so that resume() es‐
16635 sentially unpauses the timer.
16636 kill() Disable the timer. Resets the elapsed time. re‐
16638 sume() will restart the timer.
16639 resume()
16641 Restart the timer. If the timer was disabled with
16642 stop(), this will resume at the time it was
16643 stopped. If the timer was disabled with kill(), or
16644 if it's a previously fired one-shot timer (added
16645 with add_timeout()), this starts the timer from
16646 the beginning, using the initially configured
16647 timeout.
16648 is_enabled()
16650 Whether the timer is currently enabled or was pre‐
16651 viously disabled (e.g. by stop() or kill()).
16652 timeout (RW)
16654 This field contains the current timeout period.
16655 This value is not updated as time progresses. It's
16656 only used to calculate when the timer should fire
16657 next when the timer expires.
16658 If you write this, you can call t:kill() ; t:re‐
16660 sume() to reset the current timeout to the new
16661 one. (t:stop() won't use the new timeout.)
16662 oneshot (RW)
16664 Whether the timer is periodic (false) or fires
16665 just once (true). This value is used when the
16666 timer expires (but before the timer callback func‐
16667 tion fn is run).
16668 Note that these are methods, and you have to call them using :
16670 instead of . (Refer to
16671 https://www.lua.org/manual/5.2/manual.html#3.4.9 .)
16672 Example:
16674 seconds = 0
16676 timer = mp.add_periodic_timer(1, function()
16677 print("called every second")
16678 # stop it after 10 seconds
16679 seconds = seconds + 1
16680 if seconds >= 10 then
16681 timer:kill()
16682 end
16683 end)
16684 mp.get_opt(key)
16686 Return a setting from the --script-opts option. It's up to the
16687 user and the script how this mechanism is used. Currently, all
16688 scripts can access this equally, so you should be careful about
16689 collisions.
16690 mp.get_script_name()
16692 Return the name of the current script. The name is usually made
16693 of the filename of the script, with directory and file extension
16694 removed. If there are several scripts which would have the same
16695 name, it's made unique by appending a number. Any nonalphanu‐
16696 meric characters are replaced with _.
16697 Example
16699 The script /path/to/foo-script.lua becomes foo_script.
16701 mp.get_script_directory()
16703 Return the directory if this is a script packaged as directory
16704 (see Script location for a description). Return nothing if this
16705 is a single file script.
16706 mp.osd_message(text [,duration])
16708 Show an OSD message on the screen. duration is in seconds, and
16709 is optional (uses --osd-duration by default).
16710 Advanced mp functions
16712 These also live in the mp module, but are documented separately as they
16713 are useful only in special situations.
16714 mp.get_wakeup_pipe()
16716 Calls mpv_get_wakeup_pipe() and returns the read end of the
16717 wakeup pipe. This is deprecated, but still works. (See client.h
16718 for details.)
16719 mp.get_next_timeout()
16721 Return the relative time in seconds when the next timer
16722 (mp.add_timeout and similar) expires. If there is no timer, re‐
16723 turn nil.
16724 mp.dispatch_events([allow_wait])
16726 This can be used to run custom event loops. If you want to have
16727 direct control what the Lua script does (instead of being called
16728 by the default event loop), you can set the global variable
16729 mp_event_loop to your own function running the event loop. From
16730 your event loop, you should call mp.dispatch_events() to dequeue
16731 and dispatch mpv events.
16732 If the allow_wait parameter is set to true, the function will
16734 block until the next event is received or the next timer ex‐
16735 pires. Otherwise (and this is the default behavior), it returns
16736 as soon as the event loop is emptied. It's strongly recommended
16737 to use mp.get_next_timeout() and mp.get_wakeup_pipe() if you're
16738 interested in properly working notification of new events and
16739 working timers.
16740 mp.register_idle(fn)
16742 Register an event loop idle handler. Idle handlers are called
16743 before the script goes to sleep after handling all new events.
16744 This can be used for example to delay processing of property
16745 change events: if you're observing multiple properties at once,
16746 you might not want to act on each property change, but only when
16747 all change notifications have been received.
16748 mp.unregister_idle(fn)
16750 Undo mp.register_idle(fn). This removes all idle handlers that
16751 are equal to the fn parameter. This uses normal Lua == compari‐
16752 son, so be careful when dealing with closures.
16753 mp.enable_messages(level)
16755 Set the minimum log level of which mpv message output to re‐
16756 ceive. These messages are normally printed to the terminal. By
16757 calling this function, you can set the minimum log level of mes‐
16758 sages which should be received with the log-message event. See
16759 the description of this event for details. The level is a
16760 string, see msg.log for allowed log levels.
16761 mp.register_script_message(name, fn)
16763 This is a helper to dispatch script-message or script-message-to
16764 invocations to Lua functions. fn is called if script-message or
16765 script-message-to (with this script as destination) is run with
16766 name as first parameter. The other parameters are passed to fn.
16767 If a message with the given name is already registered, it's
16768 overwritten.
16769 Used by mp.add_key_binding, so be careful about name collisions.
16771 mp.unregister_script_message(name)
16773 Undo a previous registration with mp.register_script_message.
16774 Does nothing if the name wasn't registered.
16775 mp.create_osd_overlay(format)
16777 Create an OSD overlay. This is a very thin wrapper around the
16778 osd-overlay command. The function returns a table, which mostly
16779 contains fields that will be passed to osd-overlay. The format
16780 parameter is used to initialize the format field. The data field
16781 contains the text to be used as overlay. For details, see the
16782 osd-overlay command.
16783 In addition, it provides the following methods:
16785 update()
16787 Commit the OSD overlay to the screen, or in other words,
16788 run the osd-overlay command with the current fields of
16789 the overlay table. Returns the result of the osd-overlay
16790 command itself.
16791 remove()
16793 Remove the overlay from the screen. A update() call will
16794 add it again.
16795 Example:
16797 ov = mp.create_osd_overlay("ass-events")
16799 ov.data = "{\\an5}{\\b1}hello world!"
16800 ov:update()
16801 The advantage of using this wrapper (as opposed to running
16803 osd-overlay directly) is that the id field is allocated automat‐
16804 ically.
16805 mp.get_osd_size()
16807 Returns a tuple of osd_width, osd_height, osd_par. The first two
16808 give the size of the OSD in pixels (for video outputs like
16809 --vo=xv, this may be "scaled" pixels). The third is the display
16810 pixel aspect ratio.
16811 May return invalid/nonsense values if OSD is not initialized
16813 yet.
16814 mp.msg functions
16816 This module allows outputting messages to the terminal, and can be
16817 loaded with require 'mp.msg'.
16818 msg.log(level, ...)
16820 The level parameter is the message priority. It's a string and
16821 one of fatal, error, warn, info, v, debug, trace. The user's
16822 settings will determine which of these messages will be visible.
16823 Normally, all messages are visible, except v, debug and trace.
16824 The parameters after that are all converted to strings. Spaces
16826 are inserted to separate multiple parameters.
16827 You don't need to add newlines.
16829 msg.fatal(...), msg.error(...), msg.warn(...), msg.info(...), msg.ver‐
16831 bose(...), msg.debug(...), msg.trace(...)
16832 All of these are shortcuts and equivalent to the corresponding
16833 msg.log(level, ...) call.
16834 mp.options functions
16836 mpv comes with a built-in module to manage options from config-files
16837 and the command-line. All you have to do is to supply a table with de‐
16838 fault options to the read_options function. The function will overwrite
16839 the default values with values found in the config-file and the com‐
16840 mand-line (in that order).
16841 options.read_options(table [, identifier [, on_update]])
16843 A table with key-value pairs. The type of the default values is
16844 important for converting the values read from the config file or
16845 command-line back. Do not use nil as a default value!
16846 The identifier is used to identify the config-file and the com‐
16848 mand-line options. These needs to unique to avoid collisions
16849 with other scripts. Defaults to mp.get_script_name() if the pa‐
16850 rameter is nil or missing.
16851 The on_update parameter enables run-time updates of all matching
16853 option values via the script-opts option/property. If any of the
16854 matching options changes, the values in the table (which was
16855 originally passed to the function) are changed, and on_up‐
16856 date(list) is called. list is a table where each updated option
16857 has a list[option_name] = true entry. There is no initial
16858 on_update() call. This never re-reads the config file.
16859 script-opts is always applied on the original config file, ig‐
16860 noring previous script-opts values (for example, if an option is
16861 removed from script-opts at runtime, the option will have the
16862 value in the config file). table entries are only written for
16863 option values whose values effectively change (this is important
16864 if the script changes table entries independently).
16865 Example implementation:
16867 require 'mp.options'
16869 local options = {
16870 optionA = "defaultvalueA",
16871 optionB = -0.5,
16872 optionC = true,
16873 }
16874 read_options(options, "myscript")
16875 print(options.optionA)
16876 The config file will be stored in script-opts/identifier.conf in mpv's
16878 user folder. Comment lines can be started with # and stray spaces are
16879 not removed. Boolean values will be represented with yes/no.
16880 Example config:
16882 # comment
16884 optionA=Hello World
16885 optionB=9999
16886 optionC=no
16887 Command-line options are read from the --script-opts parameter. To
16889 avoid collisions, all keys have to be prefixed with identifier-.
16890 Example command-line:
16892 --script-opts=myscript-optionA=TEST,myscript-optionB=0,myscript-optionC=yes
16894 mp.utils functions
16896 This built-in module provides generic helper functions for Lua, and
16897 have strictly speaking nothing to do with mpv or video/audio playback.
16898 They are provided for convenience. Most compensate for Lua's scarce
16899 standard library.
16900 Be warned that any of these functions might disappear any time. They
16902 are not strictly part of the guaranteed API.
16903 utils.getcwd()
16905 Returns the directory that mpv was launched from. On error, nil,
16906 error is returned.
16907 utils.readdir(path [, filter])
16909 Enumerate all entries at the given path on the filesystem, and
16910 return them as array. Each entry is a directory entry (without
16911 the path). The list is unsorted (in whatever order the operat‐
16912 ing system returns it).
16913 If the filter argument is given, it must be one of the following
16915 strings:
16916 files List regular files only. This excludes directories,
16918 special files (like UNIX device files or FIFOs), and
16919 dead symlinks. It includes UNIX symlinks to regular
16920 files.
16921 dirs List directories only, or symlinks to directories. .
16923 and .. are not included.
16924 normal Include the results of both files and dirs. (This is
16926 the default.)
16927 all List all entries, even device files, dead symlinks,
16929 FIFOs, and the . and .. entries.
16930 On error, nil, error is returned.
16932 utils.file_info(path)
16934 Stats the given path for information and returns a table with
16935 the following entries:
16936 mode protection bits (on Windows, always 755 (octal) for
16938 directories and 644 (octal) for files)
16939 size size in bytes
16941 atime time of last access
16943 mtime time of last modification
16945 ctime time of last metadata change
16947 is_file
16949 Whether path is a regular file (boolean)
16950 is_dir Whether path is a directory (boolean)
16952 mode and size are integers. Timestamps (atime, mtime and ctime)
16954 are integer seconds since the Unix epoch (Unix time). The bool‐
16955 eans is_file and is_dir are provided as a convenience; they can
16956 be and are derived from mode.
16957 On error (e.g. path does not exist), nil, error is returned.
16959 utils.split_path(path)
16961 Split a path into directory component and filename component,
16962 and return them. The first return value is always the directory.
16963 The second return value is the trailing part of the path, the
16964 directory entry.
16965 utils.join_path(p1, p2)
16967 Return the concatenation of the 2 paths. Tries to be clever. For
16968 example, if p2 is an absolute path, p2 is returned without
16969 change.
16970 utils.subprocess(t)
16972 Runs an external process and waits until it exits. Returns
16973 process status and the captured output. This is a legacy wrapper
16974 around calling the subprocess command with mp.command_native. It
16975 does the following things:
16976 • copy the table t
16978 • rename cancellable field to playback_only
16980 • rename max_size to capture_size
16982 • set capture_stdout field to true if unset
16984 • set name field to subprocess
16986 • call mp.command_native(copied_t)
16988 • if the command failed, create a dummy result table
16990 • copy error_string to error field if the string is non-empty
16992 • return the result table
16994 It is recommended to use mp.command_native or mp.command_na‐
16996 tive_async directly, instead of calling this legacy wrapper. It
16997 is for compatibility only.
16998 See the subprocess documentation for semantics and further pa‐
17000 rameters.
17001 utils.subprocess_detached(t)
17003 Runs an external process and detaches it from mpv's control.
17004 The parameter t is a table. The function reads the following en‐
17006 tries:
17007 args Array of strings of the same semantics as the args
17009 used in the subprocess function.
17010 The function returns nil.
17012 This is a legacy wrapper around calling the run command with
17014 mp.commandv and other functions.
17015 utils.getpid()
17017 Returns the process ID of the running mpv process. This can be
17018 used to identify the calling mpv when launching (detached) sub‐
17019 processes.
17020 utils.get_env_list()
17022 Returns the C environment as a list of strings. (Do not confuse
17023 this with the Lua "environment", which is an unrelated concept.)
17024 utils.parse_json(str [, trail])
17026 Parses the given string argument as JSON, and returns it as a
17027 Lua table. On error, returns nil, error. (Currently, error is
17028 just a string reading error, because there is no fine-grained
17029 error reporting of any kind.)
17030 The returned value uses similar conventions as mp.get_prop‐
17032 erty_native() to distinguish empty objects and arrays.
17033 If the trail parameter is true (or any value equal to true),
17035 then trailing non-whitespace text is tolerated by the function,
17036 and the trailing text is returned as 3rd return value. (The 3rd
17037 return value is always there, but with trail set, no error is
17038 raised.)
17039 utils.format_json(v)
17041 Format the given Lua table (or value) as a JSON string and re‐
17042 turn it. On error, returns nil, error. (Errors usually only hap‐
17043 pen on value types incompatible with JSON.)
17044 The argument value uses similar conventions as mp.set_prop‐
17046 erty_native() to distinguish empty objects and arrays.
17047 utils.to_string(v)
17049 Turn the given value into a string. Formats tables and their
17050 contents. This doesn't do anything special; it is only needed
17051 because Lua is terrible.
17052 Events
17054 Events are notifications from player core to scripts. You can register
17055 an event handler with mp.register_event.
17056 Note that all scripts (and other parts of the player) receive events
17058 equally, and there's no such thing as blocking other scripts from re‐
17059 ceiving events.
17060 Example:
17062 function my_fn(event)
17064 print("start of playback!")
17065 end
17066 mp.register_event("file-loaded", my_fn)
17068 For the existing event types, see List of events.
17070 Extras
17072 This documents experimental features, or features that are "too spe‐
17073 cial" to guarantee a stable interface.
17074 mp.add_hook(type, priority, fn)
17076 Add a hook callback for type (a string identifying a certain
17077 kind of hook). These hooks allow the player to call script func‐
17078 tions and wait for their result (normally, the Lua scripting in‐
17079 terface is asynchronous from the point of view of the player
17080 core). priority is an arbitrary integer that allows ordering
17081 among hooks of the same kind. Using the value 50 is recommended
17082 as neutral default value.
17083 fn(hook) is the function that will be called during execution of
17085 the hook. The parameter passed to it (hook) is a Lua object that
17086 can control further aspects about the currently invoked hook. It
17087 provides the following methods:
17088 defer()
17090 Returning from the hook function should not automati‐
17091 cally continue the hook. Instead, the API user wants
17092 to call hook:cont() on its own at a later point in
17093 time (before or after the function has returned).
17094 cont() Continue the hook. Doesn't need to be called unless
17096 defer() was called.
17097 See Hooks for currently existing hooks and what they do - only
17099 the hook list is interesting; handling hook execution is done by
17100 the Lua script function automatically.
17101
17103 JavaScript support in mpv is near identical to its Lua support. Use
17104 this section as reference on differences and availability of APIs, but
17105 otherwise you should refer to the Lua documentation for API details and
17106 general scripting in mpv.
17107 Example
17109 JavaScript code which leaves fullscreen mode when the player is paused:
17110 function on_pause_change(name, value) {
17112 if (value == true)
17113 mp.set_property("fullscreen", "no");
17114 }
17115 mp.observe_property("pause", "bool", on_pause_change);
17116 Similarities with Lua
17118 mpv tries to load a script file as JavaScript if it has a .js exten‐
17119 sion, but otherwise, the documented Lua options, script directories,
17120 loading, etc apply to JavaScript files too.
17121 Script initialization and lifecycle is the same as with Lua, and most
17123 of the Lua functions at the modules mp, mp.utils, mp.msg and mp.options
17124 are available to JavaScript with identical APIs - including running
17125 commands, getting/setting properties, registering events/key-bind‐
17126 ings/hooks, etc.
17127 Differences from Lua
17129 No need to load modules. mp, mp.utils, mp.msg and mp.options are pre‐
17130 loaded, and you can use e.g. var cwd = mp.utils.getcwd(); without prior
17131 setup.
17132 Errors are slightly different. Where the Lua APIs return nil for error,
17134 the JavaScript ones return undefined. Where Lua returns something, er‐
17135 ror JavaScript returns only something - and makes error available via
17136 mp.last_error(). Note that only some of the functions have this addi‐
17137 tional error value - typically the same ones which have it in Lua.
17138 Standard APIs are preferred. For instance setTimeout and JSON.stringify
17140 are available, but mp.add_timeout and mp.utils.format_json are not.
17141 No standard library. This means that interaction with anything outside
17143 of mpv is limited to the available APIs, typically via mp.utils. How‐
17144 ever, some file functions were added, and CommonJS require is available
17145 too - where the loaded modules have the same privileges as normal
17146 scripts.
17147 Language features - ECMAScript 5
17149 The scripting backend which mpv currently uses is MuJS - a compatible
17150 minimal ES5 interpreter. As such, String.substring is implemented for
17151 instance, while the common but non-standard String.substr is not.
17152 Please consult the MuJS pages on language features and platform support
17153 - https://mujs.com .
17154 Unsupported Lua APIs and their JS alternatives
17156 mp.add_timeout(seconds, fn) JS: id = setTimeout(fn, ms)
17157 mp.add_periodic_timer(seconds, fn) JS: id = setInterval(fn, ms)
17159 utils.parse_json(str [, trail]) JS: JSON.parse(str)
17161 utils.format_json(v) JS: JSON.stringify(v)
17163 utils.to_string(v) see dump below.
17165 mp.get_next_timeout() see event loop below.
17167 mp.dispatch_events([allow_wait]) see event loop below.
17169 Scripting APIs - identical to Lua
17171 (LE) - Last-Error, indicates that mp.last_error() can be used after the
17172 call to test for success (empty string) or failure (non empty reason
17173 string). Where the Lua APIs use nil to indicate error, JS APIs use un‐
17174 defined.
17175 mp.command(string) (LE)
17177 mp.commandv(arg1, arg2, ...) (LE)
17179 mp.command_native(table [,def]) (LE)
17181 id = mp.command_native_async(table [,fn]) (LE) Notes: id is true-thy on
17183 success, error is empty string on success.
17184 mp.abort_async_command(id)
17186 mp.get_property(name [,def]) (LE)
17188 mp.get_property_osd(name [,def]) (LE)
17190 mp.get_property_bool(name [,def]) (LE)
17192 mp.get_property_number(name [,def]) (LE)
17194 mp.get_property_native(name [,def]) (LE)
17196 mp.set_property(name, value) (LE)
17198 mp.set_property_bool(name, value) (LE)
17200 mp.set_property_number(name, value) (LE)
17202 mp.set_property_native(name, value) (LE)
17204 mp.get_time()
17206 mp.add_key_binding(key, name|fn [,fn [,flags]])
17208 mp.add_forced_key_binding(...)
17210 mp.remove_key_binding(name)
17212 mp.register_event(name, fn)
17214 mp.unregister_event(fn)
17216 mp.observe_property(name, type, fn)
17218 mp.unobserve_property(fn)
17220 mp.get_opt(key)
17222 mp.get_script_name()
17224 mp.get_script_directory()
17226 mp.osd_message(text [,duration])
17228 mp.get_wakeup_pipe()
17230 mp.register_idle(fn)
17232 mp.unregister_idle(fn)
17234 mp.enable_messages(level)
17236 mp.register_script_message(name, fn)
17238 mp.unregister_script_message(name)
17240 mp.create_osd_overlay(format)
17242 mp.get_osd_size() (returned object has properties: width, height, as‐
17244 pect)
17245 mp.msg.log(level, ...)
17247 mp.msg.fatal(...)
17249 mp.msg.error(...)
17251 mp.msg.warn(...)
17253 mp.msg.info(...)
17255 mp.msg.verbose(...)
17257 mp.msg.debug(...)
17259 mp.msg.trace(...)
17261 mp.utils.getcwd() (LE)
17263 mp.utils.readdir(path [, filter]) (LE)
17265 mp.utils.file_info(path) (LE) Note: like lua - this does NOT expand
17267 meta-paths like ~~/foo (other JS file functions do expand meta paths).
17268 mp.utils.split_path(path)
17270 mp.utils.join_path(p1, p2)
17272 mp.utils.subprocess(t)
17274 mp.utils.subprocess_detached(t)
17276 mp.utils.get_env_list()
17278 mp.utils.getpid() (LE)
17280 mp.add_hook(type, priority, fn(hook))
17282 mp.options.read_options(obj [, identifier [, on_update]]) (types:
17284 string/boolean/number)
17285 Additional utilities
17287 mp.last_error()
17288 If used after an API call which updates last error, returns an
17289 empty string if the API call succeeded, or a non-empty error
17290 reason string otherwise.
17291 Error.stack (string)
17293 When using try { ... } catch(e) { ... }, then e.stack is the
17294 stack trace of the error - if it was created using the Er‐
17295 ror(...) constructor.
17296 print (global)
17298 A convenient alias to mp.msg.info.
17299 dump (global)
17301 Like print but also expands objects and arrays recursively.
17302 mp.utils.getenv(name)
17304 Returns the value of the host environment variable name, or un‐
17305 defined if the variable is not defined.
17306 mp.utils.get_user_path(path)
17308 Trivial wrapper of the expand-path mpv command, returns a
17309 string. read_file, write_file, append_file and require already
17310 expand the path internally and accept mpv meta-paths like
17311 ~~desktop/foo.
17312 mp.utils.read_file(fname [,max])
17314 Returns the content of file fname as string. If max is provided
17315 and not negative, limit the read to max bytes.
17316 mp.utils.write_file(fname, str)
17318 (Over)write file fname with text content str. fname must be pre‐
17319 fixed with file:// as simple protection against accidental argu‐
17320 ments switch, e.g. mp.utils.write_file("file://~/abc.txt",
17321 "hello world").
17322 mp.utils.append_file(fname, str)
17324 Same as mp.utils.write_file if the file fname does not exist. If
17325 it does exist then append instead of overwrite.
17326 Note: read_file, write_file and append_file throw on errors, allow text
17328 content only.
17329 mp.get_time_ms()
17331 Same as mp.get_time() but in ms instead of seconds.
17332 mp.get_script_file()
17334 Returns the file name of the current script.
17335 exit() (global)
17337 Make the script exit at the end of the current event loop itera‐
17338 tion. Note: please remove added key bindings before calling
17339 exit().
17340 mp.utils.compile_js(fname, content_str)
17342 Compiles the JS code content_str as file name fname (without
17343 loading anything from the filesystem), and returns it as a func‐
17344 tion. Very similar to a Function constructor, but shows at stack
17345 traces as fname.
17346 mp.module_paths
17348 Global modules search paths array for the require function (see
17349 below).
17350 Timers (global)
17352 The standard HTML/node.js timers are available:
17353 id = setTimeout(fn [,duration [,arg1 [,arg2...]]])
17355 id = setTimeout(code_string [,duration])
17357 clearTimeout(id)
17359 id = setInterval(fn [,duration [,arg1 [,arg2...]]])
17361 id = setInterval(code_string [,duration])
17363 clearInterval(id)
17365 setTimeout and setInterval return id, and later call fn (or execute
17367 code_string) after duration ms. Interval also repeat every duration.
17368 duration has a minimum and default value of 0, code_string is a plain
17370 string which is evaluated as JS code, and [,arg1 [,arg2..]] are used as
17371 arguments (if provided) when calling back fn.
17372 The clear...(id) functions cancel timer id, and are irreversible.
17374 Note: timers always call back asynchronously, e.g. setTimeout(fn) will
17376 never call fn before returning. fn will be called either at the end of
17377 this event loop iteration or at a later event loop iteration. This is
17378 true also for intervals - which also never call back twice at the same
17379 event loop iteration.
17380 Additionally, timers are processed after the event queue is empty, so
17382 it's valid to use setTimeout(fn) as a one-time idle observer.
17383 CommonJS modules and require(id)
17385 CommonJS Modules are a standard system where scripts can export common
17386 functions for use by other scripts. Specifically, a module is a script
17387 which adds properties (functions, etc) to its pre-existing exports ob‐
17388 ject, which another script can access with require(module-id). This
17389 runs the module and returns its exports object. Further calls to re‐
17390 quire for the same module will return its cached exports object without
17391 running the module again.
17392 Modules and require are supported, standard compliant, and generally
17394 similar to node.js. However, most node.js modules won't run due to
17395 missing modules such as fs, process, etc, but some node.js modules with
17396 minimal dependencies do work. In general, this is for mpv modules and
17397 not a node.js replacement.
17398 A .js file extension is always added to id, e.g. require("./foo") will
17400 load the file ./foo.js and return its exports object.
17401 An id which starts with ./ or ../ is relative to the script or module
17403 which require it. Otherwise it's considered a top-level id (CommonJS
17404 term).
17405 Top-level id is evaluated as absolute filesystem path if possible, e.g.
17407 /x/y or ~/x. Otherwise it's considered a global module id and searched
17408 according to mp.module_paths in normal array order, e.g. require("x")
17409 tries to load x.js at one of the array paths, and id foo/x tries to
17410 load x.js inside dir foo at one of the paths.
17411 The mp.module_paths array is empty by default except for scripts which
17413 are loaded as a directory where it contains one item - <directory>/mod‐
17414 ules/ . The array may be updated from a script (or using custom init -
17415 see below) which will affect future calls to require for global module
17416 id's which are not already loaded/cached.
17417 No global variable, but a module's this at its top lexical scope is the
17419 global object - also in strict mode. If you have a module which needs
17420 global as the global object, you could do this.global = this; before
17421 require.
17422 Functions and variables declared at a module don't pollute the global
17424 object.
17425 Custom initialization
17427 After mpv initializes the JavaScript environment for a script but be‐
17428 fore it loads the script - it tries to run the file init.js at the root
17429 of the mpv configuration directory. Code at this file can update the
17430 environment further for all scripts. E.g. if it contains mp.mod‐
17431 ule_paths.push("/foo") then require at all scripts will search global
17432 module id's also at /foo (do NOT do mp.module_paths = ["/foo"]; because
17433 this will remove existing paths - like <script-dir>/modules for scripts
17434 which load from a directory).
17435 The custom-init file is ignored if mpv is invoked with --no-config.
17437 Before mpv 0.34, the file name was .init.js (with dot) at the same dir.
17439 The event loop
17441 The event loop poll/dispatch mpv events as long as the queue is not
17442 empty, then processes the timers, then waits for the next event, and
17443 repeats this forever.
17444 You could put this code at your script to replace the built-in event
17446 loop, and also print every event which mpv sends to your script:
17447 function mp_event_loop() {
17449 var wait = 0;
17450 do {
17451 var e = mp.wait_event(wait);
17452 dump(e); // there could be a lot of prints...
17453 if (e.event != "none") {
17454 mp.dispatch_event(e);
17455 wait = 0;
17456 } else {
17457 wait = mp.process_timers() / 1000;
17458 if (wait != 0) {
17459 mp.notify_idle_observers();
17460 wait = mp.peek_timers_wait() / 1000;
17461 }
17462 }
17463 } while (mp.keep_running);
17464 }
17465 mp_event_loop is a name which mpv tries to call after the script loads.
17467 The internal implementation is similar to this (without dump though..).
17468 e = mp.wait_event(wait) returns when the next mpv event arrives, or af‐
17470 ter wait seconds if positive and no mpv events arrived. wait value of 0
17471 returns immediately (with e.event == "none" if the queue is empty).
17472 mp.dispatch_event(e) calls back the handlers registered for e.event, if
17474 there are such (event handlers, property observers, script messages,
17475 etc).
17476 mp.process_timers() calls back the already-added, non-canceled due
17478 timers, and returns the duration in ms till the next due timer (possi‐
17479 bly 0), or -1 if there are no pending timers. Must not be called recur‐
17480 sively.
17481 mp.notify_idle_observers() calls back the idle observers, which we do
17483 when we're about to sleep (wait != 0), but the observers may add timers
17484 or take non-negligible duration to complete, so we re-calculate wait
17485 afterwards.
17486 mp.peek_timers_wait() returns the same values as mp.process_timers()
17488 but without doing anything. Invalid result if called from a timer call‐
17489 back.
17490 Note: exit() is also registered for the shutdown event, and its imple‐
17492 mentation is a simple mp.keep_running = false.
17493
17495 mpv can be controlled by external programs using the JSON-based IPC
17496 protocol. It can be enabled by specifying the path to a unix socket or
17497 a named pipe using the option --input-ipc-server. Clients can connect
17498 to this socket and send commands to the player or receive events from
17499 it.
17500 WARNING:
17502 This is not intended to be a secure network protocol. It is explic‐
17503 itly insecure: there is no authentication, no encryption, and the
17504 commands themselves are insecure too. For example, the run command
17505 is exposed, which can run arbitrary system commands. The use-case is
17506 controlling the player locally. This is not different from the
17507 MPlayer slave protocol.
17508 Socat example
17510 You can use the socat tool to send commands (and receive replies) from
17511 the shell. Assuming mpv was started with:
17512 mpv file.mkv --input-ipc-server=/tmp/mpvsocket
17514 Then you can control it using socat:
17516 > echo '{ "command": ["get_property", "playback-time"] }' | socat - /tmp/mpvsocket
17518 {"data":190.482000,"error":"success"}
17519 In this case, socat copies data between stdin/stdout and the mpv socket
17521 connection.
17522 See the --idle option how to make mpv start without exiting immediately
17524 or playing a file.
17525 It's also possible to send input.conf style text-only commands:
17527 > echo 'show-text ${playback-time}' | socat - /tmp/mpvsocket
17529 But you won't get a reply over the socket. (This particular command
17531 shows the playback time on the player's OSD.)
17532 Command Prompt example
17534 Unfortunately, it's not as easy to test the IPC protocol on Windows,
17535 since Windows ports of socat (in Cygwin and MSYS2) don't understand
17536 named pipes. In the absence of a simple tool to send and receive from
17537 bidirectional pipes, the echo command can be used to send commands, but
17538 not receive replies from the command prompt.
17539 Assuming mpv was started with:
17541 mpv file.mkv --input-ipc-server=\\.\pipe\mpvsocket
17543 You can send commands from a command prompt:
17545 echo show-text ${playback-time} >\\.\pipe\mpvsocket
17547 To be able to simultaneously read and write from the IPC pipe, like on
17549 Linux, it's necessary to write an external program that uses overlapped
17550 file I/O (or some wrapper like .NET's NamedPipeClientStream.)
17551 You can open the pipe in PuTTY as "serial" device. This is not very
17553 comfortable, but gives a way to test interactively without having to
17554 write code.
17555 Protocol
17557 The protocol uses UTF-8-only JSON as defined by RFC-8259. Unlike stan‐
17558 dard JSON, "u" escape sequences are not allowed to construct surrogate
17559 pairs. To avoid getting conflicts, encode all text characters including
17560 and above codepoint U+0020 as UTF-8. mpv might output broken UTF-8 in
17561 corner cases (see "UTF-8" section below).
17562 Clients can execute commands on the player by sending JSON messages of
17564 the following form:
17565 { "command": ["command_name", "param1", "param2", ...] }
17567 where command_name is the name of the command to be executed, followed
17569 by a list of parameters. Parameters must be formatted as native JSON
17570 values (integers, strings, booleans, ...). Every message must be termi‐
17571 nated with \n. Additionally, \n must not appear anywhere inside the
17572 message. In practice this means that messages should be minified before
17573 being sent to mpv.
17574 mpv will then send back a reply indicating whether the command was run
17576 correctly, and an additional field holding the command-specific return
17577 data (it can also be null).
17578 { "error": "success", "data": null }
17580 mpv will also send events to clients with JSON messages of the follow‐
17582 ing form:
17583 { "event": "event_name" }
17585 where event_name is the name of the event. Additional event-specific
17587 fields can also be present. See List of events for a list of all sup‐
17588 ported events.
17589 Because events can occur at any time, it may be difficult at times to
17591 determine which response goes with which command. Commands may option‐
17592 ally include a request_id which, if provided in the command request,
17593 will be copied verbatim into the response. mpv does not interpret the
17594 request_id in any way; it is solely for the use of the requester. The
17595 only requirement is that the request_id field must be an integer (a
17596 number without fractional parts in the range -2^63..2^63-1). Using
17597 other types is deprecated and will currently show a warning. In the fu‐
17598 ture, this will raise an error.
17599 For example, this request:
17601 { "command": ["get_property", "time-pos"], "request_id": 100 }
17603 Would generate this response:
17605 { "error": "success", "data": 1.468135, "request_id": 100 }
17607 If you don't specify a request_id, command replies will set it to 0.
17609 All commands, replies, and events are separated from each other with a
17611 line break character (\n).
17612 If the first character (after skipping whitespace) is not {, the com‐
17614 mand will be interpreted as non-JSON text command, as they are used in
17615 input.conf (or mpv_command_string() in the client API). Additionally,
17616 lines starting with # and empty lines are ignored.
17617 Currently, embedded 0 bytes terminate the current line, but you should
17619 not rely on this.
17620 Data flow
17622 Currently, the mpv-side IPC implementation does not service the socket
17623 while a command is executed and the reply is written. It is for example
17624 not possible that other events, that happened during the execution of
17625 the command, are written to the socket before the reply is written.
17626 This might change in the future. The only guarantee is that replies to
17628 IPC messages are sent in sequence.
17629 Also, since socket I/O is inherently asynchronous, it is possible that
17631 you read unrelated event messages from the socket, before you read the
17632 reply to the previous command you sent. In this case, these events were
17633 queued by the mpv side before it read and started processing your com‐
17634 mand message.
17635 If the mpv-side IPC implementation switches away from blocking writes
17637 and blocking command execution, it may attempt to send events at any
17638 time.
17639 You can also use asynchronous commands, which can return in any order,
17641 and which do not block IPC protocol interaction at all while the com‐
17642 mand is executed in the background.
17643 Asynchronous commands
17645 Command can be run asynchronously. This behaves exactly as with normal
17646 command execution, except that execution is not blocking. Other com‐
17647 mands can be sent while it's executing, and command completion can be
17648 arbitrarily reordered.
17649 The async field controls this. If present, it must be a boolean. If
17651 missing, false is assumed.
17652 For example, this initiates an asynchronous command:
17654 { "command": ["screenshot"], "request_id": 123, "async": true }
17656 And this is the completion:
17658 {"request_id":123,"error":"success","data":null}
17660 By design, you will not get a confirmation that the command was
17662 started. If a command is long running, sending the message will lead to
17663 any reply until much later when the command finishes.
17664 Some commands execute synchronously, but these will behave like asyn‐
17666 chronous commands that finished execution immediately.
17667 Cancellation of asynchronous commands is available in the libmpv API,
17669 but has not yet been implemented in the IPC protocol.
17670 Commands with named arguments
17672 If the command field is a JSON object, named arguments are expected.
17673 This is described in the C API mpv_command_node() documentation (the
17674 MPV_FORMAT_NODE_MAP case). In some cases, this may make commands more
17675 readable, while some obscure commands basically require using named ar‐
17676 guments.
17677 Currently, only "proper" commands (as listed by List of Input Commands)
17679 support named arguments.
17680 Commands
17682 In addition to the commands described in List of Input Commands, a few
17683 extra commands can also be used as part of the protocol:
17684 client_name
17686 Return the name of the client as string. This is the string
17687 ipc-N with N being an integer number.
17688 get_time_us
17690 Return the current mpv internal time in microseconds as a num‐
17691 ber. This is basically the system time, with an arbitrary off‐
17692 set.
17693 get_property
17695 Return the value of the given property. The value will be sent
17696 in the data field of the replay message.
17697 Example:
17699 { "command": ["get_property", "volume"] }
17701 { "data": 50.0, "error": "success" }
17702 get_property_string
17704 Like get_property, but the resulting data will always be a
17705 string.
17706 Example:
17708 { "command": ["get_property_string", "volume"] }
17710 { "data": "50.000000", "error": "success" }
17711 set_property
17713 Set the given property to the given value. See Properties for
17714 more information about properties.
17715 Example:
17717 { "command": ["set_property", "pause", true] }
17719 { "error": "success" }
17720 set_property_string
17722 Alias for set_property. Both commands accept native values and
17723 strings.
17724 observe_property
17726 Watch a property for changes. If the given property is changed,
17727 then an event of type property-change will be generated
17728 Example:
17730 { "command": ["observe_property", 1, "volume"] }
17732 { "error": "success" }
17733 { "event": "property-change", "id": 1, "data": 52.0, "name": "volume" }
17734 WARNING:
17736 If the connection is closed, the IPC client is destroyed in‐
17737 ternally, and the observed properties are unregistered. This
17738 happens for example when sending commands to a socket with
17739 separate socat invocations. This can make it seem like prop‐
17740 erty observation does not work. You must keep the IPC connec‐
17741 tion open to make it work.
17742 observe_property_string
17744 Like observe_property, but the resulting data will always be a
17745 string.
17746 Example:
17748 { "command": ["observe_property_string", 1, "volume"] }
17750 { "error": "success" }
17751 { "event": "property-change", "id": 1, "data": "52.000000", "name": "volume" }
17752 unobserve_property
17754 Undo observe_property or observe_property_string. This requires
17755 the numeric id passed to the observed command as argument.
17756 Example:
17758 { "command": ["unobserve_property", 1] }
17760 { "error": "success" }
17761 request_log_messages
17763 Enable output of mpv log messages. They will be received as
17764 events. The parameter to this command is the log-level (see
17765 mpv_request_log_messages C API function).
17766 Log message output is meant for humans only (mostly for debug‐
17768 ging). Attempting to retrieve information by parsing these mes‐
17769 sages will just lead to breakages with future mpv releases. In‐
17770 stead, make a feature request, and ask for a proper event that
17771 returns the information you need.
17772 enable_event, disable_event
17774 Enables or disables the named event. Mirrors the mpv_re‐
17775 quest_event C API function. If the string all is used instead of
17776 an event name, all events are enabled or disabled.
17777 By default, most events are enabled, and there is not much use
17779 for this command.
17780 get_version
17782 Returns the client API version the C API of the remote mpv in‐
17783 stance provides.
17784 See also: DOCS/client-api-changes.rst.
17786 UTF-8
17788 Normally, all strings are in UTF-8. Sometimes it can happen that
17789 strings are in some broken encoding (often happens with file tags and
17790 such, and filenames on many Unixes are not required to be in UTF-8 ei‐
17791 ther). This means that mpv sometimes sends invalid JSON. If that is a
17792 problem for the client application's parser, it should filter the raw
17793 data for invalid UTF-8 sequences and perform the desired replacement,
17794 before feeding the data to its JSON parser.
17795 mpv will not attempt to construct invalid UTF-8 with broken "u" escape
17797 sequences. This includes surrogate pairs.
17798 JSON extensions
17800 The following non-standard extensions are supported:
17801 • a list or object item can have a trailing ","
17803 • object syntax accepts "=" in addition of ":"
17805 • object keys can be unquoted, if they start with a character in
17807 "A-Za-z_" and contain only characters in "A-Za-z0-9_"
17808 • byte escapes with "xAB" are allowed (with AB being a 2 digit hex
17810 number)
17811 Example:
17813 { objkey = "value\x0A" }
17815 Is equivalent to:
17817 { "objkey": "value\n" }
17819 Alternative ways of starting clients
17821 You can create an anonymous IPC connection without having to set --in‐
17822 put-ipc-server. This is achieved through a mpv pseudo scripting backend
17823 that starts processes.
17824 You can put .run file extension in the mpv scripts directory in its
17826 config directory (see the FILES section for details), or load them
17827 through other means (see Script location). These scripts are simply ex‐
17828 ecuted with the OS native mechanism (as if you ran them in the shell).
17829 They must have a proper shebang and have the executable bit set.
17830 When executed, a socket (the IPC connection) is passed to them through
17832 file descriptor inheritance. The file descriptor is indicated as the
17833 special command line argument --mpv-ipc-fd=N, where N is the numeric
17834 file descriptor.
17835 The rest is the same as with a normal --input-ipc-server IPC connec‐
17837 tion. mpv does not attempt to observe or other interact with the
17838 started script process.
17839 This does not work in Windows yet.
17841
17843 There is no real changelog, but you can look at the following things:
17844 • The release changelog, which should contain most user-visible
17846 changes, including new features and bug fixes:
17847 https://github.com/mpv-player/mpv/releases
17849 • The git log, which is the "real" changelog
17851 • The file
17853 https://github.com/mpv-player/mpv/blob/master/DOCS/interface-changes.rst
17854 documents changes to the command and user interface, such as options
17855 and properties. (It usually documents breaking changes only, addi‐
17856 tions and enhancements are often not listed.)
17857 • C API changes are listed in
17859 https://github.com/mpv-player/mpv/blob/master/DOCS/client-api-changes.rst
17860 • The file mplayer-changes.rst in the DOCS sub directory on the git
17862 repository, which used to be in place of this section. It documents
17863 some changes that happened since mplayer2 forked off MPlayer. (Not
17864 updated anymore.)
17865
17867 mpv can be embedded into other programs as video/audio playback back‐
17868 end. The recommended way to do so is using libmpv. See libmpv/client.h
17869 in the mpv source code repository. This provides a C API. Bindings for
17870 other languages might be available (see wiki).
17871 Since libmpv merely allows access to underlying mechanisms that can
17873 control mpv, further documentation is spread over a few places:
17874 • https://github.com/mpv-player/mpv/blob/master/libmpv/client.h
17876 • https://mpv.io/manual/master/#options
17878 • https://mpv.io/manual/master/#list-of-input-commands
17880 • https://mpv.io/manual/master/#properties
17882 • https://github.com/mpv-player/mpv-examples/tree/master/libmpv
17884
17886 You can write C plugins for mpv. These use the libmpv API, although
17887 they do not use the libmpv library itself.
17888 They are available on Linux/BSD platforms only and enabled by default
17890 if the compiler supports linking with the -rdynamic flag.
17891 C plugins location
17893 C plugins are put into the mpv scripts directory in its config direc‐
17894 tory (see the FILES section for details). They must have a .so file ex‐
17895 tension. They can also be explicitly loaded with the --script option.
17896 API
17898 A C plugin must export the following function:
17899 int mpv_open_cplugin(mpv_handle *handle)
17901 The plugin function will be called on loading time. This function does
17903 not return as long as your plugin is loaded (it runs in its own
17904 thread). The handle will be deallocated as soon as the plugin function
17905 returns.
17906 The return value is interpreted as error status. A value of 0 is inter‐
17908 preted as success, while -1 signals an error. In the latter case, the
17909 player prints an uninformative error message that loading failed.
17910 Return values other than 0 and -1 are reserved, and trigger undefined
17912 behavior.
17913 Within the plugin function, you can call libmpv API functions. The han‐
17915 dle is created by mpv_create_client() (or actually an internal equiva‐
17916 lent), and belongs to you. You can call mpv_wait_event() to wait for
17917 things happening, and so on.
17918 Note that the player might block until your plugin calls
17920 mpv_wait_event() for the first time. This gives you a chance to install
17921 initial hooks etc. before playback begins.
17922 The details are quite similar to Lua scripts.
17924 Linkage to libmpv
17926 The current implementation requires that your plugins are not linked
17927 against libmpv. What your plugins use are not symbols from a libmpv bi‐
17928 nary, but symbols from the mpv host binary.
17929 Examples
17931 See:
17932 • https://github.com/mpv-player/mpv-examples/tree/master/cplugins
17934
17936 There are a number of environment variables that can be used to control
17937 the behavior of mpv.
17938 HOME, XDG_CONFIG_HOME
17940 Used to determine mpv config directory. If XDG_CONFIG_HOME is
17941 not set, $HOME/.config/mpv is used.
17942 $HOME/.mpv is always added to the list of config search paths
17944 with a lower priority.
17945 MPV_HOME
17947 Directory where mpv looks for user settings. Overrides HOME, and
17948 mpv will try to load the config file as $MPV_HOME/mpv.conf.
17949 MPV_VERBOSE (see also -v and --msg-level)
17951 Set the initial verbosity level across all message modules (de‐
17952 fault: 0). This is an integer, and the resulting verbosity cor‐
17953 responds to the number of --v options passed to the command
17954 line.
17955 MPV_LEAK_REPORT
17957 If set to 1, enable internal talloc leak reporting. If set to
17958 another value, disable leak reporting. If unset, use the de‐
17959 fault, which normally is 0. If mpv was built with --en‐
17960 able-ta-leak-report, the default is 1. If leak reporting was
17961 disabled at compile time (NDEBUG in custom CFLAGS), this envi‐
17962 ronment variable is ignored.
17963 LADSPA_PATH
17965 Specifies the search path for LADSPA plugins. If it is unset,
17966 fully qualified path names must be used.
17967 DISPLAY
17969 Standard X11 display name to use.
17970 FFmpeg/Libav:
17972 This library accesses various environment variables. However,
17973 they are not centrally documented, and documenting them is not
17974 our job. Therefore, this list is incomplete.
17975 Notable environment variables:
17977 http_proxy
17979 URL to proxy for http:// and https:// URLs.
17980 no_proxy
17982 List of domain patterns for which no proxy should be
17983 used. List entries are separated by ,. Patterns can in‐
17984 clude *.
17985 libdvdcss:
17987 DVDCSS_CACHE
17989 Specify a directory in which to store title key values.
17990 This will speed up descrambling of DVDs which are in the
17991 cache. The DVDCSS_CACHE directory is created if it does
17992 not exist, and a subdirectory is created named after the
17993 DVD's title or manufacturing date. If DVDCSS_CACHE is not
17994 set or is empty, libdvdcss will use the default value
17995 which is ${HOME}/.dvdcss/ under Unix and the roaming ap‐
17996 plication data directory (%APPDATA%) under Windows. The
17997 special value "off" disables caching.
17998 DVDCSS_METHOD
18000 Sets the authentication and decryption method that libd‐
18001 vdcss will use to read scrambled discs. Can be one of ti‐
18002 tle, key or disc.
18003 key is the default method. libdvdcss will use a set of
18005 calculated player keys to try to get the disc key.
18006 This can fail if the drive does not recognize any
18007 of the player keys.
18008 disc is a fallback method when key has failed. Instead
18010 of using player keys, libdvdcss will crack the
18011 disc key using a brute force algorithm. This
18012 process is CPU intensive and requires 64 MB of
18013 memory to store temporary data.
18014 title is the fallback when all other methods have
18016 failed. It does not rely on a key exchange with
18017 the DVD drive, but rather uses a crypto attack to
18018 guess the title key. On rare cases this may fail
18019 because there is not enough encrypted data on the
18020 disc to perform a statistical attack, but on the
18021 other hand it is the only way to decrypt a DVD
18022 stored on a hard disc, or a DVD with the wrong re‐
18023 gion on an RPC2 drive.
18024 DVDCSS_RAW_DEVICE
18026 Specify the raw device to use. Exact usage will depend on
18027 your operating system, the Linux utility to set up raw
18028 devices is raw(8) for instance. Please note that on most
18029 operating systems, using a raw device requires highly
18030 aligned buffers: Linux requires a 2048 bytes alignment
18031 (which is the size of a DVD sector).
18032 DVDCSS_VERBOSE
18034 Sets the libdvdcss verbosity level.
18035 0 Outputs no messages at all.
18037 1 Outputs error messages to stderr.
18039 2 Outputs error messages and debug messages to
18041 stderr.
18042 DVDREAD_NOKEYS
18044 Skip retrieving all keys on startup. Currently disabled.
18045 HOME FIXME: Document this.
18047
18049 Normally mpv returns 0 as exit code after finishing playback success‐
18050 fully. If errors happen, the following exit codes can be returned:
18051 1 Error initializing mpv. This is also returned if unknown op‐
18053 tions are passed to mpv.
18054 2 The file passed to mpv couldn't be played. This is somewhat
18056 fuzzy: currently, playback of a file is considered to be suc‐
18057 cessful if initialization was mostly successful, even if
18058 playback fails immediately after initialization.
18059 3 There were some files that could be played, and some files
18061 which couldn't (using the definition of success from above).
18062 4 Quit due to a signal, Ctrl+c in a VO window (by default), or
18064 from the default quit key bindings in encoding mode.
18065 Note that quitting the player manually will always lead to exit code 0,
18067 overriding the exit code that would be returned normally. Also, the
18068 quit input command can take an exit code: in this case, that exit code
18069 is returned.
18070
18072 For Windows-specifics, see FILES ON WINDOWS section.
18073 /usr/local/etc/mpv/mpv.conf
18075 mpv system-wide settings (depends on --prefix passed to config‐
18076 ure - mpv in default configuration will use /usr/local/etc/mpv/
18077 as config directory, while most Linux distributions will set it
18078 to /etc/mpv/).
18079 ~/.config/mpv
18081 The standard configuration directory. This can be overridden by
18082 environment variables, in ascending order:
18083 1 If $XDG_CONFIG_HOME is set, then the derived configura‐
18085 tion directory will be $XDG_CONFIG_HOME/mpv.
18086 2 If $MPV_HOME is set, then the derived configuration di‐
18088 rectory will be $MPV_HOME.
18089 If this directory, nor the original configuration directory (see
18091 below) do not exist, mpv tries to create this directory automat‐
18092 ically.
18093 ~/.mpv/
18095 The original (pre 0.5.0) configuration directory. It will con‐
18096 tinue to be read if present.
18097 If both this directory and the standard configuration directory
18099 are present, configuration will be read from both with the stan‐
18100 dard configuration directory content taking precedence. However,
18101 you should fully migrate to the standard directory and a warning
18102 will be shown in this situation.
18103 ~/.config/mpv/mpv.conf
18105 mpv user settings (see CONFIGURATION FILES section)
18106 ~/.config/mpv/input.conf
18108 key bindings (see INPUT.CONF section)
18109 ~/.config/mpv/fonts.conf
18111 Fontconfig fonts.conf that is customized for mpv. You should in‐
18112 clude system fonts.conf in this file or mpv would not know about
18113 fonts that you already have in the system.
18114 Only available when libass is built with fontconfig.
18116 ~/.config/mpv/subfont.ttf
18118 fallback subtitle font
18119 ~/.config/mpv/fonts/
18121 Font files in this directory are used by mpv/libass for subti‐
18122 tles. Useful if you do not want to install fonts to your system.
18123 Note that files in this directory are loaded into memory before
18124 being used by mpv. If you have a lot of fonts, consider using
18125 fonts.conf (see above) to include additional fonts, which is
18126 more memory-efficient.
18127 ~/.config/mpv/scripts/
18129 All files in this directory are loaded as if they were passed to
18130 the --script option. They are loaded in alphabetical order.
18131 The --load-scripts=no option disables loading these files.
18133 See Script location for details.
18135 ~/.config/mpv/watch_later/
18137 Contains temporary config files needed for resuming playback of
18138 files with the watch later feature. See for example the Q key
18139 binding, or the quit-watch-later input command.
18140 Each file is a small config file which is loaded if the corre‐
18142 sponding media file is loaded. It contains the playback position
18143 and some (not necessarily all) settings that were changed during
18144 playback. The filenames are hashed from the full paths of the
18145 media files. It's in general not possible to extract the media
18146 filename from this hash. However, you can set the --write-file‐
18147 name-in-watch-later-config option, and the player will add the
18148 media filename to the contents of the resume config file.
18149 ~/.config/mpv/script-opts/osc.conf
18151 This is loaded by the OSC script. See the ON SCREEN CONTROLLER
18152 docs for details.
18153 Other files in this directory are specific to the corresponding
18155 scripts as well, and the mpv core doesn't touch them.
18156
18158 On win32 (if compiled with MinGW, but not Cygwin), the default config
18159 file locations are different. They are generally located under %APP‐
18160 DATA%/mpv/. For example, the path to mpv.conf is %APP‐
18161 DATA%/mpv/mpv.conf, which maps to a system and user-specific path, for
18162 example
18163 C:\users\USERNAME\AppData\Roaming\mpv\mpv.conf
18164 You can find the exact path by running echo %APPDATA%\mpv\mpv.conf in
18166 cmd.exe.
18167 Other config files (such as input.conf) are in the same directory. See
18169 the FILES section above.
18170 The environment variable $MPV_HOME completely overrides these, like on
18172 UNIX.
18173 If a directory named portable_config next to the mpv.exe exists, all
18175 config will be loaded from this directory only. Watch later config
18176 files are written to this directory as well. (This exists on Windows
18177 only and is redundant with $MPV_HOME. However, since Windows is very
18178 scripting unfriendly, a wrapper script just setting $MPV_HOME, like you
18179 could do it on other systems, won't work. portable_config is provided
18180 for convenience to get around this restriction.)
18181 Config files located in the same directory as mpv.exe are loaded with
18183 lower priority. Some config files are loaded only once, which means
18184 that e.g. of 2 input.conf files located in two config directories, only
18185 the one from the directory with higher priority will be loaded.
18186 A third config directory with the lowest priority is the directory
18188 named mpv in the same directory as mpv.exe. This used to be the direc‐
18189 tory with the highest priority, but is now discouraged to use and might
18190 be removed in the future.
18191 Note that mpv likes to mix / and \ path separators for simplicity.
18193 kernel32.dll accepts this, but cmd.exe does not.
18194
18196 GPLv2+
18197 MPV(1)