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=<auto|yes|no>
3268 Enable direct rendering (default: auto). 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 The auto option will try to guess whether DR can improve perfor‐
3279 mance on your particular hardware. Currently this enables it on
3280 AMD or NVIDIA if using OpenGL or unconditionally if using
3281 Vulkan.
3282 Using video filters of any kind that write to the image data (or
3284 output newly allocated frames) will silently disable the DR code
3285 path.
3286 --vd-lavc-bitexact
3288 Only use bit-exact algorithms in all decoding steps (for codec
3289 testing).
3290 --vd-lavc-fast (MPEG-1/2 and H.264 only)
3292 Enable optimizations which do not comply with the format speci‐
3293 fication and potentially cause problems, like simpler dequanti‐
3294 zation, simpler motion compensation, assuming use of the default
3295 quantization matrix, assuming YUV 4:2:0 and skipping a few
3296 checks to detect damaged bitstreams.
3297 --vd-lavc-o=<key>=<value>[,<key>=<value>[,...]]
3299 Pass AVOptions to libavcodec decoder. Note, a patch to make the
3300 o= unneeded and pass all unknown options through the AVOption
3301 system is welcome. A full list of AVOptions can be found in the
3302 FFmpeg manual.
3303 Some options which used to be direct options can be set with
3305 this mechanism, like bug, gray, idct, ec, vismv, skip_top (was
3306 st), skip_bottom (was sb), debug.
3307 This is a key/value list option. See List Options for details.
3309 Example
3311 --vd-lavc-o=debug=pict
3313 --vd-lavc-show-all=<yes|no>
3315 Show even broken/corrupt frames (default: no). If this option is
3316 set to no, libavcodec won't output frames that were either de‐
3317 coded before an initial keyframe was decoded, or frames that are
3318 recognized as corrupted.
3319 --vd-lavc-skiploopfilter=<skipvalue> (H.264, HEVC only)
3321 Skips the loop filter (AKA deblocking) during decoding. Since
3322 the filtered frame is supposed to be used as reference for de‐
3323 coding dependent frames, this has a worse effect on quality than
3324 not doing deblocking on e.g. MPEG-2 video. But at least for high
3325 bitrate HDTV, this provides a big speedup with little visible
3326 quality loss. Codecs other than H.264 or HEVC may have partial
3327 support for this option (often only all and none).
3328 <skipvalue> can be one of the following:
3330 none Never skip.
3332 default
3334 Skip useless processing steps (e.g. 0 size packets in
3335 AVI).
3336 nonref Skip frames that are not referenced (i.e. not used for
3338 decoding other frames, the error cannot "build up").
3339 bidir Skip B-Frames.
3341 nonkey Skip all frames except keyframes.
3343 all Skip all frames.
3345 --vd-lavc-skipidct=<skipvalue> (MPEG-1/2/4 only)
3347 Skips the IDCT step. This degrades quality a lot in almost all
3348 cases (see skiploopfilter for available skip values).
3349 --vd-lavc-skipframe=<skipvalue>
3351 Skips decoding of frames completely. Big speedup, but jerky mo‐
3352 tion and sometimes bad artifacts (see skiploopfilter for avail‐
3353 able skip values).
3354 --vd-lavc-framedrop=<skipvalue>
3356 Set framedropping mode used with --framedrop (see skiploopfilter
3357 for available skip values).
3358 --vd-lavc-threads=<N>
3360 Number of threads to use for decoding. Whether threading is ac‐
3361 tually supported depends on codec (default: 0). 0 means autode‐
3362 tect number of cores on the machine and use that, up to the max‐
3363 imum of 16. You can set more than 16 threads manually.
3364 --vd-lavc-assume-old-x264=<yes|no>
3366 Assume the video was encoded by an old, buggy x264 version (de‐
3367 fault: no). Normally, this is autodetected by libavcodec. But
3368 if the bitstream contains no x264 version info (or it was some‐
3369 how skipped), and the stream was in fact encoded by an old x264
3370 version (build 150 or earlier), and if the stream uses 4:4:4
3371 chroma, then libavcodec will by default show corrupted video.
3372 This option sets the libavcodec x264_build option to 150, which
3373 means that if the stream contains no version info, or was not
3374 encoded by x264 at all, it assumes it was encoded by the old
3375 version. Enabling this option is pretty safe if you want your
3376 broken files to work, but in theory this can break on streams
3377 not encoded by x264, or if a stream encoded by a newer x264 ver‐
3378 sion contains no version info.
3379 --swapchain-depth=<N>
3381 Allow up to N in-flight frames. This essentially controls the
3382 frame latency. Increasing the swapchain depth can improve pipe‐
3383 lining and prevent missed vsyncs, but increases visible latency.
3384 This option only mandates an upper limit, the implementation can
3385 use a lower latency than requested internally. A setting of 1
3386 means that the VO will wait for every frame to become visible
3387 before starting to render the next frame. (Default: 3)
3388 Audio
3390 --audio-pitch-correction=<yes|no>
3391 If this is enabled (default), playing with a speed different
3392 from normal automatically inserts the scaletempo2 audio filter.
3393 For details, see audio filter section.
3394 --audio-device=<name>
3396 Use the given audio device. This consists of the audio output
3397 name, e.g. alsa, followed by /, followed by the audio output
3398 specific device name. The default value for this option is auto,
3399 which tries every audio output in preference order with the de‐
3400 fault device.
3401 You can list audio devices with --audio-device=help. This out‐
3403 puts the device name in quotes, followed by a description. The
3404 device name is what you have to pass to the --audio-device op‐
3405 tion. The list of audio devices can be retrieved by API by using
3406 the audio-device-list property.
3407 While the option normally takes one of the strings as indicated
3409 by the methods above, you can also force the device for most AOs
3410 by building it manually. For example name/foobar forces the AO
3411 name to use the device foobar. However, the --ao option will
3412 strictly force a specific AO. To avoid confusion, don't use --ao
3413 and --audio-device together.
3414 Example for ALSA
3416 MPlayer and mplayer2 required you to replace any ','
3418 with '.' and any ':' with '=' in the ALSA device name.
3419 For example, to use the device named dmix:default, you
3420 had to do:
3421 -ao alsa:device=dmix=default
3422 In mpv you could instead use:
3424 --audio-device=alsa/dmix:default
3425 --audio-exclusive=<yes|no>
3427 Enable exclusive output mode. In this mode, the system is usu‐
3428 ally locked out, and only mpv will be able to output audio.
3429 This only works for some audio outputs, such as wasapi and core‐
3431 audio. Other audio outputs silently ignore this options. They
3432 either have no concept of exclusive mode, or the mpv side of the
3433 implementation is missing.
3434 --audio-fallback-to-null=<yes|no>
3436 If no audio device can be opened, behave as if --ao=null was
3437 given. This is useful in combination with --audio-device: in‐
3438 stead of causing an error if the selected device does not exist,
3439 the client API user (or a Lua script) could let playback con‐
3440 tinue normally, and check the current-ao and audio-device-list
3441 properties to make high-level decisions about how to continue.
3442 --ao=<driver>
3444 Specify the audio output drivers to be used. See AUDIO OUTPUT
3445 DRIVERS for details and descriptions of available drivers.
3446 --af=<filter1[=parameter1:parameter2:...],filter2,...>
3448 Specify a list of audio filters to apply to the audio stream.
3449 See AUDIO FILTERS for details and descriptions of the available
3450 filters. The option variants --af-add, --af-pre, --af-del and
3451 --af-clr exist to modify a previously specified list, but you
3452 should not need these for typical use.
3453 --audio-spdif=<codecs>
3455 List of codecs for which compressed audio passthrough should be
3456 used. This works for both classic S/PDIF and HDMI.
3457 Possible codecs are ac3, dts, dts-hd, eac3, truehd. Multiple
3459 codecs can be specified by separating them with ,. dts refers to
3460 low bitrate DTS core, while dts-hd refers to DTS MA (receiver
3461 and OS support varies). If both dts and dts-hd are specified, it
3462 behaves equivalent to specifying dts-hd only.
3463 In earlier mpv versions you could use --ad to force the spdif
3465 wrapper. This does not work anymore.
3466 Warning
3468 There is not much reason to use this. HDMI supports
3470 uncompressed multichannel PCM, and mpv supports loss‐
3471 less DTS-HD decoding via FFmpeg's new DCA decoder
3472 (based on libdcadec).
3473 --ad=<decoder1,decoder2,...[-]>
3475 Specify a priority list of audio decoders to be used, according
3476 to their decoder name. When determining which decoder to use,
3477 the first decoder that matches the audio format is selected. If
3478 that is unavailable, the next decoder is used. Finally, it tries
3479 all other decoders that are not explicitly selected or rejected
3480 by the option.
3481 - at the end of the list suppresses fallback on other available
3483 decoders not on the --ad list. + in front of an entry forces the
3484 decoder. Both of these should not normally be used, because they
3485 break normal decoder auto-selection! Both of these methods are
3486 deprecated.
3487 Examples
3489 --ad=mp3float
3491 Prefer the FFmpeg/Libav mp3float decoder over all
3492 other MP3 decoders.
3493 --ad=help
3495 List all available decoders.
3496 Warning
3498 Enabling compressed audio passthrough (AC3 and DTS via
3500 SPDIF/HDMI) with this option is not possible. Use
3501 --audio-spdif instead.
3502 --volume=<value>
3504 Set the startup volume. 0 means silence, 100 means no volume re‐
3505 duction or amplification. Negative values can be passed for com‐
3506 patibility, but are treated as 0.
3507 Since mpv 0.18.1, this always controls the internal mixer (aka
3509 "softvol").
3510 --replaygain=<no|track|album>
3512 Adjust volume gain according to replaygain values stored in the
3513 file metadata. With --replaygain=no (the default), perform no
3514 adjustment. With --replaygain=track, apply track gain. With
3515 --replaygain=album, apply album gain if present and fall back to
3516 track gain otherwise.
3517 --replaygain-preamp=<db>
3519 Pre-amplification gain in dB to apply to the selected replaygain
3520 gain (default: 0).
3521 --replaygain-clip=<yes|no>
3523 Prevent clipping caused by replaygain by automatically lowering
3524 the gain (default). Use --replaygain-clip=no to disable this.
3525 --replaygain-fallback=<db>
3527 Gain in dB to apply if the file has no replay gain tags. This
3528 option is always applied if the replaygain logic is somehow in‐
3529 active. If this is applied, no other replaygain options are ap‐
3530 plied.
3531 --audio-delay=<sec>
3533 Audio delay in seconds (positive or negative float value). Posi‐
3534 tive values delay the audio, and negative values delay the
3535 video.
3536 --mute=<yes|no|auto>
3538 Set startup audio mute status (default: no).
3539 auto is a deprecated possible value that is equivalent to no.
3541 See also: --volume.
3543 --softvol=<no|yes|auto>
3545 Deprecated/unfunctional. Before mpv 0.18.1, this used to control
3546 whether to use the volume controls of the audio output driver or
3547 the internal mpv volume filter.
3548 The current behavior is that softvol is always enabled, i.e. as
3550 if this option is set to yes. The other behaviors are not avail‐
3551 able anymore, although auto almost matches current behavior in
3552 most cases.
3553 The no behavior is still partially available through the ao-vol‐
3555 ume and ao-mute properties. But there are no options to reset
3556 these.
3557 --audio-demuxer=<[+]name>
3559 Use this audio demuxer type when using --audio-file. Use a '+'
3560 before the name to force it; this will skip some checks. Give
3561 the demuxer name as printed by --audio-demuxer=help.
3562 --ad-lavc-ac3drc=<level>
3564 Select the Dynamic Range Compression level for AC-3 audio
3565 streams. <level> is a float value ranging from 0 to 1, where 0
3566 means no compression (which is the default) and 1 means full
3567 compression (make loud passages more silent and vice versa).
3568 Values up to 6 are also accepted, but are purely experimental.
3569 This option only shows an effect if the AC-3 stream contains the
3570 required range compression information.
3571 The standard mandates that DRC is enabled by default, but mpv
3573 (and some other players) ignore this for the sake of better au‐
3574 dio quality.
3575 --ad-lavc-downmix=<yes|no>
3577 Whether to request audio channel downmixing from the decoder
3578 (default: no). Some decoders, like AC-3, AAC and DTS, can remix
3579 audio on decoding. The requested number of output channels is
3580 set with the --audio-channels option. Useful for playing sur‐
3581 round audio on a stereo system.
3582 --ad-lavc-threads=<0-16>
3584 Number of threads to use for decoding. Whether threading is ac‐
3585 tually supported depends on codec. As of this writing, it's sup‐
3586 ported for some lossless codecs only. 0 means autodetect number
3587 of cores on the machine and use that, up to the maximum of 16
3588 (default: 1).
3589 --ad-lavc-o=<key>=<value>[,<key>=<value>[,...]]
3591 Pass AVOptions to libavcodec decoder. Note, a patch to make the
3592 o= unneeded and pass all unknown options through the AVOption
3593 system is welcome. A full list of AVOptions can be found in the
3594 FFmpeg manual.
3595 This is a key/value list option. See List Options for details.
3597 --ad-spdif-dtshd=<yes|no>, --dtshd, --no-dtshd
3599 If DTS is passed through, use DTS-HD.
3600 Warning
3602 This and enabling passthrough via --ad are deprecated
3604 in favor of using --audio-spdif=dts-hd.
3605 --audio-channels=<auto-safe|auto|layouts>
3607 Control which audio channels are output (e.g. surround vs.
3608 stereo). There are the following possibilities:
3609 •
3611 --audio-channels=auto-safe
3613 Use the system's preferred channel layout. If there is
3614 none (such as when accessing a hardware device instead
3615 of the system mixer), force stereo. Some audio outputs
3616 might simply accept any layout and do downmixing on
3617 their own.
3618 This is the default.
3620 •
3622 --audio-channels=auto
3624 Send the audio device whatever it accepts, preferring
3625 the audio's original channel layout. Can cause issues
3626 with HDMI (see the warning below).
3627 •
3629 --audio-channels=layout1,layout2,...
3631 List of ,-separated channel layouts which should be al‐
3632 lowed. Technically, this only adjusts the filter chain
3633 output to the best matching layout in the list, and
3634 passes the result to the audio API. It's possible that
3635 the audio API will select a different channel layout.
3636 Using this mode is recommended for direct hardware out‐
3638 put, especially over HDMI (see HDMI warning below).
3639 •
3641 --audio-channels=<stereo|mono>
3643 Force a downmix to stereo or mono. These are spe‐
3644 cial-cases of the previous item. (See paragraphs below
3645 for implications.)
3646 If a list of layouts is given, each item can be either an ex‐
3648 plicit channel layout name (like 5.1), or a channel number.
3649 Channel numbers refer to default layouts, e.g. 2 channels refer
3650 to stereo, 6 refers to 5.1.
3651 See --audio-channels=help output for defined default layouts.
3653 This also lists speaker names, which can be used to express ar‐
3654 bitrary channel layouts (e.g. fl-fr-lfe is 2.1).
3655 If the list of channel layouts has only 1 item, the decoder is
3657 asked to produce according output. This sometimes triggers de‐
3658 coder-downmix, which might be different from the normal mpv
3659 downmix. (Only some decoders support remixing audio, like AC-3,
3660 AAC or DTS. You can use --ad-lavc-downmix=no to make the decoder
3661 always output its native layout.) One consequence is that --au‐
3662 dio-channels=stereo triggers decoder downmix, while auto or
3663 auto-safe never will, even if they end up selecting stereo. This
3664 happens because the decision whether to use decoder downmix hap‐
3665 pens long before the audio device is opened.
3666 If the channel layout of the media file (i.e. the decoder) and
3668 the AO's channel layout don't match, mpv will attempt to insert
3669 a conversion filter. You may need to change the channel layout
3670 of the system mixer to achieve your desired output as mpv does
3671 not have control over it. Another work-around for this on some
3672 AOs is to use --audio-exclusive=yes to circumvent the system
3673 mixer entirely.
3674 Warning
3676 Using auto can cause issues when using audio over
3678 HDMI. The OS will typically report all channel layouts
3679 that _can_ go over HDMI, even if the receiver does not
3680 support them. If a receiver gets an unsupported chan‐
3681 nel layout, random things can happen, such as dropping
3682 the additional channels, or adding noise.
3683 You are recommended to set an explicit whitelist of
3685 the layouts you want. For example, most A/V receivers
3686 connected via HDMI and that can do 7.1 would be
3687 served by: --audio-channels=7.1,5.1,stereo
3688 --audio-display=<no|embedded-first|external-first>
3690 Determines whether to display cover art when playing audio files
3691 and with what priority. It will display the first image found,
3692 and additional images are available as video tracks.
3693 no Disable display of video entirely when playing audio
3695 files.
3696 embedded-first
3698 Display embedded images and external cover art, giving
3699 priority to embedded images (default).
3700 external-first
3702 Display embedded images and external cover art, giving
3703 priority to external files.
3704 This option has no influence on files with normal video tracks.
3706 --audio-files=<files>
3708 Play audio from an external file while viewing a video.
3709 This is a path list option. See List Options for details.
3711 --audio-file=<file>
3713 CLI/config file only alias for --audio-files-append. Each use of
3714 this option will add a new audio track. The details are similar
3715 to how --sub-file works.
3716 --audio-format=<format>
3718 Select the sample format used for output from the audio filter
3719 layer to the sound card. The values that <format> can adopt are
3720 listed below in the description of the format audio filter.
3721 --audio-samplerate=<Hz>
3723 Select the output sample rate to be used (of course sound cards
3724 have limits on this). If the sample frequency selected is dif‐
3725 ferent from that of the current media, the lavrresample audio
3726 filter will be inserted into the audio filter layer to compen‐
3727 sate for the difference.
3728 --gapless-audio=<no|yes|weak>
3730 Try to play consecutive audio files with no silence or disrup‐
3731 tion at the point of file change. Default: weak.
3732 no Disable gapless audio.
3734 yes The audio device is opened using parameters chosen for
3736 the first file played and is then kept open for gapless
3737 playback. This means that if the first file for example
3738 has a low sample rate, then the following files may get
3739 resampled to the same low sample rate, resulting in re‐
3740 duced sound quality. If you play files with different pa‐
3741 rameters, consider using options such as --audio-sampler‐
3742 ate and --audio-format to explicitly select what the
3743 shared output format will be.
3744 weak Normally, the audio device is kept open (using the format
3746 it was first initialized with). If the audio format the
3747 decoder output changes, the audio device is closed and
3748 reopened. This means that you will normally get gapless
3749 audio with files that were encoded using the same set‐
3750 tings, but might not be gapless in other cases. The ex‐
3751 act conditions under which the audio device is kept open
3752 is an implementation detail, and can change from version
3753 to version. Currently, the device is kept even if the
3754 sample format changes, but the sample formats are con‐
3755 vertible. If video is still going on when there is still
3756 audio, trying to use gapless is also explicitly given up.
3757 NOTE:
3759 This feature is implemented in a simple manner and relies on
3760 audio output device buffering to continue playback while mov‐
3761 ing from one file to another. If playback of the new file
3762 starts slowly, for example because it is played from a remote
3763 network location or because you have specified cache settings
3764 that require time for the initial cache fill, then the
3765 buffered audio may run out before playback of the new file
3766 can start.
3767 --initial-audio-sync, --no-initial-audio-sync
3769 When starting a video file or after events such as seeking, mpv
3770 will by default modify the audio stream to make it start from
3771 the same timestamp as video, by either inserting silence at the
3772 start or cutting away the first samples. Disabling this option
3773 makes the player behave like older mpv versions did: video and
3774 audio are both started immediately even if their start time‐
3775 stamps differ, and then video timing is gradually adjusted if
3776 necessary to reach correct synchronization later.
3777 --volume-max=<100.0-1000.0>, --softvol-max=<...>
3779 Set the maximum amplification level in percent (default: 130). A
3780 value of 130 will allow you to adjust the volume up to about
3781 double the normal level.
3782 --softvol-max is a deprecated alias and should not be used.
3784 --audio-file-auto=<no|exact|fuzzy|all>, --no-audio-file-auto
3786 Load additional audio files matching the video filename. The pa‐
3787 rameter specifies how external audio files are matched.
3788 no Don't automatically load external audio files (default).
3790 exact Load the media filename with audio file extension.
3792 fuzzy Load all audio files containing the media filename.
3794 all Load all audio files in the current and --au‐
3796 dio-file-paths directories.
3797 --audio-file-paths=<path1:path2:...>
3799 Equivalent to --sub-file-paths option, but for auto-loaded audio
3800 files.
3801 This is a path list option. See List Options for details.
3803 --audio-client-name=<name>
3805 The application name the player reports to the audio API. Can be
3806 useful if you want to force a different audio profile (e.g. with
3807 PulseAudio), or to set your own application name when using
3808 libmpv.
3809 --audio-buffer=<seconds>
3811 Set the audio output minimum buffer. The audio device might ac‐
3812 tually create a larger buffer if it pleases. If the device cre‐
3813 ates a smaller buffer, additional audio is buffered in an addi‐
3814 tional software buffer.
3815 Making this larger will make soft-volume and other filters react
3817 slower, introduce additional issues on playback speed change,
3818 and block the player on audio format changes. A smaller buffer
3819 might lead to audio dropouts.
3820 This option should be used for testing only. If a non-default
3822 value helps significantly, the mpv developers should be con‐
3823 tacted.
3824 Default: 0.2 (200 ms).
3826 --audio-stream-silence=<yes|no>
3828 Cash-grab consumer audio hardware (such as A/V receivers) often
3829 ignore initial audio sent over HDMI. This can happen every time
3830 audio over HDMI is stopped and resumed. In order to compensate
3831 for this, you can enable this option to not to stop and restart
3832 audio on seeks, and fill the gaps with silence. Likewise, when
3833 pausing playback, audio is not stopped, and silence is played
3834 while paused. Note that if no audio track is selected, the audio
3835 device will still be closed immediately.
3836 Not all AOs support this.
3838 Warning
3840 This modifies certain subtle player behavior, like
3842 A/V-sync and underrun handling. Enabling this option
3843 is strongly discouraged.
3844 --audio-wait-open=<secs>
3846 This makes sense for use with --audio-stream-silence=yes. If
3847 this option is given, the player will wait for the given amount
3848 of seconds after opening the audio device before sending actual
3849 audio data to it. Useful if your expensive hardware discards the
3850 first 1 or 2 seconds of audio data sent to it. If --au‐
3851 dio-stream-silence=yes is not set, this option will likely just
3852 waste time.
3853 Subtitles
3855 NOTE:
3856 Changing styling and position does not work with all subtitles. Im‐
3857 age-based subtitles (DVD, Bluray/PGS, DVB) cannot changed for funda‐
3858 mental reasons. Subtitles in ASS format are normally not changed
3859 intentionally, but overriding them can be controlled with
3860 --sub-ass-override.
3861 Previously some options working on text subtitles were called
3863 --sub-text-*, they are now named --sub-*, and those specifically for
3864 ASS have been renamed from --ass-* to --sub-ass-*. They are now all
3865 in this section.
3866 --sub-demuxer=<[+]name>
3868 Force subtitle demuxer type for --sub-file. Give the demuxer
3869 name as printed by --sub-demuxer=help.
3870 --sub-delay=<sec>
3872 Delays subtitles by <sec> seconds. Can be negative.
3873 --sub-files=<file-list>, --sub-file=<filename>
3875 Add a subtitle file to the list of external subtitles.
3876 If you use --sub-file only once, this subtitle file is displayed
3878 by default.
3879 If --sub-file is used multiple times, the subtitle to use can be
3881 switched at runtime by cycling subtitle tracks. It's possible to
3882 show two subtitles at once: use --sid to select the first subti‐
3883 tle index, and --secondary-sid to select the second index. (The
3884 index is printed on the terminal output after the --sid= in the
3885 list of streams.)
3886 --sub-files is a path list option (see List Options for de‐
3888 tails), and can take multiple file names separated by : (Unix)
3889 or ; (Windows), while --sub-file takes a single filename, but
3890 can be used multiple times to add multiple files. Technically,
3891 --sub-file is a CLI/config file only alias for --sub-files-ap‐
3892 pend.
3893 --secondary-sid=<ID|auto|no>
3895 Select a secondary subtitle stream. This is similar to --sid. If
3896 a secondary subtitle is selected, it will be rendered as topti‐
3897 tle (i.e. on the top of the screen) alongside the normal subti‐
3898 tle, and provides a way to render two subtitles at once.
3899 There are some caveats associated with this feature. For exam‐
3901 ple, bitmap subtitles will always be rendered in their usual po‐
3902 sition, so selecting a bitmap subtitle as secondary subtitle
3903 will result in overlapping subtitles. Secondary subtitles are
3904 never shown on the terminal if video is disabled.
3905 NOTE:
3907 Styling and interpretation of any formatting tags is disabled
3908 for the secondary subtitle. Internally, the same mechanism as
3909 --no-sub-ass is used to strip the styling.
3910 NOTE:
3912 If the main subtitle stream contains formatting tags which
3913 display the subtitle at the top of the screen, it will over‐
3914 lap with the secondary subtitle. To prevent this, you could
3915 use --no-sub-ass to disable styling in the main subtitle
3916 stream.
3917 --sub-scale=<0-100>
3919 Factor for the text subtitle font size (default: 1).
3920 NOTE:
3922 This affects ASS subtitles as well, and may lead to incorrect
3923 subtitle rendering. Use with care, or use --sub-font-size in‐
3924 stead.
3925 --sub-scale-by-window=<yes|no>
3927 Whether to scale subtitles with the window size (default: yes).
3928 If this is disabled, changing the window size won't change the
3929 subtitle font size.
3930 Like --sub-scale, this can break ASS subtitles.
3932 --sub-scale-with-window=<yes|no>
3934 Make the subtitle font size relative to the window, instead of
3935 the video. This is useful if you always want the same font
3936 size, even if the video doesn't cover the window fully, e.g. be‐
3937 cause screen aspect and window aspect mismatch (and the player
3938 adds black bars).
3939 Default: yes.
3941 This option is misnamed. The difference to the confusingly simi‐
3943 lar sounding option --sub-scale-by-window is that
3944 --sub-scale-with-window still scales with the approximate window
3945 size, while the other option disables this scaling.
3946 Affects plain text subtitles only (or ASS if --sub-ass-override
3948 is set high enough).
3949 --sub-ass-scale-with-window=<yes|no>
3951 Like --sub-scale-with-window, but affects subtitles in ASS for‐
3952 mat only. Like --sub-scale, this can break ASS subtitles.
3953 Default: no.
3955 --embeddedfonts=<yes|no>
3957 Use fonts embedded in Matroska container files and ASS scripts
3958 (default: yes). These fonts can be used for SSA/ASS subtitle
3959 rendering.
3960 --sub-pos=<0-150>
3962 Specify the position of subtitles on the screen. The value is
3963 the vertical position of the subtitle in % of the screen height.
3964 100 is the original position, which is often not the absolute
3965 bottom of the screen, but with some margin between the bottom
3966 and the subtitle. Values above 100 move the subtitle further
3967 down.
3968 Warning
3970 Text subtitles (as opposed to image subtitles) may be
3972 cut off if the value of the option is above 100. This
3973 is a libass restriction.
3974 This affects ASS subtitles as well, and may lead to
3976 incorrect subtitle rendering in addition to the prob‐
3977 lem above.
3978 Using --sub-margin-y can achieve this in a better way.
3980 --sub-speed=<0.1-10.0>
3982 Multiply the subtitle event timestamps with the given value. Can
3983 be used to fix the playback speed for frame-based subtitle for‐
3984 mats. Affects text subtitles only.
3985 Example
3987 --sub-speed=25/23.976 plays frame based subtitles
3989 which have been loaded assuming a framerate of 23.976
3990 at 25 FPS.
3991 --sub-ass-force-style=<[Style.]Param=Value[,...]>
3993 Override some style or script info parameters.
3994 This is a string list option. See List Options for details.
3996 Examples
3998 • --sub-ass-force-style=FontName=Arial,Default.Bold=1
4000 • --sub-ass-force-style=PlayResY=768
4002 NOTE:
4004 Using this option may lead to incorrect subtitle rendering.
4005 --sub-ass-hinting=<none|light|normal|native>
4007 Set font hinting type. <type> can be:
4008 none no hinting (default)
4010 light FreeType autohinter, light mode
4012 normal FreeType autohinter, normal mode
4014 native font native hinter
4016 Warning
4018 Enabling hinting can lead to mispositioned text (in
4020 situations it's supposed to match up video back‐
4021 ground), or reduce the smoothness of animations with
4022 some badly authored ASS scripts. It is recommended to
4023 not use this option, unless really needed.
4024 --sub-ass-line-spacing=<value>
4026 Set line spacing value for SSA/ASS renderer.
4027 --sub-ass-shaper=<simple|complex>
4029 Set the text layout engine used by libass.
4030 simple uses Fribidi only, fast, doesn't render some languages
4032 correctly
4033 complex
4035 uses HarfBuzz, slower, wider language support
4036 complex is the default. If libass hasn't been compiled against
4038 HarfBuzz, libass silently reverts to simple.
4039 --sub-ass-styles=<filename>
4041 Load all SSA/ASS styles found in the specified file and use them
4042 for rendering text subtitles. The syntax of the file is exactly
4043 like the [V4 Styles] / [V4+ Styles] section of SSA/ASS.
4044 NOTE:
4046 Using this option may lead to incorrect subtitle rendering.
4047 --sub-ass-override=<yes|no|force|scale|strip>
4049 Control whether user style overrides should be applied. Note
4050 that all of these overrides try to be somewhat smart about fig‐
4051 uring out whether or not a subtitle is considered a "sign".
4052 no Render subtitles as specified by the subtitle scripts,
4054 without overrides.
4055 yes Apply all the --sub-ass-* style override options. Chang‐
4057 ing the default for any of these options can lead to in‐
4058 correct subtitle rendering (default).
4059 force Like yes, but also force all --sub-* options. Can break
4061 rendering easily.
4062 scale Like yes, but also apply --sub-scale.
4064 strip Radically strip all ASS tags and styles from the subti‐
4066 tle. This is equivalent to the old --no-ass /
4067 --no-sub-ass options.
4068 This also controls some bitmap subtitle overrides, as well as
4070 HTML tags in formats like SRT, despite the name of the option.
4071 --sub-ass-force-margins
4073 Enables placing toptitles and subtitles in black borders when
4074 they are available, if the subtitles are in the ASS format.
4075 Default: no.
4077 --sub-use-margins
4079 Enables placing toptitles and subtitles in black borders when
4080 they are available, if the subtitles are in a plain text format
4081 (or ASS if --sub-ass-override is set high enough).
4082 Default: yes.
4084 Renamed from --sub-ass-use-margins. To place ASS subtitles in
4086 the borders too (like the old option did), also add
4087 --sub-ass-force-margins.
4088 --sub-ass-vsfilter-aspect-compat=<yes|no>
4090 Stretch SSA/ASS subtitles when playing anamorphic videos for
4091 compatibility with traditional VSFilter behavior. This switch
4092 has no effect when the video is stored with square pixels.
4093 The renderer historically most commonly used for the SSA/ASS
4095 subtitle formats, VSFilter, had questionable behavior that re‐
4096 sulted in subtitles being stretched too if the video was stored
4097 in anamorphic format that required scaling for display. This
4098 behavior is usually undesirable and newer VSFilter versions may
4099 behave differently. However, many existing scripts compensate
4100 for the stretching by modifying things in the opposite direc‐
4101 tion. Thus, if such scripts are displayed "correctly", they
4102 will not appear as intended. This switch enables emulation of
4103 the old VSFilter behavior (undesirable but expected by many ex‐
4104 isting scripts).
4105 Enabled by default.
4107 --sub-ass-vsfilter-blur-compat=<yes|no>
4109 Scale \blur tags by video resolution instead of script resolu‐
4110 tion (enabled by default). This is bug in VSFilter, which ac‐
4111 cording to some, can't be fixed anymore in the name of compati‐
4112 bility.
4113 Note that this uses the actual video resolution for calculating
4115 the offset scale factor, not what the video filter chain or the
4116 video output use.
4117 --sub-ass-vsfilter-color-compat=<basic|full|force-601|no>
4119 Mangle colors like (xy-)vsfilter do (default: basic). Histori‐
4120 cally, VSFilter was not color space aware. This was no problem
4121 as long as the color space used for SD video (BT.601) was used.
4122 But when everything switched to HD (BT.709), VSFilter was still
4123 converting RGB colors to BT.601, rendered them into the video
4124 frame, and handled the frame to the video output, which would
4125 use BT.709 for conversion to RGB. The result were mangled subti‐
4126 tle colors. Later on, bad hacks were added on top of the ASS
4127 format to control how colors are to be mangled.
4128 basic Handle only BT.601->BT.709 mangling, if the subtitles
4130 seem to indicate that this is required (default).
4131 full Handle the full YCbCr Matrix header with all video color
4133 spaces supported by libass and mpv. This might lead to
4134 bad breakages in corner cases and is not strictly needed
4135 for compatibility (hopefully), which is why this is not
4136 default.
4137 force-601
4139 Force BT.601->BT.709 mangling, regardless of subtitle
4140 headers or video color space.
4141 no Disable color mangling completely. All colors are RGB.
4143 Choosing anything other than no will make the subtitle color de‐
4145 pend on the video color space, and it's for example in theory
4146 not possible to reuse a subtitle script with another video file.
4147 The --sub-ass-override option doesn't affect how this option is
4148 interpreted.
4149 --stretch-dvd-subs=<yes|no>
4151 Stretch DVD subtitles when playing anamorphic videos for better
4152 looking fonts on badly mastered DVDs. This switch has no effect
4153 when the video is stored with square pixels - which for DVD in‐
4154 put cannot be the case though.
4155 Many studios tend to use bitmap fonts designed for square pixels
4157 when authoring DVDs, causing the fonts to look stretched on
4158 playback on DVD players. This option fixes them, however at the
4159 price of possibly misaligning some subtitles (e.g. sign transla‐
4160 tions).
4161 Disabled by default.
4163 --stretch-image-subs-to-screen=<yes|no>
4165 Stretch DVD and other image subtitles to the screen, ignoring
4166 the video margins. This has a similar effect as --sub-use-mar‐
4167 gins for text subtitles, except that the text itself will be
4168 stretched, not only just repositioned. (At least in general it
4169 is unavoidable, as an image bitmap can in theory consist of a
4170 single bitmap covering the whole screen, and the player won't
4171 know where exactly the text parts are located.)
4172 This option does not display subtitles correctly. Use with care.
4174 Disabled by default.
4176 --image-subs-video-resolution=<yes|no>
4178 Override the image subtitle resolution with the video resolution
4179 (default: no). Normally, the subtitle canvas is fit into the
4180 video canvas (e.g. letterboxed). Setting this option uses the
4181 video size as subtitle canvas size. Can be useful to test broken
4182 subtitles, which often happen when the video was trancoded,
4183 while attempting to keep the old subtitles.
4184 --sub-ass, --no-sub-ass
4186 Render ASS subtitles natively (enabled by default).
4187 NOTE:
4189 This has been deprecated by --sub-ass-override=strip. You
4190 also may need --embeddedfonts=no to get the same behavior.
4191 Also, using --sub-ass-override=style should give better re‐
4192 sults without breaking subtitles too much.
4193 If --no-sub-ass is specified, all tags and style declarations
4195 are stripped and ignored on display. The subtitle renderer uses
4196 the font style as specified by the --sub- options instead.
4197 NOTE:
4199 Using --no-sub-ass may lead to incorrect or completely broken
4200 rendering of ASS/SSA subtitles. It can sometimes be useful to
4201 forcibly override the styling of ASS subtitles, but should be
4202 avoided in general.
4203 --sub-auto=<no|exact|fuzzy|all>, --no-sub-auto
4205 Load additional subtitle files matching the video filename. The
4206 parameter specifies how external subtitle files are matched. ex‐
4207 act is enabled by default.
4208 no Don't automatically load external subtitle files.
4210 exact Load the media filename with subtitle file extension and
4212 possibly language suffixes (default).
4213 fuzzy Load all subs containing the media filename.
4215 all Load all subs in the current and --sub-file-paths direc‐
4217 tories.
4218 --sub-codepage=<codepage>
4220 You can use this option to specify the subtitle codepage.
4221 uchardet will be used to guess the charset. (If mpv was not com‐
4222 piled with uchardet, then utf-8 is the effective default.)
4223 The default value for this option is auto, which enables autode‐
4225 tection.
4226 The following steps are taken to determine the final codepage,
4228 in order:
4229 • if the specific codepage has a +, use that codepage
4231 • if the data looks like UTF-8, assume it is UTF-8
4233 • if --sub-codepage is set to a specific codepage, use that
4235 • run uchardet, and if successful, use that
4237 • otherwise, use UTF-8-BROKEN
4239 Examples
4241 • --sub-codepage=latin2 Use Latin 2 if input is not UTF-8.
4243 • --sub-codepage=+cp1250 Always force recoding to cp1250.
4245 The pseudo codepage UTF-8-BROKEN is used internally. If it's
4247 set, subtitles are interpreted as UTF-8 with "Latin 1" as fall‐
4248 back for bytes which are not valid UTF-8 sequences. iconv is
4249 never involved in this mode.
4250 This option changed in mpv 0.23.0. Support for the old syntax
4252 was fully removed in mpv 0.24.0.
4253 NOTE:
4255 This works for text subtitle files only. Other types of sub‐
4256 titles (in particular subtitles in mkv files) are always as‐
4257 sumed to be UTF-8.
4258 --sub-fix-timing=<yes|no>
4260 Adjust subtitle timing is to remove minor gaps or overlaps be‐
4261 tween subtitles (if the difference is smaller than 210 ms, the
4262 gap or overlap is removed).
4263 --sub-forced-only=<auto|yes|no>
4265 Display only forced subtitles for the DVD subtitle stream se‐
4266 lected by e.g. --slang (default: auto). When set to auto, en‐
4267 abled when the --subs-with-matching-audio option is on and a
4268 non-forced stream is selected. Enabling this will hide all sub‐
4269 titles in streams that don't make a distinction between forced
4270 and unforced events within a stream.
4271 --sub-fps=<rate>
4273 Specify the framerate of the subtitle file (default: video fps).
4274 Affects text subtitles only.
4275 NOTE:
4277 <rate> > video fps speeds the subtitles up for frame-based
4278 subtitle files and slows them down for time-based ones.
4279 See also: --sub-speed.
4281 --sub-gauss=<0.0-3.0>
4283 Apply Gaussian blur to image subtitles (default: 0). This can
4284 help to make pixelated DVD/Vobsubs look nicer. A value other
4285 than 0 also switches to software subtitle scaling. Might be
4286 slow.
4287 NOTE:
4289 Never applied to text subtitles.
4290 --sub-gray
4292 Convert image subtitles to grayscale. Can help to make yellow
4293 DVD/Vobsubs look nicer.
4294 NOTE:
4296 Never applied to text subtitles.
4297 --sub-paths=<path1:path2:...>
4299 Deprecated, use --sub-file-paths.
4300 --sub-file-paths=<path-list>
4302 Specify extra directories to search for subtitles matching the
4303 video. Multiple directories can be separated by ":" (";" on
4304 Windows). Paths can be relative or absolute. Relative paths are
4305 interpreted relative to video file directory. If the file is a
4306 URL, only absolute paths and sub configuration subdirectory will
4307 be scanned.
4308 Example
4310 Assuming that /path/to/video/video.avi is played and
4312 --sub-file-paths=sub:subtitles is specified, mpv
4313 searches for subtitle files in these directories:
4314 • /path/to/video/
4316 • /path/to/video/sub/
4318 • /path/to/video/subtitles/
4320 • the sub configuration subdirectory (usually ~/.con‐
4322 fig/mpv/sub/)
4323 This is a path list option. See List Options for details.
4325 --sub-visibility, --no-sub-visibility
4327 Can be used to disable display of subtitles, but still select
4328 and decode them.
4329 --secondary-sub-visibility, --no-secondary-sub-visibility
4331 Can be used to disable display of secondary subtitles, but still
4332 select and decode them.
4333 --sub-clear-on-seek
4335 (Obscure, rarely useful.) Can be used to play broken mkv files
4336 with duplicate ReadOrder fields. ReadOrder is the first field in
4337 a Matroska-style ASS subtitle packets. It should be unique, and
4338 libass uses it for fast elimination of duplicates. This option
4339 disables caching of subtitles across seeks, so after a seek
4340 libass can't eliminate subtitle packets with the same ReadOrder
4341 as earlier packets.
4342 --teletext-page=<1-999>
4344 This works for dvb_teletext subtitle streams, and if FFmpeg has
4345 been compiled with support for it.
4346 --sub-past-video-end
4348 After the last frame of video, if this option is enabled, subti‐
4349 tles will continue to update based on audio timestamps. Other‐
4350 wise, the subtitles for the last video frame will stay onscreen.
4351 Default: disabled
4353 --sub-font=<name>
4355 Specify font to use for subtitles that do not themselves specify
4356 a particular font. The default is sans-serif.
4357 Examples
4359 • --sub-font='Bitstream Vera Sans'
4361 • --sub-font='Comic Sans MS'
4363 NOTE:
4365 The --sub-font option (and many other style related --sub-
4366 options) are ignored when ASS-subtitles are rendered, unless
4367 the --no-sub-ass option is specified.
4368 This used to support fontconfig patterns. Starting with
4370 libass 0.13.0, this stopped working.
4371 --sub-font-size=<size>
4373 Specify the sub font size. The unit is the size in scaled pixels
4374 at a window height of 720. The actual pixel size is scaled with
4375 the window height: if the window height is larger or smaller
4376 than 720, the actual size of the text increases or decreases as
4377 well.
4378 Default: 55.
4380 --sub-back-color=<color>
4382 See --sub-color. Color used for sub text background. You can use
4383 --sub-shadow-offset to change its size relative to the text.
4384 --sub-blur=<0..20.0>
4386 Gaussian blur factor. 0 means no blur applied (default).
4387 --sub-bold=<yes|no>
4389 Format text on bold.
4390 --sub-italic=<yes|no>
4392 Format text on italic.
4393 --sub-border-color=<color>
4395 See --sub-color. Color used for the sub font border.
4396 --sub-border-size=<size>
4398 Size of the sub font border in scaled pixels (see
4399 --sub-font-size for details). A value of 0 disables borders.
4400 Default: 3.
4402 --sub-color=<color>
4404 Specify the color used for unstyled text subtitles.
4405 The color is specified in the form r/g/b, where each color com‐
4407 ponent is specified as number in the range 0.0 to 1.0. It's also
4408 possible to specify the transparency by using r/g/b/a, where the
4409 alpha value 0 means fully transparent, and 1.0 means opaque. If
4410 the alpha component is not given, the color is 100% opaque.
4411 Passing a single number to the option sets the sub to gray, and
4413 the form gray/a lets you specify alpha additionally.
4414 Examples
4416 • --sub-color=1.0/0.0/0.0 set sub to opaque red
4418 • --sub-color=1.0/0.0/0.0/0.75 set sub to opaque red with 75%
4420 alpha
4421 • --sub-color=0.5/0.75 set sub to 50% gray with 75% alpha
4423 Alternatively, the color can be specified as a RGB hex triplet
4425 in the form #RRGGBB, where each 2-digit group expresses a color
4426 value in the range 0 (00) to 255 (FF). For example, #FF0000 is
4427 red. This is similar to web colors. Alpha is given with #AAR‐
4428 RGGBB.
4429 Examples
4431 • --sub-color='#FF0000' set sub to opaque red
4433 • --sub-color='#C0808080' set sub to 50% gray with 75% alpha
4435 --sub-margin-x=<size>
4437 Left and right screen margin for the subs in scaled pixels (see
4438 --sub-font-size for details).
4439 This option specifies the distance of the sub to the left, as
4441 well as at which distance from the right border long sub text
4442 will be broken.
4443 Default: 25.
4445 --sub-margin-y=<size>
4447 Top and bottom screen margin for the subs in scaled pixels (see
4448 --sub-font-size for details).
4449 This option specifies the vertical margins of unstyled text sub‐
4451 titles. If you just want to raise the vertical subtitle posi‐
4452 tion, use --sub-pos.
4453 Default: 22.
4455 --sub-align-x=<left|center|right>
4457 Control to which corner of the screen text subtitles should be
4458 aligned to (default: center).
4459 Never applied to ASS subtitles, except in --no-sub-ass mode.
4461 Likewise, this does not apply to image subtitles.
4462 --sub-align-y=<top|center|bottom>
4464 Vertical position (default: bottom). Details see --sub-align-x.
4465 --sub-justify=<auto|left|center|right>
4467 Control how multi line subs are justified irrespective of where
4468 they are aligned (default: auto which justifies as defined by
4469 --sub-align-x). Left justification is recommended to make the
4470 subs easier to read as it is easier for the eyes.
4471 --sub-ass-justify=<yes|no>
4473 Applies justification as defined by --sub-justify on ASS subti‐
4474 tles if --sub-ass-override is not set to no. Default: no.
4475 --sub-shadow-color=<color>
4477 See --sub-color. Color used for sub text shadow.
4478 NOTE:
4480 ignored when --sub-back-color is specified (or more exactly:
4481 when that option is not set to completely transparent).
4482 --sub-shadow-offset=<size>
4484 Displacement of the sub text shadow in scaled pixels (see
4485 --sub-font-size for details). A value of 0 disables shadows.
4486 Default: 0.
4488 --sub-spacing=<size>
4490 Horizontal sub font spacing in scaled pixels (see
4491 --sub-font-size for details). This value is added to the normal
4492 letter spacing. Negative values are allowed.
4493 Default: 0.
4495 --sub-filter-sdh=<yes|no>
4497 Applies filter removing subtitle additions for the deaf or
4498 hard-of-hearing (SDH). This is intended for English, but may in
4499 part work for other languages too. The intention is that it can
4500 be always enabled so may not remove all parts added. It removes
4501 speaker labels (like MAN:), upper case text in parentheses and
4502 any text in brackets.
4503 Default: no.
4505 --sub-filter-sdh-harder=<yes|no>
4507 Do harder SDH filtering (if enabled by --sub-filter-sdh). Will
4508 also remove speaker labels and text within parentheses using
4509 both lower and upper case letters.
4510 Default: no.
4512 --sub-filter-regex-...=...
4514 Set a list of regular expressions to match on text subtitles,
4515 and remove any lines that match (default: empty). This is a
4516 string list option. See List Options for details. Normally, you
4517 should use --sub-filter-regex-append=<regex>, where each option
4518 use will append a new regular expression, without having to
4519 fight escaping problems.
4520 List items are matched in order. If a regular expression
4522 matches, the process is stopped, and the subtitle line is dis‐
4523 carded. The text matched against is, by default, the Text field
4524 of ASS events (if the subtitle format is different, it is always
4525 converted). This may include formatting tags. Matching is
4526 case-insensitive, but how this is done depends on the libc, and
4527 most likely works in ASCII only. It does not work on bitmap/im‐
4528 age subtitles. Unavailable on inferior OSes (requires POSIX
4529 regex support).
4530 Example
4532 --sub-filter-regex-append=opensubtitles\.org filters
4534 some ads.
4535 Technically, using a list for matching is redundant, since you
4537 could just use a single combined regular expression. But it
4538 helps with diagnosis, ease of use, and temporarily disabling or
4539 enabling individual filters.
4540 WARNING:
4542 This is experimental. The semantics most likely will change,
4543 and if you use this, you should be prepared to update the op‐
4544 tion later. Ideas include replacing the regexes with a very
4545 primitive and small subset of sed, or some method to control
4546 case-sensitivity.
4547 --sub-filter-jsre-...=...
4549 Same as --sub-filter-regex but with JavaScript regular expres‐
4550 sions. Shares/affected-by all --sub-filter-regex-* control op‐
4551 tions (see below), and also experimental. Requires only Java‐
4552 Script support.
4553 --sub-filter-regex-plain=<yes|no>
4555 Whether to first convert the ASS "Text" field to plain-text (de‐
4556 fault: no). This strips ASS tags and applies ASS directives,
4557 like \N to new-line. If the result is multi-line then the reg‐
4558 exp anchors ^ and $ match each line, but still any match dis‐
4559 cards all lines.
4560 --sub-filter-regex-warn=<yes|no>
4562 Log dropped lines with warning log level, instead of verbose
4563 (default: no). Helpful for testing.
4564 --sub-filter-regex-enable=<yes|no>
4566 Whether to enable regex filtering (default: yes). Note that if
4567 no regexes are added to the --sub-filter-regex list, setting
4568 this option to yes has no effect. It's meant to easily disable
4569 or enable filtering temporarily.
4570 --sub-create-cc-track=<yes|no>
4572 For every video stream, create a closed captions track (default:
4573 no). The only purpose is to make the track available for selec‐
4574 tion at the start of playback, instead of creating it lazily.
4575 This applies only to ATSC A53 Part 4 Closed Captions (displayed
4576 by mpv as subtitle tracks using the codec eia_608). The CC track
4577 is marked "default" and selected according to the normal subti‐
4578 tle track selection rules. You can then use --sid to explicitly
4579 select the correct track too.
4580 If the video stream contains no closed captions, or if no video
4582 is being decoded, the CC track will remain empty and will not
4583 show any text.
4584 --sub-font-provider=<auto|none|fontconfig>
4586 Which libass font provider backend to use (default: auto). auto
4587 will attempt to use the native font provider: fontconfig on
4588 Linux, CoreText on macOS, DirectWrite on Windows. fontconfig
4589 forces fontconfig, if libass was built with support (if not, it
4590 behaves like none).
4591 The none font provider effectively disables system fonts. It
4593 will still attempt to use embedded fonts (unless --embedded‐
4594 fonts=no is set; this is the same behavior as with all other
4595 font providers), subfont.ttf if provided, and fonts in the
4596 fonts sub-directory if provided. (The fallback is more strict
4597 than that of other font providers, and if a font name does not
4598 match, it may prefer not to render any text that uses the miss‐
4599 ing font.)
4600 Window
4602 --title=<string>
4603 Set the window title. This is used for the video window, and if
4604 possible, also sets the audio stream title.
4605 Properties are expanded. (See Property Expansion.)
4607 WARNING:
4609 There is a danger of this causing significant CPU usage, de‐
4610 pending on the properties used. Changing the window title is
4611 often a slow operation, and if the title changes every frame,
4612 playback can be ruined.
4613 --screen=<default|0-32>
4615 In multi-monitor configurations (i.e. a single desktop that
4616 spans across multiple displays), this option tells mpv which
4617 screen to display the video on.
4618 Note (X11)
4620 This option does not work properly with all window
4622 managers. In these cases, you can try to use --geome‐
4623 try to position the window explicitly. It's also pos‐
4624 sible that the window manager provides native features
4625 to control which screens application windows should
4626 use.
4627 See also --fs-screen.
4629 --screen-name=<string>
4631 In multi-monitor configurations, this option tells mpv which
4632 screen to display the video on based on the screen name from the
4633 video backend. The same caveats in the --screen option also ap‐
4634 ply here. This option is ignored and does nothing if --screen is
4635 explicitly set.
4636 --fullscreen, --fs
4638 Fullscreen playback.
4639 --fs-screen=<all|current|0-32>
4641 In multi-monitor configurations (i.e. a single desktop that
4642 spans across multiple displays), this option tells mpv which
4643 screen to go fullscreen to. If current is used mpv will fall‐
4644 back on what the user provided with the screen option.
4645 Note (X11)
4647 This option works properly only with window managers
4649 which understand the EWMH _NET_WM_FULLSCREEN_MONITORS
4650 hint.
4651 Note (macOS)
4653 all does not work on macOS and will behave like cur‐
4655 rent.
4656 See also --screen.
4658 --fs-screen-name=<string>
4660 In multi-monitor configurations, this option tells mpv which
4661 screen to go fullscreen to based on the screen name from the
4662 video backend. The same caveats in the --fs-screen option also
4663 apply here. This option is ignored and does nothing if
4664 --fs-screen is explicitly set.
4665 --keep-open=<yes|no|always>
4667 Do not terminate when playing or seeking beyond the end of the
4668 file, and there is no next file to be played (and --loop is not
4669 used). Instead, pause the player. When trying to seek beyond
4670 end of the file, the player will attempt to seek to the last
4671 frame.
4672 Normally, this will act like set pause yes on EOF, unless the
4674 --keep-open-pause=no option is set.
4675 The following arguments can be given:
4677 no If the current file ends, go to the next file or termi‐
4679 nate. (Default.)
4680 yes Don't terminate if the current file is the last playlist
4682 entry. Equivalent to --keep-open without arguments.
4683 always Like yes, but also applies to files before the last
4685 playlist entry. This means playback will never automati‐
4686 cally advance to the next file.
4687 NOTE:
4689 This option is not respected when using --frames. Explicitly
4690 skipping to the next file if the binding uses force will ter‐
4691 minate playback as well.
4692 Also, if errors or unusual circumstances happen, the player
4694 can quit anyway.
4695 Since mpv 0.6.0, this doesn't pause if there is a next file in
4697 the playlist, or the playlist is looped. Approximately, this
4698 will pause when the player would normally exit, but in practice
4699 there are corner cases in which this is not the case (e.g. mpv
4700 --keep-open file.mkv /dev/null will play file.mkv normally, then
4701 fail to open /dev/null, then exit). (In mpv 0.8.0, always was
4702 introduced, which restores the old behavior.)
4703 --keep-open-pause=<yes|no>
4705 If set to no, instead of pausing when --keep-open is active,
4706 just stop at end of file and continue playing forward when you
4707 seek backwards until end where it stops again. Default: yes.
4708 --image-display-duration=<seconds|inf>
4710 If the current file is an image, play the image for the given
4711 amount of seconds (default: 1). inf means the file is kept open
4712 forever (until the user stops playback manually).
4713 Unlike --keep-open, the player is not paused, but simply contin‐
4715 ues playback until the time has elapsed. (It should not use any
4716 resources during "playback".)
4717 This affects image files, which are defined as having only 1
4719 video frame and no audio. The player may recognize certain
4720 non-images as images, for example if --length is used to reduce
4721 the length to 1 frame, or if you seek to the last frame.
4722 This option does not affect the framerate used for mf:// or
4724 --merge-files. For that, use --mf-fps instead.
4725 Setting --image-display-duration hides the OSC and does not
4727 track playback time on the command-line output, and also does
4728 not duplicate the image frame when encoding. To force the player
4729 into "dumb mode" and actually count out seconds, or to duplicate
4730 the image when encoding, you need to use --demuxer=lavf --de‐
4731 muxer-lavf-o=loop=1, and use --length or --frames to stop after
4732 a particular time.
4733 --force-window=<yes|no|immediate>
4735 Create a video output window even if there is no video. This can
4736 be useful when pretending that mpv is a GUI application. Cur‐
4737 rently, the window always has the size 640x480, and is subject
4738 to --geometry, --autofit, and similar options.
4739 WARNING:
4741 The window is created only after initialization (to make sure
4742 default window placement still works if the video size is
4743 different from the --force-window default window size). This
4744 can be a problem if initialization doesn't work perfectly,
4745 such as when opening URLs with bad network connection, or
4746 opening broken video files. The immediate mode can be used to
4747 create the window always on program start, but this may cause
4748 other issues.
4749 --taskbar-progress, --no-taskbar-progress
4751 (Windows only) Enable/disable playback progress rendering in
4752 taskbar (Windows 7 and above).
4753 Enabled by default.
4755 --snap-window
4757 (Windows only) Snap the player window to screen edges.
4758 --ontop
4760 Makes the player window stay on top of other windows.
4761 On Windows, if combined with fullscreen mode, this causes mpv to
4763 be treated as exclusive fullscreen window that bypasses the
4764 Desktop Window Manager.
4765 --ontop-level=<window|system|desktop|level>
4767 (macOS only) Sets the level of an ontop window (default: win‐
4768 dow).
4769 window On top of all other windows.
4771 system On top of system elements like Taskbar, Menubar and Dock.
4773 desktop
4775 On top of the Dekstop behind windows and Desktop icons.
4776 level A level as integer.
4778 --focus-on-open, --no-focus-on-open
4780 (macOS only) Focus the video window on creation and makes it the
4781 front most window. This is on by default.
4782 --border, --no-border
4784 Play video with window border and decorations. Since this is on
4785 by default, use --no-border to disable the standard window deco‐
4786 rations.
4787 --on-all-workspaces
4789 (X11 and macOS only) Show the video window on all virtual desk‐
4790 tops.
4791 --geometry=<[W[xH]][+-x+-y][/WS]>, --geometry=<x:y>
4793 Adjust the initial window position or size. W and H set the win‐
4794 dow size in pixels. x and y set the window position, measured in
4795 pixels from the top-left corner of the screen to the top-left
4796 corner of the image being displayed. If a percentage sign (%) is
4797 given after the argument, it turns the value into a percentage
4798 of the screen size in that direction. Positions are specified
4799 similar to the standard X11 --geometry option format, in which
4800 e.g. +10-50 means "place 10 pixels from the left border and 50
4801 pixels from the lower border" and "--20+-10" means "place 20
4802 pixels beyond the right and 10 pixels beyond the top border". A
4803 trailing / followed by an integer denotes on which workspace
4804 (virtual desktop) the window should appear (X11 only).
4805 If an external window is specified using the --wid option, this
4807 option is ignored.
4808 The coordinates are relative to the screen given with --screen
4810 for the video output drivers that fully support --screen.
4811 NOTE:
4813 Generally only supported by GUI VOs. Ignored for encoding.
4814 Note (X11)
4816 This option does not work properly with all window
4818 managers.
4819 Examples
4821 50:40 Places the window at x=50, y=40.
4823 50%:50%
4825 Places the window in the middle of the screen.
4826 100%:100%
4828 Places the window at the bottom right corner of the
4829 screen.
4830 50% Sets the window width to half the screen width. Window
4832 height is set so that the window has the video aspect
4833 ratio.
4834 50%x50%
4836 Forces the window width and height to half the screen
4837 width and height. Will show black borders to compen‐
4838 sate for the video aspect ratio (with most VOs and
4839 without --no-keepaspect).
4840 50%+10+10/2
4842 Sets the window to half the screen widths, and posi‐
4843 tions it 10 pixels below/left of the top left corner
4844 of the screen, on the second workspace.
4845 See also --autofit and --autofit-larger for fitting the window
4847 into a given size without changing aspect ratio.
4848 --autofit=<[W[xH]]>
4850 Set the initial window size to a maximum size specified by WxH,
4851 without changing the window's aspect ratio. The size is measured
4852 in pixels, or if a number is followed by a percentage sign (%),
4853 in percents of the screen size.
4854 This option never changes the aspect ratio of the window. If the
4856 aspect ratio mismatches, the window's size is reduced until it
4857 fits into the specified size.
4858 Window position is not taken into account, nor is it modified by
4860 this option (the window manager still may place the window dif‐
4861 ferently depending on size). Use --geometry to change the window
4862 position. Its effects are applied after this option.
4863 See --geometry for details how this is handled with multi-moni‐
4865 tor setups.
4866 Use --autofit-larger instead if you just want to limit the maxi‐
4868 mum size of the window, rather than always forcing a window
4869 size.
4870 Use --geometry if you want to force both window width and height
4872 to a specific size.
4873 NOTE:
4875 Generally only supported by GUI VOs. Ignored for encoding.
4876 Examples
4878 70% Make the window width 70% of the screen size, keeping
4880 aspect ratio.
4881 1000 Set the window width to 1000 pixels, keeping aspect
4883 ratio.
4884 70%x60%
4886 Make the window as large as possible, without being
4887 wider than 70% of the screen width, or higher than 60%
4888 of the screen height.
4889 --autofit-larger=<[W[xH]]>
4891 This option behaves exactly like --autofit, except the window
4892 size is only changed if the window would be larger than the
4893 specified size.
4894 Example
4896 90%x80%
4898 If the video is larger than 90% of the screen width or
4899 80% of the screen height, make the window smaller un‐
4900 til either its width is 90% of the screen, or its
4901 height is 80% of the screen.
4902 --autofit-smaller=<[W[xH]]>
4904 This option behaves exactly like --autofit, except that it sets
4905 the minimum size of the window (just as --autofit-larger sets
4906 the maximum).
4907 Example
4909 500x500
4911 Make the window at least 500 pixels wide and 500 pix‐
4912 els high (depending on the video aspect ratio, the
4913 width or height will be larger than 500 in order to
4914 keep the aspect ratio the same).
4915 --window-scale=<factor>
4917 Resize the video window to a multiple (or fraction) of the video
4918 size. This option is applied before --autofit and other options
4919 are applied (so they override this option).
4920 For example, --window-scale=0.5 would show the window at half
4922 the video size.
4923 --window-minimized=<yes|no>
4925 Whether the video window is minimized or not. Setting this will
4926 minimize, or unminimize, the video window if the current VO sup‐
4927 ports it. Note that some VOs may support minimization while not
4928 supporting unminimization (eg: Wayland).
4929 Whether this option and --window-maximized work on program start
4931 or at runtime, and whether they're (at runtime) updated to re‐
4932 flect the actual window state, heavily depends on the VO and the
4933 windowing system. Some VOs simply do not implement them or parts
4934 of them, while other VOs may be restricted by the windowing sys‐
4935 tems (especially Wayland).
4936 --window-maximized=<yes|no>
4938 Whether the video window is maximized or not. Setting this will
4939 maximize, or unmaximize, the video window if the current VO sup‐
4940 ports it. See --window-minimized for further remarks.
4941 --cursor-autohide=<number|no|always>
4943 Make mouse cursor automatically hide after given number of mil‐
4944 liseconds. no will disable cursor autohide. always means the
4945 cursor will stay hidden.
4946 --cursor-autohide-fs-only
4948 If this option is given, the cursor is always visible in win‐
4949 dowed mode. In fullscreen mode, the cursor is shown or hidden
4950 according to --cursor-autohide.
4951 --no-fixed-vo, --fixed-vo
4953 --no-fixed-vo enforces closing and reopening the video window
4954 for multiple files (one (un)initialization for each file).
4955 --force-rgba-osd-rendering
4957 Change how some video outputs render the OSD and text subtitles.
4958 This does not change appearance of the subtitles and only has
4959 performance implications. For VOs which support native ASS ren‐
4960 dering (like gpu, vdpau, direct3d), this can be slightly faster
4961 or slower, depending on GPU drivers and hardware. For other VOs,
4962 this just makes rendering slower.
4963 --force-window-position
4965 Forcefully move mpv's video output window to default location
4966 whenever there is a change in video parameters, video stream or
4967 file. This used to be the default behavior. Currently only af‐
4968 fects X11 VOs.
4969 --no-keepaspect, --keepaspect
4971 --no-keepaspect will always stretch the video to window size,
4972 and will disable the window manager hints that force the window
4973 aspect ratio. (Ignored in fullscreen mode.)
4974 --no-keepaspect-window, --keepaspect-window
4976 --keepaspect-window (the default) will lock the window size to
4977 the video aspect. --no-keepaspect-window disables this behavior,
4978 and will instead add black bars if window aspect and video as‐
4979 pect mismatch. Whether this actually works depends on the VO
4980 backend. (Ignored in fullscreen mode.)
4981 --monitoraspect=<ratio>
4983 Set the aspect ratio of your monitor or TV screen. A value of 0
4984 disables a previous setting (e.g. in the config file). Overrides
4985 the --monitorpixelaspect setting if enabled.
4986 See also --monitorpixelaspect and --video-aspect-override.
4988 Examples
4990 • --monitoraspect=4:3 or --monitoraspect=1.3333
4992 • --monitoraspect=16:9 or --monitoraspect=1.7777
4994 --hidpi-window-scale, --no-hidpi-window-scale
4996 (macOS, Windows, X11, and Wayland only) Scale the window size
4997 according to the backing scale factor (default: yes). On regu‐
4998 lar HiDPI resolutions the window opens with double the size but
4999 appears as having the same size as on non-HiDPI resolutions.
5000 This is enabled by default on macOS.
5001 --native-fs, --no-native-fs
5003 (macOS only) Uses the native fullscreen mechanism of the OS (de‐
5004 fault: yes).
5005 --monitorpixelaspect=<ratio>
5007 Set the aspect of a single pixel of your monitor or TV screen
5008 (default: 1). A value of 1 means square pixels (correct for (al‐
5009 most?) all LCDs). See also --monitoraspect and --video-as‐
5010 pect-override.
5011 --stop-screensaver=<yes|no|always>
5013 Turns off the screensaver (or screen blanker and similar mecha‐
5014 nisms) at startup and turns it on again on exit (default: yes).
5015 When using yes, the screensaver will re-enable when playback is
5016 not active. always will always disable the screensaver. Note
5017 that stopping the screensaver is only possible if a video output
5018 is available (i.e. there is an open mpv window).
5019 This is not supported on all video outputs or platforms. Some‐
5021 times it is implemented, but does not work (especially with
5022 Linux "desktops"). Read the Disabling Screensaver section very
5023 carefully.
5024 --wid=<ID>
5026 This tells mpv to attach to an existing window. If a VO is se‐
5027 lected that supports this option, it will use that window for
5028 video output. mpv will scale the video to the size of this win‐
5029 dow, and will add black bars to compensate if the aspect ratio
5030 of the video is different.
5031 On X11, the ID is interpreted as a Window on X11. Unlike
5033 MPlayer/mplayer2, mpv always creates its own window, and sets
5034 the wid window as parent. The window will always be resized to
5035 cover the parent window fully. The value 0 is interpreted spe‐
5036 cially, and mpv will draw directly on the root window.
5037 On win32, the ID is interpreted as HWND. Pass it as value cast
5039 to intptr_t. mpv will create its own window, and set the wid
5040 window as parent, like with X11.
5041 On macOS/Cocoa, the ID is interpreted as NSView*. Pass it as
5043 value cast to intptr_t. mpv will create its own sub-view. Be‐
5044 cause macOS does not support window embedding of foreign pro‐
5045 cesses, this works only with libmpv, and will crash when used
5046 from the command line.
5047 On Android, the ID is interpreted as android.view.Surface. Pass
5049 it as a value cast to intptr_t. Use with --vo=mediacodec_embed
5050 and --hwdec=mediacodec for direct rendering using MediaCodec, or
5051 with --vo=gpu --gpu-context=android (with or without --hwdec=me‐
5052 diacodec).
5053 --no-window-dragging
5055 Don't move the window when clicking on it and moving the mouse
5056 pointer.
5057 --x11-name
5059 Set the window class name for X11-based video output methods.
5060 --x11-netwm=<yes|no|auto>
5062 (X11 only) Control the use of NetWM protocol features.
5063 This may or may not help with broken window managers. This pro‐
5065 vides some functionality that was implemented by the now removed
5066 --fstype option. Actually, it is not known to the developers to
5067 which degree this option was needed, so feedback is welcome.
5068 Specifically, yes will force use of NetWM fullscreen support,
5070 even if not advertised by the WM. This can be useful for WMs
5071 that are broken on purpose, like XMonad. (XMonad supposedly
5072 doesn't advertise fullscreen support, because Flash uses it. Ap‐
5073 parently, applications which want to use fullscreen anyway are
5074 supposed to either ignore the NetWM support hints, or provide a
5075 workaround. Shame on XMonad for deliberately breaking X proto‐
5076 cols (as if X isn't bad enough already).
5077 By default, NetWM support is autodetected (auto).
5079 This option might be removed in the future.
5081 --x11-bypass-compositor=<yes|no|fs-only|never>
5083 If set to yes, then ask the compositor to unredirect the mpv
5084 window (default: fs-only). This uses the _NET_WM_BYPASS_COMPOSI‐
5085 TOR hint.
5086 fs-only asks the window manager to disable the compositor only
5088 in fullscreen mode.
5089 no sets _NET_WM_BYPASS_COMPOSITOR to 0, which is the default
5091 value as declared by the EWMH specification, i.e. no change is
5092 done.
5093 never asks the window manager to never disable the compositor.
5095 --x11-present=<no|auto|yes>
5097 Whether or not to use presentation statistics from X11's presen‐
5098 tation extension (default: auto).
5099 mpv asks X11 for present events which it then may use for more
5101 accurate frame presentation. This only has an effect if
5102 --video-sync=display-... is being used.
5103 The auto option enumerates XRandr providers for autodetection.
5105 If amd, radeon, intel, or nouveau (the standard x86 Mesa driv‐
5106 ers) is found and nvidia is NOT found, presentation feedback is
5107 enabled. Other drivers are not assumed to work, so they are not
5108 enabled automatically.
5109 yes or no can still be passed regardless to enable/disable this
5111 mechanism in case there is good/bad behavior with whatever your
5112 combination of hardware/drivers/etc. happens to be.
5113 Disc Devices
5115 --cdrom-device=<path>
5116 Specify the CD-ROM device (default: /dev/cdrom).
5117 --dvd-device=<path>
5119 Specify the DVD device or .iso filename (default: /dev/dvd). You
5120 can also specify a directory that contains files previously
5121 copied directly from a DVD (with e.g. vobcopy).
5122 Example
5124 mpv dvd:// --dvd-device=/path/to/dvd/
5126 --bluray-device=<path>
5128 (Blu-ray only) Specify the Blu-ray disc location. Must be a di‐
5129 rectory with Blu-ray structure.
5130 Example
5132 mpv bd:// --bluray-device=/path/to/bd/
5134 --cdda-...
5136 These options can be used to tune the CD Audio reading feature
5137 of mpv.
5138 --cdda-speed=<value>
5140 Set CD spin speed.
5141 --cdda-paranoia=<0-2>
5143 Set paranoia level. Values other than 0 seem to break playback
5144 of anything but the first track.
5145 0 disable checking (default)
5147 1 overlap checking only
5149 2 full data correction and verification
5151 --cdda-sector-size=<value>
5153 Set atomic read size.
5154 --cdda-overlap=<value>
5156 Force minimum overlap search during verification to <value> sec‐
5157 tors.
5158 --cdda-toc-bias
5160 Assume that the beginning offset of track 1 as reported in the
5161 TOC will be addressed as LBA 0. Some discs need this for getting
5162 track boundaries correctly.
5163 --cdda-toc-offset=<value>
5165 Add <value> sectors to the values reported when addressing
5166 tracks. May be negative.
5167 --cdda-skip=<yes|no>
5169 (Never) accept imperfect data reconstruction.
5170 --cdda-cdtext=<yes|no>
5172 Print CD text. This is disabled by default, because it ruins
5173 performance with CD-ROM drives for unknown reasons.
5174 --dvd-speed=<speed>
5176 Try to limit DVD speed (default: 0, no change). DVD base speed
5177 is 1385 kB/s, so an 8x drive can read at speeds up to 11080
5178 kB/s. Slower speeds make the drive more quiet. For watching
5179 DVDs, 2700 kB/s should be quiet and fast enough. mpv resets the
5180 speed to the drive default value on close. Values of at least
5181 100 mean speed in kB/s. Values less than 100 mean multiples of
5182 1385 kB/s, i.e. --dvd-speed=8 selects 11080 kB/s.
5183 NOTE:
5185 You need write access to the DVD device to change the speed.
5186 --dvd-angle=<ID>
5188 Some DVDs contain scenes that can be viewed from multiple an‐
5189 gles. This option tells mpv which angle to use (default: 1).
5190 Equalizer
5192 --brightness=<-100-100>
5193 Adjust the brightness of the video signal (default: 0). Not sup‐
5194 ported by all video output drivers.
5195 --contrast=<-100-100>
5197 Adjust the contrast of the video signal (default: 0). Not sup‐
5198 ported by all video output drivers.
5199 --saturation=<-100-100>
5201 Adjust the saturation of the video signal (default: 0). You can
5202 get grayscale output with this option. Not supported by all
5203 video output drivers.
5204 --gamma=<-100-100>
5206 Adjust the gamma of the video signal (default: 0). Not supported
5207 by all video output drivers.
5208 --hue=<-100-100>
5210 Adjust the hue of the video signal (default: 0). You can get a
5211 colored negative of the image with this option. Not supported by
5212 all video output drivers.
5213 Demuxer
5215 --demuxer=<[+]name>
5216 Force demuxer type. Use a '+' before the name to force it; this
5217 will skip some checks. Give the demuxer name as printed by --de‐
5218 muxer=help.
5219 --demuxer-lavf-analyzeduration=<value>
5221 Maximum length in seconds to analyze the stream properties.
5222 --demuxer-lavf-probe-info=<yes|no|auto|nostreams>
5224 Whether to probe stream information (default: auto). Techni‐
5225 cally, this controls whether libavformat's avfor‐
5226 mat_find_stream_info() function is called. Usually it's safer to
5227 call it, but it can also make startup slower.
5228 The auto choice (the default) tries to skip this for a few
5230 know-safe whitelisted formats, while calling it for everything
5231 else.
5232 The nostreams choice only calls it if and only if the file seems
5234 to contain no streams after opening (helpful in cases when call‐
5235 ing the function is needed to detect streams at all, such as
5236 with FLV files).
5237 --demuxer-lavf-probescore=<1-100>
5239 Minimum required libavformat probe score. Lower values will re‐
5240 quire less data to be loaded (makes streams start faster), but
5241 makes file format detection less reliable. Can be used to force
5242 auto-detected libavformat demuxers, even if libavformat consid‐
5243 ers the detection not reliable enough. (Default: 26.)
5244 --demuxer-lavf-allow-mimetype=<yes|no>
5246 Allow deriving the format from the HTTP MIME type (default:
5247 yes). Set this to no in case playing things from HTTP mysteri‐
5248 ously fails, even though the same files work from local disk.
5249 This is default in order to reduce latency when opening HTTP
5251 streams.
5252 --demuxer-lavf-format=<name>
5254 Force a specific libavformat demuxer.
5255 --demuxer-lavf-hacks=<yes|no>
5257 By default, some formats will be handled differently from other
5258 formats by explicitly checking for them. Most of these compen‐
5259 sate for weird or imperfect behavior from libavformat demuxers.
5260 Passing no disables these. For debugging and testing only.
5261 --demuxer-lavf-o=<key>=<value>[,<key>=<value>[,...]]
5263 Pass AVOptions to libavformat demuxer.
5264 Note, a patch to make the o= unneeded and pass all unknown op‐
5266 tions through the AVOption system is welcome. A full list of
5267 AVOptions can be found in the FFmpeg manual. Note that some op‐
5268 tions may conflict with mpv options.
5269 This is a key/value list option. See List Options for details.
5271 Example
5273 --demuxer-lavf-o=fflags=+ignidx
5275 --demuxer-lavf-probesize=<value>
5277 Maximum amount of data to probe during the detection phase. In
5278 the case of MPEG-TS this value identifies the maximum number of
5279 TS packets to scan.
5280 --demuxer-lavf-buffersize=<value>
5282 Size of the stream read buffer allocated for libavformat in
5283 bytes (default: 32768). Lowering the size could lower latency.
5284 Note that libavformat might reallocate the buffer internally, or
5285 not fully use all of it.
5286 --demuxer-lavf-linearize-timestamps=<yes|no|auto>
5288 Attempt to linearize timestamp resets in demuxed streams (de‐
5289 fault: auto). This was tested only for single audio streams.
5290 It's unknown whether it works correctly for video (but likely
5291 won't). Note that the implementation is slightly incorrect ei‐
5292 ther way, and will introduce a discontinuity by about 1 codec
5293 frame size.
5294 The auto mode enables this for OGG audio stream. This covers the
5296 common and annoying case of OGG web radio streams. Some of these
5297 will reset timestamps to 0 every time a new song begins. This
5298 breaks the mpv seekable cache, which can't deal with timestamp
5299 resets. Note that FFmpeg/libavformat's seeking API can't deal
5300 with this either; it's likely that if this option breaks this
5301 even more, while if it's disabled, you can at least seek within
5302 the first song in the stream. Well, you won't get anything use‐
5303 ful either way if the seek is outside of mpv's cache.
5304 --demuxer-lavf-propagate-opts=<yes|no>
5306 Propagate FFmpeg-level options to recursively opened connections
5307 (default: yes). This is needed because FFmpeg will apply these
5308 settings to nested AVIO contexts automatically. On the other
5309 hand, this could break in certain situations - it's the FFmpeg
5310 API, you just can't win.
5311 This affects in particular the --timeout option and anything
5313 passed with --demuxer-lavf-o.
5314 If this option is deemed unnecessary at some point in the fu‐
5316 ture, it will be removed without notice.
5317 --demuxer-mkv-subtitle-preroll=<yes|index|no>, --mkv-subtitle-preroll
5319 Try harder to show embedded soft subtitles when seeking some‐
5320 where. Normally, it can happen that the subtitle at the seek
5321 target is not shown due to how some container file formats are
5322 designed. The subtitles appear only if seeking before or exactly
5323 to the position a subtitle first appears. To make this worse,
5324 subtitles are often timed to appear a very small amount before
5325 the associated video frame, so that seeking to the video frame
5326 typically does not demux the subtitle at that position.
5327 Enabling this option makes the demuxer start reading data a bit
5329 before the seek target, so that subtitles appear correctly. Note
5330 that this makes seeking slower, and is not guaranteed to always
5331 work. It only works if the subtitle is close enough to the seek
5332 target.
5333 Works with the internal Matroska demuxer only. Always enabled
5335 for absolute and hr-seeks, and this option changes behavior with
5336 relative or imprecise seeks only.
5337 You can use the --demuxer-mkv-subtitle-preroll-secs option to
5339 specify how much data the demuxer should pre-read at most in or‐
5340 der to find subtitle packets that may overlap. Setting this to 0
5341 will effectively disable this preroll mechanism. Setting a very
5342 large value can make seeking very slow, and an extremely large
5343 value would completely reread the entire file from start to seek
5344 target on every seek - seeking can become slower towards the end
5345 of the file. The details are messy, and the value is actually
5346 rounded down to the cluster with the previous video keyframe.
5347 Some files, especially files muxed with newer mkvmerge versions,
5349 have information embedded that can be used to determine what
5350 subtitle packets overlap with a seek target. In these cases, mpv
5351 will reduce the amount of data read to a minimum. (Although it
5352 will still read all data between the cluster that contains the
5353 first wanted subtitle packet, and the seek target.) If the index
5354 choice (which is the default) is specified, then prerolling will
5355 be done only if this information is actually available. If this
5356 method is used, the maximum amount of data to skip can be addi‐
5357 tionally controlled by --demuxer-mkv-subtitle-preroll-secs-index
5358 (it still uses the value of the option without -index if that is
5359 higher).
5360 See also --hr-seek-demuxer-offset option. This option can
5362 achieve a similar effect, but only if hr-seek is active. It
5363 works with any demuxer, but makes seeking much slower, as it has
5364 to decode audio and video data instead of just skipping over it.
5365 --mkv-subtitle-preroll is a deprecated alias.
5367 --demuxer-mkv-subtitle-preroll-secs=<value>
5369 See --demuxer-mkv-subtitle-preroll.
5370 --demuxer-mkv-subtitle-preroll-secs-index=<value>
5372 See --demuxer-mkv-subtitle-preroll.
5373 --demuxer-mkv-probe-start-time=<yes|no>
5375 Check the start time of Matroska files (default: yes). This sim‐
5376 ply reads the first cluster timestamps and assumes it is the
5377 start time. Technically, this also reads the first timestamp,
5378 which may increase latency by one frame (which may be relevant
5379 for live streams).
5380 --demuxer-mkv-probe-video-duration=<yes|no|full>
5382 When opening the file, seek to the end of it, and check what
5383 timestamp the last video packet has, and report that as file du‐
5384 ration. This is strictly for compatibility with Haali only. In
5385 this mode, it's possible that opening will be slower (especially
5386 when playing over http), or that behavior with broken files is
5387 much worse. So don't use this option.
5388 The yes mode merely uses the index and reads a small number of
5390 blocks from the end of the file. The full mode actually tra‐
5391 verses the entire file and can make a reliable estimate even
5392 without an index present (such as partial files).
5393 --demuxer-rawaudio-channels=<value>
5395 Number of channels (or channel layout) if --demuxer=rawaudio is
5396 used (default: stereo).
5397 --demuxer-rawaudio-format=<value>
5399 Sample format for --demuxer=rawaudio (default: s16le). Use
5400 --demuxer-rawaudio-format=help to get a list of all formats.
5401 --demuxer-rawaudio-rate=<value>
5403 Sample rate for --demuxer=rawaudio (default: 44 kHz).
5404 --demuxer-rawvideo-fps=<value>
5406 Rate in frames per second for --demuxer=rawvideo (default:
5407 25.0).
5408 --demuxer-rawvideo-w=<value>, --demuxer-rawvideo-h=<value>
5410 Image dimension in pixels for --demuxer=rawvideo.
5411 Example
5413 Play a raw YUV sample:
5415 mpv sample-720x576.yuv --demuxer=rawvideo \
5417 --demuxer-rawvideo-w=720 --demuxer-rawvideo-h=576
5418 --demuxer-rawvideo-format=<value>
5420 Color space (fourcc) in hex or string for --demuxer=rawvideo
5421 (default: YV12).
5422 --demuxer-rawvideo-mp-format=<value>
5424 Color space by internal video format for --demuxer=rawvideo. Use
5425 --demuxer-rawvideo-mp-format=help for a list of possible for‐
5426 mats.
5427 --demuxer-rawvideo-codec=<value>
5429 Set the video codec instead of selecting the rawvideo codec when
5430 using --demuxer=rawvideo. This uses the same values as codec
5431 names in --vd (but it does not accept decoder names).
5432 --demuxer-rawvideo-size=<value>
5434 Frame size in bytes when using --demuxer=rawvideo.
5435 --demuxer-cue-codepage=<codepage>
5437 Specify the CUE sheet codepage. (See --sub-codepage for de‐
5438 tails.)
5439 --demuxer-max-bytes=<bytesize>
5441 This controls how much the demuxer is allowed to buffer ahead.
5442 The demuxer will normally try to read ahead as much as neces‐
5443 sary, or as much is requested with --demuxer-readahead-secs. The
5444 option can be used to restrict the maximum readahead. This lim‐
5445 its excessive readahead in case of broken files or desynced
5446 playback. The demuxer will stop reading additional packets as
5447 soon as one of the limits is reached. (The limits still can be
5448 slightly overstepped due to technical reasons.)
5449 Set these limits higher if you get a packet queue overflow warn‐
5451 ing, and you think normal playback would be possible with a
5452 larger packet queue.
5453 See --list-options for defaults and value range. <bytesize> op‐
5455 tions accept suffixes such as KiB and MiB.
5456 --demuxer-max-back-bytes=<bytesize>
5458 This controls how much past data the demuxer is allowed to pre‐
5459 serve. This is useful only if the cache is enabled.
5460 Unlike the forward cache, there is no control how many seconds
5462 are actually cached - it will simply use as much memory this op‐
5463 tion allows. Setting this option to 0 will strictly disable any
5464 back buffer, but this will lead to the situation that the for‐
5465 ward seek range starts after the current playback position (as
5466 it removes past packets that are seek points).
5467 If the end of the file is reached, the remaining unused forward
5469 buffer space is "donated" to the backbuffer (unless the back‐
5470 buffer size is set to 0, or --demuxer-donate-buffer is set to
5471 no). This still limits the total cache usage to the sum of the
5472 forward and backward cache, and effectively makes better use of
5473 the total allowed memory budget. (The opposite does not happen:
5474 free backward buffer is never "donated" to the forward buffer.)
5475 Keep in mind that other buffers in the player (like decoders)
5477 will cause the demuxer to cache "future" frames in the back buf‐
5478 fer, which can skew the impression about how much data the back‐
5479 buffer contains.
5480 See --list-options for defaults and value range.
5482 --demuxer-donate-buffer=<yes|no>
5484 Whether to let the back buffer use part of the forward buffer
5485 (default: yes). If set to yes, the "donation" behavior de‐
5486 scribed in the option description for --demuxer-max-back-bytes
5487 is enabled. This means the back buffer may use up memory up to
5488 the sum of the forward and back buffer options, minus the active
5489 size of the forward buffer. If set to no, the options strictly
5490 limit the forward and back buffer sizes separately.
5491 Note that if the end of the file is reached, the buffered data
5493 stays the same, even if you seek back within the cache. This is
5494 because the back buffer is only reduced when new data is read.
5495 --demuxer-seekable-cache=<yes|no|auto>
5497 Debugging option to control whether seeking can use the demuxer
5498 cache (default: auto). Normally you don't ever need to set this;
5499 the default auto does the right thing and enables cache seeking
5500 it if --cache is set to yes (or is implied yes if --cache=auto).
5501 If enabled, short seek offsets will not trigger a low level de‐
5503 muxer seek (which means for example that slow network round
5504 trips or FFmpeg seek bugs can be avoided). If a seek cannot hap‐
5505 pen within the cached range, a low level seek will be triggered.
5506 Seeking outside of the cache will start a new cached range, but
5507 can discard the old cache range if the demuxer exhibits certain
5508 unsupported behavior.
5509 The special value auto means yes in the same situation as
5511 --cache-secs is used (i.e. when the stream appears to be a net‐
5512 work stream or the stream cache is enabled).
5513 --demuxer-force-retry-on-eof=<yes|no>
5515 Whether to keep retrying making the demuxer thread read more
5516 packets each time the decoder dequeues a packet, even if the end
5517 of the file was reached (default: no). This does not really make
5518 sense, but was the default behavior in mpv 0.32.0 and earlier.
5519 This option will be silently removed after a while, and exists
5520 only to restore the old behavior for testing, in case this was
5521 actually needed somewhere. This does _not_ help with files that
5522 are being appended to (in these cases use appending://, or dis‐
5523 able the cache).
5524 --demuxer-thread=<yes|no>
5526 Run the demuxer in a separate thread, and let it prefetch a cer‐
5527 tain amount of packets (default: yes). Having this enabled leads
5528 to smoother playback, enables features like prefetching, and
5529 prevents that stuck network freezes the player. On the other
5530 hand, it can add overhead, or the background prefetching can hog
5531 CPU resources.
5532 Disabling this option is not recommended. Use it for debugging
5534 only.
5535 --demuxer-termination-timeout=<seconds>
5537 Number of seconds the player should wait to shutdown the demuxer
5538 (default: 0.1). The player will wait up to this much time before
5539 it closes the stream layer forcefully. Forceful closing usually
5540 means the network I/O is given no chance to close its connec‐
5541 tions gracefully (of course the OS can still close TCP connec‐
5542 tions properly), and might result in annoying messages being
5543 logged, and in some cases, confused remote servers.
5544 This timeout is usually only applied when loading has finished
5546 properly. If loading is aborted by the user, or in some corner
5547 cases like removing external tracks sourced from network during
5548 playback, forceful closing is always used.
5549 --demuxer-readahead-secs=<seconds>
5551 If --demuxer-thread is enabled, this controls how much the de‐
5552 muxer should buffer ahead in seconds (default: 1). As long as no
5553 packet has a timestamp difference higher than the readahead
5554 amount relative to the last packet returned to the decoder, the
5555 demuxer keeps reading.
5556 Note that enabling the cache (such as --cache=yes, or if the in‐
5558 put is considered a network stream, and --cache=auto is used),
5559 this option is mostly ignored. (--cache-secs will override this.
5560 Technically, the maximum of both options is used.)
5561 The main purpose of this option is to limit the readhead for lo‐
5563 cal playback, since a large readahead value is not overly useful
5564 in this case.
5565 (This value tends to be fuzzy, because many file formats don't
5567 store linear timestamps.)
5568 --prefetch-playlist=<yes|no>
5570 Prefetch next playlist entry while playback of the current entry
5571 is ending (default: no).
5572 This does not prefill the cache with the video data of the next
5574 URL. Prefetching video data is supported only for the current
5575 playlist entry, and depends on the demuxer cache settings (on by
5576 default). This merely opens the URL of the next playlist entry
5577 as soon the current URL is fully read.
5578 This does not work with URLs resolved by the youtube-dl wrapper,
5580 and it won't.
5581 This can give subtly wrong results if per-file options are used,
5583 or if options are changed in the time window between prefetching
5584 start and next file played.
5585 This can occasionally make wrong prefetching decisions. For ex‐
5587 ample, it can't predict whether you go backwards in the
5588 playlist, and assumes you won't edit the playlist.
5589 Highly experimental.
5591 --force-seekable=<yes|no>
5593 If the player thinks that the media is not seekable (e.g. play‐
5594 ing from a pipe, or it's an http stream with a server that
5595 doesn't support range requests), seeking will be disabled. This
5596 option can forcibly enable it. For seeks within the cache,
5597 there's a good chance of success.
5598 --demuxer-cache-wait=<yes|no>
5600 Before starting playback, read data until either the end of the
5601 file was reached, or the demuxer cache has reached maximum ca‐
5602 pacity. Only once this is done, playback starts. This intention‐
5603 ally happens before the initial seek triggered with --start.
5604 This does not change any runtime behavior after the initial
5605 caching. This option is useless if the file cannot be cached
5606 completely.
5607 --rar-list-all-volumes=<yes|no>
5609 When opening multi-volume rar files, open all volumes to create
5610 a full list of contained files (default: no). If disabled, only
5611 the archive entries whose headers are located within the first
5612 volume are listed (and thus played when opening a .rar file with
5613 mpv). Doing so speeds up opening, and the typical idiotic
5614 use-case of playing uncompressed multi-volume rar files that
5615 contain a single media file is made faster.
5616 Opening is still slow, because for unknown, idiotic, and unnec‐
5618 essary reasons libarchive opens all volumes anyway when playing
5619 the main file, even though mpv iterated no archive entries yet.
5620 Input
5622 --native-keyrepeat
5623 Use system settings for keyrepeat delay and rate, instead of
5624 --input-ar-delay and --input-ar-rate. (Whether this applies de‐
5625 pends on the VO backend and how it handles keyboard input. Does
5626 not apply to terminal input.)
5627 --input-ar-delay
5629 Delay in milliseconds before we start to autorepeat a key (0 to
5630 disable).
5631 --input-ar-rate
5633 Number of key presses to generate per second on autorepeat.
5634 --input-conf=<filename>
5636 Specify input configuration file other than the default location
5637 in the mpv configuration directory (usually ~/.config/mpv/in‐
5638 put.conf).
5639 --no-input-default-bindings
5641 Disable default-level ("weak") key bindings. These are bindings
5642 which config files like input.conf can override. It currently
5643 affects the builtin key bindings, and keys which scripts bind
5644 using mp.add_key_binding (but not mp.add_forced_key_binding be‐
5645 cause this overrides input.conf).
5646 --no-input-builtin-bindings
5648 Disable loading of built-in key bindings during start-up. This
5649 option is applied only during (lib)mpv initialization, and if
5650 used then it will not be not possible to enable them later. May
5651 be useful to libmpv clients.
5652 --input-cmdlist
5654 Prints all commands that can be bound to keys.
5655 --input-doubleclick-time=<milliseconds>
5657 Time in milliseconds to recognize two consecutive button presses
5658 as a double-click (default: 300).
5659 --input-keylist
5661 Prints all keys that can be bound to commands.
5662 --input-key-fifo-size=<2-65000>
5664 Specify the size of the FIFO that buffers key events (default:
5665 7). If it is too small, some events may be lost. The main disad‐
5666 vantage of setting it to a very large value is that if you hold
5667 down a key triggering some particularly slow command then the
5668 player may be unresponsive while it processes all the queued
5669 commands.
5670 --input-test
5672 Input test mode. Instead of executing commands on key presses,
5673 mpv will show the keys and the bound commands on the OSD. Has to
5674 be used with a dummy video, and the normal ways to quit the
5675 player will not work (key bindings that normally quit will be
5676 shown on OSD only, just like any other binding). See INPUT.CONF.
5677 --input-terminal, --no-input-terminal
5679 --no-input-terminal prevents the player from reading key events
5680 from standard input. Useful when reading data from standard in‐
5681 put. This is automatically enabled when - is found on the com‐
5682 mand line. There are situations where you have to set it manu‐
5683 ally, e.g. if you open /dev/stdin (or the equivalent on your
5684 system), use stdin in a playlist or intend to read from stdin
5685 later on via the loadfile or loadlist input commands.
5686 --input-ipc-server=<filename>
5688 Enable the IPC support and create the listening socket at the
5689 given path.
5690 On Linux and Unix, the given path is a regular filesystem path.
5692 On Windows, named pipes are used, so the path refers to the pipe
5693 namespace (\\.\pipe\<name>). If the \\.\pipe\ prefix is missing,
5694 mpv will add it automatically before creating the pipe, so --in‐
5695 put-ipc-server=/tmp/mpv-socket and --in‐
5696 put-ipc-server=\\.\pipe\tmp\mpv-socket are equivalent for IPC on
5697 Windows.
5698 See JSON IPC for details.
5700 --input-ipc-client=fd://<N>
5702 Connect a single IPC client to the given FD. This is somewhat
5703 similar to --input-ipc-server, except no socket is created, and
5704 instead the passed FD is treated like a socket connection re‐
5705 ceived from accept(). In practice, you could pass either a FD
5706 created by socketpair(), or a pipe. In both cases, you must
5707 sure the FD is actually inherited by mpv (do not set the POSIX
5708 CLOEXEC flag).
5709 The player quits when the connection is closed.
5711 This is somewhat similar to the removed --input-file option, ex‐
5713 cept it supports only integer FDs, and cannot open actual paths.
5714 Example
5716 --input-ipc-client=fd://123
5718 NOTE:
5720 Does not and will not work on Windows.
5721 WARNING:
5723 Writing to the input-ipc-server option at runtime will start
5724 another instance of an IPC client handler for the in‐
5725 put-ipc-client option, because initialization is bundled, and
5726 this thing is stupid. This is a bug. Writing to in‐
5727 put-ipc-client at runtime will start another IPC client han‐
5728 dler for the new value, without stopping the old one, even if
5729 the FD value is the same (but the string is different e.g.
5730 due to whitespace). This is not a bug.
5731 --input-gamepad=<yes|no>
5733 Enable/disable SDL2 Gamepad support. Disabled by default.
5734 --input-cursor, --no-input-cursor
5736 Permit mpv to receive pointer events reported by the video out‐
5737 put driver. Necessary to use the OSC, or to select the buttons
5738 in DVD menus. Support depends on the VO in use.
5739 --input-media-keys=<yes|no>
5741 On systems where mpv can choose between receiving media keys or
5742 letting the system handle them - this option controls whether
5743 mpv should receive them.
5744 Default: yes (except for libmpv). macOS and Windows only, be‐
5746 cause elsewhere mpv doesn't have a choice - the system decides
5747 whether to send media keys to mpv. For instance, on X11 or Way‐
5748 land, system-wide media keys are not implemented. Whether media
5749 keys work when the mpv window is focused is implementation-de‐
5750 fined.
5751 --input-right-alt-gr, --no-input-right-alt-gr
5753 (Cocoa and Windows only) Use the right Alt key as Alt Gr to pro‐
5754 duce special characters. If disabled, count the right Alt as an
5755 Alt modifier key. Enabled by default.
5756 --input-vo-keyboard=<yes|no>
5758 Disable all keyboard input on for VOs which can't participate in
5759 proper keyboard input dispatching. May not affect all VOs. Gen‐
5760 erally useful for embedding only.
5761 On X11, a sub-window with input enabled grabs all keyboard input
5763 as long as it is 1. a child of a focused window, and 2. the
5764 mouse is inside of the sub-window. It can steal away all key‐
5765 board input from the application embedding the mpv window, and
5766 on the other hand, the mpv window will receive no input if the
5767 mouse is outside of the mpv window, even though mpv has focus.
5768 Modern toolkits work around this weird X11 behavior, but naively
5769 embedding foreign windows breaks it.
5770 The only way to handle this reasonably is using the XEmbed pro‐
5772 tocol, which was designed to solve these problems. GTK provides
5773 GtkSocket, which supports XEmbed. Qt doesn't seem to provide
5774 anything working in newer versions.
5775 If the embedder supports XEmbed, input should work with default
5777 settings and with this option disabled. Note that input-de‐
5778 fault-bindings is disabled by default in libmpv as well - it
5779 should be enabled if you want the mpv default key bindings.
5780 (This option was renamed from --input-x11-keyboard.)
5782 OSD
5784 --osc, --no-osc
5785 Whether to load the on-screen-controller (default: yes).
5786 --no-osd-bar, --osd-bar
5788 Disable display of the OSD bar.
5789 You can configure this on a per-command basis in input.conf us‐
5791 ing osd- prefixes, see Input Command Prefixes. If you want to
5792 disable the OSD completely, use --osd-level=0.
5793 --osd-on-seek=<no,bar,msg,msg-bar>
5795 Set what is displayed on the OSD during seeks. The default is
5796 bar.
5797 You can configure this on a per-command basis in input.conf us‐
5799 ing osd- prefixes, see Input Command Prefixes.
5800 --osd-duration=<time>
5802 Set the duration of the OSD messages in ms (default: 1000).
5803 --osd-font=<name>
5805 Specify font to use for OSD. The default is sans-serif.
5806 Examples
5808 • --osd-font='Bitstream Vera Sans'
5810 • --osd-font='Comic Sans MS'
5812 --osd-font-size=<size>
5814 Specify the OSD font size. See --sub-font-size for details.
5815 Default: 55.
5817 --osd-msg1=<string>
5819 Show this string as message on OSD with OSD level 1 (visible by
5820 default). The message will be visible by default, and as long
5821 as no other message covers it, and the OSD level isn't changed
5822 (see --osd-level). Expands properties; see Property Expansion.
5823 --osd-msg2=<string>
5825 Similar to --osd-msg1, but for OSD level 2. If this is an empty
5826 string (default), then the playback time is shown.
5827 --osd-msg3=<string>
5829 Similar to --osd-msg1, but for OSD level 3. If this is an empty
5830 string (default), then the playback time, duration, and some
5831 more information is shown.
5832 This is used for the show-progress command (by default mapped to
5834 P), and when seeking if enabled with --osd-on-seek or by osd-
5835 prefixes in input.conf (see Input Command Prefixes).
5836 --osd-status-msg is a legacy equivalent (but with a minor dif‐
5838 ference).
5839 --osd-status-msg=<string>
5841 Show a custom string during playback instead of the standard
5842 status text. This overrides the status text used for
5843 --osd-level=3, when using the show-progress command (by default
5844 mapped to P), and when seeking if enabled with --osd-on-seek or
5845 osd- prefixes in input.conf (see Input Command Prefixes). Ex‐
5846 pands properties. See Property Expansion.
5847 This option has been replaced with --osd-msg3. The only differ‐
5849 ence is that this option implicitly includes ${osd-sym-cc}. This
5850 option is ignored if --osd-msg3 is not empty.
5851 --osd-playing-msg=<string>
5853 Show a message on OSD when playback starts. The string is ex‐
5854 panded for properties, e.g. --osd-playing-msg='file: ${file‐
5855 name}' will show the message file: followed by a space and the
5856 currently played filename.
5857 See Property Expansion.
5859 --osd-playing-msg-duration=<time>
5861 Set the duration of osd-playing-msg in ms. If this is unset,
5862 osd-playing-msg stays on screen for the duration of osd-dura‐
5863 tion.
5864 --osd-bar-align-x=<-1-1>
5866 Position of the OSD bar. -1 is far left, 0 is centered, 1 is far
5867 right. Fractional values (like 0.5) are allowed.
5868 --osd-bar-align-y=<-1-1>
5870 Position of the OSD bar. -1 is top, 0 is centered, 1 is bottom.
5871 Fractional values (like 0.5) are allowed.
5872 --osd-bar-w=<1-100>
5874 Width of the OSD bar, in percentage of the screen width (de‐
5875 fault: 75). A value of 50 means the bar is half the screen
5876 wide.
5877 --osd-bar-h=<0.1-50>
5879 Height of the OSD bar, in percentage of the screen height (de‐
5880 fault: 3.125).
5881 --osd-back-color=<color>
5883 See --sub-color. Color used for OSD text background.
5884 --osd-blur=<0..20.0>
5886 Gaussian blur factor. 0 means no blur applied (default).
5887 --osd-bold=<yes|no>
5889 Format text on bold.
5890 --osd-italic=<yes|no>
5892 Format text on italic.
5893 --osd-border-color=<color>
5895 See --sub-color. Color used for the OSD font border.
5896 NOTE:
5898 ignored when --osd-back-color is specified (or more exactly:
5899 when that option is not set to completely transparent).
5900 --osd-border-size=<size>
5902 Size of the OSD font border in scaled pixels (see
5903 --sub-font-size for details). A value of 0 disables borders.
5904 Default: 3.
5906 --osd-color=<color>
5908 Specify the color used for OSD. See --sub-color for details.
5909 --osd-fractions
5911 Show OSD times with fractions of seconds (in millisecond preci‐
5912 sion). Useful to see the exact timestamp of a video frame.
5913 --osd-level=<0-3>
5915 Specifies which mode the OSD should start in.
5916 0 OSD completely disabled (subtitles only)
5918 1 enabled (shows up only on user interaction)
5920 2 enabled + current time visible by default
5922 3 enabled + --osd-status-msg (current time and status by
5924 default)
5925 --osd-margin-x=<size>
5927 Left and right screen margin for the OSD in scaled pixels (see
5928 --sub-font-size for details).
5929 This option specifies the distance of the OSD to the left, as
5931 well as at which distance from the right border long OSD text
5932 will be broken.
5933 Default: 25.
5935 --osd-margin-y=<size>
5937 Top and bottom screen margin for the OSD in scaled pixels (see
5938 --sub-font-size for details).
5939 This option specifies the vertical margins of the OSD.
5941 Default: 22.
5943 --osd-align-x=<left|center|right>
5945 Control to which corner of the screen OSD should be aligned to
5946 (default: left).
5947 --osd-align-y=<top|center|bottom>
5949 Vertical position (default: top). Details see --osd-align-x.
5950 --osd-scale=<factor>
5952 OSD font size multiplier, multiplied with --osd-font-size value.
5953 --osd-scale-by-window=<yes|no>
5955 Whether to scale the OSD with the window size (default: yes). If
5956 this is disabled, --osd-font-size and other OSD options that use
5957 scaled pixels are always in actual pixels. The effect is that
5958 changing the window size won't change the OSD font size.
5959 --osd-shadow-color=<color>
5961 See --sub-color. Color used for OSD shadow.
5962 --osd-shadow-offset=<size>
5964 Displacement of the OSD shadow in scaled pixels (see
5965 --sub-font-size for details). A value of 0 disables shadows.
5966 Default: 0.
5968 --osd-spacing=<size>
5970 Horizontal OSD/sub font spacing in scaled pixels (see
5971 --sub-font-size for details). This value is added to the normal
5972 letter spacing. Negative values are allowed.
5973 Default: 0.
5975 --video-osd=<yes|no>
5977 Enabled OSD rendering on the video window (default: yes). This
5978 can be used in situations where terminal OSD is preferred. If
5979 you just want to disable all OSD rendering, use --osd-level=0.
5980 It does not affect subtitles or overlays created by scripts (in
5982 particular, the OSC needs to be disabled with --no-osc).
5983 This option is somewhat experimental and could be replaced by
5985 another mechanism in the future.
5986 --osd-font-provider=<...>
5988 See --sub-font-provider for details and accepted values. Note
5989 that unlike subtitles, OSD never uses embedded fonts from media
5990 files.
5991 Screenshot
5993 --screenshot-format=<type>
5994 Set the image file type used for saving screenshots.
5995 Available choices:
5997 png PNG
5999 jpg JPEG (default)
6001 jpeg JPEG (alias for jpg)
6003 webp WebP
6005 jxl JPEG XL
6007 --screenshot-tag-colorspace=<yes|no>
6009 Tag screenshots with the appropriate colorspace.
6010 Note that not all formats are supported.
6012 Default: no.
6014 --screenshot-high-bit-depth=<yes|no>
6016 If possible, write screenshots with a bit depth similar to the
6017 source video (default: yes). This is interesting in particular
6018 for PNG, as this sometimes triggers writing 16 bit PNGs with
6019 huge file sizes. This will also include an unused alpha channel
6020 in the resulting files if 16 bit is used.
6021 --screenshot-template=<template>
6023 Specify the filename template used to save screenshots. The tem‐
6024 plate specifies the filename without file extension, and can
6025 contain format specifiers, which will be substituted when taking
6026 a screenshot. By default, the template is mpv-shot%n, which re‐
6027 sults in filenames like mpv-shot0012.png for example.
6028 The template can start with a relative or absolute path, in or‐
6030 der to specify a directory location where screenshots should be
6031 saved.
6032 If the final screenshot filename points to an already existing
6034 file, the file will not be overwritten. The screenshot will ei‐
6035 ther not be saved, or if the template contains %n, saved using
6036 different, newly generated filename.
6037 Allowed format specifiers:
6039 %[#][0X]n
6041 A sequence number, padded with zeros to length X (de‐
6042 fault: 04). E.g. passing the format %04n will yield 0012
6043 on the 12th screenshot. The number is incremented every
6044 time a screenshot is taken or if the file already exists.
6045 The length X must be in the range 0-9. With the optional
6046 # sign, mpv will use the lowest available number. For ex‐
6047 ample, if you take three screenshots--0001, 0002,
6048 0003--and delete the first two, the next two screenshots
6049 will not be 0004 and 0005, but 0001 and 0002 again.
6050 %f Filename of the currently played video.
6052 %F Same as %f, but strip the file extension, including the
6054 dot.
6055 %x Directory path of the currently played video. If the
6057 video is not on the filesystem (but e.g. http://), this
6058 expand to an empty string.
6059 %X{fallback}
6061 Same as %x, but if the video file is not on the filesys‐
6062 tem, return the fallback string inside the {...}.
6063 %p Current playback time, in the same format as used in the
6065 OSD. The result is a string of the form "HH:MM:SS". For
6066 example, if the video is at the time position 5 minutes
6067 and 34 seconds, %p will be replaced with "00:05:34".
6068 %P Similar to %p, but extended with the playback time in
6070 milliseconds. It is formatted as "HH:MM:SS.mmm", with
6071 "mmm" being the millisecond part of the playback time.
6072 NOTE:
6074 This is a simple way for getting unique per-frame
6075 timestamps. (Frame numbers would be more intuitive,
6076 but are not easily implementable because container
6077 formats usually use time stamps for identifying
6078 frames.)
6079 %wX Specify the current playback time using the format string
6081 X. %p is like %wH:%wM:%wS, and %P is like
6082 %wH:%wM:%wS.%wT.
6083 Valid format specifiers:
6085 %wH hour (padded with 0 to two digits)
6087 %wh hour (not padded)
6089 %wM minutes (00-59)
6091 %wm total minutes (includes hours, unlike %wM)
6093 %wS seconds (00-59)
6095 %ws total seconds (includes hours and minutes)
6097 %wf like %ws, but as float
6099 %wT milliseconds (000-999)
6101 %tX Specify the current local date/time using the format X.
6103 This format specifier uses the UNIX strftime() function
6104 internally, and inserts the result of passing "%X" to
6105 strftime. For example, %tm will insert the number of the
6106 current month as number. You have to use multiple %tX
6107 specifiers to build a full date/time string.
6108 %{prop[:fallback text]}
6110 Insert the value of the input property 'prop'. E.g.
6111 %{filename} is the same as %f. If the property does not
6112 exist or is not available, an error text is inserted, un‐
6113 less a fallback is specified.
6114 %% Replaced with the % character itself.
6116 --screenshot-directory=<path>
6118 Store screenshots in this directory. This path is joined with
6119 the filename generated by --screenshot-template. If the template
6120 filename is already absolute, the directory is ignored.
6121 If the directory does not exist, it is created on the first
6123 screenshot. If it is not a directory, an error is generated when
6124 trying to write a screenshot.
6125 This option is not set by default, and thus will write screen‐
6127 shots to the directory from which mpv was started. In pseudo-gui
6128 mode (see PSEUDO GUI MODE), this is set to the desktop.
6129 --screenshot-jpeg-quality=<0-100>
6131 Set the JPEG quality level. Higher means better quality. The de‐
6132 fault is 90.
6133 --screenshot-jpeg-source-chroma=<yes|no>
6135 Write JPEG files with the same chroma subsampling as the video
6136 (default: yes). If disabled, the libjpeg default is used.
6137 --screenshot-png-compression=<0-9>
6139 Set the PNG compression level. Higher means better compression.
6140 This will affect the file size of the written screenshot file
6141 and the time it takes to write a screenshot. Too high compres‐
6142 sion might occupy enough CPU time to interrupt playback. The de‐
6143 fault is 7.
6144 --screenshot-png-filter=<0-5>
6146 Set the filter applied prior to PNG compression. 0 is none, 1 is
6147 "sub", 2 is "up", 3 is "average", 4 is "Paeth", and 5 is
6148 "mixed". This affects the level of compression that can be
6149 achieved. For most images, "mixed" achieves the best compression
6150 ratio, hence it is the default.
6151 --screenshot-webp-lossless=<yes|no>
6153 Write lossless WebP files. --screenshot-webp-quality is ignored
6154 if this is set. The default is no.
6155 --screenshot-webp-quality=<0-100>
6157 Set the WebP quality level. Higher means better quality. The de‐
6158 fault is 75.
6159 --screenshot-webp-compression=<0-6>
6161 Set the WebP compression level. Higher means better compression,
6162 but takes more CPU time. Note that this also affects the screen‐
6163 shot quality when used with lossy WebP files. The default is 4.
6164 --screenshot-jxl-distance=<0-15>
6166 Set the JPEG XL Butteraugli distance. Lower means better qual‐
6167 ity. Lossless is 0.0, and 1.0 is approximately equivalent to
6168 JPEG quality 90 for photographic content. Use 0.1 for "visually
6169 lossless" screenshots. The default is 1.0.
6170 --screenshot-jxl-effort=<1-9>
6172 Set the JPEG XL compression effort. Higher effort (usually)
6173 means better compression, but takes more CPU time. The default
6174 is 3.
6175 --screenshot-sw=<yes|no>
6177 Whether to use software rendering for screenshots (default: no).
6178 If set to no, the screenshot will be rendered by the current VO
6180 if possible (only vo_gpu currently). The advantage is that this
6181 will (probably) always show up as in the video window, because
6182 the same code is used for rendering. But since the renderer
6183 needs to be reinitialized, this can be slow and interrupt play‐
6184 back. (Unless the window mode is used with the screenshot com‐
6185 mand.)
6186 If set to yes, the software scaler is used to convert the video
6188 to RGB (or whatever the target screenshot requires). In this
6189 case, conversion will run in a separate thread and will probably
6190 not interrupt playback. The software renderer may lack some ca‐
6191 pabilities, such as HDR rendering.
6192 Software Scaler
6194 --sws-scaler=<name>
6195 Specify the software scaler algorithm to be used with
6196 --vf=scale. This also affects video output drivers which lack
6197 hardware acceleration, e.g. x11. See also --vf=scale.
6198 To get a list of available scalers, run --sws-scaler=help.
6200 Default: bicubic.
6202 --sws-lgb=<0-100>
6204 Software scaler Gaussian blur filter (luma). See --sws-scaler.
6205 --sws-cgb=<0-100>
6207 Software scaler Gaussian blur filter (chroma). See --sws-scaler.
6208 --sws-ls=<-100-100>
6210 Software scaler sharpen filter (luma). See --sws-scaler.
6211 --sws-cs=<-100-100>
6213 Software scaler sharpen filter (chroma). See --sws-scaler.
6214 --sws-chs=<h>
6216 Software scaler chroma horizontal shifting. See --sws-scaler.
6217 --sws-cvs=<v>
6219 Software scaler chroma vertical shifting. See --sws-scaler.
6220 --sws-bitexact=<yes|no>
6222 Unknown functionality (default: no). Consult libswscale source
6223 code. The primary purpose of this, as far as libswscale API
6224 goes), is to produce exactly the same output for the same input
6225 on all platforms (output has the same "bits" everywhere, thus
6226 "bitexact"). Typically disables optimizations.
6227 --sws-fast=<yes|no>
6229 Allow optimizations that help with performance, but reduce qual‐
6230 ity (default: no).
6231 VOs like drm and x11 will benefit a lot from using --sws-fast.
6233 You may need to set other options, like --sws-scaler. The
6234 builtin sws-fast profile sets this option and some others to
6235 gain performance for reduced quality. Also see --sws-allow-zimg.
6236 --sws-allow-zimg=<yes|no>
6238 Allow using zimg (if the component using the internal swscale
6239 wrapper explicitly allows so) (default: yes). In this case, zimg
6240 may be used, if the internal zimg wrapper supports the input and
6241 output formats. It will silently or noisily fall back to libsws‐
6242 cale if one of these conditions does not apply.
6243 If zimg is used, the other --sws- options are ignored, and the
6245 --zimg- options are used instead.
6246 If the internal component using the swscale wrapper hooks up
6248 logging correctly, a verbose priority log message will indicate
6249 whether zimg is being used.
6250 Most things which need software conversion can make use of this.
6252 NOTE:
6254 Do note that zimg may be slower than libswscale. Usually,
6255 it's faster on x86 platforms, but slower on ARM (due to lack
6256 of ARM specific optimizations). The mpv zimg wrapper uses un‐
6257 optimized repacking for some formats, for which zimg cannot
6258 be blamed.
6259 --zimg-scaler=<point|bilinear|bicubic|spline16|spline36|lanczos>
6261 Zimg luma scaler to use (default: lanczos).
6262 --zimg-scaler-param-a=<default|float>, --zimg-scaler-param-b=<de‐
6264 fault|float>
6265 Set scaler parameters. By default, these are set to the special
6266 string default, which maps to a scaler-specific default value.
6267 Ignored if the scaler is not tunable.
6268 lanczos
6270 --zimg-scaler-param-a is the number of taps.
6271 bicubic
6273 a and b are the bicubic b and c parameters.
6274 --zimg-scaler-chroma=...
6276 Same as --zimg-scaler, for for chroma interpolation (default:
6277 bilinear).
6278 --zimg-scaler-chroma-param-a, --zimg-scaler-chroma-param-b
6280 Same as --zimg-scaler-param-a / --zimg-scaler-param-b, for
6281 chroma.
6282 --zimg-dither=<no|ordered|random|error-diffusion>
6284 Dithering (default: random).
6285 --zimg-threads=<auto|integer>
6287 Set the maximum number of threads to use for scaling (default:
6288 auto). auto uses the number of logical cores on the current ma‐
6289 chine. Note that the scaler may use less threads (or even just 1
6290 thread) depending on stuff. Passing a value of 1 disables
6291 threading and always scales the image in a single operation.
6292 Higher thread counts waste resources, but make it typically
6293 faster.
6294 Note that some zimg git versions had bugs that will corrupt the
6296 output if threads are used.
6297 --zimg-fast=<yes|no>
6299 Allow optimizations that help with performance, but reduce qual‐
6300 ity (default: yes). Currently, this may simplify gamma conver‐
6301 sion operations.
6302 Audio Resampler
6304 This controls the default options of any resampling done by mpv (but
6305 not within libavfilter, within the system audio API resampler, or any
6306 other places).
6307 It also sets the defaults for the lavrresample audio filter.
6309 --audio-resample-filter-size=<length>
6311 Length of the filter with respect to the lower sampling rate.
6312 (default: 16)
6313 --audio-resample-phase-shift=<count>
6315 Log2 of the number of polyphase entries. (..., 10->1024,
6316 11->2048, 12->4096, ...) (default: 10->1024)
6317 --audio-resample-cutoff=<cutoff>
6319 Cutoff frequency (0.0-1.0), default set depending upon filter
6320 length.
6321 --audio-resample-linear=<yes|no>
6323 If set then filters will be linearly interpolated between
6324 polyphase entries. (default: no)
6325 --audio-normalize-downmix=<yes|no>
6327 Enable/disable normalization if surround audio is downmixed to
6328 stereo (default: no). If this is disabled, downmix can cause
6329 clipping. If it's enabled, the output might be too quiet. It de‐
6330 pends on the source audio.
6331 Technically, this changes the normalize suboption of the lavrre‐
6333 sample audio filter, which performs the downmixing.
6334 If downmix happens outside of mpv for some reason, or in the de‐
6336 coder (decoder downmixing), or in the audio output (system
6337 mixer), this has no effect.
6338 --audio-resample-max-output-size=<length>
6340 Limit maximum size of audio frames filtered at once, in ms (de‐
6341 fault: 40). The output size size is limited in order to make
6342 resample speed changes react faster. This is necessary espe‐
6343 cially if decoders or filters output very large frame sizes
6344 (like some lossless codecs or some DRC filters). This option
6345 does not affect the resampling algorithm in any way.
6346 For testing/debugging only. Can be removed or changed any time.
6348 --audio-swresample-o=<string>
6350 Set AVOptions on the SwrContext or AVAudioResampleContext. These
6351 should be documented by FFmpeg or Libav.
6352 This is a key/value list option. See List Options for details.
6354 Terminal
6356 --quiet
6357 Make console output less verbose; in particular, prevents the
6358 status line (i.e. AV: 3.4 (00:00:03.37) / 5320.6 ...) from being
6359 displayed. Particularly useful on slow terminals or broken ones
6360 which do not properly handle carriage return (i.e. \r).
6361 See also: --really-quiet and --msg-level.
6363 --really-quiet
6365 Display even less output and status messages than with --quiet.
6366 --no-terminal, --terminal
6368 Disable any use of the terminal and stdin/stdout/stderr. This
6369 completely silences any message output.
6370 Unlike --really-quiet, this disables input and terminal initial‐
6372 ization as well.
6373 --no-msg-color
6375 Disable colorful console output on terminals.
6376 --msg-level=<module1=level1,module2=level2,...>
6378 Control verbosity directly for each module. The all module
6379 changes the verbosity of all the modules. The verbosity changes
6380 from this option are applied in order from left to right, and
6381 each item can override a previous one.
6382 Run mpv with --msg-level=all=trace to see all messages mpv out‐
6384 puts. You can use the module names printed in the output (pre‐
6385 fixed to each line in [...]) to limit the output to interesting
6386 modules.
6387 This also affects --log-file, and in certain cases libmpv API
6389 logging.
6390 NOTE:
6392 Some messages are printed before the command line is parsed
6393 and are therefore not affected by --msg-level. To control
6394 these messages, you have to use the MPV_VERBOSE environment
6395 variable; see ENVIRONMENT VARIABLES for details.
6396 Available levels:
6398 no complete silence
6400 fatal fatal messages only
6402 error error messages
6404 warn warning messages
6406 info informational messages
6408 status status messages (default)
6410 v verbose messages
6412 debug debug messages
6414 trace very noisy debug messages
6416 Example
6418 mpv --msg-level=ao/sndio=no
6420 Completely silences the output of ao_sndio, which uses the
6422 log prefix [ao/sndio].
6423 mpv --msg-level=all=warn,ao/alsa=error
6425 Only show warnings or worse, and let the ao_alsa output show
6427 errors only.
6428 --term-osd=<auto|no|force>
6430 Control whether OSD messages are shown on the console when no
6431 video output is available (default: auto).
6432 auto use terminal OSD if no video output active
6434 no disable terminal OSD
6436 force use terminal OSD even if video output active
6438 The auto mode also enables terminal OSD if --video-osd=no was
6440 set.
6441 --term-osd-bar, --no-term-osd-bar
6443 Enable printing a progress bar under the status line on the ter‐
6444 minal. (Disabled by default.)
6445 --term-osd-bar-chars=<string>
6447 Customize the --term-osd-bar feature. The string is expected to
6448 consist of 5 characters (start, left space, position indicator,
6449 right space, end). You can use Unicode characters, but note that
6450 double- width characters will not be treated correctly.
6451 Default: [-+-].
6453 --term-playing-msg=<string>
6455 Print out a string after starting playback. The string is ex‐
6456 panded for properties, e.g. --term-playing-msg='file: ${file‐
6457 name}' will print the string file: followed by a space and the
6458 currently played filename.
6459 See Property Expansion.
6461 --term-status-msg=<string>
6463 Print out a custom string during playback instead of the stan‐
6464 dard status line. Expands properties. See Property Expansion.
6465 --term-title=<string>
6467 Set the terminal title. Currently, this simply concatenates the
6468 escape sequence setting the window title with the provided
6469 (property expanded) string. This will mess up if the expanded
6470 string contain bytes that end the escape sequence, or if the
6471 terminal does not understand the sequence. The latter probably
6472 includes the regrettable win32.
6473 Expands properties. See Property Expansion.
6475 --msg-module
6477 Prepend module name to each console message.
6478 --msg-time
6480 Prepend timing information to each console message. The time is
6481 in seconds since the player process was started (technically,
6482 slightly later actually), using a monotonic time source depend‐
6483 ing on the OS. This is CLOCK_MONOTONIC on sane UNIX variants.
6484 Cache
6486 --cache=<yes|no|auto>
6487 Decide whether to use network cache settings (default: auto).
6488 If enabled, use up to --cache-secs for the cache size (but still
6490 limited to --demuxer-max-bytes), and make the cached data seek‐
6491 able (if possible). If disabled, --cache-pause and related are
6492 implicitly disabled.
6493 The auto choice enables this depending on whether the stream is
6495 thought to involve network accesses or other slow media (this is
6496 an imperfect heuristic).
6497 Before mpv 0.30.0, this used to accept a number, which specified
6499 the size of the cache in kilobytes. Use e.g. --cache --de‐
6500 muxer-max-bytes=123k instead.
6501 --no-cache
6503 Turn off input stream caching. See --cache.
6504 --cache-secs=<seconds>
6506 How many seconds of audio/video to prefetch if the cache is ac‐
6507 tive. This overrides the --demuxer-readahead-secs option if and
6508 only if the cache is enabled and the value is larger. The de‐
6509 fault value is set to something very high, so the actually
6510 achieved readahead will usually be limited by the value of the
6511 --demuxer-max-bytes option. Setting this option is usually only
6512 useful for limiting readahead.
6513 --cache-on-disk=<yes|no>
6515 Write packet data to a temporary file, instead of keeping them
6516 in memory. This makes sense only with --cache. If the normal
6517 cache is disabled, this option is ignored.
6518 You need to set --cache-dir to use this.
6520 The cache file is append-only. Even if the player appears to
6522 prune data, the file space freed by it is not reused. The cache
6523 file is deleted when playback is closed.
6524 Note that packet metadata is still kept in memory. --de‐
6526 muxer-max-bytes and related options are applied to metadata
6527 only. The size of this metadata varies, but 50 MB per hour of
6528 media is typical. The cache statistics will report this metadats
6529 size, instead of the size of the cache file. If the metadata
6530 hits the size limits, the metadata is pruned (but not the cache
6531 file).
6532 When the media is closed, the cache file is deleted. A cache
6534 file is generally worthless after the media is closed, and it's
6535 hard to retrieve any media data from it (it's not supported by
6536 design).
6537 If the option is enabled at runtime, the cache file is created,
6539 but old data will remain in the memory cache. If the option is
6540 disabled at runtime, old data remains in the disk cache, and the
6541 cache file is not closed until the media is closed. If the op‐
6542 tion is disabled and enabled again, it will continue to use the
6543 cache file that was opened first.
6544 --cache-dir=<path>
6546 Directory where to create temporary files (default: none).
6547 Currently, this is used for --cache-on-disk only.
6549 --cache-pause=<yes|no>
6551 Whether the player should automatically pause when the cache
6552 runs out of data and stalls decoding/playback (default: yes). If
6553 enabled, it will pause and unpause once more data is available,
6554 aka "buffering".
6555 --cache-pause-wait=<seconds>
6557 Number of seconds the packet cache should have buffered before
6558 starting playback again if "buffering" was entered (default: 1).
6559 This can be used to control how long the player rebuffers if
6560 --cache-pause is enabled, and the demuxer underruns. If the
6561 given time is higher than the maximum set with --cache-secs or
6562 --demuxer-readahead-secs, or prefetching ends before that for
6563 some other reason (like file end or maximum configured cache
6564 size reached), playback resumes earlier.
6565 --cache-pause-initial=<yes|no>
6567 Enter "buffering" mode before starting playback (default: no).
6568 This can be used to ensure playback starts smoothly, in exchange
6569 for waiting some time to prefetch network data (as controlled by
6570 --cache-pause-wait). For example, some common behavior is that
6571 playback starts, but network caches immediately underrun when
6572 trying to decode more data as playback progresses.
6573 Another thing that can happen is that the network prefetching is
6575 so CPU demanding (due to demuxing in the background) that play‐
6576 back drops frames at first. In these cases, it helps enabling
6577 this option, and setting --cache-secs and --cache-pause-wait to
6578 roughly the same value.
6579 This option also triggers when playback is restarted after seek‐
6581 ing.
6582 --cache-unlink-files=<immediate|whendone|no>
6584 Whether or when to unlink cache files (default: immediate). This
6585 affects cache files which are inherently temporary, and which
6586 make no sense to remain on disk after the player terminates.
6587 This is a debugging option.
6588 immediate
6590 Unlink cache file after they were created. The cache
6591 files won't be visible anymore, even though they're in
6592 use. This ensures they are guaranteed to be removed from
6593 disk when the player terminates, even if it crashes.
6594 whendone
6596 Delete cache files after they are closed.
6597 no Don't delete cache files. They will consume disk space
6599 without having a use.
6600 Currently, this is used for --cache-on-disk only.
6602 --stream-buffer-size=<bytesize>
6604 Size of the low level stream byte buffer (default: 128KB). This
6605 is used as buffer between demuxer and low level I/O (e.g. sock‐
6606 ets). Generally, this can be very small, and the main purpose is
6607 similar to the internal buffer FILE in the C standard library
6608 will have.
6609 Half of the buffer is always used for guaranteed seek back,
6611 which is important for unseekable input.
6612 There are known cases where this can help performance to set a
6614 large buffer:
6615 1. mp4 files. libavformat may trigger many small seeks in
6617 both directions, depending on how the file was muxed.
6618 2. Certain network filesystems, which do not have a cache,
6620 and where small reads can be inefficient.
6621 In other cases, setting this to a large value can reduce perfor‐
6623 mance.
6624 Usually, read accesses are at half the buffer size, but it may
6626 happen that accesses are done alternating with smaller and
6627 larger sizes (this is due to the internal ring buffer
6628 wrap-around).
6629 See --list-options for defaults and value range. <bytesize> op‐
6631 tions accept suffixes such as KiB and MiB.
6632 --vd-queue-enable=<yes|no>, --ad-queue-enable
6634 Enable running the video/audio decoder on a separate thread (de‐
6635 fault: no). If enabled, the decoder is run on a separate
6636 thread, and a frame queue is put between decoder and higher
6637 level playback logic. The size of the frame queue is defined by
6638 the other options below.
6639 This is probably quite pointless. libavcodec already has multi‐
6641 threaded decoding (enabled by default), which makes this largely
6642 unnecessary. It might help in some corner cases with high band‐
6643 width video that is slow to decode (in these cases libavcodec
6644 would block the playback logic, while using a decoding thread
6645 would distribute the decoding time evenly without affecting the
6646 playback logic). In other situations, it will simply make seek‐
6647 ing slower and use significantly more memory.
6648 The queue size is restricted by the other --vd-queue-... op‐
6650 tions. The final queue size is the minimum as indicated by the
6651 option with the lowest limit. Each decoder/track has its own
6652 queue that may use the full configured queue size.
6653 Most queue options can be changed at runtime. --vd-queue-enable
6655 itself (and the audio equivalent) update only if decoding is
6656 completely reinitialized. However, setting --vd-queue-max-sam‐
6657 ples=1 should almost lead to the same behavior as --vd-queue-en‐
6658 able=no, so that value can be used for effectively runtime en‐
6659 abling/disabling the queue.
6660 This should not be used with hardware decoding. It is possible
6662 to enable this for audio, but it makes even less sense.
6663 --vd-queue-max-bytes=<bytesize>, --ad-queue-max-bytes
6665 Maximum approximate allowed size of the queue. If exceeded, de‐
6666 coding will be stopped. The maximum size can be exceeded by
6667 about 1 frame.
6668 See --list-options for defaults and value range. <bytesize> op‐
6670 tions accept suffixes such as KiB and MiB.
6671 --vd-queue-max-samples=<int>, --ad-queue-max-samples
6673 Maximum number of frames (video) or samples (audio) of the
6674 queue. The audio size may be exceeded by about 1 frame.
6675 See --list-options for defaults and value range.
6677 --vd-queue-max-secs=<seconds>, --ad-queue-max-secs
6679 Maximum number of seconds of media in the queue. The special
6680 value 0 means no limit is set. The queue size may be exceeded by
6681 about 2 frames. Timestamp resets may lead to random queue size
6682 usage.
6683 See --list-options for defaults and value range.
6685 Network
6687 --user-agent=<string>
6688 Use <string> as user agent for HTTP streaming.
6689 --cookies, --no-cookies
6691 Support cookies when making HTTP requests. Disabled by default.
6692 --cookies-file=<filename>
6694 Read HTTP cookies from <filename>. The file is assumed to be in
6695 Netscape format.
6696 --http-header-fields=<field1,field2>
6698 Set custom HTTP fields when accessing HTTP stream.
6699 This is a string list option. See List Options for details.
6701 Example
6703 mpv --http-header-fields='Field1: value1','Field2: value2' \
6705 http://localhost:1234
6706 Will generate HTTP request:
6708 GET / HTTP/1.0
6710 Host: localhost:1234
6711 User-Agent: MPlayer
6712 Icy-MetaData: 1
6713 Field1: value1
6714 Field2: value2
6715 Connection: close
6716 --http-proxy=<proxy>
6718 URL of the HTTP/HTTPS proxy. If this is set, the http_proxy en‐
6719 vironment is ignored. The no_proxy environment variable is still
6720 respected. This option is silently ignored if it does not start
6721 with http://. Proxies are not used for https URLs. Setting this
6722 option does not try to make the ytdl script use the proxy.
6723 --tls-ca-file=<filename>
6725 Certificate authority database file for use with TLS. (Silently
6726 fails with older FFmpeg or Libav versions.)
6727 --tls-verify
6729 Verify peer certificates when using TLS (e.g. with https://...).
6730 (Silently fails with older FFmpeg or Libav versions.)
6731 --tls-cert-file
6733 A file containing a certificate to use in the handshake with the
6734 peer.
6735 --tls-key-file
6737 A file containing the private key for the certificate.
6738 --referrer=<string>
6740 Specify a referrer path or URL for HTTP requests.
6741 --network-timeout=<seconds>
6743 Specify the network timeout in seconds (default: 60 seconds).
6744 This affects at least HTTP. The special value 0 uses the FFm‐
6745 peg/Libav defaults. If a protocol is used which does not support
6746 timeouts, this option is silently ignored.
6747 WARNING:
6749 This breaks the RTSP protocol, because of inconsistent FFmpeg
6750 API regarding its internal timeout option. Not only does the
6751 RTSP timeout option accept different units (seconds instead
6752 of microseconds, causing mpv to pass it huge values), it will
6753 also overflow FFmpeg internal calculations. The worst is that
6754 merely setting the option will put RTSP into listening mode,
6755 which breaks any client uses. At time of this writing, the
6756 fix was not made effective yet. For this reason, this option
6757 is ignored (or should be ignored) on RTSP URLs. You can still
6758 set the timeout option directly with --demuxer-lavf-o.
6759 --rtsp-transport=<lavf|udp|udp_multicast|tcp|http>
6761 Select RTSP transport method (default: tcp). This selects the
6762 underlying network transport when playing rtsp://... URLs. The
6763 value lavf leaves the decision to libavformat.
6764 --hls-bitrate=<no|min|max|<rate>>
6766 If HLS streams are played, this option controls what streams are
6767 selected by default. The option allows the following parameters:
6768 no Don't do anything special. Typically, this will simply
6770 pick the first audio/video streams it can find.
6771 min Pick the streams with the lowest bitrate.
6773 max Same, but highest bitrate. (Default.)
6775 Additionally, if the option is a number, the stream with the
6777 highest rate equal or below the option value is selected.
6778 The bitrate as used is sent by the server, and there's no guar‐
6780 antee it's actually meaningful.
6781 DVB
6783 --dvbin-prog=<string>
6784 This defines the program to tune to. Usually, you may specify
6785 this by using a stream URI like "dvb://ZDF HD", but you can tune
6786 to a different channel by writing to this property at runtime.
6787 Also see dvbin-channel-switch-offset for more useful channel
6788 switching functionality.
6789 --dvbin-card=<0-15>
6791 Specifies using card number 0-15 (default: 0).
6792 --dvbin-file=<filename>
6794 Instructs mpv to read the channels list from <filename>. The de‐
6795 fault is in the mpv configuration directory (usually ~/.con‐
6796 fig/mpv) with the filename channels.conf.{sat,ter,cbl,atsc}
6797 (based on your card type) or channels.conf as a last resort.
6798 For DVB-S/2 cards, a VDR 1.7.x format channel list is recom‐
6799 mended as it allows tuning to DVB-S2 channels, enabling subti‐
6800 tles and decoding the PMT (which largely improves the demuxing).
6801 Classic mplayer format channel lists are still supported (with‐
6802 out these improvements), and for other card types, only limited
6803 VDR format channel list support is implemented (patches wel‐
6804 come). For channels with dynamic PID switching or incomplete
6805 channels.conf, --dvbin-full-transponder or the magic PID 8192
6806 are recommended.
6807 --dvbin-timeout=<1-30>
6809 Maximum number of seconds to wait when trying to tune a fre‐
6810 quency before giving up (default: 30).
6811 --dvbin-full-transponder=<yes|no>
6813 Apply no filters on program PIDs, only tune to frequency and
6814 pass full transponder to demuxer. The player frontend selects
6815 the streams from the full TS in this case, so the program which
6816 is shown initially may not match the chosen channel. Switching
6817 between the programs is possible by cycling the program prop‐
6818 erty. This is useful to record multiple programs on a single
6819 transponder, or to work around issues in the channels.conf. It
6820 is also recommended to use this for channels which switch PIDs
6821 on-the-fly, e.g. for regional news.
6822 Default: no
6824 --dvbin-channel-switch-offset=<integer>
6826 This value is not meant for setting via configuration, but used
6827 in channel switching. An input.conf can cycle this value up and
6828 down to perform channel switching. This number effectively gives
6829 the offset to the initially tuned to channel in the channel
6830 list.
6831 An example input.conf could contain: H cycle dvbin-chan‐
6833 nel-switch-offset up, K cycle dvbin-channel-switch-offset down
6834 ALSA audio output options
6836 --alsa-device=<device>
6837 Deprecated, use --audio-device (requires alsa/ prefix).
6838 --alsa-resample=yes
6840 Enable ALSA resampling plugin. (This is disabled by default, be‐
6841 cause some drivers report incorrect audio delay in some cases.)
6842 --alsa-mixer-device=<device>
6844 Set the mixer device used with ao-volume (default: default).
6845 --alsa-mixer-name=<name>
6847 Set the name of the mixer element (default: Master). This is for
6848 example PCM or Master.
6849 --alsa-mixer-index=<number>
6851 Set the index of the mixer channel (default: 0). Consider the
6852 output of "amixer scontrols", then the index is the number that
6853 follows the name of the element.
6854 --alsa-non-interleaved
6856 Allow output of non-interleaved formats (if the audio decoder
6857 uses this format). Currently disabled by default, because some
6858 popular ALSA plugins are utterly broken with non-interleaved
6859 formats.
6860 --alsa-ignore-chmap
6862 Don't read or set the channel map of the ALSA device - only re‐
6863 quest the required number of channels, and then pass the audio
6864 as-is to it. This option most likely should not be used. It can
6865 be useful for debugging, or for static setups with a specially
6866 engineered ALSA configuration (in this case you should always
6867 force the same layout with --audio-channels, or it will work
6868 only for files which use the layout implicit to your ALSA de‐
6869 vice).
6870 --alsa-buffer-time=<microseconds>
6872 Set the requested buffer time in microseconds. A value of 0
6873 skips requesting anything from the ALSA API. This and the
6874 --alsa-periods option uses the ALSA near functions to set the
6875 requested parameters. If doing so results in an empty configura‐
6876 tion set, setting these parameters is skipped.
6877 Both options control the buffer size. A low buffer size can lead
6879 to higher CPU usage and audio dropouts, while a high buffer size
6880 can lead to higher latency in volume changes and other filter‐
6881 ing.
6882 --alsa-periods=<number>
6884 Number of periods requested from the ALSA API. See --alsa-buf‐
6885 fer-time for further remarks.
6886 GPU renderer options
6888 The following video options are currently all specific to --vo=gpu,
6889 --vo=libmpv and --vo=gpu-next, which are the only VOs that implement
6890 them.
6891 --scale=<filter>
6893 The filter function to use when upscaling video.
6894 bilinear
6896 Bilinear hardware texture filtering (fastest, very low
6897 quality). This is the default for compatibility reasons.
6898 spline36
6900 Mid quality and speed. This is the default when using
6901 gpu-hq.
6902 lanczos
6904 Lanczos scaling. Provides mid quality and speed. Gener‐
6905 ally worse than spline36, but it results in a slightly
6906 sharper image which is good for some content types. The
6907 number of taps can be controlled with scale-radius, but
6908 is best left unchanged.
6909 (This filter is an alias for sinc-windowed sinc)
6911 ewa_lanczos
6913 Elliptic weighted average Lanczos scaling. Also known as
6914 Jinc. Relatively slow, but very good quality. The radius
6915 can be controlled with scale-radius. Increasing the ra‐
6916 dius makes the filter sharper but adds more ringing.
6917 (This filter is an alias for jinc-windowed jinc)
6919 ewa_lanczossharp
6921 A slightly sharpened version of ewa_lanczos, preconfig‐
6922 ured to use an ideal radius and parameter. If your hard‐
6923 ware can run it, this is probably what you should use by
6924 default.
6925 mitchell
6927 Mitchell-Netravali. The B and C parameters can be set
6928 with --scale-param1 and --scale-param2. This filter is
6929 very good at downscaling (see --dscale).
6930 oversample
6932 A version of nearest neighbour that (naively) oversamples
6933 pixels, so that pixels overlapping edges get linearly in‐
6934 terpolated instead of rounded. This essentially removes
6935 the small imperfections and judder artifacts caused by
6936 nearest-neighbour interpolation, in exchange for adding
6937 some blur. This filter is good at temporal interpolation,
6938 and also known as "smoothmotion" (see --tscale).
6939 linear A --tscale filter.
6941 There are some more filters, but most are not as useful. For a
6943 complete list, pass help as value, e.g.:
6944 mpv --scale=help
6946 --cscale=<filter>
6948 As --scale, but for interpolating chroma information. If the im‐
6949 age is not subsampled, this option is ignored entirely.
6950 --dscale=<filter>
6952 Like --scale, but apply these filters on downscaling instead. If
6953 this option is unset, the filter implied by --scale will be ap‐
6954 plied.
6955 --tscale=<filter>
6957 The filter used for interpolating the temporal axis (frames).
6958 This is only used if --interpolation is enabled. The only valid
6959 choices for --tscale are separable convolution filters (use
6960 --tscale=help to get a list). The default is mitchell.
6961 Common --tscale choices include oversample, linear, catmull_rom,
6963 mitchell, gaussian, or bicubic. These are listed in increasing
6964 order of smoothness/blurriness, with bicubic being the
6965 smoothest/blurriest and oversample being the sharpest/least
6966 smooth.
6967 --scale-param1=<value>, --scale-param2=<value>,
6969 --cscale-param1=<value>, --cscale-param2=<value>,
6970 --dscale-param1=<value>, --dscale-param2=<value>,
6971 --tscale-param1=<value>, --tscale-param2=<value>
6972 Set filter parameters. By default, these are set to the special
6973 string default, which maps to a scaler-specific default value.
6974 Ignored if the filter is not tunable. Currently, this affects
6975 the following filter parameters:
6976 bcspline
6978 Spline parameters (B and C). Defaults to 0.5 for both.
6979 gaussian
6981 Scale parameter (t). Increasing this makes the result
6982 blurrier. Defaults to 1.
6983 oversample
6985 Minimum distance to an edge before interpolation is used.
6986 Setting this to 0 will always interpolate edges, whereas
6987 setting it to 0.5 will never interpolate, thus behaving
6988 as if the regular nearest neighbour algorithm was used.
6989 Defaults to 0.0.
6990 --scale-blur=<value>, --scale-wblur=<value>, --cscale-blur=<value>,
6992 --cscale-wblur=<value>, --dscale-blur=<value>, --dscale-wblur=<value>,
6993 --tscale-blur=<value>, --tscale-wblur=<value>
6994 Kernel/window scaling factor (also known as a blur factor). De‐
6995 creasing this makes the result sharper, increasing it makes it
6996 blurrier (default 0). If set to 0, the kernel's preferred blur
6997 factor is used. Note that setting this too low (eg. 0.5) leads
6998 to bad results. It's generally recommended to stick to values
6999 between 0.8 and 1.2.
7000 --scale-clamp=<0.0-1.0>, --cscale-clamp, --dscale-clamp, --tscale-clamp
7002 Specifies a weight bias to multiply into negative coefficients.
7003 Specifying --scale-clamp=1 has the effect of removing negative
7004 weights completely, thus effectively clamping the value range to
7005 [0-1]. Values between 0.0 and 1.0 can be specified to apply only
7006 a moderate diminishment of negative weights. This is especially
7007 useful for --tscale, where it reduces excessive ringing arti‐
7008 facts in the temporal domain (which typically manifest them‐
7009 selves as short flashes or fringes of black, mostly around mov‐
7010 ing edges) in exchange for potentially adding more blur. The de‐
7011 fault for --tscale-clamp is 1.0, the others default to 0.0.
7012 --scale-cutoff=<value>, --cscale-cutoff=<value>, --dscale-cut‐
7014 off=<value>
7015 Cut off the filter kernel prematurely once the value range drops
7016 below this threshold. Doing so allows more aggressive pruning of
7017 skippable coefficients by disregarding parts of the LUT which
7018 are effectively zeroed out by the window function. Only affects
7019 polar (EWA) filters. The default is 0.001 for each, which is
7020 perceptually transparent but provides a 10%-20% speedup, depend‐
7021 ing on the exact radius and filter kernel chosen.
7022 --scale-taper=<value>, --scale-wtaper=<value>, --dscale-taper=<value>,
7024 --dscale-wtaper=<value>, --cscale-taper=<value>, --cscale-wta‐
7025 per=<value>, --tscale-taper=<value>, --tscale-wtaper=<value>
7026 Kernel/window taper factor. Increasing this flattens the filter
7027 function. Value range is 0 to 1. A value of 0 (the default)
7028 means no flattening, a value of 1 makes the filter completely
7029 flat (equivalent to a box function). Values in between mean
7030 that some portion will be flat and the actual filter function
7031 will be squeezed into the space in between.
7032 --scale-radius=<value>, --cscale-radius=<value>, --dscale-ra‐
7034 dius=<value>, --tscale-radius=<value>
7035 Set radius for tunable filters, must be a float number between
7036 0.5 and 16.0. Defaults to the filter's preferred radius if not
7037 specified. Doesn't work for every scaler and VO combination.
7038 Note that depending on filter implementation details and video
7040 scaling ratio, the radius that actually being used might be dif‐
7041 ferent (most likely being increased a bit).
7042 --scale-antiring=<value>, --cscale-antiring=<value>, --dscale-antir‐
7044 ing=<value>, --tscale-antiring=<value>
7045 Set the antiringing strength. This tries to eliminate ringing,
7046 but can introduce other artifacts in the process. Must be a
7047 float number between 0.0 and 1.0. The default value of 0.0 dis‐
7048 ables antiringing entirely.
7049 Note that this doesn't affect the special filters bilinear and
7051 bicubic_fast, nor does it affect any polar (EWA) scalers.
7052 --scale-window=<window>, --cscale-window=<window>, --dscale-win‐
7054 dow=<window>, --tscale-window=<window>
7055 (Advanced users only) Choose a custom windowing function for the
7056 kernel. Defaults to the filter's preferred window if unset. Use
7057 --scale-window=help to get a list of supported windowing func‐
7058 tions.
7059 --scale-wparam=<window>, --cscale-wparam=<window>,
7061 --cscale-wparam=<window>, --tscale-wparam=<window>
7062 (Advanced users only) Configure the parameter for the window
7063 function given by --scale-window etc. By default, these are set
7064 to the special string default, which maps to a window-specific
7065 default value. Ignored if the window is not tunable. Currently,
7066 this affects the following window parameters:
7067 kaiser Window parameter (alpha). Defaults to 6.33.
7069 blackman
7071 Window parameter (alpha). Defaults to 0.16.
7072 gaussian
7074 Scale parameter (t). Increasing this makes the window
7075 wider. Defaults to 1.
7076 --scaler-lut-size=<4..10>
7078 Set the size of the lookup texture for scaler kernels (default:
7079 6). The actual size of the texture is 2^N for an option value of
7080 N. So the lookup texture with the default setting uses 64 sam‐
7081 ples.
7082 All weights are linearly interpolated from those samples, so in‐
7084 creasing the size of lookup table might improve the accuracy of
7085 scaler.
7086 --scaler-resizes-only
7088 Disable the scaler if the video image is not resized. In that
7089 case, bilinear is used instead of whatever is set with --scale.
7090 Bilinear will reproduce the source image perfectly if no scaling
7091 is performed. Enabled by default. Note that this option never
7092 affects --cscale.
7093 --correct-downscaling
7095 When using convolution based filters, extend the filter size
7096 when downscaling. Increases quality, but reduces performance
7097 while downscaling.
7098 This will perform slightly sub-optimally for anamorphic video
7100 (but still better than without it) since it will extend the size
7101 to match only the milder of the scale factors between the axes.
7102 Note: this option is ignored when using bilinear downscaling
7104 (the default).
7105 --linear-downscaling
7107 Scale in linear light when downscaling. It should only be used
7108 with a --fbo-format that has at least 16 bit precision. This op‐
7109 tion has no effect on HDR content.
7110 --linear-upscaling
7112 Scale in linear light when upscaling. Like --linear-downscaling,
7113 it should only be used with a --fbo-format that has at least 16
7114 bits precisions. This is not usually recommended except for
7115 testing/specific purposes. Users are advised to either enable
7116 --sigmoid-upscaling or keep both options disabled (i.e. scaling
7117 in gamma light).
7118 --sigmoid-upscaling
7120 When upscaling, use a sigmoidal color transform to avoid empha‐
7121 sizing ringing artifacts. This is incompatible with and replaces
7122 --linear-upscaling. (Note that sigmoidization also requires lin‐
7123 earization, so the LINEAR rendering step fires in both cases)
7124 --sigmoid-center
7126 The center of the sigmoid curve used for --sigmoid-upscaling,
7127 must be a float between 0.0 and 1.0. Defaults to 0.75 if not
7128 specified.
7129 --sigmoid-slope
7131 The slope of the sigmoid curve used for --sigmoid-upscaling,
7132 must be a float between 1.0 and 20.0. Defaults to 6.5 if not
7133 specified.
7134 --interpolation
7136 Reduce stuttering caused by mismatches in the video fps and dis‐
7137 play refresh rate (also known as judder).
7138 WARNING:
7140 This requires setting the --video-sync option to one of the
7141 display- modes, or it will be silently disabled. This was
7142 not required before mpv 0.14.0.
7143 This essentially attempts to interpolate the missing frames by
7145 convoluting the video along the temporal axis. The filter used
7146 can be controlled using the --tscale setting.
7147 --interpolation-threshold=<0..1,-1>
7149 Threshold below which frame ratio interpolation gets disabled
7150 (default: 0.01). This is calculated as abs(disphz/vfps - 1) <
7151 threshold, where vfps is the speed-adjusted video FPS, and dis‐
7152 phz the display refresh rate. (The speed-adjusted video FPS is
7153 roughly equal to the normal video FPS, but with slowdown and
7154 speedup applied. This matters if you use --video-sync=dis‐
7155 play-resample to make video run synchronously to the display
7156 FPS, or if you change the speed property.)
7157 The default is intended to enable interpolation in scenarios
7159 where retiming with the --video-sync=display-* cannot adjust the
7160 speed of the video sufficiently for smooth playback. For example
7161 if a video is 60.00 FPS and your display refresh rate is 59.94
7162 Hz, interpolation will never be activated, since the mismatch is
7163 within 1% of the refresh rate. The default also handles the sce‐
7164 nario when mpv cannot determine the container FPS, such as dur‐
7165 ing certain live streams, and may dynamically toggle interpola‐
7166 tion on and off. In this scenario, the default would be to not
7167 use interpolation but rather to allow --video-sync=display-* to
7168 retime the video to match display refresh rate. See
7169 --video-sync-max-video-change for more information about how mpv
7170 will retime video.
7171 Also note that if you use e.g. --video-sync=display-vdrop, small
7173 deviations in the rate can disable interpolation and introduce a
7174 discontinuity every other minute.
7175 Set this to -1 to disable this logic.
7177 --interpolation-preserve
7179 Preserve the previous frames' interpolated results even when
7180 renderer parameters are changed - with the exception of options
7181 related to cropping and video placement, which always invalidate
7182 the cache. Enabling this option makes dynamic updates of ren‐
7183 derer settings slightly smoother at the cost of slightly higher
7184 latency in response to such changes. Defaults to on. (Only af‐
7185 fects --vo=gpu-next, note that --vo=gpu always invalidates in‐
7186 terpolated frames)
7187 --opengl-pbo
7189 Enable use of PBOs. On some drivers this can be faster, espe‐
7190 cially if the source video size is huge (e.g. so called "4K"
7191 video). On other drivers it might be slower or cause latency is‐
7192 sues.
7193 --dither-depth=<N|no|auto>
7195 Set dither target depth to N. Default: no.
7196 no Disable any dithering done by mpv.
7198 auto Automatic selection. If output bit depth cannot be de‐
7200 tected, 8 bits per component are assumed.
7201 8 Dither to 8 bit output.
7203 Note that the depth of the connected video display device cannot
7205 be detected. Often, LCD panels will do dithering on their own,
7206 which conflicts with this option and leads to ugly output.
7207 --dither-size-fruit=<2-8>
7209 Set the size of the dither matrix (default: 6). The actual size
7210 of the matrix is (2^N) x (2^N) for an option value of N, so a
7211 value of 6 gives a size of 64x64. The matrix is generated at
7212 startup time, and a large matrix can take rather long to compute
7213 (seconds).
7214 Used in --dither=fruit mode only.
7216 --dither=<fruit|ordered|error-diffusion|no>
7218 Select dithering algorithm (default: fruit). (Normally, the
7219 --dither-depth option controls whether dithering is enabled.)
7220 The error-diffusion option requires compute shader support. It
7222 also requires large amount of shared memory to run, the size of
7223 which depends on both the kernel (see --error-diffusion option
7224 below) and the height of video window. It will fallback to fruit
7225 dithering if there is no enough shared memory to run the shader.
7226 --temporal-dither
7228 Enable temporal dithering. (Only active if dithering is enabled
7229 in general.) This changes between 8 different dithering patterns
7230 on each frame by changing the orientation of the tiled dithering
7231 matrix. Unfortunately, this can lead to flicker on LCD displays,
7232 since these have a high reaction time.
7233 --temporal-dither-period=<1-128>
7235 Determines how often the dithering pattern is updated when
7236 --temporal-dither is in use. 1 (the default) will update on ev‐
7237 ery video frame, 2 on every other frame, etc.
7238 --error-diffusion=<kernel>
7240 The error diffusion kernel to use when --dither=error-diffusion
7241 is set.
7242 simple Propagate error to only two adjacent pixels. Fastest but
7244 low quality.
7245 sierra-lite
7247 Fast with reasonable quality. This is the default.
7248 floyd-steinberg
7250 Most notable error diffusion kernel.
7251 atkinson
7253 Looks different from other kernels because only fraction
7254 of errors will be propagated during dithering. A typical
7255 use case of this kernel is saving dithered screenshot (in
7256 window mode). This kernel produces slightly smaller file,
7257 with still reasonable dithering quality.
7258 There are other kernels (use --error-diffusion=help to list) but
7260 most of them are much slower and demanding even larger amount of
7261 shared memory. Among these kernels, burkes achieves a good bal‐
7262 ance between performance and quality, and probably is the one
7263 you want to try first.
7264 --gpu-debug
7266 Enables GPU debugging. What this means depends on the API type.
7267 For OpenGL, it calls glGetError(), and requests a debug context.
7268 For Vulkan, it enables validation layers.
7269 --opengl-swapinterval=<n>
7271 Interval in displayed frames between two buffer swaps. 1 is
7272 equivalent to enable VSYNC, 0 to disable VSYNC. Defaults to 1 if
7273 not specified.
7274 Note that this depends on proper OpenGL vsync support. On some
7276 platforms and drivers, this only works reliably when in
7277 fullscreen mode. It may also require driver-specific hacks if
7278 using multiple monitors, to ensure mpv syncs to the right one.
7279 Compositing window managers can also lead to bad results, as can
7280 missing or incorrect display FPS information (see --over‐
7281 ride-display-fps).
7282 --vulkan-device=<device name>
7284 The name of the Vulkan device to use for rendering and presenta‐
7285 tion. Use --vulkan-device=help to see the list of available de‐
7286 vices and their names. If left unspecified, the first enumerated
7287 hardware Vulkan device will be used.
7288 --vulkan-swap-mode=<mode>
7290 Controls the presentation mode of the vulkan swapchain. This is
7291 similar to the --opengl-swapinterval option.
7292 auto Use the preferred swapchain mode for the vulkan context.
7294 (Default)
7295 fifo Non-tearing, vsync blocked. Similar to "VSync on".
7297 fifo-relaxed
7299 Tearing, vsync blocked. Late frames will tear instead of
7300 stuttering.
7301 mailbox
7303 Non-tearing, not vsync blocked. Similar to "triple
7304 buffering".
7305 immediate
7307 Tearing, not vsync blocked. Similar to "VSync off".
7308 --vulkan-queue-count=<1..8>
7310 Controls the number of VkQueues used for rendering (limited by
7311 how many your device supports). In theory, using more queues
7312 could enable some parallelism between frames (when using a
7313 --swapchain-depth higher than 1), but it can also slow things
7314 down on hardware where there's no true parallelism between
7315 queues. (Default: 1)
7316 --vulkan-async-transfer
7318 Enables the use of async transfer queues on supported vulkan de‐
7319 vices. Using them allows transfer operations like texture up‐
7320 loads and blits to happen concurrently with the actual render‐
7321 ing, thus improving overall throughput and power consumption.
7322 Enabled by default, and should be relatively safe.
7323 --vulkan-async-compute
7325 Enables the use of async compute queues on supported vulkan de‐
7326 vices. Using this, in theory, allows out-of-order scheduling of
7327 compute shaders with graphics shaders, thus enabling the hard‐
7328 ware to do more effective work while waiting for pipeline bub‐
7329 bles and memory operations. Not beneficial on all GPUs. It's
7330 worth noting that if async compute is enabled, and the device
7331 supports more compute queues than graphics queues (bound by the
7332 restrictions set by --vulkan-queue-count), mpv will internally
7333 try and prefer the use of compute shaders over fragment shaders
7334 wherever possible. Enabled by default, although Nvidia users may
7335 want to disable it.
7336 --vulkan-display-display=<n>
7338 The index of the display, on the selected Vulkan device, to
7339 present on when using the displayvk GPU context. Use
7340 --vulkan-display-display=help to see the list of available dis‐
7341 plays. If left unspecified, the first enumerated display will be
7342 used.
7343 --vulkan-display-mode=<n>
7345 The index of the display mode, of the selected Vulkan display,
7346 to use when using the displayvk GPU context. Use --vulkan-dis‐
7347 play-mode=help to see the list of available modes. If left un‐
7348 specified, the first enumerated mode will be used.
7349 --vulkan-display-plane=<n>
7351 The index of the plane, on the selected Vulkan device, to
7352 present on when using the displayvk GPU context. Use
7353 --vulkan-display-plane=help to see the list of available planes.
7354 If left unspecified, the first enumerated plane will be used.
7355 --d3d11-exclusive-fs=<yes|no>
7357 Switches the D3D11 swap chain fullscreen state to 'fullscreen'
7358 when fullscreen video is requested. Also known as "exclusive
7359 fullscreen" or "D3D fullscreen" in other applications. Gives mpv
7360 full control of rendering on the swap chain's screen. Off by de‐
7361 fault.
7362 --d3d11-warp=<yes|no|auto>
7364 Use WARP (Windows Advanced Rasterization Platform) with the
7365 D3D11 GPU backend (default: auto). This is a high performance
7366 software renderer. By default, it is only used when the system
7367 has no hardware adapters that support D3D11. While the extended
7368 GPU features will work with WARP, they can be very slow.
7369 --d3d11-feature-level=<12_1|12_0|11_1|11_0|10_1|10_0|9_3|9_2|9_1>
7371 Select a specific feature level when using the D3D11 GPU back‐
7372 end. By default, the highest available feature level is used.
7373 This option can be used to select a lower feature level, which
7374 is mainly useful for debugging. Most extended GPU features will
7375 not work at 9_x feature levels.
7376 --d3d11-flip=<yes|no>
7378 Enable flip-model presentation, which avoids unnecessarily copy‐
7379 ing the backbuffer by sharing surfaces with the DWM (default:
7380 yes). This may cause performance issues with older drivers. If
7381 flip-model presentation is not supported (for example, on Win‐
7382 dows 7 without the platform update), mpv will automatically fall
7383 back to the older bitblt presentation model.
7384 --d3d11-sync-interval=<0..4>
7386 Schedule each frame to be presented for this number of VBlank
7387 intervals. (default: 1) Setting to 1 will enable VSync, setting
7388 to 0 will disable it.
7389 --d3d11-adapter=<adapter name|help>
7391 Select a specific D3D11 adapter to utilize for D3D11 rendering.
7392 Will pick the default adapter if unset. Alternatives are listed
7393 when the name "help" is given.
7394 Checks for matches based on the start of the string, case insen‐
7396 sitive. Thus, if the description of the adapter starts with the
7397 vendor name, that can be utilized as the selection parameter.
7398 Hardware decoders utilizing the D3D11 rendering abstraction's
7400 helper functionality to receive a device, such as D3D11VA or
7401 DXVA2's DXGI mode, will be affected by this choice.
7402 --d3d11-output-format=<auto|rgba8|bgra8|rgb10_a2|rgba16f>
7404 Select a specific D3D11 output format to utilize for D3D11 ren‐
7405 dering. "auto" is the default, which will pick either rgba8 or
7406 rgb10_a2 depending on the configured desktop bit depth. rgba16f
7407 and bgra8 are left out of the autodetection logic, and are
7408 available for manual testing.
7409 NOTE:
7411 Desktop bit depth querying is only available from an API
7412 available from Windows 10. Thus on older systems it will only
7413 automatically utilize the rgba8 output format.
7414 --d3d11-output-csp=<auto|srgb|linear|pq|bt.2020>
7416 Select a specific D3D11 output color space to utilize for D3D11
7417 rendering. "auto" is the default, which will select the color
7418 space of the desktop on which the swap chain is located.
7419 Values other than "srgb" and "pq" have had issues in testing, so
7421 they are mostly available for manual testing.
7422 NOTE:
7424 Swap chain color space configuration is only available from
7425 an API available from Windows 10. Thus on older systems it
7426 will not work.
7427 --d3d11va-zero-copy=<yes|no>
7429 By default, when using hardware decoding with --gpu-api=d3d11,
7430 the video image will be copied (GPU-to-GPU) from the decoder
7431 surface to a shader resource. Set this option to avoid that copy
7432 by sampling directly from the decoder image. This may increase
7433 performance and reduce power usage, but can cause the image to
7434 be sampled incorrectly on the bottom and right edges due to pad‐
7435 ding, and may invoke driver bugs, since Direct3D 11 technically
7436 does not allow sampling from a decoder surface (though most
7437 drivers support it.)
7438 Currently only relevant for --gpu-api=d3d11.
7440 --wayland-app-id=<string>
7442 Set the client app id for Wayland-based video output methods
7443 (default: mpv).
7444 --wayland-configure-bounds=<yes|no>
7446 Controls whether or not mpv opts into the configure bounds event
7447 if sent by the compositor (default: yes). This restricts the
7448 initial size of the mpv window to a certain maximum size in‐
7449 tended by the compositor. In most cases, this simply just pre‐
7450 vents the mpv window from being larger than the size of the mon‐
7451 itor when it first renders. This option will take precedence
7452 over any autofit or geometry type settings if the configure
7453 bounds are used.
7454 --wayland-disable-vsync=<yes|no>
7456 Disable mpv's internal vsync for Wayland-based video output (de‐
7457 fault: no). This is mainly useful for benchmarking wayland VOs
7458 when combined with video-sync=display-desync, --no-audio, and
7459 --untimed=yes.
7460 --wayland-edge-pixels-pointer=<value>
7462 Defines the size of an edge border (default: 10) to initiate
7463 client side resize events in the wayland contexts with the
7464 mouse. This is only active if there are no server side decora‐
7465 tions from the compositor.
7466 --wayland-edge-pixels-touch=<value>
7468 Defines the size of an edge border (default: 32) to initiate
7469 client side resizes events in the wayland contexts with touch
7470 events.
7471 --spirv-compiler=<compiler>
7473 Controls which compiler is used to translate GLSL to SPIR-V.
7474 This is (currently) only relevant for --gpu-api=vulkan and
7475 --gpu-api=d3d11. The possible choices are currently only:
7476 auto Use the first available compiler. (Default)
7478 shaderc
7480 Use libshaderc, which is an API wrapper around glslang.
7481 This is generally the most preferred, if available.
7482 NOTE:
7484 This option is deprecated, since there is only one reasonable
7485 value. It may be removed in the future.
7486 --glsl-shader=<file>, --glsl-shaders=<file-list>
7488 Custom GLSL hooks. These are a flexible way to add custom frag‐
7489 ment shaders, which can be injected at almost arbitrary points
7490 in the rendering pipeline, and access all previous intermediate
7491 textures.
7492 Each use of the --glsl-shader option will add another file to
7494 the internal list of shaders, while --glsl-shaders takes a list
7495 of files, and overwrites the internal list with it. The latter
7496 is a path list option (see List Options for details).
7497 Warning
7499 The syntax is not stable yet and may change any time.
7501 The general syntax of a user shader looks like this:
7503 //!METADATA ARGS...
7505 //!METADATA ARGS...
7506 vec4 hook() {
7508 ...
7509 return something;
7510 }
7511 //!METADATA ARGS...
7513 //!METADATA ARGS...
7514 ...
7516 Each section of metadata, along with the non-metadata lines af‐
7518 ter it, defines a single block. There are currently two types of
7519 blocks, HOOKs and TEXTUREs.
7520 A TEXTURE block can set the following options:
7522 TEXTURE <name> (required)
7524 The name of this texture. Hooks can then bind the texture
7525 under this name using BIND. This must be the first option
7526 of the texture block.
7527 SIZE <width> [<height>] [<depth>] (required)
7529 The dimensions of the texture. The height and depth are
7530 optional. The type of texture (1D, 2D or 3D) depends on
7531 the number of components specified.
7532 FORMAT <name> (required)
7534 The texture format for the samples. Supported texture
7535 formats are listed in debug logging when the gpu VO is
7536 initialized (look for Texture formats:). Usually, this
7537 follows OpenGL naming conventions. For example, rgb16
7538 provides 3 channels with normalized 16 bit components.
7539 One oddity are float formats: for example, rgba16f has 16
7540 bit internal precision, but the texture data is provided
7541 as 32 bit floats, and the driver converts the data on
7542 texture upload.
7543 Although format names follow a common naming convention,
7545 not all of them are available on all hardware, drivers,
7546 GL versions, and so on.
7547 FILTER <LINEAR|NEAREST>
7549 The min/magnification filter used when sampling from this
7550 texture.
7551 BORDER <CLAMP|REPEAT|MIRROR>
7553 The border wrapping mode used when sampling from this
7554 texture.
7555 Following the metadata is a string of bytes in hexadecimal nota‐
7557 tion that define the raw texture data, corresponding to the for‐
7558 mat specified by FORMAT, on a single line with no extra white‐
7559 space.
7560 A HOOK block can set the following options:
7562 HOOK <name> (required)
7564 The texture which to hook into. May occur multiple times
7565 within a metadata block, up to a predetermined limit. See
7566 below for a list of hookable textures.
7567 DESC <title>
7569 User-friendly description of the pass. This is the name
7570 used when representing this shader in the list of passes
7571 for property vo-passes.
7572 BIND <name>
7574 Loads a texture (either coming from mpv or from a TEXTURE
7575 block) and makes it available to the pass. When binding
7576 textures from mpv, this will also set up macros to facil‐
7577 itate accessing it properly. See below for a list. By de‐
7578 fault, no textures are bound. The special name HOOKED can
7579 be used to refer to the texture that triggered this pass.
7580 SAVE <name>
7582 Gives the name of the texture to save the result of this
7583 pass into. By default, this is set to the special name
7584 HOOKED which has the effect of overwriting the hooked
7585 texture.
7586 WIDTH <szexpr>, HEIGHT <szexpr>
7588 Specifies the size of the resulting texture for this
7589 pass. szexpr refers to an expression in RPN (reverse pol‐
7590 ish notation), using the operators + - * / > < !, float‐
7591 ing point literals, and references to sizes of existing
7592 texture (such as MAIN.width or CHROMA.height), OUTPUT, or
7593 NATIVE_CROPPED (size of an input texture cropped after
7594 pan-and-scan, video-align-x/y, video-pan-x/y, etc. and
7595 possibly prescaled). By default, these are set to
7596 HOOKED.w and HOOKED.h, espectively.
7597 WHEN <szexpr>
7599 Specifies a condition that needs to be true (non-zero)
7600 for the shader stage to be evaluated. If it fails, it
7601 will silently be omitted. (Note that a shader stage like
7602 this which has a dependency on an optional hook point can
7603 still cause that hook point to be saved, which has some
7604 minor overhead)
7605 OFFSET <ox oy | ALIGN>
7607 Indicates a pixel shift (offset) introduced by this pass.
7608 These pixel offsets will be accumulated and corrected
7609 during the next scaling pass (cscale or scale). The de‐
7610 fault values are 0 0 which correspond to no shift. Note
7611 that offsets are ignored when not overwriting the hooked
7612 texture.
7613 A special value of ALIGN will attempt to fix existing
7615 offset of HOOKED by align it with reference. It requires
7616 HOOKED to be resizable (see below). It works transpar‐
7617 ently with fragment shader. For compute shader, the pre‐
7618 defined texmap macro is required to handle coordinate
7619 mapping.
7620 COMPONENTS <n>
7622 Specifies how many components of this pass's output are
7623 relevant and should be stored in the texture, up to 4
7624 (rgba). By default, this value is equal to the number of
7625 components in HOOKED.
7626 COMPUTE <bw> <bh> [<tw> <th>]
7628 Specifies that this shader should be treated as a compute
7629 shader, with the block size bw and bh. The compute shader
7630 will be dispatched with however many blocks are necessary
7631 to completely tile over the output. Within each block,
7632 there will be tw*th threads, forming a single work group.
7633 In other words: tw and th specify the work group size,
7634 which can be different from the block size. So for exam‐
7635 ple, a compute shader with bw, bh = 32 and tw, th = 8
7636 running on a 500x500 texture would dispatch 16x16 blocks
7637 (rounded up), each with 8x8 threads.
7638 Compute shaders in mpv are treated a bit different from
7640 fragment shaders. Instead of defining a vec4 hook that
7641 produces an output sample, you directly define void hook
7642 which writes to a fixed writeonly image unit named
7643 out_image (this is bound by mpv) using imageStore. To
7644 help translate texture coordinates in the absence of ver‐
7645 tices, mpv provides a special function NAME_map(id) to
7646 map from the texel space of the output image to the tex‐
7647 ture coordinates for all bound textures. In particular,
7648 NAME_pos is equivalent to NAME_map(gl_GlobalInvoca‐
7649 tionID), although using this only really makes sense if
7650 (tw,th) == (bw,bh).
7651 Each bound mpv texture (via BIND) will make available the fol‐
7653 lowing definitions to that shader pass, where NAME is the name
7654 of the bound texture:
7655 vec4 NAME_tex(vec2 pos)
7657 The sampling function to use to access the texture at a
7658 certain spot (in texture coordinate space, range [0,1]).
7659 This takes care of any necessary normalization conver‐
7660 sions.
7661 vec4 NAME_texOff(vec2 offset)
7663 Sample the texture at a certain offset in pixels. This
7664 works like NAME_tex but additionally takes care of neces‐
7665 sary rotations, so that sampling at e.g. vec2(-1,0) is
7666 always one pixel to the left.
7667 vec2 NAME_pos
7669 The local texture coordinate of that texture, range
7670 [0,1].
7671 vec2 NAME_size
7673 The (rotated) size in pixels of the texture.
7674 mat2 NAME_rot
7676 The rotation matrix associated with this texture. (Ro‐
7677 tates pixel space to texture coordinates)
7678 vec2 NAME_pt
7680 The (unrotated) size of a single pixel, range [0,1].
7681 float NAME_mul
7683 The coefficient that needs to be multiplied into the tex‐
7684 ture contents in order to normalize it to the range
7685 [0,1].
7686 sampler NAME_raw
7688 The raw bound texture itself. The use of this should be
7689 avoided unless absolutely necessary.
7690 Normally, users should use either NAME_tex or NAME_texOff to
7692 read from the texture. For some shaders however , it can be bet‐
7693 ter for performance to do custom sampling from NAME_raw, in
7694 which case care needs to be taken to respect NAME_mul and
7695 NAME_rot.
7696 In addition to these parameters, the following uniforms are also
7698 globally available:
7699 float random
7701 A random number in the range [0-1], different per frame.
7702 int frame
7704 A simple count of frames rendered, increases by one per
7705 frame and never resets (regardless of seeks).
7706 vec2 input_size
7708 The size in pixels of the input image (possibly cropped
7709 and prescaled).
7710 vec2 target_size
7712 The size in pixels of the visible part of the scaled (and
7713 possibly cropped) image.
7714 vec2 tex_offset
7716 Texture offset introduced by user shaders or options like
7717 panscan, video-align-x/y, video-pan-x/y.
7718 Internally, vo_gpu may generate any number of the following tex‐
7720 tures. Whenever a texture is rendered and saved by vo_gpu, all
7721 of the passes that have hooked into it will run, in the order
7722 they were added by the user. This is a list of the legal hook
7723 points:
7724 RGB, LUMA, CHROMA, ALPHA, XYZ (resizable)
7726 Source planes (raw). Which of these fire depends on the
7727 image format of the source.
7728 CHROMA_SCALED, ALPHA_SCALED (fixed)
7730 Source planes (upscaled). These only fire on subsampled
7731 content.
7732 NATIVE (resizable)
7734 The combined image, in the source colorspace, before con‐
7735 version to RGB.
7736 MAINPRESUB (resizable)
7738 The image, after conversion to RGB, but before
7739 --blend-subtitles=video is applied.
7740 MAIN (resizable)
7742 The main image, after conversion to RGB but before up‐
7743 scaling.
7744 LINEAR (fixed)
7746 Linear light image, before scaling. This only fires when
7747 --linear-upscaling, --linear-downscaling or --sigmoid-up‐
7748 scaling is in effect.
7749 SIGMOID (fixed)
7751 Sigmoidized light, before scaling. This only fires when
7752 --sigmoid-upscaling is in effect.
7753 PREKERNEL (fixed)
7755 The image immediately before the scaler kernel runs.
7756 POSTKERNEL (fixed)
7758 The image immediately after the scaler kernel runs.
7759 SCALED (fixed)
7761 The final upscaled image, before color management.
7762 OUTPUT (fixed)
7764 The final output image, after color management but before
7765 dithering and drawing to screen.
7766 Only the textures labelled with resizable may be transformed by
7768 the pass. When overwriting a texture marked fixed, the WIDTH,
7769 HEIGHT and OFFSET must be left at their default values.
7770 --glsl-shader=<file>
7772 CLI/config file only alias for --glsl-shaders-append.
7773 --glsl-shader-opts=param1=value1,param2=value2,...
7775 Specifies the options to use for tunable shader parameters. You
7776 can target specific named shaders by prefixing the shader name
7777 with a /, e.g. shader/param=value. Without a prefix, parameters
7778 affect all shaders. The shader name is the base part of the
7779 shader filename, without the extension. (--vo=gpu-next only)
7780 --deband
7782 Enable the debanding algorithm. This greatly reduces the amount
7783 of visible banding, blocking and other quantization artifacts,
7784 at the expense of very slightly blurring some of the finest de‐
7785 tails. In practice, it's virtually always an improvement - the
7786 only reason to disable it would be for performance.
7787 --deband-iterations=<1..16>
7789 The number of debanding steps to perform per sample. Each step
7790 reduces a bit more banding, but takes time to compute. Note that
7791 the strength of each step falls off very quickly, so high num‐
7792 bers (>4) are practically useless. (Default 1)
7793 --deband-threshold=<0..4096>
7795 The debanding filter's cut-off threshold. Higher numbers in‐
7796 crease the debanding strength dramatically but progressively di‐
7797 minish image details. (Default 32)
7798 --deband-range=<1..64>
7800 The debanding filter's initial radius. The radius increases lin‐
7801 early for each iteration. A higher radius will find more gradi‐
7802 ents, but a lower radius will smooth more aggressively. (Default
7803 16)
7804 If you increase the --deband-iterations, you should probably de‐
7806 crease this to compensate.
7807 --deband-grain=<0..4096>
7809 Add some extra noise to the image. This significantly helps
7810 cover up remaining quantization artifacts. Higher numbers add
7811 more noise. (Default 48)
7812 --sharpen=<value>
7814 If set to a value other than 0, enable an unsharp masking fil‐
7815 ter. Positive values will sharpen the image (but add more ring‐
7816 ing and aliasing). Negative values will blur the image. If your
7817 GPU is powerful enough, consider alternatives like the ewa_lanc‐
7818 zossharp scale filter, or the --scale-blur option. (Only for
7819 --vo=gpu)
7820 --opengl-glfinish
7822 Call glFinish() before swapping buffers (default: disabled).
7823 Slower, but might improve results when doing framedropping. Can
7824 completely ruin performance. The details depend entirely on the
7825 OpenGL driver.
7826 --opengl-waitvsync
7828 Call glXWaitVideoSyncSGI after each buffer swap (default: dis‐
7829 abled). This may or may not help with video timing accuracy and
7830 frame drop. It's possible that this makes video output slower,
7831 or has no effect at all.
7832 X11/GLX only.
7834 --opengl-dwmflush=<no|windowed|yes|auto>
7836 Calls DwmFlush after swapping buffers on Windows (default:
7837 auto). It also sets SwapInterval(0) to ignore the OpenGL timing.
7838 Values are: no (disabled), windowed (only in windowed mode), yes
7839 (also in full screen).
7840 The value auto will try to determine whether the compositor is
7842 active, and calls DwmFlush only if it seems to be.
7843 This may help to get more consistent frame intervals, especially
7845 with high-fps clips - which might also reduce dropped frames.
7846 Typically, a value of windowed should be enough, since full
7847 screen may bypass the DWM.
7848 Windows only.
7850 --angle-d3d11-feature-level=<11_0|10_1|10_0|9_3>
7852 Selects a specific feature level when using the ANGLE backend
7853 with D3D11. By default, the highest available feature level is
7854 used. This option can be used to select a lower feature level,
7855 which is mainly useful for debugging. Note that OpenGL ES 3.0
7856 is only supported at feature level 10_1 or higher. Most ex‐
7857 tended OpenGL features will not work at lower feature levels
7858 (similar to --gpu-dumb-mode).
7859 Windows with ANGLE only.
7861 --angle-d3d11-warp=<yes|no|auto>
7863 Use WARP (Windows Advanced Rasterization Platform) when using
7864 the ANGLE backend with D3D11 (default: auto). This is a high
7865 performance software renderer. By default, it is used when the
7866 Direct3D hardware does not support Direct3D 11 feature level
7867 9_3. While the extended OpenGL features will work with WARP,
7868 they can be very slow.
7869 Windows with ANGLE only.
7871 --angle-egl-windowing=<yes|no|auto>
7873 Use ANGLE's built in EGL windowing functions to create a swap
7874 chain (default: auto). If this is set to no and the D3D11 ren‐
7875 derer is in use, ANGLE's built in swap chain will not be used
7876 and a custom swap chain that is optimized for video rendering
7877 will be created instead. If set to auto, a custom swap chain
7878 will be used for D3D11 and the built in swap chain will be used
7879 for D3D9. This option is mainly for debugging purposes, in case
7880 the custom swap chain has poor performance or does not work.
7881 If set to yes, the --angle-max-frame-latency, --an‐
7883 gle-swapchain-length and --angle-flip options will have no ef‐
7884 fect.
7885 Windows with ANGLE only.
7887 --angle-flip=<yes|no>
7889 Enable flip-model presentation, which avoids unnecessarily copy‐
7890 ing the backbuffer by sharing surfaces with the DWM (default:
7891 yes). This may cause performance issues with older drivers. If
7892 flip-model presentation is not supported (for example, on Win‐
7893 dows 7 without the platform update), mpv will automatically fall
7894 back to the older bitblt presentation model.
7895 If set to no, the --angle-swapchain-length option will have no
7897 effect.
7898 Windows with ANGLE only.
7900 --angle-renderer=<d3d9|d3d11|auto>
7902 Forces a specific renderer when using the ANGLE backend (de‐
7903 fault: auto). In auto mode this will pick D3D11 for systems that
7904 support Direct3D 11 feature level 9_3 or higher, and D3D9 other‐
7905 wise. This option is mainly for debugging purposes. Normally
7906 there is no reason to force a specific renderer, though --an‐
7907 gle-renderer=d3d9 may give slightly better performance on old
7908 hardware. Note that the D3D9 renderer only supports OpenGL ES
7909 2.0, so most extended OpenGL features will not work if this ren‐
7910 derer is selected (similar to --gpu-dumb-mode).
7911 Windows with ANGLE only.
7913 --macos-force-dedicated-gpu=<yes|no>
7915 Deactivates the automatic graphics switching and forces the ded‐
7916 icated GPU. (default: no)
7917 macOS only.
7919 --cocoa-cb-sw-renderer=<yes|no|auto>
7921 Use the Apple Software Renderer when using cocoa-cb (default:
7922 auto). If set to no the software renderer is never used and in‐
7923 stead fails when a the usual pixel format could not be created,
7924 yes will always only use the software renderer, and auto only
7925 falls back to the software renderer when the usual pixel format
7926 couldn't be created.
7927 macOS only.
7929 --cocoa-cb-10bit-context=<yes|no>
7931 Creates a 10bit capable pixel format for the context creation
7932 (default: yes). Instead of 8bit integer framebuffer a 16bit
7933 half-float framebuffer is requested.
7934 macOS only.
7936 --macos-title-bar-appearance=<appearance>
7938 Sets the appearance of the title bar (default: auto). Not all
7939 combinations of appearances and --macos-title-bar-material mate‐
7940 rials make sense or are unique. Appearances that are not sup‐
7941 ported by you current macOS version fall back to the default
7942 value. macOS and cocoa-cb only
7943 <appearance> can be one of the following:
7945 auto Detects the system settings and sets the title bar ap‐
7947 pearance appropriately. On macOS 10.14 it also detects
7948 run time changes.
7949 aqua The standard macOS Light appearance.
7951 darkAqua
7953 The standard macOS Dark appearance. (macOS 10.14+)
7954 vibrantLight
7956 Light vibrancy appearance with.
7957 vibrantDark
7959 Dark vibrancy appearance with.
7960 aquaHighContrast
7962 Light Accessibility appearance. (macOS 10.14+)
7963 darkAquaHighContrast
7965 Dark Accessibility appearance. (macOS 10.14+)
7966 vibrantLightHighContrast
7968 Light vibrancy Accessibility appearance. (macOS 10.14+)
7969 vibrantDarkHighContrast
7971 Dark vibrancy Accessibility appearance. (macOS 10.14+)
7972 --macos-title-bar-material=<material>
7974 Sets the material of the title bar (default: titlebar). All dep‐
7975 recated materials should not be used on macOS 10.14+ because
7976 their functionality is not guaranteed. Not all combinations of
7977 materials and --macos-title-bar-appearance appearances make
7978 sense or are unique. Materials that are not supported by you
7979 current macOS version fall back to the default value. macOS and
7980 cocoa-cb only
7981 <material> can be one of the following:
7983 titlebar
7985 The standard macOS titel bar material.
7986 selection
7988 The standard macOS selection material.
7989 menu The standard macOS menu material. (macOS 10.11+)
7991 popover
7993 The standard macOS popover material. (macOS 10.11+)
7994 sidebar
7996 The standard macOS sidebar material. (macOS 10.11+)
7997 headerView
7999 The standard macOS header view material. (macOS 10.14+)
8000 sheet The standard macOS sheet material. (macOS 10.14+)
8002 windowBackground
8004 The standard macOS window background material. (macOS
8005 10.14+)
8006 hudWindow
8008 The standard macOS hudWindow material. (macOS 10.14+)
8009 fullScreen
8011 The standard macOS full screen material. (macOS 10.14+)
8012 toolTip
8014 The standard macOS tool tip material. (macOS 10.14+)
8015 contentBackground
8017 The standard macOS content background material. (macOS
8018 10.14+)
8019 underWindowBackground
8021 The standard macOS under window background material.
8022 (macOS 10.14+)
8023 underPageBackground
8025 The standard macOS under page background material. (dep‐
8026 recated in macOS 10.14+)
8027 dark The standard macOS dark material. (deprecated in macOS
8029 10.14+)
8030 light The standard macOS light material. (macOS 10.14+)
8032 mediumLight
8034 The standard macOS mediumLight material. (macOS 10.11+,
8035 deprecated in macOS 10.14+)
8036 ultraDark
8038 The standard macOS ultraDark material. (macOS 10.11+
8039 deprecated in macOS 10.14+)
8040 --macos-title-bar-color=<color>
8042 Sets the color of the title bar (default: completely transpar‐
8043 ent). Is influenced by --macos-title-bar-appearance and
8044 --macos-title-bar-material. See --sub-color for color syntax.
8045 --macos-fs-animation-duration=<default|0-1000>
8047 Sets the fullscreen resize animation duration in ms (default:
8048 default). The default value is slightly less than the system's
8049 animation duration (500ms) to prevent some problems when the end
8050 of an async animation happens at the same time as the end of the
8051 system wide fullscreen animation. Setting anything higher than
8052 500ms will only prematurely cancel the resize animation after
8053 the system wide animation ended. The upper limit is still set at
8054 1000ms since it's possible that Apple or the user changes the
8055 system defaults. Anything higher than 1000ms though seems too
8056 long and shouldn't be set anyway. (macOS and cocoa-cb only)
8057 --macos-app-activation-policy=<regular|accessory|prohibited>
8059 Changes the App activation policy. With accessory the mpv icon
8060 in the Dock can be hidden. (default: regular)
8061 macOS only.
8063 --macos-geometry-calculation=<visible|whole>
8065 This changes the rectangle which is used to calculate the screen
8066 position and size of the window (default: visible). visible
8067 takes the the menu bar and Dock into account and the window is
8068 only positioned/sized within the visible screen frame rectangle,
8069 whole takes the whole screen frame rectangle and ignores the
8070 menu bar and Dock. Other previous restrictions still apply, like
8071 the window can't be placed on top of the menu bar etc.
8072 macOS only.
8074 --android-surface-size=<WxH>
8076 Set dimensions of the rendering surface used by the Android gpu
8077 context. Needs to be set by the embedding application if the
8078 dimensions change during runtime (i.e. if the device is ro‐
8079 tated), via the surfaceChanged callback.
8080 Android with --gpu-context=android only.
8082 --gpu-sw
8084 Continue even if a software renderer is detected.
8085 --gpu-context=<sys>
8087 The value auto (the default) selects the GPU context. You can
8088 also pass help to get a complete list of compiled in backends
8089 (sorted by autoprobe order).
8090 auto auto-select (default)
8092 cocoa Cocoa/macOS (deprecated, use --vo=libmpv instead)
8094 win Win32/WGL
8096 winvk VK_KHR_win32_surface
8098 angle Direct3D11 through the OpenGL ES translation layer ANGLE.
8100 This supports almost everything the win backend does (if
8101 the ANGLE build is new enough).
8102 dxinterop (experimental)
8104 Win32, using WGL for rendering and Direct3D 9Ex for pre‐
8105 sentation. Works on Nvidia and AMD. Newer Intel chips
8106 with the latest drivers may also work.
8107 d3d11 Win32, with native Direct3D 11 rendering.
8109 x11 X11/GLX
8111 x11vk VK_KHR_xlib_surface
8113 wayland
8115 Wayland/EGL
8116 waylandvk
8118 VK_KHR_wayland_surface
8119 drm DRM/EGL
8121 displayvk
8123 VK_KHR_display. This backend is roughly the Vukan equiva‐
8124 lent of DRM/EGL, allowing for direct rendering via Vulkan
8125 without a display manager.
8126 x11egl X11/EGL
8128 android
8130 Android/EGL. Requires --wid be set to an an‐
8131 droid.view.Surface.
8132 --gpu-api=<type>
8134 Controls which type of graphics APIs will be accepted:
8135 auto Use any available API (default)
8137 opengl Allow only OpenGL (requires OpenGL 2.1+ or GLES 2.0+)
8139 vulkan Allow only Vulkan (requires a valid/working --spirv-com‐
8141 piler)
8142 d3d11 Allow only --gpu-context=d3d11
8144 --opengl-es=<mode>
8146 Controls which type of OpenGL context will be accepted:
8147 auto Allow all types of OpenGL (default)
8149 yes Only allow GLES
8151 no Only allow desktop/core GL
8153 --fbo-format=<fmt>
8155 Selects the internal format of textures used for FBOs. The for‐
8156 mat can influence performance and quality of the video output.
8157 fmt can be one of: rgb8, rgb10, rgb10_a2, rgb16, rgb16f, rgb32f,
8158 rgba12, rgba16, rgba16f, rgba16hf, rgba32f.
8159 Default: auto, which first attempts to utilize 16bit float
8161 (rgba16f, rgba16hf), and falls back to rgba16 if those are not
8162 available. Finally, attempts to utilize rgb10_a2 or rgba8 if
8163 all of the previous formats are not available.
8164 --gamma-factor=<0.1..2.0>
8166 Set an additional raw gamma factor (default: 1.0). If gamma is
8167 adjusted in other ways (like with the --gamma option or key
8168 bindings and the gamma property), the value is multiplied with
8169 the other gamma value.
8170 This option is deprecated and may be removed in the future.
8172 --gamma-auto
8174 Automatically corrects the gamma value depending on ambient
8175 lighting conditions (adding a gamma boost for bright rooms).
8176 This option is deprecated and may be removed in the future.
8178 NOTE: Only implemented on macOS.
8180 --image-lut=<file>
8182 Specifies a custom LUT file (in Adobe .cube format) to apply to
8183 the colors during image decoding. The exact interpretation of
8184 the LUT depends on the value of --image-lut-type. (Only for
8185 --vo=gpu-next)
8186 --image-lut-type=<value>
8188 Controls the interpretation of color values fed to and from the
8189 LUT specified as --image-lut. Valid values are:
8190 auto Chooses the interpretation of the LUT automatically from
8192 tagged metadata, and otherwise falls back to native. (De‐
8193 fault)
8194 native Applied to the raw image contents in its native col‐
8196 orspace, before decoding to RGB. For example, for a HDR10
8197 image, this would be fed PQ-encoded YCbCr values in the
8198 range 0.0 - 1.0.
8199 normalized
8201 Applied to the normalized RGB image contents, after de‐
8202 coding from its native color encoding, but before lin‐
8203 earization.
8204 conversion
8206 Fully replaces the color decoding. A LUT of this type
8207 should ingest the image's native colorspace and output
8208 normalized non-linear RGB.
8209 --target-colorspace-hint
8211 Automatically configure the output colorspace of the display to
8212 pass through the input values of the stream (e.g. for HDR
8213 passthrough), if possible. Requires a supporting driver and
8214 --vo=gpu-next.
8215 --target-prim=<value>
8217 Specifies the primaries of the display. Video colors will be
8218 adapted to this colorspace when ICC color management is not be‐
8219 ing used. Valid values are:
8220 auto Disable any adaptation, except for atypical color spaces.
8222 Specifically, wide/unusual gamuts get automatically
8223 adapted to BT.709, while standard gamut (i.e. BT.601 and
8224 BT.709) content is not touched. (default)
8225 bt.470m
8227 ITU-R BT.470 M
8228 bt.601-525
8230 ITU-R BT.601 (525-line SD systems, eg. NTSC), SMPTE
8231 170M/240M
8232 bt.601-625
8234 ITU-R BT.601 (625-line SD systems, eg. PAL/SECAM), ITU-R
8235 BT.470 B/G
8236 bt.709 ITU-R BT.709 (HD), IEC 61966-2-4 (sRGB), SMPTE RP177 An‐
8238 nex B
8239 bt.2020
8241 ITU-R BT.2020 (UHD)
8242 apple Apple RGB
8244 adobe Adobe RGB (1998)
8246 prophoto
8248 ProPhoto RGB (ROMM)
8249 cie1931
8251 CIE 1931 RGB (not to be confused with CIE XYZ)
8252 dci-p3 DCI-P3 (Digital Cinema Colorspace), SMPTE RP431-2
8254 v-gamut
8256 Panasonic V-Gamut (VARICAM) primaries
8257 s-gamut
8259 Sony S-Gamut (S-Log) primaries
8260 --target-trc=<value>
8262 Specifies the transfer characteristics (gamma) of the display.
8263 Video colors will be adjusted to this curve when ICC color man‐
8264 agement is not being used. Valid values are:
8265 auto Disable any adaptation, except for atypical transfers.
8267 Specifically, HDR or linear light source material gets
8268 automatically converted to gamma 2.2, while SDR content
8269 is not touched. (default)
8270 bt.1886
8272 ITU-R BT.1886 curve (assuming infinite contrast)
8273 srgb IEC 61966-2-4 (sRGB)
8275 linear Linear light output
8277 gamma1.8
8279 Pure power curve (gamma 1.8), also used for Apple RGB
8280 gamma2.0
8282 Pure power curve (gamma 2.0)
8283 gamma2.2
8285 Pure power curve (gamma 2.2)
8286 gamma2.4
8288 Pure power curve (gamma 2.4)
8289 gamma2.6
8291 Pure power curve (gamma 2.6)
8292 gamma2.8
8294 Pure power curve (gamma 2.8), also used for BT.470-BG
8295 prophoto
8297 ProPhoto RGB (ROMM)
8298 pq ITU-R BT.2100 PQ (Perceptual quantizer) curve, aka SMPTE
8300 ST2084
8301 hlg ITU-R BT.2100 HLG (Hybrid Log-gamma) curve, aka ARIB
8303 STD-B67
8304 v-log Panasonic V-Log (VARICAM) curve
8306 s-log1 Sony S-Log1 curve
8308 s-log2 Sony S-Log2 curve
8310 NOTE:
8312 When using HDR output formats, mpv will encode to the speci‐
8313 fied curve but it will not set any HDMI flags or other sig‐
8314 nalling that might be required for the target device to cor‐
8315 rectly display the HDR signal. The user should independently
8316 guarantee this before using these signal formats for display.
8317 --target-peak=<auto|nits>
8319 Specifies the measured peak brightness of the output display, in
8320 cd/m^2 (AKA nits). The interpretation of this brightness depends
8321 on the configured --target-trc. In all cases, it imposes a limit
8322 on the signal values that will be sent to the display. If the
8323 source exceeds this brightness level, a tone mapping filter will
8324 be inserted. For HLG, it has the additional effect of
8325 parametrizing the inverse OOTF, in order to get colorimetrically
8326 consistent results with the mastering display. For SDR, or when
8327 using an ICC (profile (--icc-profile), setting this to a value
8328 above 203 essentially causes the display to be treated as if it
8329 were an HDR display in disguise. (See the note below)
8330 In auto mode (the default), the chosen peak is an appropriate
8332 value based on the TRC in use. For SDR curves, it uses 203. For
8333 HDR curves, it uses 203 * the transfer function's nominal peak.
8334 NOTE:
8336 When using an SDR transfer function, this is normally not
8337 needed, and setting it may lead to very unexpected results.
8338 The one time it is useful is if you want to calibrate a HDR
8339 display using traditional transfer functions and calibration
8340 equipment. In such cases, you can set your HDR display to a
8341 high brightness such as 800 cd/m^2, and then calibrate it to
8342 a standard curve like gamma2.8. Setting this value to 800
8343 would then instruct mpv to essentially treat it as an HDR
8344 display with the given peak. This may be a good alternative
8345 in environments where PQ or HLG input to the display is not
8346 possible, and makes it possible to use HDR displays with mpv
8347 regardless of operating system support for HDMI HDR metadata.
8348 In such a configuration, we highly recommend setting
8350 --tone-mapping to mobius or even clip.
8351 --target-lut=<file>
8353 Specifies a custom LUT file (in Adobe .cube format) to apply to
8354 the colors before display on-screen. This LUT is fed values in
8355 normalized RGB, after encoding into the target colorspace, so
8356 after the application of --target-trc. (Only for --vo=gpu-next)
8357 --tone-mapping=<value>
8359 Specifies the algorithm used for tone-mapping images onto the
8360 target display. This is relevant for both HDR->SDR conversion as
8361 well as gamut reduction (e.g. playing back BT.2020 content on a
8362 standard gamut display). Valid values are:
8363 auto Choose the best curve according to internal heuristics.
8365 (Default)
8366 clip Hard-clip any out-of-range values. Use this when you care
8368 about perfect color accuracy for in-range values at the
8369 cost of completely distorting out-of-range values. Not
8370 generally recommended.
8371 mobius Generalization of Reinhard to a Möbius transform with
8373 linear section. Smoothly maps out-of-range values while
8374 retaining contrast and colors for in-range material as
8375 much as possible. Use this when you care about color ac‐
8376 curacy more than detail preservation. This is somewhere
8377 in between clip and reinhard, depending on the value of
8378 --tone-mapping-param.
8379 reinhard
8381 Reinhard tone mapping algorithm. Very simple continuous
8382 curve. Preserves overall image brightness but uses non‐
8383 linear contrast, which results in flattening of details
8384 and degradation in color accuracy.
8385 hable Similar to reinhard but preserves both dark and bright
8387 details better (slightly sigmoidal), at the cost of
8388 slightly darkening / desaturating everything. Developed
8389 by John Hable for use in video games. Use this when you
8390 care about detail preservation more than color/brightness
8391 accuracy. This is roughly equivalent to --tone-map‐
8392 ping=reinhard --tone-mapping-param=0.24. If possible, you
8393 should also enable --hdr-compute-peak for the best re‐
8394 sults.
8395 bt.2390
8397 Perceptual tone mapping curve (EETF) specified in ITU-R
8398 Report BT.2390.
8399 gamma Fits a logarithmic transfer between the tone curves.
8401 linear Linearly stretches the entire reference gamut to (a lin‐
8403 ear multiple of) the display.
8404 spline Perceptually linear single-pivot polynomial.
8406 (--vo=gpu-next only)
8407 bt.2446a
8409 HDR<->SDR mapping specified in ITU-R Report BT.2446,
8410 method A. This is the recommended curve for well-mastered
8411 content. (--vo=gpu-next only)
8412 --tone-mapping-param=<value>
8414 Set tone mapping parameters. By default, this is set to the spe‐
8415 cial string default, which maps to an algorithm-specific default
8416 value. Ignored if the tone mapping algorithm is not tunable.
8417 This affects the following tone mapping algorithms:
8418 clip Specifies an extra linear coefficient to multiply into
8420 the signal before clipping. Defaults to 1.0.
8421 mobius Specifies the transition point from linear to mobius
8423 transform. Every value below this point is guaranteed to
8424 be mapped 1:1. The higher the value, the more accurate
8425 the result will be, at the cost of losing bright details.
8426 Defaults to 0.3, which due to the steep initial slope
8427 still preserves in-range colors fairly accurately.
8428 reinhard
8430 Specifies the local contrast coefficient at the display
8431 peak. Defaults to 0.5, which means that in-gamut values
8432 will be about half as bright as when clipping.
8433 bt.2390
8435 Specifies the offset for the knee point. Defaults to 1.0,
8436 which is higher than the value from the original ITU-R
8437 specification (0.5). (--vo=gpu-next only)
8438 gamma Specifies the exponent of the function. Defaults to 1.8.
8440 linear Specifies the scale factor to use while stretching. De‐
8442 faults to 1.0.
8443 spline Specifies the knee point (in PQ space). Defaults to 0.30.
8445 --inverse-tone-mapping
8447 If set, allows inverse tone mapping (expanding SDR to HDR). Not
8448 supported by all tone mapping curves. Use with caution.
8449 (--vo=gpu-next only)
8450 --tone-mapping-crosstalk=<0.0..0.30>
8452 If nonzero, apply an extra crosstalk matrix before tone mapping.
8453 Can help improve the appearance of strongly saturated monochro‐
8454 matic highlights. (Default: 0.04, only affects --vo=gpu-next)
8455 --tone-mapping-max-boost=<1.0..10.0>
8457 Upper limit for how much the tone mapping algorithm is allowed
8458 to boost the average brightness by over-exposing the image. The
8459 default value of 1.0 allows no additional brightness boost. A
8460 value of 2.0 would allow over-exposing by a factor of 2, and so
8461 on. Raising this setting can help reveal details that would oth‐
8462 erwise be hidden in dark scenes, but raising it too high will
8463 make dark scenes appear unnaturally bright. (--vo=gpu only)
8464 --tone-mapping-mode
8466 Controls how the tone mapping function is applied to colors.
8467 auto Choose the best mode automatically. (Default)
8469 rgb Tone-map per-channel (RGB). Has a tendency to severely
8471 distort colors, desaturate highlights, and is generally
8472 not very recommended. However, this is the mode used in
8473 many displays and TVs (especially early ones), and so
8474 sometimes it's needed to reproduce the artistic intent a
8475 film was mastered with.
8476 max Tone-map on the brightest component in the video. Has a
8478 tendency to lead to weirdly oversaturated colors, and
8479 loss of dark details.
8480 hybrid A hybrid approach that uses linear tone-mapping for mid‐
8482 tones and per-channel tone mapping for highlights.
8483 luma Luminance-based method from ITU-R BT.2446a, including
8485 fixed gamut reductions to account for brightness-related
8486 perceptual nonuniformity. (--vo=gpu-next only)
8487 --gamut-mapping-mode
8489 Specifies the algorithm used for reducing the gamut of images
8490 for the target display, after any tone mapping is done.
8491 auto Choose the best mode automatically. (Default)
8493 clip Hard-clip to the gamut (per-channel).
8495 warn Simply highlight out-of-gamut pixels.
8497 desaturate
8499 Chromatically desaturate out-of-gamut colors towards
8500 white.
8501 darken Linearly darken the entire image, then clip to the color
8503 volume. Unlike clip, this does not destroy detail in sat‐
8504 urated regions, but comes at the cost of sometimes sig‐
8505 nificantly lowering output brightness. (--vo=gpu-next
8506 only)
8507 --hdr-compute-peak=<auto|yes|no>
8509 Compute the HDR peak and frame average brightness per-frame in‐
8510 stead of relying on tagged metadata. These values are averaged
8511 over local regions as well as over several frames to prevent the
8512 value from jittering around too much. This option basically
8513 gives you dynamic, per-scene tone mapping. Requires compute
8514 shaders, which is a fairly recent OpenGL feature, and will prob‐
8515 ably also perform horribly on some drivers, so enable at your
8516 own risk. The special value auto (default) will enable HDR peak
8517 computation automatically if compute shaders and SSBOs are sup‐
8518 ported.
8519 --allow-delayed-peak-detect
8521 When using --hdr-compute-peak, allow delaying the detected peak
8522 by a frame when beneficial for performance. In particular, this
8523 is required to avoid an unnecessary FBO indirection when no ad‐
8524 vanced rendering is required otherwise. Has no effect if there
8525 already is an indirect pass, such as when advanced scaling is
8526 enabled. Defaults to on. (Only affects --vo=gpu-next, note that
8527 --vo=gpu always delays the peak.)
8528 --hdr-peak-decay-rate=<1.0..1000.0>
8530 The decay rate used for the HDR peak detection algorithm (de‐
8531 fault: 100.0). This is only relevant when --hdr-compute-peak is
8532 enabled. Higher values make the peak decay more slowly, leading
8533 to more stable values at the cost of more "eye adaptation"-like
8534 effects (although this is mitigated somewhat by
8535 --hdr-scene-threshold). A value of 1.0 (the lowest possible)
8536 disables all averaging, meaning each frame's value is used di‐
8537 rectly as measured, but doing this is not recommended for
8538 "noisy" sources since it may lead to excessive flicker. (In sig‐
8539 nal theory terms, this controls the time constant "tau" of an
8540 IIR low pass filter)
8541 --hdr-scene-threshold-low=<0.0..100.0>, --hdr-scene-thresh‐
8543 old-high=<0.0..100.0>
8544 The lower and upper thresholds (in dB) for a brightness differ‐
8545 ence to be considered a scene change (default: 5.5 low, 10.0
8546 high). This is only relevant when --hdr-compute-peak is enabled.
8547 Normally, small fluctuations in the frame brightness are compen‐
8548 sated for by the peak averaging mechanism, but for large jumps
8549 in the brightness this can result in the frame remaining too
8550 bright or too dark for up to several seconds, depending on the
8551 value of --hdr-peak-decay-rate. To counteract this, when the
8552 brightness between the running average and the current frame ex‐
8553 ceeds the low threshold, mpv will make the averaging filter more
8554 aggressive, up to the limit of the high threshold (at which
8555 point the filter becomes instant).
8556 --use-embedded-icc-profile
8558 Load the embedded ICC profile contained in media files such as
8559 PNG images. (Default: yes). Note that this option only works
8560 when also using a display ICC profile (--icc-profile or
8561 --icc-profile-auto), and also requires LittleCMS 2 support.
8562 --icc-profile=<file>
8564 Load an ICC profile and use it to transform video RGB to screen
8565 output. Needs LittleCMS 2 support compiled in. This option
8566 overrides the --target-prim, --target-trc and --icc-profile-auto
8567 options.
8568 --icc-profile-auto
8570 Automatically select the ICC display profile currently specified
8571 by the display settings of the operating system.
8572 NOTE: On Windows, the default profile must be an ICC profile.
8574 WCS profiles are not supported.
8575 Applications using libmpv with the render API need to provide
8577 the ICC profile via MPV_RENDER_PARAM_ICC_PROFILE.
8578 --icc-cache-dir=<dirname>
8580 Store and load the 3D LUTs created from the ICC profile in this
8581 directory. This can be used to speed up loading, since Lit‐
8582 tleCMS 2 can take a while to create a 3D LUT. Note that these
8583 files contain uncompressed LUTs. Their size depends on the
8584 --icc-3dlut-size, and can be very big.
8585 NOTE: This is not cleaned automatically, so old, unused cache
8587 files may stick around indefinitely.
8588 --icc-intent=<value>
8590 Specifies the ICC intent used for the color transformation (when
8591 using --icc-profile).
8592 0 perceptual
8594 1 relative colorimetric (default)
8596 2 saturation
8598 3 absolute colorimetric
8600 --icc-3dlut-size=<r>x<g>x<b>
8602 Size of the 3D LUT generated from the ICC profile in each dimen‐
8603 sion. Default is 64x64x64. Sizes may range from 2 to 512.
8604 --icc-force-contrast=<no|0-1000000|inf>
8606 Override the target device's detected contrast ratio by a spe‐
8607 cific value. This is detected automatically from the profile if
8608 possible, but for some profiles it might be missing, causing the
8609 contrast to be assumed as infinite. As a result, video may ap‐
8610 pear darker than intended. If this is the case, setting this op‐
8611 tion might help. This only affects BT.1886 content. The default
8612 of no means to use the profile values. The special value inf
8613 causes the BT.1886 curve to be treated as a pure power gamma 2.4
8614 function.
8615 --lut=<file>
8617 Specifies a custom LUT (in Adobe .cube format) to apply to the
8618 colors as part of color conversion. The exact interpretation de‐
8619 pends on the value of --lut-type. (Only for --vo=gpu-next)
8620 --lut-type=<value>
8622 Controls the interpretation of color values fed to and from the
8623 LUT specified as --lut. Valid values are:
8624 auto Chooses the interpretation of the LUT automatically from
8626 tagged metadata, and otherwise falls back to native. (De‐
8627 fault)
8628 native Applied to raw image contents in its native RGB col‐
8630 orspace (non-linear light), before conversion to the out‐
8631 put color space.
8632 normalized
8634 Applied to the normalized RGB image contents, in linear
8635 light, before conversion to the output color space.
8636 conversion
8638 Fully replaces the conversion from the image color space
8639 to the output color space. If such a LUT is present, it
8640 has the highest priority, and overrides any ICC profiles,
8641 as well as options related to tone mapping and output
8642 colorimetry (--target-prim, --target-trc etc.).
8643 --blend-subtitles=<yes|video|no>
8645 Blend subtitles directly onto upscaled video frames, before in‐
8646 terpolation and/or color management (default: no). Enabling this
8647 causes subtitles to be affected by --icc-profile, --target-prim,
8648 --target-trc, --interpolation, --gamma-factor and
8649 --glsl-shaders. It also increases subtitle performance when us‐
8650 ing --interpolation.
8651 The downside of enabling this is that it restricts subtitles to
8653 the visible portion of the video, so you can't have subtitles
8654 exist in the black margins below a video (for example).
8655 If video is selected, the behavior is similar to yes, but subs
8657 are drawn at the video's native resolution, and scaled along
8658 with the video.
8659 WARNING:
8661 This changes the way subtitle colors are handled. Normally,
8662 subtitle colors are assumed to be in sRGB and color managed
8663 as such. Enabling this makes them treated as being in the
8664 video's color space instead. This is good if you want things
8665 like softsubbed ASS signs to match the video colors, but may
8666 cause SRT subtitles or similar to look slightly off.
8667 --alpha=<blend-tiles|blend|yes|no>
8669 Decides what to do if the input has an alpha component.
8670 blend-tiles
8672 Blend the frame against a 16x16 gray/white tiles back‐
8673 ground (default).
8674 blend Blend the frame against the background color (--back‐
8676 ground, normally black).
8677 yes Try to create a framebuffer with alpha component. This
8679 only makes sense if the video contains alpha information
8680 (which is extremely rare) or if you make the background
8681 color transparent. May not be supported on all platforms.
8682 If alpha framebuffers are unavailable, it silently falls
8683 back on a normal framebuffer. Note that if you set the
8684 --fbo-format option to a non-default value, a format with
8685 alpha must be specified, or this won't work. Whether this
8686 really works depends on the windowing system and desktop
8687 environment.
8688 no Ignore alpha component.
8690 --opengl-rectangle-textures
8692 Force use of rectangle textures (default: no). Normally this
8693 shouldn't have any advantages over normal textures. Note that
8694 hardware decoding overrides this flag. Could be removed any
8695 time.
8696 --background=<color>
8698 Color used to draw parts of the mpv window not covered by video.
8699 See the --sub-color option for how colors are defined.
8700 --gpu-tex-pad-x, --gpu-tex-pad-y
8702 Enlarge the video source textures by this many pixels. For de‐
8703 bugging only (normally textures are sized exactly, but due to
8704 hardware decoding interop we may have to deal with additional
8705 padding, which can be tested with these options). Could be re‐
8706 moved any time.
8707 --opengl-early-flush=<yes|no|auto>
8709 Call glFlush() after rendering a frame and before attempting to
8710 display it (default: auto). Can fix stuttering in some cases, in
8711 other cases probably causes it. The auto mode will call
8712 glFlush() only if the renderer is going to wait for a while af‐
8713 ter rendering, instead of flipping GL front and backbuffers im‐
8714 mediately (i.e. it doesn't call it in display-sync mode).
8715 On macOS this is always deactivated because it only causes per‐
8717 formance problems and other regressions.
8718 --gpu-dumb-mode=<yes|no|auto>
8720 This mode is extremely restricted, and will disable most ex‐
8721 tended features. That includes high quality scalers and custom
8722 shaders!
8723 It is intended for hardware that does not support FBOs (includ‐
8725 ing GLES, which supports it insufficiently), or to get some more
8726 performance out of bad or old hardware.
8727 This mode is forced automatically if needed, and this option is
8729 mostly useful for debugging. The default of auto will enable it
8730 automatically if nothing uses features which require FBOs.
8731 This option might be silently removed in the future.
8733 --gpu-shader-cache-dir=<dirname>
8735 Store and load compiled GLSL shaders in this directory. Nor‐
8736 mally, shader compilation is very fast, so this is usually not
8737 needed. It mostly matters for GPU APIs that require internally
8738 recompiling shaders to other languages, for example anything
8739 based on ANGLE or Vulkan. Enabling this can improve startup per‐
8740 formance on these platforms.
8741 NOTE: This is not cleaned automatically, so old, unused cache
8743 files may stick around indefinitely.
8744 Miscellaneous
8746 --display-tags=tag1,tags2,...
8747 Set the list of tags that should be displayed on the terminal.
8748 Tags that are in the list, but are not present in the played
8749 file, will not be shown. If a value ends with *, all tags are
8750 matched by prefix (though there is no general globbing). Just
8751 passing * essentially filtering.
8752 The default includes a common list of tags, call mpv with
8754 --list-options to see it.
8755 This is a string list option. See List Options for details.
8757 --mc=<seconds/frame>
8759 Maximum A-V sync correction per frame (in seconds)
8760 --autosync=<factor>
8762 Gradually adjusts the A/V sync based on audio delay measure‐
8763 ments. Specifying --autosync=0, the default, will cause frame
8764 timing to be based entirely on audio delay measurements. Speci‐
8765 fying --autosync=1 will do the same, but will subtly change the
8766 A/V correction algorithm. An uneven video framerate in a video
8767 which plays fine with --no-audio can often be helped by setting
8768 this to an integer value greater than 1. The higher the value,
8769 the closer the timing will be to --no-audio. Try --autosync=30
8770 to smooth out problems with sound drivers which do not implement
8771 a perfect audio delay measurement. With this value, if large A/V
8772 sync offsets occur, they will only take about 1 or 2 seconds to
8773 settle out. This delay in reaction time to sudden A/V offsets
8774 should be the only side effect of turning this option on, for
8775 all sound drivers.
8776 --video-timing-offset=<seconds>
8778 Control how long before video display target time the frame
8779 should be rendered (default: 0.050). If a video frame should be
8780 displayed at a certain time, the VO will start rendering the
8781 frame earlier, and then will perform a blocking wait until the
8782 display time, and only then "swap" the frame to display. The
8783 rendering cannot start before the previous frame is displayed,
8784 so this value is implicitly limited by the video framerate. With
8785 normal video frame rates, the default value will ensure that
8786 rendering is always immediately started after the previous frame
8787 was displayed. On the other hand, setting a too high value can
8788 reduce responsiveness with low FPS value.
8789 This option is interesting for client API users using the render
8791 API because you can stop it from limiting your FPS (see mpv_ren‐
8792 der_context_render() documentation).
8793 This applies only to audio timing modes (e.g. --video-sync=au‐
8795 dio). In other modes (--video-sync=display-...), video timing
8796 relies on vsync blocking, and this option is not used.
8797 --video-sync=<audio|...>
8799 How the player synchronizes audio and video.
8800 If you use this option, you usually want to set it to dis‐
8802 play-resample to enable a timing mode that tries to not skip or
8803 repeat frames when for example playing 24fps video on a 24Hz
8804 screen.
8805 The modes starting with display- try to output video frames com‐
8807 pletely synchronously to the display, using the detected display
8808 vertical refresh rate as a hint how fast frames will be dis‐
8809 played on average. These modes change video speed slightly to
8810 match the display. See --video-sync-... options for fine tun‐
8811 ing. The robustness of this mode is further reduced by making a
8812 some idealized assumptions, which may not always apply in real‐
8813 ity. Behavior can depend on the VO and the system's video and
8814 audio drivers. Media files must use constant framerate. Sec‐
8815 tion-wise VFR might work as well with some container formats
8816 (but not e.g. mkv).
8817 Under some circumstances, the player automatically reverts to
8819 audio mode for some time or permanently. This can happen on very
8820 low framerate video, or if the framerate cannot be detected.
8821 Also in display-sync modes it can happen that interruptions to
8823 video playback (such as toggling fullscreen mode, or simply re‐
8824 sizing the window) will skip the video frames that should have
8825 been displayed, while audio mode will display them after the
8826 renderer has resumed (typically resulting in a short A/V desync
8827 and the video "catching up").
8828 Before mpv 0.30.0, there was a fallback to audio mode on severe
8830 A/V desync. This was changed for the sake of not sporadically
8831 stopping. Now, display-desync does what it promises and may
8832 desync with audio by an arbitrary amount, until it is manually
8833 fixed with a seek.
8834 These modes also require a vsync blocked presentation mode. For
8836 OpenGL, this translates to --opengl-swapinterval=1. For Vulkan,
8837 it translates to --vulkan-swap-mode=fifo (or fifo-relaxed).
8838 The modes with desync in their names do not attempt to keep au‐
8840 dio/video in sync. They will slowly (or quickly) desync, until
8841 e.g. the next seek happens. These modes are meant for testing,
8842 not serious use.
8843 audio Time video frames to audio. This is the most robust mode,
8845 because the player doesn't have to assume anything about
8846 how the display behaves. The disadvantage is that it can
8847 lead to occasional frame drops or repeats. If audio is
8848 disabled, this uses the system clock. This is the default
8849 mode.
8850 display-resample
8852 Resample audio to match the video. This mode will also
8853 try to adjust audio speed to compensate for other drift.
8854 (This means it will play the audio at a different speed
8855 every once in a while to reduce the A/V difference.)
8856 display-resample-vdrop
8858 Resample audio to match the video. Drop video frames to
8859 compensate for drift.
8860 display-resample-desync
8862 Like the previous mode, but no A/V compensation.
8863 display-vdrop
8865 Drop or repeat video frames to compensate desyncing
8866 video. (Although it should have the same effects as au‐
8867 dio, the implementation is very different.)
8868 display-adrop
8870 Drop or repeat audio data to compensate desyncing video.
8871 This mode will cause severe audio artifacts if the real
8872 monitor refresh rate is too different from the reported
8873 or forced rate. Since mpv 0.33.0, this acts on entire au‐
8874 dio frames, instead of single samples.
8875 display-desync
8877 Sync video to display, and let audio play on its own.
8878 desync Sync video according to system clock, and let audio play
8880 on its own.
8881 --video-sync-max-factor=<value>
8883 Maximum multiple for which to try to fit the video's FPS to the
8884 display's FPS (default: 5).
8885 For example, if this is set to 1, the video FPS is forced to an
8887 integer multiple of the display FPS, as long as the speed change
8888 does not exceed the value set by --video-sync-max-video-change.
8889 See --interpolation-threshold for how this option affects inter‐
8891 polation.
8892 This is mostly for testing, and the option may be randomly
8894 changed in the future without notice.
8895 --video-sync-max-video-change=<value>
8897 Maximum speed difference in percent that is applied to video
8898 with --video-sync=display-... (default: 1). Display sync mode
8899 will be disabled if the monitor and video refresh way do not
8900 match within the given range. It tries multiples as well: play‐
8901 ing 30 fps video on a 60 Hz screen will duplicate every second
8902 frame. Playing 24 fps video on a 60 Hz screen will play video in
8903 a 2-3-2-3-... pattern.
8904 The default settings are not loose enough to speed up 23.976 fps
8906 video to 25 fps. We consider the pitch change too extreme to al‐
8907 low this behavior by default. Set this option to a value of 5 to
8908 enable it.
8909 Note that in the --video-sync=display-resample mode, audio speed
8911 will additionally be changed by a small amount if necessary for
8912 A/V sync. See --video-sync-max-audio-change.
8913 --video-sync-max-audio-change=<value>
8915 Maximum additional speed difference in percent that is applied
8916 to audio with --video-sync=display-... (default: 0.125). Nor‐
8917 mally, the player plays the audio at the speed of the video. But
8918 if the difference between audio and video position is too high,
8919 e.g. due to drift or other timing errors, it will attempt to
8920 speed up or slow down audio by this additional factor. Too low
8921 values could lead to video frame dropping or repeating if the
8922 A/V desync cannot be compensated, too high values could lead to
8923 chaotic frame dropping due to the audio "overshooting" and skip‐
8924 ping multiple video frames before the sync logic can react.
8925 --mf-fps=<value>
8927 Framerate used when decoding from multiple PNG or JPEG files
8928 with mf:// (default: 1).
8929 --mf-type=<value>
8931 Input file type for mf:// (available: jpeg, png, tga, sgi). By
8932 default, this is guessed from the file extension.
8933 --stream-dump=<destination-filename>
8935 Instead of playing a file, read its byte stream and write it to
8936 the given destination file. The destination is overwritten. Can
8937 be useful to test network-related behavior.
8938 --stream-lavf-o=opt1=value1,opt2=value2,...
8940 Set AVOptions on streams opened with libavformat. Unknown or
8941 misspelled options are silently ignored. (They are mentioned in
8942 the terminal output in verbose mode, i.e. --v. In general we
8943 can't print errors, because other options such as e.g. user
8944 agent are not available with all protocols, and printing errors
8945 for unknown options would end up being too noisy.)
8946 This is a key/value list option. See List Options for details.
8948 --vo-mmcss-profile=<name>
8950 (Windows only.) Set the MMCSS profile for the video renderer
8951 thread (default: Playback).
8952 --priority=<prio>
8954 (Windows only.) Set process priority for mpv according to the
8955 predefined priorities available under Windows.
8956 Possible values of <prio>: idle|belownormal|normal|abovenor‐
8958 mal|high|realtime
8959 WARNING:
8961 Using realtime priority can cause system lockup.
8962 --force-media-title=<string>
8964 Force the contents of the media-title property to this value.
8965 Useful for scripts which want to set a title, without overriding
8966 the user's setting in --title.
8967 --external-files=<file-list>
8969 Load a file and add all of its tracks. This is useful to play
8970 different files together (for example audio from one file, video
8971 from another), or for advanced --lavfi-complex used (like play‐
8972 ing two video files at the same time).
8973 Unlike --sub-files and --audio-files, this includes all tracks,
8975 and does not cause default stream selection over the "proper"
8976 file. This makes it slightly less intrusive. (In mpv 0.28.0 and
8977 before, this was not quite strictly enforced.)
8978 This is a path list option. See List Options for details.
8980 --external-file=<file>
8982 CLI/config file only alias for --external-files-append. Each use
8983 of this option will add a new external file.
8984 --cover-art-files=<file-list>
8986 Use an external file as cover art while playing audio. This
8987 makes it appear on the track list and subject to automatic track
8988 selection. Options like --audio-display control whether such
8989 tracks are supposed to be selected.
8990 (The difference to loading a file with --external-files is that
8992 video tracks will be marked as being pictures, which affects the
8993 auto-selection method. If the passed file is a video, only the
8994 first frame will be decoded and displayed. Enabling the cover
8995 art track during playback may show a random frame if the source
8996 file is a video. Normally you're not supposed to pass videos to
8997 this option, so this paragraph describes the behavior coinciden‐
8998 tally resulting from implementation details.)
8999 This is a path list option. See List Options for details.
9001 --cover-art-file=<file>
9003 CLI/config file only alias for --cover-art-files-append. Each
9004 use of this option will add a new external file.
9005 --cover-art-auto=<no|exact|fuzzy|all>
9007 Whether to load _external_ cover art automatically. Similar to
9008 --sub-auto and --audio-file-auto. If a video already has tracks
9009 (which are not marked as cover art), external cover art will not
9010 be loaded.
9011 no Don't automatically load cover art.
9013 exact Load the media filename with an image file extension (de‐
9015 fault).
9016 fuzzy Load all cover art containing the media filename.
9018 all Load all images in the current directory.
9020 See --cover-art-files for details about what constitutes cover
9022 art.
9023 See --audio-display how to control display of cover art (this
9025 can be used to disable cover art that is part of the file).
9026 --cover-art-whitelist=<no|yes>
9028 Whether to load filenames in an internal whitelist, such as
9029 cover.jpg, as cover art. If cover-art-auto is set to no, the
9030 whitelisted filenames are never loaded even if this option is
9031 set to yes.
9032 Default: yes.
9034 --autoload-files=<yes|no>
9036 Automatically load/select external files (default: yes).
9037 If set to no, then do not automatically load external files as
9039 specified by --sub-auto, --audio-file-auto and --cover-art-auto.
9040 If external files are forcibly added (like with --sub-files),
9041 they will not be auto-selected.
9042 This does not affect playlist expansion, redirection, or other
9044 loading of referenced files like with ordered chapters.
9045 --record-file=<file>
9047 Deprecated, use --stream-record, or the dump-cache command.
9048 Record the current stream to the given target file. The target
9050 file will always be overwritten without asking.
9051 This was deprecated because it isn't very nice to use. For one,
9053 seeking while this is enabled will be directly reflected in the
9054 output, which was not useful and annoying.
9055 --stream-record=<file>
9057 Write received/read data from the demuxer to the given output
9058 file. The output file will always be overwritten without asking.
9059 The output format is determined by the extension of the output
9060 file.
9061 Switching streams or seeking during recording might result in
9063 recording being stopped and/or broken files. Use with care.
9064 Seeking outside of the demuxer cache will result in "skips" in
9066 the output file, but seeking within the demuxer cache should
9067 not affect recording. One exception is when you seek back far
9068 enough to exceed the forward buffering size, in which case the
9069 cache stops actively reading. This will return in dropped data
9070 if it's a live stream.
9071 If this is set at runtime, the old file is closed, and the new
9073 file is opened. Note that this will write only data that is ap‐
9074 pended at the end of the cache, and the already cached data can‐
9075 not be written. You can try the dump-cache command as an alter‐
9076 native.
9077 External files (--audio-file etc.) are ignored by this, it works
9079 on the "main" file only. Using this with files using ordered
9080 chapters or EDL files will also not work correctly in general.
9081 There are some glitches with this because it uses FFmpeg's
9083 libavformat for writing the output file. For example, it's typi‐
9084 cal that it will only work if the output format is the same as
9085 the input format. This is the case even if it works with the
9086 ffmpeg tool. One reason for this is that ffmpeg and its li‐
9087 braries contain certain hacks and workarounds for these issues,
9088 that are unavailable to outside users.
9089 This replaces --record-file. It is similar to the ancient/re‐
9091 moved --stream-capture/--capture options, and provides better
9092 behavior in most cases (i.e. actually works).
9093 --lavfi-complex=<string>
9095 Set a "complex" libavfilter filter, which means a single filter
9096 graph can take input from multiple source audio and video
9097 tracks. The graph can result in a single audio or video output
9098 (or both).
9099 Currently, the filter graph labels are used to select the par‐
9101 ticipating input tracks and audio/video output. The following
9102 rules apply:
9103 • A label of the form aidN selects audio track N as input (e.g.
9105 aid1).
9106 • A label of the form vidN selects video track N as input.
9108 • A label named ao will be connected to the audio output.
9110 • A label named vo will be connected to the video output.
9112 Each label can be used only once. If you want to use e.g. an au‐
9114 dio stream for multiple filters, you need to use the asplit fil‐
9115 ter. Multiple video or audio outputs are not possible, but you
9116 can use filters to merge them into one.
9117 It's not possible to change the tracks connected to the filter
9119 at runtime, unless you explicitly change the lavfi-complex prop‐
9120 erty and set new track assignments. When the graph is changed,
9121 the track selection is changed according to the used labels as
9122 well.
9123 Other tracks, as long as they're not connected to the filter,
9125 and the corresponding output is not connected to the filter, can
9126 still be freely changed with the normal methods.
9127 Note that the normal filter chains (--af, --vf) are applied be‐
9129 tween the complex graphs (e.g. ao label) and the actual output.
9130 Examples
9132 • --lavfi-complex='[aid1] [aid2] amix [ao]' Play audio track
9134 1 and 2 at the same time.
9135 • --lavfi-complex='[vid1] [vid2] vstack [vo]' Stack video
9137 track 1 and 2 and play them at the same time. Note that
9138 both tracks need to have the same width, or filter initial‐
9139 ization will fail (you can add scale filters before the vs‐
9140 tack filter to fix the size). To load a video track from
9141 another file, you can use --external-file=other.mkv.
9142 • --lavfi-complex='[aid1] asplit [t1] [ao] ; [t1] showvolume
9144 [t2] ; [vid1] [t2] overlay [vo]' Play audio track 1, and
9145 overlay the measured volume for each speaker over video
9146 track 1.
9147 • null:// --lavfi-complex='life [vo]' A libavfilter
9149 source-only filter (Conways' Life Game).
9150 See the FFmpeg libavfilter documentation for details on the
9152 available filters.
9153 --metadata-codepage=<codepage>
9155 Codepage for various input metadata (default: utf-8). This af‐
9156 fects how file tags, chapter titles, etc. are interpreted. You
9157 can for example set this to auto to enable autodetection of the
9158 codepage. (This is not the default because non-UTF-8 codepages
9159 are an obscure fringe use-case.)
9160 See --sub-codepage option on how codepages are specified and
9162 further details regarding autodetection and codepage conversion.
9163 (The underlying code is the same.)
9164 Conversion is not applied to metadata that is updated at run‐
9166 time.
9167 Debugging
9169 --unittest=<name>
9170 Run an internal unit test. There are multiple, and the name
9171 specifies which.
9172 The special value all-simple runs all tests which do not need
9174 further setup (other arguments and such). Some tests may need
9175 additional arguments to do anything useful.
9176 On success, the player binary exits with exit status 0, other‐
9178 wise it returns with an undefined non-0 exit status (it may
9179 crash or abort itself on test failures).
9180 This is only enabled if built with --enable-tests, and should
9182 normally be enabled and used by developers only.
9183
9185 Audio output drivers are interfaces to different audio output facili‐
9186 ties. The syntax is:
9187 --ao=<driver1,driver2,...[,]>
9189 Specify a priority list of audio output drivers to be used.
9190 If the list has a trailing ',', mpv will fall back on drivers not con‐
9192 tained in the list.
9193 NOTE:
9195 See --ao=help for a list of compiled-in audio output drivers. The
9196 driver --ao=alsa is preferred. --ao=pulse is preferred on systems
9197 where PulseAudio is used. On BSD systems, --ao=oss is preferred.
9198 Available audio output drivers are:
9200 alsa (Linux only)
9202 ALSA audio output driver
9203 See ALSA audio output options for options specific to this AO.
9205 WARNING:
9207 To get multichannel/surround audio, use --audio-chan‐
9208 nels=auto. The default for this option is auto-safe, which
9209 makes this audio output explicitly reject multichannel out‐
9210 put, as there is no way to detect whether a certain channel
9211 layout is actually supported.
9212 You can also try using the upmix plugin. This setup enables
9214 multichannel audio on the default device with automatic up‐
9215 mixing with shared access, so playing stereo and multichannel
9216 audio at the same time will work as expected.
9217 oss OSS audio output driver
9219 jack JACK (Jack Audio Connection Kit) audio output driver.
9221 The following global options are supported by this audio output:
9223 --jack-port=<name>
9225 Connects to the ports with the given name (default: phys‐
9226 ical ports).
9227 --jack-name=<client>
9229 Client name that is passed to JACK (default: mpv). Useful
9230 if you want to have certain connections established auto‐
9231 matically.
9232 --jack-autostart=<yes|no>
9234 Automatically start jackd if necessary (default: dis‐
9235 abled). Note that this tends to be unreliable and will
9236 flood stdout with server messages.
9237 --jack-connect=<yes|no>
9239 Automatically create connections to output ports (de‐
9240 fault: enabled). When enabled, the maximum number of
9241 output channels will be limited to the number of avail‐
9242 able output ports.
9243 --jack-std-channel-layout=<waveext|any>
9245 Select the standard channel layout (default: waveext).
9246 JACK itself has no notion of channel layouts (i.e. as‐
9247 signing which speaker a given channel is supposed to map
9248 to) - it just takes whatever the application outputs, and
9249 reroutes it to whatever the user defines. This means the
9250 user and the application are in charge of dealing with
9251 the channel layout. waveext uses WAVE_FORMAT_EXTENSIBLE
9252 order, which, even though it was defined by Microsoft, is
9253 the standard on many systems. The value any makes JACK
9254 accept whatever comes from the audio filter chain, re‐
9255 gardless of channel layout and without reordering. This
9256 mode is probably not very useful, other than for debug‐
9257 ging or when used with fixed setups.
9258 coreaudio (macOS only)
9260 Native macOS audio output driver using AudioUnits and the Core‐
9261 Audio sound server.
9262 Automatically redirects to coreaudio_exclusive when playing com‐
9264 pressed formats.
9265 The following global options are supported by this audio output:
9267 --coreaudio-change-physical-format=<yes|no>
9269 Change the physical format to one similar to the re‐
9270 quested audio format (default: no). This has the advan‐
9271 tage that multichannel audio output will actually work.
9272 The disadvantage is that it will change the system-wide
9273 audio settings. This is equivalent to changing the Format
9274 setting in the Audio Devices dialog in the Audio MIDI
9275 Setup utility. Note that this does not affect the se‐
9276 lected speaker setup.
9277 --coreaudio-spdif-hack=<yes|no>
9279 Try to pass through AC3/DTS data as PCM. This is useful
9280 for drivers which do not report AC3 support. It converts
9281 the AC3 data to float, and assumes the driver will do the
9282 inverse conversion, which means a typical A/V receiver
9283 will pick it up as compressed IEC framed AC3 stream, ig‐
9284 noring that it's marked as PCM. This disables normal AC3
9285 passthrough (even if the device reports it as supported).
9286 Use with extreme care.
9287 coreaudio_exclusive (macOS only)
9289 Native macOS audio output driver using direct device access and
9290 exclusive mode (bypasses the sound server).
9291 openal OpenAL audio output driver.
9293 --openal-num-buffers=<2-128>
9295 Specify the number of audio buffers to use. Lower values
9296 are better for lower CPU usage. Default: 4.
9297 --openal-num-samples=<256-32768>
9299 Specify the number of complete samples to use for each
9300 buffer. Higher values are better for lower CPU usage. De‐
9301 fault: 8192.
9302 --openal-direct-channels=<yes|no>
9304 Enable OpenAL Soft's direct channel extension when avail‐
9305 able to avoid tinting the sound with ambisonics or HRTF.
9306 Default: yes.
9307 pulse PulseAudio audio output driver
9309 The following global options are supported by this audio output:
9311 --pulse-host=<host>
9313 Specify the host to use. An empty <host> string uses a
9314 local connection, "localhost" uses network transfer (most
9315 likely not what you want).
9316 --pulse-buffer=<1-2000|native>
9318 Set the audio buffer size in milliseconds. A higher value
9319 buffers more data, and has a lower probability of buffer
9320 underruns. A smaller value makes the audio stream react
9321 faster, e.g. to playback speed changes.
9322 --pulse-latency-hacks=<yes|no>
9324 Enable hacks to workaround PulseAudio timing bugs (de‐
9325 fault: no). If enabled, mpv will do elaborate latency
9326 calculations on its own. If disabled, it will use
9327 PulseAudio automatically updated timing information. Dis‐
9328 abling this might help with e.g. networked audio or some
9329 plugins, while enabling it might help in some unknown
9330 situations (it used to be required to get good behavior
9331 on old PulseAudio versions).
9332 If you have stuttering video when using pulse, try to en‐
9334 able this option. (Or try to update PulseAudio.)
9335 --pulse-allow-suspended=<yes|no>
9337 Allow mpv to use PulseAudio even if the sink is suspended
9338 (default: no). Can be useful if PulseAudio is running as
9339 a bridge to jack and mpv has its sink-input set to the
9340 one jack is using.
9341 pipewire
9343 PipeWire audio output driver
9344 The following global options are supported by this audio output:
9346 --pipewire-buffer=<1-2000|native>
9348 Set the audio buffer size in milliseconds. A higher value
9349 buffers more data, and has a lower probability of buffer
9350 underruns. A smaller value makes the audio stream react
9351 faster, e.g. to playback speed changes.
9352 --pipewire-remote=<remote>
9354 Specify the PipeWire remote daemon name to connect to via
9355 local UNIX sockets. An empty <remote> string uses the
9356 default remote named pipewire-0.
9357 sdl SDL 1.2+ audio output driver. Should work on any platform sup‐
9359 ported by SDL 1.2, but may require the SDL_AUDIODRIVER environ‐
9360 ment variable to be set appropriately for your system.
9361 NOTE:
9363 This driver is for compatibility with extremely foreign envi‐
9364 ronments, such as systems where none of the other drivers are
9365 available.
9366 The following global options are supported by this audio output:
9368 --sdl-buflen=<length>
9370 Sets the audio buffer length in seconds. Is used only as
9371 a hint by the sound system. Playing a file with -v will
9372 show the requested and obtained exact buffer size. A
9373 value of 0 selects the sound system default.
9374 null Produces no audio output but maintains video playback speed. You
9376 can use --ao=null --ao-null-untimed for benchmarking.
9377 The following global options are supported by this audio output:
9379 --ao-null-untimed
9381 Do not simulate timing of a perfect audio device. This
9382 means audio decoding will go as fast as possible, instead
9383 of timing it to the system clock.
9384 --ao-null-buffer
9386 Simulated buffer length in seconds.
9387 --ao-null-outburst
9389 Simulated chunk size in samples.
9390 --ao-null-speed
9392 Simulated audio playback speed as a multiplier. Usually,
9393 a real audio device will not go exactly as fast as the
9394 system clock. It will deviate just a little, and this op‐
9395 tion helps to simulate this.
9396 --ao-null-latency
9398 Simulated device latency. This is additional to EOF.
9399 --ao-null-broken-eof
9401 Simulate broken audio drivers, which always add the fixed
9402 device latency to the reported audio playback position.
9403 --ao-null-broken-delay
9405 Simulate broken audio drivers, which don't report latency
9406 correctly.
9407 --ao-null-channel-layouts
9409 If not empty, this is a , separated list of channel lay‐
9410 outs the AO allows. This can be used to test channel lay‐
9411 out selection.
9412 --ao-null-format
9414 Force the audio output format the AO will accept. If un‐
9415 set accepts any.
9416 pcm Raw PCM/WAVE file writer audio output
9418 The following global options are supported by this audio output:
9420 --ao-pcm-waveheader=<yes|no>
9422 Include or do not include the WAVE header (default: in‐
9423 cluded). When not included, raw PCM will be generated.
9424 --ao-pcm-file=<filename>
9426 Write the sound to <filename> instead of the default au‐
9427 diodump.wav. If no-waveheader is specified, the default
9428 is audiodump.pcm.
9429 --ao-pcm-append=<yes|no>
9431 Append to the file, instead of overwriting it. Always use
9432 this with the no-waveheader option - with waveheader it's
9433 broken, because it will write a WAVE header every time
9434 the file is opened.
9435 sndio Audio output to the OpenBSD sndio sound system
9437 (Note: only supports mono, stereo, 4.0, 5.1 and 7.1 channel lay‐
9439 outs.)
9440 wasapi Audio output to the Windows Audio Session API.
9442
9444 Video output drivers are interfaces to different video output facili‐
9445 ties. The syntax is:
9446 --vo=<driver1,driver2,...[,]>
9448 Specify a priority list of video output drivers to be used.
9449 If the list has a trailing ,, mpv will fall back on drivers not con‐
9451 tained in the list.
9452 NOTE:
9454 See --vo=help for a list of compiled-in video output drivers.
9455 The recommended output driver is --vo=gpu, which is the default. All
9457 other drivers are for compatibility or special purposes. If the de‐
9458 fault does not work, it will fallback to other drivers (in the same
9459 order as listed by --vo=help).
9460 Available video output drivers are:
9462 gpu General purpose, customizable, GPU-accelerated video output
9464 driver. It supports extended scaling methods, dithering, color
9465 management, custom shaders, HDR, and more.
9466 See GPU renderer options for options specific to this VO.
9468 By default, it tries to use fast and fail-safe settings. Use the
9470 gpu-hq profile to use this driver with defaults set to high
9471 quality rendering. The profile can be applied with --pro‐
9472 file=gpu-hq and its contents can be viewed with --show-pro‐
9473 file=gpu-hq.
9474 This VO abstracts over several possible graphics APIs and win‐
9476 dowing contexts, which can be influenced using the --gpu-api and
9477 --gpu-context options.
9478 Hardware decoding over OpenGL-interop is supported to some de‐
9480 gree. Note that in this mode, some corner case might not be
9481 gracefully handled, and color space conversion and chroma upsam‐
9482 pling is generally in the hand of the hardware decoder APIs.
9483 gpu makes use of FBOs by default. Sometimes you can achieve bet‐
9485 ter quality or performance by changing the --fbo-format option
9486 to rgb16f, rgb32f or rgb. Known problems include Mesa/Intel not
9487 accepting rgb16, Mesa sometimes not being compiled with float
9488 texture support, and some macOS setups being very slow with
9489 rgb16 but fast with rgb32f. If you have problems, you can also
9490 try enabling the --gpu-dumb-mode=yes option.
9491 gpu-next
9493 Experimental video renderer based on libplacebo. This supports
9494 almost the same set of features as --vo=gpu. See GPU renderer
9495 options for a list.
9496 Should generally be faster and higher quality, but some features
9498 may still be missing or misbehave. Expect (and report!) bugs.
9499 See here for a list of known differences and bugs:
9500 https://github.com/mpv-player/mpv/wiki/GPU-Next-vs-GPU
9502 xv (X11 only)
9504 Uses the XVideo extension to enable hardware-accelerated dis‐
9505 play. This is the most compatible VO on X, but may be low-qual‐
9506 ity, and has issues with OSD and subtitle display.
9507 NOTE:
9509 This driver is for compatibility with old systems.
9510 The following global options are supported by this video output:
9512 --xv-adaptor=<number>
9514 Select a specific XVideo adapter (check xvinfo results).
9515 --xv-port=<number>
9517 Select a specific XVideo port.
9518 --xv-ck=<cur|use|set>
9520 Select the source from which the color key is taken (de‐
9521 fault: cur).
9522 cur The default takes the color key currently set in
9524 Xv.
9525 use Use but do not set the color key from mpv (use the
9527 --colorkey option to change it).
9528 set Same as use but also sets the supplied color key.
9530 --xv-ck-method=<none|man|bg|auto>
9532 Sets the color key drawing method (default: man).
9533 none Disables color-keying.
9535 man Draw the color key manually (reduces flicker in
9537 some cases).
9538 bg Set the color key as window background.
9540 auto Let Xv draw the color key.
9542 --xv-colorkey=<number>
9544 Changes the color key to an RGB value of your choice.
9545 0x000000 is black and 0xffffff is white.
9546 --xv-buffers=<number>
9548 Number of image buffers to use for the internal ring‐
9549 buffer (default: 2). Increasing this will use more mem‐
9550 ory, but might help with the X server not responding
9551 quickly enough if video FPS is close to or higher than
9552 the display refresh rate.
9553 x11 (X11 only)
9555 Shared memory video output driver without hardware acceleration
9556 that works whenever X11 is present.
9557 Since mpv 0.30.0, you may need to use --profile=sw-fast to get
9559 decent performance.
9560 NOTE:
9562 This is a fallback only, and should not be normally used.
9563 vdpau (X11 only)
9565 Uses the VDPAU interface to display and optionally also decode
9566 video. Hardware decoding is used with --hwdec=vdpau. Note that
9567 there is absolutely no reason to use this, other than compati‐
9568 bility. We strongly recommend that you use --vo=gpu with
9569 --hwdec=nvdec instead.
9570 NOTE:
9572 Earlier versions of mpv (and MPlayer, mplayer2) provided
9573 sub-options to tune vdpau post-processing, like deint,
9574 sharpen, denoise, chroma-deint, pullup, hqscaling. These
9575 sub-options are deprecated, and you should use the vdpaupp
9576 video filter instead.
9577 The following global options are supported by this video output:
9579 --vo-vdpau-sharpen=<-1-1>
9581 (Deprecated. See note about vdpaupp.)
9582 For positive values, apply a sharpening algorithm to the
9584 video, for negative values a blurring algorithm (default:
9585 0).
9586 --vo-vdpau-denoise=<0-1>
9588 (Deprecated. See note about vdpaupp.)
9589 Apply a noise reduction algorithm to the video (default:
9591 0; no noise reduction).
9592 --vo-vdpau-chroma-deint
9594 (Deprecated. See note about vdpaupp.)
9595 Makes temporal deinterlacers operate both on luma and
9597 chroma (default). Use no-chroma-deint to solely use luma
9598 and speed up advanced deinterlacing. Useful with slow
9599 video memory.
9600 --vo-vdpau-pullup
9602 (Deprecated. See note about vdpaupp.)
9603 Try to apply inverse telecine, needs motion adaptive tem‐
9605 poral deinterlacing.
9606 --vo-vdpau-hqscaling=<0-9>
9608 (Deprecated. See note about vdpaupp.)
9609 0 Use default VDPAU scaling (default).
9611 1-9 Apply high quality VDPAU scaling (needs capable
9613 hardware).
9614 --vo-vdpau-fps=<number>
9616 Override autodetected display refresh rate value (the
9617 value is needed for framedrop to allow video playback
9618 rates higher than display refresh rate, and for
9619 vsync-aware frame timing adjustments). Default 0 means
9620 use autodetected value. A positive value is interpreted
9621 as a refresh rate in Hz and overrides the autodetected
9622 value. A negative value disables all timing adjustment
9623 and framedrop logic.
9624 --vo-vdpau-composite-detect
9626 NVIDIA's current VDPAU implementation behaves somewhat
9627 differently under a compositing window manager and does
9628 not give accurate frame timing information. With this op‐
9629 tion enabled, the player tries to detect whether a com‐
9630 positing window manager is active. If one is detected,
9631 the player disables timing adjustments as if the user had
9632 specified fps=-1 (as they would be based on incorrect in‐
9633 put). This means timing is somewhat less accurate than
9634 without compositing, but with the composited mode behav‐
9635 ior of the NVIDIA driver, there is no hard playback speed
9636 limit even without the disabled logic. Enabled by de‐
9637 fault, use --vo-vdpau-composite-detect=no to disable.
9638 --vo-vdpau-queuetime-windowed=<number> and queuetime-fs=<number>
9640 Use VDPAU's presentation queue functionality to queue fu‐
9641 ture video frame changes at most this many milliseconds
9642 in advance (default: 50). See below for additional in‐
9643 formation.
9644 --vo-vdpau-output-surfaces=<2-15>
9646 Allocate this many output surfaces to display video
9647 frames (default: 3). See below for additional informa‐
9648 tion.
9649 --vo-vdpau-colorkey=<#RRGGBB|#AARRGGBB>
9651 Set the VDPAU presentation queue background color, which
9652 in practice is the colorkey used if VDPAU operates in
9653 overlay mode (default: #020507, some shade of black). If
9654 the alpha component of this value is 0, the default VDPAU
9655 colorkey will be used instead (which is usually green).
9656 --vo-vdpau-force-yuv
9658 Never accept RGBA input. This means mpv will insert a
9659 filter to convert to a YUV format before the VO. Some‐
9660 times useful to force availability of certain YUV-only
9661 features, like video equalizer or deinterlacing.
9662 Using the VDPAU frame queuing functionality controlled by the
9664 queuetime options makes mpv's frame flip timing less sensitive
9665 to system CPU load and allows mpv to start decoding the next
9666 frame(s) slightly earlier, which can reduce jitter caused by in‐
9667 dividual slow-to-decode frames. However, the NVIDIA graphics
9668 drivers can make other window behavior such as window moves
9669 choppy if VDPAU is using the blit queue (mainly happens if you
9670 have the composite extension enabled) and this feature is ac‐
9671 tive. If this happens on your system and it bothers you then you
9672 can set the queuetime value to 0 to disable this feature. The
9673 settings to use in windowed and fullscreen mode are separate be‐
9674 cause there should be no reason to disable this for fullscreen
9675 mode (as the driver issue should not affect the video itself).
9676 You can queue more frames ahead by increasing the queuetime val‐
9678 ues and the output_surfaces count (to ensure enough surfaces to
9679 buffer video for a certain time ahead you need at least as many
9680 surfaces as the video has frames during that time, plus two).
9681 This could help make video smoother in some cases. The main
9682 downsides are increased video RAM requirements for the surfaces
9683 and laggier display response to user commands (display changes
9684 only become visible some time after they're queued). The graph‐
9685 ics driver implementation may also have limits on the length of
9686 maximum queuing time or number of queued surfaces that work well
9687 or at all.
9688 direct3d (Windows only)
9690 Video output driver that uses the Direct3D interface.
9691 NOTE:
9693 This driver is for compatibility with systems that don't pro‐
9694 vide proper OpenGL drivers, and where ANGLE does not perform
9695 well.
9696 The following global options are supported by this video output:
9698 --vo-direct3d-disable-texture-align
9700 Normally texture sizes are always aligned to 16. With
9701 this option enabled, the video texture will always have
9702 exactly the same size as the video itself.
9703 Debug options. These might be incorrect, might be removed in the
9705 future, might crash, might cause slow downs, etc. Contact the
9706 developers if you actually need any of these for performance or
9707 proper operation.
9708 --vo-direct3d-force-power-of-2
9710 Always force textures to power of 2, even if the device
9711 reports non-power-of-2 texture sizes as supported.
9712 --vo-direct3d-texture-memory=<mode>
9714 Only affects operation with shaders/texturing enabled,
9715 and (E)OSD. Possible values:
9716 default (default)
9718 Use D3DPOOL_DEFAULT, with a D3DPOOL_SYSTEMMEM tex‐
9719 ture for locking. If the driver supports D3DDEV‐
9720 CAPS_TEXTURESYSTEMMEMORY, D3DPOOL_SYSTEMMEM is
9721 used directly.
9722 default-pool
9724 Use D3DPOOL_DEFAULT. (Like default, but never use
9725 a shadow-texture.)
9726 default-pool-shadow
9728 Use D3DPOOL_DEFAULT, with a D3DPOOL_SYSTEMMEM tex‐
9729 ture for locking. (Like default, but always force
9730 the shadow-texture.)
9731 managed
9733 Use D3DPOOL_MANAGED.
9734 scratch
9736 Use D3DPOOL_SCRATCH, with a D3DPOOL_SYSTEMMEM tex‐
9737 ture for locking.
9738 --vo-direct3d-swap-discard
9740 Use D3DSWAPEFFECT_DISCARD, which might be faster. Might
9741 be slower too, as it must(?) clear every frame.
9742 --vo-direct3d-exact-backbuffer
9744 Always resize the backbuffer to window size.
9745 sdl SDL 2.0+ Render video output driver, depending on system with or
9747 without hardware acceleration. Should work on all platforms sup‐
9748 ported by SDL 2.0. For tuning, refer to your copy of the file
9749 SDL_hints.h.
9750 NOTE:
9752 This driver is for compatibility with systems that don't pro‐
9753 vide proper graphics drivers.
9754 The following global options are supported by this video output:
9756 --sdl-sw
9758 Continue even if a software renderer is detected.
9759 --sdl-switch-mode
9761 Instruct SDL to switch the monitor video mode when going
9762 fullscreen.
9763 dmabuf-wayland
9765 Experimental Wayland output driver designed for use with either
9766 drm stateless or VA API hardware decoding. The driver is de‐
9767 signed to avoid any GPU to CPU copies, and to perform scaling
9768 and color space conversion using fixed-function hardware, if
9769 available, rather than GPU shaders. This frees up GPU resources
9770 for other tasks. Currently this driver is experimental and only
9771 works with the --hwdec=vaapi or hwdec=drm drivers; OSD is also
9772 not supported. Supported compositors : Weston and Sway.
9773 vaapi Intel VA API video output driver with support for hardware de‐
9775 coding. Note that there is absolutely no reason to use this,
9776 other than compatibility. This is low quality, and has issues
9777 with OSD. We strongly recommend that you use --vo=gpu with
9778 --hwdec=vaapi instead.
9779 The following global options are supported by this video output:
9781 --vo-vaapi-scaling=<algorithm>
9783 default
9785 Driver default (mpv default as well).
9786 fast Fast, but low quality.
9788 hq Unspecified driver dependent high-quality scaling,
9790 slow.
9791 nla non-linear anamorphic scaling
9793 --vo-vaapi-deint-mode=<mode>
9795 Select deinterlacing algorithm. Note that by default
9796 deinterlacing is initially always off, and needs to be
9797 enabled with the d key (default key binding for cycle
9798 deinterlace).
9799 This option doesn't apply if libva supports video post
9801 processing (vpp). In this case, the default for
9802 deint-mode is no, and enabling deinterlacing via user in‐
9803 teraction using the methods mentioned above actually in‐
9804 serts the vavpp video filter. If vpp is not actually sup‐
9805 ported with the libva backend in use, you can use this
9806 option to forcibly enable VO based deinterlacing.
9807 no Don't allow deinterlacing (default for newer
9809 libva).
9810 first-field
9812 Show only first field.
9813 bob bob deinterlacing (default for older libva).
9815 --vo-vaapi-scaled-osd=<yes|no>
9817 If enabled, then the OSD is rendered at video resolution
9818 and scaled to display resolution. By default, this is
9819 disabled, and the OSD is rendered at display resolution
9820 if the driver supports it.
9821 null Produces no video output. Useful for benchmarking.
9823 Usually, it's better to disable video with --no-video instead.
9825 The following global options are supported by this video output:
9827 --vo-null-fps=<value>
9829 Simulate display FPS. This artificially limits how many
9830 frames the VO accepts per second.
9831 caca Color ASCII art video output driver that works on a text con‐
9833 sole.
9834 NOTE:
9836 This driver is a joke.
9837 tct Color Unicode art video output driver that works on a text con‐
9839 sole. By default depends on support of true color by modern
9840 terminals to display the images at full color range, but
9841 256-colors output is also supported (see below). On Windows it
9842 requires an ansi terminal such as mintty.
9843 Since mpv 0.30.0, you may need to use --profile=sw-fast to get
9845 decent performance.
9846 Note: the TCT image output is not synchronized with other termi‐
9848 nal output from mpv, which can lead to broken images. The op‐
9849 tions --no-terminal or --really-quiet can help with that.
9850 --vo-tct-algo=<algo>
9852 Select how to write the pixels to the terminal.
9853 half-blocks
9855 Uses unicode LOWER HALF BLOCK character to achieve
9856 higher vertical resolution. (Default.)
9857 plain Uses spaces. Causes vertical resolution to drop
9859 twofolds, but in theory works in more places.
9860 --vo-tct-width=<width> --vo-tct-height=<height>
9862 Assume the terminal has the specified character width
9863 and/or height. These default to 80x25 if the terminal
9864 size cannot be determined.
9865 --vo-tct-256=<yes|no> (default: no)
9867 Use 256 colors - for terminals which don't support true
9868 color.
9869 sixel Graphical output for the terminal, using sixels. Tested with ml‐
9871 term and xterm.
9872 Note: the Sixel image output is not synchronized with other ter‐
9874 minal output from mpv, which can lead to broken images. The op‐
9875 tion --really-quiet can help with that, and is recommended.
9876 You may need to use --profile=sw-fast to get decent performance.
9878 Note: at the time of writing, xterm does not enable sixel by de‐
9880 fault - launching it as xterm -ti 340 is one way to enable it.
9881 Also, xterm does not display images bigger than 1000x1000 pixels
9882 by default.
9883 To render and align sixel images correctly, mpv needs to know
9885 the terminal size both in cells and in pixels. By default it
9886 tries to use values which the terminal reports, however, due to
9887 differences between terminals this is an error-prone process
9888 which cannot be automated with certainty - some terminals report
9889 the size in pixels including the padding - e.g. xterm, while
9890 others report the actual usable number of pixels - like mlterm.
9891 Additionally, they may behave differently when maximized or in
9892 fullscreen, and mpv cannot detect this state using standard
9893 methods.
9894 Sixel size and alignment options:
9896 --vo-sixel-cols=<columns>, --vo-sixel-rows=<rows> (default: 0)
9898 Specify the terminal size in character cells, otherwise
9899 (0) read it from the terminal, or fall back to 80x25.
9900 Note that mpv doesn't use the the last row with sixel be‐
9901 cause this seems to result in scrolling.
9902 --vo-sixel-width=<width>, --vo-sixel-height=<height> (default:
9904 0)
9905 Specify the available size in pixels, otherwise (0) read
9906 it from the terminal, or fall back to 320x240. Other than
9907 excluding the last line, the height is also further
9908 rounded down to a multiple of 6 (sixel unit height) to
9909 avoid overflowing below the designated size.
9910 --vo-sixel-left=<col>, --vo-sixel-top=<row> (default: 0)
9912 Specify the position in character cells where the image
9913 starts (1 is the first column or row). If 0 (default)
9914 then try to automatically determine it according to the
9915 other values and the image aspect ratio and zoom.
9916 --vo-sixel-pad-x=<pad_x>, --vo-sixel-pad-y=<pad_y> (default: -1)
9918 Used only when mpv reads the size in pixels from the ter‐
9919 minal. Specify the number of padding pixels (on one
9920 side) which are included at the size which the terminal
9921 reports. If -1 (default) then the number of pixels is
9922 rounded down to a multiple of number of cells (per axis),
9923 to take into account padding at the report - this only
9924 works correctly when the overall padding per axis is
9925 smaller than the number of cells.
9926 --vo-sixel-exit-clear=<yes|no> (default: yes)
9928 Whether or not to clear the terminal on quit. When set to
9929 no - the last sixel image stays on screen after quit,
9930 with the cursor following it.
9931 Sixel image quality options:
9933 --vo-sixel-dither=<algo>
9935 Selects the dither algorithm which libsixel should apply.
9936 Can be one of the below list as per libsixel's documenta‐
9937 tion.
9938 auto (Default)
9940 Let libsixel choose the dithering method.
9941 none Don't diffuse
9943 atkinson
9945 Diffuse with Bill Atkinson's method.
9946 fs Diffuse with Floyd-Steinberg method
9948 jajuni Diffuse with Jarvis, Judice & Ninke method
9950 stucki Diffuse with Stucki's method
9952 burkes Diffuse with Burkes' method
9954 arithmetic
9956 Positionally stable arithmetic dither
9957 xor Positionally stable arithmetic xor based dither
9959 --vo-sixel-fixedpalette=<yes|no> (default: yes)
9961 Use libsixel's built-in static palette using the XTERM256
9962 profile for dither. Fixed palette uses 256 colors for
9963 dithering. Note that using no (at the time of writing)
9964 will slow down xterm.
9965 --vo-sixel-reqcolors=<colors> (default: 256)
9967 Has no effect with fixed palette. Set up libsixel to use
9968 required number of colors for dynamic palette. This value
9969 depends on the terminal emulator as well. Xterm supports
9970 256 colors. Can set this to a lower value for faster per‐
9971 formance.
9972 --vo-sixel-threshold=<threshold> (default: -1)
9974 Has no effect with fixed palette. Defines the threshold
9975 to change the palette - as percentage of the number of
9976 colors, e.g. 20 will change the palette when the number
9977 of colors changed by 20%. It's a simple measure to reduce
9978 the number of palette changes, because it can be slow in
9979 some terminals (xterm). The default (-1) will choose a
9980 palette on every frame and will have better quality.
9981 image Output each frame into an image file in the current directory.
9983 Each file takes the frame number padded with leading zeros as
9984 name.
9985 The following global options are supported by this video output:
9987 --vo-image-format=<format>
9989 Select the image file format.
9990 jpg JPEG files, extension .jpg. (Default.)
9992 jpeg JPEG files, extension .jpeg.
9994 png PNG files.
9996 webp WebP files.
9998 --vo-image-png-compression=<0-9>
10000 PNG compression factor (speed vs. file size tradeoff)
10001 (default: 7)
10002 --vo-image-png-filter=<0-5>
10004 Filter applied prior to PNG compression (0 = none; 1 =
10005 sub; 2 = up; 3 = average; 4 = Paeth; 5 = mixed) (default:
10006 5)
10007 --vo-image-jpeg-quality=<0-100>
10009 JPEG quality factor (default: 90)
10010 --vo-image-jpeg-optimize=<0-100>
10012 JPEG optimization factor (default: 100)
10013 --vo-image-webp-lossless=<yes|no>
10015 Enable writing lossless WebP files (default: no)
10016 --vo-image-webp-quality=<0-100>
10018 WebP quality (default: 75)
10019 --vo-image-webp-compression=<0-6>
10021 WebP compression factor (default: 4)
10022 --vo-image-outdir=<dirname>
10024 Specify the directory to save the image files to (de‐
10025 fault: ./).
10026 libmpv For use with libmpv direct embedding. As a special case, on
10028 macOS it is used like a normal VO within mpv (cocoa-cb). Other‐
10029 wise useless in any other contexts. (See <mpv/render.h>.)
10030 This also supports many of the options the gpu VO has, depending
10032 on the backend.
10033 rpi (Raspberry Pi)
10035 Native video output on the Raspberry Pi using the MMAL API.
10036 This is deprecated. Use --vo=gpu instead, which is the default
10038 and provides the same functionality. The rpi VO will be removed
10039 in mpv 0.23.0. Its functionality was folded into --vo=gpu, which
10040 now uses RPI hardware decoding by treating it as a hardware
10041 overlay (without applying GL filtering). Also to be changed in
10042 0.23.0: the --fs flag will be reset to "no" by default (like on
10043 the other platforms).
10044 The following deprecated global options are supported by this
10046 video output:
10047 --rpi-display=<number>
10049 Select the display number on which the video overlay
10050 should be shown (default: 0).
10051 --rpi-layer=<number>
10053 Select the dispmanx layer on which the video overlay
10054 should be shown (default: -10). Note that mpv will also
10055 use the 2 layers above the selected layer, to handle the
10056 window background and OSD. Actual video rendering will
10057 happen on the layer above the selected layer.
10058 --rpi-background=<yes|no>
10060 Whether to render a black background behind the video
10061 (default: no). Normally it's better to kill the console
10062 framebuffer instead, which gives better performance.
10063 --rpi-osd=<yes|no>
10065 Enabled by default. If disabled with no, no OSD layer is
10066 created. This also means there will be no subtitles ren‐
10067 dered.
10068 drm (Direct Rendering Manager)
10070 Video output driver using Kernel Mode Setting / Direct Rendering
10071 Manager. Should be used when one doesn't want to install
10072 full-blown graphical environment (e.g. no X). Does not support
10073 hardware acceleration (if you need this, check the drm backend
10074 for gpu VO).
10075 Since mpv 0.30.0, you may need to use --profile=sw-fast to get
10077 decent performance.
10078 The following global options are supported by this video output:
10080 --drm-connector=[<gpu_number>.]<name>
10082 Select the connector to use (usually this is a monitor.)
10083 If <name> is empty or auto, mpv renders the output on the
10084 first available connector. Use --drm-connector=help to
10085 get a list of available connectors. The <gpu_number> ar‐
10086 gument can be used to disambiguate multiple graphic
10087 cards, but is deprecated in favor of --drm-device. (de‐
10088 fault: empty)
10089 --drm-device=<path>
10091 Select the DRM device file to use. If specified this
10092 overrides automatic card selection and any card number
10093 specified --drm-connector. (default: empty)
10094 --drm-mode=<preferred|highest|N|WxH[@R]>
10096 Mode to use (resolution and frame rate). Possible val‐
10097 ues:
10098 preferred
10100 Use the preferred mode for the screen on the se‐
10101 lected connector. (default)
10102 highest
10104 Use the mode with the highest resolution available
10105 on the selected connector.
10106 N Select mode by index.
10108 WxH[@R]
10110 Specify mode by width, height, and optionally re‐
10111 fresh rate. In case several modes match, selects
10112 the mode that comes first in the EDID list of
10113 modes.
10114 Use --drm-mode=help to get a list of available modes for
10116 all active connectors.
10117 --drm-atomic=<no|auto>
10119 Toggle use of atomic modesetting. Mostly useful for de‐
10120 bugging.
10121 no Use legacy modesetting.
10123 auto Use atomic modesetting, falling back to legacy
10125 modesetting if not available. (default)
10126 Note: Only affects gpu-context=drm. vo=drm supports
10128 legacy modesetting only.
10129 --drm-draw-plane=<primary|overlay|N>
10131 Select the DRM plane to which video and OSD is drawn to,
10132 under normal circumstances. The plane can be specified as
10133 primary, which will pick the first applicable primary
10134 plane; overlay, which will pick the first applicable
10135 overlay plane; or by index. The index is zero based, and
10136 related to the CRTC. (default: primary)
10137 When using this option with the drmprime-overlay hwdec
10139 interop, only the OSD is rendered to this plane.
10140 --drm-drmprime-video-plane=<primary|overlay|N>
10142 Select the DRM plane to use for video with the drm‐
10143 prime-overlay hwdec interop (used by e.g. the rkmpp hwdec
10144 on RockChip SoCs, and v4l2 hwdec:s on various other
10145 SoC:s). The plane is unused otherwise. This option ac‐
10146 cepts the same values as --drm-draw-plane. (default:
10147 overlay)
10148 To be able to successfully play 4K video on various SoCs
10150 you might need to set --drm-draw-plane=overlay --drm-drm‐
10151 prime-video-plane=primary and setting --drm-draw-sur‐
10152 face-size=1920x1080, to render the OSD at a lower resolu‐
10153 tion (the video when handled by the hwdec will be on the
10154 drmprime-video plane and at full 4K resolution)
10155 --drm-format=<xrgb8888|xrgb2101010>
10157 Select the DRM format to use (default: xrgb8888). This
10158 allows you to choose the bit depth of the DRM mode.
10159 xrgb8888 is your usual 24 bit per pixel/8 bits per chan‐
10160 nel packed RGB format with 8 bits of padding.
10161 xrgb2101010 is a packed 30 bits per pixel/10 bits per
10162 channel packed RGB format with 2 bits of padding.
10163 There are cases when xrgb2101010 will work with the drm
10165 VO, but not with the drm backend for the gpu VO. This is
10166 because with the gpu VO, in addition to requiring support
10167 in your DRM driver, requires support for xrgb2101010 in
10168 your EGL driver
10169 --drm-draw-surface-size=<[WxH]>
10171 Sets the size of the surface used on the draw plane. The
10172 surface will then be upscaled to the current screen reso‐
10173 lution. This option can be useful when used together with
10174 the drmprime-overlay hwdec interop at high resolutions,
10175 as it allows scaling the draw plane (which in this case
10176 only handles the OSD) down to a size the GPU can handle.
10177 When used without the drmprime-overlay hwdec interop this
10179 option will just cause the video to get rendered at a
10180 different resolution and then scaled to screen size.
10181 Note: this option is only available with DRM atomic sup‐
10183 port. (default: display resolution)
10184 --drm-vrr-enabled=<no|yes|auto>
10186 Toggle use of Variable Refresh Rate (VRR), aka Freesync
10187 or Adaptive Sync on compatible systems. VRR allows for
10188 the display to be refreshed at any rate within a range
10189 (usually ~40Hz-60Hz for 60Hz displays). This can help
10190 with playback of 24/25/50fps content. Support depends on
10191 the use of a compatible monitor, GPU, and a sufficiently
10192 new kernel with drivers that support the feature.
10193 no Do not attempt to enable VRR. (default)
10195 yes Attempt to enable VRR, whether the capability is
10197 reported or not.
10198 auto Attempt to enable VRR if support is reported.
10200 mediacodec_embed (Android)
10202 Renders IMGFMT_MEDIACODEC frames directly to an an‐
10203 droid.view.Surface. Requires --hwdec=mediacodec for hardware
10204 decoding, along with --vo=mediacodec_embed and
10205 --wid=(intptr_t)(*android.view.Surface).
10206 Since this video output driver uses native decoding and render‐
10208 ing routines, many of mpv's features (subtitle rendering,
10209 OSD/OSC, video filters, etc) are not available with this driver.
10210 To use hardware decoding with --vo=gpu instead, use --hwdec=me‐
10212 diacodec or mediacodec-copy along with --gpu-context=android.
10213 wlshm (Wayland only)
10215 Shared memory video output driver without hardware acceleration
10216 that works whenever Wayland is present.
10217 Since mpv 0.30.0, you may need to use --profile=sw-fast to get
10219 decent performance.
10220 NOTE:
10222 This is a fallback only, and should not be normally used.
10223
10225 Audio filters allow you to modify the audio stream and its properties.
10226 The syntax is:
10227 --af=...
10229 Setup a chain of audio filters. See --vf (VIDEO FILTERS) for the
10230 full syntax.
10231 NOTE:
10233 To get a full list of available audio filters, see --af=help.
10234 Also, keep in mind that most actual filters are available via the
10236 lavfi wrapper, which gives you access to most of libavfilter's fil‐
10237 ters. This includes all filters that have been ported from MPlayer
10238 to libavfilter.
10239 The --vf description describes how libavfilter can be used and how
10241 to workaround deprecated mpv filters.
10242 See --vf group of options for info on how --af-defaults, --af-add,
10244 --af-pre, --af-del, --af-clr, and possibly others work.
10245 Available filters are:
10247 lavcac3enc[=options]
10249 Encode multi-channel audio to AC-3 at runtime using libavcodec.
10250 Supports 16-bit native-endian input format, maximum 6 channels.
10251 The output is big-endian when outputting a raw AC-3 stream, na‐
10252 tive-endian when outputting to S/PDIF. If the input sample rate
10253 is not 48 kHz, 44.1 kHz or 32 kHz, it will be resampled to 48
10254 kHz.
10255 tospdif=<yes|no>
10257 Output raw AC-3 stream if no, output to S/PDIF for
10258 pass-through if yes (default).
10259 bitrate=<rate>
10261 The bitrate use for the AC-3 stream. Set it to 384 to get
10262 384 kbps.
10263 The default is 640. Some receivers might not be able to
10265 handle this.
10266 Valid values: 32, 40, 48, 56, 64, 80, 96, 112, 128, 160,
10268 192, 224, 256, 320, 384, 448, 512, 576, 640.
10269 The special value auto selects a default bitrate based on
10271 the input channel number:
10272 1ch 96
10274 2ch 192
10276 3ch 224
10278 4ch 384
10280 5ch 448
10282 6ch 448
10284 minch=<n>
10286 If the input channel number is less than <minch>, the
10287 filter will detach itself (default: 3).
10288 encoder=<name>
10290 Select the libavcodec encoder used. Currently, this
10291 should be an AC-3 encoder, and using another codec will
10292 fail horribly.
10293 format=format:srate:channels:out-srate:out-channels
10295 Does not do any format conversion itself. Rather, it may cause
10296 the filter system to insert necessary conversion filters before
10297 or after this filter if needed. It is primarily useful for con‐
10298 trolling the audio format going into other filters. To specify
10299 the format for audio output, see --audio-format, --audio-sam‐
10300 plerate, and --audio-channels. This filter is able to force a
10301 particular format, whereas --audio-* may be overridden by the ao
10302 based on output compatibility.
10303 All parameters are optional. The first 3 parameters restrict
10305 what the filter accepts as input. They will therefore cause con‐
10306 version filters to be inserted before this one. The out- param‐
10307 eters tell the filters or audio outputs following this filter
10308 how to interpret the data without actually doing a conversion.
10309 Setting these will probably just break things unless you really
10310 know you want this for some reason, such as testing or dealing
10311 with broken media.
10312 <format>
10314 Force conversion to this format. Use --af=format=for‐
10315 mat=help to get a list of valid formats.
10316 <srate>
10318 Force conversion to a specific sample rate. The rate is
10319 an integer, 48000 for example.
10320 <channels>
10322 Force mixing to a specific channel layout. See --au‐
10323 dio-channels option for possible values.
10324 <out-srate>
10326 <out-channels>
10328 NOTE: this filter used to be named force. The old format filter
10330 used to do conversion itself, unlike this one which lets the
10331 filter system handle the conversion.
10332 scaletempo[=option1:option2:...]
10334 Scales audio tempo without altering pitch, optionally synced to
10335 playback speed (default).
10336 This works by playing 'stride' ms of audio at normal speed then
10338 consuming 'stride*scale' ms of input audio. It pieces the
10339 strides together by blending 'overlap'% of stride with audio
10340 following the previous stride. It optionally performs a short
10341 statistical analysis on the next 'search' ms of audio to deter‐
10342 mine the best overlap position.
10343 scale=<amount>
10345 Nominal amount to scale tempo. Scales this amount in ad‐
10346 dition to speed. (default: 1.0)
10347 stride=<amount>
10349 Length in milliseconds to output each stride. Too high of
10350 a value will cause noticeable skips at high scale amounts
10351 and an echo at low scale amounts. Very low values will
10352 alter pitch. Increasing improves performance. (default:
10353 60)
10354 overlap=<percent>
10356 Percentage of stride to overlap. Decreasing improves per‐
10357 formance. (default: .20)
10358 search=<amount>
10360 Length in milliseconds to search for best overlap posi‐
10361 tion. Decreasing improves performance greatly. On slow
10362 systems, you will probably want to set this very low.
10363 (default: 14)
10364 speed=<tempo|pitch|both|none>
10366 Set response to speed change.
10367 tempo Scale tempo in sync with speed (default).
10369 pitch Reverses effect of filter. Scales pitch without
10371 altering tempo. Add this to your input.conf to
10372 step by musical semi-tones:
10373 [ multiply speed 0.9438743126816935
10375 ] multiply speed 1.059463094352953
10376 WARNING:
10378 Loses sync with video.
10379 both Scale both tempo and pitch.
10381 none Ignore speed changes.
10383 Examples
10385 mpv --af=scaletempo --speed=1.2 media.ogg
10387 Would play media at 1.2x normal speed, with audio at
10388 normal pitch. Changing playback speed would change au‐
10389 dio tempo to match.
10390 mpv --af=scaletempo=scale=1.2:speed=none --speed=1.2 me‐
10392 dia.ogg
10393 Would play media at 1.2x normal speed, with audio at
10394 normal pitch, but changing playback speed would have
10395 no effect on audio tempo.
10396 mpv --af=scaletempo=stride=30:overlap=.50:search=10 media.ogg
10398 Would tweak the quality and performance parameters.
10399 mpv --af=scaletempo=scale=1.2:speed=pitch audio.ogg
10401 Would play media at 1.2x normal speed, with audio at
10402 normal pitch. Changing playback speed would change
10403 pitch, leaving audio tempo at 1.2x.
10404 scaletempo2[=option1:option2:...]
10406 Scales audio tempo without altering pitch. The algorithm is
10407 ported from chromium and uses the Waveform Similarity Over‐
10408 lap-and-add (WSOLA) method. It seems to achieve a higher audio
10409 quality than scaletempo and rubberband.
10410 By default, the search-interval and window-size parameters have
10412 the same values as in chromium.
10413 min-speed=<speed>
10415 Mute audio if the playback speed is below <speed>. (de‐
10416 fault: 0.25)
10417 max-speed=<speed>
10419 Mute audio if the playback speed is above <speed> and
10420 <speed> != 0. (default: 4.0)
10421 search-interval=<amount>
10423 Length in milliseconds to search for best overlap posi‐
10424 tion. (default: 30)
10425 window-size=<amount>
10427 Length in milliseconds of the overlap-and-add window.
10428 (default: 20)
10429 rubberband
10431 High quality pitch correction with librubberband. This can be
10432 used in place of scaletempo, and will be used to adjust audio
10433 pitch when playing at speed different from normal. It can also
10434 be used to adjust audio pitch without changing playback speed.
10435 <pitch-scale>
10437 Sets the pitch scaling factor. Frequencies are multiplied
10438 by this value.
10439 This filter has a number of additional sub-options. You can list
10441 them with mpv --af=rubberband=help. This will also show the de‐
10442 fault values for each option. The options are not documented
10443 here, because they are merely passed to librubberband. Look at
10444 the librubberband documentation to learn what each option does:
10445 https://breakfastquay.com/rubberband/code-doc/classRubberBand_1_1RubberBandStretcher.html
10446 (The mapping of the mpv rubberband filter sub-option names and
10447 values to those of librubberband follows a simple pattern: "Op‐
10448 tion" + Name + Value.)
10449 This filter supports the following af-command commands:
10451 set-pitch
10453 Set the <pitch-scale> argument dynamically. This can be
10454 used to change the playback pitch at runtime. Note that
10455 speed is controlled using the standard speed property,
10456 not af-command.
10457 multiply-pitch <factor>
10459 Multiply the current value of <pitch-scale> dynamically.
10460 For example: 0.5 to go down by an octave, 1.5 to go up by
10461 a perfect fifth. If you want to go up or down by
10462 semi-tones, use 1.059463094352953 and 0.9438743126816935
10463 lavfi=graph
10465 Filter audio using FFmpeg's libavfilter.
10466 <graph>
10468 Libavfilter graph. See lavfi video filter for details -
10469 the graph syntax is the same.
10470 WARNING:
10472 Don't forget to quote libavfilter graphs as described
10473 in the lavfi video filter section.
10474 o=<string>
10476 AVOptions.
10477 fix-pts=<yes|no>
10479 Determine PTS based on sample count (default: no). If
10480 this is enabled, the player won't rely on libavfilter
10481 passing through PTS accurately. Instead, it pass a sam‐
10482 ple count as PTS to libavfilter, and compute the PTS used
10483 by mpv based on that and the input PTS. This helps with
10484 filters which output a recomputed PTS instead of the
10485 original PTS (including filters which require the PTS to
10486 start at 0). mpv normally expects filters to not touch
10487 the PTS (or only to the extent of changing frame bound‐
10488 aries), so this is not the default, but it will be needed
10489 to use broken filters. In practice, these broken filters
10490 will either cause slow A/V desync over time (with some
10491 files), or break playback completely if you seek or start
10492 playback from the middle of a file.
10493 drop This filter drops or repeats audio frames to adapt to playback
10495 speed. It always operates on full audio frames, because it was
10496 made to handle SPDIF (compressed audio passthrough). This is
10497 used automatically if the --video-sync=display-adrop option is
10498 used. Do not use this filter (or the given option); they are ex‐
10499 tremely low quality.
10500
10502 Video filters allow you to modify the video stream and its properties.
10503 All of the information described in this section applies to audio fil‐
10504 ters as well (generally using the prefix --af instead of --vf).
10505 The exact syntax is:
10507 --vf=<filter1[=parameter1:parameter2:...],filter2,...>
10509 Setup a chain of video filters. This consists on the filter
10510 name, and an option list of parameters after =. The parameters
10511 are separated by : (not ,, as that starts a new filter entry).
10512 Before the filter name, a label can be specified with @name:,
10514 where name is an arbitrary user-given name, which identifies the
10515 filter. This is only needed if you want to toggle the filter at
10516 runtime.
10517 A ! before the filter name means the filter is disabled by de‐
10519 fault. It will be skipped on filter creation. This is also use‐
10520 ful for runtime filter toggling.
10521 See the vf command (and toggle sub-command) for further explana‐
10523 tions and examples.
10524 The general filter entry syntax is:
10526 ["@"<label-name>":"] ["!"] <filter-name> [ "=" <filter-param‐
10527 eter-list> ]
10528 or for the special "toggle" syntax (see vf command):
10530 "@"<label-name>
10531 and the filter-parameter-list:
10533 <filter-parameter> | <filter-parameter> "," <filter-parame‐
10534 ter-list>
10535 and filter-parameter:
10537 ( <param-name> "=" <param-value> ) | <param-value>
10538 param-value can further be quoted in [ / ] in case the value
10540 contains characters like , or =. This is used in particular with
10541 the lavfi filter, which uses a very similar syntax as mpv
10542 (MPlayer historically) to specify filters and their parameters.
10543 Filters can be manipulated at run time. You can use @ labels as de‐
10545 scribed above in combination with the vf command (see COMMAND INTER‐
10546 FACE) to get more control over this. Initially disabled filters with !
10547 are useful for this as well.
10548 You can also set defaults for each filter. The defaults are applied be‐
10550 fore the normal filter parameters. This is deprecated and never worked
10551 for the libavfilter bridge.
10552 --vf-defaults=<filter1[=parameter1:parameter2:...],filter2,...>
10554 Set defaults for each filter. (Deprecated. --af-defaults is dep‐
10555 recated as well.)
10556 NOTE:
10558 To get a full list of available video filters, see --vf=help and
10559 https://ffmpeg.org/ffmpeg-filters.html .
10560 Also, keep in mind that most actual filters are available via the
10562 lavfi wrapper, which gives you access to most of libavfilter's fil‐
10563 ters. This includes all filters that have been ported from MPlayer
10564 to libavfilter.
10565 Most builtin filters are deprecated in some ways, unless they're
10567 only available in mpv (such as filters which deal with mpv
10568 specifics, or which are implemented in mpv only).
10569 If a filter is not builtin, the lavfi-bridge will be automatically
10571 tried. This bridge does not support help output, and does not verify
10572 parameters before the filter is actually used. Although the mpv syn‐
10573 tax is rather similar to libavfilter's, it's not the same. (Which
10574 means not everything accepted by vf_lavfi's graph option will be ac‐
10575 cepted by --vf.)
10576 You can also prefix the filter name with lavfi- to force the wrap‐
10578 per. This is helpful if the filter name collides with a deprecated
10579 mpv builtin filter. For example --vf=lavfi-scale=args would use
10580 libavfilter's scale filter over mpv's deprecated builtin one.
10581 Video filters are managed in lists. There are a few commands to manage
10583 the filter list.
10584 --vf-append=filter
10586 Appends the filter given as arguments to the filter list.
10587 --vf-add=filter
10589 Appends the filter given as arguments to the filter list. (Pass‐
10590 ing multiple filters is currently still possible, but depre‐
10591 cated.)
10592 --vf-pre=filter
10594 Prepends the filters given as arguments to the filter list.
10595 (Passing multiple filters is currently still possible, but dep‐
10596 recated.)
10597 --vf-remove=filter
10599 Deletes the filter from the list. The filter can be either given
10600 the way it was added (filter name and its full argument list),
10601 or by label (prefixed with @). Matching of filters works as fol‐
10602 lows: if either of the compared filters has a label set, only
10603 the labels are compared. If none of the filters have a label,
10604 the filter name, arguments, and argument order are compared.
10605 (Passing multiple filters is currently still possible, but dep‐
10606 recated.)
10607 -vf-toggle=filter
10609 Add the given filter to the list if it was not present yet, or
10610 remove it from the list if it was present. Matching of filters
10611 works as described in --vf-remove.
10612 --vf-del=filter
10614 Sort of like --vf-remove, but also accepts an index number. In‐
10615 dex numbers start at 0, negative numbers address the end of the
10616 list (-1 is the last). Deprecated.
10617 --vf-clr
10619 Completely empties the filter list.
10620 With filters that support it, you can access parameters by their name.
10622 --vf=<filter>=help
10624 Prints the parameter names and parameter value ranges for a par‐
10625 ticular filter.
10626 Available mpv-only filters are:
10628 format=fmt=<value>:colormatrix=<value>:...
10630 Applies video parameter overrides, with optional conversion. By
10631 default, this overrides the video's parameters without conver‐
10632 sion (except for the fmt parameter), but can be made to perform
10633 an appropriate conversion with convert=yes for parameters for
10634 which conversion is supported.
10635 <fmt> Image format name, e.g. rgb15, bgr24, 420p, etc. (de‐
10637 fault: don't change).
10638 This filter always performs conversion to the given for‐
10640 mat.
10641 NOTE:
10643 For a list of available formats, use --vf=for‐
10644 mat=fmt=help.
10645 <convert=yes|no>
10647 Force conversion of color parameters (default: no).
10648 If this is disabled (the default), the only conversion
10650 that is possibly performed is format conversion if <fmt>
10651 is set. All other parameters (like <colormatrix>) are
10652 forced without conversion. This mode is typically useful
10653 when files have been incorrectly tagged.
10654 If this is enabled, libswscale or zimg is used if any of
10656 the parameters mismatch. zimg is used of the input/output
10657 image formats are supported by mpv's zimg wrapper, and if
10658 --sws-allow-zimg=yes is used. Both libraries may not sup‐
10659 port all kinds of conversions. This typically results in
10660 silent incorrect conversion. zimg has in many cases a
10661 better chance of performing the conversion correctly.
10662 In both cases, the color parameters are set on the output
10664 stage of the image format conversion (if fmt was set).
10665 The difference is that with convert=no, the color parame‐
10666 ters are not passed on to the converter.
10667 If input and output video parameters are the same, con‐
10669 version is always skipped.
10670 Examples
10672 mpv test.mkv --vf=format:colormatrix=ycgco
10674 Results in incorrect colors (if test.mkv was
10675 tagged correctly).
10676 mpv test.mkv --vf=format:colormatrix=ycgco:convert=yes
10678 --sws-allow-zimg
10679 Results in true conversion to ycgco, assuming
10680 the renderer supports it (--vo=gpu normally
10681 does). You can add --vo=xv to force a VO which
10682 definitely does not support it, which should
10683 show incorrect colors as confirmation.
10684 Using --sws-allow-zimg=no (or disabling zimg at
10686 build time) will use libswscale, which cannot
10687 perform this conversion as of this writing.
10688 <colormatrix>
10690 Controls the YUV to RGB color space conversion when play‐
10691 ing video. There are various standards. Normally, BT.601
10692 should be used for SD video, and BT.709 for HD video.
10693 (This is done by default.) Using incorrect color space
10694 results in slightly under or over saturated and shifted
10695 colors.
10696 These options are not always supported. Different video
10698 outputs provide varying degrees of support. The gpu and
10699 vdpau video output drivers usually offer full support.
10700 The xv output can set the color space if the system video
10701 driver supports it, but not input and output levels. The
10702 scale video filter can configure color space and input
10703 levels, but only if the output format is RGB (if the
10704 video output driver supports RGB output, you can force
10705 this with -vf scale,format=rgba).
10706 If this option is set to auto (which is the default), the
10708 video's color space flag will be used. If that flag is
10709 unset, the color space will be selected automatically.
10710 This is done using a simple heuristic that attempts to
10711 distinguish SD and HD video. If the video is larger than
10712 1279x576 pixels, BT.709 (HD) will be used; otherwise
10713 BT.601 (SD) is selected.
10714 Available color spaces are:
10716 auto automatic selection (default)
10718 bt.601 ITU-R BT.601 (SD)
10720 bt.709 ITU-R BT.709 (HD)
10722 bt.2020-ncl
10724 ITU-R BT.2020 non-constant luminance system
10725 bt.2020-cl
10727 ITU-R BT.2020 constant luminance system
10728 smpte-240m
10730 SMPTE-240M
10731 <colorlevels>
10733 YUV color levels used with YUV to RGB conversion. This
10734 option is only necessary when playing broken files which
10735 do not follow standard color levels or which are flagged
10736 wrong. If the video does not specify its color range, it
10737 is assumed to be limited range.
10738 The same limitations as with <colormatrix> apply.
10740 Available color ranges are:
10742 auto automatic selection (normally limited range) (de‐
10744 fault)
10745 limited
10747 limited range (16-235 for luma, 16-240 for chroma)
10748 full full range (0-255 for both luma and chroma)
10750 <primaries>
10752 RGB primaries the source file was encoded with. Normally
10753 this should be set in the file header, but when playing
10754 broken or mistagged files this can be used to override
10755 the setting.
10756 This option only affects video output drivers that per‐
10758 form color management, for example gpu with the tar‐
10759 get-prim or icc-profile suboptions set.
10760 If this option is set to auto (which is the default), the
10762 video's primaries flag will be used. If that flag is un‐
10763 set, the color space will be selected automatically, us‐
10764 ing the following heuristics: If the <colormatrix> is set
10765 or determined as BT.2020 or BT.709, the corresponding
10766 primaries are used. Otherwise, if the video height is ex‐
10767 actly 576 (PAL), BT.601-625 is used. If it's exactly 480
10768 or 486 (NTSC), BT.601-525 is used. If the video resolu‐
10769 tion is anything else, BT.709 is used.
10770 Available primaries are:
10772 auto automatic selection (default)
10774 bt.601-525
10776 ITU-R BT.601 (SD) 525-line systems (NTSC, SMPTE-C)
10777 bt.601-625
10779 ITU-R BT.601 (SD) 625-line systems (PAL, SECAM)
10780 bt.709 ITU-R BT.709 (HD) (same primaries as sRGB)
10782 bt.2020
10784 ITU-R BT.2020 (UHD)
10785 apple Apple RGB
10787 adobe Adobe RGB (1998)
10789 prophoto
10791 ProPhoto RGB (ROMM)
10792 cie1931
10794 CIE 1931 RGB
10795 dci-p3 DCI-P3 (Digital Cinema)
10797 v-gamut
10799 Panasonic V-Gamut primaries
10800 <gamma>
10802 Gamma function the source file was encoded with. Normally
10803 this should be set in the file header, but when playing
10804 broken or mistagged files this can be used to override
10805 the setting.
10806 This option only affects video output drivers that per‐
10808 form color management.
10809 If this option is set to auto (which is the default), the
10811 gamma will be set to BT.1886 for YCbCr content, sRGB for
10812 RGB content and Linear for XYZ content.
10813 Available gamma functions are:
10815 auto automatic selection (default)
10817 bt.1886
10819 ITU-R BT.1886 (EOTF corresponding to
10820 BT.601/BT.709/BT.2020)
10821 srgb IEC 61966-2-4 (sRGB)
10823 linear Linear light
10825 gamma1.8
10827 Pure power curve (gamma 1.8)
10828 gamma2.0
10830 Pure power curve (gamma 2.0)
10831 gamma2.2
10833 Pure power curve (gamma 2.2)
10834 gamma2.4
10836 Pure power curve (gamma 2.4)
10837 gamma2.6
10839 Pure power curve (gamma 2.6)
10840 gamma2.8
10842 Pure power curve (gamma 2.8)
10843 prophoto
10845 ProPhoto RGB (ROMM) curve
10846 pq ITU-R BT.2100 PQ (Perceptual quantizer) curve
10848 hlg ITU-R BT.2100 HLG (Hybrid Log-gamma) curve
10850 v-log Panasonic V-Log transfer curve
10852 s-log1 Sony S-Log1 transfer curve
10854 s-log2 Sony S-Log2 transfer curve
10856 <sig-peak>
10858 Reference peak illumination for the video file, relative
10859 to the signal's reference white level. This is mostly in‐
10860 teresting for HDR, but it can also be used tone map SDR
10861 content to simulate a different exposure. Normally in‐
10862 ferred from tags such as MaxCLL or mastering metadata.
10863 The default of 0.0 will default to the source's nominal
10865 peak luminance.
10866 <light>
10868 Light type of the scene. This is mostly correctly in‐
10869 ferred based on the gamma function, but it can be use‐
10870 ful to override this when viewing raw camera footage
10871 (e.g. V-Log), which is normally scene-referred instead
10872 of display-referred.
10873 Available light types are:
10875 auto Automatic selection (default)
10877 display
10879 Display-referred light (most content)
10880 hlg Scene-referred using the HLG OOTF (e.g. HLG con‐
10882 tent)
10883 709-1886
10885 Scene-referred using the BT709+BT1886 interaction
10886 gamma1.2
10888 Scene-referred using a pure power OOTF (gamma=1.2)
10889 <dolbyvision=yes|no>
10891 Whether or not to include Dolby Vision metadata (default:
10892 yes). If disabled, any Dolby Vision metadata will be
10893 stripped from frames.
10894 <film-grain=yes|no>
10896 Whether or not to include film grain metadata (default:
10897 yes). If disabled, any film grain metadata will be
10898 stripped from frames.
10899 <stereo-in>
10901 Set the stereo mode the video is assumed to be encoded
10902 in. Use --vf=format:stereo-in=help to list all available
10903 modes. Check with the stereo3d filter documentation to
10904 see what the names mean.
10905 <stereo-out>
10907 Set the stereo mode the video should be displayed as.
10908 Takes the same values as the stereo-in option.
10909 <rotate>
10911 Set the rotation the video is assumed to be encoded with
10912 in degrees. The special value -1 uses the input format.
10913 <w>, <h>
10915 If not 0, perform conversion to the given size. Ignored
10916 if convert=yes is not set.
10917 <dw>, <dh>
10919 Set the display size. Note that setting the display size
10920 such that the video is scaled in both directions instead
10921 of just changing the aspect ratio is an implementation
10922 detail, and might change later.
10923 <dar> Set the display aspect ratio of the video frame. This is
10925 a float, but values such as [16:9] can be passed too
10926 ([...] for quoting to prevent the option parser from in‐
10927 terpreting the : character).
10928 <force-scaler=auto|zimg|sws>
10930 Force a specific scaler backend, if applicable. This is a
10931 debug option and could go away any time.
10932 <alpha=auto|straight|premul>
10934 Set the kind of alpha the video uses. Undefined effect if
10935 the image format has no alpha channel (could be ignored
10936 or cause an error, depending on how mpv internals
10937 evolve). Setting this may or may not cause downstream im‐
10938 age processing to treat alpha differently, depending on
10939 support. With convert and zimg used, this will convert
10940 the alpha. libswscale and other FFmpeg components com‐
10941 pletely ignore this.
10942 lavfi=graph[:sws-flags[:o=opts]]
10944 Filter video using FFmpeg's libavfilter.
10945 <graph>
10947 The libavfilter graph string. The filter must have a sin‐
10948 gle video input pad and a single video output pad.
10949 See https://ffmpeg.org/ffmpeg-filters.html for syntax and
10951 available filters.
10952 WARNING:
10954 If you want to use the full filter syntax with this
10955 option, you have to quote the filter graph in order to
10956 prevent mpv's syntax and the filter graph syntax from
10957 clashing. To prevent a quoting and escaping mess, con‐
10958 sider using --lavfi-complex if you know which video
10959 track you want to use from the input file. (There is
10960 only one video track for nearly all video files any‐
10961 way.)
10962 Examples
10964 --vf=lavfi=[gradfun=20:30,vflip]
10966 gradfun filter with nonsense parameters, fol‐
10967 lowed by a vflip filter. (This demonstrates how
10968 libavfilter takes a graph and not just a single
10969 filter.) The filter graph string is quoted with
10970 [ and ]. This requires no additional quoting or
10971 escaping with some shells (like bash), while
10972 others (like zsh) require additional " quotes
10973 around the option string.
10974 '--vf=lavfi="gradfun=20:30,vflip"'
10976 Same as before, but uses quoting that should be
10977 safe with all shells. The outer ' quotes make
10978 sure that the shell does not remove the "
10979 quotes needed by mpv.
10980 '--vf=lavfi=graph="gradfun=ra‐
10982 dius=30:strength=20,vflip"'
10983 Same as before, but uses named parameters for
10984 everything.
10985 <sws-flags>
10987 If libavfilter inserts filters for pixel format conver‐
10988 sion, this option gives the flags which should be passed
10989 to libswscale. This option is numeric and takes a
10990 bit-wise combination of SWS_ flags.
10991 See https://git.videolan.org/?p=ffmpeg.git;a=blob;f=lib‐
10993 swscale/swscale.h.
10994 <o> Set AVFilterGraph options. These should be documented by
10996 FFmpeg.
10997 Example
10999 '--vf=lavfi=yadif:o="threads=2,thread_type=slice"'
11001 forces a specific threading configuration.
11002 sub=[=bottom-margin:top-margin]
11004 Moves subtitle rendering to an arbitrary point in the filter
11005 chain, or force subtitle rendering in the video filter as op‐
11006 posed to using video output OSD support.
11007 <bottom-margin>
11009 Adds a black band at the bottom of the frame. The SSA/ASS
11010 renderer can place subtitles there (with --sub-use-mar‐
11011 gins).
11012 <top-margin>
11014 Black band on the top for toptitles (with --sub-use-mar‐
11015 gins).
11016 Examples
11018 --vf=sub,eq
11020 Moves sub rendering before the eq filter. This will
11021 put both subtitle colors and video under the influence
11022 of the video equalizer settings.
11023 vapoursynth=file:buffered-frames:concurrent-frames
11025 Loads a VapourSynth filter script. This is intended for streamed
11026 processing: mpv actually provides a source filter, instead of
11027 using a native VapourSynth video source. The mpv source will an‐
11028 swer frame requests only within a small window of frames (the
11029 size of this window is controlled with the buffered-frames pa‐
11030 rameter), and requests outside of that will return errors. As
11031 such, you can't use the full power of VapourSynth, but you can
11032 use certain filters.
11033 WARNING:
11035 Do not use this filter, unless you have expert knowledge in
11036 VapourSynth, and know how to fix bugs in the mpv VapourSynth
11037 wrapper code.
11038 If you just want to play video generated by VapourSynth (i.e.
11040 using a native VapourSynth video source), it's better to use
11041 vspipe and a pipe or FIFO to feed the video to mpv. The same ap‐
11042 plies if the filter script requires random frame access (see
11043 buffered-frames parameter).
11044 file Filename of the script source. Currently, this is always
11046 a python script (.vpy in VapourSynth convention).
11047 The variable video_in is set to the mpv video source, and
11049 it is expected that the script reads video from it. (Oth‐
11050 erwise, mpv will decode no video, and the video packet
11051 queue will overflow, eventually leading to only audio
11052 playing, or worse.)
11053 The filter graph created by the script is also expected
11055 to pass through timestamps using the _DurationNum and
11056 _DurationDen frame properties.
11057 See the end of the option list for a full list of script
11059 variables defined by mpv.
11060 Example:
11062 import vapoursynth as vs
11064 from vapoursynth import core
11065 core.std.AddBorders(video_in, 10, 10, 20, 20).set_output()
11066 WARNING:
11068 The script will be reloaded on every seek. This is
11069 done to reset the filter properly on discontinuities.
11070 buffered-frames
11072 Maximum number of decoded video frames that should be
11073 buffered before the filter (default: 4). This specifies
11074 the maximum number of frames the script can request in
11075 backward direction.
11076 E.g. if buffered-frames=5, and the script just requested
11078 frame 15, it can still request frame 10, but frame 9 is
11079 not available anymore. If it requests frame 30, mpv will
11080 decode 15 more frames, and keep only frames 25-30.
11081 The only reason why this buffer exists is to serve the
11083 random access requests the VapourSynth filter can make.
11084 The VapourSynth API has a getFrameAsync function, which
11086 takes an absolute frame number. Source filters must re‐
11087 spond to all requests. For example, a source filter can
11088 request frame 2432, and then frame 3. Source filters
11089 typically implement this by pre-indexing the entire file.
11090 mpv on the other hand is stream oriented, and does not
11092 allow filters to seek. (And it would not make sense to
11093 allow it, because it would ruin performance.) Filters get
11094 frames sequentially in playback direction, and cannot re‐
11095 quest them out of order.
11096 To compensate for this mismatch, mpv allows the filter to
11098 access frames within a certain window. buffered-frames
11099 controls the size of this window. Most VapourSynth fil‐
11100 ters happen to work with this, because mpv requests
11101 frames sequentially increasing from it, and most filters
11102 only require frames "close" to the requested frame.
11103 If the filter requests a frame that has a higher frame
11105 number than the highest buffered frame, new frames will
11106 be decoded until the requested frame number is reached.
11107 Excessive frames will be flushed out in a FIFO manner
11108 (there are only at most buffered-frames in this buffer).
11109 If the filter requests a frame that has a lower frame
11111 number than the lowest buffered frame, the request cannot
11112 be satisfied, and an error is returned to the filter.
11113 This kind of error is not supposed to happen in a
11114 "proper" VapourSynth environment. What exactly happens
11115 depends on the filters involved.
11116 Increasing this buffer will not improve performance.
11118 Rather, it will waste memory, and slow down seeks (when
11119 enough frames to fill the buffer need to be decoded at
11120 once). It is only needed to prevent the error described
11121 in the previous paragraph.
11122 How many frames a filter requires depends on filter im‐
11124 plementation details, and mpv has no way of knowing. A
11125 scale filter might need only 1 frame, an interpolation
11126 filter may require a small number of frames, and the Re‐
11127 verse filter will require an infinite number of frames.
11128 If you want reliable operation to the full extend
11130 VapourSynth is capable, use vspipe.
11131 The actual number of buffered frames also depends on the
11133 value of the concurrent-frames option. Currently, both
11134 option values are multiplied to get the final buffer
11135 size.
11136 concurrent-frames
11138 Number of frames that should be requested in parallel.
11139 The level of concurrency depends on the filter and how
11140 quickly mpv can decode video to feed the filter. This
11141 value should probably be proportional to the number of
11142 cores on your machine. Most time, making it higher than
11143 the number of cores can actually make it slower.
11144 Technically, mpv will call the VapourSynth getFrameAsync
11146 function in a loop, until there are concurrent-frames
11147 frames that have not been returned by the filter yet.
11148 This also assumes that the rest of the mpv filter chain
11149 reads the output of the vapoursynth filter quickly
11150 enough. (For example, if you pause the player, filtering
11151 will stop very soon, because the filtered frames are
11152 waiting in a queue.)
11153 Actual concurrency depends on many other factors.
11155 By default, this uses the special value auto, which sets
11157 the option to the number of detected logical CPU cores.
11158 The following .vpy script variables are defined by mpv:
11160 video_in
11162 The mpv video source as vapoursynth clip. Note that this
11163 has an incorrect (very high) length set, which confuses
11164 many filters. This is necessary, because the true number
11165 of frames is unknown. You can use the Trim filter on the
11166 clip to reduce the length.
11167 video_in_dw, video_in_dh
11169 Display size of the video. Can be different from video
11170 size if the video does not use square pixels (e.g. DVD).
11171 container_fps
11173 FPS value as reported by file headers. This value can be
11174 wrong or completely broken (e.g. 0 or NaN). Even if the
11175 value is correct, if another filter changes the real FPS
11176 (by dropping or inserting frames), the value of this
11177 variable will not be useful. Note that the --fps command
11178 line option overrides this value.
11179 Useful for some filters which insist on having a FPS.
11181 display_fps
11183 Refresh rate of the current display. Note that this value
11184 can be 0.
11185 vavpp VA-API video post processing. Requires the system to support
11187 VA-API, i.e. Linux/BSD only. Works with --vo=vaapi and --vo=gpu
11188 only. Currently deinterlaces. This filter is automatically in‐
11189 serted if deinterlacing is requested (either using the d key, by
11190 default mapped to the command cycle deinterlace, or the --dein‐
11191 terlace option).
11192 deint=<method>
11194 Select the deinterlacing algorithm.
11195 no Don't perform deinterlacing.
11197 auto Select the best quality deinterlacing algorithm
11199 (default). This goes by the order of the options
11200 as documented, with motion-compensated being con‐
11201 sidered best quality.
11202 first-field
11204 Show only first field.
11205 bob bob deinterlacing.
11207 weave, motion-adaptive, motion-compensated
11209 Advanced deinterlacing algorithms. Whether these
11210 actually work depends on the GPU hardware, the GPU
11211 drivers, driver bugs, and mpv bugs.
11212 <interlaced-only>
11214 no Deinterlace all frames (default).
11216 yes Only deinterlace frames marked as interlaced.
11218 reversal-bug=<yes|no>
11220 no Use the API as it was interpreted by older Mesa
11222 drivers. While this interpretation was more obvi‐
11223 ous and intuitive, it was apparently wrong, and
11224 not shared by Intel driver developers.
11225 yes Use Intel interpretation of surface forward and
11227 backwards references (default). This is what Intel
11228 drivers and newer Mesa drivers expect. Matters
11229 only for the advanced deinterlacing algorithms.
11230 vdpaupp
11232 VDPAU video post processing. Works with --vo=vdpau and --vo=gpu
11233 only. This filter is automatically inserted if deinterlacing is
11234 requested (either using the d key, by default mapped to the com‐
11235 mand cycle deinterlace, or the --deinterlace option). When en‐
11236 abling deinterlacing, it is always preferred over software dein‐
11237 terlacer filters if the vdpau VO is used, and also if gpu is
11238 used and hardware decoding was activated at least once (i.e. vd‐
11239 pau was loaded).
11240 sharpen=<-1-1>
11242 For positive values, apply a sharpening algorithm to the
11243 video, for negative values a blurring algorithm (default:
11244 0).
11245 denoise=<0-1>
11247 Apply a noise reduction algorithm to the video (default:
11248 0; no noise reduction).
11249 deint=<yes|no>
11251 Whether deinterlacing is enabled (default: no). If en‐
11252 abled, it will use the mode selected with deint-mode.
11253 deint-mode=<first-field|bob|temporal|temporal-spatial>
11255 Select deinterlacing mode (default: temporal).
11256 Note that there's currently a mechanism that allows the
11258 vdpau VO to change the deint-mode of auto-inserted vd‐
11259 paupp filters. To avoid confusion, it's recommended not
11260 to use the --vo=vdpau suboptions related to filtering.
11261 first-field
11263 Show only first field.
11264 bob Bob deinterlacing.
11266 temporal
11268 Motion-adaptive temporal deinterlacing. May lead
11269 to A/V desync with slow video hardware and/or high
11270 resolution.
11271 temporal-spatial
11273 Motion-adaptive temporal deinterlacing with
11274 edge-guided spatial interpolation. Needs fast
11275 video hardware.
11276 chroma-deint
11278 Makes temporal deinterlacers operate both on luma and
11279 chroma (default). Use no-chroma-deint to solely use luma
11280 and speed up advanced deinterlacing. Useful with slow
11281 video memory.
11282 pullup Try to apply inverse telecine, needs motion adaptive tem‐
11284 poral deinterlacing.
11285 interlaced-only=<yes|no>
11287 If yes, only deinterlace frames marked as interlaced (de‐
11288 fault: no).
11289 hqscaling=<0-9>
11291 0 Use default VDPAU scaling (default).
11293 1-9 Apply high quality VDPAU scaling (needs capable
11295 hardware).
11296 d3d11vpp
11298 Direct3D 11 video post processing. Currently requires D3D11
11299 hardware decoding for use.
11300 deint=<yes|no>
11302 Whether deinterlacing is enabled (default: no).
11303 interlaced-only=<yes|no>
11305 If yes, only deinterlace frames marked as interlaced (de‐
11306 fault: no).
11307 mode=<blend|bob|adaptive|mocomp|ivctc|none>
11309 Tries to select a video processor with the given process‐
11310 ing capability. If a video processor supports multiple
11311 capabilities, it is not clear which algorithm is actually
11312 selected. none always falls back. On most if not all
11313 hardware, this option will probably do nothing, because a
11314 video processor usually supports all modes or none.
11315 fingerprint=...
11317 Compute video frame fingerprints and provide them as metadata.
11318 Actually, it currently barely deserved to be called fingerprint,
11319 because it does not compute "proper" fingerprints, only tiny
11320 downscaled images (but which can be used to compute image hashes
11321 or for similarity matching).
11322 The main purpose of this filter is to support the skip-logo.lua
11324 script. If this script is dropped, or mpv ever gains a way to
11325 load user-defined filters (other than VapourSynth), this filter
11326 will be removed. Due to the "special" nature of this filter, it
11327 will be removed without warning.
11328 The intended way to read from the filter is using vf-metadata
11330 (also see clear-on-query filter parameter). The property will
11331 return a list of key/value pairs as follows:
11332 fp0.pts = 1.2345
11334 fp0.hex = 1234abcdef...bcde
11335 fp1.pts = 1.4567
11336 fp1.hex = abcdef1234...6789
11337 ...
11338 fpN.pts = ...
11339 fpN.hex = ...
11340 type = gray-hex-16x16
11341 Each fp<N> entry is for a frame. The pts entry specifies the
11343 timestamp of the frame (within the filter chain; in simple cases
11344 this is the same as the display timestamp). The hex field is the
11345 hex encoded fingerprint, whose size and meaning depend on the
11346 type filter option. The type field has the same value as the
11347 option the filter was created with.
11348 This returns the frames that were filtered since the last query
11350 of the property. If clear-on-query=no was set, a query doesn't
11351 reset the list of frames. In both cases, a maximum of 10 frames
11352 is returned. If there are more frames, the oldest frames are
11353 discarded. Frames are returned in filter order.
11354 (This doesn't return a structured list for the per-frame details
11356 because the internals of the vf-metadata mechanism suck. The re‐
11357 turned format may change in the future.)
11358 This filter uses zimg for speed and profit. However, it will
11360 fallback to libswscale in a number of situations: lesser pixel
11361 formats, unaligned data pointers or strides, or if zimg fails to
11362 initialize for unknown reasons. In these cases, the filter will
11363 use more CPU. Also, it will output different fingerprints, be‐
11364 cause libswscale cannot perform the full range expansion we nor‐
11365 mally request from zimg. As a consequence, the filter may be
11366 slower and not work correctly in random situations.
11367 type=...
11369 What fingerprint to compute. Available types are:
11370 gray-hex-8x8
11372 grayscale, 8 bit, 8x8 size
11373 gray-hex-16x16
11375 grayscale, 8 bit, 16x16 size (default)
11376 Both types simply remove all colors, downscale the image,
11378 concatenate all pixel values to a byte array, and convert
11379 the array to a hex string.
11380 clear-on-query=yes|no
11382 Clear the list of frame fingerprints if the vf-metadata
11383 property for this filter is queried (default: yes). This
11384 requires some care by the user. Some types of accesses
11385 might query the filter multiple times, which leads to
11386 lost frames.
11387 print=yes|no
11389 Print computed fingerprints to the terminal (default:
11390 no). This is mostly for testing and such. Scripts should
11391 use vf-metadata to read information from this filter in‐
11392 stead.
11393 gpu=...
11395 Convert video to RGB using the OpenGL renderer normally used
11396 with --vo=gpu. This requires that the EGL implementation sup‐
11397 ports off-screen rendering on the default display. (This is the
11398 case with Mesa.)
11399 Sub-options:
11401 w=<pixels>, h=<pixels>
11403 Size of the output in pixels (default: 0). If not posi‐
11404 tive, this will use the size of the first filtered input
11405 frame.
11406 WARNING:
11408 This is highly experimental. Performance is bad, and it will
11409 not work everywhere in the first place. Some features are not
11410 supported.
11411 WARNING:
11413 This does not do OSD rendering. If you see OSD, then it has
11414 been rendered by the VO backend. (Subtitles are rendered by
11415 the gpu filter, if possible.)
11416 WARNING:
11418 If you use this with encoding mode, keep in mind that encod‐
11419 ing mode will convert the RGB filter's output back to yuv420p
11420 in software, using the configured software scaler. Using zimg
11421 might improve this, but in any case it might go against your
11422 goals when using this filter.
11423 WARNING:
11425 Do not use this with --vo=gpu. It will apply filtering twice,
11426 since most --vo=gpu options are unconditionally applied to
11427 the gpu filter. There is no mechanism in mpv to prevent this.
11428
11430 You can encode files from one format/codec to another using this facil‐
11431 ity.
11432 --o=<filename>
11434 Enables encoding mode and specifies the output file name.
11435 --of=<format>
11437 Specifies the output format (overrides autodetection by the file
11438 name extension of the file specified by -o). See --of=help for a
11439 full list of supported formats.
11440 --ofopts=<options>
11442 Specifies the output format options for libavformat. See
11443 --ofopts=help for a full list of supported options.
11444 This is a key/value list option. See List Options for details.
11446 --ofopts-add=<option>
11448 Appends the option given as an argument to the options
11449 list. (Passing multiple options is currently still possi‐
11450 ble, but deprecated.)
11451 --ofopts=""
11453 Completely empties the options list.
11454 --oac=<codec>
11456 Specifies the output audio codec. See --oac=help for a full list
11457 of supported codecs.
11458 --oaoffset=<value>
11460 Shifts audio data by the given time (in seconds) by adding/re‐
11461 moving samples at the start. Deprecated.
11462 --oacopts=<options>
11464 Specifies the output audio codec options for libavcodec. See
11465 --oacopts=help for a full list of supported options.
11466 Example
11468 "--oac=libmp3lame --oacopts=b=128000"
11470 selects 128 kbps MP3 encoding.
11471 This is a key/value list option. See List Options for details.
11473 --oacopts-add=<option>
11475 Appends the option given as an argument to the options
11476 list. (Passing multiple options is currently still possi‐
11477 ble, but deprecated.)
11478 --oacopts=""
11480 Completely empties the options list.
11481 --oafirst
11483 Force the audio stream to become the first stream in the output.
11484 By default, the order is unspecified. Deprecated.
11485 --ovc=<codec>
11487 Specifies the output video codec. See --ovc=help for a full list
11488 of supported codecs.
11489 --ovoffset=<value>
11491 Shifts video data by the given time (in seconds) by shifting the
11492 pts values. Deprecated.
11493 --ovcopts=<options>
11495 Specifies the output video codec options for libavcodec. See
11496 --ovcopts=help for a full list of supported options.
11497 Examples
11499 "--ovc=mpeg4 --ovcopts=qscale=5"
11501 selects constant quantizer scale 5 for MPEG-4 encod‐
11502 ing.
11503 "--ovc=libx264 --ovcopts=crf=23"
11505 selects VBR quality factor 23 for H.264 encoding.
11506 This is a key/value list option. See List Options for details.
11508 --ovcopts-add=<option>
11510 Appends the option given as an argument to the options
11511 list. (Passing multiple options is currently still possi‐
11512 ble, but deprecated.)
11513 --ovcopts=""
11515 Completely empties the options list.
11516 --ovfirst
11518 Force the video stream to become the first stream in the output.
11519 By default, the order is unspecified. Deprecated.
11520 --orawts
11522 Copies input pts to the output video (not supported by some out‐
11523 put container formats, e.g. AVI). In this mode, discontinuities
11524 are not fixed and all pts are passed through as-is. Never seek
11525 backwards or use multiple input files in this mode!
11526 --no-ocopy-metadata
11528 Turns off copying of metadata from input files to output files
11529 when encoding (which is enabled by default).
11530 --oset-metadata=<metadata-tag[,metadata-tag,...]>
11532 Specifies metadata to include in the output file. Supported
11533 keys vary between output formats. For example, Matroska (MKV)
11534 and FLAC allow almost arbitrary keys, while support in MP4 and
11535 MP3 is more limited.
11536 This is a key/value list option. See List Options for details.
11538 Example
11540 "--oset-metadata=title="Output title",comment="Another tag""
11542 adds a title and a comment to the output file.
11543 --oremove-metadata=<metadata-tag[,metadata-tag,...]>
11545 Specifies metadata to exclude from the output file when copying
11546 from the input file.
11547 This is a string list option. See List Options for details.
11549 Example
11551 "--oremove-metadata=comment,genre"
11553 excludes copying of the the comment and genre tags to
11554 the output file.
11555
11557 The mpv core can be controlled with commands and properties. A number
11558 of ways to interact with the player use them: key bindings (in‐
11559 put.conf), OSD (showing information with properties), JSON IPC, the
11560 client API (libmpv), and the classic slave mode.
11561 input.conf
11563 The input.conf file consists of a list of key bindings, for example:
11564 s screenshot # take a screenshot with the s key
11566 LEFT seek 15 # map the left-arrow key to seeking forward by 15 seconds
11567 Each line maps a key to an input command. Keys are specified with their
11569 literal value (upper case if combined with Shift), or a name for spe‐
11570 cial keys. For example, a maps to the a key without shift, and A maps
11571 to a with shift.
11572 The file is located in the mpv configuration directory (normally at
11574 ~/.config/mpv/input.conf depending on platform). The default bindings
11575 are defined here:
11576 https://github.com/mpv-player/mpv/blob/master/etc/input.conf
11578 A list of special keys can be obtained with
11580 mpv --input-keylist
11581 In general, keys can be combined with Shift, Ctrl and Alt:
11583 ctrl+q quit
11585 mpv can be started in input test mode, which displays key bindings and
11587 the commands they're bound to on the OSD, instead of executing the com‐
11588 mands:
11589 mpv --input-test --force-window --idle
11591 (Only closing the window will make mpv exit, pressing normal keys will
11593 merely display the binding, even if mapped to quit.)
11594 Also see Key names.
11596 input.conf syntax
11598 [Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] <command> ( ; <command>
11599 )*
11600 Note that by default, the right Alt key can be used to create special
11602 characters, and thus does not register as a modifier. The option
11603 --no-input-right-alt-gr changes this behavior.
11604 Newlines always start a new binding. # starts a comment (outside of
11606 quoted string arguments). To bind commands to the # key, SHARP can be
11607 used.
11608 <key> is either the literal character the key produces (ASCII or Uni‐
11610 code character), or a symbolic name (as printed by --input-keylist).
11611 <section> (braced with { and }) is the input section for this command.
11613 <command> is the command itself. It consists of the command name and
11615 multiple (or none) arguments, all separated by whitespace. String argu‐
11616 ments should be quoted, typically with ". See Flat command syntax.
11617 You can bind multiple commands to one key. For example:
11619 a show-text "command 1" ; show-text "command 2"
11620 It's also possible to bind a command to a sequence of keys:
11623 a-b-c show-text "command run after a, b, c have been pressed"
11624 (This is not shown in the general command syntax.)
11627 If a or a-b or b are already bound, this will run the first command
11629 that matches, and the multi-key command will never be called. Interme‐
11630 diate keys can be remapped to ignore in order to avoid this issue. The
11631 maximum number of (non-modifier) keys for combinations is currently 4.
11632 Key names
11634 All mouse and keyboard input is to converted to mpv-specific key names.
11635 Key names are either special symbolic identifiers representing a physi‐
11636 cal key, or a text key names, which are unicode code points encoded as
11637 UTF-8. These are what keyboard input would normally produce, for exam‐
11638 ple a for the A key. As a consequence, mpv uses input translated by the
11639 current OS keyboard layout, rather than physical scan codes.
11640 Currently there is the hardcoded assumption that every text key can be
11642 represented as a single unicode code point (in NFKC form).
11643 All key names can be combined with the modifiers Shift, Ctrl, Alt,
11645 Meta. They must be prefixed to the actual key name, where each modifier
11646 is followed by a + (for example ctrl+q).
11647 The Shift modifier requires some attention. For instance Shift+2 should
11649 usually be specified as key-name @ at input.conf, and similarly the
11650 combination Alt+Shift+2 is usually Alt+@, etc. Special key names like
11651 Shift+LEFT work as expected. If in doubt - use --input-test to check
11652 how a key/combination is seen by mpv.
11653 Symbolic key names and modifier names are case-insensitive. Unicode key
11655 names are case-sensitive because input bindings typically respect the
11656 shift key.
11657 Another type of key names are hexadecimal key names, that serve as
11659 fallback for special keys that are neither unicode, nor have a special
11660 mpv defined name. They will break as soon as mpv adds proper names for
11661 them, but can enable you to use a key at all if that does not happen.
11662 All symbolic names are listed by --input-keylist. --input-test is a
11664 special mode that prints all input on the OSD.
11665 Comments on some symbolic names:
11667 KP* Keypad names. Behavior varies by backend (whether they implement
11669 this, and on how they treat numlock), but typically, mpv tries
11670 to map keys on the keypad to separate names, even if they pro‐
11671 duce the same text as normal keys.
11672 MOUSE_BTN*, MBTN*
11674 Various mouse buttons.
11675 Depending on backend, the mouse wheel might also be represented
11677 as a button. In addition, MOUSE_BTN3 to MOUSE_BTN6 are depre‐
11678 cated aliases for WHEEL_UP, WHEEL_DOWN, WHEEL_LEFT, WHEEL_RIGHT.
11679 MBTN* are aliases for MOUSE_BTN*.
11681 WHEEL_*
11683 Mouse wheels (typically).
11684 AXIS_* Deprecated aliases for WHEEL_*.
11686 *_DBL Mouse button double clicks.
11688 MOUSE_MOVE, MOUSE_ENTER, MOUSE_LEAVE
11690 Emitted by mouse move events. Enter/leave happens when the mouse
11691 enters or leave the mpv window (or the current mouse region, us‐
11692 ing the deprecated mouse region input section mechanism).
11693 CLOSE_WIN
11695 Pseudo key emitted when closing the mpv window using the OS win‐
11696 dow manager (for example, by clicking the close button in the
11697 window title bar).
11698 GAMEPAD_*
11700 Keys emitted by the SDL gamepad backend.
11701 UNMAPPED
11703 Pseudo-key that matches any unmapped key. (You should probably
11704 avoid this if possible, because it might change behavior or get
11705 removed in the future.)
11706 ANY_UNICODE
11708 Pseudo-key that matches any key that produces text. (You should
11709 probably avoid this if possible, because it might change behav‐
11710 ior or get removed in the future.)
11711 Flat command syntax
11713 This is the syntax used in input.conf, and referred to "input.conf syn‐
11714 tax" in a number of other places.
11715 <command> ::= [<prefixes>] <command_name> (<argument>)*
11717 <argument> ::= (<unquoted> | " <double_quoted> " | ' <single_quoted> ' | `X <custom_quoted> X`)
11718 command_name is an unquoted string with the command name itself. See
11721 List of Input Commands for a list.
11722 Arguments are separated by whitespaces even if the command expects only
11724 one argument. Arguments with whitespaces or other special characters
11725 must be quoted, or the command cannot be parsed correctly.
11726 Double quotes interpret JSON/C-style escaping, like \t or \" or \\.
11728 JSON escapes according to RFC 8259, minus surrogate pair escapes. This
11729 is the only form which allows newlines at the value - as \n.
11730 Single quotes take the content literally, and cannot include the sin‐
11732 gle-quote character at the value.
11733 Custom quotes also take the content literally, but are more flexible
11735 than single quotes. They start with ` (back-quote) followed by any
11736 ASCII character, and end at the first occurance of the same pair in re‐
11737 verse order, e.g. `-foo-` or ``bar``. The final pair sequence is not
11738 allowed at the value - in these examples -` and `` respectively. In the
11739 second example the last character of the value also can't be a
11740 back-quote.
11741 Mixed quoting at the same argument, like 'foo'"bar", is not supported.
11743 Note that argument parsing and property expansion happen at different
11745 stages. First, arguments are determined as described above, and then,
11746 where applicable, properties are expanded - regardless of argument
11747 quoting. However, expansion can still be prevented with the raw prefix
11748 or $>. See Input Command Prefixes and Property Expansion.
11749 Commands specified as arrays
11751 This applies to certain APIs, such as mp.commandv() or mp.command_na‐
11752 tive() (with array parameters) in Lua scripting, or mpv_command() or
11753 mpv_command_node() (with MPV_FORMAT_NODE_ARRAY) in the C libmpv client
11754 API.
11755 The command as well as all arguments are passed as a single array. Sim‐
11757 ilar to the Flat command syntax, you can first pass prefixes as strings
11758 (each as separate array item), then the command name as string, and
11759 then each argument as string or a native value.
11760 Since these APIs pass arguments as separate strings or native values,
11762 they do not expect quotes, and do support escaping. Technically, there
11763 is the input.conf parser, which first splits the command string into
11764 arguments, and then invokes argument parsers for each argument. The in‐
11765 put.conf parser normally handles quotes and escaping. The array command
11766 APIs mentioned above pass strings directly to the argument parsers, or
11767 can sidestep them by the ability to pass non-string values.
11768 Property expansion is disabled by default for these APIs. This can be
11770 changed with the expand-properties prefix. See Input Command Prefixes.
11771 Sometimes commands have string arguments, that in turn are actually
11773 parsed by other components (e.g. filter strings with vf add) - in these
11774 cases, you you would have to double-escape in input.conf, but not with
11775 the array APIs.
11776 For complex commands, consider using Named arguments instead, which
11778 should give slightly more compatibility. Some commands do not support
11779 named arguments and inherently take an array, though.
11780 Named arguments
11782 This applies to certain APIs, such as mp.command_native() (with tables
11783 that have string keys) in Lua scripting, or mpv_command_node() (with
11784 MPV_FORMAT_NODE_MAP) in the C libmpv client API.
11785 The name of the command is provided with a name string field. The name
11787 of each command is defined in each command description in the List of
11788 Input Commands. --input-cmdlist also lists them. See the subprocess
11789 command for an example.
11790 Some commands do not support named arguments (e.g. run command). You
11792 need to use APIs that pass arguments as arrays.
11793 Named arguments are not supported in the "flat" input.conf syntax,
11795 which means you cannot use them for key bindings in input.conf at all.
11796 Property expansion is disabled by default for these APIs. This can be
11798 changed with the expand-properties prefix. See Input Command Prefixes.
11799 List of Input Commands
11801 Commands with parameters have the parameter name enclosed in < / >.
11802 Don't add those to the actual command. Optional arguments are enclosed
11803 in [ / ]. If you don't pass them, they will be set to a default value.
11804 Remember to quote string arguments in input.conf (see Flat command syn‐
11806 tax).
11807 ignore Use this to "block" keys that should be unbound, and do nothing.
11809 Useful for disabling default bindings, without disabling all
11810 bindings with --no-input-default-bindings.
11811 seek <target> [<flags>]
11813 Change the playback position. By default, seeks by a relative
11814 amount of seconds.
11815 The second argument consists of flags controlling the seek mode:
11817 relative (default)
11819 Seek relative to current position (a negative value seeks
11820 backwards).
11821 absolute
11823 Seek to a given time (a negative value starts from the
11824 end of the file).
11825 absolute-percent
11827 Seek to a given percent position.
11828 relative-percent
11830 Seek relative to current position in percent.
11831 keyframes
11833 Always restart playback at keyframe boundaries (fast).
11834 exact Always do exact/hr/precise seeks (slow).
11836 Multiple flags can be combined, e.g.: absolute+keyframes.
11838 By default, keyframes is used for relative, relative-percent,
11840 and absolute-percent seeks, while exact is used for absolute
11841 seeks.
11842 Before mpv 0.9, the keyframes and exact flags had to be passed
11844 as 3rd parameter (essentially using a space instead of +). The
11845 3rd parameter is still parsed, but is considered deprecated.
11846 revert-seek [<flags>]
11848 Undoes the seek command, and some other commands that seek (but
11849 not necessarily all of them). Calling this command once will
11850 jump to the playback position before the seek. Calling it a sec‐
11851 ond time undoes the revert-seek command itself. This only works
11852 within a single file.
11853 The first argument is optional, and can change the behavior:
11855 mark Mark the current time position. The next normal re‐
11857 vert-seek command will seek back to this point, no matter
11858 how many seeks happened since last time.
11859 mark-permanent
11861 If set, mark the current position, and do not change the
11862 mark position before the next revert-seek command that
11863 has mark or mark-permanent set (or playback of the cur‐
11864 rent file ends). Until this happens, revert-seek will al‐
11865 ways seek to the marked point. This flag cannot be com‐
11866 bined with mark.
11867 Using it without any arguments gives you the default behavior.
11869 frame-step
11871 Play one frame, then pause. Does nothing with audio-only play‐
11872 back.
11873 frame-back-step
11875 Go back by one frame, then pause. Note that this can be very
11876 slow (it tries to be precise, not fast), and sometimes fails to
11877 behave as expected. How well this works depends on whether pre‐
11878 cise seeking works correctly (e.g. see the --hr-seek-de‐
11879 muxer-offset option). Video filters or other video post-process‐
11880 ing that modifies timing of frames (e.g. deinterlacing) should
11881 usually work, but might make backstepping silently behave incor‐
11882 rectly in corner cases. Using --hr-seek-framedrop=no should
11883 help, although it might make precise seeking slower.
11884 This does not work with audio-only playback.
11886 set <name> <value>
11888 Set the given property or option to the given value.
11889 add <name> [<value>]
11891 Add the given value to the property or option. On overflow or
11892 underflow, clamp the property to the maximum. If <value> is
11893 omitted, assume 1.
11894 cycle <name> [<value>]
11896 Cycle the given property or option. The second argument can be
11897 up or down to set the cycle direction. On overflow, set the
11898 property back to the minimum, on underflow set it to the maxi‐
11899 mum. If up or down is omitted, assume up.
11900 Whether or not key-repeat is enabled by default depends on the
11902 property. Currently properties with continuous values are re‐
11903 peatable by default (like volume), while discrete values are not
11904 (like osd-level).
11905 multiply <name> <value>
11907 Similar to add, but multiplies the property or option with the
11908 numeric value.
11909 screenshot <flags>
11911 Take a screenshot.
11912 Multiple flags are available (some can be combined with +):
11914 <subtitles> (default)
11916 Save the video image, in its original resolution, and
11917 with subtitles. Some video outputs may still include the
11918 OSD in the output under certain circumstances.
11919 <video>
11921 Like subtitles, but typically without OSD or subtitles.
11922 The exact behavior depends on the selected video output.
11923 <window>
11925 Save the contents of the mpv window. Typically scaled,
11926 with OSD and subtitles. The exact behavior depends on the
11927 selected video output, and if no support is available,
11928 this will act like video.
11929 <each-frame>
11931 Take a screenshot each frame. Issue this command again to
11932 stop taking screenshots. Note that you should disable
11933 frame-dropping when using this mode - or you might re‐
11934 ceive duplicate images in cases when a frame was dropped.
11935 This flag can be combined with the other flags, e.g.
11936 video+each-frame.
11937 Older mpv versions required passing single and each-frame as
11939 second argument (and did not have flags). This syntax is still
11940 understood, but deprecated and might be removed in the future.
11941 If you combine this command with another one using ;, you can
11943 use the async flag to make encoding/writing the image file asyn‐
11944 chronous. For normal standalone commands, this is always asyn‐
11945 chronous, and the flag has no effect. (This behavior changed
11946 with mpv 0.29.0.)
11947 screenshot-to-file <filename> <flags>
11949 Take a screenshot and save it to a given file. The format of the
11950 file will be guessed by the extension (and --screenshot-format
11951 is ignored - the behavior when the extension is missing or un‐
11952 known is arbitrary).
11953 The second argument is like the first argument to screenshot and
11955 supports subtitles, video, window.
11956 If the file already exists, it's overwritten.
11958 Like all input command parameters, the filename is subject to
11960 property expansion as described in Property Expansion.
11961 playlist-next <flags>
11963 Go to the next entry on the playlist.
11964 First argument:
11966 weak (default)
11968 If the last file on the playlist is currently played, do
11969 nothing.
11970 force Terminate playback if there are no more files on the
11972 playlist.
11973 playlist-prev <flags>
11975 Go to the previous entry on the playlist.
11976 First argument:
11978 weak (default)
11980 If the first file on the playlist is currently played, do
11981 nothing.
11982 force Terminate playback if the first file is being played.
11984 playlist-play-index <integer|current|none>
11986 Start (or restart) playback of the given playlist index. In ad‐
11987 dition to the 0-based playlist entry index, it supports the fol‐
11988 lowing values:
11989 <current>
11991 The current playlist entry (as in playlist-current-pos)
11992 will be played again (unload and reload). If none is set,
11993 playback is stopped. (In corner cases, playlist-cur‐
11994 rent-pos can point to a playlist entry even if playback
11995 is currently inactive,
11996 <none> Playback is stopped. If idle mode (--idle) is enabled,
11998 the player will enter idle mode, otherwise it will exit.
11999 This command is similar to loadfile in that it only manipulates
12001 the state of what to play next, without waiting until the cur‐
12002 rent file is unloaded, and the next one is loaded.
12003 Setting playlist-pos or similar properties can have a similar
12005 effect to this command. However, it's more explicit, and guaran‐
12006 tees that playback is restarted if for example the new playlist
12007 entry is the same as the previous one.
12008 loadfile <url> [<flags> [<options>]]
12010 Load the given file or URL and play it. Technically, this is
12011 just a playlist manipulation command (which either replaces the
12012 playlist or appends an entry to it). Actual file loading happens
12013 independently. For example, a loadfile command that replaces the
12014 current file with a new one returns before the current file is
12015 stopped, and the new file even begins loading.
12016 Second argument:
12018 <replace> (default)
12020 Stop playback of the current file, and play the new file
12021 immediately.
12022 <append>
12024 Append the file to the playlist.
12025 <append-play>
12027 Append the file, and if nothing is currently playing,
12028 start playback. (Always starts with the added file, even
12029 if the playlist was not empty before running this com‐
12030 mand.)
12031 The third argument is a list of options and values which should
12033 be set while the file is playing. It is of the form
12034 opt1=value1,opt2=value2,... When using the client API, this can
12035 be a MPV_FORMAT_NODE_MAP (or a Lua table), however the values
12036 themselves must be strings currently. These options are set dur‐
12037 ing playback, and restored to the previous value at end of play‐
12038 back (see Per-File Options).
12039 loadlist <url> [<flags>]
12041 Load the given playlist file or URL (like --playlist).
12042 Second argument:
12044 <replace> (default)
12046 Stop playback and replace the internal playlist with the
12047 new one.
12048 <append>
12050 Append the new playlist at the end of the current inter‐
12051 nal playlist.
12052 <append-play>
12054 Append the new playlist, and if nothing is currently
12055 playing, start playback. (Always starts with the new
12056 playlist, even if the internal playlist was not empty be‐
12057 fore running this command.)
12058 playlist-clear
12060 Clear the playlist, except the currently played file.
12061 playlist-remove <index>
12063 Remove the playlist entry at the given index. Index values start
12064 counting with 0. The special value current removes the current
12065 entry. Note that removing the current entry also stops playback
12066 and starts playing the next entry.
12067 playlist-move <index1> <index2>
12069 Move the playlist entry at index1, so that it takes the place of
12070 the entry index2. (Paradoxically, the moved playlist entry will
12071 not have the index value index2 after moving if index1 was lower
12072 than index2, because index2 refers to the target entry, not the
12073 index the entry will have after moving.)
12074 playlist-shuffle
12076 Shuffle the playlist. This is similar to what is done on start
12077 if the --shuffle option is used.
12078 playlist-unshuffle
12080 Attempt to revert the previous playlist-shuffle command. This
12081 works only once (multiple successive playlist-unshuffle commands
12082 do nothing). May not work correctly if new recursive playlists
12083 have been opened since a playlist-shuffle command.
12084 run <command> [<arg1> [<arg2> [...]]]
12086 Run the given command. Unlike in MPlayer/mplayer2 and earlier
12087 versions of mpv (0.2.x and older), this doesn't call the shell.
12088 Instead, the command is run directly, with each argument passed
12089 separately. Each argument is expanded like in Property Expan‐
12090 sion.
12091 This command has a variable number of arguments, and cannot be
12093 used with named arguments.
12094 The program is run in a detached way. mpv doesn't wait until the
12096 command is completed, but continues playback right after spawn‐
12097 ing it.
12098 To get the old behavior, use /bin/sh and -c as the first two ar‐
12100 guments.
12101 Example
12103 run "/bin/sh" "-c" "echo ${title} > /tmp/playing"
12105 This is not a particularly good example, because it
12107 doesn't handle escaping, and a specially prepared file
12108 might allow an attacker to execute arbitrary shell
12109 commands. It is recommended to write a small shell
12110 script, and call that with run.
12111 subprocess
12113 Similar to run, but gives more control about process execution
12114 to the caller, and does does not detach the process.
12115 You can avoid blocking until the process terminates by running
12117 this command asynchronously. (For example mp.command_na‐
12118 tive_async() in Lua scripting.)
12119 This has the following named arguments. The order of them is not
12121 guaranteed, so you should always call them with named arguments,
12122 see Named arguments.
12123 args (MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING])
12125 Array of strings with the command as first argument, and
12126 subsequent command line arguments following. This is just
12127 like the run command argument list.
12128 The first array entry is either an absolute path to the
12130 executable, or a filename with no path components, in
12131 which case the executable is searched in the directories
12132 in the PATH environment variable. On Unix, this is equiv‐
12133 alent to posix_spawnp and execvp behavior.
12134 playback_only (MPV_FORMAT_FLAG)
12136 Boolean indicating whether the process should be killed
12137 when playback of the current playlist entry terminates
12138 (optional, default: true). If enabled, stopping playback
12139 will automatically kill the process, and you can't start
12140 it outside of playback.
12141 capture_size (MPV_FORMAT_INT64)
12143 Integer setting the maximum number of stdout plus stderr
12144 bytes that can be captured (optional, default: 64MB). If
12145 the number of bytes exceeds this, capturing is stopped.
12146 The limit is per captured stream.
12147 capture_stdout (MPV_FORMAT_FLAG)
12149 Capture all data the process outputs to stdout and return
12150 it once the process ends (optional, default: no).
12151 capture_stderr (MPV_FORMAT_FLAG)
12153 Same as capture_stdout, but for stderr.
12154 detach (MPV_FORMAT_FLAG)
12156 Whether to run the process in detached mode (optional,
12157 default: no). In this mode, the process is run in a new
12158 process session, and the command does not wait for the
12159 process to terminate. If neither capture_stdout nor cap‐
12160 ture_stderr have been set to true, the command returns
12161 immediately after the new process has been started, oth‐
12162 erwise the command will read as long as the pipes are
12163 open.
12164 env (MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING])
12166 Set a list of environment variables for the new process
12167 (default: empty). If an empty list is passed, the envi‐
12168 ronment of the mpv process is used instead. (Unlike the
12169 underlying OS mechanisms, the mpv command cannot start a
12170 process with empty environment. Fortunately, that is com‐
12171 pletely useless.) The format of the list is as in the ex‐
12172 ecle() syscall. Each string item defines an environment
12173 variable as in NAME=VALUE.
12174 On Lua, you may use utils.get_env_list() to retrieve the
12176 current environment if you e.g. simply want to add a new
12177 variable.
12178 stdin_data (MPV_FORMAT_STRING)
12180 Feed the given string to the new process' stdin. Since
12181 this is a string, you cannot pass arbitrary binary data.
12182 If the process terminates or closes the pipe before all
12183 data is written, the remaining data is silently dis‐
12184 carded. Probably does not work on win32.
12185 passthrough_stdin (MPV_FORMAT_FLAG)
12187 If enabled, wire the new process' stdin to mpv's stdin
12188 (default: no). Before mpv 0.33.0, this argument did not
12189 exist, but the behavior was as if this was set to true.
12190 The command returns the following result (as MPV_FOR‐
12192 MAT_NODE_MAP):
12193 status (MPV_FORMAT_INT64)
12195 Typically this is the process exit code (0 or positive)
12196 if the process terminates normally, or negative for other
12197 errors (failed to start, terminated by mpv, and others).
12198 The meaning of negative values is undefined, other than
12199 meaning error (and does not correspond to OS low level
12200 exit status values).
12201 On Windows, it can happen that a negative return value is
12203 returned even if the process terminates normally, because
12204 the win32 UINT exit code is assigned to an int variable
12205 before being set as int64_t field in the result map. This
12206 might be fixed later.
12207 stdout (MPV_FORMAT_BYTE_ARRAY)
12209 Captured stdout stream, limited to capture_size.
12210 stderr (MPV_FORMAT_BYTE_ARRAY)
12212 Same as stdout, but for stderr.
12213 error_string (MPV_FORMAT_STRING)
12215 Empty string if the process terminated normally. The
12216 string killed if the process was terminated in an unusual
12217 way. The string init if the process could not be started.
12218 On Windows, killed is only returned when the process has
12220 been killed by mpv as a result of playback_only being set
12221 to true.
12222 killed_by_us (MPV_FORMAT_FLAG)
12224 Whether the process has been killed by mpv, for example
12225 as a result of playback_only being set to true, aborting
12226 the command (e.g. by mp.abort_async_command()), or if the
12227 player is about to exit.
12228 Note that the command itself will always return success as long
12230 as the parameters are correct. Whether the process could be
12231 spawned or whether it was somehow killed or returned an error
12232 status has to be queried from the result value.
12233 This command can be asynchronously aborted via API. Also see
12235 Asynchronous command details. Only the run command can start
12236 processes in a truly detached way.
12237 NOTE:
12239 The subprocess will always be terminated on player exit if it
12240 wasn't started in detached mode, even if playback_only is
12241 false.
12242 Warning
12244 Don't forget to set the playback_only field to false
12246 if you want the command to run while the player is in
12247 idle mode, or if you don't want the end of playback to
12248 kill the command.
12249 Example
12251 local r = mp.command_native({
12253 name = "subprocess",
12254 playback_only = false,
12255 capture_stdout = true,
12256 args = {"cat", "/proc/cpuinfo"},
12257 })
12258 if r.status == 0 then
12259 print("result: " .. r.stdout)
12260 end
12261 This is a fairly useless Lua example, which demonstrates how
12263 to run a process in a blocking manner, and retrieving its
12264 stdout output.
12265 quit [<code>]
12267 Exit the player. If an argument is given, it's used as process
12268 exit code.
12269 quit-watch-later [<code>]
12271 Exit player, and store current playback position. Playing that
12272 file later will seek to the previous position on start. The (op‐
12273 tional) argument is exactly as in the quit command. See RESUMING
12274 PLAYBACK.
12275 sub-add <url> [<flags> [<title> [<lang>]]]
12277 Load the given subtitle file or stream. By default, it is se‐
12278 lected as current subtitle after loading.
12279 The flags argument is one of the following values:
12281 <select>
12283 Select the subtitle immediately (default).
12284 <auto>
12286 Don't select the subtitle. (Or in some special situations,
12287 let the default stream selection mechanism decide.)
12288 <cached>
12290 Select the subtitle. If a subtitle with the same filename was
12291 already added, that one is selected, instead of loading a du‐
12292 plicate entry. (In this case, title/language are ignored,
12293 and if the was changed since it was loaded, these changes
12294 won't be reflected.)
12295 The title argument sets the track title in the UI.
12297 The lang argument sets the track language, and can also influ‐
12299 ence stream selection with flags set to auto.
12300 sub-remove [<id>]
12302 Remove the given subtitle track. If the id argument is missing,
12303 remove the current track. (Works on external subtitle files
12304 only.)
12305 sub-reload [<id>]
12307 Reload the given subtitle tracks. If the id argument is missing,
12308 reload the current track. (Works on external subtitle files
12309 only.)
12310 This works by unloading and re-adding the subtitle track.
12312 sub-step <skip> <flags>
12314 Change subtitle timing such, that the subtitle event after the
12315 next <skip> subtitle events is displayed. <skip> can be negative
12316 to step backwards.
12317 Secondary argument:
12319 primary (default)
12321 Steps through the primary subtitles.
12322 secondary
12324 Steps through the secondary subtitles.
12325 sub-seek <skip> <flags>
12327 Seek to the next (skip set to 1) or the previous (skip set to
12328 -1) subtitle. This is similar to sub-step, except that it seeks
12329 video and audio instead of adjusting the subtitle delay.
12330 Secondary argument:
12332 primary (default)
12334 Seeks through the primary subtitles.
12335 secondary
12337 Seeks through the secondary subtitles.
12338 For embedded subtitles (like with Matroska), this works only
12340 with subtitle events that have already been displayed, or are
12341 within a short prefetch range.
12342 print-text <text>
12344 Print text to stdout. The string can contain properties (see
12345 Property Expansion). Take care to put the argument in quotes.
12346 show-text <text> [<duration>|-1 [<level>]]
12348 Show text on the OSD. The string can contain properties, which
12349 are expanded as described in Property Expansion. This can be
12350 used to show playback time, filename, and so on.
12351 <duration>
12353 The time in ms to show the message for. By default, it
12354 uses the same value as --osd-duration.
12355 <level>
12357 The minimum OSD level to show the text at (see
12358 --osd-level).
12359 expand-text <string>
12361 Property-expand the argument and return the expanded string.
12362 This can be used only through the client API or from a script
12363 using mp.command_native. (see Property Expansion).
12364 expand-path "<string>"
12366 Expand a path's double-tilde placeholders into a platform-spe‐
12367 cific path. As expand-text, this can only be used through the
12368 client API or from a script using mp.command_native.
12369 Example
12371 mp.osd_message(mp.command_native({"expand-path",
12373 "~~home/"}))
12374 This line of Lua would show the location of the user's
12376 mpv configuration directory on the OSD.
12377 show-progress
12379 Show the progress bar, the elapsed time and the total duration
12380 of the file on the OSD.
12381 write-watch-later-config
12383 Write the resume config file that the quit-watch-later command
12384 writes, but continue playback normally.
12385 delete-watch-later-config [<filename>]
12387 Delete any existing resume config file that was written by
12388 quit-watch-later or write-watch-later-config. If a filename is
12389 specified, then the deleted config is for that file; otherwise,
12390 it is the same one as would be written by quit-watch-later or
12391 write-watch-later-config in the current circumstance.
12392 stop [<flags>]
12394 Stop playback and clear playlist. With default settings, this is
12395 essentially like quit. Useful for the client API: playback can
12396 be stopped without terminating the player.
12397 The first argument is optional, and supports the following
12399 flags:
12400 keep-playlist
12402 Do not clear the playlist.
12403 mouse <x> <y> [<button> [<mode>]]
12405 Send a mouse event with given coordinate (<x>, <y>).
12406 Second argument:
12408 <button>
12410 The button number of clicked mouse button. This should be
12411 one of 0-19. If <button> is omitted, only the position
12412 will be updated.
12413 Third argument:
12415 <single> (default)
12417 The mouse event represents regular single click.
12418 <double>
12420 The mouse event represents double-click.
12421 keypress <name>
12423 Send a key event through mpv's input handler, triggering what‐
12424 ever behavior is configured to that key. name uses the in‐
12425 put.conf naming scheme for keys and modifiers. Useful for the
12426 client API: key events can be sent to libmpv to handle inter‐
12427 nally.
12428 keydown <name>
12430 Similar to keypress, but sets the KEYDOWN flag so that if the
12431 key is bound to a repeatable command, it will be run repeatedly
12432 with mpv's key repeat timing until the keyup command is called.
12433 keyup [<name>]
12435 Set the KEYUP flag, stopping any repeated behavior that had been
12436 triggered. name is optional. If name is not given or is an empty
12437 string, KEYUP will be set on all keys. Otherwise, KEYUP will
12438 only be set on the key specified by name.
12439 keybind <name> <command>
12441 Binds a key to an input command. command must be a complete com‐
12442 mand containing all the desired arguments and flags. Both name
12443 and command use the input.conf naming scheme. This is primarily
12444 useful for the client API.
12445 audio-add <url> [<flags> [<title> [<lang>]]]
12447 Load the given audio file. See sub-add command.
12448 audio-remove [<id>]
12450 Remove the given audio track. See sub-remove command.
12451 audio-reload [<id>]
12453 Reload the given audio tracks. See sub-reload command.
12454 video-add <url> [<flags> [<title> [<lang> [<albumart>]]]]
12456 Load the given video file. See sub-add command for common op‐
12457 tions.
12458 albumart (MPV_FORMAT_FLAG)
12460 If enabled, mpv will load the given video as album art.
12461 video-remove [<id>]
12463 Remove the given video track. See sub-remove command.
12464 video-reload [<id>]
12466 Reload the given video tracks. See sub-reload command.
12467 rescan-external-files [<mode>]
12469 Rescan external files according to the current --sub-auto, --au‐
12470 dio-file-auto and --cover-art-auto settings. This can be used to
12471 auto-load external files after the file was loaded.
12472 The mode argument is one of the following:
12474 <reselect> (default)
12476 Select the default audio and subtitle streams, which typ‐
12477 ically selects external files with the highest prefer‐
12478 ence. (The implementation is not perfect, and could be
12479 improved on request.)
12480 <keep-selection>
12482 Do not change current track selections.
12483 Input Commands that are Possibly Subject to Change
12485 af <operation> <value>
12486 Change audio filter chain. See vf command.
12487 vf <operation> <value>
12489 Change video filter chain.
12490 The semantics are exactly the same as with option parsing (see
12492 VIDEO FILTERS). As such the text below is a redundant and incom‐
12493 plete summary.
12494 The first argument decides what happens:
12496 <set> Overwrite the previous filter chain with the new one.
12498 <add> Append the new filter chain to the previous one.
12500 <toggle>
12502 Check if the given filter (with the exact parameters) is
12503 already in the video chain. If it is, remove the filter.
12504 If it isn't, add the filter. (If several filters are
12505 passed to the command, this is done for each filter.)
12506 A special variant is combining this with labels, and us‐
12508 ing @name without filter name and parameters as filter
12509 entry. This toggles the enable/disable flag.
12510 <remove>
12512 Like toggle, but always remove the given filter from the
12513 chain.
12514 <del> Remove the given filters from the video chain. Unlike in
12516 the other cases, the second parameter is a comma sepa‐
12517 rated list of filter names or integer indexes. 0 would
12518 denote the first filter. Negative indexes start from the
12519 last filter, and -1 denotes the last filter. Deprecated,
12520 use remove.
12521 <clr> Remove all filters. Note that like the other sub-com‐
12523 mands, this does not control automatically inserted fil‐
12524 ters.
12525 The argument is always needed. E.g. in case of clr use vf clr
12527 "".
12528 You can assign labels to filter by prefixing them with @name:
12530 (where name is a user-chosen arbitrary identifier). Labels can
12531 be used to refer to filters by name in all of the filter chain
12532 modification commands. For add, using an already used label
12533 will replace the existing filter.
12534 The vf command shows the list of requested filters on the OSD
12536 after changing the filter chain. This is roughly equivalent to
12537 show-text ${vf}. Note that auto-inserted filters for format con‐
12538 version are not shown on the list, only what was requested by
12539 the user.
12540 Normally, the commands will check whether the video chain is
12542 recreated successfully, and will undo the operation on failure.
12543 If the command is run before video is configured (can happen if
12544 the command is run immediately after opening a file and before a
12545 video frame is decoded), this check can't be run. Then it can
12546 happen that creating the video chain fails.
12547 Example for input.conf
12549 • a vf set vflip turn the video upside-down on the a key
12551 • b vf set "" remove all video filters on b
12553 • c vf toggle gradfun toggle debanding on c
12555 Example how to toggle disabled filters at runtime
12557 • Add something like vf-add=@deband:!gradfun to mpv.conf.
12559 The @deband: is the label, an arbitrary, user-given name
12560 for this filter entry. The ! before the filter name dis‐
12561 ables the filter by default. Everything after this is the
12562 normal filter name and possibly filter parameters, like in
12563 the normal --vf syntax.
12564 • Add a vf toggle @deband to input.conf. This toggles the
12566 "disabled" flag for the filter with the label deband when
12567 the a key is hit.
12568 cycle-values [<"!reverse">] <property> <value1> [<value2> [...]]
12570 Cycle through a list of values. Each invocation of the command
12571 will set the given property to the next value in the list. The
12572 command will use the current value of the property/option, and
12573 use it to determine the current position in the list of values.
12574 Once it has found it, it will set the next value in the list
12575 (wrapping around to the first item if needed).
12576 This command has a variable number of arguments, and cannot be
12578 used with named arguments.
12579 The special argument !reverse can be used to cycle the value
12581 list in reverse. The only advantage is that you don't need to
12582 reverse the value list yourself when adding a second key binding
12583 for cycling backwards.
12584 enable-section <name> [<flags>]
12586 This command is deprecated, except for mpv-internal uses.
12587 Enable all key bindings in the named input section.
12589 The enabled input sections form a stack. Bindings in sections on
12591 the top of the stack are preferred to lower sections. This com‐
12592 mand puts the section on top of the stack. If the section was
12593 already on the stack, it is implicitly removed beforehand. (A
12594 section cannot be on the stack more than once.)
12595 The flags parameter can be a combination (separated by +) of the
12597 following flags:
12598 <exclusive>
12600 All sections enabled before the newly enabled section are
12601 disabled. They will be re-enabled as soon as all exclu‐
12602 sive sections above them are removed. In other words, the
12603 new section shadows all previous sections.
12604 <allow-hide-cursor>
12606 This feature can't be used through the public API.
12607 <allow-vo-dragging>
12609 Same.
12610 disable-section <name>
12612 This command is deprecated, except for mpv-internal uses.
12613 Disable the named input section. Undoes enable-section.
12615 define-section <name> <contents> [<flags>]
12617 This command is deprecated, except for mpv-internal uses.
12618 Create a named input section, or replace the contents of an al‐
12620 ready existing input section. The contents parameter uses the
12621 same syntax as the input.conf file (except that using the sec‐
12622 tion syntax in it is not allowed), including the need to sepa‐
12623 rate bindings with a newline character.
12624 If the contents parameter is an empty string, the section is re‐
12626 moved.
12627 The section with the name default is the normal input section.
12629 In general, input sections have to be enabled with the en‐
12631 able-section command, or they are ignored.
12632 The last parameter has the following meaning:
12634 <default> (also used if parameter omitted)
12636 Use a key binding defined by this section only if the
12637 user hasn't already bound this key to a command.
12638 <force>
12640 Always bind a key. (The input section that was made ac‐
12641 tive most recently wins if there are ambiguities.)
12642 This command can be used to dispatch arbitrary keys to a script
12644 or a client API user. If the input section defines script-bind‐
12645 ing commands, it is also possible to get separate events on key
12646 up/down, and relatively detailed information about the key
12647 state. The special key name unmapped can be used to match any
12648 unmapped key.
12649 overlay-add <id> <x> <y> <file> <offset> <fmt> <w> <h> <stride>
12651 Add an OSD overlay sourced from raw data. This might be useful
12652 for scripts and applications controlling mpv, and which want to
12653 display things on top of the video window.
12654 Overlays are usually displayed in screen resolution, but with
12656 some VOs, the resolution is reduced to that of the video's. You
12657 can read the osd-width and osd-height properties. At least with
12658 --vo-xv and anamorphic video (such as DVD), osd-par should be
12659 read as well, and the overlay should be aspect-compensated.
12660 This has the following named arguments. The order of them is not
12662 guaranteed, so you should always call them with named arguments,
12663 see Named arguments.
12664 id is an integer between 0 and 63 identifying the overlay ele‐
12666 ment. The ID can be used to add multiple overlay parts, update a
12667 part by using this command with an already existing ID, or to
12668 remove a part with overlay-remove. Using a previously unused ID
12669 will add a new overlay, while reusing an ID will update it.
12670 x and y specify the position where the OSD should be displayed.
12672 file specifies the file the raw image data is read from. It can
12674 be either a numeric UNIX file descriptor prefixed with @ (e.g.
12675 @4), or a filename. The file will be mapped into memory with
12676 mmap(), copied, and unmapped before the command returns (changed
12677 in mpv 0.18.1).
12678 It is also possible to pass a raw memory address for use as bit‐
12680 map memory by passing a memory address as integer prefixed with
12681 an & character. Passing the wrong thing here will crash the
12682 player. This mode might be useful for use with libmpv. The off‐
12683 set parameter is simply added to the memory address (since mpv
12684 0.8.0, ignored before).
12685 offset is the byte offset of the first pixel in the source file.
12687 (The current implementation always mmap's the whole file from
12688 position 0 to the end of the image, so large offsets should be
12689 avoided. Before mpv 0.8.0, the offset was actually passed di‐
12690 rectly to mmap, but it was changed to make using it easier.)
12691 fmt is a string identifying the image format. Currently, only
12693 bgra is defined. This format has 4 bytes per pixels, with 8 bits
12694 per component. The least significant 8 bits are blue, and the
12695 most significant 8 bits are alpha (in little endian, the compo‐
12696 nents are B-G-R-A, with B as first byte). This uses premulti‐
12697 plied alpha: every color component is already multiplied with
12698 the alpha component. This means the numeric value of each compo‐
12699 nent is equal to or smaller than the alpha component. (Violating
12700 this rule will lead to different results with different VOs: nu‐
12701 meric overflows resulting from blending broken alpha values is
12702 considered something that shouldn't happen, and consequently im‐
12703 plementations don't ensure that you get predictable behavior in
12704 this case.)
12705 w, h, and stride specify the size of the overlay. w is the visi‐
12707 ble width of the overlay, while stride gives the width in bytes
12708 in memory. In the simple case, and with the bgra format,
12709 stride==4*w. In general, the total amount of memory accessed is
12710 stride * h. (Technically, the minimum size would be stride * (h
12711 - 1) + w * 4, but for simplicity, the player will access all
12712 stride * h bytes.)
12713 NOTE:
12715 Before mpv 0.18.1, you had to do manual "double buffering"
12716 when updating an overlay by replacing it with a different
12717 memory buffer. Since mpv 0.18.1, the memory is simply copied
12718 and doesn't reference any of the memory indicated by the com‐
12719 mand's arguments after the commend returns. If you want to
12720 use this command before mpv 0.18.1, reads the old docs to see
12721 how to handle this correctly.
12722 overlay-remove <id>
12724 Remove an overlay added with overlay-add and the same ID. Does
12725 nothing if no overlay with this ID exists.
12726 osd-overlay
12728 Add/update/remove an OSD overlay.
12729 (Although this sounds similar to overlay-add, osd-overlay is for
12731 text overlays, while overlay-add is for bitmaps. Maybe over‐
12732 lay-add will be merged into osd-overlay to remove this oddity.)
12733 You can use this to add text overlays in ASS format. ASS has ad‐
12735 vanced positioning and rendering tags, which can be used to ren‐
12736 der almost any kind of vector graphics.
12737 This command accepts the following parameters:
12739 id Arbitrary integer that identifies the overlay. Multiple
12741 overlays can be added by calling this command with dif‐
12742 ferent id parameters. Calling this command with the same
12743 id replaces the previously set overlay.
12744 There is a separate namespace for each libmpv client
12746 (i.e. IPC connection, script), so IDs can be made up and
12747 assigned by the API user without conflicting with other
12748 API users.
12749 If the libmpv client is destroyed, all overlays associ‐
12751 ated with it are also deleted. In particular, connecting
12752 via --input-ipc-server, adding an overlay, and discon‐
12753 necting will remove the overlay immediately again.
12754 format String that gives the type of the overlay. Accepts the
12756 following values (HTML rendering of this is broken, view
12757 the generated manpage instead, or the raw RST source):
12758 ass-events
12760 The data parameter is a string. The string is
12761 split on the newline character. Every line is
12762 turned into the Text part of a Dialogue ASS event.
12763 Timing is unused (but behavior of timing dependent
12764 ASS tags may change in future mpv versions).
12765 Note that it's better to put multiple lines into
12767 data, instead of adding multiple OSD overlays.
12768 This provides 2 ASS Styles. OSD contains the text
12770 style as defined by the current --osd-... options.
12771 Default is similar, and contains style that OSD
12772 would have if all options were set to the default.
12773 In addition, the res_x and res_y options specify
12775 the value of the ASS PlayResX and PlayResY header
12776 fields. If res_y is set to 0, PlayResY is initial‐
12777 ized to an arbitrary default value (but note that
12778 the default for this command is 720, not 0). If
12779 res_x is set to 0, PlayResX is set based on res_y
12780 such that a virtual ASS pixel has a square pixel
12781 aspect ratio.
12782 none Special value that causes the overlay to be re‐
12784 moved. Most parameters other than id and format
12785 are mostly ignored.
12786 data String defining the overlay contents according to the
12788 format parameter.
12789 res_x, res_y
12791 Used if format is set to ass-events (see description
12792 there). Optional, defaults to 0/720.
12793 z The Z order of the overlay. Optional, defaults to 0.
12795 Note that Z order between different overlays of different
12797 formats is static, and cannot be changed (currently, this
12798 means that bitmap overlays added by overlay-add are al‐
12799 ways on top of the ASS overlays added by osd-overlay). In
12800 addition, the builtin OSD components are always below any
12801 of the custom OSD. (This includes subtitles of any kind
12802 as well as text rendered by show-text.)
12803 It's possible that future mpv versions will randomly
12805 change how Z order between different OSD formats and
12806 builtin OSD is handled.
12807 hidden If set to true, do not display this (default: false).
12809 compute_bounds
12811 If set to true, attempt to determine bounds and write
12812 them to the command's result value as x0, x1, y0, y1 rec‐
12813 tangle (default: false). If the rectangle is empty, not
12814 known, or somehow degenerate, it is not set. x1/y1 is the
12815 coordinate of the bottom exclusive corner of the rectan‐
12816 gle.
12817 The result value may depend on the VO window size, and is
12819 based on the last known window size at the time of the
12820 call. This means the results may be different from what
12821 is actually rendered.
12822 For ass-events, the result rectangle is recomputed to
12824 PlayRes coordinates (res_x/res_y). If window size is not
12825 known, a fallback is chosen.
12826 You should be aware that this mechanism is very ineffi‐
12828 cient, as it renders the full result, and then uses the
12829 bounding box of the rendered bitmap list (even if hidden
12830 is set). It will flush various caches. Its results also
12831 depend on the used libass version.
12832 This feature is experimental, and may change in some way
12834 again.
12835 NOTE:
12837 Always use named arguments (mpv_command_node()). Lua scripts
12838 should use the mp.create_osd_overlay() helper instead of in‐
12839 voking this command directly.
12840 script-message [<arg1> [<arg2> [...]]]
12842 Send a message to all clients, and pass it the following list of
12843 arguments. What this message means, how many arguments it
12844 takes, and what the arguments mean is fully up to the receiver
12845 and the sender. Every client receives the message, so be careful
12846 about name clashes (or use script-message-to).
12847 This command has a variable number of arguments, and cannot be
12849 used with named arguments.
12850 script-message-to <target> [<arg1> [<arg2> [...]]]
12852 Same as script-message, but send it only to the client named
12853 <target>. Each client (scripts etc.) has a unique name. For ex‐
12854 ample, Lua scripts can get their name via mp.get_script_name().
12855 Note that client names only consist of alphanumeric characters
12856 and _.
12857 This command has a variable number of arguments, and cannot be
12859 used with named arguments.
12860 script-binding <name>
12862 Invoke a script-provided key binding. This can be used to remap
12863 key bindings provided by external Lua scripts.
12864 The argument is the name of the binding.
12866 It can optionally be prefixed with the name of the script, using
12868 / as separator, e.g. script-binding scriptname/bindingname. Note
12869 that script names only consist of alphanumeric characters and _.
12870 For completeness, here is how this command works internally. The
12872 details could change any time. On any matching key event,
12873 script-message-to or script-message is called (depending on
12874 whether the script name is included), with the following argu‐
12875 ments:
12876 1. The string key-binding.
12878 2. The name of the binding (as established above).
12880 3. The key state as string (see below).
12882 4. The key name (since mpv 0.15.0).
12884 5. The text the key would produce, or empty string if not appli‐
12886 cable.
12887 The 5th argument is only set if no modifiers are present (using
12889 the shift key with a letter is normally not emitted as having a
12890 modifier, and results in upper case text instead, but some back‐
12891 ends may mess up).
12892 The key state consists of 2 characters:
12894 1. One of d (key was pressed down), u (was released), r (key is
12896 still down, and was repeated; only if key repeat is enabled
12897 for this binding), p (key was pressed; happens if up/down
12898 can't be tracked).
12899 2. Whether the event originates from the mouse, either m (mouse
12901 button) or - (something else).
12902 Future versions can add more arguments and more key state char‐
12904 acters to support more input peculiarities.
12905 ab-loop
12907 Cycle through A-B loop states. The first command will set the A
12908 point (the ab-loop-a property); the second the B point, and the
12909 third will clear both points.
12910 drop-buffers
12912 Drop audio/video/demuxer buffers, and restart from fresh. Might
12913 help with unseekable streams that are going out of sync. This
12914 command might be changed or removed in the future.
12915 screenshot-raw [<flags>]
12917 Return a screenshot in memory. This can be used only through the
12918 client API. The MPV_FORMAT_NODE_MAP returned by this command has
12919 the w, h, stride fields set to obvious contents. The format
12920 field is set to bgr0 by default. This format is organized as
12921 B8G8R8X8 (where B is the LSB). The contents of the padding X are
12922 undefined. The data field is of type MPV_FORMAT_BYTE_ARRAY with
12923 the actual image data. The image is freed as soon as the result
12924 mpv_node is freed. As usual with client API semantics, you are
12925 not allowed to write to the image data.
12926 The stride is the number of bytes from a pixel at (x0, y0) to
12928 the pixel at (x0, y0 + 1). This can be larger than w * 4 if the
12929 image was cropped, or if there is padding. This number can be
12930 negative as well. You access a pixel with byte_index = y *
12931 stride + x * 4 (assuming the bgr0 format).
12932 The flags argument is like the first argument to screenshot and
12934 supports subtitles, video, window.
12935 vf-command <label> <command> <argument>
12937 Send a command to the filter with the given <label>. Use all to
12938 send it to all filters at once. The command and argument string
12939 is filter specific. Currently, this only works with the lavfi
12940 filter - see the libavfilter documentation for which commands a
12941 filter supports.
12942 Note that the <label> is a mpv filter label, not a libavfilter
12944 filter name.
12945 af-command <label> <command> <argument>
12947 Same as vf-command, but for audio filters.
12948 apply-profile <name> [<mode>]
12950 Apply the contents of a named profile. This is like using pro‐
12951 file=name in a config file, except you can map it to a key bind‐
12952 ing to change it at runtime.
12953 The mode argument:
12955 default
12957 Apply the profile. Default if the argument is omitted.
12958 restore
12960 Restore options set by a previous apply-profile command
12961 for this profile. Only works if the profile has pro‐
12962 file-restore set to a relevant mode. Prints a warning if
12963 nothing could be done. See Runtime profiles for details.
12964 load-script <filename>
12966 Load a script, similar to the --script option. Whether this
12967 waits for the script to finish initialization or not changed
12968 multiple times, and the future behavior is left undefined.
12969 On success, returns a mpv_node with a client_id field set to the
12971 return value of the mpv_client_id() API call of the newly cre‐
12972 ated script handle.
12973 change-list <name> <operation> <value>
12975 This command changes list options as described in List Options.
12976 The <name> parameter is the normal option name, while <opera‐
12977 tion> is the suffix or action used on the option.
12978 Some operations take no value, but the command still requires
12980 the value parameter. In these cases, the value must be an empty
12981 string.
12982 Example
12984 change-list glsl-shaders append file.glsl
12986 Add a filename to the glsl-shaders list. The command
12988 line equivalent is --glsl-shaders-append=file.glsl or
12989 alternatively --glsl-shader=file.glsl.
12990 dump-cache <start> <end> <filename>
12992 Dump the current cache to the given filename. The <filename>
12993 file is overwritten if it already exists. <start> and <end> give
12994 the time range of what to dump. If no data is cached at the
12995 given time range, nothing may be dumped (creating a file with no
12996 packets).
12997 Dumping a larger part of the cache will freeze the player. No
12999 effort was made to fix this, as this feature was meant mostly
13000 for creating small excerpts.
13001 See --stream-record for various caveats that mostly apply to
13003 this command too, as both use the same underlying code for writ‐
13004 ing the output file.
13005 If <filename> is an empty string, an ongoing dump-cache is
13007 stopped.
13008 If <end> is no, then continuous dumping is enabled. Then, after
13010 dumping the existing parts of the cache, anything read from net‐
13011 work is appended to the cache as well. This behaves similar to
13012 --stream-record (although it does not conflict with that option,
13013 and they can be both active at the same time).
13014 If the <end> time is after the cache, the command will _not_
13016 wait and write newly received data to it.
13017 The end of the resulting file may be slightly damaged or incom‐
13019 plete at the end. (Not enough effort was made to ensure that the
13020 end lines up properly.)
13021 Note that this command will finish only once dumping ends. That
13023 means it works similar to the screenshot command, just that it
13024 can block much longer. If continuous dumping is used, the com‐
13025 mand will not finish until playback is stopped, an error hap‐
13026 pens, another dump-cache command is run, or an API like
13027 mp.abort_async_command was called to explicitly stop the com‐
13028 mand. See Synchronous vs. Asynchronous.
13029 NOTE:
13031 This was mostly created for network streams. For local files,
13032 there may be much better methods to create excerpts and such.
13033 There are tons of much more user-friendly Lua scripts, that
13034 will reencode parts of a file by spawning a separate instance
13035 of ffmpeg. With network streams, this is not that easily pos‐
13036 sible, as the stream would have to be downloaded again. Even
13037 if --stream-record is used to record the stream to the local
13038 filesystem, there may be problems, because the recorded file
13039 is still written to.
13040 This command is experimental, and all details about it may
13042 change in the future.
13043 ab-loop-dump-cache <filename>
13045 Essentially calls dump-cache with the current AB-loop points as
13046 arguments. Like dump-cache, this will overwrite the file at
13047 <filename>. Likewise, if the B point is set to no, it will enter
13048 continuous dumping after the existing cache was dumped.
13049 The author reserves the right to remove this command if enough
13051 motivation is found to move this functionality to a trivial Lua
13052 script.
13053 ab-loop-align-cache
13055 Re-adjust the A/B loop points to the start and end within the
13056 cache the ab-loop-dump-cache command will (probably) dump. Basi‐
13057 cally, it aligns the times on keyframes. The guess might be off
13058 especially at the end (due to granularity issues due to remux‐
13059 ing). If the cache shrinks in the meantime, the points set by
13060 the command will not be the effective parameters either.
13061 This command has an even more uncertain future than
13063 ab-loop-dump-cache and might disappear without replacement if
13064 the author decides it's useless.
13065 Undocumented commands: ao-reload (experimental/internal).
13067 List of events
13069 This is a partial list of events. This section describes what
13070 mpv_event_to_node() returns, and which is what scripting APIs and the
13071 JSON IPC sees. Note that the C API has separate C-level declarations
13072 with mpv_event, which may be slightly different.
13073 Note that events are asynchronous: the player core continues running
13075 while events are delivered to scripts and other clients. In some cases,
13076 you can hooks to enforce synchronous execution.
13077 All events can have the following fields:
13079 event Name as the event (as returned by mpv_event_name()).
13081 id The reply_userdata field (opaque user value). If reply_userdata
13083 is 0, the field is not added.
13084 error Set to an error string (as returned by mpv_error_string()). This
13086 field is missing if no error happened, or the event type does
13087 not report error. Most events leave this unset.
13088 This list uses the event name field value, and the C API symbol in
13090 brackets:
13091 start-file (MPV_EVENT_START_FILE)
13093 Happens right before a new file is loaded. When you receive
13094 this, the player is loading the file (or possibly already done
13095 with it).
13096 This has the following fields:
13098 playlist_entry_id
13100 Playlist entry ID of the file being loaded now.
13101 end-file (MPV_EVENT_END_FILE)
13103 Happens after a file was unloaded. Typically, the player will
13104 load the next file right away, or quit if this was the last
13105 file.
13106 The event has the following fields:
13108 reason Has one of these values:
13110 eof The file has ended. This can (but doesn't have to)
13112 include incomplete files or broken network connec‐
13113 tions under circumstances.
13114 stop Playback was ended by a command.
13116 quit Playback was ended by sending the quit command.
13118 error An error happened. In this case, an error field is
13120 present with the error string.
13121 redirect
13123 Happens with playlists and similar. Details see
13124 MPV_END_FILE_REASON_REDIRECT in the C API.
13125 unknown
13127 Unknown. Normally doesn't happen, unless the Lua
13128 API is out of sync with the C API. (Likewise, it
13129 could happen that your script gets reason strings
13130 that did not exist yet at the time your script was
13131 written.)
13132 playlist_entry_id
13134 Playlist entry ID of the file that was being played or
13135 attempted to be played. This has the same value as the
13136 playlist_entry_id field in the corresponding start-file
13137 event.
13138 file_error
13140 Set to mpv error string describing the approximate reason
13141 why playback failed. Unset if no error known. (In Lua
13142 scripting, this value was set on the error field di‐
13143 rectly. This is deprecated since mpv 0.33.0. In the fu‐
13144 ture, this error field will be unset for this specific
13145 event.)
13146 playlist_insert_id
13148 If loading ended, because the playlist entry to be played
13149 was for example a playlist, and the current playlist en‐
13150 try is replaced with a number of other entries. This may
13151 happen at least with MPV_END_FILE_REASON_REDIRECT (other
13152 event types may use this for similar but different pur‐
13153 poses in the future). In this case, playlist_insert_id
13154 will be set to the playlist entry ID of the first in‐
13155 serted entry, and playlist_insert_num_entries to the to‐
13156 tal number of inserted playlist entries. Note this in
13157 this specific case, the ID of the last inserted entry is
13158 playlist_insert_id+num-1. Beware that depending on cir‐
13159 cumstances, you may observe the new playlist entries be‐
13160 fore seeing the event (e.g. reading the "playlist" prop‐
13161 erty or getting a property change notification before re‐
13162 ceiving the event). If this is 0 in the C API, this
13163 field isn't added.
13164 playlist_insert_num_entries
13166 See playlist_insert_id. Only present if playlist_in‐
13167 sert_id is present.
13168 file-loaded (MPV_EVENT_FILE_LOADED)
13170 Happens after a file was loaded and begins playback.
13171 seek (MPV_EVENT_SEEK)
13173 Happens on seeking. (This might include cases when the player
13174 seeks internally, even without user interaction. This includes
13175 e.g. segment changes when playing ordered chapters Matroska
13176 files.)
13177 playback-restart (MPV_EVENT_PLAYBACK_RESTART)
13179 Start of playback after seek or after file was loaded.
13180 shutdown (MPV_EVENT_SHUTDOWN)
13182 Sent when the player quits, and the script should terminate.
13183 Normally handled automatically. See Details on the script ini‐
13184 tialization and lifecycle.
13185 log-message (MPV_EVENT_LOG_MESSAGE)
13187 Receives messages enabled with mpv_request_log_messages() (Lua:
13188 mp.enable_messages).
13189 This contains, in addition to the default event fields, the fol‐
13191 lowing fields:
13192 prefix The module prefix, identifies the sender of the message.
13194 This is what the terminal player puts in front of the
13195 message text when using the --v option, and is also what
13196 is used for --msg-level.
13197 level The log level as string. See msg.log for possible log
13199 level names. Note that later versions of mpv might add
13200 new levels or remove (undocumented) existing ones.
13201 text The log message. The text will end with a newline charac‐
13203 ter. Sometimes it can contain multiple lines.
13204 Keep in mind that these messages are meant to be hints for hu‐
13206 mans. You should not parse them, and prefix/level/text of mes‐
13207 sages might change any time.
13208 hook The event has the following fields:
13210 hook_id
13212 ID to pass to mpv_hook_continue(). The Lua scripting
13213 wrapper provides a better API around this with
13214 mp.add_hook().
13215 get-property-reply (MPV_EVENT_GET_PROPERTY_REPLY)
13217 See C API.
13218 set-property-reply (MPV_EVENT_SET_PROPERTY_REPLY)
13220 See C API.
13221 command-reply (MPV_EVENT_COMMAND_REPLY)
13223 This is one of the commands for which the `error field is mean‐
13224 ingful.
13225 JSON IPC and Lua and possibly other backends treat this spe‐
13227 cially and may not pass the actual event to the user. See C API.
13228 The event has the following fields:
13230 result The result (on success) of any mpv_node type, if any.
13232 client-message (MPV_EVENT_CLIENT_MESSAGE)
13234 Lua and possibly other backends treat this specially and may not
13235 pass the actual event to the user.
13236 The event has the following fields:
13238 args Array of strings with the message data.
13240 video-reconfig (MPV_EVENT_VIDEO_RECONFIG)
13242 Happens on video output or filter reconfig.
13243 audio-reconfig (MPV_EVENT_AUDIO_RECONFIG)
13245 Happens on audio output or filter reconfig.
13246 property-change (MPV_EVENT_PROPERTY_CHANGE)
13248 Happens when a property that is being observed changes value.
13249 The event has the following fields:
13251 name The name of the property.
13253 data The new value of the property.
13255 The following events also happen, but are deprecated: idle, tick Use
13257 mpv_observe_property() (Lua: mp.observe_property()) instead.
13258 Hooks
13260 Hooks are synchronous events between player core and a script or simi‐
13261 lar. This applies to client API (including the Lua scripting inter‐
13262 face). Normally, events are supposed to be asynchronous, and the hook
13263 API provides an awkward and obscure way to handle events that require
13264 stricter coordination. There are no API stability guarantees made. Not
13265 following the protocol exactly can make the player freeze randomly. Ba‐
13266 sically, nobody should use this API.
13267 The C API is described in the header files. The Lua API is described in
13269 the Lua section.
13270 Before a hook is actually invoked on an API clients, it will attempt to
13272 return new values for all observed properties that were changed before
13273 the hook. This may make it easier for an application to set defined
13274 "barriers" between property change notifications by registering hooks.
13275 (That means these hooks will have an effect, even if you do nothing and
13276 make them continue immediately.)
13277 The following hooks are currently defined:
13279 on_load
13281 Called when a file is to be opened, before anything is actually
13282 done. For example, you could read and write the
13283 stream-open-filename property to redirect an URL to something
13284 else (consider support for streaming sites which rarely give the
13285 user a direct media URL), or you could set per-file options with
13286 by setting the property file-local-options/<option name>. The
13287 player will wait until all hooks are run.
13288 Ordered after start-file and before playback-restart.
13290 on_load_fail
13292 Called after after a file has been opened, but failed to. This
13293 can be used to provide a fallback in case native demuxers failed
13294 to recognize the file, instead of always running before the na‐
13295 tive demuxers like on_load. Demux will only be retried if
13296 stream-open-filename was changed. If it fails again, this hook
13297 is _not_ called again, and loading definitely fails.
13298 Ordered after on_load, and before playback-restart and end-file.
13300 on_preloaded
13302 Called after a file has been opened, and before tracks are se‐
13303 lected and decoders are created. This has some usefulness if an
13304 API users wants to select tracks manually, based on the set of
13305 available tracks. It's also useful to initialize --lavfi-complex
13306 in a specific way by API, without having to "probe" the avail‐
13307 able streams at first.
13308 Note that this does not yet apply default track selection. Which
13310 operations exactly can be done and not be done, and what infor‐
13311 mation is available and what is not yet available yet, is all
13312 subject to change.
13313 Ordered after on_load_fail etc. and before playback-restart.
13315 on_unload
13317 Run before closing a file, and before actually uninitializing
13318 everything. It's not possible to resume playback in this state.
13319 Ordered before end-file. Will also happen in the error case
13321 (then after on_load_fail).
13322 on_before_start_file
13324 Run before a start-file event is sent. (If any client changes
13325 the current playlist entry, or sends a quit command to the
13326 player, the corresponding event will not actually happen after
13327 the hook returns.) Useful to drain property changes before a
13328 new file is loaded.
13329 on_after_end_file
13331 Run after an end-file event. Useful to drain property changes
13332 after a file has finished.
13333 Input Command Prefixes
13335 These prefixes are placed between key name and the actual command. Mul‐
13336 tiple prefixes can be specified. They are separated by whitespace.
13337 osd-auto
13339 Use the default behavior for this command. This is the default
13340 for input.conf commands. Some libmpv/scripting/IPC APIs do not
13341 use this as default, but use no-osd instead.
13342 no-osd Do not use any OSD for this command.
13344 osd-bar
13346 If possible, show a bar with this command. Seek commands will
13347 show the progress bar, property changing commands may show the
13348 newly set value.
13349 osd-msg
13351 If possible, show an OSD message with this command. Seek command
13352 show the current playback time, property changing commands show
13353 the newly set value as text.
13354 osd-msg-bar
13356 Combine osd-bar and osd-msg.
13357 raw Do not expand properties in string arguments. (Like "${prop‐
13359 erty-name}".) This is the default for some libmpv/scripting/IPC
13360 APIs.
13361 expand-properties
13363 All string arguments are expanded as described in Property Ex‐
13364 pansion. This is the default for input.conf commands.
13365 repeatable
13367 For some commands, keeping a key pressed doesn't run the command
13368 repeatedly. This prefix forces enabling key repeat in any case.
13369 For a list of commands: the first command determines the re‐
13370 peatability of the whole list (up to and including version 0.33
13371 - a list was always repeatable).
13372 async Allow asynchronous execution (if possible). Note that only a few
13374 commands will support this (usually this is explicitly docu‐
13375 mented). Some commands are asynchronous by default (or rather,
13376 their effects might manifest after completion of the command).
13377 The semantics of this flag might change in the future. Set it
13378 only if you don't rely on the effects of this command being
13379 fully realized when it returns. See Synchronous vs. Asynchro‐
13380 nous.
13381 sync Allow synchronous execution (if possible). Normally, all com‐
13383 mands are synchronous by default, but some are asynchronous by
13384 default for compatibility with older behavior.
13385 All of the osd prefixes are still overridden by the global --osd-level
13387 settings.
13388 Synchronous vs. Asynchronous
13390 The async and sync prefix matter only for how the issuer of the command
13391 waits on the completion of the command. Normally it does not affect how
13392 the command behaves by itself. There are the following cases:
13393 • Normal input.conf commands are always run asynchronously. Slow run‐
13395 ning commands are queued up or run in parallel.
13396 • "Multi" input.conf commands (1 key binding, concatenated with ;) will
13398 be executed in order, except for commands that are async (either pre‐
13399 fixed with async, or async by default for some commands). The async
13400 commands are run in a detached manner, possibly in parallel to the
13401 remaining sync commands in the list.
13402 • Normal Lua and libmpv commands (e.g. mpv_command()) are run in a
13404 blocking manner, unless the async prefix is used, or the command is
13405 async by default. This means in the sync case the caller will block,
13406 even if the core continues playback. Async mode runs the command in a
13407 detached manner.
13408 • Async libmpv command API (e.g. mpv_command_async()) never blocks the
13410 caller, and always notify their completion with a message. The sync
13411 and async prefixes make no difference.
13412 • Lua also provides APIs for running async commands, which behave simi‐
13414 lar to the C counterparts.
13415 • In all cases, async mode can still run commands in a synchronous man‐
13417 ner, even in detached mode. This can for example happen in cases when
13418 a command does not have an asynchronous implementation. The async
13419 libmpv API still never blocks the caller in these cases.
13420 Before mpv 0.29.0, the async prefix was only used by screenshot com‐
13422 mands, and made them run the file saving code in a detached manner.
13423 This is the default now, and async changes behavior only in the ways
13424 mentioned above.
13425 Currently the following commands have different waiting characteristics
13427 with sync vs. async: sub-add, audio-add, sub-reload, audio-reload, res‐
13428 can-external-files, screenshot, screenshot-to-file, dump-cache,
13429 ab-loop-dump-cache.
13430 Asynchronous command details
13432 On the API level, every asynchronous command is bound to the context
13433 which started it. For example, an asynchronous command started by
13434 mpv_command_async is bound to the mpv_handle passed to the function.
13435 Only this mpv_handle receives the completion notification
13436 (MPV_EVENT_COMMAND_REPLY), and only this handle can abort a still run‐
13437 ning command directly. If the mpv_handle is destroyed, any still run‐
13438 ning async. commands started by it are terminated.
13439 The scripting APIs and JSON IPC give each script/connection its own im‐
13441 plicit mpv_handle.
13442 If the player is closed, the core may abort all pending async. commands
13444 on its own (like a forced mpv_abort_async_command() call for each pend‐
13445 ing command on behalf of the API user). This happens at the same time
13446 MPV_EVENT_SHUTDOWN is sent, and there is no way to prevent this.
13447 Input Sections
13449 Input sections group a set of bindings, and enable or disable them at
13450 once. In input.conf, each key binding is assigned to an input section,
13451 rather than actually having explicit text sections.
13452 See also: enable-section and disable-section commands.
13454 Predefined bindings:
13456 default
13458 Bindings without input section are implicitly assigned to this
13459 section. It is enabled by default during normal playback.
13460 encode Section which is active in encoding mode. It is enabled exclu‐
13462 sively, so that bindings in the default sections are ignored.
13463 Properties
13465 Properties are used to set mpv options during runtime, or to query ar‐
13466 bitrary information. They can be manipulated with the set/add/cycle
13467 commands, and retrieved with show-text, or anything else that uses
13468 property expansion. (See Property Expansion.)
13469 The property name is annotated with RW to indicate whether the property
13471 is generally writable.
13472 If an option is referenced, the property will normally take/return ex‐
13474 actly the same values as the option. In these cases, properties are
13475 merely a way to change an option at runtime.
13476 Property list
13478 NOTE:
13479 Most options can be set at runtime via properties as well. Just re‐
13480 move the leading -- from the option name. These are not documented
13481 below, see OPTIONS instead. Only properties which do not exist as
13482 option with the same name, or which have very different behavior
13483 from the options are documented below.
13484 Properties marked as (RW) are writeable, while those that aren't are
13486 read-only.
13487 audio-speed-correction, video-speed-correction
13489 Factor multiplied with speed at which the player attempts to
13490 play the file. Usually it's exactly 1. (Display sync mode will
13491 make this useful.)
13492 OSD formatting will display it in the form of +1.23456%, with
13494 the number being (raw - 1) * 100 for the given raw property
13495 value.
13496 display-sync-active
13498 Whether --video-sync=display is actually active.
13499 filename
13501 Currently played file, with path stripped. If this is an URL,
13502 try to undo percent encoding as well. (The result is not neces‐
13503 sarily correct, but looks better for display purposes. Use the
13504 path property to get an unmodified filename.)
13505 This has a sub-property:
13507 filename/no-ext
13509 Like the filename property, but if the text contains a .,
13510 strip all text after the last .. Usually this removes the
13511 file extension.
13512 file-size
13514 Length in bytes of the source file/stream. (This is the same as
13515 ${stream-end}. For segmented/multi-part files, this will return
13516 the size of the main or manifest file, whatever it is.)
13517 estimated-frame-count
13519 Total number of frames in current file.
13520 NOTE:
13522 This is only an estimate. (It's computed from two unreliable
13523 quantities: fps and stream length.)
13524 estimated-frame-number
13526 Number of current frame in current stream.
13527 NOTE:
13529 This is only an estimate. (It's computed from two unreliable
13530 quantities: fps and possibly rounded timestamps.)
13531 pid Process-id of mpv.
13533 path Full path of the currently played file. Usually this is exactly
13535 the same string you pass on the mpv command line or the loadfile
13536 command, even if it's a relative path. If you expect an absolute
13537 path, you will have to determine it yourself, for example by us‐
13538 ing the working-directory property.
13539 stream-open-filename
13541 The full path to the currently played media. This is different
13542 from path only in special cases. In particular, if --ytdl=yes is
13543 used, and the URL is detected by youtube-dl, then the script
13544 will set this property to the actual media URL. This property
13545 should be set only during the on_load or on_load_fail hooks,
13546 otherwise it will have no effect (or may do something implemen‐
13547 tation defined in the future). The property is reset if playback
13548 of the current media ends.
13549 media-title
13551 If the currently played file has a title tag, use that.
13552 Otherwise, return the filename property.
13554 file-format
13556 Symbolic name of the file format. In some cases, this is a
13557 comma-separated list of format names, e.g. mp4 is
13558 mov,mp4,m4a,3gp,3g2,mj2 (the list may grow in the future for any
13559 format).
13560 current-demuxer
13562 Name of the current demuxer. (This is useless.)
13563 (Renamed from demuxer.)
13565 stream-path
13567 Filename (full path) of the stream layer filename. (This is
13568 probably useless and is almost never different from path.)
13569 stream-pos
13571 Raw byte position in source stream. Technically, this returns
13572 the position of the most recent packet passed to a decoder.
13573 stream-end
13575 Raw end position in bytes in source stream.
13576 duration
13578 Duration of the current file in seconds. If the duration is un‐
13579 known, the property is unavailable. Note that the file duration
13580 is not always exactly known, so this is an estimate.
13581 This replaces the length property, which was deprecated after
13583 the mpv 0.9 release. (The semantics are the same.)
13584 avsync Last A/V synchronization difference. Unavailable if audio or
13586 video is disabled.
13587 total-avsync-change
13589 Total A-V sync correction done. Unavailable if audio or video is
13590 disabled.
13591 decoder-frame-drop-count
13593 Video frames dropped by decoder, because video is too far behind
13594 audio (when using --framedrop=decoder). Sometimes, this may be
13595 incremented in other situations, e.g. when video packets are
13596 damaged, or the decoder doesn't follow the usual rules. Unavail‐
13597 able if video is disabled.
13598 drop-frame-count is a deprecated alias.
13600 frame-drop-count
13602 Frames dropped by VO (when using --framedrop=vo).
13603 vo-drop-frame-count is a deprecated alias.
13605 mistimed-frame-count
13607 Number of video frames that were not timed correctly in dis‐
13608 play-sync mode for the sake of keeping A/V sync. This does not
13609 include external circumstances, such as video rendering being
13610 too slow or the graphics driver somehow skipping a vsync. It
13611 does not include rounding errors either (which can happen espe‐
13612 cially with bad source timestamps). For example, using the dis‐
13613 play-desync mode should never change this value from 0.
13614 vsync-ratio
13616 For how many vsyncs a frame is displayed on average. This is
13617 available if display-sync is active only. For 30 FPS video on a
13618 60 Hz screen, this will be 2. This is the moving average of what
13619 actually has been scheduled, so 24 FPS on 60 Hz will never re‐
13620 main exactly on 2.5, but jitter depending on the last frame dis‐
13621 played.
13622 vo-delayed-frame-count
13624 Estimated number of frames delayed due to external circumstances
13625 in display-sync mode. Note that in general, mpv has to guess
13626 that this is happening, and the guess can be inaccurate.
13627 percent-pos (RW)
13629 Position in current file (0-100). The advantage over using this
13630 instead of calculating it out of other properties is that it
13631 properly falls back to estimating the playback position from the
13632 byte position, if the file duration is not known.
13633 time-pos (RW)
13635 Position in current file in seconds.
13636 time-start
13638 Deprecated. Always returns 0. Before mpv 0.14, this used to re‐
13639 turn the start time of the file (could affect e.g. transport
13640 streams). See --rebase-start-time option.
13641 time-remaining
13643 Remaining length of the file in seconds. Note that the file du‐
13644 ration is not always exactly known, so this is an estimate.
13645 audio-pts
13647 Current audio playback position in current file in seconds. Un‐
13648 like time-pos, this updates more often than once per frame. For
13649 audio-only files, it is mostly equivalent to time-pos, while for
13650 video-only files this property is not available.
13651 playtime-remaining
13653 time-remaining scaled by the current speed.
13654 playback-time (RW)
13656 Position in current file in seconds. Unlike time-pos, the time
13657 is clamped to the range of the file. (Inaccurate file durations
13658 etc. could make it go out of range. Useful on attempts to seek
13659 outside of the file, as the seek target time is considered the
13660 current position during seeking.)
13661 chapter (RW)
13663 Current chapter number. The number of the first chapter is 0.
13664 edition (RW)
13666 Current MKV edition number. Setting this property to a different
13667 value will restart playback. The number of the first edition is
13668 0.
13669 Before mpv 0.31.0, this showed the actual edition selected at
13671 runtime, if you didn't set the option or property manually. With
13672 mpv 0.31.0 and later, this strictly returns the user-set option
13673 or property value, and the current-edition property was added to
13674 return the runtime selected edition (this matters with --edi‐
13675 tion=auto, the default).
13676 current-edition
13678 Currently selected edition. This property is unavailable if no
13679 file is loaded, or the file has no editions. (Matroska files
13680 make a difference between having no editions and a single edi‐
13681 tion, which will be reflected by the property, although in prac‐
13682 tice it does not matter.)
13683 chapters
13685 Number of chapters.
13686 editions
13688 Number of MKV editions.
13689 edition-list
13691 List of editions, current entry marked. Currently, the raw prop‐
13692 erty value is useless.
13693 This has a number of sub-properties. Replace N with the 0-based
13695 edition index.
13696 edition-list/count
13698 Number of editions. If there are no editions, this can be
13699 0 or 1 (1 if there's a useless dummy edition).
13700 edition-list/N/id (RW)
13702 Edition ID as integer. Use this to set the edition prop‐
13703 erty. Currently, this is the same as the edition index.
13704 edition-list/N/default
13706 Whether this is the default edition.
13707 edition-list/N/title
13709 Edition title as stored in the file. Not always avail‐
13710 able.
13711 When querying the property with the client API using MPV_FOR‐
13713 MAT_NODE, or with Lua mp.get_property_native, this will return a
13714 mpv_node with the following contents:
13715 MPV_FORMAT_NODE_ARRAY
13717 MPV_FORMAT_NODE_MAP (for each edition)
13718 "id" MPV_FORMAT_INT64
13719 "title" MPV_FORMAT_STRING
13720 "default" MPV_FORMAT_FLAG
13721 metadata
13723 Metadata key/value pairs.
13724 If the property is accessed with Lua's mp.get_property_native,
13726 this returns a table with metadata keys mapping to metadata val‐
13727 ues. If it is accessed with the client API, this returns a
13728 MPV_FORMAT_NODE_MAP, with tag keys mapping to tag values.
13729 For OSD, it returns a formatted list. Trying to retrieve this
13731 property as a raw string doesn't work.
13732 This has a number of sub-properties:
13734 metadata/by-key/<key>
13736 Value of metadata entry <key>.
13737 metadata/list/count
13739 Number of metadata entries.
13740 metadata/list/N/key
13742 Key name of the Nth metadata entry. (The first entry is
13743 0).
13744 metadata/list/N/value
13746 Value of the Nth metadata entry.
13747 metadata/<key>
13749 Old version of metadata/by-key/<key>. Use is discouraged,
13750 because the metadata key string could conflict with other
13751 sub-properties.
13752 The layout of this property might be subject to change. Sugges‐
13754 tions are welcome how exactly this property should work.
13755 When querying the property with the client API using MPV_FOR‐
13757 MAT_NODE, or with Lua mp.get_property_native, this will return a
13758 mpv_node with the following contents:
13759 MPV_FORMAT_NODE_MAP
13761 (key and string value for each metadata entry)
13762 filtered-metadata
13764 Like metadata, but includes only fields listed in the --dis‐
13765 play-tags option. This is the same set of tags that is printed
13766 to the terminal.
13767 chapter-metadata
13769 Metadata of current chapter. Works similar to metadata property.
13770 It also allows the same access methods (using sub-properties).
13771 Per-chapter metadata is very rare. Usually, only the chapter
13773 name (title) is set.
13774 For accessing other information, like chapter start, see the
13776 chapter-list property.
13777 vf-metadata/<filter-label>
13779 Metadata added by video filters. Accessed by the filter label,
13780 which, if not explicitly specified using the @filter-label: syn‐
13781 tax, will be <filter-name>NN.
13782 Works similar to metadata property. It allows the same access
13784 methods (using sub-properties).
13785 An example of this kind of metadata are the cropping parameters
13787 added by --vf=lavfi=cropdetect.
13788 af-metadata/<filter-label>
13790 Equivalent to vf-metadata/<filter-label>, but for audio filters.
13791 idle-active
13793 Returns yes/true if no file is loaded, but the player is staying
13794 around because of the --idle option.
13795 (Renamed from idle.)
13797 core-idle
13799 Whether the playback core is paused. This can differ from pause
13800 in special situations, such as when the player pauses itself due
13801 to low network cache.
13802 This also returns yes/true if playback is restarting or if noth‐
13804 ing is playing at all. In other words, it's only no/false if
13805 there's actually video playing. (Behavior since mpv 0.7.0.)
13806 cache-speed
13808 Current I/O read speed between the cache and the lower layer
13809 (like network). This gives the number bytes per seconds over a
13810 1 second window (using the type MPV_FORMAT_INT64 for the client
13811 API).
13812 This is the same as demuxer-cache-state/raw-input-rate.
13814 demuxer-cache-duration
13816 Approximate duration of video buffered in the demuxer, in sec‐
13817 onds. The guess is very unreliable, and often the property will
13818 not be available at all, even if data is buffered.
13819 demuxer-cache-time
13821 Approximate time of video buffered in the demuxer, in seconds.
13822 Same as demuxer-cache-duration but returns the last timestamp of
13823 buffered data in demuxer.
13824 demuxer-cache-idle
13826 Whether the demuxer is idle, which means that the demuxer cache
13827 is filled to the requested amount, and is currently not reading
13828 more data.
13829 demuxer-cache-state
13831 Each entry in seekable-ranges represents a region in the demuxer
13832 cache that can be seeked to, with a start and end fields con‐
13833 taining the respective timestamps. If there are multiple demux‐
13834 ers active, this only returns information about the "main" de‐
13835 muxer, but might be changed in future to return unified informa‐
13836 tion about all demuxers. The ranges are in arbitrary order. Of‐
13837 ten, ranges will overlap for a bit, before being joined. In
13838 broken corner cases, ranges may overlap all over the place.
13839 The end of a seek range is usually smaller than the value re‐
13841 turned by the demuxer-cache-time property, because that property
13842 returns the guessed buffering amount, while the seek ranges rep‐
13843 resent the buffered data that can actually be used for cached
13844 seeking.
13845 bof-cached indicates whether the seek range with the lowest
13847 timestamp points to the beginning of the stream (BOF). This im‐
13848 plies you cannot seek before this position at all. eof-cached
13849 indicates whether the seek range with the highest timestamp
13850 points to the end of the stream (EOF). If both bof-cached and
13851 eof-cached are true, and there's only 1 cache range, the entire
13852 stream is cached.
13853 fw-bytes is the number of bytes of packets buffered in the range
13855 starting from the current decoding position. This is a rough es‐
13856 timate (may not account correctly for various overhead), and
13857 stops at the demuxer position (it ignores seek ranges after it).
13858 file-cache-bytes is the number of bytes stored in the file
13860 cache. This includes all overhead, and possibly unused data
13861 (like pruned data). This member is missing if the file cache
13862 wasn't enabled with --cache-on-disk=yes.
13863 cache-end is demuxer-cache-time. Missing if unavailable.
13865 reader-pts is the approximate timestamp of the start of the
13867 buffered range. Missing if unavailable.
13868 cache-duration is demuxer-cache-duration. Missing if unavail‐
13870 able.
13871 raw-input-rate is the estimated input rate of the network layer
13873 (or any other byte-oriented input layer) in bytes per second.
13874 May be inaccurate or missing.
13875 When querying the property with the client API using MPV_FOR‐
13877 MAT_NODE, or with Lua mp.get_property_native, this will return a
13878 mpv_node with the following contents:
13879 MPV_FORMAT_NODE_MAP
13881 "seekable-ranges" MPV_FORMAT_NODE_ARRAY
13882 MPV_FORMAT_NODE_MAP
13883 "start" MPV_FORMAT_DOUBLE
13884 "end" MPV_FORMAT_DOUBLE
13885 "bof-cached" MPV_FORMAT_FLAG
13886 "eof-cached" MPV_FORMAT_FLAG
13887 "fw-bytes" MPV_FORMAT_INT64
13888 "file-cache-bytes" MPV_FORMAT_INT64
13889 "cache-end" MPV_FORMAT_DOUBLE
13890 "reader-pts" MPV_FORMAT_DOUBLE
13891 "cache-duration" MPV_FORMAT_DOUBLE
13892 "raw-input-rate" MPV_FORMAT_INT64
13893 Other fields (might be changed or removed in the future):
13895 eof Whether the reader thread has hit the end of the file.
13897 underrun
13899 Whether the reader thread could not satisfy a decoder's
13900 request for a new packet.
13901 idle Whether the thread is currently not reading.
13903 total-bytes
13905 Sum of packet bytes (plus some overhead estimation) of
13906 the entire packet queue, including cached seekable
13907 ranges.
13908 demuxer-via-network
13910 Whether the stream demuxed via the main demuxer is most likely
13911 played via network. What constitutes "network" is not always
13912 clear, might be used for other types of untrusted streams, could
13913 be wrong in certain cases, and its definition might be changing.
13914 Also, external files (like separate audio files or streams) do
13915 not influence the value of this property (currently).
13916 demuxer-start-time
13918 The start time reported by the demuxer in fractional seconds.
13919 paused-for-cache
13921 Whether playback is paused because of waiting for the cache.
13922 cache-buffering-state
13924 The percentage (0-100) of the cache fill status until the player
13925 will unpause (related to paused-for-cache).
13926 eof-reached
13928 Whether the end of playback was reached. Note that this is usu‐
13929 ally interesting only if --keep-open is enabled, since otherwise
13930 the player will immediately play the next file (or exit or enter
13931 idle mode), and in these cases the eof-reached property will
13932 logically be cleared immediately after it's set.
13933 seeking
13935 Whether the player is currently seeking, or otherwise trying to
13936 restart playback. (It's possible that it returns yes/true while
13937 a file is loaded. This is because the same underlying code is
13938 used for seeking and resyncing.)
13939 mixer-active
13941 Whether the audio mixer is active.
13942 This option is relatively useless. Before mpv 0.18.1, it could
13944 be used to infer behavior of the volume property.
13945 ao-volume (RW)
13947 System volume. This property is available only if mpv audio out‐
13948 put is currently active, and only if the underlying implementa‐
13949 tion supports volume control. What this option does depends on
13950 the API. For example, on ALSA this usually changes system-wide
13951 audio, while with PulseAudio this controls per-application vol‐
13952 ume.
13953 ao-mute (RW)
13955 Similar to ao-volume, but controls the mute state. May be unim‐
13956 plemented even if ao-volume works.
13957 audio-codec
13959 Audio codec selected for decoding.
13960 audio-codec-name
13962 Audio codec.
13963 audio-params
13965 Audio format as output by the audio decoder. This has a number
13966 of sub-properties:
13967 audio-params/format
13969 The sample format as string. This uses the same names as
13970 used in other places of mpv.
13971 audio-params/samplerate
13973 Samplerate.
13974 audio-params/channels
13976 The channel layout as a string. This is similar to what
13977 the --audio-channels accepts.
13978 audio-params/hr-channels
13980 As channels, but instead of the possibly cryptic actual
13981 layout sent to the audio device, return a hopefully more
13982 human readable form. (Usually only au‐
13983 dio-out-params/hr-channels makes sense.)
13984 audio-params/channel-count
13986 Number of audio channels. This is redundant to the chan‐
13987 nels field described above.
13988 When querying the property with the client API using MPV_FOR‐
13990 MAT_NODE, or with Lua mp.get_property_native, this will return a
13991 mpv_node with the following contents:
13992 MPV_FORMAT_NODE_MAP
13994 "format" MPV_FORMAT_STRING
13995 "samplerate" MPV_FORMAT_INT64
13996 "channels" MPV_FORMAT_STRING
13997 "channel-count" MPV_FORMAT_INT64
13998 "hr-channels" MPV_FORMAT_STRING
13999 audio-out-params
14001 Same as audio-params, but the format of the data written to the
14002 audio API.
14003 colormatrix
14005 Redirects to video-params/colormatrix. This parameter (as well
14006 as similar ones) can be overridden with the format video filter.
14007 colormatrix-input-range
14009 See colormatrix.
14010 colormatrix-primaries
14012 See colormatrix.
14013 hwdec (RW)
14015 Reflects the --hwdec option.
14016 Writing to it may change the currently used hardware decoder, if
14018 possible. (Internally, the player may reinitialize the decoder,
14019 and will perform a seek to refresh the video properly.) You can
14020 watch the other hwdec properties to see whether this was suc‐
14021 cessful.
14022 Unlike in mpv 0.9.x and before, this does not return the cur‐
14024 rently active hardware decoder. Since mpv 0.18.0, hwdec-current
14025 is available for this purpose.
14026 hwdec-current
14028 The current hardware decoding in use. If decoding is active, re‐
14029 turn one of the values used by the hwdec option/property.
14030 no/false indicates software decoding. If no decoder is loaded,
14031 the property is unavailable.
14032 hwdec-interop
14034 This returns the currently loaded hardware decoding/output in‐
14035 terop driver. This is known only once the VO has opened (and
14036 possibly later). With some VOs (like gpu), this might be never
14037 known in advance, but only when the decoder attempted to create
14038 the hw decoder successfully. (Using --gpu-hwdec-interop can load
14039 it eagerly.) If there are multiple drivers loaded, they will be
14040 separated by ,.
14041 If no VO is active or no interop driver is known, this property
14043 is unavailable.
14044 This does not necessarily use the same values as hwdec. There
14046 can be multiple interop drivers for the same hardware decoder,
14047 depending on platform and VO.
14048 video-format
14050 Video format as string.
14051 video-codec
14053 Video codec selected for decoding.
14054 width, height
14056 Video size. This uses the size of the video as decoded, or if no
14057 video frame has been decoded yet, the (possibly incorrect) con‐
14058 tainer indicated size.
14059 video-params
14061 Video parameters, as output by the decoder (with overrides like
14062 aspect etc. applied). This has a number of sub-properties:
14063 video-params/pixelformat
14065 The pixel format as string. This uses the same names as
14066 used in other places of mpv.
14067 video-params/hw-pixelformat
14069 The underlying pixel format as string. This is relevant
14070 for some cases of hardware decoding and unavailable oth‐
14071 erwise.
14072 video-params/average-bpp
14074 Average bits-per-pixel as integer. Subsampled planar for‐
14075 mats use a different resolution, which is the reason this
14076 value can sometimes be odd or confusing. Can be unavail‐
14077 able with some formats.
14078 video-params/w, video-params/h
14080 Video size as integers, with no aspect correction ap‐
14081 plied.
14082 video-params/dw, video-params/dh
14084 Video size as integers, scaled for correct aspect ratio.
14085 video-params/aspect
14087 Display aspect ratio as float.
14088 video-params/par
14090 Pixel aspect ratio.
14091 video-params/colormatrix
14093 The colormatrix in use as string. (Exact values subject
14094 to change.)
14095 video-params/colorlevels
14097 The colorlevels as string. (Exact values subject to
14098 change.)
14099 video-params/primaries
14101 The primaries in use as string. (Exact values subject to
14102 change.)
14103 video-params/gamma
14105 The gamma function in use as string. (Exact values sub‐
14106 ject to change.)
14107 video-params/sig-peak
14109 The video file's tagged signal peak as float.
14110 video-params/light
14112 The light type in use as a string. (Exact values subject
14113 to change.)
14114 video-params/chroma-location
14116 Chroma location as string. (Exact values subject to
14117 change.)
14118 video-params/rotate
14120 Intended display rotation in degrees (clockwise).
14121 video-params/stereo-in
14123 Source file stereo 3D mode. (See the format video fil‐
14124 ter's stereo-in option.)
14125 video-params/alpha
14127 Alpha type. If the format has no alpha channel, this will
14128 be unavailable (but in future releases, it could change
14129 to no). If alpha is present, this is set to straight or
14130 premul.
14131 When querying the property with the client API using MPV_FOR‐
14133 MAT_NODE, or with Lua mp.get_property_native, this will return a
14134 mpv_node with the following contents:
14135 MPV_FORMAT_NODE_MAP
14137 "pixelformat" MPV_FORMAT_STRING
14138 "hw-pixelformat" MPV_FORMAT_STRING
14139 "w" MPV_FORMAT_INT64
14140 "h" MPV_FORMAT_INT64
14141 "dw" MPV_FORMAT_INT64
14142 "dh" MPV_FORMAT_INT64
14143 "aspect" MPV_FORMAT_DOUBLE
14144 "par" MPV_FORMAT_DOUBLE
14145 "colormatrix" MPV_FORMAT_STRING
14146 "colorlevels" MPV_FORMAT_STRING
14147 "primaries" MPV_FORMAT_STRING
14148 "gamma" MPV_FORMAT_STRING
14149 "sig-peak" MPV_FORMAT_DOUBLE
14150 "light" MPV_FORMAT_STRING
14151 "chroma-location" MPV_FORMAT_STRING
14152 "rotate" MPV_FORMAT_INT64
14153 "stereo-in" MPV_FORMAT_STRING
14154 "average-bpp" MPV_FORMAT_INT64
14155 "alpha" MPV_FORMAT_STRING
14156 dwidth, dheight
14158 Video display size. This is the video size after filters and as‐
14159 pect scaling have been applied. The actual video window size can
14160 still be different from this, e.g. if the user resized the video
14161 window manually.
14162 These have the same values as video-out-params/dw and
14164 video-out-params/dh.
14165 video-dec-params
14167 Exactly like video-params, but no overrides applied.
14168 video-out-params
14170 Same as video-params, but after video filters have been applied.
14171 If there are no video filters in use, this will contain the same
14172 values as video-params. Note that this is still not necessarily
14173 what the video window uses, since the user can change the window
14174 size, and all real VOs do their own scaling independently from
14175 the filter chain.
14176 Has the same sub-properties as video-params.
14178 video-frame-info
14180 Approximate information of the current frame. Note that if any
14181 of these are used on OSD, the information might be off by a few
14182 frames due to OSD redrawing and frame display being somewhat
14183 disconnected, and you might have to pause and force a redraw.
14184 This has a number of sub-properties:
14186 video-frame-info/picture-type
14188 The type of the picture. It can be "I" (intra), "P" (pre‐
14189 dicted), "B" (bi-dir predicted) or unavailable.
14190 video-frame-info/interlaced
14192 Whether the content of the frame is interlaced.
14193 video-frame-info/tff
14195 If the content is interlaced, whether the top field is
14196 displayed first.
14197 video-frame-info/repeat
14199 Whether the frame must be delayed when decoding.
14200 container-fps
14202 Container FPS. This can easily contain bogus values. For videos
14203 that use modern container formats or video codecs, this will of‐
14204 ten be incorrect.
14205 (Renamed from fps.)
14207 estimated-vf-fps
14209 Estimated/measured FPS of the video filter chain output. (If no
14210 filters are used, this corresponds to decoder output.) This uses
14211 the average of the 10 past frame durations to calculate the FPS.
14212 It will be inaccurate if frame-dropping is involved (such as
14213 when framedrop is explicitly enabled, or after precise seeking).
14214 Files with imprecise timestamps (such as Matroska) might lead to
14215 unstable results.
14216 window-scale (RW)
14218 Window size multiplier. Setting this will resize the video win‐
14219 dow to the values contained in dwidth and dheight multiplied
14220 with the value set with this property. Setting 1 will resize to
14221 original video size (or to be exact, the size the video filters
14222 output). 2 will set the double size, 0.5 halves the size.
14223 Note that setting a value identical to its previous value will
14225 not resize the window. That's because this property mirrors the
14226 window-scale option, and setting an option to its previous value
14227 is ignored. If this value is set while the window is in a
14228 fullscreen, the multiplier is not applied until the window is
14229 taken out of that state. Writing this property to a maximized
14230 window can unmaximize the window depending on the OS and window
14231 manager. If the window does not unmaximize, the multiplier will
14232 be applied if the user unmaximizes the window later.
14233 See current-window-scale for the value derived from the actual
14235 window size.
14236 Since mpv 0.31.0, this always returns the previously set value
14238 (or the default value), instead of the value implied by the ac‐
14239 tual window size. Before mpv 0.31.0, this returned what cur‐
14240 rent-window-scale returns now, after the window was created.
14241 current-window-scale (RW)
14243 The window-scale value calculated from the current window size.
14244 This has the same value as window-scale if the window size was
14245 not changed since setting the option, and the window size was
14246 not restricted in other ways. If the window is fullscreened,
14247 this will return the scale value calculated from the last
14248 non-fullscreen size of the window. The property is unavailable
14249 if no video is active.
14250 When setting this property in the fullscreen or maximized state,
14252 the behavior is the same as window-scale. In all ther cases,
14253 setting the value of this property will always resize the win‐
14254 dow. This does not affect the value of window-scale.
14255 focused
14257 Whether the window has focus. Might not be supported by all VOs.
14258 display-names
14260 Names of the displays that the mpv window covers. On X11, these
14261 are the xrandr names (LVDS1, HDMI1, DP1, VGA1, etc.). On Win‐
14262 dows, these are the GDI names (\.DISPLAY1, \.DISPLAY2, etc.) and
14263 the first display in the list will be the one that Windows con‐
14264 siders associated with the window (as determined by the Monitor‐
14265 FromWindow API.) On macOS these are the Display Product Names as
14266 used in the System Information and only one display name is re‐
14267 turned since a window can only be on one screen.
14268 display-fps
14270 The refresh rate of the current display. Currently, this is the
14271 lowest FPS of any display covered by the video, as retrieved by
14272 the underlying system APIs (e.g. xrandr on X11). It is not the
14273 measured FPS. It's not necessarily available on all platforms.
14274 Note that any of the listed facts may change any time without a
14275 warning.
14276 Writing to this property is deprecated. It has the same effect
14278 as writing to override-display-fps. Since mpv 0.31.0, this prop‐
14279 erty is unavailable if no display FPS was reported (e.g. if no
14280 video is active), while in older versions, it returned the
14281 --display-fps option value.
14282 estimated-display-fps
14284 The actual rate at which display refreshes seem to occur, mea‐
14285 sured by system time. Only available if display-sync mode (as
14286 selected by --video-sync) is active.
14287 vsync-jitter
14289 Estimated deviation factor of the vsync duration.
14290 display-width, display-height
14292 The current display's horizontal and vertical resolution in pix‐
14293 els. Whether or not these values update as the mpv window
14294 changes displays depends on the windowing backend. It may not be
14295 available on all platforms.
14296 display-hidpi-scale
14298 The HiDPI scale factor as reported by the windowing backend. If
14299 no VO is active, or if the VO does not report a value, this
14300 property is unavailable. It may be saner to report an absolute
14301 DPI, however, this is the way HiDPI support is implemented on
14302 most OS APIs. See also --hidpi-window-scale.
14303 video-aspect (RW)
14305 Deprecated. This is tied to --video-aspect-override, but always
14306 reports the current video aspect if video is active.
14307 The read and write components of this option can be split up
14309 into video-params/aspect and video-aspect-override respectively.
14310 osd-width, osd-height
14312 Last known OSD width (can be 0). This is needed if you want to
14313 use the overlay-add command. It gives you the actual OSD/window
14314 size (not including decorations drawn by the OS window manager).
14315 Alias to osd-dimensions/w and osd-dimensions/h.
14317 osd-par
14319 Last known OSD display pixel aspect (can be 0).
14320 Alias to osd-dimensions/osd-par.
14322 osd-dimensions
14324 Last known OSD dimensions.
14325 Has the following sub-properties (which can be read as MPV_FOR‐
14327 MAT_NODE or Lua table with mp.get_property_native):
14328 osd-dimensions/w
14330 Size of the VO window in OSD render units (usually pix‐
14331 els, but may be scaled pixels with VOs like xv).
14332 osd-dimensions/h
14334 Size of the VO window in OSD render units,
14335 osd-dimensions/par
14337 Pixel aspect ratio of the OSD (usually 1).
14338 osd-dimensions/aspect
14340 Display aspect ratio of the VO window. (Computing from
14341 the properties above.)
14342 osd-dimensions/mt, osd-dimensions/mb, osd-dimensions/ml, osd-di‐
14344 mensions/mr
14345 OSD to video margins (top, bottom, left, right). This de‐
14346 scribes the area into which the video is rendered.
14347 Any of these properties may be unavailable or set to dummy val‐
14349 ues if the VO window is not created or visible.
14350 mouse-pos
14352 Read-only - last known mouse position, normalizd to OSD dimen‐
14353 sions.
14354 Has the following sub-properties (which can be read as MPV_FOR‐
14356 MAT_NODE or Lua table with mp.get_property_native):
14357 mouse-pos/x, mouse-pos/y
14359 Last known coordinates of the mouse pointer.
14360 mouse-pos/hover
14362 Boolean - whether the mouse pointer hovers the video win‐
14363 dow. The coordinates should be ignored when this value is
14364 false, because the video backends update them only when
14365 the pointer hovers the window.
14366 sub-text
14368 The current subtitle text regardless of sub visibility. Format‐
14369 ting is stripped. If the subtitle is not text-based (i.e. DVD/BD
14370 subtitles), an empty string is returned.
14371 This property is experimental and might be removed in the fu‐
14373 ture.
14374 sub-text-ass
14376 Like sub-text, but return the text in ASS format. Text subtitles
14377 in other formats are converted. For native ASS subtitles, events
14378 that do not contain any text (but vector drawings etc.) are not
14379 filtered out. If multiple events match with the current playback
14380 time, they are concatenated with line breaks. Contains only the
14381 "Text" part of the events.
14382 This property is not enough to render ASS subtitles correctly,
14384 because ASS header and per-event metadata are not returned. You
14385 likely need to do further filtering on the returned string to
14386 make it useful.
14387 This property is experimental and might be removed in the fu‐
14389 ture.
14390 secondary-sub-text
14392 Same as sub-text, but for the secondary subtitles.
14393 sub-start
14395 The current subtitle start time (in seconds). If there's multi‐
14396 ple current subtitles, returns the first start time. If no cur‐
14397 rent subtitle is present null is returned instead.
14398 secondary-sub-start
14400 Same as sub-start, but for the secondary subtitles.
14401 sub-end
14403 The current subtitle end time (in seconds). If there's multiple
14404 current subtitles, return the last end time. If no current sub‐
14405 title is present, or if it's present but has unknown or incor‐
14406 rect duration, null is returned instead.
14407 secondary-sub-end
14409 Same as sub-end, but for the secondary subtitles.
14410 playlist-pos (RW)
14412 Current position on playlist. The first entry is on position 0.
14413 Writing to this property may start playback at the new position.
14414 In some cases, this is not necessarily the currently playing
14416 file. See explanation of current and playing flags in playlist.
14417 If there the playlist is empty, or if it's non-empty, but no en‐
14419 try is "current", this property returns -1. Likewise, writing -1
14420 will put the player into idle mode (or exit playback if idle
14421 mode is not enabled). If an out of range index is written to the
14422 property, this behaves as if writing -1. (Before mpv 0.33.0,
14423 instead of returning -1, this property was unavailable if no
14424 playlist entry was current.)
14425 Writing the current value back to the property is subject to
14427 change. Currently, it will restart playback of the playlist en‐
14428 try. But in the future, writing the current value will be ig‐
14429 nored. Use the playlist-play-index command to get guaranteed be‐
14430 havior.
14431 playlist-pos-1 (RW)
14433 Same as playlist-pos, but 1-based.
14434 playlist-current-pos (RW)
14436 Index of the "current" item on playlist. This usually, but not
14437 necessarily, the currently playing item (see playlist-play‐
14438 ing-pos). Depending on the exact internal state of the player,
14439 it may refer to the playlist item to play next, or the playlist
14440 item used to determine what to play next.
14441 For reading, this is exactly the same as playlist-pos.
14443 For writing, this only sets the position of the "current" item,
14445 without stopping playback of the current file (or starting play‐
14446 back, if this is done in idle mode). Use -1 to remove the cur‐
14447 rent flag.
14448 This property is only vaguely useful. If set during playback, it
14450 will typically cause the playlist entry after it to be played
14451 next. Another possibly odd observable state is that if
14452 playlist-next is run during playback, this property is set to
14453 the playlist entry to play next (unlike the previous case).
14454 There is an internal flag that decides whether the current
14455 playlist entry or the next one should be played, and this flag
14456 is currently inaccessible for API users. (Whether this behavior
14457 will kept is possibly subject to change.)
14458 playlist-playing-pos
14460 Index of the "playing" item on playlist. A playlist item is
14461 "playing" if it's being loaded, actually playing, or being un‐
14462 loaded. This property is set during the MPV_EVENT_START_FILE
14463 (start-file) and the MPV_EVENT_START_END (end-file) events. Out‐
14464 side of that, it returns -1. If the playlist entry was somehow
14465 removed during playback, but playback hasn't stopped yet, or is
14466 in progress of being stopped, it also returns -1. (This can
14467 happen at least during state transitions.)
14468 In the "playing" state, this is usually the same as
14470 playlist-pos, except during state changes, or if playlist-cur‐
14471 rent-pos was written explicitly.
14472 playlist-count
14474 Number of total playlist entries.
14475 playlist
14477 Playlist, current entry marked. Currently, the raw property
14478 value is useless.
14479 This has a number of sub-properties. Replace N with the 0-based
14481 playlist entry index.
14482 playlist/count
14484 Number of playlist entries (same as playlist-count).
14485 playlist/N/filename
14487 Filename of the Nth entry.
14488 playlist/N/playing
14490 yes/true if the playlist-playing-pos property points to
14491 this entry, no/false or unavailable otherwise.
14492 playlist/N/current
14494 yes/true if the playlist-current-pos property points to
14495 this entry, no/false or unavailable otherwise.
14496 playlist/N/title
14498 Name of the Nth entry. Only available if the playlist
14499 file contains such fields, and only if mpv's parser sup‐
14500 ports it for the given playlist format.
14501 playlist/N/id
14503 Unique ID for this entry. This is an automatically as‐
14504 signed integer ID that is unique for the entire life time
14505 of the current mpv core instance. Other commands, events,
14506 etc. use this as playlist_entry_id fields.
14507 When querying the property with the client API using MPV_FOR‐
14509 MAT_NODE, or with Lua mp.get_property_native, this will return a
14510 mpv_node with the following contents:
14511 MPV_FORMAT_NODE_ARRAY
14513 MPV_FORMAT_NODE_MAP (for each playlist entry)
14514 "filename" MPV_FORMAT_STRING
14515 "current" MPV_FORMAT_FLAG (might be missing; since mpv 0.7.0)
14516 "playing" MPV_FORMAT_FLAG (same)
14517 "title" MPV_FORMAT_STRING (optional)
14518 "id" MPV_FORMAT_INT64
14519 track-list
14521 List of audio/video/sub tracks, current entry marked. Currently,
14522 the raw property value is useless.
14523 This has a number of sub-properties. Replace N with the 0-based
14525 track index.
14526 track-list/count
14528 Total number of tracks.
14529 track-list/N/id
14531 The ID as it's used for -sid/--aid/--vid. This is unique
14532 within tracks of the same type (sub/audio/video), but
14533 otherwise not.
14534 track-list/N/type
14536 String describing the media type. One of audio, video,
14537 sub.
14538 track-list/N/src-id
14540 Track ID as used in the source file. Not always avail‐
14541 able. (It is missing if the format has no native ID, if
14542 the track is a pseudo-track that does not exist in this
14543 way in the actual file, or if the format is handled by
14544 libavformat, and the format was not whitelisted as having
14545 track IDs.)
14546 track-list/N/title
14548 Track title as it is stored in the file. Not always
14549 available.
14550 track-list/N/lang
14552 Track language as identified by the file. Not always
14553 available.
14554 track-list/N/image
14556 yes/true if this is a video track that consists of a sin‐
14557 gle picture, no/false or unavailable otherwise. The
14558 heuristic used to determine if a stream is an image
14559 doesn't attempt to detect images in codecs normally used
14560 for videos. Otherwise, it is reliable.
14561 track-list/N/albumart
14563 yes/true if this is an image embedded in an audio file or
14564 external cover art, no/false or unavailable otherwise.
14565 track-list/N/default
14567 yes/true if the track has the default flag set in the
14568 file, no/false or unavailable otherwise.
14569 track-list/N/forced
14571 yes/true if the track has the forced flag set in the
14572 file, no/false or unavailable otherwise.
14573 track-list/N/codec
14575 The codec name used by this track, for example h264. Un‐
14576 available in some rare cases.
14577 track-list/N/external
14579 yes/true if the track is an external file, no/false or
14580 unavailable otherwise. This is set for separate subtitle
14581 files.
14582 track-list/N/external-filename
14584 The filename if the track is from an external file, un‐
14585 available otherwise.
14586 track-list/N/selected
14588 yes/true if the track is currently decoded, no/false or
14589 unavailable otherwise.
14590 track-list/N/main-selection
14592 It indicates the selection order of tracks for the same
14593 type. If a track is not selected, or is selected by the
14594 --lavfi-complex, it is not available. For subtitle
14595 tracks, 0 represents the sid, and 1 represents the sec‐
14596 ondary-sid.
14597 track-list/N/ff-index
14599 The stream index as usually used by the FFmpeg utilities.
14600 Note that this can be potentially wrong if a demuxer
14601 other than libavformat (--demuxer=lavf) is used. For mkv
14602 files, the index will usually match even if the default
14603 (builtin) demuxer is used, but there is no hard guaran‐
14604 tee.
14605 track-list/N/decoder-desc
14607 If this track is being decoded, the human-readable de‐
14608 coder name,
14609 track-list/N/demux-w, track-list/N/demux-h
14611 Video size hint as indicated by the container. (Not al‐
14612 ways accurate.)
14613 track-list/N/demux-channel-count
14615 Number of audio channels as indicated by the container.
14616 (Not always accurate - in particular, the track could be
14617 decoded as a different number of channels.)
14618 track-list/N/demux-channels
14620 Channel layout as indicated by the container. (Not always
14621 accurate.)
14622 track-list/N/demux-samplerate
14624 Audio sample rate as indicated by the container. (Not al‐
14625 ways accurate.)
14626 track-list/N/demux-fps
14628 Video FPS as indicated by the container. (Not always ac‐
14629 curate.)
14630 track-list/N/demux-bitrate
14632 Audio average bitrate, in bits per second. (Not always
14633 accurate.)
14634 track-list/N/demux-rotation
14636 Video clockwise rotation metadata, in degrees.
14637 track-list/N/demux-par
14639 Pixel aspect ratio.
14640 track-list/N/audio-channels (deprecated)
14642 Deprecated alias for track-list/N/demux-channel-count.
14643 track-list/N/replaygain-track-peak, track-list/N/replay‐
14645 gain-track-gain
14646 Per-track replaygain values. Only available for audio
14647 tracks with corresponding information stored in the
14648 source file.
14649 track-list/N/replaygain-album-peak, track-list/N/replaygain-al‐
14651 bum-gain
14652 Per-album replaygain values. If the file has per-track
14653 but no per-album information, the per-album values will
14654 be copied from the per-track values currently. It's pos‐
14655 sible that future mpv versions will make these properties
14656 unavailable instead in this case.
14657 When querying the property with the client API using MPV_FOR‐
14659 MAT_NODE, or with Lua mp.get_property_native, this will return a
14660 mpv_node with the following contents:
14661 MPV_FORMAT_NODE_ARRAY
14663 MPV_FORMAT_NODE_MAP (for each track)
14664 "id" MPV_FORMAT_INT64
14665 "type" MPV_FORMAT_STRING
14666 "src-id" MPV_FORMAT_INT64
14667 "title" MPV_FORMAT_STRING
14668 "lang" MPV_FORMAT_STRING
14669 "image" MPV_FORMAT_FLAG
14670 "albumart" MPV_FORMAT_FLAG
14671 "default" MPV_FORMAT_FLAG
14672 "forced" MPV_FORMAT_FLAG
14673 "selected" MPV_FORMAT_FLAG
14674 "main-selection" MPV_FORMAT_INT64
14675 "external" MPV_FORMAT_FLAG
14676 "external-filename" MPV_FORMAT_STRING
14677 "codec" MPV_FORMAT_STRING
14678 "ff-index" MPV_FORMAT_INT64
14679 "decoder-desc" MPV_FORMAT_STRING
14680 "demux-w" MPV_FORMAT_INT64
14681 "demux-h" MPV_FORMAT_INT64
14682 "demux-channel-count" MPV_FORMAT_INT64
14683 "demux-channels" MPV_FORMAT_STRING
14684 "demux-samplerate" MPV_FORMAT_INT64
14685 "demux-fps" MPV_FORMAT_DOUBLE
14686 "demux-bitrate" MPV_FORMAT_INT64
14687 "demux-rotation" MPV_FORMAT_INT64
14688 "demux-par" MPV_FORMAT_DOUBLE
14689 "audio-channels" MPV_FORMAT_INT64
14690 "replaygain-track-peak" MPV_FORMAT_DOUBLE
14691 "replaygain-track-gain" MPV_FORMAT_DOUBLE
14692 "replaygain-album-peak" MPV_FORMAT_DOUBLE
14693 "replaygain-album-gain" MPV_FORMAT_DOUBLE
14694 current-tracks/...
14696 This gives access to currently selected tracks. It redirects to
14697 the correct entry in track-list.
14698 The following sub-entries are defined: video, audio, sub, sub2
14700 For example, current-tracks/audio/lang returns the current audio
14702 track's language field (the same value as track-list/N/lang).
14703 If tracks of the requested type are selected via --lavfi-com‐
14705 plex, the first one is returned.
14706 chapter-list (RW)
14708 List of chapters, current entry marked. Currently, the raw prop‐
14709 erty value is useless.
14710 This has a number of sub-properties. Replace N with the 0-based
14712 chapter index.
14713 chapter-list/count
14715 Number of chapters.
14716 chapter-list/N/title
14718 Chapter title as stored in the file. Not always avail‐
14719 able.
14720 chapter-list/N/time
14722 Chapter start time in seconds as float.
14723 When querying the property with the client API using MPV_FOR‐
14725 MAT_NODE, or with Lua mp.get_property_native, this will return a
14726 mpv_node with the following contents:
14727 MPV_FORMAT_NODE_ARRAY
14729 MPV_FORMAT_NODE_MAP (for each chapter)
14730 "title" MPV_FORMAT_STRING
14731 "time" MPV_FORMAT_DOUBLE
14732 af, vf (RW)
14734 See --vf/--af and the vf/af command.
14735 When querying the property with the client API using MPV_FOR‐
14737 MAT_NODE, or with Lua mp.get_property_native, this will return a
14738 mpv_node with the following contents:
14739 MPV_FORMAT_NODE_ARRAY
14741 MPV_FORMAT_NODE_MAP (for each filter entry)
14742 "name" MPV_FORMAT_STRING
14743 "label" MPV_FORMAT_STRING [optional]
14744 "enabled" MPV_FORMAT_FLAG [optional]
14745 "params" MPV_FORMAT_NODE_MAP [optional]
14746 "key" MPV_FORMAT_STRING
14747 "value" MPV_FORMAT_STRING
14748 It's also possible to write the property using this format.
14750 seekable
14752 Whether it's generally possible to seek in the current file.
14753 partially-seekable
14755 Whether the current file is considered seekable, but only be‐
14756 cause the cache is active. This means small relative seeks may
14757 be fine, but larger seeks may fail anyway. Whether a seek will
14758 succeed or not is generally not known in advance.
14759 If this property returns yes/true, so will seekable.
14761 playback-abort
14763 Whether playback is stopped or is to be stopped. (Useful in ob‐
14764 scure situations like during on_load hook processing, when the
14765 user can stop playback, but the script has to explicitly end
14766 processing.)
14767 cursor-autohide (RW)
14769 See --cursor-autohide. Setting this to a new value will always
14770 update the cursor, and reset the internal timer.
14771 osd-sym-cc
14773 Inserts the current OSD symbol as opaque OSD control code (cc).
14774 This makes sense only with the show-text command or options
14775 which set OSD messages. The control code is implementation spe‐
14776 cific and is useless for anything else.
14777 osd-ass-cc
14779 ${osd-ass-cc/0} disables escaping ASS sequences of text in OSD,
14780 ${osd-ass-cc/1} enables it again. By default, ASS sequences are
14781 escaped to avoid accidental formatting, and this property can
14782 disable this behavior. Note that the properties return an opaque
14783 OSD control code, which only makes sense for the show-text com‐
14784 mand or options which set OSD messages.
14785 Example
14787 • --osd-msg3='This is ${osd-ass-cc/0}{\\b1}bold text'
14789 • show-text "This is ${osd-ass-cc/0}{\\b1}bold text"
14791 Any ASS override tags as understood by libass can be used.
14793 Note that you need to escape the \ character, because the string
14795 is processed for C escape sequences before passing it to the OSD
14796 code. See Flat command syntax for details.
14797 A list of tags can be found here:
14799 https://aeg-dev.github.io/AegiSite/docs/3.2/ass_tags/
14800 vo-configured
14802 Whether the VO is configured right now. Usually this corresponds
14803 to whether the video window is visible. If the --force-window
14804 option is used, this usually always returns yes/true.
14805 vo-passes
14807 Contains introspection about the VO's active render passes and
14808 their execution times. Not implemented by all VOs.
14809 This is further subdivided into two frame types, vo-passes/fresh
14811 for fresh frames (which have to be uploaded, scaled, etc.) and
14812 vo-passes/redraw for redrawn frames (which only have to be
14813 re-painted). The number of passes for any given subtype can
14814 change from frame to frame, and should not be relied upon.
14815 Each frame type has a number of further sub-properties. Replace
14817 TYPE with the frame type, N with the 0-based pass index, and M
14818 with the 0-based sample index.
14819 vo-passes/TYPE/count
14821 Number of passes.
14822 vo-passes/TYPE/N/desc
14824 Human-friendy description of the pass.
14825 vo-passes/TYPE/N/last
14827 Last measured execution time, in nanoseconds.
14828 vo-passes/TYPE/N/avg
14830 Average execution time of this pass, in nanoseconds. The
14831 exact timeframe varies, but it should generally be a
14832 handful of seconds.
14833 vo-passes/TYPE/N/peak
14835 The peak execution time (highest value) within this aver‐
14836 aging range, in nanoseconds.
14837 vo-passes/TYPE/N/count
14839 The number of samples for this pass.
14840 vo-passes/TYPE/N/samples/M
14842 The raw execution time of a specific sample for this
14843 pass, in nanoseconds.
14844 When querying the property with the client API using MPV_FOR‐
14846 MAT_NODE, or with Lua mp.get_property_native, this will return a
14847 mpv_node with the following contents:
14848 MPV_FORMAT_NODE_MAP
14850 "TYPE" MPV_FORMAT_NODE_ARRAY
14851 MPV_FORMAT_NODE_MAP
14852 "desc" MPV_FORMAT_STRING
14853 "last" MPV_FORMAT_INT64
14854 "avg" MPV_FORMAT_INT64
14855 "peak" MPV_FORMAT_INT64
14856 "count" MPV_FORMAT_INT64
14857 "samples" MPV_FORMAT_NODE_ARRAY
14858 MP_FORMAT_INT64
14859 Note that directly accessing this structure via subkeys is not
14861 supported, the only access is through aforementioned MPV_FOR‐
14862 MAT_NODE.
14863 perf-info
14865 Further performance data. Querying this property triggers inter‐
14866 nal collection of some data, and may slow down the player. Each
14867 query will reset some internal state. Property change notifica‐
14868 tion doesn't and won't work. All of this may change in the fu‐
14869 ture, so don't use this. The builtin stats script is supposed to
14870 be the only user; since it's bundled and built with the source
14871 code, it can use knowledge of mpv internal to render the infor‐
14872 mation properly. See stats script description for some details.
14873 video-bitrate, audio-bitrate, sub-bitrate
14875 Bitrate values calculated on the packet level. This works by di‐
14876 viding the bit size of all packets between two keyframes by
14877 their presentation timestamp distance. (This uses the timestamps
14878 are stored in the file, so e.g. playback speed does not influ‐
14879 ence the returned values.) In particular, the video bitrate will
14880 update only per keyframe, and show the "past" bitrate. To make
14881 the property more UI friendly, updates to these properties are
14882 throttled in a certain way.
14883 The unit is bits per second. OSD formatting turns these values
14885 in kilobits (or megabits, if appropriate), which can be pre‐
14886 vented by using the raw property value, e.g. with ${=video-bi‐
14887 trate}.
14888 Note that the accuracy of these properties is influenced by a
14890 few factors. If the underlying demuxer rewrites the packets on
14891 demuxing (done for some file formats), the bitrate might be
14892 slightly off. If timestamps are bad or jittery (like in Ma‐
14893 troska), even constant bitrate streams might show fluctuating
14894 bitrate.
14895 How exactly these values are calculated might change in the fu‐
14897 ture.
14898 In earlier versions of mpv, these properties returned a static
14900 (but bad) guess using a completely different method.
14901 packet-video-bitrate, packet-audio-bitrate, packet-sub-bitrate
14903 Old and deprecated properties for video-bitrate, audio-bitrate,
14904 sub-bitrate. They behave exactly the same, but return a value in
14905 kilobits. Also, they don't have any OSD formatting, though the
14906 same can be achieved with e.g. ${=video-bitrate}.
14907 These properties shouldn't be used anymore.
14909 audio-device-list
14911 The list of discovered audio devices. This is mostly for use
14912 with the client API, and reflects what --audio-device=help with
14913 the command line player returns.
14914 When querying the property with the client API using MPV_FOR‐
14916 MAT_NODE, or with Lua mp.get_property_native, this will return a
14917 mpv_node with the following contents:
14918 MPV_FORMAT_NODE_ARRAY
14920 MPV_FORMAT_NODE_MAP (for each device entry)
14921 "name" MPV_FORMAT_STRING
14922 "description" MPV_FORMAT_STRING
14923 The name is what is to be passed to the --audio-device option
14925 (and often a rather cryptic audio API-specific ID), while de‐
14926 scription is human readable free form text. The description is
14927 set to the device name (minus mpv-specific <driver>/ prefix) if
14928 no description is available or the description would have been
14929 an empty string.
14930 The special entry with the name set to auto selects the default
14932 audio output driver and the default device.
14933 The property can be watched with the property observation mecha‐
14935 nism in the client API and in Lua scripts. (Technically, change
14936 notification is enabled the first time this property is read.)
14937 audio-device (RW)
14939 Set the audio device. This directly reads/writes the --audio-de‐
14940 vice option, but on write accesses, the audio output will be
14941 scheduled for reloading.
14942 Writing this property while no audio output is active will not
14944 automatically enable audio. (This is also true in the case when
14945 audio was disabled due to reinitialization failure after a pre‐
14946 vious write access to audio-device.)
14947 This property also doesn't tell you which audio device is actu‐
14949 ally in use.
14950 How these details are handled may change in the future.
14952 current-vo
14954 Current video output driver (name as used with --vo).
14955 current-ao
14957 Current audio output driver (name as used with --ao).
14958 shared-script-properties (RW)
14960 This is a key/value map of arbitrary strings shared between
14961 scripts for general use. The player itself does not use any data
14962 in it (although some builtin scripts may). The property is not
14963 preserved across player restarts.
14964 This is very primitive, inefficient, and annoying to use. It's a
14966 makeshift solution which could go away any time (for example,
14967 when a better solution becomes available). This is also why this
14968 property has an annoying name. You should avoid using it, unless
14969 you absolutely have to.
14970 Lua scripting has helpers starting with
14972 utils.shared_script_property_. They are undocumented because
14973 you should not use this property. If you still think you must,
14974 you should use the helpers instead of the property directly.
14975 You are supposed to use the change-list command to modify the
14977 contents. Reading, modifying, and writing the property manually
14978 could data loss if two scripts update different keys at the same
14979 time due to lack of synchronization. The Lua helpers take care
14980 of this.
14981 (There is no way to ensure synchronization if two scripts try to
14983 update the same key at the same time.)
14984 working-directory
14986 The working directory of the mpv process. Can be useful for JSON
14987 IPC users, because the command line player usually works with
14988 relative paths.
14989 protocol-list
14991 List of protocol prefixes potentially recognized by the player.
14992 They are returned without trailing :// suffix (which is still
14993 always required). In some cases, the protocol will not actually
14994 be supported (consider https if ffmpeg is not compiled with TLS
14995 support).
14996 decoder-list
14998 List of decoders supported. This lists decoders which can be
14999 passed to --vd and --ad.
15000 codec Canonical codec name, which identifies the format the de‐
15002 coder can handle.
15003 driver The name of the decoder itself. Often, this is the same
15005 as codec. Sometimes it can be different. It is used to
15006 distinguish multiple decoders for the same codec.
15007 description
15009 Human readable description of the decoder and codec.
15010 When querying the property with the client API using MPV_FOR‐
15012 MAT_NODE, or with Lua mp.get_property_native, this will return a
15013 mpv_node with the following contents:
15014 MPV_FORMAT_NODE_ARRAY
15016 MPV_FORMAT_NODE_MAP (for each decoder entry)
15017 "codec" MPV_FORMAT_STRING
15018 "driver" MPV_FORMAT_STRING
15019 "description" MPV_FORMAT_STRING
15020 encoder-list
15022 List of libavcodec encoders. This has the same format as de‐
15023 coder-list. The encoder names (driver entries) can be passed to
15024 --ovc and --oac (without the lavc: prefix required by --vd and
15025 --ad).
15026 demuxer-lavf-list
15028 List of available libavformat demuxers' names. This can be used
15029 to check for support for a specific format or use with --de‐
15030 muxer-lavf-format.
15031 input-key-list
15033 List of Key names, same as output by --input-keylist.
15034 mpv-version
15036 The mpv version/copyright string. Depending on how the binary
15037 was built, it might contain either a release version, or just a
15038 git hash.
15039 mpv-configuration
15041 The configuration arguments which were passed to the build sys‐
15042 tem (typically the way ./waf configure ... was invoked).
15043 ffmpeg-version
15045 The contents of the av_version_info() API call. This is a string
15046 which identifies the build in some way, either through a release
15047 version number, or a git hash. This applies to Libav as well
15048 (the property is still named the same.) This property is un‐
15049 available if mpv is linked against older FFmpeg and Libav ver‐
15050 sions.
15051 libass-version
15053 The value of ass_library_version(). This is an integer, encoded
15054 in a somewhat weird form (apparently "hex BCD"), indicating the
15055 release version of the libass library linked to mpv.
15056 options/<name> (RW)
15058 The value of option --<name>. Most options can be changed at
15059 runtime by writing to this property. Note that many options re‐
15060 quire reloading the file for changes to take effect. If there is
15061 an equivalent property, prefer setting the property instead.
15062 There shouldn't be any reason to access options/<name> instead
15064 of <name>, except in situations in which the properties have
15065 different behavior or conflicting semantics.
15066 file-local-options/<name> (RW)
15068 Similar to options/<name>, but when setting an option through
15069 this property, the option is reset to its old value once the
15070 current file has stopped playing. Trying to write an option
15071 while no file is playing (or is being loaded) results in an er‐
15072 ror.
15073 (Note that if an option is marked as file-local, even options/
15075 will access the local value, and the old value, which will be
15076 restored on end of playback, cannot be read or written until end
15077 of playback.)
15078 option-info/<name>
15080 Additional per-option information.
15081 This has a number of sub-properties. Replace <name> with the
15083 name of a top-level option. No guarantee of stability is given
15084 to any of these sub-properties - they may change radically in
15085 the feature.
15086 option-info/<name>/name
15088 The name of the option.
15089 option-info/<name>/type
15091 The name of the option type, like String or Integer. For
15092 many complex types, this isn't very accurate.
15093 option-info/<name>/set-from-commandline
15095 Whether the option was set from the mpv command line.
15096 What this is set to if the option is e.g. changed at run‐
15097 time is left undefined (meaning it could change in the
15098 future).
15099 option-info/<name>/set-locally
15101 Whether the option was set per-file. This is the case
15102 with automatically loaded profiles, file-dir configs, and
15103 other cases. It means the option value will be restored
15104 to the value before playback start when playback ends.
15105 option-info/<name>/default-value
15107 The default value of the option. May not always be avail‐
15108 able.
15109 option-info/<name>/min, option-info/<name>/max
15111 Integer minimum and maximum values allowed for the op‐
15112 tion. Only available if the options are numeric, and the
15113 minimum/maximum has been set internally. It's also possi‐
15114 ble that only one of these is set.
15115 option-info/<name>/choices
15117 If the option is a choice option, the possible choices.
15118 Choices that are integers may or may not be included
15119 (they can be implied by min and max). Note that options
15120 which behave like choice options, but are not actual
15121 choice options internally, may not have this info avail‐
15122 able.
15123 property-list
15125 The list of top-level properties.
15126 profile-list
15128 The list of profiles and their contents. This is highly imple‐
15129 mentation-specific, and may change any time. Currently, it re‐
15130 turns an array of options for each profile. Each option has a
15131 name and a value, with the value currently always being a
15132 string. Note that the options array is not a map, as order mat‐
15133 ters and duplicate entries are possible. Recursive profiles are
15134 not expanded, and show up as special profile options.
15135 The profile-restore field is currently missing if it holds the
15137 default value (either because it was not set, or set explicitly
15138 to default), but in the future it might hold the value default.
15139 command-list
15141 The list of input commands. This returns an array of maps, where
15142 each map node represents a command. This map currently only has
15143 a single entry: name for the name of the command. (This property
15144 is supposed to be a replacement for --input-cmdlist. The option
15145 dumps some more information, but it's a valid feature request to
15146 extend this property if needed.)
15147 input-bindings
15149 The list of current input key bindings. This returns an array of
15150 maps, where each map node represents a binding for a single
15151 key/command. This map has the following entries:
15152 key The key name. This is normalized and may look slightly
15154 different from how it was specified in the source (e.g.
15155 in input.conf).
15156 cmd The command mapped to the key. (Currently, this is ex‐
15158 actly the same string as specified in the source, other
15159 than stripping whitespace and comments. It's possible
15160 that it will be normalized in the future.)
15161 is_weak
15163 If set to true, any existing and active user bindings
15164 will take priority.
15165 owner If this entry exists, the name of the script (or similar)
15167 which added this binding.
15168 section
15170 Name of the section this binding is part of. This is a
15171 rarely used mechanism. This entry may be removed or
15172 change meaning in the future.
15173 priority
15175 A number. Bindings with a higher value are preferred over
15176 bindings with a lower value. If the value is negative,
15177 this binding is inactive and will not be triggered by in‐
15178 put. Note that mpv does not use this value internally,
15179 and matching of bindings may work slightly differently in
15180 some cases. In addition, this value is dynamic and can
15181 change around at runtime.
15182 comment
15184 If available, the comment following the command on the
15185 same line. (For example, the input.conf entry f cycle bla
15186 # toggle bla would result in an entry with comment =
15187 "toggle bla", cmd = "cycle bla".)
15188 This property is read-only, and change notification is not sup‐
15190 ported. Currently, there is no mechanism to change key bindings
15191 at runtime, other than scripts adding or removing their own
15192 bindings.
15193 Inconsistencies between options and properties
15195 You can access (almost) all options as properties, though there are
15196 some caveats with some properties (due to historical reasons):
15197 vid, aid, sid
15199 While playback is active, these return the actually active
15200 tracks. For example, if you set aid=5, and the currently played
15201 file contains no audio track with ID 5, the aid property will
15202 return no.
15203 Before mpv 0.31.0, you could set existing tracks at runtime
15205 only.
15206 display-fps
15208 This inconsistent behavior is deprecated. Post-deprecation, the
15209 reported value and the option value are cleanly separated (over‐
15210 ride-display-fps for the option value).
15211 vf, af If you set the properties during playback, and the filter chain
15213 fails to reinitialize, the option will be set, but the runtime
15214 filter chain does not change. On the other hand, the next video
15215 to be played will fail, because the initial filter chain cannot
15216 be created.
15217 This behavior changed in mpv 0.31.0. Before this, the new value
15219 was rejected iff a video (for vf) or an audio (for af) track was
15220 active. If playback was not active, the behavior was the same as
15221 the current one.
15222 playlist
15224 The property is read-only and returns the current internal
15225 playlist. The option is for loading playlist during command line
15226 parsing. For client API uses, you should use the loadlist com‐
15227 mand instead.
15228 profile, include
15230 These are write-only, and will perform actions as they are writ‐
15231 ten to, exactly as if they were used on the mpv CLI commandline.
15232 Their only use is when using libmpv before mpv_initialize(),
15233 which in turn is probably only useful in encoding mode. Normal
15234 libmpv users should use other mechanisms, such as the apply-pro‐
15235 file command, and the mpv_load_config_file API function. Avoid
15236 these properties.
15237 Property Expansion
15239 All string arguments to input commands as well as certain options (like
15240 --term-playing-msg) are subject to property expansion. Note that prop‐
15241 erty expansion does not work in places where e.g. numeric parameters
15242 are expected. (For example, the add command does not do property ex‐
15243 pansion. The set command is an exception and not a general rule.)
15244 Example for input.conf
15246 i show-text "Filename: ${filename}"
15248 shows the filename of the current file when pressing the i
15249 key
15250 Whether property expansion is enabled by default depends on which API
15252 is used (see Flat command syntax, Commands specified as arrays and
15253 Named arguments), but it can always be enabled with the expand-proper‐
15254 ties prefix or disabled with the raw prefix, as described in Input Com‐
15255 mand Prefixes.
15256 The following expansions are supported:
15258 ${NAME}
15260 Expands to the value of the property NAME. If retrieving the
15261 property fails, expand to an error string. (Use ${NAME:} with a
15262 trailing : to expand to an empty string instead.) If NAME is
15263 prefixed with =, expand to the raw value of the property (see
15264 section below).
15265 ${NAME:STR}
15267 Expands to the value of the property NAME, or STR if the prop‐
15268 erty cannot be retrieved. STR is expanded recursively.
15269 ${?NAME:STR}
15271 Expands to STR (recursively) if the property NAME is available.
15272 ${!NAME:STR}
15274 Expands to STR (recursively) if the property NAME cannot be re‐
15275 trieved.
15276 ${?NAME==VALUE:STR}
15278 Expands to STR (recursively) if the property NAME expands to a
15279 string equal to VALUE. You can prefix NAME with = in order to
15280 compare the raw value of a property (see section below). If the
15281 property is unavailable, or other errors happen when retrieving
15282 it, the value is never considered equal. Note that VALUE can't
15283 contain any of the characters : or }. Also, it is possible that
15284 escaping with " or % might be added in the future, should the
15285 need arise.
15286 ${!NAME==VALUE:STR}
15288 Same as with the ? variant, but STR is expanded if the value is
15289 not equal. (Using the same semantics as with ?.)
15290 $$ Expands to $.
15292 $} Expands to }. (To produce this character inside recursive expan‐
15294 sion.)
15295 $> Disable property expansion and special handling of $ for the
15297 rest of the string.
15298 In places where property expansion is allowed, C-style escapes are of‐
15300 ten accepted as well. Example:
15301 • \n becomes a newline character
15303 • \\ expands to \
15305 Raw and Formatted Properties
15307 Normally, properties are formatted as human-readable text, meant to be
15308 displayed on OSD or on the terminal. It is possible to retrieve an un‐
15309 formatted (raw) value from a property by prefixing its name with =.
15310 These raw values can be parsed by other programs and follow the same
15311 conventions as the options associated with the properties.
15312 Examples
15314 • ${time-pos} expands to 00:14:23 (if playback position is at 14
15316 minutes 23 seconds)
15317 • ${=time-pos} expands to 863.4 (same time, plus 400 milliseconds -
15319 milliseconds are normally not shown in the formatted case)
15320 Sometimes, the difference in amount of information carried by raw and
15322 formatted property values can be rather big. In some cases, raw values
15323 have more information, like higher precision than seconds with
15324 time-pos. Sometimes it is the other way around, e.g. aid shows track
15325 title and language in the formatted case, but only the track number if
15326 it is raw.
15327
15329 The On Screen Controller (short: OSC) is a minimal GUI integrated with
15330 mpv to offer basic mouse-controllability. It is intended to make inter‐
15331 action easier for new users and to enable precise and direct seeking.
15332 The OSC is enabled by default if mpv was compiled with Lua support. It
15334 can be disabled entirely using the --osc=no option.
15335 Using the OSC
15337 By default, the OSC will show up whenever the mouse is moved inside the
15338 player window and will hide if the mouse is not moved outside the OSC
15339 for 0.5 seconds or if the mouse leaves the window.
15340 The Interface
15342 +---------+----------+------------------------------------------+----------+
15343 | pl prev | pl next | title | cache |
15344 +------+--+---+------+---------+-----------+------+-------+-----+-----+----+
15345 | play | skip | skip | time | seekbar | time | audio | sub | vol | fs |
15346 | | back | frwd | elapsed | | left | | | | |
15347 +------+------+------+---------+-----------+------+-------+-----+-----+----+
15348 pl prev
15350 ┌──────────────┬────────────────────────────┐
15352 │left-click │ play previous file in │
15353 │ │ playlist │
15354 ├──────────────┼────────────────────────────┤
15355 │right-click │ show playlist │
15356 ├──────────────┼────────────────────────────┤
15357 │shift+L-click │ show playlist │
15358 └──────────────┴────────────────────────────┘
15359 pl next
15361 ┌──────────────┬────────────────────────────┐
15364 │left-click │ play next file in playlist │
15365 ├──────────────┼────────────────────────────┤
15366 │right-click │ show playlist │
15367 ├──────────────┼────────────────────────────┤
15368 │shift+L-click │ show playlist │
15369 └──────────────┴────────────────────────────┘
15370 title
15372 Displays current media-title, filename, custom title, or target chapter
15373 name while hovering the seekbar.
15374 ┌────────────┬────────────────────────────┐
15377 │left-click │ show playlist position and │
15378 │ │ length and full title │
15379 ├────────────┼────────────────────────────┤
15380 │right-click │ show filename │
15381 └────────────┴────────────────────────────┘
15382 cache
15384 Shows current cache fill status
15385 play
15388 ┌───────────┬───────────────────┐
15390 │left-click │ toggle play/pause │
15391 └───────────┴───────────────────┘
15392 skip back
15394 ┌──────────────┬────────────────────────────┐
15396 │left-click │ go to beginning of chapter │
15397 │ │ / previous chapter │
15398 ├──────────────┼────────────────────────────┤
15399 │right-click │ show chapters │
15400 ├──────────────┼────────────────────────────┤
15401 │shift+L-click │ show chapters │
15402 └──────────────┴────────────────────────────┘
15403 skip frwd
15405 ┌──────────────┬────────────────────┐
15407 │left-click │ go to next chapter │
15408 ├──────────────┼────────────────────┤
15409 │right-click │ show chapters │
15410 ├──────────────┼────────────────────┤
15411 │shift+L-click │ show chapters │
15412 └──────────────┴────────────────────┘
15413 time elapsed
15415 Shows current playback position timestamp
15416 ┌───────────┬────────────────────────────┐
15419 │left-click │ toggle displaying time‐ │
15420 │ │ codes with milliseconds │
15421 └───────────┴────────────────────────────┘
15422 seekbar
15424 Indicates current playback position and position of chapters
15425 ┌───────────┬──────────────────┐
15428 │left-click │ seek to position │
15429 └───────────┴──────────────────┘
15430 time left
15432 Shows remaining playback time timestamp
15433 ┌───────────┬────────────────────────────┐
15436 │left-click │ toggle between total and │
15437 │ │ remaining time │
15438 └───────────┴────────────────────────────┘
15439 audio and sub
15441 Displays selected track and amount of available tracks
15442 ┌──────────────┬────────────────────────────┐
15445 │left-click │ cycle audio/sub tracks │
15446 │ │ forward │
15447 ├──────────────┼────────────────────────────┤
15448 │right-click │ cycle audio/sub tracks │
15449 │ │ backwards │
15450 ├──────────────┼────────────────────────────┤
15451 │shift+L-click │ show available audio/sub │
15452 │ │ tracks │
15453 └──────────────┴────────────────────────────┘
15454 vol
15456 ┌────────────┬────────────────┐
15458 │left-click │ toggle mute │
15459 ├────────────┼────────────────┤
15460 │mouse wheel │ volume up/down │
15461 └────────────┴────────────────┘
15462 fs
15464 ┌───────────┬───────────────────┐
15466 │left-click │ toggle fullscreen │
15467 └───────────┴───────────────────┘
15468 Key Bindings
15470 These key bindings are active by default if nothing else is already
15471 bound to these keys. In case of collision, the function needs to be
15472 bound to a different key. See the Script Commands section.
15473 ┌────┬────────────────────────────┐
15475 │del │ Cycles visibility between │
15476 │ │ never / auto (mouse-move) │
15477 │ │ / always │
15478 └────┴────────────────────────────┘
15479 Configuration
15481 The OSC offers limited configuration through a config file
15482 script-opts/osc.conf placed in mpv's user dir and through the
15483 --script-opts command-line option. Options provided through the com‐
15484 mand-line will override those from the config file.
15485 Config Syntax
15487 The config file must exactly follow the following syntax:
15488 # this is a comment
15490 optionA=value1
15491 optionB=value2
15492 # can only be used at the beginning of a line and there may be no spa‐
15494 ces around the = or anywhere else.
15495 Command-line Syntax
15497 To avoid collisions with other scripts, all options need to be prefixed
15498 with osc-.
15499 Example:
15501 --script-opts=osc-optionA=value1,osc-optionB=value2
15503 Configurable Options
15505 layout Default: bottombar
15506 The layout for the OSC. Currently available are: box, slimbox,
15508 bottombar and topbar. Default pre-0.21.0 was 'box'.
15509 seekbarstyle
15511 Default: bar
15512 Sets the style of the playback position marker and overall shape
15514 of the seekbar: bar, diamond or knob.
15515 seekbarhandlesize
15517 Default: 0.6
15518 Size ratio of the seek handle if seekbarstyle is set to dimaond
15520 or knob. This is relative to the full height of the seekbar.
15521 seekbarkeyframes
15523 Default: yes
15524 Controls the mode used to seek when dragging the seekbar. If set
15526 to yes, default seeking mode is used (usually keyframes, but
15527 player defaults and heuristics can change it to exact). If set
15528 to no, exact seeking on mouse drags will be used instead.
15529 Keyframes are preferred, but exact seeks may be useful in cases
15530 where keyframes cannot be found. Note that using exact seeks can
15531 potentially make mouse dragging much slower.
15532 seekrangestyle
15534 Default: inverted
15535 Display seekable ranges on the seekbar. bar shows them on the
15537 full height of the bar, line as a thick line and inverted as a
15538 thin line that is inverted over playback position markers. none
15539 will hide them. Additionally, slider will show a permanent han‐
15540 dle inside the seekbar with cached ranges marked inside. Note
15541 that these will look differently based on the seekbarstyle op‐
15542 tion. Also, slider does not work with seekbarstyle set to bar.
15543 seekrangeseparate
15545 Default: yes
15546 Controls whether to show line-style seekable ranges on top of
15548 the seekbar or separately if seekbarstyle is set to bar.
15549 seekrangealpha
15551 Default: 200
15552 Alpha of the seekable ranges, 0 (opaque) to 255 (fully transpar‐
15554 ent).
15555 deadzonesize
15557 Default: 0.5
15558 Size of the deadzone. The deadzone is an area that makes the
15560 mouse act like leaving the window. Movement there won't make the
15561 OSC show up and it will hide immediately if the mouse enters it.
15562 The deadzone starts at the window border opposite to the OSC and
15563 the size controls how much of the window it will span. Values
15564 between 0.0 and 1.0, where 0 means the OSC will always popup
15565 with mouse movement in the window, and 1 means the OSC will only
15566 show up when the mouse hovers it. Default pre-0.21.0 was 0.
15567 minmousemove
15569 Default: 0
15570 Minimum amount of pixels the mouse has to move between ticks to
15572 make the OSC show up. Default pre-0.21.0 was 3.
15573 showwindowed
15575 Default: yes
15576 Enable the OSC when windowed
15578 showfullscreen
15580 Default: yes
15581 Enable the OSC when fullscreen
15583 idlescreen
15585 Default: yes
15586 Show the mpv logo and message when idle
15588 scalewindowed
15590 Default: 1.0
15591 Scale factor of the OSC when windowed.
15593 scalefullscreen
15595 Default: 1.0
15596 Scale factor of the OSC when fullscreen
15598 scaleforcedwindow
15600 Default: 2.0
15601 Scale factor of the OSC when rendered on a forced (dummy) window
15603 vidscale
15605 Default: yes
15606 Scale the OSC with the video no tries to keep the OSC size con‐
15608 stant as much as the window size allows
15609 valign Default: 0.8
15611 Vertical alignment, -1 (top) to 1 (bottom)
15613 halign Default: 0.0
15615 Horizontal alignment, -1 (left) to 1 (right)
15617 barmargin
15619 Default: 0
15620 Margin from bottom (bottombar) or top (topbar), in pixels
15622 boxalpha
15624 Default: 80
15625 Alpha of the background box, 0 (opaque) to 255 (fully transpar‐
15627 ent)
15628 hidetimeout
15630 Default: 500
15631 Duration in ms until the OSC hides if no mouse movement, must
15633 not be negative
15634 fadeduration
15636 Default: 200
15637 Duration of fade out in ms, 0 = no fade
15639 title Default: ${media-title}
15641 String that supports property expansion that will be displayed
15643 as OSC title. ASS tags are escaped, and newlines and trailing
15644 slashes are stripped.
15645 tooltipborder
15647 Default: 1
15648 Size of the tooltip outline when using bottombar or topbar lay‐
15650 outs
15651 timetotal
15653 Default: no
15654 Show total time instead of time remaining
15656 timems Default: no
15658 Display timecodes with milliseconds
15660 tcspace
15662 Default: 100 (allowed: 50-200)
15663 Adjust space reserved for timecodes (current time and time re‐
15665 maining) in the bottombar and topbar layouts. The timecode width
15666 depends on the font, and with some fonts the spacing near the
15667 timecodes becomes too small. Use values above 100 to increase
15668 that spacing, or below 100 to decrease it.
15669 visibility
15671 Default: auto (auto hide/show on mouse move)
15672 Also supports never and always
15674 boxmaxchars
15676 Default: 80
15677 Max chars for the osc title at the box layout. mpv does not mea‐
15679 sure the text width on screen and so it needs to limit it by
15680 number of chars. The default is conservative to allow wide fonts
15681 to be used without overflow. However, with many common fonts a
15682 bigger number can be used. YMMV.
15683 boxvideo
15685 Default: no
15686 Whether to overlay the osc over the video (no), or to box the
15688 video within the areas not covered by the osc (yes). If this op‐
15689 tion is set, the osc may overwrite the --video-margin-ratio-*
15690 options, even if the user has set them. (It will not overwrite
15691 them if all of them are set to default values.) Additionally,
15692 visibility must be set to always. Otherwise, this option does
15693 nothing.
15694 Currently, this is supported for the bottombar and topbar layout
15696 only. The other layouts do not change if this option is set.
15697 Separately, if window controls are present (see below), they
15698 will be affected regardless of which osc layout is in use.
15699 The border is static and appears even if the OSC is configured
15701 to appear only on mouse interaction. If the OSC is invisible,
15702 the border is simply filled with the background color (black by
15703 default).
15704 This currently still makes the OSC overlap with subtitles (if
15706 the --sub-use-margins option is set to yes, the default). This
15707 may be fixed later.
15708 This does not work correctly with video outputs like --vo=xv,
15710 which render OSD into the unscaled video.
15711 windowcontrols
15713 Default: auto (Show window controls if there is no window bor‐
15714 der)
15715 Whether to show window management controls over the video, and
15717 if so, which side of the window to place them. This may be de‐
15718 sirable when the window has no decorations, either because they
15719 have been explicitly disabled (border=no) or because the current
15720 platform doesn't support them (eg: gnome-shell with wayland).
15721 The set of window controls is fixed, offering minimize, maxi‐
15723 mize, and quit. Not all platforms implement minimize and maxi‐
15724 mize, but quit will always work.
15725 windowcontrols_alignment
15727 Default: right
15728 If window controls are shown, indicates which side should they
15730 be aligned to.
15731 Supports left and right which will place the controls on those
15733 respective sides.
15734 greenandgrumpy
15736 Default: no
15737 Set to yes to reduce festivity (i.e. disable santa hat in Decem‐
15739 ber.)
15740 livemarkers
15742 Default: yes
15743 Update chapter markers positions on duration changes, e.g. live
15745 streams. The updates are unoptimized - consider disabling it on
15746 very low-end systems.
15747 chapters_osd, playlist_osd
15749 Default: yes
15750 Whether to display the chapters/playlist at the OSD when
15752 left-clicking the next/previous OSC buttons, respectively.
15753 chapter_fmt
15755 Default: Chapter: %s
15756 Template for the chapter-name display when hovering the seekbar.
15758 Use no to disable chapter display on hover. Otherwise it's a lua
15759 string.format template and %s is replaced with the actual name.
15760 unicodeminus
15762 Default: no
15763 Use a Unicode minus sign instead of an ASCII hyphen when dis‐
15765 playing the remaining playback time.
15766 Script Commands
15768 The OSC script listens to certain script commands. These commands can
15769 bound in input.conf, or sent by other scripts.
15770 osc-message
15772 Show a message on screen using the OSC. First argument is the
15773 message, second the duration in seconds.
15774 osc-visibility
15776 Controls visibility mode never / auto (on mouse move) / always
15777 and also cycle to cycle between the modes
15778 Example
15780 You could put this into input.conf to hide the OSC with the a key and
15782 to set auto mode (the default) with b:
15783 a script-message osc-visibility never
15785 b script-message osc-visibility auto
15786 osc-idlescreen
15788 Controls the visibility of the mpv logo on idle. Valid arguments
15789 are yes, no, and cycle to toggle between yes and no.
15790 osc-playlist, osc-chapterlist, osc-tracklist
15792 Shows a limited view of the respective type of list using the
15793 OSC. First argument is duration in seconds.
15794
15796 This builtin script displays information and statistics for the cur‐
15797 rently played file. It is enabled by default if mpv was compiled with
15798 Lua support. It can be disabled entirely using the --load-stats-over‐
15799 lay=no option.
15800 Usage
15802 The following key bindings are active by default unless something else
15803 is already bound to them:
15804 ┌──┬────────────────────────────┐
15806 │i │ Show stats for a fixed du‐ │
15807 │ │ ration │
15808 ├──┼────────────────────────────┤
15809 │I │ Toggle stats (shown until │
15810 │ │ toggled again) │
15811 └──┴────────────────────────────┘
15812 While the stats are visible on screen the following key bindings are
15814 active, regardless of existing bindings. They allow you to switch be‐
15815 tween pages of stats:
15816 ┌──┬────────────────────────────┐
15818 │1 │ Show usual stats │
15819 ├──┼────────────────────────────┤
15820 │2 │ Show frame timings │
15821 │ │ (scroll) │
15822 ├──┼────────────────────────────┤
15823 │3 │ Input cache stats │
15824 ├──┼────────────────────────────┤
15825 │4 │ Active key bindings │
15826 │ │ (scroll) │
15827 ├──┼────────────────────────────┤
15828 │0 │ Internal stuff (scroll) │
15829 └──┴────────────────────────────┘
15830 On pages which support scroll, these key bindings are also active:
15832 ┌─────┬──────────────────────┐
15834 │UP │ Scroll one line up │
15835 ├─────┼──────────────────────┤
15836 │DOWN │ Scroll one line down │
15837 └─────┴──────────────────────┘
15838 Font
15840 For optimal visual experience, a font with support for many font
15841 weights and monospaced digits is recommended. By default, the open
15842 source font Source Sans Pro is used.
15843 Configuration
15845 This script can be customized through a config file
15846 script-opts/stats.conf placed in mpv's user directory and through the
15847 --script-opts command-line option. The configuration syntax is de‐
15848 scribed in ON SCREEN CONTROLLER.
15849 Configurable Options
15851 key_page_1
15852 Default: 1
15853 key_page_2
15855 Default: 2
15856 key_page_3
15858 Default: 3
15859 key_page_4
15861 Default: 4
15862 key_page_0
15864 Default: 0
15865 Key bindings for page switching while stats are displayed.
15867 key_scroll_up
15869 Default: UP
15870 key_scroll_down
15872 Default: DOWN
15873 scroll_lines
15875 Default: 1
15876 Scroll key bindings and number of lines to scroll on pages which
15878 support it.
15879 duration
15881 Default: 4
15882 How long the stats are shown in seconds (oneshot).
15884 redraw_delay
15886 Default: 1
15887 How long it takes to refresh the displayed stats in seconds
15889 (toggling).
15890 persistent_overlay
15892 Default: no
15893 When no, other scripts printing text to the screen can overwrite
15895 the displayed stats. When yes, displayed stats are persistently
15896 shown for the respective duration. This can result in overlap‐
15897 ping text when multiple scripts decide to print text at the same
15898 time.
15899 plot_perfdata
15901 Default: yes
15902 Show graphs for performance data (page 2).
15904 plot_vsync_ratio
15906 Default: yes
15907 plot_vsync_jitter
15909 Default: yes
15910 Show graphs for vsync and jitter values (page 1). Only when tog‐
15912 gled.
15913 flush_graph_data
15915 Default: yes
15916 Clear data buffers used for drawing graphs when toggling.
15918 font Default: Source Sans Pro
15920 Font name. Should support as many font weights as possible for
15922 optimal visual experience.
15923 font_mono
15925 Default: Source Sans Pro
15926 Font name for parts where monospaced characters are necessary to
15928 align text. Currently, monospaced digits are sufficient.
15929 font_size
15931 Default: 8
15932 Font size used to render text.
15934 font_color
15936 Default: FFFFFF
15937 Font color.
15939 border_size
15941 Default: 0.8
15942 Size of border drawn around the font.
15944 border_color
15946 Default: 262626
15947 Color of drawn border.
15949 alpha Default: 11
15951 Transparency for drawn text.
15953 plot_bg_border_color
15955 Default: 0000FF
15956 Border color used for drawing graphs.
15958 plot_bg_color
15960 Default: 262626
15961 Background color used for drawing graphs.
15963 plot_color
15965 Default: FFFFFF
15966 Color used for drawing graphs.
15968 Note: colors are given as hexadecimal values and use ASS tag order:
15970 BBGGRR (blue green red).
15971 Different key bindings
15973 Additional keys can be configured in input.conf to display the stats:
15974 e script-binding stats/display-stats
15976 E script-binding stats/display-stats-toggle
15977 And to display a certain page directly:
15979 i script-binding stats/display-page-1
15981 e script-binding stats/display-page-2
15982 Active key bindings page
15984 Lists the active key bindings and the commands they're bound to, ex‐
15985 cluding the interactive keys of the stats script itself. See also --in‐
15986 put-test for more detailed view of each binding.
15987 The keys are grouped automatically using a simple analysis of the com‐
15989 mand string, and one should not expect documentation-level grouping ac‐
15990 curacy, however, it should still be reasonably useful.
15991 Using --idle --script-opts=stats-bindlist=yes will print the list to
15993 the terminal and quit immediately. By default long lines are shortened
15994 to 79 chars, and terminal escape sequences are enabled. A different
15995 length limit can be set by changing yes to a number (at least 40), and
15996 escape sequences can be disabled by adding - before the value, e.g.
15997 ...=-yes or ...=-120.
15998 Like with --input-test, the list includes bindings from input.conf and
16000 from user scripts. Use --no-config to list only built-in bindings.
16001 Internal stuff page
16003 Most entries shown on this page have rather vague meaning. Likely none
16004 of this is useful for you. Don't attempt to use it. Forget its exis‐
16005 tence.
16006 Selecting this for the first time will start collecting some internal
16008 performance data. That means performance will be slightly lower than
16009 normal for the rest of the time the player is running (even if the
16010 stats page is closed). Note that the stats page itself uses a lot of
16011 CPU and even GPU resources, and may have a heavy impact on performance.
16012 The displayed information is accumulated over the redraw delay (shown
16014 as poll-time field).
16015 This adds entries for each Lua script. If there are too many scripts
16017 running, parts of the list will simply be out of the screen, but it can
16018 be scrolled.
16019 If the underlying platform does not support pthread per thread times,
16021 the displayed times will be 0 or something random (I suspect that at
16022 time of this writing, only Linux provides the correct via pthread APIs
16023 for per thread times).
16024 Most entries are added lazily and only during data collection, which is
16026 why entries may pop up randomly after some time. It's also why the mem‐
16027 ory usage entries for scripts that have been inactive since the start
16028 of data collection are missing.
16029 Memory usage is approximate and does not reflect internal fragmenta‐
16031 tion.
16032 JS scripts memory reporting is disabled by default because collecting
16034 the data at the JS side has an overhead. It can be enabled by exporting
16035 the env var MPV_LEAK_REPORT=1 before starting mpv, and will increase JS
16036 memory usage.
16037 If entries have /time and /cpu variants, the former gives the real time
16039 (monotonic clock), while the latter the thread CPU time (only if the
16040 corresponding pthread API works and is supported).
16041
16043 The console is a REPL for mpv input commands. It is displayed on the
16044 video window. It also shows log messages. It can be disabled entirely
16045 using the --load-osd-console=no option.
16046 Keybindings
16048 ` Show the console.
16049 ESC Hide the console.
16051 ENTER, Ctrl+J and Ctrl+M
16053 Run the typed command.
16054 Shift+ENTER
16056 Type a literal newline character.
16057 LEFT and Ctrl+B
16059 Move the cursor to the previous character.
16060 RIGHT and Ctrl+F
16062 Move the cursor to the next character.
16063 Ctrl+LEFT and Alt+B
16065 Move the cursor to the beginning of the current word, or if be‐
16066 tween words, to the beginning of the previous word.
16067 Ctrl+RIGHT and Alt+F
16069 Move the cursor to the end of the current word, or if between
16070 words, to the end of the next word.
16071 HOME and Ctrl+A
16073 Move the cursor to the start of the current line.
16074 END and Ctrl+E
16076 Move the cursor to the end of the current line.
16077 BACKSPACE and Ctrl+H
16079 Delete the previous character.
16080 Ctrl+D Hide the console if the current line is empty, otherwise delete
16082 the next character.
16083 Ctrl+BACKSPACE and Ctrl+W
16085 Delete text from the cursor to the beginning of the current
16086 word, or if between words, to the beginning of the previous
16087 word.
16088 Ctrl+DEL and Alt+D
16090 Delete text from the cursor to the end of the current word, or
16091 if between words, to the end of the next word.
16092 Ctrl+U Delete text from the cursor to the beginning of the current
16094 line.
16095 Ctrl+K Delete text from the cursor to the end of the current line.
16097 Ctrl+C Clear the current line.
16099 UP and Ctrl+P
16101 Move back in the command history.
16102 DOWN and Ctrl+N
16104 Move forward in the command history.
16105 PGUP Go to the first command in the history.
16107 PGDN Stop navigating the command history.
16109 INSERT Toggle insert mode.
16111 Ctrl+V Paste text (uses the clipboard on X11 and Wayland).
16113 Shift+INSERT
16115 Paste text (uses the primary selection on X11 and Wayland).
16116 TAB and Ctrl+I
16118 Complete the command or property name at the cursor.
16119 Ctrl+L Clear all log messages from the console.
16121 Commands
16123 script-message-to console type <text> [<cursor_pos>]
16124 Show the console and pre-fill it with the provided text, option‐
16125 ally specifying the initial cursor position as a positive inte‐
16126 ger starting from 1.
16127 Example for input.conf
16129 % script-message-to console type "seek absolute-per‐
16131 cent" 6
16132 Known issues
16134 • Pasting text is slow on Windows
16135 • Non-ASCII keyboard input has restrictions
16137 • The cursor keys move between Unicode code-points, not grapheme clus‐
16139 ters
16140 Configuration
16142 This script can be customized through a config file script-opts/con‐
16143 sole.conf placed in mpv's user directory and through the --script-opts
16144 command-line option. The configuration syntax is described in ON SCREEN
16145 CONTROLLER.
16146 Key bindings can be changed in a standard way, see for example
16148 stats.lua documentation.
16149 Configurable Options
16151 scale Default: 1
16152 All drawing is scaled by this value, including the text borders
16154 and the cursor.
16155 If the VO backend in use has HiDPI scale reporting implemented,
16157 the option value is scaled with the reported HiDPI scale.
16158 font Default: unset (picks a hardcoded font depending on detected
16160 platform)
16161 Set the font used for the REPL and the console. This probably
16163 doesn't have to be a monospaced font.
16164 font_size
16166 Default: 16
16167 Set the font size used for the REPL and the console. This will
16169 be multiplied by "scale".
16170 history_dedup
16172 Default: true
16173 Remove duplicate entries in history as to only keep the latest
16175 one.
16176
16178 mpv can load Lua scripts. (See Script location.)
16179 mpv provides the built-in module mp, which contains functions to send
16181 commands to the mpv core and to retrieve information about playback
16182 state, user settings, file information, and so on.
16183 These scripts can be used to control mpv in a similar way to slave
16185 mode. Technically, the Lua code uses the client API internally.
16186 Example
16188 A script which leaves fullscreen mode when the player is paused:
16189 function on_pause_change(name, value)
16191 if value == true then
16192 mp.set_property("fullscreen", "no")
16193 end
16194 end
16195 mp.observe_property("pause", "bool", on_pause_change)
16196 Script location
16198 Scripts can be passed to the --script option, and are automatically
16199 loaded from the scripts subdirectory of the mpv configuration directory
16200 (usually ~/.config/mpv/scripts/).
16201 A script can be a single file. The file extension is used to select the
16203 scripting backend to use for it. For Lua, it is .lua. If the extension
16204 is not recognized, an error is printed. (If an error happens, the ex‐
16205 tension is either mistyped, or the backend was not compiled into your
16206 mpv binary.)
16207 mpv internally loads the script's name by stripping the .lua extension
16209 and replacing all nonalphanumeric characters with _. E.g., my-tools.lua
16210 becomes my_tools. If there are several scripts with the same name, it
16211 is made unique by appending a number. This is the name returned by
16212 mp.get_script_name().
16213 Entries with .disable extension are always ignored.
16215 If a script is a directory (either if a directory is passed to
16217 --script, or any sub-directories in the script directory, such as for
16218 example ~/.config/mpv/scripts/something/), then the directory repre‐
16219 sents a single script. The player will try to load a file named main.x,
16220 where x is replaced with the file extension. For example, if main.lua
16221 exists, it is loaded with the Lua scripting backend.
16222 You must not put any other files or directories that start with main.
16224 into the script's top level directory. If the script directory contains
16225 for example both main.lua and main.js, only one of them will be loaded
16226 (and which one depends on mpv internals that may change any time).
16227 Likewise, if there is for example main.foo, your script will break as
16228 soon as mpv adds a backend that uses the .foo file extension.
16229 mpv also appends the top level directory of the script to the start of
16231 Lua's package path so you can import scripts from there too. Be aware
16232 that this will shadow Lua libraries that use the same package path.
16233 (Single file scripts do not include mpv specific directory the Lua
16234 package path. This was silently changed in mpv 0.32.0.)
16235 Using a script directory is the recommended way to package a script
16237 that consists of multiple source files, or requires other files (you
16238 can use mp.get_script_directory() to get the location and e.g. load
16239 data files).
16240 Making a script a git repository, basically a repository which contains
16242 a main.lua` file in the root directory, makes scripts easily updateable
16243 (without the dangers of auto-updates). Another suggestion is to use git
16244 submodules to share common files or libraries.
16245 Details on the script initialization and lifecycle
16247 Your script will be loaded by the player at program start from the
16248 scripts configuration subdirectory, or from a path specified with the
16249 --script option. Some scripts are loaded internally (like --osc). Each
16250 script runs in its own thread. Your script is first run "as is", and
16251 once that is done, the event loop is entered. This event loop will dis‐
16252 patch events received by mpv and call your own event handlers which you
16253 have registered with mp.register_event, or timers added with
16254 mp.add_timeout or similar. Note that since the script starts execution
16255 concurrently with player initialization, some properties may not be
16256 populated with meaningful values until the relevant subsystems have
16257 initialized.
16258 When the player quits, all scripts will be asked to terminate. This
16260 happens via a shutdown event, which by default will make the event loop
16261 return. If your script got into an endless loop, mpv will probably be‐
16262 have fine during playback, but it won't terminate when quitting, be‐
16263 cause it's waiting on your script.
16264 Internally, the C code will call the Lua function mp_event_loop after
16266 loading a Lua script. This function is normally defined by the default
16267 prelude loaded before your script (see player/lua/defaults.lua in the
16268 mpv sources). The event loop will wait for events and dispatch events
16269 registered with mp.register_event. It will also handle timers added
16270 with mp.add_timeout and similar (by waiting with a timeout).
16271 Since mpv 0.6.0, the player will wait until the script is fully loaded
16273 before continuing normal operation. The player considers a script as
16274 fully loaded as soon as it starts waiting for mpv events (or it exits).
16275 In practice this means the player will more or less hang until the
16276 script returns from the main chunk (and mp_event_loop is called), or
16277 the script calls mp_event_loop or mp.dispatch_events directly. This is
16278 done to make it possible for a script to fully setup event handlers
16279 etc. before playback actually starts. In older mpv versions, this hap‐
16280 pened asynchronously. With mpv 0.29.0, this changes slightly, and it
16281 merely waits for scripts to be loaded in this manner before starting
16282 playback as part of the player initialization phase. Scripts run though
16283 initialization in parallel. This might change again.
16284 mp functions
16286 The mp module is preloaded, although it can be loaded manually with re‐
16287 quire 'mp'. It provides the core client API.
16288 mp.command(string)
16290 Run the given command. This is similar to the commands used in
16291 input.conf. See List of Input Commands.
16292 By default, this will show something on the OSD (depending on
16294 the command), as if it was used in input.conf. See Input Command
16295 Prefixes how to influence OSD usage per command.
16296 Returns true on success, or nil, error on error.
16298 mp.commandv(arg1, arg2, ...)
16300 Similar to mp.command, but pass each command argument as sepa‐
16301 rate parameter. This has the advantage that you don't have to
16302 care about quoting and escaping in some cases.
16303 Example:
16305 mp.command("loadfile " .. filename .. " append")
16307 mp.commandv("loadfile", filename, "append")
16308 These two commands are equivalent, except that the first version
16310 breaks if the filename contains spaces or certain special char‐
16311 acters.
16312 Note that properties are not expanded. You can use either
16314 mp.command, the expand-properties prefix, or the mp.get_property
16315 family of functions.
16316 Unlike mp.command, this will not use OSD by default either (ex‐
16318 cept for some OSD-specific commands).
16319 mp.command_native(table [,def])
16321 Similar to mp.commandv, but pass the argument list as table.
16322 This has the advantage that in at least some cases, arguments
16323 can be passed as native types. It also allows you to use named
16324 argument.
16325 If the table is an array, each array item is like an argument in
16327 mp.commandv() (but can be a native type instead of a string).
16328 If the table contains string keys, it's interpreted as command
16330 with named arguments. This requires at least an entry with the
16331 key name to be present, which must be a string, and contains the
16332 command name. The special entry _flags is optional, and if
16333 present, must be an array of Input Command Prefixes to apply.
16334 All other entries are interpreted as arguments.
16335 Returns a result table on success (usually empty), or def, error
16337 on error. def is the second parameter provided to the function,
16338 and is nil if it's missing.
16339 mp.command_native_async(table [,fn])
16341 Like mp.command_native(), but the command is ran asynchronously
16342 (as far as possible), and upon completion, fn is called. fn has
16343 three arguments: fn(success, result, error):
16344 success
16346 Always a Boolean and is true if the command was
16347 successful, otherwise false.
16348 result The result value (can be nil) in case of success, nil
16350 otherwise (as returned by mp.command_native()).
16351 error The error string in case of an error, nil otherwise.
16353 Returns a table with undefined contents, which can be used as
16355 argument for mp.abort_async_command.
16356 If starting the command failed for some reason, nil, error is
16358 returned, and fn is called indicating failure, using the same
16359 error value.
16360 fn is always called asynchronously, even if the command failed
16362 to start.
16363 mp.abort_async_command(t)
16365 Abort a mp.command_native_async call. The argument is the return
16366 value of that command (which starts asynchronous execution of
16367 the command). Whether this works and how long it takes depends
16368 on the command and the situation. The abort call itself is asyn‐
16369 chronous. Does not return anything.
16370 mp.get_property(name [,def])
16372 Return the value of the given property as string. These are the
16373 same properties as used in input.conf. See Properties for a list
16374 of properties. The returned string is formatted similar to
16375 ${=name} (see Property Expansion).
16376 Returns the string on success, or def, error on error. def is
16378 the second parameter provided to the function, and is nil if
16379 it's missing.
16380 mp.get_property_osd(name [,def])
16382 Similar to mp.get_property, but return the property value for‐
16383 matted for OSD. This is the same string as printed with ${name}
16384 when used in input.conf.
16385 Returns the string on success, or def, error on error. def is
16387 the second parameter provided to the function, and is an empty
16388 string if it's missing. Unlike get_property(), assigning the re‐
16389 turn value to a variable will always result in a string.
16390 mp.get_property_bool(name [,def])
16392 Similar to mp.get_property, but return the property value as
16393 Boolean.
16394 Returns a Boolean on success, or def, error on error.
16396 mp.get_property_number(name [,def])
16398 Similar to mp.get_property, but return the property value as
16399 number.
16400 Note that while Lua does not distinguish between integers and
16402 floats, mpv internals do. This function simply request a double
16403 float from mpv, and mpv will usually convert integer property
16404 values to float.
16405 Returns a number on success, or def, error on error.
16407 mp.get_property_native(name [,def])
16409 Similar to mp.get_property, but return the property value using
16410 the best Lua type for the property. Most time, this will return
16411 a string, Boolean, or number. Some properties (for example chap‐
16412 ter-list) are returned as tables.
16413 Returns a value on success, or def, error on error. Note that
16415 nil might be a possible, valid value too in some corner cases.
16416 mp.set_property(name, value)
16418 Set the given property to the given string value. See
16419 mp.get_property and Properties for more information about prop‐
16420 erties.
16421 Returns true on success, or nil, error on error.
16423 mp.set_property_bool(name, value)
16425 Similar to mp.set_property, but set the given property to the
16426 given Boolean value.
16427 mp.set_property_number(name, value)
16429 Similar to mp.set_property, but set the given property to the
16430 given numeric value.
16431 Note that while Lua does not distinguish between integers and
16433 floats, mpv internals do. This function will test whether the
16434 number can be represented as integer, and if so, it will pass an
16435 integer value to mpv, otherwise a double float.
16436 mp.set_property_native(name, value)
16438 Similar to mp.set_property, but set the given property using its
16439 native type.
16440 Since there are several data types which cannot represented na‐
16442 tively in Lua, this might not always work as expected. For exam‐
16443 ple, while the Lua wrapper can do some guesswork to decide
16444 whether a Lua table is an array or a map, this would fail with
16445 empty tables. Also, there are not many properties for which it
16446 makes sense to use this, instead of set_property, set_prop‐
16447 erty_bool, set_property_number. For these reasons, this func‐
16448 tion should probably be avoided for now, except for properties
16449 that use tables natively.
16450 mp.get_time()
16452 Return the current mpv internal time in seconds as a number.
16453 This is basically the system time, with an arbitrary offset.
16454 mp.add_key_binding(key, name|fn [,fn [,flags]])
16456 Register callback to be run on a key binding. The binding will
16457 be mapped to the given key, which is a string describing the
16458 physical key. This uses the same key names as in input.conf, and
16459 also allows combinations (e.g. ctrl+a). If the key is empty or
16460 nil, no physical key is registered, but the user still can cre‐
16461 ate own bindings (see below).
16462 After calling this function, key presses will cause the function
16464 fn to be called (unless the user remapped the key with another
16465 binding).
16466 The name argument should be a short symbolic string. It allows
16468 the user to remap the key binding via input.conf using the
16469 script-message command, and the name of the key binding (see be‐
16470 low for an example). The name should be unique across other
16471 bindings in the same script - if not, the previous binding with
16472 the same name will be overwritten. You can omit the name, in
16473 which case a random name is generated internally. (Omitting
16474 works as follows: either pass nil for name, or pass the fn argu‐
16475 ment in place of the name. The latter is not recommended and is
16476 handled for compatibility only.)
16477 The last argument is used for optional flags. This is a table,
16479 which can have the following entries:
16480 repeatable
16482 If set to true, enables key repeat for this specific
16483 binding.
16484 complex
16486 If set to true, then fn is called on both key up and
16487 down events (as well as key repeat, if enabled), with
16488 the first argument being a table. This table has the
16489 following entries (and may contain undocumented ones):
16490 event Set to one of the strings down, repeat, up
16492 or press (the latter if key up/down can't
16493 be tracked).
16494 is_mouse
16496 Boolean Whether the event was caused by a
16497 mouse button.
16498 key_name
16500 The name of they key that triggered this,
16501 or nil if invoked artificially. If the key
16502 name is unknown, it's an empty string.
16503 key_text
16505 Text if triggered by a text key, otherwise
16506 nil. See description of script-binding com‐
16507 mand for details (this field is equivalent
16508 to the 5th argument).
16509 Internally, key bindings are dispatched via the script-mes‐
16511 sage-to or script-binding input commands and mp.regis‐
16512 ter_script_message.
16513 Trying to map multiple commands to a key will essentially prefer
16515 a random binding, while the other bindings are not called. It is
16516 guaranteed that user defined bindings in the central input.conf
16517 are preferred over bindings added with this function (but see
16518 mp.add_forced_key_binding).
16519 Example:
16521 function something_handler()
16523 print("the key was pressed")
16524 end
16525 mp.add_key_binding("x", "something", something_handler)
16526 This will print the message the key was pressed when x was
16528 pressed.
16529 The user can remap these key bindings. Then the user has to put
16531 the following into their input.conf to remap the command to the
16532 y key:
16533 y script-binding something
16535 This will print the message when the key y is pressed. (x will
16537 still work, unless the user remaps it.)
16538 You can also explicitly send a message to a named script only.
16540 Assume the above script was using the filename fooscript.lua:
16541 y script-binding fooscript/something
16543 mp.add_forced_key_binding(...)
16545 This works almost the same as mp.add_key_binding, but registers
16546 the key binding in a way that will overwrite the user's custom
16547 bindings in their input.conf. (mp.add_key_binding overwrites de‐
16548 fault key bindings only, but not those by the user's in‐
16549 put.conf.)
16550 mp.remove_key_binding(name)
16552 Remove a key binding added with mp.add_key_binding or
16553 mp.add_forced_key_binding. Use the same name as you used when
16554 adding the bindings. It's not possible to remove bindings for
16555 which you omitted the name.
16556 mp.register_event(name, fn)
16558 Call a specific function when an event happens. The event name
16559 is a string, and the function fn is a Lua function value.
16560 Some events have associated data. This is put into a Lua table
16562 and passed as argument to fn. The Lua table by default contains
16563 a name field, which is a string containing the event name. If
16564 the event has an error associated, the error field is set to a
16565 string describing the error, on success it's not set.
16566 If multiple functions are registered for the same event, they
16568 are run in registration order, which the first registered func‐
16569 tion running before all the other ones.
16570 Returns true if such an event exists, false otherwise.
16572 See Events and List of events for details.
16574 mp.unregister_event(fn)
16576 Undo mp.register_event(..., fn). This removes all event handlers
16577 that are equal to the fn parameter. This uses normal Lua == com‐
16578 parison, so be careful when dealing with closures.
16579 mp.observe_property(name, type, fn)
16581 Watch a property for changes. If the property name is changed,
16582 then the function fn(name) will be called. type can be nil, or
16583 be set to one of none, native, bool, string, or number. none is
16584 the same as nil. For all other values, the new value of the
16585 property will be passed as second argument to fn, using
16586 mp.get_property_<type> to retrieve it. This means if type is for
16587 example string, fn is roughly called as in fn(name, mp.get_prop‐
16588 erty_string(name)).
16589 If possible, change events are coalesced. If a property is
16591 changed a bunch of times in a row, only the last change triggers
16592 the change function. (The exact behavior depends on timing and
16593 other things.)
16594 If a property is unavailable, or on error, the value argument to
16596 fn is nil. (The observe_property() call always succeeds, even if
16597 a property does not exist.)
16598 In some cases the function is not called even if the property
16600 changes. This depends on the property, and it's a valid feature
16601 request to ask for better update handling of a specific prop‐
16602 erty.
16603 If the type is none or nil, sporadic property change events are
16605 possible. This means the change function fn can be called even
16606 if the property doesn't actually change.
16607 You always get an initial change notification. This is meant to
16609 initialize the user's state to the current value of the prop‐
16610 erty.
16611 mp.unobserve_property(fn)
16613 Undo mp.observe_property(..., fn). This removes all property
16614 handlers that are equal to the fn parameter. This uses normal
16615 Lua == comparison, so be careful when dealing with closures.
16616 mp.add_timeout(seconds, fn)
16618 Call the given function fn when the given number of seconds has
16619 elapsed. Note that the number of seconds can be fractional. For
16620 now, the timer's resolution may be as low as 50 ms, although
16621 this will be improved in the future.
16622 This is a one-shot timer: it will be removed when it's fired.
16624 Returns a timer object. See mp.add_periodic_timer for details.
16626 mp.add_periodic_timer(seconds, fn)
16628 Call the given function periodically. This is like mp.add_time‐
16629 out, but the timer is re-added after the function fn is run.
16630 Returns a timer object. The timer object provides the following
16632 methods:
16633 stop() Disable the timer. Does nothing if the timer is
16635 already disabled. This will remember the current
16636 elapsed time when stopping, so that resume() es‐
16637 sentially unpauses the timer.
16638 kill() Disable the timer. Resets the elapsed time. re‐
16640 sume() will restart the timer.
16641 resume()
16643 Restart the timer. If the timer was disabled with
16644 stop(), this will resume at the time it was
16645 stopped. If the timer was disabled with kill(), or
16646 if it's a previously fired one-shot timer (added
16647 with add_timeout()), this starts the timer from
16648 the beginning, using the initially configured
16649 timeout.
16650 is_enabled()
16652 Whether the timer is currently enabled or was pre‐
16653 viously disabled (e.g. by stop() or kill()).
16654 timeout (RW)
16656 This field contains the current timeout period.
16657 This value is not updated as time progresses. It's
16658 only used to calculate when the timer should fire
16659 next when the timer expires.
16660 If you write this, you can call t:kill() ; t:re‐
16662 sume() to reset the current timeout to the new
16663 one. (t:stop() won't use the new timeout.)
16664 oneshot (RW)
16666 Whether the timer is periodic (false) or fires
16667 just once (true). This value is used when the
16668 timer expires (but before the timer callback func‐
16669 tion fn is run).
16670 Note that these are methods, and you have to call them using :
16672 instead of . (Refer to
16673 https://www.lua.org/manual/5.2/manual.html#3.4.9 .)
16674 Example:
16676 seconds = 0
16678 timer = mp.add_periodic_timer(1, function()
16679 print("called every second")
16680 # stop it after 10 seconds
16681 seconds = seconds + 1
16682 if seconds >= 10 then
16683 timer:kill()
16684 end
16685 end)
16686 mp.get_opt(key)
16688 Return a setting from the --script-opts option. It's up to the
16689 user and the script how this mechanism is used. Currently, all
16690 scripts can access this equally, so you should be careful about
16691 collisions.
16692 mp.get_script_name()
16694 Return the name of the current script. The name is usually made
16695 of the filename of the script, with directory and file extension
16696 removed. If there are several scripts which would have the same
16697 name, it's made unique by appending a number. Any nonalphanu‐
16698 meric characters are replaced with _.
16699 Example
16701 The script /path/to/foo-script.lua becomes foo_script.
16703 mp.get_script_directory()
16705 Return the directory if this is a script packaged as directory
16706 (see Script location for a description). Return nothing if this
16707 is a single file script.
16708 mp.osd_message(text [,duration])
16710 Show an OSD message on the screen. duration is in seconds, and
16711 is optional (uses --osd-duration by default).
16712 Advanced mp functions
16714 These also live in the mp module, but are documented separately as they
16715 are useful only in special situations.
16716 mp.get_wakeup_pipe()
16718 Calls mpv_get_wakeup_pipe() and returns the read end of the
16719 wakeup pipe. This is deprecated, but still works. (See client.h
16720 for details.)
16721 mp.get_next_timeout()
16723 Return the relative time in seconds when the next timer
16724 (mp.add_timeout and similar) expires. If there is no timer, re‐
16725 turn nil.
16726 mp.dispatch_events([allow_wait])
16728 This can be used to run custom event loops. If you want to have
16729 direct control what the Lua script does (instead of being called
16730 by the default event loop), you can set the global variable
16731 mp_event_loop to your own function running the event loop. From
16732 your event loop, you should call mp.dispatch_events() to dequeue
16733 and dispatch mpv events.
16734 If the allow_wait parameter is set to true, the function will
16736 block until the next event is received or the next timer ex‐
16737 pires. Otherwise (and this is the default behavior), it returns
16738 as soon as the event loop is emptied. It's strongly recommended
16739 to use mp.get_next_timeout() and mp.get_wakeup_pipe() if you're
16740 interested in properly working notification of new events and
16741 working timers.
16742 mp.register_idle(fn)
16744 Register an event loop idle handler. Idle handlers are called
16745 before the script goes to sleep after handling all new events.
16746 This can be used for example to delay processing of property
16747 change events: if you're observing multiple properties at once,
16748 you might not want to act on each property change, but only when
16749 all change notifications have been received.
16750 mp.unregister_idle(fn)
16752 Undo mp.register_idle(fn). This removes all idle handlers that
16753 are equal to the fn parameter. This uses normal Lua == compari‐
16754 son, so be careful when dealing with closures.
16755 mp.enable_messages(level)
16757 Set the minimum log level of which mpv message output to re‐
16758 ceive. These messages are normally printed to the terminal. By
16759 calling this function, you can set the minimum log level of mes‐
16760 sages which should be received with the log-message event. See
16761 the description of this event for details. The level is a
16762 string, see msg.log for allowed log levels.
16763 mp.register_script_message(name, fn)
16765 This is a helper to dispatch script-message or script-message-to
16766 invocations to Lua functions. fn is called if script-message or
16767 script-message-to (with this script as destination) is run with
16768 name as first parameter. The other parameters are passed to fn.
16769 If a message with the given name is already registered, it's
16770 overwritten.
16771 Used by mp.add_key_binding, so be careful about name collisions.
16773 mp.unregister_script_message(name)
16775 Undo a previous registration with mp.register_script_message.
16776 Does nothing if the name wasn't registered.
16777 mp.create_osd_overlay(format)
16779 Create an OSD overlay. This is a very thin wrapper around the
16780 osd-overlay command. The function returns a table, which mostly
16781 contains fields that will be passed to osd-overlay. The format
16782 parameter is used to initialize the format field. The data field
16783 contains the text to be used as overlay. For details, see the
16784 osd-overlay command.
16785 In addition, it provides the following methods:
16787 update()
16789 Commit the OSD overlay to the screen, or in other words,
16790 run the osd-overlay command with the current fields of
16791 the overlay table. Returns the result of the osd-overlay
16792 command itself.
16793 remove()
16795 Remove the overlay from the screen. A update() call will
16796 add it again.
16797 Example:
16799 ov = mp.create_osd_overlay("ass-events")
16801 ov.data = "{\\an5}{\\b1}hello world!"
16802 ov:update()
16803 The advantage of using this wrapper (as opposed to running
16805 osd-overlay directly) is that the id field is allocated automat‐
16806 ically.
16807 mp.get_osd_size()
16809 Returns a tuple of osd_width, osd_height, osd_par. The first two
16810 give the size of the OSD in pixels (for video outputs like
16811 --vo=xv, this may be "scaled" pixels). The third is the display
16812 pixel aspect ratio.
16813 May return invalid/nonsense values if OSD is not initialized
16815 yet.
16816 mp.msg functions
16818 This module allows outputting messages to the terminal, and can be
16819 loaded with require 'mp.msg'.
16820 msg.log(level, ...)
16822 The level parameter is the message priority. It's a string and
16823 one of fatal, error, warn, info, v, debug, trace. The user's
16824 settings will determine which of these messages will be visible.
16825 Normally, all messages are visible, except v, debug and trace.
16826 The parameters after that are all converted to strings. Spaces
16828 are inserted to separate multiple parameters.
16829 You don't need to add newlines.
16831 msg.fatal(...), msg.error(...), msg.warn(...), msg.info(...), msg.ver‐
16833 bose(...), msg.debug(...), msg.trace(...)
16834 All of these are shortcuts and equivalent to the corresponding
16835 msg.log(level, ...) call.
16836 mp.options functions
16838 mpv comes with a built-in module to manage options from config-files
16839 and the command-line. All you have to do is to supply a table with de‐
16840 fault options to the read_options function. The function will overwrite
16841 the default values with values found in the config-file and the com‐
16842 mand-line (in that order).
16843 options.read_options(table [, identifier [, on_update]])
16845 A table with key-value pairs. The type of the default values is
16846 important for converting the values read from the config file or
16847 command-line back. Do not use nil as a default value!
16848 The identifier is used to identify the config-file and the com‐
16850 mand-line options. These needs to unique to avoid collisions
16851 with other scripts. Defaults to mp.get_script_name() if the pa‐
16852 rameter is nil or missing.
16853 The on_update parameter enables run-time updates of all matching
16855 option values via the script-opts option/property. If any of the
16856 matching options changes, the values in the table (which was
16857 originally passed to the function) are changed, and on_up‐
16858 date(list) is called. list is a table where each updated option
16859 has a list[option_name] = true entry. There is no initial
16860 on_update() call. This never re-reads the config file.
16861 script-opts is always applied on the original config file, ig‐
16862 noring previous script-opts values (for example, if an option is
16863 removed from script-opts at runtime, the option will have the
16864 value in the config file). table entries are only written for
16865 option values whose values effectively change (this is important
16866 if the script changes table entries independently).
16867 Example implementation:
16869 require 'mp.options'
16871 local options = {
16872 optionA = "defaultvalueA",
16873 optionB = -0.5,
16874 optionC = true,
16875 }
16876 read_options(options, "myscript")
16877 print(options.optionA)
16878 The config file will be stored in script-opts/identifier.conf in mpv's
16880 user folder. Comment lines can be started with # and stray spaces are
16881 not removed. Boolean values will be represented with yes/no.
16882 Example config:
16884 # comment
16886 optionA=Hello World
16887 optionB=9999
16888 optionC=no
16889 Command-line options are read from the --script-opts parameter. To
16891 avoid collisions, all keys have to be prefixed with identifier-.
16892 Example command-line:
16894 --script-opts=myscript-optionA=TEST,myscript-optionB=0,myscript-optionC=yes
16896 mp.utils functions
16898 This built-in module provides generic helper functions for Lua, and
16899 have strictly speaking nothing to do with mpv or video/audio playback.
16900 They are provided for convenience. Most compensate for Lua's scarce
16901 standard library.
16902 Be warned that any of these functions might disappear any time. They
16904 are not strictly part of the guaranteed API.
16905 utils.getcwd()
16907 Returns the directory that mpv was launched from. On error, nil,
16908 error is returned.
16909 utils.readdir(path [, filter])
16911 Enumerate all entries at the given path on the filesystem, and
16912 return them as array. Each entry is a directory entry (without
16913 the path). The list is unsorted (in whatever order the operat‐
16914 ing system returns it).
16915 If the filter argument is given, it must be one of the following
16917 strings:
16918 files List regular files only. This excludes directories,
16920 special files (like UNIX device files or FIFOs), and
16921 dead symlinks. It includes UNIX symlinks to regular
16922 files.
16923 dirs List directories only, or symlinks to directories. .
16925 and .. are not included.
16926 normal Include the results of both files and dirs. (This is
16928 the default.)
16929 all List all entries, even device files, dead symlinks,
16931 FIFOs, and the . and .. entries.
16932 On error, nil, error is returned.
16934 utils.file_info(path)
16936 Stats the given path for information and returns a table with
16937 the following entries:
16938 mode protection bits (on Windows, always 755 (octal) for
16940 directories and 644 (octal) for files)
16941 size size in bytes
16943 atime time of last access
16945 mtime time of last modification
16947 ctime time of last metadata change
16949 is_file
16951 Whether path is a regular file (boolean)
16952 is_dir Whether path is a directory (boolean)
16954 mode and size are integers. Timestamps (atime, mtime and ctime)
16956 are integer seconds since the Unix epoch (Unix time). The bool‐
16957 eans is_file and is_dir are provided as a convenience; they can
16958 be and are derived from mode.
16959 On error (e.g. path does not exist), nil, error is returned.
16961 utils.split_path(path)
16963 Split a path into directory component and filename component,
16964 and return them. The first return value is always the directory.
16965 The second return value is the trailing part of the path, the
16966 directory entry.
16967 utils.join_path(p1, p2)
16969 Return the concatenation of the 2 paths. Tries to be clever. For
16970 example, if p2 is an absolute path, p2 is returned without
16971 change.
16972 utils.subprocess(t)
16974 Runs an external process and waits until it exits. Returns
16975 process status and the captured output. This is a legacy wrapper
16976 around calling the subprocess command with mp.command_native. It
16977 does the following things:
16978 • copy the table t
16980 • rename cancellable field to playback_only
16982 • rename max_size to capture_size
16984 • set capture_stdout field to true if unset
16986 • set name field to subprocess
16988 • call mp.command_native(copied_t)
16990 • if the command failed, create a dummy result table
16992 • copy error_string to error field if the string is non-empty
16994 • return the result table
16996 It is recommended to use mp.command_native or mp.command_na‐
16998 tive_async directly, instead of calling this legacy wrapper. It
16999 is for compatibility only.
17000 See the subprocess documentation for semantics and further pa‐
17002 rameters.
17003 utils.subprocess_detached(t)
17005 Runs an external process and detaches it from mpv's control.
17006 The parameter t is a table. The function reads the following en‐
17008 tries:
17009 args Array of strings of the same semantics as the args
17011 used in the subprocess function.
17012 The function returns nil.
17014 This is a legacy wrapper around calling the run command with
17016 mp.commandv and other functions.
17017 utils.getpid()
17019 Returns the process ID of the running mpv process. This can be
17020 used to identify the calling mpv when launching (detached) sub‐
17021 processes.
17022 utils.get_env_list()
17024 Returns the C environment as a list of strings. (Do not confuse
17025 this with the Lua "environment", which is an unrelated concept.)
17026 utils.parse_json(str [, trail])
17028 Parses the given string argument as JSON, and returns it as a
17029 Lua table. On error, returns nil, error. (Currently, error is
17030 just a string reading error, because there is no fine-grained
17031 error reporting of any kind.)
17032 The returned value uses similar conventions as mp.get_prop‐
17034 erty_native() to distinguish empty objects and arrays.
17035 If the trail parameter is true (or any value equal to true),
17037 then trailing non-whitespace text is tolerated by the function,
17038 and the trailing text is returned as 3rd return value. (The 3rd
17039 return value is always there, but with trail set, no error is
17040 raised.)
17041 utils.format_json(v)
17043 Format the given Lua table (or value) as a JSON string and re‐
17044 turn it. On error, returns nil, error. (Errors usually only hap‐
17045 pen on value types incompatible with JSON.)
17046 The argument value uses similar conventions as mp.set_prop‐
17048 erty_native() to distinguish empty objects and arrays.
17049 utils.to_string(v)
17051 Turn the given value into a string. Formats tables and their
17052 contents. This doesn't do anything special; it is only needed
17053 because Lua is terrible.
17054 Events
17056 Events are notifications from player core to scripts. You can register
17057 an event handler with mp.register_event.
17058 Note that all scripts (and other parts of the player) receive events
17060 equally, and there's no such thing as blocking other scripts from re‐
17061 ceiving events.
17062 Example:
17064 function my_fn(event)
17066 print("start of playback!")
17067 end
17068 mp.register_event("file-loaded", my_fn)
17070 For the existing event types, see List of events.
17072 Extras
17074 This documents experimental features, or features that are "too spe‐
17075 cial" to guarantee a stable interface.
17076 mp.add_hook(type, priority, fn)
17078 Add a hook callback for type (a string identifying a certain
17079 kind of hook). These hooks allow the player to call script func‐
17080 tions and wait for their result (normally, the Lua scripting in‐
17081 terface is asynchronous from the point of view of the player
17082 core). priority is an arbitrary integer that allows ordering
17083 among hooks of the same kind. Using the value 50 is recommended
17084 as neutral default value.
17085 fn(hook) is the function that will be called during execution of
17087 the hook. The parameter passed to it (hook) is a Lua object that
17088 can control further aspects about the currently invoked hook. It
17089 provides the following methods:
17090 defer()
17092 Returning from the hook function should not automati‐
17093 cally continue the hook. Instead, the API user wants
17094 to call hook:cont() on its own at a later point in
17095 time (before or after the function has returned).
17096 cont() Continue the hook. Doesn't need to be called unless
17098 defer() was called.
17099 See Hooks for currently existing hooks and what they do - only
17101 the hook list is interesting; handling hook execution is done by
17102 the Lua script function automatically.
17103
17105 JavaScript support in mpv is near identical to its Lua support. Use
17106 this section as reference on differences and availability of APIs, but
17107 otherwise you should refer to the Lua documentation for API details and
17108 general scripting in mpv.
17109 Example
17111 JavaScript code which leaves fullscreen mode when the player is paused:
17112 function on_pause_change(name, value) {
17114 if (value == true)
17115 mp.set_property("fullscreen", "no");
17116 }
17117 mp.observe_property("pause", "bool", on_pause_change);
17118 Similarities with Lua
17120 mpv tries to load a script file as JavaScript if it has a .js exten‐
17121 sion, but otherwise, the documented Lua options, script directories,
17122 loading, etc apply to JavaScript files too.
17123 Script initialization and lifecycle is the same as with Lua, and most
17125 of the Lua functions at the modules mp, mp.utils, mp.msg and mp.options
17126 are available to JavaScript with identical APIs - including running
17127 commands, getting/setting properties, registering events/key-bind‐
17128 ings/hooks, etc.
17129 Differences from Lua
17131 No need to load modules. mp, mp.utils, mp.msg and mp.options are pre‐
17132 loaded, and you can use e.g. var cwd = mp.utils.getcwd(); without prior
17133 setup.
17134 Errors are slightly different. Where the Lua APIs return nil for error,
17136 the JavaScript ones return undefined. Where Lua returns something, er‐
17137 ror JavaScript returns only something - and makes error available via
17138 mp.last_error(). Note that only some of the functions have this addi‐
17139 tional error value - typically the same ones which have it in Lua.
17140 Standard APIs are preferred. For instance setTimeout and JSON.stringify
17142 are available, but mp.add_timeout and mp.utils.format_json are not.
17143 No standard library. This means that interaction with anything outside
17145 of mpv is limited to the available APIs, typically via mp.utils. How‐
17146 ever, some file functions were added, and CommonJS require is available
17147 too - where the loaded modules have the same privileges as normal
17148 scripts.
17149 Language features - ECMAScript 5
17151 The scripting backend which mpv currently uses is MuJS - a compatible
17152 minimal ES5 interpreter. As such, String.substring is implemented for
17153 instance, while the common but non-standard String.substr is not.
17154 Please consult the MuJS pages on language features and platform support
17155 - https://mujs.com .
17156 Unsupported Lua APIs and their JS alternatives
17158 mp.add_timeout(seconds, fn) JS: id = setTimeout(fn, ms)
17159 mp.add_periodic_timer(seconds, fn) JS: id = setInterval(fn, ms)
17161 utils.parse_json(str [, trail]) JS: JSON.parse(str)
17163 utils.format_json(v) JS: JSON.stringify(v)
17165 utils.to_string(v) see dump below.
17167 mp.get_next_timeout() see event loop below.
17169 mp.dispatch_events([allow_wait]) see event loop below.
17171 Scripting APIs - identical to Lua
17173 (LE) - Last-Error, indicates that mp.last_error() can be used after the
17174 call to test for success (empty string) or failure (non empty reason
17175 string). Where the Lua APIs use nil to indicate error, JS APIs use un‐
17176 defined.
17177 mp.command(string) (LE)
17179 mp.commandv(arg1, arg2, ...) (LE)
17181 mp.command_native(table [,def]) (LE)
17183 id = mp.command_native_async(table [,fn]) (LE) Notes: id is true-thy on
17185 success, error is empty string on success.
17186 mp.abort_async_command(id)
17188 mp.get_property(name [,def]) (LE)
17190 mp.get_property_osd(name [,def]) (LE)
17192 mp.get_property_bool(name [,def]) (LE)
17194 mp.get_property_number(name [,def]) (LE)
17196 mp.get_property_native(name [,def]) (LE)
17198 mp.set_property(name, value) (LE)
17200 mp.set_property_bool(name, value) (LE)
17202 mp.set_property_number(name, value) (LE)
17204 mp.set_property_native(name, value) (LE)
17206 mp.get_time()
17208 mp.add_key_binding(key, name|fn [,fn [,flags]])
17210 mp.add_forced_key_binding(...)
17212 mp.remove_key_binding(name)
17214 mp.register_event(name, fn)
17216 mp.unregister_event(fn)
17218 mp.observe_property(name, type, fn)
17220 mp.unobserve_property(fn)
17222 mp.get_opt(key)
17224 mp.get_script_name()
17226 mp.get_script_directory()
17228 mp.osd_message(text [,duration])
17230 mp.get_wakeup_pipe()
17232 mp.register_idle(fn)
17234 mp.unregister_idle(fn)
17236 mp.enable_messages(level)
17238 mp.register_script_message(name, fn)
17240 mp.unregister_script_message(name)
17242 mp.create_osd_overlay(format)
17244 mp.get_osd_size() (returned object has properties: width, height, as‐
17246 pect)
17247 mp.msg.log(level, ...)
17249 mp.msg.fatal(...)
17251 mp.msg.error(...)
17253 mp.msg.warn(...)
17255 mp.msg.info(...)
17257 mp.msg.verbose(...)
17259 mp.msg.debug(...)
17261 mp.msg.trace(...)
17263 mp.utils.getcwd() (LE)
17265 mp.utils.readdir(path [, filter]) (LE)
17267 mp.utils.file_info(path) (LE) Note: like lua - this does NOT expand
17269 meta-paths like ~~/foo (other JS file functions do expand meta paths).
17270 mp.utils.split_path(path)
17272 mp.utils.join_path(p1, p2)
17274 mp.utils.subprocess(t)
17276 mp.utils.subprocess_detached(t)
17278 mp.utils.get_env_list()
17280 mp.utils.getpid() (LE)
17282 mp.add_hook(type, priority, fn(hook))
17284 mp.options.read_options(obj [, identifier [, on_update]]) (types:
17286 string/boolean/number)
17287 Additional utilities
17289 mp.last_error()
17290 If used after an API call which updates last error, returns an
17291 empty string if the API call succeeded, or a non-empty error
17292 reason string otherwise.
17293 Error.stack (string)
17295 When using try { ... } catch(e) { ... }, then e.stack is the
17296 stack trace of the error - if it was created using the Er‐
17297 ror(...) constructor.
17298 print (global)
17300 A convenient alias to mp.msg.info.
17301 dump (global)
17303 Like print but also expands objects and arrays recursively.
17304 mp.utils.getenv(name)
17306 Returns the value of the host environment variable name, or un‐
17307 defined if the variable is not defined.
17308 mp.utils.get_user_path(path)
17310 Trivial wrapper of the expand-path mpv command, returns a
17311 string. read_file, write_file, append_file and require already
17312 expand the path internally and accept mpv meta-paths like
17313 ~~desktop/foo.
17314 mp.utils.read_file(fname [,max])
17316 Returns the content of file fname as string. If max is provided
17317 and not negative, limit the read to max bytes.
17318 mp.utils.write_file(fname, str)
17320 (Over)write file fname with text content str. fname must be pre‐
17321 fixed with file:// as simple protection against accidental argu‐
17322 ments switch, e.g. mp.utils.write_file("file://~/abc.txt",
17323 "hello world").
17324 mp.utils.append_file(fname, str)
17326 Same as mp.utils.write_file if the file fname does not exist. If
17327 it does exist then append instead of overwrite.
17328 Note: read_file, write_file and append_file throw on errors, allow text
17330 content only.
17331 mp.get_time_ms()
17333 Same as mp.get_time() but in ms instead of seconds.
17334 mp.get_script_file()
17336 Returns the file name of the current script.
17337 exit() (global)
17339 Make the script exit at the end of the current event loop itera‐
17340 tion. Note: please remove added key bindings before calling
17341 exit().
17342 mp.utils.compile_js(fname, content_str)
17344 Compiles the JS code content_str as file name fname (without
17345 loading anything from the filesystem), and returns it as a func‐
17346 tion. Very similar to a Function constructor, but shows at stack
17347 traces as fname.
17348 mp.module_paths
17350 Global modules search paths array for the require function (see
17351 below).
17352 Timers (global)
17354 The standard HTML/node.js timers are available:
17355 id = setTimeout(fn [,duration [,arg1 [,arg2...]]])
17357 id = setTimeout(code_string [,duration])
17359 clearTimeout(id)
17361 id = setInterval(fn [,duration [,arg1 [,arg2...]]])
17363 id = setInterval(code_string [,duration])
17365 clearInterval(id)
17367 setTimeout and setInterval return id, and later call fn (or execute
17369 code_string) after duration ms. Interval also repeat every duration.
17370 duration has a minimum and default value of 0, code_string is a plain
17372 string which is evaluated as JS code, and [,arg1 [,arg2..]] are used as
17373 arguments (if provided) when calling back fn.
17374 The clear...(id) functions cancel timer id, and are irreversible.
17376 Note: timers always call back asynchronously, e.g. setTimeout(fn) will
17378 never call fn before returning. fn will be called either at the end of
17379 this event loop iteration or at a later event loop iteration. This is
17380 true also for intervals - which also never call back twice at the same
17381 event loop iteration.
17382 Additionally, timers are processed after the event queue is empty, so
17384 it's valid to use setTimeout(fn) as a one-time idle observer.
17385 CommonJS modules and require(id)
17387 CommonJS Modules are a standard system where scripts can export common
17388 functions for use by other scripts. Specifically, a module is a script
17389 which adds properties (functions, etc) to its pre-existing exports ob‐
17390 ject, which another script can access with require(module-id). This
17391 runs the module and returns its exports object. Further calls to re‐
17392 quire for the same module will return its cached exports object without
17393 running the module again.
17394 Modules and require are supported, standard compliant, and generally
17396 similar to node.js. However, most node.js modules won't run due to
17397 missing modules such as fs, process, etc, but some node.js modules with
17398 minimal dependencies do work. In general, this is for mpv modules and
17399 not a node.js replacement.
17400 A .js file extension is always added to id, e.g. require("./foo") will
17402 load the file ./foo.js and return its exports object.
17403 An id which starts with ./ or ../ is relative to the script or module
17405 which require it. Otherwise it's considered a top-level id (CommonJS
17406 term).
17407 Top-level id is evaluated as absolute filesystem path if possible, e.g.
17409 /x/y or ~/x. Otherwise it's considered a global module id and searched
17410 according to mp.module_paths in normal array order, e.g. require("x")
17411 tries to load x.js at one of the array paths, and id foo/x tries to
17412 load x.js inside dir foo at one of the paths.
17413 The mp.module_paths array is empty by default except for scripts which
17415 are loaded as a directory where it contains one item - <directory>/mod‐
17416 ules/ . The array may be updated from a script (or using custom init -
17417 see below) which will affect future calls to require for global module
17418 id's which are not already loaded/cached.
17419 No global variable, but a module's this at its top lexical scope is the
17421 global object - also in strict mode. If you have a module which needs
17422 global as the global object, you could do this.global = this; before
17423 require.
17424 Functions and variables declared at a module don't pollute the global
17426 object.
17427 Custom initialization
17429 After mpv initializes the JavaScript environment for a script but be‐
17430 fore it loads the script - it tries to run the file init.js at the root
17431 of the mpv configuration directory. Code at this file can update the
17432 environment further for all scripts. E.g. if it contains mp.mod‐
17433 ule_paths.push("/foo") then require at all scripts will search global
17434 module id's also at /foo (do NOT do mp.module_paths = ["/foo"]; because
17435 this will remove existing paths - like <script-dir>/modules for scripts
17436 which load from a directory).
17437 The custom-init file is ignored if mpv is invoked with --no-config.
17439 Before mpv 0.34, the file name was .init.js (with dot) at the same dir.
17441 The event loop
17443 The event loop poll/dispatch mpv events as long as the queue is not
17444 empty, then processes the timers, then waits for the next event, and
17445 repeats this forever.
17446 You could put this code at your script to replace the built-in event
17448 loop, and also print every event which mpv sends to your script:
17449 function mp_event_loop() {
17451 var wait = 0;
17452 do {
17453 var e = mp.wait_event(wait);
17454 dump(e); // there could be a lot of prints...
17455 if (e.event != "none") {
17456 mp.dispatch_event(e);
17457 wait = 0;
17458 } else {
17459 wait = mp.process_timers() / 1000;
17460 if (wait != 0) {
17461 mp.notify_idle_observers();
17462 wait = mp.peek_timers_wait() / 1000;
17463 }
17464 }
17465 } while (mp.keep_running);
17466 }
17467 mp_event_loop is a name which mpv tries to call after the script loads.
17469 The internal implementation is similar to this (without dump though..).
17470 e = mp.wait_event(wait) returns when the next mpv event arrives, or af‐
17472 ter wait seconds if positive and no mpv events arrived. wait value of 0
17473 returns immediately (with e.event == "none" if the queue is empty).
17474 mp.dispatch_event(e) calls back the handlers registered for e.event, if
17476 there are such (event handlers, property observers, script messages,
17477 etc).
17478 mp.process_timers() calls back the already-added, non-canceled due
17480 timers, and returns the duration in ms till the next due timer (possi‐
17481 bly 0), or -1 if there are no pending timers. Must not be called recur‐
17482 sively.
17483 mp.notify_idle_observers() calls back the idle observers, which we do
17485 when we're about to sleep (wait != 0), but the observers may add timers
17486 or take non-negligible duration to complete, so we re-calculate wait
17487 afterwards.
17488 mp.peek_timers_wait() returns the same values as mp.process_timers()
17490 but without doing anything. Invalid result if called from a timer call‐
17491 back.
17492 Note: exit() is also registered for the shutdown event, and its imple‐
17494 mentation is a simple mp.keep_running = false.
17495
17497 mpv can be controlled by external programs using the JSON-based IPC
17498 protocol. It can be enabled by specifying the path to a unix socket or
17499 a named pipe using the option --input-ipc-server. Clients can connect
17500 to this socket and send commands to the player or receive events from
17501 it.
17502 WARNING:
17504 This is not intended to be a secure network protocol. It is explic‐
17505 itly insecure: there is no authentication, no encryption, and the
17506 commands themselves are insecure too. For example, the run command
17507 is exposed, which can run arbitrary system commands. The use-case is
17508 controlling the player locally. This is not different from the
17509 MPlayer slave protocol.
17510 Socat example
17512 You can use the socat tool to send commands (and receive replies) from
17513 the shell. Assuming mpv was started with:
17514 mpv file.mkv --input-ipc-server=/tmp/mpvsocket
17516 Then you can control it using socat:
17518 > echo '{ "command": ["get_property", "playback-time"] }' | socat - /tmp/mpvsocket
17520 {"data":190.482000,"error":"success"}
17521 In this case, socat copies data between stdin/stdout and the mpv socket
17523 connection.
17524 See the --idle option how to make mpv start without exiting immediately
17526 or playing a file.
17527 It's also possible to send input.conf style text-only commands:
17529 > echo 'show-text ${playback-time}' | socat - /tmp/mpvsocket
17531 But you won't get a reply over the socket. (This particular command
17533 shows the playback time on the player's OSD.)
17534 Command Prompt example
17536 Unfortunately, it's not as easy to test the IPC protocol on Windows,
17537 since Windows ports of socat (in Cygwin and MSYS2) don't understand
17538 named pipes. In the absence of a simple tool to send and receive from
17539 bidirectional pipes, the echo command can be used to send commands, but
17540 not receive replies from the command prompt.
17541 Assuming mpv was started with:
17543 mpv file.mkv --input-ipc-server=\\.\pipe\mpvsocket
17545 You can send commands from a command prompt:
17547 echo show-text ${playback-time} >\\.\pipe\mpvsocket
17549 To be able to simultaneously read and write from the IPC pipe, like on
17551 Linux, it's necessary to write an external program that uses overlapped
17552 file I/O (or some wrapper like .NET's NamedPipeClientStream.)
17553 You can open the pipe in PuTTY as "serial" device. This is not very
17555 comfortable, but gives a way to test interactively without having to
17556 write code.
17557 Protocol
17559 The protocol uses UTF-8-only JSON as defined by RFC-8259. Unlike stan‐
17560 dard JSON, "u" escape sequences are not allowed to construct surrogate
17561 pairs. To avoid getting conflicts, encode all text characters including
17562 and above codepoint U+0020 as UTF-8. mpv might output broken UTF-8 in
17563 corner cases (see "UTF-8" section below).
17564 Clients can execute commands on the player by sending JSON messages of
17566 the following form:
17567 { "command": ["command_name", "param1", "param2", ...] }
17569 where command_name is the name of the command to be executed, followed
17571 by a list of parameters. Parameters must be formatted as native JSON
17572 values (integers, strings, booleans, ...). Every message must be termi‐
17573 nated with \n. Additionally, \n must not appear anywhere inside the
17574 message. In practice this means that messages should be minified before
17575 being sent to mpv.
17576 mpv will then send back a reply indicating whether the command was run
17578 correctly, and an additional field holding the command-specific return
17579 data (it can also be null).
17580 { "error": "success", "data": null }
17582 mpv will also send events to clients with JSON messages of the follow‐
17584 ing form:
17585 { "event": "event_name" }
17587 where event_name is the name of the event. Additional event-specific
17589 fields can also be present. See List of events for a list of all sup‐
17590 ported events.
17591 Because events can occur at any time, it may be difficult at times to
17593 determine which response goes with which command. Commands may option‐
17594 ally include a request_id which, if provided in the command request,
17595 will be copied verbatim into the response. mpv does not interpret the
17596 request_id in any way; it is solely for the use of the requester. The
17597 only requirement is that the request_id field must be an integer (a
17598 number without fractional parts in the range -2^63..2^63-1). Using
17599 other types is deprecated and will currently show a warning. In the fu‐
17600 ture, this will raise an error.
17601 For example, this request:
17603 { "command": ["get_property", "time-pos"], "request_id": 100 }
17605 Would generate this response:
17607 { "error": "success", "data": 1.468135, "request_id": 100 }
17609 If you don't specify a request_id, command replies will set it to 0.
17611 All commands, replies, and events are separated from each other with a
17613 line break character (\n).
17614 If the first character (after skipping whitespace) is not {, the com‐
17616 mand will be interpreted as non-JSON text command, as they are used in
17617 input.conf (or mpv_command_string() in the client API). Additionally,
17618 lines starting with # and empty lines are ignored.
17619 Currently, embedded 0 bytes terminate the current line, but you should
17621 not rely on this.
17622 Data flow
17624 Currently, the mpv-side IPC implementation does not service the socket
17625 while a command is executed and the reply is written. It is for example
17626 not possible that other events, that happened during the execution of
17627 the command, are written to the socket before the reply is written.
17628 This might change in the future. The only guarantee is that replies to
17630 IPC messages are sent in sequence.
17631 Also, since socket I/O is inherently asynchronous, it is possible that
17633 you read unrelated event messages from the socket, before you read the
17634 reply to the previous command you sent. In this case, these events were
17635 queued by the mpv side before it read and started processing your com‐
17636 mand message.
17637 If the mpv-side IPC implementation switches away from blocking writes
17639 and blocking command execution, it may attempt to send events at any
17640 time.
17641 You can also use asynchronous commands, which can return in any order,
17643 and which do not block IPC protocol interaction at all while the com‐
17644 mand is executed in the background.
17645 Asynchronous commands
17647 Command can be run asynchronously. This behaves exactly as with normal
17648 command execution, except that execution is not blocking. Other com‐
17649 mands can be sent while it's executing, and command completion can be
17650 arbitrarily reordered.
17651 The async field controls this. If present, it must be a boolean. If
17653 missing, false is assumed.
17654 For example, this initiates an asynchronous command:
17656 { "command": ["screenshot"], "request_id": 123, "async": true }
17658 And this is the completion:
17660 {"request_id":123,"error":"success","data":null}
17662 By design, you will not get a confirmation that the command was
17664 started. If a command is long running, sending the message will lead to
17665 any reply until much later when the command finishes.
17666 Some commands execute synchronously, but these will behave like asyn‐
17668 chronous commands that finished execution immediately.
17669 Cancellation of asynchronous commands is available in the libmpv API,
17671 but has not yet been implemented in the IPC protocol.
17672 Commands with named arguments
17674 If the command field is a JSON object, named arguments are expected.
17675 This is described in the C API mpv_command_node() documentation (the
17676 MPV_FORMAT_NODE_MAP case). In some cases, this may make commands more
17677 readable, while some obscure commands basically require using named ar‐
17678 guments.
17679 Currently, only "proper" commands (as listed by List of Input Commands)
17681 support named arguments.
17682 Commands
17684 In addition to the commands described in List of Input Commands, a few
17685 extra commands can also be used as part of the protocol:
17686 client_name
17688 Return the name of the client as string. This is the string
17689 ipc-N with N being an integer number.
17690 get_time_us
17692 Return the current mpv internal time in microseconds as a num‐
17693 ber. This is basically the system time, with an arbitrary off‐
17694 set.
17695 get_property
17697 Return the value of the given property. The value will be sent
17698 in the data field of the replay message.
17699 Example:
17701 { "command": ["get_property", "volume"] }
17703 { "data": 50.0, "error": "success" }
17704 get_property_string
17706 Like get_property, but the resulting data will always be a
17707 string.
17708 Example:
17710 { "command": ["get_property_string", "volume"] }
17712 { "data": "50.000000", "error": "success" }
17713 set_property
17715 Set the given property to the given value. See Properties for
17716 more information about properties.
17717 Example:
17719 { "command": ["set_property", "pause", true] }
17721 { "error": "success" }
17722 set_property_string
17724 Alias for set_property. Both commands accept native values and
17725 strings.
17726 observe_property
17728 Watch a property for changes. If the given property is changed,
17729 then an event of type property-change will be generated
17730 Example:
17732 { "command": ["observe_property", 1, "volume"] }
17734 { "error": "success" }
17735 { "event": "property-change", "id": 1, "data": 52.0, "name": "volume" }
17736 WARNING:
17738 If the connection is closed, the IPC client is destroyed in‐
17739 ternally, and the observed properties are unregistered. This
17740 happens for example when sending commands to a socket with
17741 separate socat invocations. This can make it seem like prop‐
17742 erty observation does not work. You must keep the IPC connec‐
17743 tion open to make it work.
17744 observe_property_string
17746 Like observe_property, but the resulting data will always be a
17747 string.
17748 Example:
17750 { "command": ["observe_property_string", 1, "volume"] }
17752 { "error": "success" }
17753 { "event": "property-change", "id": 1, "data": "52.000000", "name": "volume" }
17754 unobserve_property
17756 Undo observe_property or observe_property_string. This requires
17757 the numeric id passed to the observed command as argument.
17758 Example:
17760 { "command": ["unobserve_property", 1] }
17762 { "error": "success" }
17763 request_log_messages
17765 Enable output of mpv log messages. They will be received as
17766 events. The parameter to this command is the log-level (see
17767 mpv_request_log_messages C API function).
17768 Log message output is meant for humans only (mostly for debug‐
17770 ging). Attempting to retrieve information by parsing these mes‐
17771 sages will just lead to breakages with future mpv releases. In‐
17772 stead, make a feature request, and ask for a proper event that
17773 returns the information you need.
17774 enable_event, disable_event
17776 Enables or disables the named event. Mirrors the mpv_re‐
17777 quest_event C API function. If the string all is used instead of
17778 an event name, all events are enabled or disabled.
17779 By default, most events are enabled, and there is not much use
17781 for this command.
17782 get_version
17784 Returns the client API version the C API of the remote mpv in‐
17785 stance provides.
17786 See also: DOCS/client-api-changes.rst.
17788 UTF-8
17790 Normally, all strings are in UTF-8. Sometimes it can happen that
17791 strings are in some broken encoding (often happens with file tags and
17792 such, and filenames on many Unixes are not required to be in UTF-8 ei‐
17793 ther). This means that mpv sometimes sends invalid JSON. If that is a
17794 problem for the client application's parser, it should filter the raw
17795 data for invalid UTF-8 sequences and perform the desired replacement,
17796 before feeding the data to its JSON parser.
17797 mpv will not attempt to construct invalid UTF-8 with broken "u" escape
17799 sequences. This includes surrogate pairs.
17800 JSON extensions
17802 The following non-standard extensions are supported:
17803 • a list or object item can have a trailing ","
17805 • object syntax accepts "=" in addition of ":"
17807 • object keys can be unquoted, if they start with a character in
17809 "A-Za-z_" and contain only characters in "A-Za-z0-9_"
17810 • byte escapes with "xAB" are allowed (with AB being a 2 digit hex
17812 number)
17813 Example:
17815 { objkey = "value\x0A" }
17817 Is equivalent to:
17819 { "objkey": "value\n" }
17821 Alternative ways of starting clients
17823 You can create an anonymous IPC connection without having to set --in‐
17824 put-ipc-server. This is achieved through a mpv pseudo scripting backend
17825 that starts processes.
17826 You can put .run file extension in the mpv scripts directory in its
17828 config directory (see the FILES section for details), or load them
17829 through other means (see Script location). These scripts are simply ex‐
17830 ecuted with the OS native mechanism (as if you ran them in the shell).
17831 They must have a proper shebang and have the executable bit set.
17832 When executed, a socket (the IPC connection) is passed to them through
17834 file descriptor inheritance. The file descriptor is indicated as the
17835 special command line argument --mpv-ipc-fd=N, where N is the numeric
17836 file descriptor.
17837 The rest is the same as with a normal --input-ipc-server IPC connec‐
17839 tion. mpv does not attempt to observe or other interact with the
17840 started script process.
17841 This does not work in Windows yet.
17843
17845 There is no real changelog, but you can look at the following things:
17846 • The release changelog, which should contain most user-visible
17848 changes, including new features and bug fixes:
17849 https://github.com/mpv-player/mpv/releases
17851 • The git log, which is the "real" changelog
17853 • The file
17855 https://github.com/mpv-player/mpv/blob/master/DOCS/interface-changes.rst
17856 documents changes to the command and user interface, such as options
17857 and properties. (It usually documents breaking changes only, addi‐
17858 tions and enhancements are often not listed.)
17859 • C API changes are listed in
17861 https://github.com/mpv-player/mpv/blob/master/DOCS/client-api-changes.rst
17862 • The file mplayer-changes.rst in the DOCS sub directory on the git
17864 repository, which used to be in place of this section. It documents
17865 some changes that happened since mplayer2 forked off MPlayer. (Not
17866 updated anymore.)
17867
17869 mpv can be embedded into other programs as video/audio playback back‐
17870 end. The recommended way to do so is using libmpv. See libmpv/client.h
17871 in the mpv source code repository. This provides a C API. Bindings for
17872 other languages might be available (see wiki).
17873 Since libmpv merely allows access to underlying mechanisms that can
17875 control mpv, further documentation is spread over a few places:
17876 • https://github.com/mpv-player/mpv/blob/master/libmpv/client.h
17878 • https://mpv.io/manual/master/#options
17880 • https://mpv.io/manual/master/#list-of-input-commands
17882 • https://mpv.io/manual/master/#properties
17884 • https://github.com/mpv-player/mpv-examples/tree/master/libmpv
17886
17888 You can write C plugins for mpv. These use the libmpv API, although
17889 they do not use the libmpv library itself.
17890 They are available on Linux/BSD platforms only and enabled by default
17892 if the compiler supports linking with the -rdynamic flag.
17893 C plugins location
17895 C plugins are put into the mpv scripts directory in its config direc‐
17896 tory (see the FILES section for details). They must have a .so file ex‐
17897 tension. They can also be explicitly loaded with the --script option.
17898 API
17900 A C plugin must export the following function:
17901 int mpv_open_cplugin(mpv_handle *handle)
17903 The plugin function will be called on loading time. This function does
17905 not return as long as your plugin is loaded (it runs in its own
17906 thread). The handle will be deallocated as soon as the plugin function
17907 returns.
17908 The return value is interpreted as error status. A value of 0 is inter‐
17910 preted as success, while -1 signals an error. In the latter case, the
17911 player prints an uninformative error message that loading failed.
17912 Return values other than 0 and -1 are reserved, and trigger undefined
17914 behavior.
17915 Within the plugin function, you can call libmpv API functions. The han‐
17917 dle is created by mpv_create_client() (or actually an internal equiva‐
17918 lent), and belongs to you. You can call mpv_wait_event() to wait for
17919 things happening, and so on.
17920 Note that the player might block until your plugin calls
17922 mpv_wait_event() for the first time. This gives you a chance to install
17923 initial hooks etc. before playback begins.
17924 The details are quite similar to Lua scripts.
17926 Linkage to libmpv
17928 The current implementation requires that your plugins are not linked
17929 against libmpv. What your plugins use are not symbols from a libmpv bi‐
17930 nary, but symbols from the mpv host binary.
17931 Examples
17933 See:
17934 • https://github.com/mpv-player/mpv-examples/tree/master/cplugins
17936
17938 There are a number of environment variables that can be used to control
17939 the behavior of mpv.
17940 HOME, XDG_CONFIG_HOME
17942 Used to determine mpv config directory. If XDG_CONFIG_HOME is
17943 not set, $HOME/.config/mpv is used.
17944 $HOME/.mpv is always added to the list of config search paths
17946 with a lower priority.
17947 MPV_HOME
17949 Directory where mpv looks for user settings. Overrides HOME, and
17950 mpv will try to load the config file as $MPV_HOME/mpv.conf.
17951 MPV_VERBOSE (see also -v and --msg-level)
17953 Set the initial verbosity level across all message modules (de‐
17954 fault: 0). This is an integer, and the resulting verbosity cor‐
17955 responds to the number of --v options passed to the command
17956 line.
17957 MPV_LEAK_REPORT
17959 If set to 1, enable internal talloc leak reporting. If set to
17960 another value, disable leak reporting. If unset, use the de‐
17961 fault, which normally is 0. If mpv was built with --en‐
17962 able-ta-leak-report, the default is 1. If leak reporting was
17963 disabled at compile time (NDEBUG in custom CFLAGS), this envi‐
17964 ronment variable is ignored.
17965 LADSPA_PATH
17967 Specifies the search path for LADSPA plugins. If it is unset,
17968 fully qualified path names must be used.
17969 DISPLAY
17971 Standard X11 display name to use.
17972 FFmpeg/Libav:
17974 This library accesses various environment variables. However,
17975 they are not centrally documented, and documenting them is not
17976 our job. Therefore, this list is incomplete.
17977 Notable environment variables:
17979 http_proxy
17981 URL to proxy for http:// and https:// URLs.
17982 no_proxy
17984 List of domain patterns for which no proxy should be
17985 used. List entries are separated by ,. Patterns can in‐
17986 clude *.
17987 libdvdcss:
17989 DVDCSS_CACHE
17991 Specify a directory in which to store title key values.
17992 This will speed up descrambling of DVDs which are in the
17993 cache. The DVDCSS_CACHE directory is created if it does
17994 not exist, and a subdirectory is created named after the
17995 DVD's title or manufacturing date. If DVDCSS_CACHE is not
17996 set or is empty, libdvdcss will use the default value
17997 which is ${HOME}/.dvdcss/ under Unix and the roaming ap‐
17998 plication data directory (%APPDATA%) under Windows. The
17999 special value "off" disables caching.
18000 DVDCSS_METHOD
18002 Sets the authentication and decryption method that libd‐
18003 vdcss will use to read scrambled discs. Can be one of ti‐
18004 tle, key or disc.
18005 key is the default method. libdvdcss will use a set of
18007 calculated player keys to try to get the disc key.
18008 This can fail if the drive does not recognize any
18009 of the player keys.
18010 disc is a fallback method when key has failed. Instead
18012 of using player keys, libdvdcss will crack the
18013 disc key using a brute force algorithm. This
18014 process is CPU intensive and requires 64 MB of
18015 memory to store temporary data.
18016 title is the fallback when all other methods have
18018 failed. It does not rely on a key exchange with
18019 the DVD drive, but rather uses a crypto attack to
18020 guess the title key. On rare cases this may fail
18021 because there is not enough encrypted data on the
18022 disc to perform a statistical attack, but on the
18023 other hand it is the only way to decrypt a DVD
18024 stored on a hard disc, or a DVD with the wrong re‐
18025 gion on an RPC2 drive.
18026 DVDCSS_RAW_DEVICE
18028 Specify the raw device to use. Exact usage will depend on
18029 your operating system, the Linux utility to set up raw
18030 devices is raw(8) for instance. Please note that on most
18031 operating systems, using a raw device requires highly
18032 aligned buffers: Linux requires a 2048 bytes alignment
18033 (which is the size of a DVD sector).
18034 DVDCSS_VERBOSE
18036 Sets the libdvdcss verbosity level.
18037 0 Outputs no messages at all.
18039 1 Outputs error messages to stderr.
18041 2 Outputs error messages and debug messages to
18043 stderr.
18044 DVDREAD_NOKEYS
18046 Skip retrieving all keys on startup. Currently disabled.
18047 HOME FIXME: Document this.
18049
18051 Normally mpv returns 0 as exit code after finishing playback success‐
18052 fully. If errors happen, the following exit codes can be returned:
18053 1 Error initializing mpv. This is also returned if unknown op‐
18055 tions are passed to mpv.
18056 2 The file passed to mpv couldn't be played. This is somewhat
18058 fuzzy: currently, playback of a file is considered to be suc‐
18059 cessful if initialization was mostly successful, even if
18060 playback fails immediately after initialization.
18061 3 There were some files that could be played, and some files
18063 which couldn't (using the definition of success from above).
18064 4 Quit due to a signal, Ctrl+c in a VO window (by default), or
18066 from the default quit key bindings in encoding mode.
18067 Note that quitting the player manually will always lead to exit code 0,
18069 overriding the exit code that would be returned normally. Also, the
18070 quit input command can take an exit code: in this case, that exit code
18071 is returned.
18072
18074 For Windows-specifics, see FILES ON WINDOWS section.
18075 /usr/local/etc/mpv/mpv.conf
18077 mpv system-wide settings (depends on --prefix passed to config‐
18078 ure - mpv in default configuration will use /usr/local/etc/mpv/
18079 as config directory, while most Linux distributions will set it
18080 to /etc/mpv/).
18081 ~/.config/mpv
18083 The standard configuration directory. This can be overridden by
18084 environment variables, in ascending order:
18085 1 If $XDG_CONFIG_HOME is set, then the derived configura‐
18087 tion directory will be $XDG_CONFIG_HOME/mpv.
18088 2 If $MPV_HOME is set, then the derived configuration di‐
18090 rectory will be $MPV_HOME.
18091 If this directory, nor the original configuration directory (see
18093 below) do not exist, mpv tries to create this directory automat‐
18094 ically.
18095 ~/.mpv/
18097 The original (pre 0.5.0) configuration directory. It will con‐
18098 tinue to be read if present.
18099 If both this directory and the standard configuration directory
18101 are present, configuration will be read from both with the stan‐
18102 dard configuration directory content taking precedence. However,
18103 you should fully migrate to the standard directory and a warning
18104 will be shown in this situation.
18105 ~/.config/mpv/mpv.conf
18107 mpv user settings (see CONFIGURATION FILES section)
18108 ~/.config/mpv/input.conf
18110 key bindings (see INPUT.CONF section)
18111 ~/.config/mpv/fonts.conf
18113 Fontconfig fonts.conf that is customized for mpv. You should in‐
18114 clude system fonts.conf in this file or mpv would not know about
18115 fonts that you already have in the system.
18116 Only available when libass is built with fontconfig.
18118 ~/.config/mpv/subfont.ttf
18120 fallback subtitle font
18121 ~/.config/mpv/fonts/
18123 Font files in this directory are used by mpv/libass for subti‐
18124 tles. Useful if you do not want to install fonts to your system.
18125 Note that files in this directory are loaded into memory before
18126 being used by mpv. If you have a lot of fonts, consider using
18127 fonts.conf (see above) to include additional fonts, which is
18128 more memory-efficient.
18129 ~/.config/mpv/scripts/
18131 All files in this directory are loaded as if they were passed to
18132 the --script option. They are loaded in alphabetical order.
18133 The --load-scripts=no option disables loading these files.
18135 See Script location for details.
18137 ~/.config/mpv/watch_later/
18139 Contains temporary config files needed for resuming playback of
18140 files with the watch later feature. See for example the Q key
18141 binding, or the quit-watch-later input command.
18142 Each file is a small config file which is loaded if the corre‐
18144 sponding media file is loaded. It contains the playback position
18145 and some (not necessarily all) settings that were changed during
18146 playback. The filenames are hashed from the full paths of the
18147 media files. It's in general not possible to extract the media
18148 filename from this hash. However, you can set the --write-file‐
18149 name-in-watch-later-config option, and the player will add the
18150 media filename to the contents of the resume config file.
18151 ~/.config/mpv/script-opts/osc.conf
18153 This is loaded by the OSC script. See the ON SCREEN CONTROLLER
18154 docs for details.
18155 Other files in this directory are specific to the corresponding
18157 scripts as well, and the mpv core doesn't touch them.
18158
18160 On win32 (if compiled with MinGW, but not Cygwin), the default config
18161 file locations are different. They are generally located under %APP‐
18162 DATA%/mpv/. For example, the path to mpv.conf is %APP‐
18163 DATA%/mpv/mpv.conf, which maps to a system and user-specific path, for
18164 example
18165 C:\users\USERNAME\AppData\Roaming\mpv\mpv.conf
18166 You can find the exact path by running echo %APPDATA%\mpv\mpv.conf in
18168 cmd.exe.
18169 Other config files (such as input.conf) are in the same directory. See
18171 the FILES section above.
18172 The environment variable $MPV_HOME completely overrides these, like on
18174 UNIX.
18175 If a directory named portable_config next to the mpv.exe exists, all
18177 config will be loaded from this directory only. Watch later config
18178 files are written to this directory as well. (This exists on Windows
18179 only and is redundant with $MPV_HOME. However, since Windows is very
18180 scripting unfriendly, a wrapper script just setting $MPV_HOME, like you
18181 could do it on other systems, won't work. portable_config is provided
18182 for convenience to get around this restriction.)
18183 Config files located in the same directory as mpv.exe are loaded with
18185 lower priority. Some config files are loaded only once, which means
18186 that e.g. of 2 input.conf files located in two config directories, only
18187 the one from the directory with higher priority will be loaded.
18188 A third config directory with the lowest priority is the directory
18190 named mpv in the same directory as mpv.exe. This used to be the direc‐
18191 tory with the highest priority, but is now discouraged to use and might
18192 be removed in the future.
18193 Note that mpv likes to mix / and \ path separators for simplicity.
18195 kernel32.dll accepts this, but cmd.exe does not.
18196
18198 GPLv2+
18199 MPV(1)