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 │~~cache/ │ the path to application │
436 │ │ cache data (~/.cache/mpv/) │
437 │ │ On some platforms, this │
438 │ │ will be the same as │
439 │ │ ~~home/. │
440 ├─────────────┼────────────────────────────┤
441 │~~state/ │ the path to application │
442 │ │ state data (~/.lo‐ │
443 │ │ cal/state/mpv/) On some │
444 │ │ platforms, this will be │
445 │ │ the same as ~~home/. │
446 ├─────────────┼────────────────────────────┤
447 │~~old_home/ │ do not use │
448 └─────────────┴────────────────────────────┘
449 Per-File Options
451 When playing multiple files, any option given on the command line usu‐
452 ally affects all files. Example:
453 mpv --a file1.mkv --b file2.mkv --c
455 ┌──────────┬────────────────┐
457 │File │ Active options │
458 ├──────────┼────────────────┤
459 │file1.mkv │ --a --b --c │
460 ├──────────┼────────────────┤
461 │file2.mkv │ --a --b --c │
462 └──────────┴────────────────┘
463 (This is different from MPlayer and mplayer2.)
465 Also, if any option is changed at runtime (via input commands), they
467 are not reset when a new file is played.
468 Sometimes, it is useful to change options per-file. This can be
470 achieved by adding the special per-file markers --{ and --}. (Note that
471 you must escape these on some shells.) Example:
472 mpv --a file1.mkv --b --\{ --c file2.mkv --d file3.mkv --e --\} file4.mkv --f
474 ┌──────────┬─────────────────────────┐
476 │File │ Active options │
477 ├──────────┼─────────────────────────┤
478 │file1.mkv │ --a --b --f │
479 ├──────────┼─────────────────────────┤
480 │file2.mkv │ --a --b --f --c --d --e │
481 ├──────────┼─────────────────────────┤
482 │file3.mkv │ --a --b --f --c --d --e │
483 ├──────────┼─────────────────────────┤
484 │file4.mkv │ --a --b --f │
485 └──────────┴─────────────────────────┘
486 Additionally, any file-local option changed at runtime is reset when
488 the current file stops playing. If option --c is changed during play‐
489 back of file2.mkv, it is reset when advancing to file3.mkv. This only
490 affects file-local options. The option --a is never reset here.
491 List Options
493 Some options which store lists of option values can have action suf‐
494 fixes. For example, the --display-tags option takes a ,-separated list
495 of tags, but the option also allows you to append a single tag with
496 --display-tags-append, and the tag name can for example contain a lit‐
497 eral , without the need for escaping.
498 String list and path list options
500 String lists are separated by ,. The strings are not parsed or inter‐
501 preted by the option system itself. However, most
502 Path or file list options use : (Unix) or ; (Windows) as separator, in‐
504 stead of ,.
505 They support the following operations:
507 ┌────────┬────────────────────────────┐
509 │Suffix │ Meaning │
510 ├────────┼────────────────────────────┤
511 │-set │ Set a list of items (using │
512 │ │ the list separator, es‐ │
513 │ │ caped with backslash) │
514 ├────────┼────────────────────────────┤
515 │-append │ Append single item (does │
516 │ │ not interpret escapes) │
517 ├────────┼────────────────────────────┤
518 │-add │ Append 1 or more items │
519 │ │ (same syntax as -set) │
520 ├────────┼────────────────────────────┤
521 │-pre │ Prepend 1 or more items │
522 │ │ (same syntax as -set) │
523 ├────────┼────────────────────────────┤
524 │-clr │ Clear the option (remove │
525 │ │ all items) │
526 ├────────┼────────────────────────────┤
527 │-remove │ Delete item if present │
528 │ │ (does not interpret es‐ │
529 │ │ capes) │
530 ├────────┼────────────────────────────┤
531 │-del │ Delete 1 or more items by │
532 │ │ integer index (deprecated) │
533 └────────┴────────────────────────────┘
534 │-toggle │ Append an item, or remove │
538 │ │ if if it already exists │
539 │ │ (no escapes) │
540 └────────┴────────────────────────────┘
541 -append is meant as a simple way to append a single item without having
543 to escape the argument (you may still need to escape on the shell
544 level).
545 Key/value list options
547 A key/value list is a list of key/value string pairs. In programming
548 languages, this type of data structure is often called a map or a dic‐
549 tionary. The order normally does not matter, although in some cases the
550 order might matter.
551 They support the following operations:
553 ┌────────┬────────────────────────────┐
555 │Suffix │ Meaning │
556 ├────────┼────────────────────────────┤
557 │-set │ Set a list of items (using │
558 │ │ , as separator) │
559 ├────────┼────────────────────────────┤
560 │-append │ Append a single item (es‐ │
561 │ │ capes for the key, no es‐ │
562 │ │ capes for the value) │
563 ├────────┼────────────────────────────┤
564 │-add │ Append 1 or more items │
565 │ │ (same syntax as -set) │
566 ├────────┼────────────────────────────┤
567 │-remove │ Delete item by key if │
568 │ │ present (does not inter‐ │
569 │ │ pret escapes) │
570 └────────┴────────────────────────────┘
571 Keys are unique within the list. If an already present key is set, the
573 existing key is removed before the new value is appended.
574 If you want to pass a value without interpreting it for escapes or ,,
576 it is recommended to use the -add variant. When using libmpv, prefer
577 using MPV_FORMAT_NODE_MAP; when using a scripting backend or the JSON
578 IPC, use an appropriate structured data type.
579 Prior to mpv 0.33, : was also recognized as separator by -set.
581 Filter options
583 This is a very complex option type for the --af and --vf options only.
584 They often require complicated escaping. See VIDEO FILTERS for details.
585 They support the following operations:
586 ┌────────┬────────────────────────────┐
588 │Suffix │ Meaning │
589 ├────────┼────────────────────────────┤
590 │-set │ Set a list of filters (us‐ │
591 │ │ ing , as separator) │
592 ├────────┼────────────────────────────┤
593 │-append │ Append single filter │
594 ├────────┼────────────────────────────┤
595 │-add │ Append 1 or more filters │
596 │ │ (same syntax as -set) │
597 ├────────┼────────────────────────────┤
598 │-pre │ Prepend 1 or more filters │
599 │ │ (same syntax as -set) │
600 └────────┴────────────────────────────┘
601 │-clr │ Clear the option (remove │
605 │ │ all filters) │
606 ├────────┼────────────────────────────┤
607 │-remove │ Delete filter if present │
608 ├────────┼────────────────────────────┤
609 │-del │ Delete 1 or more filters │
610 │ │ by integer index or filter │
611 │ │ label (deprecated) │
612 ├────────┼────────────────────────────┤
613 │-toggle │ Append a filter, or remove │
614 │ │ if if it already exists │
615 ├────────┼────────────────────────────┤
616 │-help │ Pseudo operation that │
617 │ │ prints a help text to the │
618 │ │ terminal │
619 └────────┴────────────────────────────┘
620 General
622 Without suffix, the operation used is normally -set.
623 Although some operations allow specifying multiple items, using this is
625 strongly discouraged and deprecated, except for -set. There is a chance
626 that operations like -add and -pre will work like -append and accept a
627 single, unescaped item only (so the , separator will not be interpreted
628 and is passed on as part of the value).
629 Some options (like --sub-file, --audio-file, --glsl-shader) are aliases
631 for the proper option with -append action. For example, --sub-file is
632 an alias for --sub-files-append.
633 Options of this type can be changed at runtime using the change-list
635 command, which takes the suffix (without the -) as separate operation
636 parameter.
637
639 Location and Syntax
640 You can put all of the options in configuration files which will be
641 read every time mpv is run. The system-wide configuration file
642 'mpv.conf' is in your configuration directory (e.g. /etc/mpv or
643 /usr/local/etc/mpv), the user-specific one is ~/.config/mpv/mpv.conf.
644 For details and platform specifics (in particular Windows paths) see
645 the FILES section.
646 User-specific options override system-wide options and options given on
648 the command line override either. The syntax of the configuration files
649 is option=value. Everything after a # is considered a comment. Options
650 that work without values can be enabled by setting them to yes and dis‐
651 abled by setting them to no. Even suboptions can be specified in this
652 way.
653 Example configuration file
655 # Use GPU-accelerated video output by default.
657 vo=gpu
658 # Use quotes for text that can contain spaces:
659 term-status-msg="Time: ${time-pos}"
660 Escaping spaces and special characters
662 This is done like with command line options. The shell is not involved
663 here, but option values still need to be quoted as a whole if it con‐
664 tains certain characters like spaces. A config entry can be quoted with
665 ", as well as with the fixed-length syntax (%n%) mentioned before. This
666 is like passing the exact contents of the quoted string as command line
667 option. C-style escapes are currently _not_ interpreted on this level,
668 although some options do this manually. (This is a mess and should
669 probably be changed at some point.)
670 Putting Command Line Options into the Configuration File
672 Almost all command line options can be put into the configuration file.
673 Here is a small guide:
674 ┌──────────────────┬──────────────────────────┐
676 │Option │ Configuration file entry │
677 ├──────────────────┼──────────────────────────┤
678 │--flag │ flag │
679 ├──────────────────┼──────────────────────────┤
680 │-opt val │ opt=val │
681 ├──────────────────┼──────────────────────────┤
682 │--opt=val │ opt=val │
683 ├──────────────────┼──────────────────────────┤
684 │-opt "has spaces" │ opt="has spaces" │
685 └──────────────────┴──────────────────────────┘
686 File-specific Configuration Files
688 You can also write file-specific configuration files. If you wish to
689 have a configuration file for a file called 'video.avi', create a file
690 named 'video.avi.conf' with the file-specific options in it and put it
691 in ~/.config/mpv/. You can also put the configuration file in the same
692 directory as the file to be played. Both require you to set the
693 --use-filedir-conf option (either on the command line or in your global
694 config file). If a file-specific configuration file is found in the
695 same directory, no file-specific configuration is loaded from ~/.con‐
696 fig/mpv. In addition, the --use-filedir-conf option enables direc‐
697 tory-specific configuration files. For this, mpv first tries to load a
698 mpv.conf from the same directory as the file played and then tries to
699 load any file-specific configuration.
700 Profiles
702 To ease working with different configurations, profiles can be defined
703 in the configuration files. A profile starts with its name in square
704 brackets, e.g. [my-profile]. All following options will be part of the
705 profile. A description (shown by --profile=help) can be defined with
706 the profile-desc option. To end the profile, start another one or use
707 the profile name default to continue with normal options.
708 You can list profiles with --profile=help, and show the contents of a
710 profile with --show-profile=<name> (replace <name> with the profile
711 name). You can apply profiles on start with the --profile=<name> op‐
712 tion, or at runtime with the apply-profile <name> command.
713 Example mpv config file with profiles
715 # normal top-level option
717 fullscreen=yes
718 # a profile that can be enabled with --profile=big-cache
720 [big-cache]
721 cache=yes
722 demuxer-max-bytes=123400KiB
723 demuxer-readahead-secs=20
724 [slow]
726 profile-desc="some profile name"
727 # reference a builtin profile
728 profile=gpu-hq
729 [fast]
731 vo=vdpau
732 # using a profile again extends it
734 [slow]
735 framedrop=no
736 # you can also include other profiles
737 profile=big-cache
738 Runtime profiles
740 Profiles can be set at runtime with apply-profile command. Since this
741 operation is "destructive" (every item in a profile is simply set as an
742 option, overwriting the previous value), you can't just enable and dis‐
743 able profiles again.
744 As a partial remedy, there is a way to make profiles save old option
746 values before overwriting them with the profile values, and then
747 restoring the old values at a later point using apply-profile <pro‐
748 file-name> restore.
749 This can be enabled with the profile-restore option, which takes one of
751 the following options:
752 default
754 Does nothing, and nothing can be restored (default).
755 copy When applying a profile, copy the old values of all profile
757 options to a backup before setting them from the profile.
758 These options are reset to their old values using the backup
759 when restoring.
760 Every profile has its own list of backed up values. If the
762 backup already exists (e.g. if apply-profile name was called
763 more than once in a row), the existing backup is no changed.
764 The restore operation will remove the backup.
765 It's important to know that restoring does not "undo" setting
767 an option, but simply copies the old option value. Consider
768 for example vf-add, appends an entry to vf. This mechanism
769 will simply copy the entire vf list, and does _not_ execute
770 the inverse of vf-add (that would be vf-remove) on restoring.
771 Note that if a profile contains recursive profiles (via the
773 profile option), the options in these recursive profiles are
774 treated as if they were part of this profile. The referenced
775 profile's backup list is not used when creating or using the
776 backup. Restoring a profile does not restore referenced pro‐
777 files, only the options of referenced profiles (as if they
778 were part of the main profile).
779 copy-equal
781 Similar to copy, but restore an option only if it has the
782 same value as the value effectively set by the profile. This
783 tries to deal with the situation when the user does not want
784 the option to be reset after interactively changing it.
785 Example
787 [something]
789 profile-restore=copy-equal
790 vf-add=rotate=PI/2 # rotate by 90 degrees
791 Then running these commands will result in behavior as commented:
793 set vf vflip
795 apply-profile something
796 vf add hflip
797 apply-profile something
798 # vf == vflip,rotate=PI/2,hflip,rotate=PI/2
799 apply-profile something restore
800 # vf == vflip
801 Conditional auto profiles
803 Profiles which have the profile-cond option set are applied automati‐
804 cally if the associated condition matches (unless auto profiles are
805 disabled). The option takes a string, which is interpreted as Lua ex‐
806 pression. If the expression evaluates as truthy, the profile is ap‐
807 plied. If the expression errors or evaluates as falsy, the profile is
808 not applied. This Lua code execution is not sandboxed.
809 Any variables in condition expressions can reference properties. If an
811 identifier is not already defined by Lua or mpv, it is interpreted as
812 property. For example, pause would return the current pause status.
813 You cannot reference properties with - this way since that would denote
814 a subtraction, but if the variable name contains any _ characters, they
815 are turned into -. For example, playback_time would return the property
816 playback-time.
817 A more robust way to access properties is using p.property_name or
819 get("property-name", default_value). The automatic variable to property
820 magic will break if a new identifier with the same name is introduced
821 (for example, if a function named pause() were added, pause would re‐
822 turn a function value instead of the value of the pause property).
823 Note that if a property is not available, it will return nil, which can
825 cause errors if used in expressions. These are logged in verbose mode,
826 and the expression is considered to be false.
827 Whenever a property referenced by a profile condition changes, the con‐
829 dition is re-evaluated. If the return value of the condition changes
830 from falsy or error to truthy, the profile is applied.
831 This mechanism tries to "unapply" profiles once the condition changes
833 from truthy to falsy or error. If you want to use this, you need to set
834 profile-restore for the profile. Another possibility it to create an‐
835 other profile with an inverse condition to undo the other profile.
836 Recursive profiles can be used. But it is discouraged to reference
838 other conditional profiles in a conditional profile, since this can
839 lead to tricky and unintuitive behavior.
840 Example
842 Make only HD video look funny:
844 [something]
846 profile-desc=HD video sucks
847 profile-cond=width >= 1280
848 hue=-50
849 Make only videos containing "youtube" or "youtu.be" in their path
851 brighter:
852 [youtube]
854 profile-cond=path:find('youtu%.?be')
855 gamma=20
856 If you want the profile to be reverted if the condition goes to
858 false again, you can set profile-restore:
859 [something]
861 profile-desc=Mess up video when entering fullscreen
862 profile-cond=fullscreen
863 profile-restore=copy
864 vf-add=rotate=PI/2 # rotate by 90 degrees
865 This appends the rotate filter to the video filter chain when enter‐
867 ing fullscreen. When leaving fullscreen, the vf option is set to the
868 value it had before entering fullscreen. Note that this would also
869 remove any other filters that were added during fullscreen mode by
870 the user. Avoiding this is trickier, and could for example be solved
871 by adding a second profile with an inverse condition and operation:
872 [something]
874 profile-cond=fullscreen
875 vf-add=@rot:rotate=PI/2
876 [something-inv]
878 profile-cond=not fullscreen
879 vf-remove=@rot
880 WARNING:
882 Every time an involved property changes, the condition is evaluated
883 again. If your condition uses p.playback_time for example, the con‐
884 dition is re-evaluated approximately on every video frame. This is
885 probably slow.
886 This feature is managed by an internal Lua script. Conditions are exe‐
888 cuted as Lua code within this script. Its environment contains at least
889 the following things:
890 (function environment table)
892 Every Lua function has an environment table. This is used for
893 identifier access. There is no named Lua symbol for it; it is
894 implicit.
895 The environment does "magic" accesses to mpv properties. If an
897 identifier is not already defined in _G, it retrieves the mpv
898 property of the same name. Any occurrences of _ in the name are
899 replaced with - before reading the property. The returned value
900 is as retrieved by mp.get_property_native(name). Internally, a
901 cache of property values, updated by observing the property is
902 used instead, so properties that are not observable will be
903 stuck at the initial value forever.
904 If you want to access properties, that actually contain _ in the
906 name, use get() (which does not perform transliteration).
907 Internally, the environment table has a __index meta method set,
909 which performs the access logic.
910 p A "magic" table similar to the environment table. Unlike the
912 latter, this does not prefer accessing variables defined in _G -
913 it always accesses properties.
914 get(name [, def])
916 Read a property and return its value. If the property value is
917 nil (e.g. if the property does not exist), def is returned.
918 This is superficially similar to mp.get_property_native(name).
920 An important difference is that this accesses the property
921 cache, and enables the change detection logic (which is essen‐
922 tial to the dynamic runtime behavior of auto profiles). Also, it
923 does not return an error value as second return value.
924 The "magic" tables mentioned above use this function as backend.
926 It does not perform the _ transliteration.
927 In addition, the same environment as in a blank mpv Lua script is
929 present. For example, math is defined and gives access to the Lua stan‐
930 dard math library.
931 WARNING:
933 This feature is subject to change indefinitely. You might be forced
934 to adjust your profiles on mpv updates.
935 Legacy auto profiles
937 Some profiles are loaded automatically using a legacy mechanism. The
938 following example demonstrates this:
939 Auto profile loading
941 [extension.mkv]
943 profile-desc="profile for .mkv files"
944 vf=vflip
945 The profile name follows the schema type.name, where type can be proto‐
947 col for the input/output protocol in use (see --list-protocols), and
948 extension for the extension of the path of the currently played file
949 (not the file format).
950 This feature is very limited, and is considered soft-deprecated. Use
952 conditional auto profiles.
953
955 There are three choices for using mpv from other programs or scripts:
956 1. Calling it as UNIX process. If you do this, do not parse terminal
958 output. The terminal output is intended for humans, and may
959 change any time. In addition, terminal behavior itself may change
960 any time. Compatibility cannot be guaranteed.
961 Your code should work even if you pass --no-terminal. Do not at‐
963 tempt to simulate user input by sending terminal control codes to
964 mpv's stdin. If you need interactive control, using --in‐
965 put-ipc-server is recommended. This gives you access to the JSON
966 IPC over unix domain sockets (or named pipes on Windows).
967 Depending on what you do, passing --no-config or --config-dir may
969 be a good idea to avoid conflicts with the normal mpv user con‐
970 figuration intended for CLI playback.
971 Using --input-ipc-server is also suitable for purposes like re‐
973 mote control (however, the IPC protocol itself is not "secure"
974 and not intended to be so).
975 2. Using libmpv. This is generally recommended when mpv is used as
977 playback backend for a completely different application. The pro‐
978 vided C API is very close to CLI mechanisms and the scripting
979 API.
980 Note that even though libmpv has different defaults, it can be
982 configured to work exactly like the CLI player (except command
983 line parsing is unavailable).
984 See EMBEDDING INTO OTHER PROGRAMS (LIBMPV).
986 3. As a user script (LUA SCRIPTING, JAVASCRIPT, C PLUGINS). This is
988 recommended when the goal is to "enhance" the CLI player. Scripts
989 get access to the entire client API of mpv.
990 This is the standard way to create third-party extensions for the
992 player.
993 All these access the client API, which is the sum of the various mecha‐
995 nisms provided by the player core, as documented here: OPTIONS, List of
996 Input Commands, Properties, List of events (also see C API), Hooks.
997
999 Screenshots of the currently played file can be taken using the
1000 'screenshot' input mode command, which is by default bound to the s
1001 key. Files named mpv-shotNNNN.jpg will be saved in the working direc‐
1002 tory, using the first available number - no files will be overwritten.
1003 In pseudo-GUI mode, the screenshot will be saved somewhere else. See
1004 PSEUDO GUI MODE.
1005 A screenshot will usually contain the unscaled video contents at the
1007 end of the video filter chain and subtitles. By default, S takes
1008 screenshots without subtitles, while s includes subtitles.
1009 Unlike with MPlayer, the screenshot video filter is not required. This
1011 filter was never required in mpv, and has been removed.
1012
1014 During playback, mpv shows the playback status on the terminal. It
1015 looks like something like this:
1016 AV: 00:03:12 / 00:24:25 (13%) A-V: -0.000
1017 The status line can be overridden with the --term-status-msg option.
1019 The following is a list of things that can show up in the status line.
1021 Input properties, that can be used to get the same information manu‐
1022 ally, are also listed.
1023 • AV: or V: (video only) or A: (audio only)
1025 • The current time position in HH:MM:SS format (playback-time property)
1027 • The total file duration (absent if unknown) (duration property)
1029 • Playback speed, e.g. x2.0. Only visible if the speed is not normal.
1031 This is the user-requested speed, and not the actual speed (usually
1032 they should be the same, unless playback is too slow). (speed prop‐
1033 erty.)
1034 • Playback percentage, e.g. (13%). How much of the file has been
1036 played. Normally calculated out of playback position and duration,
1037 but can fallback to other methods (like byte position) if these are
1038 not available. (percent-pos property.)
1039 • The audio/video sync as A-V: 0.000. This is the difference between
1041 audio and video time. Normally it should be 0 or close to 0. If it's
1042 growing, it might indicate a playback problem. (avsync property.)
1043 • Total A/V sync change, e.g. ct: -0.417. Normally invisible. Can show
1045 up if there is audio "missing", or not enough frames can be dropped.
1046 Usually this will indicate a problem. (total-avsync-change property.)
1047 • Encoding state in {...}, only shown in encoding mode.
1049 • Display sync state. If display sync is active (display-sync-active
1051 property), this shows DS: 2.500/13, where the first number is average
1052 number of vsyncs per video frame (e.g. 2.5 when playing 24Hz videos
1053 on 60Hz screens), which might jitter if the ratio doesn't round off,
1054 or there are mistimed frames (vsync-ratio), and the second number of
1055 estimated number of vsyncs which took too long (vo-de‐
1056 layed-frame-count property). The latter is a heuristic, as it's gen‐
1057 erally not possible to determine this with certainty.
1058 • Dropped frames, e.g. Dropped: 4. Shows up only if the count is not 0.
1060 Can grow if the video framerate is higher than that of the display,
1061 or if video rendering is too slow. May also be incremented on "hic‐
1062 cups" and when the video frame couldn't be displayed on time.
1063 (frame-drop-count property.) If the decoder drops frames, the number
1064 of decoder-dropped frames is appended to the display as well, e.g.:
1065 Dropped: 4/34. This happens only if decoder frame dropping is enabled
1066 with the --framedrop options. (decoder-frame-drop-count property.)
1067 • Cache state, e.g. Cache: 2s/134KB. Visible if the stream cache is
1069 enabled. The first value shows the amount of video buffered in the
1070 demuxer in seconds, the second value shows the estimated size of the
1071 buffered amount in kilobytes. (demuxer-cache-duration and de‐
1072 muxer-cache-state properties.)
1073
1075 mpv is optimized for normal video playback, meaning it actually tries
1076 to buffer as much data as it seems to make sense. This will increase
1077 latency. Reducing latency is possible only by specifically disabling
1078 features which increase latency.
1079 The builtin low-latency profile tries to apply some of the options
1081 which can reduce latency. You can use --profile=low-latency to apply
1082 all of them. You can list the contents with --show-profile=low-latency
1083 (some of the options are quite obscure, and may change every mpv re‐
1084 lease).
1085 Be aware that some of the options can reduce playback quality.
1087 Most latency is actually caused by inconvenient timing behavior. You
1089 can disable this with --untimed, but it will likely break, unless the
1090 stream has no audio, and the input feeds data to the player at a con‐
1091 stant rate.
1092 Another common problem is with MJPEG streams. These do not signal the
1094 correct framerate. Using --untimed or --no-correct-pts --fps=60 might
1095 help.
1096 For livestreams, data can build up due to pausing the stream, due to
1098 slightly lower playback rate, or "buffering" pauses. If the demuxer
1099 cache is enabled, these can be skipped manually. The experimental
1100 drop-buffers command can be used to discard any buffered data, though
1101 it's very disruptive.
1102 In some cases, manually tuning TCP buffer sizes and such can help to
1104 reduce latency.
1105 Additional options that can be tried:
1107 • --opengl-glfinish=yes, can reduce buffering in the graphics driver
1109 • --opengl-swapinterval=0, same
1111 • --vo=xv, same
1113 • without audio --framedrop=no --speed=1.01 may help for live sources
1115 (results can be mixed)
1116
1118 mpv is capable of storing the playback position of the currently play‐
1119 ing file and resume from there the next time that file is played. This
1120 is done with the commands quit-watch-later (bound to Shift+Q by de‐
1121 fault) and write-watch-later-config, and with the --save-posi‐
1122 tion-on-quit option.
1123 The difference between always quitting with a key bound to
1125 quit-watch-later and using --save-position-on-quit is that the latter
1126 will save the playback position even when mpv is closed with a method
1127 other than a keybinding, for example if you shutdown your system with‐
1128 out closing mpv beforehand, unless of course mpv is terminated abruptly
1129 and doesn't have the time to save (e.g. with the KILL Unix signal).
1130 mpv also stores options other than the playback position when they have
1132 been modified after playback began, for example the volume and the
1133 fullscreen state, and restores their values the next time the file is
1134 played. Which options are saved can be configured with the
1135 --watch-later-options option.
1136 When playing multiple playlist entries, mpv checks if one them has a
1138 resume config file associated, and if it finds one it restarts playback
1139 from it. For example, if you use quit-watch-later on the 5th episode of
1140 a show, and later play all the episodes, mpv will automatically resume
1141 playback from episode 5.
1142 More options to configure this functionality are listed in Watch Later.
1144
1146 http://..., https://, ...
1147 Many network protocols are supported, but the protocol prefix must
1148 always be specified. mpv will never attempt to guess whether a file‐
1149 name is actually a network address. A protocol prefix is always re‐
1150 quired.
1151 Note that not all prefixes are documented here. Undocumented pre‐
1153 fixes are either aliases to documented protocols, or are just redi‐
1154 rections to protocols implemented and documented in FFmpeg.
1155 data: is supported in FFmpeg (not in Libav), but needs to be in the
1157 format data://. This is done to avoid ambiguity with filenames. You
1158 can also prefix it with lavf:// or ffmpeg://.
1159 ytdl://...
1161 By default, the youtube-dl hook script only looks at http(s) URLs.
1162 Prefixing an URL with ytdl:// forces it to be always processed by
1163 the script. This can also be used to invoke special youtube-dl func‐
1164 tionality like playing a video by ID or invoking search.
1165 Keep in mind that you can't pass youtube-dl command line options by
1167 this, and you have to use --ytdl-raw-options instead.
1168 -
1170 Play data from stdin.
1171 smb://PATH
1173 Play a path from Samba share. (Requires FFmpeg support.)
1174 bd://[title][/device] --bluray-device=PATH
1176 Play a Blu-ray disc. Since libbluray 1.0.1, you can read from ISO
1177 files by passing them to --bluray-device.
1178 title can be: longest or first (selects the default playlist);
1180 mpls/<number> (selects <number>.mpls playlist); <number> (select
1181 playlist with the same index). mpv will list the available playlists
1182 on loading.
1183 bluray:// is an alias.
1185 dvd://[title][/device] --dvd-device=PATH
1187 Play a DVD. DVD menus are not supported. If no title is given, the
1188 longest title is auto-selected. Without --dvd-device, it will proba‐
1189 bly try to open an actual optical drive, if available and imple‐
1190 mented for the OS.
1191 dvdnav:// is an old alias for dvd:// and does exactly the same
1193 thing.
1194 dvb://[cardnumber@]channel --dvbin-...
1196 Digital TV via DVB. (Linux only.)
1197 mf://[filemask|@listfile] --mf-...
1199 Play a series of images as video.
1200 cdda://[device] --cdrom-device=PATH --cdda-...
1202 Play CD.
1203 lavf://...
1205 Access any FFmpeg/Libav libavformat protocol. Basically, this passed
1206 the string after the // directly to libavformat.
1207 av://type:options
1209 This is intended for using libavdevice inputs. type is the libavde‐
1210 vice demuxer name, and options is the (pseudo-)filename passed to
1211 the demuxer.
1212 Example
1214 mpv av://v4l2:/dev/video0 --profile=low-latency --untimed
1216 This plays video from the first v4l input with nearly the lowest
1218 latency possible. It's a good replacement for the removed tv://
1219 input. Using --untimed is a hack to output a captured frame im‐
1220 mediately, instead of respecting the input framerate. (There may
1221 be better ways to handle this in the future.)
1222 avdevice:// is an alias.
1224 file://PATH
1226 A local path as URL. Might be useful in some special use-cases. Note
1227 that PATH itself should start with a third / to make the path an ab‐
1228 solute path.
1229 appending://PATH
1231 Play a local file, but assume it's being appended to. This is useful
1232 for example for files that are currently being downloaded to disk.
1233 This will block playback, and stop playback only if no new data was
1234 appended after a timeout of about 2 seconds.
1235 Using this is still a bit of a bad idea, because there is no way to
1237 detect if a file is actually being appended, or if it's still writ‐
1238 ten. If you're trying to play the output of some program, consider
1239 using a pipe (something | mpv -). If it really has to be a file on
1240 disk, use tail to make it wait forever, e.g. tail -f -c +0 file.mkv
1241 | mpv -.
1242 fd://123
1244 Read data from the given file descriptor (for example 123). This is
1245 similar to piping data to stdin via -, but can use an arbitrary file
1246 descriptor. mpv may modify some file descriptor properties when the
1247 stream layer "opens" it.
1248 fdclose://123
1250 Like fd://, but the file descriptor is closed after use. When using
1251 this you need to ensure that the same fd URL will only be used once.
1252 edl://[edl specification as in edl-mpv.rst]
1254 Stitch together parts of multiple files and play them.
1255 slice://start[-end]@URL
1257 Read a slice of a stream.
1258 start and end represent a byte range and accept suffixes such as KiB
1260 and MiB. end is optional.
1261 if end starts with +, it is considered as offset from start.
1263 Only works with seekable streams.
1265 Examples:
1267 mpv slice://1g-2g@cap.ts
1269 This starts reading from cap.ts after seeking 1 GiB, then
1271 reads until reaching 2 GiB or end of file.
1272 mpv slice://1g-+2g@cap.ts
1274 This starts reading from cap.ts after seeking 1 GiB, then
1276 reads until reaching 3 GiB or end of file.
1277 mpv slice://100m@appending://cap.ts
1279 This starts reading from cap.ts after seeking 100MiB, then
1281 reads until end of file.
1282 null://
1284 Simulate an empty file. If opened for writing, it will discard all
1285 data. The null demuxer will specifically pass autoprobing if this
1286 protocol is used (while it's not automatically invoked for empty
1287 files).
1288 memory://data
1290 Use the data part as source data.
1291 hex://data
1293 Like memory://, but the string is interpreted as hexdump.
1294
1296 mpv has no official GUI, other than the OSC (ON SCREEN CONTROLLER),
1297 which is not a full GUI and is not meant to be. However, to compensate
1298 for the lack of expected GUI behavior, mpv will in some cases start
1299 with some settings changed to behave slightly more like a GUI mode.
1300 Currently this happens only in the following cases:
1302 • if started using the mpv.desktop file on Linux (e.g. started from
1304 menus or file associations provided by desktop environments)
1305 • if started from explorer.exe on Windows (technically, if it was
1307 started on Windows, and all of the stdout/stderr/stdin handles are
1308 unset)
1309 • started out of the bundle on macOS
1311 • if you manually use --player-operation-mode=pseudo-gui on the command
1313 line
1314 This mode applies options from the builtin profile builtin-pseudo-gui,
1316 but only if these haven't been set in the user's config file or on the
1317 command line, which is the main difference to using --pro‐
1318 file=builtin-pseudo-gui.
1319 The profile is currently defined as follows:
1321 [builtin-pseudo-gui]
1323 terminal=no
1324 force-window=yes
1325 idle=once
1326 screenshot-directory=~~desktop/
1327 The pseudo-gui profile exists for compatibility. The options in the
1329 pseudo-gui profile are applied unconditionally. In addition, the pro‐
1330 file makes sure to enable the pseudo-GUI mode, so that --pro‐
1331 file=pseudo-gui works like in older mpv releases:
1332 [pseudo-gui]
1334 player-operation-mode=pseudo-gui
1335 WARNING:
1337 Currently, you can extend the pseudo-gui profile in the config file
1338 the normal way. This is deprecated. In future mpv releases, the be‐
1339 havior might change, and not apply your additional settings, and/or
1340 use a different profile name.
1341
1343 This subsection describes common problems on the Linux desktop. None of
1344 these problems exist on systems like Windows or macOS.
1345 Disabling Screensaver
1347 By default, mpv tries to disable the OS screensaver during playback
1348 (only if a VO using the OS GUI API is active). --stop-screensaver=no
1349 disables this.
1350 A common problem is that Linux desktop environments ignore the standard
1352 screensaver APIs on which mpv relies. In particular, mpv uses the
1353 Screen Saver extension (XSS) on X11, and the idle-inhibit protocol on
1354 Wayland.
1355 GNOME in particular still ignores the idle-inhibit protocol, and has
1357 its own D-Bus interfaces for display power management, which mpv does
1358 not support.
1359 Before mpv 0.33.0, the X11 backend ran xdg-screensaver reset in 10 sec‐
1361 ond intervals when not paused in order to support screensaver inhibi‐
1362 tion in these environments. This functionality was removed in 0.33.0,
1363 but it is possible to call the xdg-screensaver command line program
1364 from a user script instead.
1365
1367 Track Selection
1368 --alang=<languagecode[,languagecode,...]>
1369 Specify a priority list of audio languages to use, as IETF lan‐
1370 guage tags. Equivalent ISO 639-1 two-letter and ISO 639-2
1371 three-letter codes are treated the same. The first tag in the
1372 list whose language matches a track in the file will be used. A
1373 track that matches more subtags will be preferred over one that
1374 matches fewer, with preference given to earlier subtags over
1375 later ones. See also --aid.
1376 The special value "auto" can be included anywhere in the list,
1378 and is equivalent to the user's OS-level list of preferred lan‐
1379 guages.
1380 This is a string list option. See List Options for details.
1382 Examples
1384 • mpv dvd://1 --alang=hu,en chooses the Hungarian language
1386 track on a DVD and falls back on English if Hungarian is
1387 not available.
1388 • mpv --alang=jpn example.mkv plays a Matroska file with Ja‐
1390 panese audio.
1391 --slang=<languagecode[,languagecode,...]>
1393 Equivalent to --alang, for subtitle tracks (default: auto).
1394 This is a string list option. See List Options for details.
1396 Examples
1398 • mpv dvd://1 --slang=hu,en chooses the Hungarian subtitle
1400 track on a DVD and falls back on English if Hungarian is
1401 not available.
1402 • mpv --slang=jpn example.mkv plays a Matroska file with Ja‐
1404 panese subtitles.
1405 • mpv --slang=pt-BR example.mkv plays a Matroska file with
1407 Brazilian Portuguese subtitles if available, and otherwise
1408 any Portuguese subtitles.
1409 --vlang=<...>
1411 Equivalent to --alang and --slang, for video tracks.
1412 This is a string list option. See List Options for details.
1414 --aid=<ID|auto|no>
1416 Select audio track. auto selects the default, no disables audio.
1417 See also --alang. mpv normally prints available audio tracks on
1418 the terminal when starting playback of a file.
1419 --audio is an alias for --aid.
1421 --aid=no or --audio=no or --no-audio disables audio playback.
1423 (The latter variant does not work with the client API.)
1424 NOTE:
1426 The track selection options (--aid but also --sid and the
1427 others) sometimes expose behavior that may appear strange.
1428 Also, the behavior tends to change around with each mpv re‐
1429 lease.
1430 The track selection properties will return the option value
1432 outside of playback (as expected), but during playback, the
1433 affective track selection is returned. For example, with
1434 --aid=auto, the aid property will suddenly return 2 after
1435 playback initialization (assuming the file has at least 2 au‐
1436 dio tracks, and the second is the default).
1437 At mpv 0.32.0 (and some releases before), if you passed a
1439 track value for which a corresponding track didn't exist
1440 (e.g. --aid=2 and there was only 1 audio track), the aid
1441 property returned no. However if another audio track was
1442 added during playback, and you tried to set the aid property
1443 to 2, nothing happened, because the aid option still had the
1444 value 2, and writing the same value has no effect.
1445 With mpv 0.33.0, the behavior was changed. Now track selec‐
1447 tion options are reset to auto at playback initialization, if
1448 the option had tries to select a track that does not exist.
1449 The same is done if the track exists, but fails to initial‐
1450 ize. The consequence is that unlike before mpv 0.33.0, the
1451 user's track selection parameters are clobbered in certain
1452 situations.
1453 Also since mpv 0.33.0, trying to select a track by number
1455 will strictly select this track. Before this change, trying
1456 to select a track which did not exist would fall back to
1457 track default selection at playback initialization. The new
1458 behavior is more consistent.
1459 Setting a track selection property at runtime, and then play‐
1461 ing a new file might reset the track selection to defaults,
1462 if the fingerprint of the track list of the new file is dif‐
1463 ferent.
1464 Be aware of tricky combinations of all of all of the above:
1466 for example, mpv --aid=2 file_with_2_audio_tracks.mkv
1467 file_with_1_audio_track.mkv would first play the correct
1468 track, and the second file without audio. If you then go
1469 back the first file, its first audio track will be played,
1470 and the second file is played with audio. If you do the same
1471 thing again but instead of using --aid=2 you run set aid 2
1472 while the file is playing, then changing to the second file
1473 will play its audio track. This is because runtime selection
1474 enables the fingerprint heuristic.
1475 Most likely this is not the end.
1477 --sid=<ID|auto|no>
1479 Display the subtitle stream specified by <ID>. auto selects the
1480 default, no disables subtitles.
1481 --sub is an alias for --sid.
1483 --sid=no or --sub=no or --no-sub disables subtitle decoding.
1485 (The latter variant does not work with the client API.)
1486 --vid=<ID|auto|no>
1488 Select video channel. auto selects the default, no disables
1489 video.
1490 --video is an alias for --vid.
1492 --vid=no or --video=no or --no-video disables video playback.
1494 (The latter variant does not work with the client API.)
1495 If video is disabled, mpv will try to download the audio only if
1497 media is streamed with youtube-dl, because it saves bandwidth.
1498 This is done by setting the ytdl_format to "bestaudio/best" in
1499 the ytdl_hook.lua script.
1500 --edition=<ID|auto>
1502 (Matroska files only) Specify the edition (set of chapters) to
1503 use, where 0 is the first. If set to auto (the default), mpv
1504 will choose the first edition declared as a default, or if there
1505 is no default, the first edition defined.
1506 --track-auto-selection=<yes|no>
1508 Enable the default track auto-selection (default: yes). Enabling
1509 this will make the player select streams according to --aid,
1510 --alang, and others. If it is disabled, no tracks are selected.
1511 In addition, the player will not exit if no tracks are selected,
1512 and wait instead (this wait mode is similar to pausing, but the
1513 pause option is not set).
1514 This is useful with --lavfi-complex: you can start playback in
1516 this mode, and then set select tracks at runtime by setting the
1517 filter graph. Note that if --lavfi-complex is set before play‐
1518 back is started, the referenced tracks are always selected.
1519 --subs-with-matching-audio=<yes|no>
1521 When autoselecting a subtitle track, select a full/non-forced
1522 one even if the selected audio stream matches your preferred
1523 subtitle language (default: no).
1524 --subs-fallback=<yes|default|no>
1526 When autoselecting a subtitle track, if no tracks match your
1527 preferred languages, select a full track even if it doesn't
1528 match your preferred subtitle language (default: no). Setting
1529 this to default means that only streams flagged as default will
1530 be selected.
1531 --subs-fallback-forced=<yes|no>
1533 When autoselecting a subtitle track, if no tracks match your
1534 preferred languages, select a forced track that matches the lan‐
1535 guage of the selected audio track (default: yes).
1536 Playback Control
1538 --start=<relative time>
1539 Seek to given time position.
1540 The general format for times is [+|-][[hh:]mm:]ss[.ms]. If the
1542 time is prefixed with -, the time is considered relative from
1543 the end of the file (as signaled by the demuxer/the file). A +
1544 is usually ignored (but see below).
1545 The following alternative time specifications are recognized:
1547 pp% seeks to percent position pp (0-100).
1549 #c seeks to chapter number c. (Chapters start from 1.)
1551 none resets any previously set option (useful for libmpv).
1553 If --rebase-start-time=no is given, then prefixing times with +
1555 makes the time relative to the start of the file. A timestamp
1556 without prefix is considered an absolute time, i.e. should seek
1557 to a frame with a timestamp as the file contains it. As a bug,
1558 but also a hidden feature, putting 1 or more spaces before the +
1559 or - always interprets the time as absolute, which can be used
1560 to seek to negative timestamps (useful for debugging at most).
1561 Examples
1563 --start=+56, --start=00:56
1565 Seeks to the start time + 56 seconds.
1566 --start=-56, --start=-00:56
1568 Seeks to the end time - 56 seconds.
1569 --start=01:10:00
1571 Seeks to 1 hour 10 min.
1572 --start=50%
1574 Seeks to the middle of the file.
1575 --start=30 --end=40
1577 Seeks to 30 seconds, plays 10 seconds, and exits.
1578 --start=-3:20 --length=10
1580 Seeks to 3 minutes and 20 seconds before the end of
1581 the file, plays 10 seconds, and exits.
1582 --start='#2' --end='#4'
1584 Plays chapters 2 and 3, and exits.
1585 --end=<relative time>
1587 Stop at given time. Use --length if the time should be relative
1588 to --start. See --start for valid option values and examples.
1589 --length=<relative time>
1591 Stop after a given time relative to the start time. See --start
1592 for valid option values and examples.
1593 If both --end and --length are provided, playback will stop when
1595 it reaches either of the two endpoints.
1596 Obscurity note: this does not work correctly if --re‐
1598 base-start-time=no, and the specified time is not an "absolute"
1599 time, as defined in the --start option description.
1600 --rebase-start-time=<yes|no>
1602 Whether to move the file start time to 00:00:00 (default: yes).
1603 This is less awkward for files which start at a random time‐
1604 stamp, such as transport streams. On the other hand, if there
1605 are timestamp resets, the resulting behavior can be rather
1606 weird. For this reason, and in case you are actually interested
1607 in the real timestamps, this behavior can be disabled with no.
1608 --speed=<0.01-100>
1610 Slow down or speed up playback by the factor given as parameter.
1611 If --audio-pitch-correction (on by default) is used, playing
1613 with a speed higher than normal automatically inserts the
1614 scaletempo2 audio filter.
1615 --pause
1617 Start the player in paused state.
1618 --shuffle
1620 Play files in random order.
1621 --playlist-start=<auto|index>
1623 Set which file on the internal playlist to start playback with.
1624 The index is an integer, with 0 meaning the first file. The
1625 value auto means that the selection of the entry to play is left
1626 to the playback resume mechanism (default). If an entry with the
1627 given index doesn't exist, the behavior is unspecified and might
1628 change in future mpv versions. The same applies if the playlist
1629 contains further playlists (don't expect any reasonable behav‐
1630 ior). Passing a playlist file to mpv should work with this op‐
1631 tion, though. E.g. mpv playlist.m3u --playlist-start=123 will
1632 work as expected, as long as playlist.m3u does not link to fur‐
1633 ther playlists.
1634 The value no is a deprecated alias for auto.
1636 --playlist=<filename>
1638 Play files according to a playlist file. Supports some common
1639 formats. If no format is detected, it will be treated as list of
1640 files, separated by newline characters. You may need this option
1641 to load plaintext files as a playlist. Note that XML playlist
1642 formats are not supported.
1643 This option forces --demuxer=playlist to interpret the playlist
1645 file. Some playlist formats, notably CUE and optical disc for‐
1646 mats, need to use different demuxers and will not work with this
1647 option. They still can be played directly, without using this
1648 option.
1649 You can play playlists directly, without this option. Before mpv
1651 version 0.31.0, this option disabled any security mechanisms
1652 that might be in place, but since 0.31.0 it uses the same secu‐
1653 rity mechanisms as playing a playlist file directly. If you
1654 trust the playlist file, you can disable any security checks
1655 with --load-unsafe-playlists. Because playlists can load other
1656 playlist entries, consider applying this option only to the
1657 playlist itself and not its entries, using something along these
1658 lines:
1659 mpv --{ --playlist=filename --load-unsafe-playlists --}
1660 WARNING:
1662 The way older versions of mpv played playlist files via
1663 --playlist was not safe against maliciously constructed
1664 files. Such files may trigger harmful actions. This has been
1665 the case for all versions of mpv prior to 0.31.0, and all
1666 MPlayer versions, but unfortunately this fact was not well
1667 documented earlier, and some people have even misguidedly
1668 recommended the use of --playlist with untrusted sources. Do
1669 NOT use --playlist with random internet sources or files you
1670 do not trust if you are not sure your mpv is at least 0.31.0.
1671 In particular, playlists can contain entries using protocols
1673 other than local files, such as special protocols like avde‐
1674 vice:// (which are inherently unsafe).
1675 --chapter-merge-threshold=<number>
1677 Threshold for merging almost consecutive ordered chapter parts
1678 in milliseconds (default: 100). Some Matroska files with ordered
1679 chapters have inaccurate chapter end timestamps, causing a small
1680 gap between the end of one chapter and the start of the next one
1681 when they should match. If the end of one playback part is less
1682 than the given threshold away from the start of the next one
1683 then keep playing video normally over the chapter change instead
1684 of doing a seek.
1685 --chapter-seek-threshold=<seconds>
1687 Distance in seconds from the beginning of a chapter within which
1688 a backward chapter seek will go to the previous chapter (de‐
1689 fault: 5.0). Past this threshold, a backward chapter seek will
1690 go to the beginning of the current chapter instead. A negative
1691 value means always go back to the previous chapter.
1692 --hr-seek=<no|absolute|yes|default>
1694 Select when to use precise seeks that are not limited to
1695 keyframes. Such seeks require decoding video from the previous
1696 keyframe up to the target position and so can take some time de‐
1697 pending on decoding performance. For some video formats, precise
1698 seeks are disabled. This option selects the default choice to
1699 use for seeks; it is possible to explicitly override that de‐
1700 fault in the definition of key bindings and in input commands.
1701 no Never use precise seeks.
1703 absolute
1705 Use precise seeks if the seek is to an absolute position
1706 in the file, such as a chapter seek, but not for relative
1707 seeks like the default behavior of arrow keys.
1708 default
1710 Like absolute, but enable hr-seeks in audio-only cases.
1711 The exact behavior is implementation specific and may
1712 change with new releases (default).
1713 yes Use precise seeks whenever possible.
1715 always Same as yes (for compatibility).
1717 --hr-seek-demuxer-offset=<seconds>
1719 This option exists to work around failures to do precise seeks
1720 (as in --hr-seek) caused by bugs or limitations in the demuxers
1721 for some file formats. Some demuxers fail to seek to a keyframe
1722 before the given target position, going to a later position in‐
1723 stead. The value of this option is subtracted from the time
1724 stamp given to the demuxer. Thus, if you set this option to 1.5
1725 and try to do a precise seek to 60 seconds, the demuxer is told
1726 to seek to time 58.5, which hopefully reduces the chance that it
1727 erroneously goes to some time later than 60 seconds. The down‐
1728 side of setting this option is that precise seeks become slower,
1729 as video between the earlier demuxer position and the real tar‐
1730 get may be unnecessarily decoded.
1731 --hr-seek-framedrop=<yes|no>
1733 Allow the video decoder to drop frames during seek, if these
1734 frames are before the seek target. If this is enabled, precise
1735 seeking can be faster, but if you're using video filters which
1736 modify timestamps or add new frames, it can lead to precise
1737 seeking skipping the target frame. This e.g. can break frame
1738 backstepping when deinterlacing is enabled.
1739 Default: yes
1741 --index=<mode>
1743 Controls how to seek in files. Note that if the index is missing
1744 from a file, it will be built on the fly by default, so you
1745 don't need to change this. But it might help with some broken
1746 files.
1747 default
1749 use an index if the file has one, or build it if missing
1750 recreate
1752 don't read or use the file's index
1753 NOTE:
1755 This option only works if the underlying media supports seek‐
1756 ing (i.e. not with stdin, pipe, etc).
1757 --load-unsafe-playlists
1759 Load URLs from playlists which are considered unsafe (default:
1760 no). This includes special protocols and anything that doesn't
1761 refer to normal files. Local files and HTTP links on the other
1762 hand are always considered safe.
1763 In addition, if a playlist is loaded while this is set, the
1765 added playlist entries are not marked as originating from net‐
1766 work or potentially unsafe location. (Instead, the behavior is
1767 as if the playlist entries were provided directly to mpv command
1768 line or loadfile command.)
1769 --access-references=<yes|no>
1771 Follow any references in the file being opened (default: yes).
1772 Disabling this is helpful if the file is automatically scanned
1773 (e.g. thumbnail generation). If the thumbnail scanner for exam‐
1774 ple encounters a playlist file, which contains network URLs, and
1775 the scanner should not open these, enabling this option will
1776 prevent it. This option also disables ordered chapters, mov ref‐
1777 erence files, opening of archives, and a number of other fea‐
1778 tures.
1779 On older FFmpeg versions, this will not work in some cases. Some
1781 FFmpeg demuxers might not respect this option.
1782 This option does not prevent opening of paired subtitle files
1784 and such. Use --autoload-files=no to prevent this.
1785 This option does not always work if you open non-files (for ex‐
1787 ample using dvd://directory would open a whole bunch of files in
1788 the given directory). Prefixing the filename with ./ if it
1789 doesn't start with a / will avoid this.
1790 --loop-playlist=<N|inf|force|no>, --loop-playlist
1792 Loops playback N times. A value of 1 plays it one time (de‐
1793 fault), 2 two times, etc. inf means forever. no is the same as 1
1794 and disables looping. If several files are specified on command
1795 line, the entire playlist is looped. --loop-playlist is the same
1796 as --loop-playlist=inf.
1797 The force mode is like inf, but does not skip playlist entries
1799 which have been marked as failing. This means the player might
1800 waste CPU time trying to loop a file that doesn't exist. But it
1801 might be useful for playing webradios under very bad network
1802 conditions.
1803 --loop-file=<N|inf|no>, --loop=<N|inf|no>
1805 Loop a single file N times. inf means forever, no means normal
1806 playback. For compatibility, --loop-file and --loop-file=yes are
1807 also accepted, and are the same as --loop-file=inf.
1808 The difference to --loop-playlist is that this doesn't loop the
1810 playlist, just the file itself. If the playlist contains only a
1811 single file, the difference between the two option is that this
1812 option performs a seek on loop, instead of reloading the file.
1813 NOTE:
1815 --loop-file counts the number of times it causes the player
1816 to seek to the beginning of the file, not the number of full
1817 playthroughs. This means --loop-file=1 will end up playing
1818 the file twice. Contrast with --loop-playlist, which counts
1819 the number of full playthroughs.
1820 --loop is an alias for this option.
1822 --ab-loop-a=<time>, --ab-loop-b=<time>
1824 Set loop points. If playback passes the b timestamp, it will
1825 seek to the a timestamp. Seeking past the b point doesn't loop
1826 (this is intentional).
1827 If a is after b, the behavior is as if the points were given in
1829 the right order, and the player will seek to b after crossing
1830 through a. This is different from old behavior, where looping
1831 was disabled (and as a bug, looped back to a on the end of the
1832 file).
1833 If either options are set to no (or unset), looping is disabled.
1835 This is different from old behavior, where an unset a implied
1836 the start of the file, and an unset b the end of the file.
1837 The loop-points can be adjusted at runtime with the correspond‐
1839 ing properties. See also ab-loop command.
1840 --ab-loop-count=<N|inf>
1842 Run A-B loops only N times, then ignore the A-B loop points (de‐
1843 fault: inf). Every finished loop iteration will decrement this
1844 option by 1 (unless it is set to inf or 0). inf means that loop‐
1845 ing goes on forever. If this option is set to 0, A-B looping is
1846 ignored, and even the ab-loop command will not enable looping
1847 again (the command will show (disabled) on the OSD message if
1848 both loop points are set, but ab-loop-count is 0).
1849 --ordered-chapters, --no-ordered-chapters
1851 Enabled by default. Disable support for Matroska ordered chap‐
1852 ters. mpv will not load or search for video segments from other
1853 files, and will also ignore any chapter order specified for the
1854 main file.
1855 --ordered-chapters-files=<playlist-file>
1857 Loads the given file as playlist, and tries to use the files
1858 contained in it as reference files when opening a Matroska file
1859 that uses ordered chapters. This overrides the normal mechanism
1860 for loading referenced files by scanning the same directory the
1861 main file is located in.
1862 Useful for loading ordered chapter files that are not located on
1864 the local filesystem, or if the referenced files are in differ‐
1865 ent directories.
1866 Note: a playlist can be as simple as a text file containing
1868 filenames separated by newlines.
1869 --chapters-file=<filename>
1871 Load chapters from this file, instead of using the chapter meta‐
1872 data found in the main file.
1873 This accepts a media file (like mkv) or even a pseudo-format
1875 like ffmetadata and uses its chapters to replace the current
1876 file's chapters. This doesn't work with OGM or XML chapters di‐
1877 rectly.
1878 --sstep=<sec>
1880 Skip <sec> seconds after every frame.
1881 NOTE:
1883 Without --hr-seek, skipping will snap to keyframes.
1884 --stop-playback-on-init-failure=<yes|no>
1886 Stop playback if either audio or video fails to initialize (de‐
1887 fault: no). With no, playback will continue in video-only or
1888 audio-only mode if one of them fails. This doesn't affect play‐
1889 back of audio-only or video-only files.
1890 --play-dir=<forward|+|backward|->
1892 Control the playback direction (default: forward). Setting back‐
1893 ward will attempt to play the file in reverse direction, with
1894 decreasing playback time. If this is set on playback starts,
1895 playback will start from the end of the file. If this is changed
1896 at during playback, a hr-seek will be issued to change the di‐
1897 rection.
1898 + and - are aliases for forward and backward.
1900 The rest of this option description pertains to the backward
1902 mode.
1903 NOTE:
1905 Backward playback is extremely fragile. It may not always
1906 work, is much slower than forward playback, and breaks cer‐
1907 tain other features. How well it works depends mainly on the
1908 file being played. Generally, it will show good results (or
1909 results at all) only if the stars align.
1910 mpv, as well as most media formats, were designed for forward
1912 playback only. Backward playback is bolted on top of mpv, and
1913 tries to make a medium effort to make backward playback work.
1914 Depending on your use-case, another tool may work much better.
1915 Backward playback is not exactly a 1st class feature. Implemen‐
1917 tation tradeoffs were made, that are bad for backward playback,
1918 but in turn do not cause disadvantages for normal playback. Var‐
1919 ious possible optimizations are not implemented in order to keep
1920 the complexity down. Normally, a media player is highly
1921 pipelined (future data is prepared in separate threads, so it is
1922 available in realtime when the next stage needs it), but back‐
1923 ward playback will essentially stall the pipeline at various
1924 random points.
1925 For example, for intra-only codecs are trivially backward
1927 playable, and tools built around them may make efficient use of
1928 them (consider video editors or camera viewers). mpv won't be
1929 efficient in this case, because it uses its generic backward
1930 playback algorithm, that on top of it is not very optimized.
1931 If you just want to quickly go backward through the video and
1933 just show "keyframes", just use forward playback, and hold down
1934 the left cursor key (which on CLI with default config sends many
1935 small relative seek commands).
1936 The implementation consists of mostly 3 parts:
1938 • Backward demuxing. This relies on the demuxer cache, so the
1940 demuxer cache should (or must, didn't test it) be enabled, and
1941 its size will affect performance. If the cache is too small or
1942 too large, quadratic runtime behavior may result.
1943 • Backward decoding. The decoder library used (libavcodec) does
1945 not support this. It is emulated by feeding bits of data in
1946 forward, putting the result in a queue, returning the queue
1947 data to the VO in reverse, and then starting over at an ear‐
1948 lier position. This can require buffering an extreme amount of
1949 decoded data, and also completely breaks pipelining.
1950 • Backward output. This is relatively simple, because the de‐
1952 coder returns the frames in the needed order. However, this
1953 may cause various problems because filters see audio and video
1954 going backward.
1955 Known problems:
1957 • It's fragile. If anything doesn't work, random non-useful be‐
1959 havior may occur. In simple cases, the player will just play
1960 nonsense and artifacts. In other cases, it may get stuck or
1961 heat the CPU. (Exceeding memory usage significantly beyond the
1962 user-set limits would be a bug, though.)
1963 • Performance and resource usage isn't good. In part this is in‐
1965 herent to backward playback of normal media formats, and in
1966 parts due to implementation choices and tradeoffs.
1967 • This is extremely reliant on good demuxer behavior. Although
1969 backward demuxing requires no special demuxer support, it is
1970 required that the demuxer performs seeks reliably, fulfills
1971 some specific requirements about packet metadata, and has de‐
1972 terministic behavior.
1973 • Starting playback exactly from the end may or may not work,
1975 depending on seeking behavior and file duration detection.
1976 • Some container formats, audio, and video codecs are not sup‐
1978 ported due to their behavior. There is no list, and the player
1979 usually does not detect them. Certain live streams (including
1980 TV captures) may exhibit problems in particular, as well as
1981 some lossy audio codecs. h264 intra-refresh is known not to
1982 work due to problems with libavcodec. WAV and some other raw
1983 audio formats tend to have problems - there are hacks for
1984 dealing with them, which may or may not work.
1985 • Backward demuxing of subtitles is not supported. Subtitle dis‐
1987 play still works for some external text subtitle formats.
1988 (These are fully read into memory, and only backward display
1989 is needed.) Text subtitles that are cached in the subtitle
1990 renderer also have a chance to be displayed correctly.
1991 • Some features dealing with playback of broken or hard to deal
1993 with files will not work fully (such as timestamp correction).
1994 • If demuxer low level seeks (i.e. seeking the actual demuxer
1996 instead of just within the demuxer cache) are performed by
1997 backward playback, the created seek ranges may not join, be‐
1998 cause not enough overlap is achieved.
1999 • Trying to use this with hardware video decoding will probably
2001 exhaust all your GPU memory and then crash a thing or two. Or
2002 it will fail because --hwdec-extra-frames will certainly be
2003 set too low.
2004 • Stream recording is broken. --stream-record may keep working
2006 if you backward play within a cached region only.
2007 • Relative seeks may behave weird. Small seeks backward (towards
2009 smaller time, i.e. seek -1) may not really seek properly, and
2010 audio will remain muted for a while. Using hr-seek is recom‐
2011 mended, which should have none of these problems.
2012 • Some things are just weird. For example, while seek commands
2014 manipulate playback time in the expected way (provided they
2015 work correctly), the framestep commands are transposed. Back‐
2016 stepping will perform very expensive work to step forward by 1
2017 frame.
2018 Tuning:
2020 • Remove all --vf/--af filters you have set. Disable hardware
2022 decoding. Disable idiotic nonsense like SPDIF passthrough.
2023 • Increasing --video-reversal-buffer might help if reversal
2025 queue overflow is reported, which may happen in high bitrate
2026 video, or video with large GOP. Hardware decoding mostly ig‐
2027 nores this, and you need to increase --hwdec-extra-frames in‐
2028 stead (until you get playback without logged errors).
2029 • The demuxer cache is essential for backward demuxing. Make
2031 sure to set --cache=yes. The cache size might matter. If it's
2032 too small, a queue overflow will be logged, and backward play‐
2033 back cannot continue, or it performs too many low level seeks.
2034 If it's too large, implementation tradeoffs may cause general
2035 performance issues. Use --demuxer-max-bytes to potentially in‐
2036 crease the amount of packets the demuxer layer can queue for
2037 reverse demuxing (basically it's the --video-reversal-buffer
2038 equivalent for the demuxer layer).
2039 • Setting --vd-queue-enable=yes can help a lot to make playback
2041 smooth (once it works).
2042 • --demuxer-backward-playback-step also factors into how many
2044 seeks may be performed, and whether backward demuxing could
2045 break due to queue overflow. If it's set too high, the back‐
2046 step operation needs to search through more packets all the
2047 time, even if the cache is large enough.
2048 • Setting --demuxer-cache-wait may be useful to cache the entire
2050 file into the demuxer cache. Set --demuxer-max-bytes to a
2051 large size to make sure it can read the entire cache; --de‐
2052 muxer-max-back-bytes should also be set to a large size to
2053 prevent that tries to trim the cache.
2054 • If audio artifacts are audible, even though the AO does not
2056 underrun, increasing --audio-backward-overlap might help in
2057 some cases.
2058 --video-reversal-buffer=<bytesize>, --audio-reversal-buffer=<bytesize>
2060 For backward decoding. Backward decoding decodes forward in
2061 steps, and then reverses the decoder output. These options con‐
2062 trol the approximate maximum amount of bytes that can be
2063 buffered. The main use of this is to avoid unbounded resource
2064 usage; during normal backward playback, it's not supposed to hit
2065 the limit, and if it does, it will drop frames and complain
2066 about it.
2067 Use this option if you get reversal queue overflow errors during
2069 backward playback. Increase the size until the warning disap‐
2070 pears. Usually, the video buffer will overflow first, especially
2071 if it's high resolution video.
2072 This does not work correctly if video hardware decoding is used.
2074 The video frame size will not include the referenced GPU and
2075 driver memory. Some hardware decoders may also be limited by
2076 --hwdec-extra-frames.
2077 How large the queue size needs to be depends entirely on the way
2079 the media was encoded. Audio typically requires a very small
2080 buffer, while video can require excessively large buffers.
2081 (Technically, this allows the last frame to exceed the limit.
2083 Also, this does not account for other buffered frames, such as
2084 inside the decoder or the video output.)
2085 This does not affect demuxer cache behavior at all.
2087 See --list-options for defaults and value range. <bytesize> op‐
2089 tions accept suffixes such as KiB and MiB.
2090 --video-backward-overlap=<auto|number>, --audio-backward-over‐
2092 lap=<auto|number>
2093 Number of overlapping keyframe ranges to use for backward decod‐
2094 ing (default: auto) ("keyframe" to be understood as in the
2095 mpv/ffmpeg specific meaning). Backward decoding works by for‐
2096 ward decoding in small steps. Some codecs cannot restart decod‐
2097 ing from any packet (even if it's marked as seek point), which
2098 becomes noticeable with backward decoding (in theory this is a
2099 problem with seeking too, but --hr-seek-demuxer-offset can fix
2100 it for seeking). In particular, MDCT based audio codecs are af‐
2101 fected.
2102 The solution is to feed a previous packet to the decoder each
2104 time, and then discard the output. This option controls how many
2105 packets to feed. The auto choice is currently hardcoded to 0 for
2106 video, and uses 1 for lossy audio, 0 for lossless audio. For
2107 some specific lossy audio codecs, this is set to 2.
2108 --video-backward-overlap can potentially handle intra-refresh
2110 video, depending on the exact conditions. You may have to use
2111 the --vd-lavc-show-all option as well.
2112 --video-backward-batch=<number>, --audio-backward-batch=<number>
2114 Number of keyframe ranges to decode at once when backward decod‐
2115 ing (default: 1 for video, 10 for audio). Another pointless tun‐
2116 ing parameter nobody should use. This should affect performance
2117 only. In theory, setting a number higher than 1 for audio will
2118 reduce overhead due to less frequent backstep operations and
2119 less redundant decoding work due to fewer decoded overlap frames
2120 (see --audio-backward-overlap). On the other hand, it requires a
2121 larger reversal buffer, and could make playback less smooth due
2122 to breaking pipelining (e.g. by decoding a lot, and then doing
2123 nothing for a while).
2124 It probably never makes sense to set --video-backward-batch. But
2126 in theory, it could help with intra-only video codecs by reduc‐
2127 ing backstep operations.
2128 --demuxer-backward-playback-step=<seconds>
2130 Number of seconds the demuxer should seek back to get new pack‐
2131 ets during backward playback (default: 60). This is useful for
2132 tuning backward playback, see --play-dir for details.
2133 Setting this to a very low value or 0 may make the player think
2135 seeking is broken, or may make it perform multiple seeks.
2136 Setting this to a high value may lead to quadratic runtime be‐
2138 havior.
2139 Program Behavior
2141 --help, --h
2142 Show short summary of options.
2143 You can also pass a string to this option, which will list all
2145 top-level options which contain the string in the name, e.g.
2146 --h=scale for all options that contain the word scale. The spe‐
2147 cial string * lists all top-level options.
2148 -v Increment verbosity level, one level for each -v found on the
2150 command line.
2151 --version, -V
2153 Print version string and exit.
2154 --no-config
2156 Do not load default configuration or any user files. This pre‐
2157 vents loading of both the user-level and system-wide mpv.conf
2158 and input.conf files. Other user files are blocked as well, such
2159 as resume playback files and cache files.
2160 NOTE:
2162 Files explicitly requested by command line options, like
2163 --include or --use-filedir-conf, will still be loaded.
2164 See also: --config-dir.
2166 --list-options
2168 Prints all available options.
2169 --list-properties
2171 Print a list of the available properties.
2172 --list-protocols
2174 Print a list of the supported protocols.
2175 --log-file=<path>
2177 Opens the given path for writing, and print log messages to it.
2178 Existing files will be truncated. The log level is at least -v
2179 -v, but can be raised via --msg-level (the option cannot lower
2180 it below the forced minimum log level).
2181 A special case is the macOS bundle, it will create a log file at
2183 ~/Library/Logs/mpv.log by default.
2184 --config-dir=<path>
2186 Force a different configuration directory. If this is set, the
2187 given directory is used to load configuration files, and all
2188 other configuration directories are ignored. This means the
2189 global mpv configuration directory as well as per-user directo‐
2190 ries are ignored, and overrides through environment variables
2191 (MPV_HOME) are also ignored.
2192 Note that the --no-config option takes precedence over this op‐
2194 tion.
2195 --dump-stats=<filename>
2197 Write certain statistics to the given file. The file is trun‐
2198 cated on opening. The file will contain raw samples, each with a
2199 timestamp. To make this file into a readable, the script
2200 TOOLS/stats-conv.py can be used (which currently displays it as
2201 a graph).
2202 This option is useful for debugging only.
2204 --idle=<no|yes|once>
2206 Makes mpv wait idly instead of quitting when there is no file to
2207 play. Mostly useful in input mode, where mpv can be controlled
2208 through input commands. (Default: no)
2209 once will only idle at start and let the player close once the
2211 first playlist has finished playing back.
2212 --include=<configuration-file>
2214 Specify configuration file to be parsed after the default ones.
2215 --load-scripts=<yes|no>
2217 If set to no, don't auto-load scripts from the scripts configu‐
2218 ration subdirectory (usually ~/.config/mpv/scripts/). (Default:
2219 yes)
2220 --script=<filename>, --scripts=file1.lua:file2.lua:...
2222 Load a Lua script. The second option allows you to load multiple
2223 scripts by separating them with the path separator (: on Unix, ;
2224 on Windows).
2225 --scripts is a path list option. See List Options for details.
2227 --script-opts=key1=value1,key2=value2,...
2229 Set options for scripts. A script can query an option by key. If
2230 an option is used and what semantics the option value has de‐
2231 pends entirely on the loaded scripts. Values not claimed by any
2232 scripts are ignored.
2233 This is a key/value list option. See List Options for details.
2235 --merge-files
2237 Pretend that all files passed to mpv are concatenated into a
2238 single, big file. This uses timeline/EDL support internally.
2239 --profile=<profile1,profile2,...>
2241 Use the given profile(s), --profile=help displays a list of the
2242 defined profiles.
2243 --reset-on-next-file=<all|option1,option2,...>
2245 Normally, mpv will try to keep all settings when playing the
2246 next file on the playlist, even if they were changed by the user
2247 during playback. (This behavior is the opposite of MPlayer's,
2248 which tries to reset all settings when starting next file.)
2249 Default: Do not reset anything.
2251 This can be changed with this option. It accepts a list of op‐
2253 tions, and mpv will reset the value of these options on playback
2254 start to the initial value. The initial value is either the de‐
2255 fault value, or as set by the config file or command line.
2256 In some cases, this might not work as expected. For example,
2258 --volume will only be reset if it is explicitly set in the con‐
2259 fig file or the command line.
2260 The special name all resets as many options as possible.
2262 This is a string list option. See List Options for details.
2264 Examples
2266 • --reset-on-next-file=pause Reset pause mode when switching
2268 to the next file.
2269 • --reset-on-next-file=fullscreen,speed Reset fullscreen and
2271 playback speed settings if they were changed during play‐
2272 back.
2273 • --reset-on-next-file=all Try to reset all settings that
2275 were changed during playback.
2276 --show-profile=<profile>
2278 Show the description and content of a profile. Lists all pro‐
2279 files if no parameter is provided.
2280 --use-filedir-conf
2282 Look for a file-specific configuration file in the same direc‐
2283 tory as the file that is being played. See File-specific Config‐
2284 uration Files.
2285 WARNING:
2287 May be dangerous if playing from untrusted media.
2288 --ytdl, --no-ytdl
2290 Enable the youtube-dl hook-script. It will look at the input
2291 URL, and will play the video located on the website. This works
2292 with many streaming sites, not just the one that the script is
2293 named after. This requires a recent version of youtube-dl to be
2294 installed on the system. (Enabled by default.)
2295 If the script can't do anything with an URL, it will do nothing.
2297 This accepts a set of options, which can be passed to it with
2299 the --script-opts option (using ytdl_hook- as prefix):
2300 try_ytdl_first=<yes|no>
2302 If 'yes' will try parsing the URL with youtube-dl first,
2303 instead of the default where it's only after mpv failed
2304 to open it. This mostly depends on whether most of your
2305 URLs need youtube-dl parsing.
2306 exclude=<URL1|URL2|...
2308 A |-separated list of URL patterns which mpv should not
2309 use with youtube-dl. The patterns are matched after the
2310 http(s):// part of the URL.
2311 ^ matches the beginning of the URL, $ matches its end,
2313 and you should use % before any of the characters
2314 ^$()%|,.[]*+-? to match that character.
2315 Examples
2317 • --script-opts=ytdl_hook-exclude='^youtube%.com' will
2319 exclude any URL that starts with http://youtube.com
2320 or https://youtube.com.
2321 • --script-opts=ytdl_hook-exclude='%.mkv$|%.mp4$' will
2323 exclude any URL that ends with .mkv or .mp4.
2324 See more lua patterns here:
2326 https://www.lua.org/manual/5.1/manual.html#5.4.1
2327 all_formats=<yes|no>
2329 If 'yes' will attempt to add all formats found reported
2330 by youtube-dl (default: no). Each format is added as a
2331 separate track. In addition, they are delay-loaded, and
2332 actually opened only when a track is selected (this
2333 should keep load times as low as without this option).
2334 It adds average bitrate metadata, if available, which
2336 means you can use --hls-bitrate to decide which track to
2337 select. (HLS used to be the only format whose alternative
2338 quality streams were exposed in a similar way, thus the
2339 option name.)
2340 Tracks which represent formats that were selected by
2342 youtube-dl as default will have the default flag set.
2343 This means mpv should generally still select formats cho‐
2344 sen with --ytdl-format by default.
2345 Although this mechanism makes it possible to switch
2347 streams at runtime, it's not suitable for this purpose
2348 for various technical reasons. (It's slow, which can't be
2349 really fixed.) In general, this option is not useful, and
2350 was only added to show that it's possible.
2351 There are two cases that must be considered when doing
2353 quality/bandwidth selection:
2354 1. Completely separate audio and video streams
2356 (DASH-like). Each of these streams contain either
2357 only audio or video, so you can mix and combine au‐
2358 dio/video bandwidths without restriction. This in‐
2359 tuitively matches best with the concept of select‐
2360 ing quality by track (what all_formats is supposed
2361 to do).
2362 2. Separate sets of muxed audio and video streams.
2364 Each version of the media contains both an audio
2365 and video stream, and they are interleaved. In or‐
2366 der not to waste bandwidth, you should only select
2367 one of these versions (if, for example, you select
2368 an audio stream, then video will be downloaded,
2369 even if you selected video from a different
2370 stream).
2371 mpv will still represent them as separate tracks,
2373 but will set the title of each track to muxed-N,
2374 where N is replaced with the youtube-dl format ID
2375 of the originating stream.
2376 Some sites will mix 1. and 2., but we assume that they do
2378 so for compatibility reasons, and there is no reason to
2379 use them at all.
2380 force_all_formats=<yes|no>
2382 If set to 'yes', and all_formats is also set to 'yes',
2383 this will try to represent all youtube-dl reported for‐
2384 mats as tracks, even if mpv would normally use the direct
2385 URL reported by it (default: yes).
2386 It appears this normally makes a difference if youtube-dl
2388 works on a master HLS playlist.
2389 If this is set to 'no', this specific kind of stream is
2391 treated like all_formats is set to 'no', and the stream
2392 selection as done by youtube-dl (via --ytdl-format) is
2393 used.
2394 use_manifests=<yes|no>
2396 Make mpv use the master manifest URL for formats like HLS
2397 and DASH, if available, allowing for video/audio selec‐
2398 tion in runtime (default: no). It's disabled ("no") by
2399 default for performance reasons.
2400 ytdl_path=youtube-dl
2402 Configure paths to youtube-dl's executable or a compati‐
2403 ble fork's. The paths should be separated by : on Unix
2404 and ; on Windows. mpv looks in order for the configured
2405 paths in PATH and in mpv's config directory. The de‐
2406 faults are "yt-dlp", "yt-dlp_x86" and "youtube-dl". On
2407 Windows the suffix extension ".exe" is always appended.
2408 Why do the option names mix _ and -?
2410 I have no idea.
2412 --ytdl-format=<ytdl|best|worst|mp4|webm|...>
2414 Video format/quality that is directly passed to youtube-dl. The
2415 possible values are specific to the website and the video, for a
2416 given url the available formats can be found with the command
2417 youtube-dl --list-formats URL. See youtube-dl's documentation
2418 for available aliases. (Default: bestvideo+bestaudio/best)
2419 The ytdl value does not pass a --format option to youtube-dl at
2421 all, and thus does not override its default. Note that sometimes
2422 youtube-dl returns a format that mpv cannot use, and in these
2423 cases the mpv default may work better.
2424 --ytdl-raw-options=<key>=<value>[,<key>=<value>[,...]]
2426 Pass arbitrary options to youtube-dl. Parameter and argument
2427 should be passed as a key-value pair. Options without argument
2428 must include =.
2429 There is no sanity checking so it's possible to break things
2431 (i.e. passing invalid parameters to youtube-dl).
2432 A proxy URL can be passed for youtube-dl to use it in parsing
2434 the website. This is useful for geo-restricted URLs. After
2435 youtube-dl parsing, some URLs also require a proxy for playback,
2436 so this can pass that proxy information to mpv. Take note that
2437 SOCKS proxies aren't supported and https URLs also bypass the
2438 proxy. This is a limitation in FFmpeg.
2439 This is a key/value list option. See List Options for details.
2441 Example
2443 • --ytdl-raw-options=username=user,password=pass
2445 • --ytdl-raw-options=force-ipv6=
2447 • --ytdl-raw-options=proxy=[http://127.0.0.1:3128]
2449 • --ytdl-raw-options-append=proxy=http://127.0.0.1:3128
2451 --load-stats-overlay=<yes|no>
2453 Enable the builtin script that shows useful playback information
2454 on a key binding (default: yes). By default, the i key is used
2455 (I to make the overlay permanent).
2456 --load-osd-console=<yes|no>
2458 Enable the built-in script that shows a console on a key binding
2459 and lets you enter commands (default: yes). The ` key is used to
2460 show the console by default, and ESC to hide it again.
2461 --load-auto-profiles=<yes|no|auto>
2463 Enable the builtin script that does auto profiles (default:
2464 auto). See Conditional auto profiles for details. auto will load
2465 the script, but immediately unload it if there are no condi‐
2466 tional profiles.
2467 --player-operation-mode=<cplayer|pseudo-gui>
2469 For enabling "pseudo GUI mode", which means that the defaults
2470 for some options are changed. This option should not normally be
2471 used directly, but only by mpv internally, or mpv-provided
2472 scripts, config files, or .desktop files. See PSEUDO GUI MODE
2473 for details.
2474 Watch Later
2476 --save-position-on-quit
2477 Always save the current playback position on quit. When this
2478 file is played again later, the player will seek to the old
2479 playback position on start. This does not happen if playback of
2480 a file is stopped in any other way than quitting. For example,
2481 going to the next file in the playlist will not save the posi‐
2482 tion, and start playback at beginning the next time the file is
2483 played.
2484 This behavior is disabled by default, but is always available
2486 when quitting the player with Shift+Q.
2487 See RESUMING PLAYBACK.
2489 --watch-later-directory=<path>
2491 The directory in which to store the "watch later" temporary
2492 files.
2493 If this option is unset, the files will be stored in a subdirec‐
2495 tory named "watch_later" underneath the local state directory
2496 (usually ~/.local/state/mpv/).
2497 --no-resume-playback
2499 Do not restore playback position from the watch_later configura‐
2500 tion subdirectory (usually ~/.config/mpv/watch_later/).
2501 --resume-playback-check-mtime
2503 Only restore the playback position from the watch_later configu‐
2504 ration subdirectory (usually ~/.config/mpv/watch_later/) if the
2505 file's modification time is the same as at the time of saving.
2506 This may prevent skipping forward in files with the same name
2507 which have different content. (Default: no)
2508 --watch-later-options=option1,option2,...
2510 The options that are saved in "watch later" files if they have
2511 been changed since when mpv started. These values will be re‐
2512 stored the next time the files are played. Note that the play‐
2513 back position is saved via the start option.
2514 When removing options, existing watch later data won't be modi‐
2516 fied and will still be applied fully, but new watch later data
2517 won't contain these options.
2518 This is a string list option. See List Options for details.
2520 Examples
2522 • --watch-later-options-remove=fullscreen The fullscreen
2524 state won't be saved to watch later files.
2525 • --watch-later-options-remove=volume --watch-later-op‐
2527 tions-remove=mute The volume and mute state won't be saved
2528 to watch later files.
2529 • --watch-later-options-clr No option will be saved to watch
2531 later files.
2532 --write-filename-in-watch-later-config
2534 Prepend the watch later config files with the name of the file
2535 they refer to. This is simply written as comment on the top of
2536 the file.
2537 WARNING:
2539 This option may expose privacy-sensitive information and is
2540 thus disabled by default.
2541 --ignore-path-in-watch-later-config
2543 Ignore path (i.e. use filename only) when using watch later fea‐
2544 ture. (Default: disabled)
2545 Video
2547 --vo=<driver>
2548 Specify the video output backend to be used. See VIDEO OUTPUT
2549 DRIVERS for details and descriptions of available drivers.
2550 --vd=<...>
2552 Specify a priority list of video decoders to be used, according
2553 to their family and name. See --ad for further details. Both of
2554 these options use the same syntax and semantics; the only dif‐
2555 ference is that they operate on different codec lists.
2556 NOTE:
2558 See --vd=help for a full list of available decoders.
2559 --vf=<filter1[=parameter1:parameter2:...],filter2,...>
2561 Specify a list of video filters to apply to the video stream.
2562 See VIDEO FILTERS for details and descriptions of the available
2563 filters. The option variants --vf-add, --vf-pre, --vf-del and
2564 --vf-clr exist to modify a previously specified list, but you
2565 should not need these for typical use.
2566 --untimed
2568 Do not sleep when outputting video frames. Useful for benchmarks
2569 when used with --no-audio.
2570 --framedrop=<mode>
2572 Skip displaying some frames to maintain A/V sync on slow sys‐
2573 tems, or playing high framerate video on video outputs that have
2574 an upper framerate limit.
2575 The argument selects the drop methods, and can be one of the
2577 following:
2578 <no> Disable any frame dropping. Not recommended, for testing
2580 only.
2581 <vo> Drop late frames on video output (default). This still
2583 decodes and filters all frames, but doesn't render them
2584 on the VO. Drops are indicated in the terminal status
2585 line as Dropped: field.
2586 In audio sync. mode, this drops frames that are outdated
2588 at the time of display. If the decoder is too slow, in
2589 theory all frames would have to be dropped (because all
2590 frames are too late) - to avoid this, frame dropping
2591 stops if the effective framerate is below 10 FPS.
2592 In display-sync. modes (see --video-sync), this affects
2594 only how A/V drops or repeats frames. If this mode is
2595 disabled, A/V desync will in theory not affect video
2596 scheduling anymore (much like the display-resample-desync
2597 mode). However, even if disabled, frames will still be
2598 skipped (i.e. dropped) according to the ratio between
2599 video and display frequencies.
2600 This is the recommended mode, and the default.
2602 <decoder>
2604 Old, decoder-based framedrop mode. (This is the same as
2605 --framedrop=yes in mpv 0.5.x and before.) This tells the
2606 decoder to skip frames (unless they are needed to decode
2607 future frames). May help with slow systems, but can pro‐
2608 duce unwatchable choppy output, or even freeze the dis‐
2609 play completely.
2610 This uses a heuristic which may not make sense, and in
2612 general cannot achieve good results, because the de‐
2613 coder's frame dropping cannot be controlled in a predict‐
2614 able manner. Not recommended.
2615 Even if you want to use this, prefer decoder+vo for bet‐
2617 ter results.
2618 The --vd-lavc-framedrop option controls what frames to
2620 drop.
2621 <decoder+vo>
2623 Enable both modes. Not recommended. Better than just de‐
2624 coder mode.
2625 NOTE:
2627 --vo=vdpau has its own code for the vo framedrop mode. Slight
2628 differences to other VOs are possible.
2629 --video-latency-hacks=<yes|no>
2631 Enable some things which tend to reduce video latency by 1 or 2
2632 frames (default: no). Note that this option might be removed
2633 without notice once the player's timing code does not inherently
2634 need to do these things anymore.
2635 This does:
2637 • Use the demuxer reported FPS for frame dropping. This avoids
2639 the player needing to decode 1 frame in advance, lowering to‐
2640 tal latency in effect. This also means that if the demuxer re‐
2641 ported FPS is wrong, or the video filter chain changes FPS
2642 (e.g. deinterlacing), then it could drop too many or not
2643 enough frames.
2644 • Disable waiting for the first video frame. Normally the player
2646 waits for the first video frame to be fully rendered before
2647 starting playback properly. Some VOs will lazily initialize
2648 stuff when rendering the first frame, so if this is not done,
2649 there is some likeliness that the VO has to drop some frames
2650 if rendering the first frame takes longer than needed.
2651 --override-display-fps=<fps>
2653 Set the display FPS used with the --video-sync=display-* modes.
2654 By default, a detected value is used. Keep in mind that setting
2655 an incorrect value (even if slightly incorrect) can ruin video
2656 playback. On multi-monitor systems, there is a chance that the
2657 detected value is from the wrong monitor.
2658 Set this option only if you have reason to believe the automati‐
2660 cally determined value is wrong.
2661 --display-fps=<fps>
2663 Deprecated alias for --override-display-fps.
2664 --hwdec=<api1,api2,...|no|auto|auto-safe|auto-copy>
2666 Specify the hardware video decoding API that should be used if
2667 possible. Whether hardware decoding is actually done depends on
2668 the video codec. If hardware decoding is not possible, mpv will
2669 fall back on software decoding.
2670 Hardware decoding is not enabled by default, to keep the
2672 out-of-the-box configuration as reliable as possible. However,
2673 when using modern hardware, hardware video decoding should work
2674 correctly, offering reduced CPU usage, and possibly lower power
2675 consumption. On older systems, it may be necessary to use hard‐
2676 ware decoding due to insufficient CPU resources; and even on
2677 modern systems, sufficiently complex content (eg: 4K60 AV1) may
2678 require it.
2679 NOTE:
2681 Use the Ctrl+h shortcut to toggle hardware decoding at run‐
2682 time. It toggles this option between auto-safe and no.
2683 If you decide you want to use hardware decoding by default,
2685 the general recommendation is to try out decoding with the
2686 command line option, and prove to yourself that it works as
2687 desired for the content you care about. After that, you can
2688 add it to your config file.
2689 When testing, you should start by using hwdec=auto-safe as it
2691 will limit itself to choosing from hwdecs that are actively
2692 supported by the development team. If that doesn't result in
2693 working hardware decoding, you can try hwdec=auto to have it
2694 attempt to load every possible hwdec, but if auto-safe didn't
2695 work, you will probably need to know exactly which hwdec
2696 matches your hardware and read up on that entry below.
2697 If auto-safe or auto produced the desired results, we recom‐
2699 mend just sticking with that and only setting a specific
2700 hwdec in your config file if it is really necessary.
2701 If you use the Ubuntu package, keep in mind that their
2703 /etc/mpv/mpv.conf contains hwdec=vaapi, which is less than
2704 ideal as it may not be the right choice for your system, and
2705 it may end up using an inefficient wrapper library under the
2706 covers. We recommend removing this line or deleting the file
2707 altogether.
2708 NOTE:
2710 Even if enabled, hardware decoding is still only white-listed
2711 for some codecs. See --hwdec-codecs to enable hardware decod‐
2712 ing in more cases.
2713 Which method to choose?
2715 • If you only want to enable hardware decoding at runtime,
2717 don't set the parameter, or put hwdec=no into your mpv.conf
2718 (relevant on distros which force-enable it by default, such
2719 as on Ubuntu). Use the Ctrl+h default binding to enable it
2720 at runtime.
2721 • If you're not sure, but want hardware decoding always en‐
2723 abled by default, put hwdec=auto-safe into your mpv.conf,
2724 and acknowledge that this may cause problems.
2725 • If you want to test available hardware decoding methods,
2727 pass --hwdec=auto --hwdec-codecs=all and look at the termi‐
2728 nal output.
2729 • If you're a developer, or want to perform elaborate tests,
2731 you may need any of the other possible option values.
2732 This option accepts a comma delimited list of api types, along
2734 with certain special values:
2735 no always use software decoding (default)
2737 auto-safe
2739 enable any whitelisted hw decoder (see below)
2740 auto forcibly enable any hw decoder found (see below)
2742 yes exactly the same as auto-safe
2744 auto-copy
2746 enable best hw decoder with copy-back (see below)
2747 NOTE:
2749 Special values can be mixed with api names. eg: vaapi,auto
2750 will try and use the vaapi hwdec, and if that fails, will run
2751 through the normal auto logic.
2752 Actively supported hwdecs:
2754 d3d11va
2756 requires --vo=gpu with --gpu-context=d3d11 or --gpu-con‐
2757 text=angle (Windows 8+ only)
2758 d3d11va-copy
2760 copies video back to system RAM (Windows 8+ only)
2761 videotoolbox
2763 requires --vo=gpu (macOS 10.8 and up), or --vo=libmpv
2764 (iOS 9.0 and up)
2765 videotoolbox-copy
2767 copies video back into system RAM (macOS 10.8 or iOS 9.0
2768 and up)
2769 vaapi requires --vo=gpu, --vo=vaapi or --vo=dmabuf-wayland
2771 (Linux only)
2772 vaapi-copy
2774 copies video back into system RAM (Linux with some GPUs
2775 only)
2776 nvdec requires --vo=gpu (Any platform CUDA is available)
2778 nvdec-copy
2780 copies video back to system RAM (Any platform CUDA is
2781 available)
2782 drm requires --vo=gpu (Linux only)
2784 drm-copy
2786 copies video back to system RAM (Linux only)
2787 vulkan requires --vo=gpu-next (Any platform with Vulkan Video
2789 Decoding)
2790 vulkan-copy
2792 copies video back to system RAM (Any platform with Vulkan
2793 Video Decoding)
2794 Other hwdecs (only use if you know you have to):
2796 dxva2 requires --vo=gpu with --gpu-context=d3d11, --gpu-con‐
2798 text=angle or --gpu-context=dxinterop (Windows only)
2799 dxva2-copy
2801 copies video back to system RAM (Windows only)
2802 vdpau requires --vo=gpu with X11, or --vo=vdpau (Linux only)
2804 vdpau-copy
2806 copies video back into system RAM (Linux with some GPUs
2807 only)
2808 mediacodec
2810 requires --vo=gpu --gpu-context=android or --vo=media‐
2811 codec_embed (Android only)
2812 mediacodec-copy
2814 copies video back to system RAM (Android only)
2815 mmal requires --vo=gpu (Raspberry Pi only - default if avail‐
2817 able)
2818 mmal-copy
2820 copies video back to system RAM (Raspberry Pi only)
2821 cuda requires --vo=gpu (Any platform CUDA is available)
2823 cuda-copy
2825 copies video back to system RAM (Any platform CUDA is
2826 available)
2827 crystalhd
2829 copies video back to system RAM (Any platform supported
2830 by hardware)
2831 rkmpp requires --vo=gpu (some RockChip devices only)
2833 auto tries to automatically enable hardware decoding using the
2835 first available method. This still depends what VO you are us‐
2836 ing. For example, if you are not using --vo=gpu or --vo=vdpau,
2837 vdpau decoding will never be enabled. Also note that if the
2838 first found method doesn't actually work, it will always fall
2839 back to software decoding, instead of trying the next method
2840 (might matter on some Linux systems).
2841 auto-safe is similar to auto, but allows only whitelisted meth‐
2843 ods that are considered "safe". This is supposed to be a reason‐
2844 able way to enable hardware decdoding by default in a config
2845 file (even though you shouldn't do that anyway; prefer runtime
2846 enabling with Ctrl+h). Unlike auto, this will not try to enable
2847 unknown or known-to-be-bad methods. In addition, this may dis‐
2848 able hardware decoding in other situations when it's known to
2849 cause problems, but currently this mechanism is quite primitive.
2850 (As an example for something that still causes problems: certain
2851 combinations of HEVC and Intel chips on Windows tend to cause
2852 mpv to crash, most likely due to driver bugs.)
2853 auto-copy-safe selects the union of methods selected with
2855 auto-safe and auto-copy.
2856 auto-copy selects only modes that copy the video data back to
2858 system memory after decoding. This selects modes like vaapi-copy
2859 (and so on). If none of these work, hardware decoding is dis‐
2860 abled. This mode is usually guaranteed to incur no additional
2861 quality loss compared to software decoding (assuming modern
2862 codecs and an error free video stream), and will allow CPU pro‐
2863 cessing with video filters. This mode works with all video fil‐
2864 ters and VOs.
2865 Because these copy the decoded video back to system RAM, they're
2867 often less efficient than the direct modes, and may not help too
2868 much over software decoding if you are short on CPU resources.
2869 NOTE:
2871 Most non-copy methods only work with the OpenGL GPU backend.
2872 Currently, only the vaapi, nvdec, cuda and vulkan methods
2873 work with Vulkan.
2874 The vaapi mode, if used with --vo=gpu, requires Mesa 11, and
2876 most likely works with Intel and AMD GPUs only. It also requires
2877 the opengl EGL backend.
2878 nvdec and nvdec-copy are the newest, and recommended method to
2880 do hardware decoding on Nvidia GPUs.
2881 cuda and cuda-copy are an older implementation of hardware de‐
2883 coding on Nvidia GPUs that uses Nvidia's bitstream parsers
2884 rather than FFmpeg's. This can lead to feature deficiencies,
2885 such as incorrect playback of HDR content, and nvdec/nvdec-copy
2886 should always be preferred unless you specifically need Nvidia's
2887 deinterlacing algorithms. To use this deinterlacing you must
2888 pass the option: vd-lavc-o=deint=[weave|bob|adaptive]. Pass
2889 weave (or leave the option unset) to not attempt any deinterlac‐
2890 ing.
2891 Quality reduction with hardware decoding
2893 In theory, hardware decoding does not reduce video
2895 quality (at least for the codecs h264 and HEVC). How‐
2896 ever, due to restrictions in video output APIs, as
2897 well as bugs in the actual hardware decoders, there
2898 can be some loss, or even blatantly incorrect results.
2899 This has largely ceased to be a problem with modern
2900 hardware, but there is a lot of hardware out there, so
2901 caveat emptor. Known problems are discussed below, but
2902 the list cannot be considered exhaustive, as even
2903 hwdecs that work well on certain hardware generations
2904 may be problematic on other ones.
2905 In some cases, RGB conversion is forced, which means
2907 the RGB conversion is performed by the hardware decod‐
2908 ing API, instead of the shaders used by --vo=gpu. This
2909 means certain colorspaces may not display correctly,
2910 and certain filtering (such as debanding) cannot be
2911 applied in an ideal way. This will also usually force
2912 the use of low quality chroma scalers instead of the
2913 one specified by --cscale. In other cases, hardware
2914 decoding can also reduce the bit depth of the decoded
2915 image, which can introduce banding or precision loss
2916 for 10-bit files.
2917 vdpau always does RGB conversion in hardware, which
2919 does not support newer colorspaces like BT.2020 cor‐
2920 rectly. However, vdpau doesn't support 10 bit or HDR
2921 encodings, so these limitations are unlikely to be
2922 relevant.
2923 dxva2 is not safe. It appears to always use BT.601 for
2925 forced RGB conversion, but actual behavior depends on
2926 the GPU drivers. Some drivers appear to convert to
2927 limited range RGB, which gives a faded appearance. In
2928 addition to driver-specific behavior, global system
2929 settings might affect this additionally. This can give
2930 incorrect results even with completely ordinary video
2931 sources.
2932 rpi always uses the hardware overlay renderer, even
2934 with --vo=gpu.
2935 mediacodec is not safe. It forces RGB conversion (not
2937 with -copy) and how well it handles non-standard col‐
2938 orspaces is not known. In the rare cases where 10-bit
2939 is supported the bit depth of the output will be re‐
2940 duced to 8.
2941 cuda should usually be safe, but depending on how a
2943 file/stream has been mixed, it has been reported to
2944 corrupt the timestamps causing glitched, flashing
2945 frames. It can also sometimes cause massive framedrops
2946 for unknown reasons. Caution is advised, and nvdec
2947 should always be preferred.
2948 crystalhd is not safe. It always converts to 4:2:2
2950 YUV, which may be lossy, depending on how chroma
2951 sub-sampling is done during conversion. It also dis‐
2952 cards the top left pixel of each frame for some rea‐
2953 son.
2954 If you run into any weird decoding issues, frame
2956 glitches or discoloration, and you have --hwdec turned
2957 on, the first thing you should try is disabling it.
2958 --gpu-hwdec-interop=<auto|all|no|name>
2960 This option is for troubleshooting hwdec interop issues. Since
2961 it's a debugging option, its semantics may change at any time.
2962 This is useful for the gpu and libmpv VOs for selecting which
2964 hwdec interop context to use exactly. Effectively it also can be
2965 used to block loading of certain backends.
2966 If set to auto (default), the behavior depends on the VO: for
2968 gpu, it does nothing, and the interop context is loaded on de‐
2969 mand (when the decoder probes for --hwdec support). For libmpv,
2970 which has has no on-demand loading, this is equivalent to all.
2971 The empty string is equivalent to auto.
2973 If set to all, it attempts to load all interop contexts at GL
2975 context creation time.
2976 Other than that, a specific backend can be set, and the list of
2978 them can be queried with help (mpv CLI only).
2979 Runtime changes to this are ignored (the current option value is
2981 used whenever the renderer is created).
2982 The old aliases --opengl-hwdec-interop and --hwdec-preload are
2984 barely related to this anymore, but will be somewhat compatible
2985 in some cases.
2986 --hwdec-extra-frames=<N>
2988 Number of GPU frames hardware decoding should preallocate (de‐
2989 fault: see --list-options output). If this is too low, frame al‐
2990 location may fail during decoding, and video frames might get
2991 dropped and/or corrupted. Setting it too high simply wastes GPU
2992 memory and has no advantages.
2993 This value is used only for hardware decoding APIs which require
2995 preallocating surfaces (known examples include d3d11va and
2996 vaapi). For other APIs, frames are allocated as needed. The de‐
2997 tails depend on the libavcodec implementations of the hardware
2998 decoders.
2999 The required number of surfaces depends on dynamic runtime situ‐
3001 ations. The default is a fixed value that is thought to be suf‐
3002 ficient for most uses. But in certain situations, it may not be
3003 enough.
3004 --hwdec-image-format=<name>
3006 Set the internal pixel format used by hardware decoding via
3007 --hwdec (default no). The special value no selects an implemen‐
3008 tation specific standard format. Most decoder implementations
3009 support only one format, and will fail to initialize if the for‐
3010 mat is not supported.
3011 Some implementations might support multiple formats. In particu‐
3013 lar, videotoolbox is known to require uyvy422 for good perfor‐
3014 mance on some older hardware. d3d11va can always use yuv420p,
3015 which uses an opaque format, with likely no advantages.
3016 --cuda-decode-device=<auto|0..>
3018 Choose the GPU device used for decoding when using the cuda or
3019 nvdec hwdecs with the OpenGL GPU backend, and with the cuda-copy
3020 or nvdec-copy hwdecs in all cases.
3021 For the OpenGL GPU backend, the default device used for decoding
3023 is the one being used to provide gpu output (and in the vast ma‐
3024 jority of cases, only one GPU will be present).
3025 For the copy hwdecs, the default device will be the first device
3027 enumerated by the CUDA libraries - however that is done.
3028 For the Vulkan GPU backend, decoding must always happen on the
3030 display device, and this option has no effect.
3031 --vaapi-device=<device file>
3033 Choose the DRM device for vaapi-copy. This should be the path to
3034 a DRM device file. (Default: /dev/dri/renderD128)
3035 --panscan=<0.0-1.0>
3037 Enables pan-and-scan functionality (cropping the sides of e.g. a
3038 16:9 video to make it fit a 4:3 display without black bands).
3039 The range controls how much of the image is cropped. May not
3040 work with all video output drivers.
3041 This option has no effect if --video-unscaled option is used.
3043 --video-aspect-override=<ratio|no>
3045 Override video aspect ratio, in case aspect information is in‐
3046 correct or missing in the file being played.
3047 These values have special meaning:
3049 0 disable aspect ratio handling, pretend the video has
3051 square pixels
3052 no same as 0
3054 -1 use the video stream or container aspect (default)
3056 But note that handling of these special values might change in
3058 the future.
3059 Examples
3061 • --video-aspect-override=4:3 or --video-aspect-over‐
3063 ride=1.3333
3064 • --video-aspect-override=16:9 or --video-aspect-over‐
3066 ride=1.7777
3067 • --no-video-aspect-override or --video-aspect-override=no
3069 --video-aspect-method=<bitstream|container>
3071 This sets the default video aspect determination method (if the
3072 aspect is _not_ overridden by the user with --video-aspect-over‐
3073 ride or others).
3074 container
3076 Strictly prefer the container aspect ratio. This is ap‐
3077 parently the default behavior with VLC, at least with Ma‐
3078 troska. Note that if the container has no aspect ratio
3079 set, the behavior is the same as with bitstream.
3080 bitstream
3082 Strictly prefer the bitstream aspect ratio, unless the
3083 bitstream aspect ratio is not set. This is apparently the
3084 default behavior with XBMC/kodi, at least with Matroska.
3085 The current default for mpv is container.
3087 Normally you should not set this. Try the various choices if you
3089 encounter video that has the wrong aspect ratio in mpv, but
3090 seems to be correct in other players.
3091 --video-unscaled=<no|yes|downscale-big>
3093 Disable scaling of the video. If the window is larger than the
3094 video, black bars are added. Otherwise, the video is cropped,
3095 unless the option is set to downscale-big, in which case the
3096 video is fit to window. The video still can be influenced by the
3097 other --video-... options. This option disables the effect of
3098 --panscan.
3099 Note that the scaler algorithm may still be used, even if the
3101 video isn't scaled. For example, this can influence chroma con‐
3102 version. The video will also still be scaled in one dimension if
3103 the source uses non-square pixels (e.g. anamorphic widescreen
3104 DVDs).
3105 This option is disabled if the --no-keepaspect option is used.
3107 --video-pan-x=<value>, --video-pan-y=<value>
3109 Moves the displayed video rectangle by the given value in the X
3110 or Y direction. The unit is in fractions of the size of the
3111 scaled video (the full size, even if parts of the video are not
3112 visible due to panscan or other options).
3113 For example, displaying a 1280x720 video fullscreen on a
3115 1680x1050 screen with --video-pan-x=-0.1 would move the video
3116 168 pixels to the left (making 128 pixels of the source video
3117 invisible).
3118 This option is disabled if the --no-keepaspect option is used.
3120 --video-rotate=<0-359|no>
3122 Rotate the video clockwise, in degrees. If no is given, the
3123 video is never rotated, even if the file has rotation metadata.
3124 (The rotation value is added to the rotation metadata, which
3125 means the value 0 would rotate the video according to the rota‐
3126 tion metadata.)
3127 When using hardware decoding without copy-back, only 90° steps
3129 work, while software decoding and hardware decoding methods that
3130 copy the video back to system memory support all values between
3131 0 and 359.
3132 --video-zoom=<value>
3134 Adjust the video display scale factor by the given value. The
3135 parameter is given log 2. For example, --video-zoom=0 is un‐
3136 scaled, --video-zoom=1 is twice the size, --video-zoom=-2 is one
3137 fourth of the size, and so on.
3138 This option is disabled if the --no-keepaspect option is used.
3140 --video-scale-x=<value>, --video-scale-y=<value>
3142 Multiply the video display size with the given value (default:
3143 1.0). If a non-default value is used, this will be different
3144 from the window size, so video will be either cut off, or black
3145 bars are added.
3146 This value is multiplied with the value derived from
3148 --video-zoom and the normal video aspect ratio. This option is
3149 disabled if the --no-keepaspect option is used.
3150 --video-align-x=<-1-1>, --video-align-y=<-1-1>
3152 Moves the video rectangle within the black borders, which are
3153 usually added to pad the video to screen if video and screen as‐
3154 pect ratios are different. --video-align-y=-1 would move the
3155 video to the top of the screen (leaving a border only on the
3156 bottom), a value of 0 centers it (default), and a value of 1
3157 would put the video at the bottom of the screen.
3158 If video and screen aspect match perfectly, these options do
3160 nothing.
3161 This option is disabled if the --no-keepaspect option is used.
3163 --video-margin-ratio-left=<val>, --video-margin-ratio-right=<val>,
3165 --video-margin-ratio-top=<val>, --video-margin-ratio-bottom=<val>
3166 Set extra video margins on each border (default: 0). Each value
3167 is a ratio of the window size, using a range 0.0-1.0. For exam‐
3168 ple, setting the option --video-margin-ratio-right=0.2 at a win‐
3169 dow size of 1000 pixels will add a 200 pixels border on the
3170 right side of the window.
3171 The video is "boxed" by these margins. The window size is not
3173 changed. In particular it does not enlarge the window, and the
3174 margins will cause the video to be downscaled by default. This
3175 may or may not change in the future.
3176 The margins are applied after 90° video rotation, but before any
3178 other video transformations.
3179 This option is disabled if the --no-keepaspect option is used.
3181 Subtitles still may use the margins, depending on --sub-use-mar‐
3183 gins and similar options.
3184 These options were created for the OSC. Some odd decisions, such
3186 as making the margin values a ratio (instead of pixels), were
3187 made for the sake of the OSC. It's possible that these options
3188 may be replaced by ones that are more generally useful. The be‐
3189 havior of these options may change to fit OSC requirements bet‐
3190 ter, too.
3191 --correct-pts, --no-correct-pts
3193 --no-correct-pts switches mpv to a mode where video timing is
3194 determined using a fixed framerate value (either using the --fps
3195 option, or using file information). Sometimes, files with very
3196 broken timestamps can be played somewhat well in this mode. Note
3197 that video filters, subtitle rendering, seeking (including
3198 hr-seeks and backstepping), and audio synchronization can be
3199 completely broken in this mode.
3200 --fps=<float>
3202 Override video framerate. Useful if the original value is wrong
3203 or missing.
3204 NOTE:
3206 Works in --no-correct-pts mode only.
3207 --deinterlace=<yes|no>
3209 Enable or disable interlacing (default: no). Interlaced video
3210 shows ugly comb-like artifacts, which are visible on fast move‐
3211 ment. Enabling this typically inserts the yadif video filter in
3212 order to deinterlace the video, or lets the video output apply
3213 deinterlacing if supported.
3214 This behaves exactly like the deinterlace input property (usu‐
3216 ally mapped to d).
3217 Keep in mind that this will conflict with manually inserted
3219 deinterlacing filters, unless you take care. (Since mpv 0.27.0,
3220 even the hardware deinterlace filters will conflict. Also since
3221 that version, --deinterlace=auto was removed, which used to mean
3222 that the default interlacing option of possibly inserted video
3223 filters was used.)
3224 Note that this will make video look worse if it's not actually
3226 interlaced.
3227 --frames=<number>
3229 Play/convert only first <number> video frames, then quit.
3230 --frames=0 loads the file, but immediately quits before initial‐
3232 izing playback. (Might be useful for scripts which just want to
3233 determine some file properties.)
3234 For audio-only playback, any value greater than 0 will quit
3236 playback immediately after initialization. The value 0 works as
3237 with video.
3238 --video-output-levels=<outputlevels>
3240 RGB color levels used with YUV to RGB conversion. Normally, out‐
3241 put devices such as PC monitors use full range color levels.
3242 However, some TVs and video monitors expect studio RGB levels.
3243 Providing full range output to a device expecting studio level
3244 input results in crushed blacks and whites, the reverse in dim
3245 gray blacks and dim whites.
3246 Not all VOs support this option. Some will silently ignore it.
3248 Available color ranges are:
3250 auto automatic selection (equals to full range) (default)
3252 limited
3254 limited range (16-235 per component), studio levels
3255 full full range (0-255 per component), PC levels
3257 NOTE:
3259 It is advisable to use your graphics driver's color range op‐
3260 tion instead, if available.
3261 --hwdec-codecs=<codec1,codec2,...|all>
3263 Allow hardware decoding for a given list of codecs only. The
3264 special value all always allows all codecs.
3265 You can get the list of allowed codecs with mpv --vd=help. Re‐
3267 move the prefix, e.g. instead of lavc:h264 use h264.
3268 By default, this is set to h264,vc1,hevc,vp8,vp9,av1. Note that
3270 the hardware acceleration special codecs like h264_vdpau are not
3271 relevant anymore, and in fact have been removed from Libav in
3272 this form.
3273 This is usually only needed with broken GPUs, where a codec is
3275 reported as supported, but decoding causes more problems than it
3276 solves.
3277 Example
3279 mpv --hwdec=vdpau --vo=vdpau --hwdec-codecs=h264,mpeg2video
3281 Enable vdpau decoding for h264 and mpeg2 only.
3282 --vd-lavc-check-hw-profile=<yes|no>
3284 Check hardware decoder profile (default: yes). If no is set, the
3285 highest profile of the hardware decoder is unconditionally se‐
3286 lected, and decoding is forced even if the profile of the video
3287 is higher than that. The result is most likely broken decoding,
3288 but may also help if the detected or reported profiles are some‐
3289 how incorrect.
3290 --vd-lavc-software-fallback=<yes|no|N>
3292 Fallback to software decoding if the hardware-accelerated de‐
3293 coder fails (default: 3). If this is a number, then fallback
3294 will be triggered if N frames fail to decode in a row. 1 is
3295 equivalent to yes.
3296 Setting this to a higher number might break the playback start
3298 fallback: if a fallback happens, parts of the file will be
3299 skipped, approximately by to the number of packets that could
3300 not be decoded. Values below an unspecified count will not have
3301 this problem, because mpv retains the packets.
3302 --vd-lavc-film-grain=<auto|cpu|gpu>
3304 Enables film grain application on the GPU. If video decoding is
3305 done on the CPU, doing film grain application on the GPU can
3306 speed up decoding. This option can also help hardware decoding,
3307 as it can reduce the number of frame copies done.
3308 By default, it's set to auto, so if the VO supports film grain
3310 application, then it will be treated as gpu. If the VO does not
3311 support this, then it will be treated as cpu, regardless of the
3312 setting. Currently, only gpu-next supports film grain applica‐
3313 tion.
3314 --vd-lavc-dr=<auto|yes|no>
3316 Enable direct rendering (default: auto). If this is set to yes,
3317 the video will be decoded directly to GPU video memory (or stag‐
3318 ing buffers). This can speed up video upload, and may help with
3319 large resolutions or slow hardware. This works only with the
3320 following VOs:
3321 • gpu: requires at least OpenGL 4.4 or Vulkan.
3323 • libmpv: The libmpv render API has optional support.
3325 The auto option will try to guess whether DR can improve perfor‐
3327 mance on your particular hardware. Currently this enables it on
3328 AMD or NVIDIA if using OpenGL or unconditionally if using
3329 Vulkan.
3330 Using video filters of any kind that write to the image data (or
3332 output newly allocated frames) will silently disable the DR code
3333 path.
3334 --vd-lavc-bitexact
3336 Only use bit-exact algorithms in all decoding steps (for codec
3337 testing).
3338 --vd-lavc-fast (MPEG-1/2 and H.264 only)
3340 Enable optimizations which do not comply with the format speci‐
3341 fication and potentially cause problems, like simpler dequanti‐
3342 zation, simpler motion compensation, assuming use of the default
3343 quantization matrix, assuming YUV 4:2:0 and skipping a few
3344 checks to detect damaged bitstreams.
3345 --vd-lavc-o=<key>=<value>[,<key>=<value>[,...]]
3347 Pass AVOptions to libavcodec decoder. Note, a patch to make the
3348 o= unneeded and pass all unknown options through the AVOption
3349 system is welcome. A full list of AVOptions can be found in the
3350 FFmpeg manual.
3351 Some options which used to be direct options can be set with
3353 this mechanism, like bug, gray, idct, ec, vismv, skip_top (was
3354 st), skip_bottom (was sb), debug.
3355 This is a key/value list option. See List Options for details.
3357 Example
3359 --vd-lavc-o=debug=pict
3361 --vd-lavc-show-all=<yes|no>
3363 Show even broken/corrupt frames (default: no). If this option is
3364 set to no, libavcodec won't output frames that were either de‐
3365 coded before an initial keyframe was decoded, or frames that are
3366 recognized as corrupted.
3367 --vd-lavc-skiploopfilter=<skipvalue> (H.264, HEVC only)
3369 Skips the loop filter (AKA deblocking) during decoding. Since
3370 the filtered frame is supposed to be used as reference for de‐
3371 coding dependent frames, this has a worse effect on quality than
3372 not doing deblocking on e.g. MPEG-2 video. But at least for high
3373 bitrate HDTV, this provides a big speedup with little visible
3374 quality loss. Codecs other than H.264 or HEVC may have partial
3375 support for this option (often only all and none).
3376 <skipvalue> can be one of the following:
3378 none Never skip.
3380 default
3382 Skip useless processing steps (e.g. 0 size packets in
3383 AVI).
3384 nonref Skip frames that are not referenced (i.e. not used for
3386 decoding other frames, the error cannot "build up").
3387 bidir Skip B-Frames.
3389 nonkey Skip all frames except keyframes.
3391 all Skip all frames.
3393 --vd-lavc-skipidct=<skipvalue> (MPEG-1/2/4 only)
3395 Skips the IDCT step. This degrades quality a lot in almost all
3396 cases (see skiploopfilter for available skip values).
3397 --vd-lavc-skipframe=<skipvalue>
3399 Skips decoding of frames completely. Big speedup, but jerky mo‐
3400 tion and sometimes bad artifacts (see skiploopfilter for avail‐
3401 able skip values).
3402 --vd-lavc-framedrop=<skipvalue>
3404 Set framedropping mode used with --framedrop (see skiploopfilter
3405 for available skip values).
3406 --vd-lavc-threads=<N>
3408 Number of threads to use for decoding. Whether threading is ac‐
3409 tually supported depends on codec (default: 0). 0 means autode‐
3410 tect number of cores on the machine and use that, up to the max‐
3411 imum of 16. You can set more than 16 threads manually.
3412 --vd-lavc-assume-old-x264=<yes|no>
3414 Assume the video was encoded by an old, buggy x264 version (de‐
3415 fault: no). Normally, this is autodetected by libavcodec. But
3416 if the bitstream contains no x264 version info (or it was some‐
3417 how skipped), and the stream was in fact encoded by an old x264
3418 version (build 150 or earlier), and if the stream uses 4:4:4
3419 chroma, then libavcodec will by default show corrupted video.
3420 This option sets the libavcodec x264_build option to 150, which
3421 means that if the stream contains no version info, or was not
3422 encoded by x264 at all, it assumes it was encoded by the old
3423 version. Enabling this option is pretty safe if you want your
3424 broken files to work, but in theory this can break on streams
3425 not encoded by x264, or if a stream encoded by a newer x264 ver‐
3426 sion contains no version info.
3427 --swapchain-depth=<N>
3429 Allow up to N in-flight frames. This essentially controls the
3430 frame latency. Increasing the swapchain depth can improve pipe‐
3431 lining and prevent missed vsyncs, but increases visible latency.
3432 This option only mandates an upper limit, the implementation can
3433 use a lower latency than requested internally. A setting of 1
3434 means that the VO will wait for every frame to become visible
3435 before starting to render the next frame. (Default: 3)
3436 Audio
3438 --audio-pitch-correction=<yes|no>
3439 If this is enabled (default), playing with a speed different
3440 from normal automatically inserts the scaletempo2 audio filter.
3441 For details, see audio filter section.
3442 --audio-device=<name>
3444 Use the given audio device. This consists of the audio output
3445 name, e.g. alsa, followed by /, followed by the audio output
3446 specific device name. The default value for this option is auto,
3447 which tries every audio output in preference order with the de‐
3448 fault device.
3449 You can list audio devices with --audio-device=help. This out‐
3451 puts the device name in quotes, followed by a description. The
3452 device name is what you have to pass to the --audio-device op‐
3453 tion. The list of audio devices can be retrieved by API by using
3454 the audio-device-list property.
3455 While the option normally takes one of the strings as indicated
3457 by the methods above, you can also force the device for most AOs
3458 by building it manually. For example name/foobar forces the AO
3459 name to use the device foobar. However, the --ao option will
3460 strictly force a specific AO. To avoid confusion, don't use --ao
3461 and --audio-device together.
3462 Example for ALSA
3464 MPlayer and mplayer2 required you to replace any ','
3466 with '.' and any ':' with '=' in the ALSA device name.
3467 For example, to use the device named dmix:default, you
3468 had to do:
3469 -ao alsa:device=dmix=default
3470 In mpv you could instead use:
3472 --audio-device=alsa/dmix:default
3473 --audio-exclusive=<yes|no>
3475 Enable exclusive output mode. In this mode, the system is usu‐
3476 ally locked out, and only mpv will be able to output audio.
3477 This only works for some audio outputs, such as wasapi, coreau‐
3479 dio and pipewire. Other audio outputs silently ignore this op‐
3480 tion. They either have no concept of exclusive mode, or the mpv
3481 side of the implementation is missing.
3482 --audio-fallback-to-null=<yes|no>
3484 If no audio device can be opened, behave as if --ao=null was
3485 given. This is useful in combination with --audio-device: in‐
3486 stead of causing an error if the selected device does not exist,
3487 the client API user (or a Lua script) could let playback con‐
3488 tinue normally, and check the current-ao and audio-device-list
3489 properties to make high-level decisions about how to continue.
3490 --ao=<driver>
3492 Specify the audio output drivers to be used. See AUDIO OUTPUT
3493 DRIVERS for details and descriptions of available drivers.
3494 --af=<filter1[=parameter1:parameter2:...],filter2,...>
3496 Specify a list of audio filters to apply to the audio stream.
3497 See AUDIO FILTERS for details and descriptions of the available
3498 filters. The option variants --af-add, --af-pre, --af-del and
3499 --af-clr exist to modify a previously specified list, but you
3500 should not need these for typical use.
3501 --audio-spdif=<codecs>
3503 List of codecs for which compressed audio passthrough should be
3504 used. This works for both classic S/PDIF and HDMI.
3505 Possible codecs are ac3, dts, dts-hd, eac3, truehd. Multiple
3507 codecs can be specified by separating them with ,. dts refers to
3508 low bitrate DTS core, while dts-hd refers to DTS MA (receiver
3509 and OS support varies). If both dts and dts-hd are specified, it
3510 behaves equivalent to specifying dts-hd only.
3511 In earlier mpv versions you could use --ad to force the spdif
3513 wrapper. This does not work anymore.
3514 Warning
3516 There is not much reason to use this. HDMI supports
3518 uncompressed multichannel PCM, and mpv supports loss‐
3519 less DTS-HD decoding via FFmpeg's new DCA decoder
3520 (based on libdcadec).
3521 --ad=<decoder1,decoder2,...[-]>
3523 Specify a priority list of audio decoders to be used, according
3524 to their decoder name. When determining which decoder to use,
3525 the first decoder that matches the audio format is selected. If
3526 that is unavailable, the next decoder is used. Finally, it tries
3527 all other decoders that are not explicitly selected or rejected
3528 by the option.
3529 - at the end of the list suppresses fallback on other available
3531 decoders not on the --ad list. + in front of an entry forces the
3532 decoder. Both of these should not normally be used, because they
3533 break normal decoder auto-selection! Both of these methods are
3534 deprecated.
3535 Examples
3537 --ad=mp3float
3539 Prefer the FFmpeg/Libav mp3float decoder over all
3540 other MP3 decoders.
3541 --ad=help
3543 List all available decoders.
3544 Warning
3546 Enabling compressed audio passthrough (AC3 and DTS via
3548 SPDIF/HDMI) with this option is not possible. Use
3549 --audio-spdif instead.
3550 --volume=<value>
3552 Set the startup volume. 0 means silence, 100 means no volume re‐
3553 duction or amplification. Negative values can be passed for com‐
3554 patibility, but are treated as 0.
3555 Since mpv 0.18.1, this always controls the internal mixer (aka
3557 "softvol").
3558 --replaygain=<no|track|album>
3560 Adjust volume gain according to replaygain values stored in the
3561 file metadata. With --replaygain=no (the default), perform no
3562 adjustment. With --replaygain=track, apply track gain. With
3563 --replaygain=album, apply album gain if present and fall back to
3564 track gain otherwise.
3565 --replaygain-preamp=<db>
3567 Pre-amplification gain in dB to apply to the selected replaygain
3568 gain (default: 0).
3569 --replaygain-clip=<yes|no>
3571 Prevent clipping caused by replaygain by automatically lowering
3572 the gain (default). Use --replaygain-clip=no to disable this.
3573 --replaygain-fallback=<db>
3575 Gain in dB to apply if the file has no replay gain tags. This
3576 option is always applied if the replaygain logic is somehow in‐
3577 active. If this is applied, no other replaygain options are ap‐
3578 plied.
3579 --audio-delay=<sec>
3581 Audio delay in seconds (positive or negative float value). Posi‐
3582 tive values delay the audio, and negative values delay the
3583 video.
3584 --mute=<yes|no|auto>
3586 Set startup audio mute status (default: no).
3587 auto is a deprecated possible value that is equivalent to no.
3589 See also: --volume.
3591 --softvol=<no|yes|auto>
3593 Deprecated/unfunctional. Before mpv 0.18.1, this used to control
3594 whether to use the volume controls of the audio output driver or
3595 the internal mpv volume filter.
3596 The current behavior is that softvol is always enabled, i.e. as
3598 if this option is set to yes. The other behaviors are not avail‐
3599 able anymore, although auto almost matches current behavior in
3600 most cases.
3601 The no behavior is still partially available through the ao-vol‐
3603 ume and ao-mute properties. But there are no options to reset
3604 these.
3605 --audio-demuxer=<[+]name>
3607 Use this audio demuxer type when using --audio-file. Use a '+'
3608 before the name to force it; this will skip some checks. Give
3609 the demuxer name as printed by --audio-demuxer=help.
3610 --ad-lavc-ac3drc=<level>
3612 Select the Dynamic Range Compression level for AC-3 audio
3613 streams. <level> is a float value ranging from 0 to 1, where 0
3614 means no compression (which is the default) and 1 means full
3615 compression (make loud passages more silent and vice versa).
3616 Values up to 6 are also accepted, but are purely experimental.
3617 This option only shows an effect if the AC-3 stream contains the
3618 required range compression information.
3619 The standard mandates that DRC is enabled by default, but mpv
3621 (and some other players) ignore this for the sake of better au‐
3622 dio quality.
3623 --ad-lavc-downmix=<yes|no>
3625 Whether to request audio channel downmixing from the decoder
3626 (default: no). Some decoders, like AC-3, AAC and DTS, can remix
3627 audio on decoding. The requested number of output channels is
3628 set with the --audio-channels option. Useful for playing sur‐
3629 round audio on a stereo system.
3630 --ad-lavc-threads=<0-16>
3632 Number of threads to use for decoding. Whether threading is ac‐
3633 tually supported depends on codec. As of this writing, it's sup‐
3634 ported for some lossless codecs only. 0 means autodetect number
3635 of cores on the machine and use that, up to the maximum of 16
3636 (default: 1).
3637 --ad-lavc-o=<key>=<value>[,<key>=<value>[,...]]
3639 Pass AVOptions to libavcodec decoder. Note, a patch to make the
3640 o= unneeded and pass all unknown options through the AVOption
3641 system is welcome. A full list of AVOptions can be found in the
3642 FFmpeg manual.
3643 This is a key/value list option. See List Options for details.
3645 --ad-spdif-dtshd=<yes|no>, --dtshd, --no-dtshd
3647 If DTS is passed through, use DTS-HD.
3648 Warning
3650 This and enabling passthrough via --ad are deprecated
3652 in favor of using --audio-spdif=dts-hd.
3653 --audio-channels=<auto-safe|auto|layouts>
3655 Control which audio channels are output (e.g. surround vs.
3656 stereo). There are the following possibilities:
3657 •
3659 --audio-channels=auto-safe
3661 Use the system's preferred channel layout. If there is
3662 none (such as when accessing a hardware device instead
3663 of the system mixer), force stereo. Some audio outputs
3664 might simply accept any layout and do downmixing on
3665 their own.
3666 This is the default.
3668 •
3670 --audio-channels=auto
3672 Send the audio device whatever it accepts, preferring
3673 the audio's original channel layout. Can cause issues
3674 with HDMI (see the warning below).
3675 •
3677 --audio-channels=layout1,layout2,...
3679 List of ,-separated channel layouts which should be al‐
3680 lowed. Technically, this only adjusts the filter chain
3681 output to the best matching layout in the list, and
3682 passes the result to the audio API. It's possible that
3683 the audio API will select a different channel layout.
3684 Using this mode is recommended for direct hardware out‐
3686 put, especially over HDMI (see HDMI warning below).
3687 •
3689 --audio-channels=<stereo|mono>
3691 Force a downmix to stereo or mono. These are spe‐
3692 cial-cases of the previous item. (See paragraphs below
3693 for implications.)
3694 If a list of layouts is given, each item can be either an ex‐
3696 plicit channel layout name (like 5.1), or a channel number.
3697 Channel numbers refer to default layouts, e.g. 2 channels refer
3698 to stereo, 6 refers to 5.1.
3699 See --audio-channels=help output for defined default layouts.
3701 This also lists speaker names, which can be used to express ar‐
3702 bitrary channel layouts (e.g. fl-fr-lfe is 2.1).
3703 If the list of channel layouts has only 1 item, the decoder is
3705 asked to produce according output. This sometimes triggers de‐
3706 coder-downmix, which might be different from the normal mpv
3707 downmix. (Only some decoders support remixing audio, like AC-3,
3708 AAC or DTS. You can use --ad-lavc-downmix=no to make the decoder
3709 always output its native layout.) One consequence is that --au‐
3710 dio-channels=stereo triggers decoder downmix, while auto or
3711 auto-safe never will, even if they end up selecting stereo. This
3712 happens because the decision whether to use decoder downmix hap‐
3713 pens long before the audio device is opened.
3714 If the channel layout of the media file (i.e. the decoder) and
3716 the AO's channel layout don't match, mpv will attempt to insert
3717 a conversion filter. You may need to change the channel layout
3718 of the system mixer to achieve your desired output as mpv does
3719 not have control over it. Another work-around for this on some
3720 AOs is to use --audio-exclusive=yes to circumvent the system
3721 mixer entirely.
3722 Warning
3724 Using auto can cause issues when using audio over
3726 HDMI. The OS will typically report all channel layouts
3727 that _can_ go over HDMI, even if the receiver does not
3728 support them. If a receiver gets an unsupported chan‐
3729 nel layout, random things can happen, such as dropping
3730 the additional channels, or adding noise.
3731 You are recommended to set an explicit whitelist of
3733 the layouts you want. For example, most A/V receivers
3734 connected via HDMI and that can do 7.1 would be
3735 served by: --audio-channels=7.1,5.1,stereo
3736 --audio-display=<no|embedded-first|external-first>
3738 Determines whether to display cover art when playing audio files
3739 and with what priority. It will display the first image found,
3740 and additional images are available as video tracks.
3741 no Disable display of video entirely when playing audio
3743 files.
3744 embedded-first
3746 Display embedded images and external cover art, giving
3747 priority to embedded images (default).
3748 external-first
3750 Display embedded images and external cover art, giving
3751 priority to external files.
3752 This option has no influence on files with normal video tracks.
3754 --audio-files=<files>
3756 Play audio from an external file while viewing a video.
3757 This is a path list option. See List Options for details.
3759 --audio-file=<file>
3761 CLI/config file only alias for --audio-files-append. Each use of
3762 this option will add a new audio track. The details are similar
3763 to how --sub-file works.
3764 --audio-format=<format>
3766 Select the sample format used for output from the audio filter
3767 layer to the sound card. The values that <format> can adopt are
3768 listed below in the description of the format audio filter.
3769 --audio-samplerate=<Hz>
3771 Select the output sample rate to be used (of course sound cards
3772 have limits on this). If the sample frequency selected is dif‐
3773 ferent from that of the current media, the lavrresample audio
3774 filter will be inserted into the audio filter layer to compen‐
3775 sate for the difference.
3776 --gapless-audio=<no|yes|weak>
3778 Try to play consecutive audio files with no silence or disrup‐
3779 tion at the point of file change. Default: weak.
3780 no Disable gapless audio.
3782 yes The audio device is opened using parameters chosen for
3784 the first file played and is then kept open for gapless
3785 playback. This means that if the first file for example
3786 has a low sample rate, then the following files may get
3787 resampled to the same low sample rate, resulting in re‐
3788 duced sound quality. If you play files with different pa‐
3789 rameters, consider using options such as --audio-sampler‐
3790 ate and --audio-format to explicitly select what the
3791 shared output format will be.
3792 weak Normally, the audio device is kept open (using the format
3794 it was first initialized with). If the audio format the
3795 decoder output changes, the audio device is closed and
3796 reopened. This means that you will normally get gapless
3797 audio with files that were encoded using the same set‐
3798 tings, but might not be gapless in other cases. The ex‐
3799 act conditions under which the audio device is kept open
3800 is an implementation detail, and can change from version
3801 to version. Currently, the device is kept even if the
3802 sample format changes, but the sample formats are con‐
3803 vertible. If video is still going on when there is still
3804 audio, trying to use gapless is also explicitly given up.
3805 NOTE:
3807 This feature is implemented in a simple manner and relies on
3808 audio output device buffering to continue playback while mov‐
3809 ing from one file to another. If playback of the new file
3810 starts slowly, for example because it is played from a remote
3811 network location or because you have specified cache settings
3812 that require time for the initial cache fill, then the
3813 buffered audio may run out before playback of the new file
3814 can start.
3815 --initial-audio-sync, --no-initial-audio-sync
3817 When starting a video file or after events such as seeking, mpv
3818 will by default modify the audio stream to make it start from
3819 the same timestamp as video, by either inserting silence at the
3820 start or cutting away the first samples. Disabling this option
3821 makes the player behave like older mpv versions did: video and
3822 audio are both started immediately even if their start time‐
3823 stamps differ, and then video timing is gradually adjusted if
3824 necessary to reach correct synchronization later.
3825 --volume-max=<100.0-1000.0>, --softvol-max=<...>
3827 Set the maximum amplification level in percent (default: 130). A
3828 value of 130 will allow you to adjust the volume up to about
3829 double the normal level.
3830 --softvol-max is a deprecated alias and should not be used.
3832 --audio-file-auto=<no|exact|fuzzy|all>, --no-audio-file-auto
3834 Load additional audio files matching the video filename. The pa‐
3835 rameter specifies how external audio files are matched.
3836 no Don't automatically load external audio files (default).
3838 exact Load the media filename with audio file extension.
3840 fuzzy Load all audio files containing the media filename.
3842 all Load all audio files in the current and --au‐
3844 dio-file-paths directories.
3845 --audio-file-paths=<path1:path2:...>
3847 Equivalent to --sub-file-paths option, but for auto-loaded audio
3848 files.
3849 This is a path list option. See List Options for details.
3851 --audio-client-name=<name>
3853 The application name the player reports to the audio API. Can be
3854 useful if you want to force a different audio profile (e.g. with
3855 PulseAudio), or to set your own application name when using
3856 libmpv.
3857 --audio-buffer=<seconds>
3859 Set the audio output minimum buffer. The audio device might ac‐
3860 tually create a larger buffer if it pleases. If the device cre‐
3861 ates a smaller buffer, additional audio is buffered in an addi‐
3862 tional software buffer.
3863 Making this larger will make soft-volume and other filters react
3865 slower, introduce additional issues on playback speed change,
3866 and block the player on audio format changes. A smaller buffer
3867 might lead to audio dropouts.
3868 This option should be used for testing only. If a non-default
3870 value helps significantly, the mpv developers should be con‐
3871 tacted.
3872 Default: 0.2 (200 ms).
3874 --audio-stream-silence=<yes|no>
3876 Cash-grab consumer audio hardware (such as A/V receivers) often
3877 ignore initial audio sent over HDMI. This can happen every time
3878 audio over HDMI is stopped and resumed. In order to compensate
3879 for this, you can enable this option to not to stop and restart
3880 audio on seeks, and fill the gaps with silence. Likewise, when
3881 pausing playback, audio is not stopped, and silence is played
3882 while paused. Note that if no audio track is selected, the audio
3883 device will still be closed immediately.
3884 Not all AOs support this.
3886 Warning
3888 This modifies certain subtle player behavior, like
3890 A/V-sync and underrun handling. Enabling this option
3891 is strongly discouraged.
3892 --audio-wait-open=<secs>
3894 This makes sense for use with --audio-stream-silence=yes. If
3895 this option is given, the player will wait for the given amount
3896 of seconds after opening the audio device before sending actual
3897 audio data to it. Useful if your expensive hardware discards the
3898 first 1 or 2 seconds of audio data sent to it. If --au‐
3899 dio-stream-silence=yes is not set, this option will likely just
3900 waste time.
3901 Subtitles
3903 NOTE:
3904 Changing styling and position does not work with all subtitles. Im‐
3905 age-based subtitles (DVD, Bluray/PGS, DVB) cannot changed for funda‐
3906 mental reasons. Subtitles in ASS format are normally not changed
3907 intentionally, but overriding them can be controlled with
3908 --sub-ass-override.
3909 Previously some options working on text subtitles were called
3911 --sub-text-*, they are now named --sub-*, and those specifically for
3912 ASS have been renamed from --ass-* to --sub-ass-*. They are now all
3913 in this section.
3914 --sub-demuxer=<[+]name>
3916 Force subtitle demuxer type for --sub-file. Give the demuxer
3917 name as printed by --sub-demuxer=help.
3918 --sub-delay=<sec>
3920 Delays subtitles by <sec> seconds. Can be negative.
3921 --sub-files=<file-list>, --sub-file=<filename>
3923 Add a subtitle file to the list of external subtitles.
3924 If you use --sub-file only once, this subtitle file is displayed
3926 by default.
3927 If --sub-file is used multiple times, the subtitle to use can be
3929 switched at runtime by cycling subtitle tracks. It's possible to
3930 show two subtitles at once: use --sid to select the first subti‐
3931 tle index, and --secondary-sid to select the second index. (The
3932 index is printed on the terminal output after the --sid= in the
3933 list of streams.)
3934 --sub-files is a path list option (see List Options for de‐
3936 tails), and can take multiple file names separated by : (Unix)
3937 or ; (Windows), while --sub-file takes a single filename, but
3938 can be used multiple times to add multiple files. Technically,
3939 --sub-file is a CLI/config file only alias for --sub-files-ap‐
3940 pend.
3941 --secondary-sid=<ID|auto|no>
3943 Select a secondary subtitle stream. This is similar to --sid. If
3944 a secondary subtitle is selected, it will be rendered as topti‐
3945 tle (i.e. on the top of the screen) alongside the normal subti‐
3946 tle, and provides a way to render two subtitles at once.
3947 There are some caveats associated with this feature. For exam‐
3949 ple, bitmap subtitles will always be rendered in their usual po‐
3950 sition, so selecting a bitmap subtitle as secondary subtitle
3951 will result in overlapping subtitles. Secondary subtitles are
3952 never shown on the terminal if video is disabled.
3953 NOTE:
3955 Styling and interpretation of any formatting tags is disabled
3956 for the secondary subtitle. Internally, the same mechanism as
3957 --no-sub-ass is used to strip the styling.
3958 NOTE:
3960 If the main subtitle stream contains formatting tags which
3961 display the subtitle at the top of the screen, it will over‐
3962 lap with the secondary subtitle. To prevent this, you could
3963 use --no-sub-ass to disable styling in the main subtitle
3964 stream.
3965 --sub-scale=<0-100>
3967 Factor for the text subtitle font size (default: 1).
3968 NOTE:
3970 This affects ASS subtitles as well, and may lead to incorrect
3971 subtitle rendering. Use with care, or use --sub-font-size in‐
3972 stead.
3973 --sub-scale-by-window=<yes|no>
3975 Whether to scale subtitles with the window size (default: yes).
3976 If this is disabled, changing the window size won't change the
3977 subtitle font size.
3978 Like --sub-scale, this can break ASS subtitles.
3980 --sub-scale-with-window=<yes|no>
3982 Make the subtitle font size relative to the window, instead of
3983 the video. This is useful if you always want the same font
3984 size, even if the video doesn't cover the window fully, e.g. be‐
3985 cause screen aspect and window aspect mismatch (and the player
3986 adds black bars).
3987 Default: yes.
3989 This option is misnamed. The difference to the confusingly simi‐
3991 lar sounding option --sub-scale-by-window is that
3992 --sub-scale-with-window still scales with the approximate window
3993 size, while the other option disables this scaling.
3994 Affects plain text subtitles only (or ASS if --sub-ass-override
3996 is set high enough).
3997 --sub-ass-scale-with-window=<yes|no>
3999 Like --sub-scale-with-window, but affects subtitles in ASS for‐
4000 mat only. Like --sub-scale, this can break ASS subtitles.
4001 Default: no.
4003 --embeddedfonts=<yes|no>
4005 Use fonts embedded in Matroska container files and ASS scripts
4006 (default: yes). These fonts can be used for SSA/ASS subtitle
4007 rendering.
4008 --sub-pos=<0-150>
4010 Specify the position of subtitles on the screen. The value is
4011 the vertical position of the subtitle in % of the screen height.
4012 100 is the original position, which is often not the absolute
4013 bottom of the screen, but with some margin between the bottom
4014 and the subtitle. Values above 100 move the subtitle further
4015 down.
4016 Warning
4018 Text subtitles (as opposed to image subtitles) may be
4020 cut off if the value of the option is above 100. This
4021 is a libass restriction.
4022 This affects ASS subtitles as well, and may lead to
4024 incorrect subtitle rendering in addition to the prob‐
4025 lem above.
4026 Using --sub-margin-y can achieve this in a better way.
4028 --sub-speed=<0.1-10.0>
4030 Multiply the subtitle event timestamps with the given value. Can
4031 be used to fix the playback speed for frame-based subtitle for‐
4032 mats. Affects text subtitles only.
4033 Example
4035 --sub-speed=25/23.976 plays frame based subtitles
4037 which have been loaded assuming a framerate of 23.976
4038 at 25 FPS.
4039 --sub-ass-force-style=<[Style.]Param=Value[,...]>
4041 Override some style or script info parameters.
4042 This is a string list option. See List Options for details.
4044 Examples
4046 • --sub-ass-force-style=FontName=Arial,Default.Bold=1
4048 • --sub-ass-force-style=PlayResY=768
4050 NOTE:
4052 Using this option may lead to incorrect subtitle rendering.
4053 --sub-ass-hinting=<none|light|normal|native>
4055 Set font hinting type. <type> can be:
4056 none no hinting (default)
4058 light FreeType autohinter, light mode
4060 normal FreeType autohinter, normal mode
4062 native font native hinter
4064 Warning
4066 Enabling hinting can lead to mispositioned text (in
4068 situations it's supposed to match up video back‐
4069 ground), or reduce the smoothness of animations with
4070 some badly authored ASS scripts. It is recommended to
4071 not use this option, unless really needed.
4072 --sub-ass-line-spacing=<value>
4074 Set line spacing value for SSA/ASS renderer.
4075 --sub-ass-shaper=<simple|complex>
4077 Set the text layout engine used by libass.
4078 simple uses Fribidi only, fast, doesn't render some languages
4080 correctly
4081 complex
4083 uses HarfBuzz, slower, wider language support
4084 complex is the default. If libass hasn't been compiled against
4086 HarfBuzz, libass silently reverts to simple.
4087 --sub-ass-styles=<filename>
4089 Load all SSA/ASS styles found in the specified file and use them
4090 for rendering text subtitles. The syntax of the file is exactly
4091 like the [V4 Styles] / [V4+ Styles] section of SSA/ASS.
4092 NOTE:
4094 Using this option may lead to incorrect subtitle rendering.
4095 --sub-ass-override=<yes|no|force|scale|strip>
4097 Control whether user style overrides should be applied. Note
4098 that all of these overrides try to be somewhat smart about fig‐
4099 uring out whether or not a subtitle is considered a "sign".
4100 no Render subtitles as specified by the subtitle scripts,
4102 without overrides.
4103 yes Apply all the --sub-ass-* style override options. Chang‐
4105 ing the default for any of these options can lead to in‐
4106 correct subtitle rendering (default).
4107 force Like yes, but also force all --sub-* options. Can break
4109 rendering easily.
4110 scale Like yes, but also apply --sub-scale.
4112 strip Radically strip all ASS tags and styles from the subti‐
4114 tle. This is equivalent to the old --no-ass /
4115 --no-sub-ass options.
4116 This also controls some bitmap subtitle overrides, as well as
4118 HTML tags in formats like SRT, despite the name of the option.
4119 --sub-ass-force-margins
4121 Enables placing toptitles and subtitles in black borders when
4122 they are available, if the subtitles are in the ASS format.
4123 Default: no.
4125 --sub-use-margins
4127 Enables placing toptitles and subtitles in black borders when
4128 they are available, if the subtitles are in a plain text format
4129 (or ASS if --sub-ass-override is set high enough).
4130 Default: yes.
4132 Renamed from --sub-ass-use-margins. To place ASS subtitles in
4134 the borders too (like the old option did), also add
4135 --sub-ass-force-margins.
4136 --sub-ass-vsfilter-aspect-compat=<yes|no>
4138 Stretch SSA/ASS subtitles when playing anamorphic videos for
4139 compatibility with traditional VSFilter behavior. This switch
4140 has no effect when the video is stored with square pixels.
4141 The renderer historically most commonly used for the SSA/ASS
4143 subtitle formats, VSFilter, had questionable behavior that re‐
4144 sulted in subtitles being stretched too if the video was stored
4145 in anamorphic format that required scaling for display. This
4146 behavior is usually undesirable and newer VSFilter versions may
4147 behave differently. However, many existing scripts compensate
4148 for the stretching by modifying things in the opposite direc‐
4149 tion. Thus, if such scripts are displayed "correctly", they
4150 will not appear as intended. This switch enables emulation of
4151 the old VSFilter behavior (undesirable but expected by many ex‐
4152 isting scripts).
4153 Enabled by default.
4155 --sub-ass-vsfilter-blur-compat=<yes|no>
4157 Scale \blur tags by video resolution instead of script resolu‐
4158 tion (enabled by default). This is bug in VSFilter, which ac‐
4159 cording to some, can't be fixed anymore in the name of compati‐
4160 bility.
4161 Note that this uses the actual video resolution for calculating
4163 the offset scale factor, not what the video filter chain or the
4164 video output use.
4165 --sub-ass-vsfilter-color-compat=<basic|full|force-601|no>
4167 Mangle colors like (xy-)vsfilter do (default: basic). Histori‐
4168 cally, VSFilter was not color space aware. This was no problem
4169 as long as the color space used for SD video (BT.601) was used.
4170 But when everything switched to HD (BT.709), VSFilter was still
4171 converting RGB colors to BT.601, rendered them into the video
4172 frame, and handled the frame to the video output, which would
4173 use BT.709 for conversion to RGB. The result were mangled subti‐
4174 tle colors. Later on, bad hacks were added on top of the ASS
4175 format to control how colors are to be mangled.
4176 basic Handle only BT.601->BT.709 mangling, if the subtitles
4178 seem to indicate that this is required (default).
4179 full Handle the full YCbCr Matrix header with all video color
4181 spaces supported by libass and mpv. This might lead to
4182 bad breakages in corner cases and is not strictly needed
4183 for compatibility (hopefully), which is why this is not
4184 default.
4185 force-601
4187 Force BT.601->BT.709 mangling, regardless of subtitle
4188 headers or video color space.
4189 no Disable color mangling completely. All colors are RGB.
4191 Choosing anything other than no will make the subtitle color de‐
4193 pend on the video color space, and it's for example in theory
4194 not possible to reuse a subtitle script with another video file.
4195 The --sub-ass-override option doesn't affect how this option is
4196 interpreted.
4197 --stretch-dvd-subs=<yes|no>
4199 Stretch DVD subtitles when playing anamorphic videos for better
4200 looking fonts on badly mastered DVDs. This switch has no effect
4201 when the video is stored with square pixels - which for DVD in‐
4202 put cannot be the case though.
4203 Many studios tend to use bitmap fonts designed for square pixels
4205 when authoring DVDs, causing the fonts to look stretched on
4206 playback on DVD players. This option fixes them, however at the
4207 price of possibly misaligning some subtitles (e.g. sign transla‐
4208 tions).
4209 Disabled by default.
4211 --stretch-image-subs-to-screen=<yes|no>
4213 Stretch DVD and other image subtitles to the screen, ignoring
4214 the video margins. This has a similar effect as --sub-use-mar‐
4215 gins for text subtitles, except that the text itself will be
4216 stretched, not only just repositioned. (At least in general it
4217 is unavoidable, as an image bitmap can in theory consist of a
4218 single bitmap covering the whole screen, and the player won't
4219 know where exactly the text parts are located.)
4220 This option does not display subtitles correctly. Use with care.
4222 Disabled by default.
4224 --image-subs-video-resolution=<yes|no>
4226 Override the image subtitle resolution with the video resolution
4227 (default: no). Normally, the subtitle canvas is fit into the
4228 video canvas (e.g. letterboxed). Setting this option uses the
4229 video size as subtitle canvas size. Can be useful to test broken
4230 subtitles, which often happen when the video was trancoded,
4231 while attempting to keep the old subtitles.
4232 --sub-ass, --no-sub-ass
4234 Render ASS subtitles natively (enabled by default).
4235 NOTE:
4237 This has been deprecated by --sub-ass-override=strip. You
4238 also may need --embeddedfonts=no to get the same behavior.
4239 Also, using --sub-ass-override=style should give better re‐
4240 sults without breaking subtitles too much.
4241 If --no-sub-ass is specified, all tags and style declarations
4243 are stripped and ignored on display. The subtitle renderer uses
4244 the font style as specified by the --sub- options instead.
4245 NOTE:
4247 Using --no-sub-ass may lead to incorrect or completely broken
4248 rendering of ASS/SSA subtitles. It can sometimes be useful to
4249 forcibly override the styling of ASS subtitles, but should be
4250 avoided in general.
4251 --sub-auto=<no|exact|fuzzy|all>, --no-sub-auto
4253 Load additional subtitle files matching the video filename. The
4254 parameter specifies how external subtitle files are matched. ex‐
4255 act is enabled by default.
4256 no Don't automatically load external subtitle files.
4258 exact Load the media filename with subtitle file extension and
4260 possibly language suffixes (default).
4261 fuzzy Load all subs containing the media filename.
4263 all Load all subs in the current and --sub-file-paths direc‐
4265 tories.
4266 --sub-codepage=<codepage>
4268 You can use this option to specify the subtitle codepage.
4269 uchardet will be used to guess the charset. (If mpv was not com‐
4270 piled with uchardet, then utf-8 is the effective default.)
4271 The default value for this option is auto, which enables autode‐
4273 tection.
4274 The following steps are taken to determine the final codepage,
4276 in order:
4277 • if the specific codepage has a +, use that codepage
4279 • if the data looks like UTF-8, assume it is UTF-8
4281 • if --sub-codepage is set to a specific codepage, use that
4283 • run uchardet, and if successful, use that
4285 • otherwise, use UTF-8-BROKEN
4287 Examples
4289 • --sub-codepage=latin2 Use Latin 2 if input is not UTF-8.
4291 • --sub-codepage=+cp1250 Always force recoding to cp1250.
4293 The pseudo codepage UTF-8-BROKEN is used internally. If it's
4295 set, subtitles are interpreted as UTF-8 with "Latin 1" as fall‐
4296 back for bytes which are not valid UTF-8 sequences. iconv is
4297 never involved in this mode.
4298 This option changed in mpv 0.23.0. Support for the old syntax
4300 was fully removed in mpv 0.24.0.
4301 NOTE:
4303 This works for text subtitle files only. Other types of sub‐
4304 titles (in particular subtitles in mkv files) are always as‐
4305 sumed to be UTF-8.
4306 --sub-fix-timing=<yes|no>
4308 Adjust subtitle timing is to remove minor gaps or overlaps be‐
4309 tween subtitles (if the difference is smaller than 210 ms, the
4310 gap or overlap is removed).
4311 --sub-forced-only=<auto|yes|no>
4313 Display only forced subtitles for the DVD subtitle stream se‐
4314 lected by e.g. --slang (default: auto). When set to auto, en‐
4315 abled when the --subs-with-matching-audio option is on and a
4316 non-forced stream is selected. Enabling this will hide all sub‐
4317 titles in streams that don't make a distinction between forced
4318 and unforced events within a stream.
4319 --sub-fps=<rate>
4321 Specify the framerate of the subtitle file (default: video fps).
4322 Affects text subtitles only.
4323 NOTE:
4325 <rate> > video fps speeds the subtitles up for frame-based
4326 subtitle files and slows them down for time-based ones.
4327 See also: --sub-speed.
4329 --sub-gauss=<0.0-3.0>
4331 Apply Gaussian blur to image subtitles (default: 0). This can
4332 help to make pixelated DVD/Vobsubs look nicer. A value other
4333 than 0 also switches to software subtitle scaling. Might be
4334 slow.
4335 NOTE:
4337 Never applied to text subtitles.
4338 --sub-gray
4340 Convert image subtitles to grayscale. Can help to make yellow
4341 DVD/Vobsubs look nicer.
4342 NOTE:
4344 Never applied to text subtitles.
4345 --sub-paths=<path1:path2:...>
4347 Deprecated, use --sub-file-paths.
4348 --sub-file-paths=<path-list>
4350 Specify extra directories to search for subtitles matching the
4351 video. Multiple directories can be separated by ":" (";" on
4352 Windows). Paths can be relative or absolute. Relative paths are
4353 interpreted relative to video file directory. If the file is a
4354 URL, only absolute paths and sub configuration subdirectory will
4355 be scanned.
4356 Example
4358 Assuming that /path/to/video/video.avi is played and
4360 --sub-file-paths=sub:subtitles is specified, mpv
4361 searches for subtitle files in these directories:
4362 • /path/to/video/
4364 • /path/to/video/sub/
4366 • /path/to/video/subtitles/
4368 • the sub configuration subdirectory (usually ~/.con‐
4370 fig/mpv/sub/)
4371 This is a path list option. See List Options for details.
4373 --sub-visibility, --no-sub-visibility
4375 Can be used to disable display of subtitles, but still select
4376 and decode them.
4377 --secondary-sub-visibility, --no-secondary-sub-visibility
4379 Can be used to disable display of secondary subtitles, but still
4380 select and decode them.
4381 --sub-clear-on-seek
4383 (Obscure, rarely useful.) Can be used to play broken mkv files
4384 with duplicate ReadOrder fields. ReadOrder is the first field in
4385 a Matroska-style ASS subtitle packets. It should be unique, and
4386 libass uses it for fast elimination of duplicates. This option
4387 disables caching of subtitles across seeks, so after a seek
4388 libass can't eliminate subtitle packets with the same ReadOrder
4389 as earlier packets.
4390 --teletext-page=<1-999>
4392 This works for dvb_teletext subtitle streams, and if FFmpeg has
4393 been compiled with support for it.
4394 --sub-past-video-end
4396 After the last frame of video, if this option is enabled, subti‐
4397 tles will continue to update based on audio timestamps. Other‐
4398 wise, the subtitles for the last video frame will stay onscreen.
4399 Default: disabled
4401 --sub-font=<name>
4403 Specify font to use for subtitles that do not themselves specify
4404 a particular font. The default is sans-serif.
4405 Examples
4407 • --sub-font='Bitstream Vera Sans'
4409 • --sub-font='Comic Sans MS'
4411 NOTE:
4413 The --sub-font option (and many other style related --sub-
4414 options) are ignored when ASS-subtitles are rendered, unless
4415 the --no-sub-ass option is specified.
4416 This used to support fontconfig patterns. Starting with
4418 libass 0.13.0, this stopped working.
4419 --sub-font-size=<size>
4421 Specify the sub font size. The unit is the size in scaled pixels
4422 at a window height of 720. The actual pixel size is scaled with
4423 the window height: if the window height is larger or smaller
4424 than 720, the actual size of the text increases or decreases as
4425 well.
4426 Default: 55.
4428 --sub-back-color=<color>
4430 See --sub-color. Color used for sub text background. You can use
4431 --sub-shadow-offset to change its size relative to the text.
4432 --sub-blur=<0..20.0>
4434 Gaussian blur factor. 0 means no blur applied (default).
4435 --sub-bold=<yes|no>
4437 Format text on bold.
4438 --sub-italic=<yes|no>
4440 Format text on italic.
4441 --sub-border-color=<color>
4443 See --sub-color. Color used for the sub font border.
4444 --sub-border-size=<size>
4446 Size of the sub font border in scaled pixels (see
4447 --sub-font-size for details). A value of 0 disables borders.
4448 Default: 3.
4450 --sub-color=<color>
4452 Specify the color used for unstyled text subtitles.
4453 The color is specified in the form r/g/b, where each color com‐
4455 ponent is specified as number in the range 0.0 to 1.0. It's also
4456 possible to specify the transparency by using r/g/b/a, where the
4457 alpha value 0 means fully transparent, and 1.0 means opaque. If
4458 the alpha component is not given, the color is 100% opaque.
4459 Passing a single number to the option sets the sub to gray, and
4461 the form gray/a lets you specify alpha additionally.
4462 Examples
4464 • --sub-color=1.0/0.0/0.0 set sub to opaque red
4466 • --sub-color=1.0/0.0/0.0/0.75 set sub to opaque red with 75%
4468 alpha
4469 • --sub-color=0.5/0.75 set sub to 50% gray with 75% alpha
4471 Alternatively, the color can be specified as a RGB hex triplet
4473 in the form #RRGGBB, where each 2-digit group expresses a color
4474 value in the range 0 (00) to 255 (FF). For example, #FF0000 is
4475 red. This is similar to web colors. Alpha is given with #AAR‐
4476 RGGBB.
4477 Examples
4479 • --sub-color='#FF0000' set sub to opaque red
4481 • --sub-color='#C0808080' set sub to 50% gray with 75% alpha
4483 --sub-margin-x=<size>
4485 Left and right screen margin for the subs in scaled pixels (see
4486 --sub-font-size for details).
4487 This option specifies the distance of the sub to the left, as
4489 well as at which distance from the right border long sub text
4490 will be broken.
4491 Default: 25.
4493 --sub-margin-y=<size>
4495 Top and bottom screen margin for the subs in scaled pixels (see
4496 --sub-font-size for details).
4497 This option specifies the vertical margins of unstyled text sub‐
4499 titles. If you just want to raise the vertical subtitle posi‐
4500 tion, use --sub-pos.
4501 Default: 22.
4503 --sub-align-x=<left|center|right>
4505 Control to which corner of the screen text subtitles should be
4506 aligned to (default: center).
4507 Never applied to ASS subtitles, except in --no-sub-ass mode.
4509 Likewise, this does not apply to image subtitles.
4510 --sub-align-y=<top|center|bottom>
4512 Vertical position (default: bottom). Details see --sub-align-x.
4513 --sub-justify=<auto|left|center|right>
4515 Control how multi line subs are justified irrespective of where
4516 they are aligned (default: auto which justifies as defined by
4517 --sub-align-x). Left justification is recommended to make the
4518 subs easier to read as it is easier for the eyes.
4519 --sub-ass-justify=<yes|no>
4521 Applies justification as defined by --sub-justify on ASS subti‐
4522 tles if --sub-ass-override is not set to no. Default: no.
4523 --sub-shadow-color=<color>
4525 See --sub-color. Color used for sub text shadow.
4526 NOTE:
4528 ignored when --sub-back-color is specified (or more exactly:
4529 when that option is not set to completely transparent).
4530 --sub-shadow-offset=<size>
4532 Displacement of the sub text shadow in scaled pixels (see
4533 --sub-font-size for details). A value of 0 disables shadows.
4534 Default: 0.
4536 --sub-spacing=<size>
4538 Horizontal sub font spacing in scaled pixels (see
4539 --sub-font-size for details). This value is added to the normal
4540 letter spacing. Negative values are allowed.
4541 Default: 0.
4543 --sub-filter-sdh=<yes|no>
4545 Applies filter removing subtitle additions for the deaf or
4546 hard-of-hearing (SDH). This is intended for English, but may in
4547 part work for other languages too. The intention is that it can
4548 be always enabled so may not remove all parts added. It removes
4549 speaker labels (like MAN:), upper case text in parentheses and
4550 any text in brackets.
4551 Default: no.
4553 --sub-filter-sdh-harder=<yes|no>
4555 Do harder SDH filtering (if enabled by --sub-filter-sdh). Will
4556 also remove speaker labels and text within parentheses using
4557 both lower and upper case letters.
4558 Default: no.
4560 --sub-filter-regex-...=...
4562 Set a list of regular expressions to match on text subtitles,
4563 and remove any lines that match (default: empty). This is a
4564 string list option. See List Options for details. Normally, you
4565 should use --sub-filter-regex-append=<regex>, where each option
4566 use will append a new regular expression, without having to
4567 fight escaping problems.
4568 List items are matched in order. If a regular expression
4570 matches, the process is stopped, and the subtitle line is dis‐
4571 carded. The text matched against is, by default, the Text field
4572 of ASS events (if the subtitle format is different, it is always
4573 converted). This may include formatting tags. Matching is
4574 case-insensitive, but how this is done depends on the libc, and
4575 most likely works in ASCII only. It does not work on bitmap/im‐
4576 age subtitles. Unavailable on inferior OSes (requires POSIX
4577 regex support).
4578 Example
4580 --sub-filter-regex-append=opensubtitles\.org filters
4582 some ads.
4583 Technically, using a list for matching is redundant, since you
4585 could just use a single combined regular expression. But it
4586 helps with diagnosis, ease of use, and temporarily disabling or
4587 enabling individual filters.
4588 WARNING:
4590 This is experimental. The semantics most likely will change,
4591 and if you use this, you should be prepared to update the op‐
4592 tion later. Ideas include replacing the regexes with a very
4593 primitive and small subset of sed, or some method to control
4594 case-sensitivity.
4595 --sub-filter-jsre-...=...
4597 Same as --sub-filter-regex but with JavaScript regular expres‐
4598 sions. Shares/affected-by all --sub-filter-regex-* control op‐
4599 tions (see below), and also experimental. Requires only Java‐
4600 Script support.
4601 --sub-filter-regex-plain=<yes|no>
4603 Whether to first convert the ASS "Text" field to plain-text (de‐
4604 fault: no). This strips ASS tags and applies ASS directives,
4605 like \N to new-line. If the result is multi-line then the reg‐
4606 exp anchors ^ and $ match each line, but still any match dis‐
4607 cards all lines.
4608 --sub-filter-regex-warn=<yes|no>
4610 Log dropped lines with warning log level, instead of verbose
4611 (default: no). Helpful for testing.
4612 --sub-filter-regex-enable=<yes|no>
4614 Whether to enable regex filtering (default: yes). Note that if
4615 no regexes are added to the --sub-filter-regex list, setting
4616 this option to yes has no effect. It's meant to easily disable
4617 or enable filtering temporarily.
4618 --sub-create-cc-track=<yes|no>
4620 For every video stream, create a closed captions track (default:
4621 no). The only purpose is to make the track available for selec‐
4622 tion at the start of playback, instead of creating it lazily.
4623 This applies only to ATSC A53 Part 4 Closed Captions (displayed
4624 by mpv as subtitle tracks using the codec eia_608). The CC track
4625 is marked "default" and selected according to the normal subti‐
4626 tle track selection rules. You can then use --sid to explicitly
4627 select the correct track too.
4628 If the video stream contains no closed captions, or if no video
4630 is being decoded, the CC track will remain empty and will not
4631 show any text.
4632 --sub-font-provider=<auto|none|fontconfig>
4634 Which libass font provider backend to use (default: auto). auto
4635 will attempt to use the native font provider: fontconfig on
4636 Linux, CoreText on macOS, DirectWrite on Windows. fontconfig
4637 forces fontconfig, if libass was built with support (if not, it
4638 behaves like none).
4639 The none font provider effectively disables system fonts. It
4641 will still attempt to use embedded fonts (unless --embedded‐
4642 fonts=no is set; this is the same behavior as with all other
4643 font providers), subfont.ttf if provided, and fonts in the
4644 fonts sub-directory if provided. (The fallback is more strict
4645 than that of other font providers, and if a font name does not
4646 match, it may prefer not to render any text that uses the miss‐
4647 ing font.)
4648 --sub-fonts-dir=<path>
4650 Font files in this directory are used by mpv/libass for subti‐
4651 tles. Useful if you do not want to install fonts to your system.
4652 Note that files in this directory are loaded into memory before
4653 being used by mpv. If you have a lot of fonts, consider using
4654 fonts.conf (see FILES section) to include additional mpv user
4655 settings.
4656 If this option is not specified, ~~/fonts will be used by de‐
4658 fault.
4659 Window
4661 --title=<string>
4662 Set the window title. This is used for the video window, and if
4663 possible, also sets the audio stream title.
4664 Properties are expanded. (See Property Expansion.)
4666 WARNING:
4668 There is a danger of this causing significant CPU usage, de‐
4669 pending on the properties used. Changing the window title is
4670 often a slow operation, and if the title changes every frame,
4671 playback can be ruined.
4672 --screen=<default|0-32>
4674 In multi-monitor configurations (i.e. a single desktop that
4675 spans across multiple displays), this option tells mpv which
4676 screen to display the video on.
4677 Note (X11)
4679 This option does not work properly with all window
4681 managers. In these cases, you can try to use --geome‐
4682 try to position the window explicitly. It's also pos‐
4683 sible that the window manager provides native features
4684 to control which screens application windows should
4685 use.
4686 See also --fs-screen.
4688 --screen-name=<string>
4690 In multi-monitor configurations, this option tells mpv which
4691 screen to display the video on based on the screen name from the
4692 video backend. The same caveats in the --screen option also ap‐
4693 ply here. This option is ignored and does nothing if --screen is
4694 explicitly set.
4695 --fullscreen, --fs
4697 Fullscreen playback.
4698 --fs-screen=<all|current|0-32>
4700 In multi-monitor configurations (i.e. a single desktop that
4701 spans across multiple displays), this option tells mpv which
4702 screen to go fullscreen to. If current is used mpv will fall‐
4703 back on what the user provided with the screen option.
4704 Note (X11)
4706 This option works properly only with window managers
4708 which understand the EWMH _NET_WM_FULLSCREEN_MONITORS
4709 hint.
4710 Note (macOS)
4712 all does not work on macOS and will behave like cur‐
4714 rent.
4715 See also --screen.
4717 --fs-screen-name=<string>
4719 In multi-monitor configurations, this option tells mpv which
4720 screen to go fullscreen to based on the screen name from the
4721 video backend. The same caveats in the --fs-screen option also
4722 apply here. This option is ignored and does nothing if
4723 --fs-screen is explicitly set.
4724 --keep-open=<yes|no|always>
4726 Do not terminate when playing or seeking beyond the end of the
4727 file, and there is no next file to be played (and --loop is not
4728 used). Instead, pause the player. When trying to seek beyond
4729 end of the file, the player will attempt to seek to the last
4730 frame.
4731 Normally, this will act like set pause yes on EOF, unless the
4733 --keep-open-pause=no option is set.
4734 The following arguments can be given:
4736 no If the current file ends, go to the next file or termi‐
4738 nate. (Default.)
4739 yes Don't terminate if the current file is the last playlist
4741 entry. Equivalent to --keep-open without arguments.
4742 always Like yes, but also applies to files before the last
4744 playlist entry. This means playback will never automati‐
4745 cally advance to the next file.
4746 NOTE:
4748 This option is not respected when using --frames. Explicitly
4749 skipping to the next file if the binding uses force will ter‐
4750 minate playback as well.
4751 Also, if errors or unusual circumstances happen, the player
4753 can quit anyway.
4754 Since mpv 0.6.0, this doesn't pause if there is a next file in
4756 the playlist, or the playlist is looped. Approximately, this
4757 will pause when the player would normally exit, but in practice
4758 there are corner cases in which this is not the case (e.g. mpv
4759 --keep-open file.mkv /dev/null will play file.mkv normally, then
4760 fail to open /dev/null, then exit). (In mpv 0.8.0, always was
4761 introduced, which restores the old behavior.)
4762 --keep-open-pause=<yes|no>
4764 If set to no, instead of pausing when --keep-open is active,
4765 just stop at end of file and continue playing forward when you
4766 seek backwards until end where it stops again. Default: yes.
4767 --image-display-duration=<seconds|inf>
4769 If the current file is an image, play the image for the given
4770 amount of seconds (default: 1). inf means the file is kept open
4771 forever (until the user stops playback manually).
4772 Unlike --keep-open, the player is not paused, but simply contin‐
4774 ues playback until the time has elapsed. (It should not use any
4775 resources during "playback".)
4776 This affects image files, which are defined as having only 1
4778 video frame and no audio. The player may recognize certain
4779 non-images as images, for example if --length is used to reduce
4780 the length to 1 frame, or if you seek to the last frame.
4781 This option does not affect the framerate used for mf:// or
4783 --merge-files. For that, use --mf-fps instead.
4784 Setting --image-display-duration hides the OSC and does not
4786 track playback time on the command-line output, and also does
4787 not duplicate the image frame when encoding. To force the player
4788 into "dumb mode" and actually count out seconds, or to duplicate
4789 the image when encoding, you need to use --demuxer=lavf --de‐
4790 muxer-lavf-o=loop=1, and use --length or --frames to stop after
4791 a particular time.
4792 --force-window=<yes|no|immediate>
4794 Create a video output window even if there is no video. This can
4795 be useful when pretending that mpv is a GUI application. Cur‐
4796 rently, the window always has the size 640x480, and is subject
4797 to --geometry, --autofit, and similar options.
4798 WARNING:
4800 The window is created only after initialization (to make sure
4801 default window placement still works if the video size is
4802 different from the --force-window default window size). This
4803 can be a problem if initialization doesn't work perfectly,
4804 such as when opening URLs with bad network connection, or
4805 opening broken video files. The immediate mode can be used to
4806 create the window always on program start, but this may cause
4807 other issues.
4808 --taskbar-progress, --no-taskbar-progress
4810 (Windows only) Enable/disable playback progress rendering in
4811 taskbar (Windows 7 and above).
4812 Enabled by default.
4814 --snap-window
4816 (Windows only) Snap the player window to screen edges.
4817 --drag-and-drop=<no|auto|replace|append>
4819 (X11, Wayland and Windows only) Controls the default behavior of
4820 drag and drop on platforms that support this. auto will obey
4821 what the underlying os/platform gives mpv. Typically, holding
4822 shift during the drag and drop will append the item to the
4823 playlist. Otherwise, it will completely replace it. replace and
4824 append always force replacing and appending to the playlist re‐
4825 spectively. no disables all drag and drop behavior.
4826 --ontop
4828 Makes the player window stay on top of other windows.
4829 On Windows, if combined with fullscreen mode, this causes mpv to
4831 be treated as exclusive fullscreen window that bypasses the
4832 Desktop Window Manager.
4833 --ontop-level=<window|system|desktop|level>
4835 (macOS only) Sets the level of an ontop window (default: win‐
4836 dow).
4837 window On top of all other windows.
4839 system On top of system elements like Taskbar, Menubar and Dock.
4841 desktop
4843 On top of the Desktop behind windows and Desktop icons.
4844 level A level as integer.
4846 --focus-on-open, --no-focus-on-open
4848 (macOS only) Focus the video window on creation and makes it the
4849 front most window. This is on by default.
4850 --border, --no-border
4852 Play video with window border and decorations. Since this is on
4853 by default, use --no-border to disable the standard window deco‐
4854 rations.
4855 --on-all-workspaces
4857 (X11 and macOS only) Show the video window on all virtual desk‐
4858 tops.
4859 --geometry=<[W[xH]][+-x+-y][/WS]>, --geometry=<x:y>
4861 Adjust the initial window position or size. W and H set the win‐
4862 dow size in pixels. x and y set the window position, measured in
4863 pixels from the top-left corner of the screen to the top-left
4864 corner of the image being displayed. If a percentage sign (%) is
4865 given after the argument, it turns the value into a percentage
4866 of the screen size in that direction. Positions are specified
4867 similar to the standard X11 --geometry option format, in which
4868 e.g. +10-50 means "place 10 pixels from the left border and 50
4869 pixels from the lower border" and "--20+-10" means "place 20
4870 pixels beyond the right and 10 pixels beyond the top border". A
4871 trailing / followed by an integer denotes on which workspace
4872 (virtual desktop) the window should appear (X11 only).
4873 If an external window is specified using the --wid option, this
4875 option is ignored.
4876 The coordinates are relative to the screen given with --screen
4878 for the video output drivers that fully support --screen.
4879 NOTE:
4881 Generally only supported by GUI VOs. Ignored for encoding.
4882 Note (macOS)
4884 On macOS, the origin of the screen coordinate system
4886 is located on the bottom-left corner. For instance,
4887 0:0 will place the window at the bottom-left of the
4888 screen.
4889 Note (X11)
4891 This option does not work properly with all window
4893 managers.
4894 Examples
4896 50:40 Places the window at x=50, y=40.
4898 50%:50%
4900 Places the window in the middle of the screen.
4901 100%:100%
4903 Places the window at the bottom right corner of the
4904 screen.
4905 50% Sets the window width to half the screen width. Window
4907 height is set so that the window has the video aspect
4908 ratio.
4909 50%x50%
4911 Forces the window width and height to half the screen
4912 width and height. Will show black borders to compen‐
4913 sate for the video aspect ratio (with most VOs and
4914 without --no-keepaspect).
4915 50%+10+10/2
4917 Sets the window to half the screen widths, and posi‐
4918 tions it 10 pixels below/left of the top left corner
4919 of the screen, on the second workspace.
4920 See also --autofit and --autofit-larger for fitting the window
4922 into a given size without changing aspect ratio.
4923 --autofit=<[W[xH]]>
4925 Set the initial window size to a maximum size specified by WxH,
4926 without changing the window's aspect ratio. The size is measured
4927 in pixels, or if a number is followed by a percentage sign (%),
4928 in percents of the screen size.
4929 This option never changes the aspect ratio of the window. If the
4931 aspect ratio mismatches, the window's size is reduced until it
4932 fits into the specified size.
4933 Window position is not taken into account, nor is it modified by
4935 this option (the window manager still may place the window dif‐
4936 ferently depending on size). Use --geometry to change the window
4937 position. Its effects are applied after this option.
4938 See --geometry for details how this is handled with multi-moni‐
4940 tor setups.
4941 Use --autofit-larger instead if you just want to limit the maxi‐
4943 mum size of the window, rather than always forcing a window
4944 size.
4945 Use --geometry if you want to force both window width and height
4947 to a specific size.
4948 NOTE:
4950 Generally only supported by GUI VOs. Ignored for encoding.
4951 Examples
4953 70% Make the window width 70% of the screen size, keeping
4955 aspect ratio.
4956 1000 Set the window width to 1000 pixels, keeping aspect
4958 ratio.
4959 70%x60%
4961 Make the window as large as possible, without being
4962 wider than 70% of the screen width, or higher than 60%
4963 of the screen height.
4964 --autofit-larger=<[W[xH]]>
4966 This option behaves exactly like --autofit, except the window
4967 size is only changed if the window would be larger than the
4968 specified size.
4969 Example
4971 90%x80%
4973 If the video is larger than 90% of the screen width or
4974 80% of the screen height, make the window smaller un‐
4975 til either its width is 90% of the screen, or its
4976 height is 80% of the screen.
4977 --autofit-smaller=<[W[xH]]>
4979 This option behaves exactly like --autofit, except that it sets
4980 the minimum size of the window (just as --autofit-larger sets
4981 the maximum).
4982 Example
4984 500x500
4986 Make the window at least 500 pixels wide and 500 pix‐
4987 els high (depending on the video aspect ratio, the
4988 width or height will be larger than 500 in order to
4989 keep the aspect ratio the same).
4990 --window-scale=<factor>
4992 Resize the video window to a multiple (or fraction) of the video
4993 size. This option is applied before --autofit and other options
4994 are applied (so they override this option).
4995 For example, --window-scale=0.5 would show the window at half
4997 the video size.
4998 --window-minimized=<yes|no>
5000 Whether the video window is minimized or not. Setting this will
5001 minimize, or unminimize, the video window if the current VO sup‐
5002 ports it. Note that some VOs may support minimization while not
5003 supporting unminimization (eg: Wayland).
5004 Whether this option and --window-maximized work on program start
5006 or at runtime, and whether they're (at runtime) updated to re‐
5007 flect the actual window state, heavily depends on the VO and the
5008 windowing system. Some VOs simply do not implement them or parts
5009 of them, while other VOs may be restricted by the windowing sys‐
5010 tems (especially Wayland).
5011 --window-maximized=<yes|no>
5013 Whether the video window is maximized or not. Setting this will
5014 maximize, or unmaximize, the video window if the current VO sup‐
5015 ports it. See --window-minimized for further remarks.
5016 --cursor-autohide=<number|no|always>
5018 Make mouse cursor automatically hide after given number of mil‐
5019 liseconds (default: 1000 ms). no will disable cursor autohide.
5020 always means the cursor will stay hidden.
5021 --cursor-autohide-fs-only
5023 If this option is given, the cursor is always visible in win‐
5024 dowed mode. In fullscreen mode, the cursor is shown or hidden
5025 according to --cursor-autohide.
5026 --no-fixed-vo, --fixed-vo
5028 --no-fixed-vo enforces closing and reopening the video window
5029 for multiple files (one (un)initialization for each file).
5030 --force-rgba-osd-rendering
5032 Change how some video outputs render the OSD and text subtitles.
5033 This does not change appearance of the subtitles and only has
5034 performance implications. For VOs which support native ASS ren‐
5035 dering (like gpu, vdpau, direct3d), this can be slightly faster
5036 or slower, depending on GPU drivers and hardware. For other VOs,
5037 this just makes rendering slower.
5038 --force-render
5040 Forces mpv to always render frames regardless of the visibility
5041 of the window. Currently only affects X11 and Wayland VOs since
5042 they are the only ones that have this optimization (i.e. every‐
5043 thing else always renders regardless of visibility).
5044 --force-window-position
5046 Forcefully move mpv's video output window to default location
5047 whenever there is a change in video parameters, video stream or
5048 file. This used to be the default behavior. Currently only af‐
5049 fects X11 VOs.
5050 --auto-window-resize=<yes|no>
5052 (Wayland, Win32, and X11) By default, mpv will automatically re‐
5053 size itself if the video's size changes (i.e. advancing forward
5054 in a playlist). Setting this to no disables this behavior so the
5055 window size never changes automatically. This option does not
5056 have any impact on the --autofit or --geometry options.
5057 --no-keepaspect, --keepaspect
5059 --no-keepaspect will always stretch the video to window size,
5060 and will disable the window manager hints that force the window
5061 aspect ratio. (Ignored in fullscreen mode.)
5062 --no-keepaspect-window, --keepaspect-window
5064 --keepaspect-window (the default) will lock the window size to
5065 the video aspect. --no-keepaspect-window disables this behavior,
5066 and will instead add black bars if window aspect and video as‐
5067 pect mismatch. Whether this actually works depends on the VO
5068 backend. (Ignored in fullscreen mode.)
5069 --monitoraspect=<ratio>
5071 Set the aspect ratio of your monitor or TV screen. A value of 0
5072 disables a previous setting (e.g. in the config file). Overrides
5073 the --monitorpixelaspect setting if enabled.
5074 See also --monitorpixelaspect and --video-aspect-override.
5076 Examples
5078 • --monitoraspect=4:3 or --monitoraspect=1.3333
5080 • --monitoraspect=16:9 or --monitoraspect=1.7777
5082 --hidpi-window-scale, --no-hidpi-window-scale
5084 (macOS, Windows, X11, and Wayland only) Scale the window size
5085 according to the backing scale factor (default: yes). On regu‐
5086 lar HiDPI resolutions the window opens with double the size but
5087 appears as having the same size as on non-HiDPI resolutions.
5088 --native-fs, --no-native-fs
5090 (macOS only) Uses the native fullscreen mechanism of the OS (de‐
5091 fault: yes).
5092 --monitorpixelaspect=<ratio>
5094 Set the aspect of a single pixel of your monitor or TV screen
5095 (default: 1). A value of 1 means square pixels (correct for (al‐
5096 most?) all LCDs). See also --monitoraspect and --video-as‐
5097 pect-override.
5098 --stop-screensaver=<yes|no|always>
5100 Turns off the screensaver (or screen blanker and similar mecha‐
5101 nisms) at startup and turns it on again on exit (default: yes).
5102 When using yes, the screensaver will re-enable when playback is
5103 not active. always will always disable the screensaver. Note
5104 that stopping the screensaver is only possible if a video output
5105 is available (i.e. there is an open mpv window).
5106 This is not supported on all video outputs or platforms. Some‐
5108 times it is implemented, but does not work (especially with
5109 Linux "desktops"). Read the Disabling Screensaver section very
5110 carefully.
5111 --wid=<ID>
5113 This tells mpv to attach to an existing window. If a VO is se‐
5114 lected that supports this option, it will use that window for
5115 video output. mpv will scale the video to the size of this win‐
5116 dow, and will add black bars to compensate if the aspect ratio
5117 of the video is different.
5118 On X11, the ID is interpreted as a Window on X11. Unlike
5120 MPlayer/mplayer2, mpv always creates its own window, and sets
5121 the wid window as parent. The window will always be resized to
5122 cover the parent window fully. The value 0 is interpreted spe‐
5123 cially, and mpv will draw directly on the root window.
5124 On win32, the ID is interpreted as HWND. Pass it as value cast
5126 to uint32_t (all Windows handles are 32-bit), this is important
5127 as mpv will not accept negative values. mpv will create its own
5128 window and set the wid window as parent, like with X11.
5129 On macOS/Cocoa, the ID is interpreted as NSView*. Pass it as
5131 value cast to intptr_t. mpv will create its own sub-view. Be‐
5132 cause macOS does not support window embedding of foreign pro‐
5133 cesses, this works only with libmpv, and will crash when used
5134 from the command line.
5135 On Android, the ID is interpreted as android.view.Surface. Pass
5137 it as a value cast to intptr_t. Use with --vo=mediacodec_embed
5138 and --hwdec=mediacodec for direct rendering using MediaCodec, or
5139 with --vo=gpu --gpu-context=android (with or without --hwdec=me‐
5140 diacodec).
5141 --no-window-dragging
5143 Don't move the window when clicking on it and moving the mouse
5144 pointer.
5145 --x11-name=<string>
5147 Set the window class name for X11-based video output methods.
5148 --x11-netwm=<yes|no|auto>
5150 (X11 only) Control the use of NetWM protocol features.
5151 This may or may not help with broken window managers. This pro‐
5153 vides some functionality that was implemented by the now removed
5154 --fstype option. Actually, it is not known to the developers to
5155 which degree this option was needed, so feedback is welcome.
5156 Specifically, yes will force use of NetWM fullscreen support,
5158 even if not advertised by the WM. This can be useful for WMs
5159 that are broken on purpose, like XMonad. (XMonad supposedly
5160 doesn't advertise fullscreen support, because Flash uses it. Ap‐
5161 parently, applications which want to use fullscreen anyway are
5162 supposed to either ignore the NetWM support hints, or provide a
5163 workaround. Shame on XMonad for deliberately breaking X proto‐
5164 cols (as if X isn't bad enough already).
5165 By default, NetWM support is autodetected (auto).
5167 This option might be removed in the future.
5169 --x11-bypass-compositor=<yes|no|fs-only|never>
5171 If set to yes, then ask the compositor to unredirect the mpv
5172 window (default: fs-only). This uses the _NET_WM_BYPASS_COMPOSI‐
5173 TOR hint.
5174 fs-only asks the window manager to disable the compositor only
5176 in fullscreen mode.
5177 no sets _NET_WM_BYPASS_COMPOSITOR to 0, which is the default
5179 value as declared by the EWMH specification, i.e. no change is
5180 done.
5181 never asks the window manager to never disable the compositor.
5183 --x11-present=<no|auto|yes>
5185 Whether or not to use presentation statistics from X11's presen‐
5186 tation extension (default: auto).
5187 mpv asks X11 for present events which it then may use for more
5189 accurate frame presentation. This only has an effect if
5190 --video-sync=display-... is being used.
5191 The auto option enumerates XRandr providers for autodetection.
5193 If amd, radeon, intel, or nouveau (the standard x86 Mesa driv‐
5194 ers) is found and nvidia is NOT found, presentation feedback is
5195 enabled. Other drivers are not assumed to work, so they are not
5196 enabled automatically.
5197 yes or no can still be passed regardless to enable/disable this
5199 mechanism in case there is good/bad behavior with whatever your
5200 combination of hardware/drivers/etc. happens to be.
5201 Disc Devices
5203 --cdrom-device=<path>
5204 Specify the CD-ROM device (default: /dev/cdrom).
5205 --dvd-device=<path>
5207 Specify the DVD device or .iso filename (default: /dev/dvd). You
5208 can also specify a directory that contains files previously
5209 copied directly from a DVD (with e.g. vobcopy).
5210 Example
5212 mpv dvd:// --dvd-device=/path/to/dvd/
5214 --bluray-device=<path>
5216 (Blu-ray only) Specify the Blu-ray disc location. Must be a di‐
5217 rectory with Blu-ray structure.
5218 Example
5220 mpv bd:// --bluray-device=/path/to/bd/
5222 --cdda-...
5224 These options can be used to tune the CD Audio reading feature
5225 of mpv.
5226 --cdda-speed=<value>
5228 Set CD spin speed.
5229 --cdda-paranoia=<0-2>
5231 Set paranoia level. Values other than 0 seem to break playback
5232 of anything but the first track.
5233 0 disable checking (default)
5235 1 overlap checking only
5237 2 full data correction and verification
5239 --cdda-sector-size=<value>
5241 Set atomic read size.
5242 --cdda-overlap=<value>
5244 Force minimum overlap search during verification to <value> sec‐
5245 tors.
5246 --cdda-toc-bias
5248 Assume that the beginning offset of track 1 as reported in the
5249 TOC will be addressed as LBA 0. Some discs need this for getting
5250 track boundaries correctly.
5251 --cdda-toc-offset=<value>
5253 Add <value> sectors to the values reported when addressing
5254 tracks. May be negative.
5255 --cdda-skip=<yes|no>
5257 (Never) accept imperfect data reconstruction.
5258 --cdda-cdtext=<yes|no>
5260 Print CD text. This is disabled by default, because it ruins
5261 performance with CD-ROM drives for unknown reasons.
5262 --dvd-speed=<speed>
5264 Try to limit DVD speed (default: 0, no change). DVD base speed
5265 is 1385 kB/s, so an 8x drive can read at speeds up to 11080
5266 kB/s. Slower speeds make the drive more quiet. For watching
5267 DVDs, 2700 kB/s should be quiet and fast enough. mpv resets the
5268 speed to the drive default value on close. Values of at least
5269 100 mean speed in kB/s. Values less than 100 mean multiples of
5270 1385 kB/s, i.e. --dvd-speed=8 selects 11080 kB/s.
5271 NOTE:
5273 You need write access to the DVD device to change the speed.
5274 --dvd-angle=<ID>
5276 Some DVDs contain scenes that can be viewed from multiple an‐
5277 gles. This option tells mpv which angle to use (default: 1).
5278 Equalizer
5280 --brightness=<-100-100>
5281 Adjust the brightness of the video signal (default: 0). Not sup‐
5282 ported by all video output drivers.
5283 --contrast=<-100-100>
5285 Adjust the contrast of the video signal (default: 0). Not sup‐
5286 ported by all video output drivers.
5287 --saturation=<-100-100>
5289 Adjust the saturation of the video signal (default: 0). You can
5290 get grayscale output with this option. Not supported by all
5291 video output drivers.
5292 --gamma=<-100-100>
5294 Adjust the gamma of the video signal (default: 0). Not supported
5295 by all video output drivers.
5296 --hue=<-100-100>
5298 Adjust the hue of the video signal (default: 0). You can get a
5299 colored negative of the image with this option. Not supported by
5300 all video output drivers.
5301 Demuxer
5303 --demuxer=<[+]name>
5304 Force demuxer type. Use a '+' before the name to force it; this
5305 will skip some checks. Give the demuxer name as printed by --de‐
5306 muxer=help.
5307 --demuxer-lavf-analyzeduration=<value>
5309 Maximum length in seconds to analyze the stream properties.
5310 --demuxer-lavf-probe-info=<yes|no|auto|nostreams>
5312 Whether to probe stream information (default: auto). Techni‐
5313 cally, this controls whether libavformat's avfor‐
5314 mat_find_stream_info() function is called. Usually it's safer to
5315 call it, but it can also make startup slower.
5316 The auto choice (the default) tries to skip this for a few
5318 know-safe whitelisted formats, while calling it for everything
5319 else.
5320 The nostreams choice only calls it if and only if the file seems
5322 to contain no streams after opening (helpful in cases when call‐
5323 ing the function is needed to detect streams at all, such as
5324 with FLV files).
5325 --demuxer-lavf-probescore=<1-100>
5327 Minimum required libavformat probe score. Lower values will re‐
5328 quire less data to be loaded (makes streams start faster), but
5329 makes file format detection less reliable. Can be used to force
5330 auto-detected libavformat demuxers, even if libavformat consid‐
5331 ers the detection not reliable enough. (Default: 26.)
5332 --demuxer-lavf-allow-mimetype=<yes|no>
5334 Allow deriving the format from the HTTP MIME type (default:
5335 yes). Set this to no in case playing things from HTTP mysteri‐
5336 ously fails, even though the same files work from local disk.
5337 This is default in order to reduce latency when opening HTTP
5339 streams.
5340 --demuxer-lavf-format=<name>
5342 Force a specific libavformat demuxer.
5343 --demuxer-lavf-hacks=<yes|no>
5345 By default, some formats will be handled differently from other
5346 formats by explicitly checking for them. Most of these compen‐
5347 sate for weird or imperfect behavior from libavformat demuxers.
5348 Passing no disables these. For debugging and testing only.
5349 --demuxer-lavf-o=<key>=<value>[,<key>=<value>[,...]]
5351 Pass AVOptions to libavformat demuxer.
5352 Note, a patch to make the o= unneeded and pass all unknown op‐
5354 tions through the AVOption system is welcome. A full list of
5355 AVOptions can be found in the FFmpeg manual. Note that some op‐
5356 tions may conflict with mpv options.
5357 This is a key/value list option. See List Options for details.
5359 Example
5361 --demuxer-lavf-o=fflags=+ignidx
5363 --demuxer-lavf-probesize=<value>
5365 Maximum amount of data to probe during the detection phase. In
5366 the case of MPEG-TS this value identifies the maximum number of
5367 TS packets to scan.
5368 --demuxer-lavf-buffersize=<value>
5370 Size of the stream read buffer allocated for libavformat in
5371 bytes (default: 32768). Lowering the size could lower latency.
5372 Note that libavformat might reallocate the buffer internally, or
5373 not fully use all of it.
5374 --demuxer-lavf-linearize-timestamps=<yes|no|auto>
5376 Attempt to linearize timestamp resets in demuxed streams (de‐
5377 fault: auto). This was tested only for single audio streams.
5378 It's unknown whether it works correctly for video (but likely
5379 won't). Note that the implementation is slightly incorrect ei‐
5380 ther way, and will introduce a discontinuity by about 1 codec
5381 frame size.
5382 The auto mode enables this for OGG audio stream. This covers the
5384 common and annoying case of OGG web radio streams. Some of these
5385 will reset timestamps to 0 every time a new song begins. This
5386 breaks the mpv seekable cache, which can't deal with timestamp
5387 resets. Note that FFmpeg/libavformat's seeking API can't deal
5388 with this either; it's likely that if this option breaks this
5389 even more, while if it's disabled, you can at least seek within
5390 the first song in the stream. Well, you won't get anything use‐
5391 ful either way if the seek is outside of mpv's cache.
5392 --demuxer-lavf-propagate-opts=<yes|no>
5394 Propagate FFmpeg-level options to recursively opened connections
5395 (default: yes). This is needed because FFmpeg will apply these
5396 settings to nested AVIO contexts automatically. On the other
5397 hand, this could break in certain situations - it's the FFmpeg
5398 API, you just can't win.
5399 This affects in particular the --timeout option and anything
5401 passed with --demuxer-lavf-o.
5402 If this option is deemed unnecessary at some point in the fu‐
5404 ture, it will be removed without notice.
5405 --demuxer-mkv-subtitle-preroll=<yes|index|no>, --mkv-subtitle-preroll
5407 Try harder to show embedded soft subtitles when seeking some‐
5408 where. Normally, it can happen that the subtitle at the seek
5409 target is not shown due to how some container file formats are
5410 designed. The subtitles appear only if seeking before or exactly
5411 to the position a subtitle first appears. To make this worse,
5412 subtitles are often timed to appear a very small amount before
5413 the associated video frame, so that seeking to the video frame
5414 typically does not demux the subtitle at that position.
5415 Enabling this option makes the demuxer start reading data a bit
5417 before the seek target, so that subtitles appear correctly. Note
5418 that this makes seeking slower, and is not guaranteed to always
5419 work. It only works if the subtitle is close enough to the seek
5420 target.
5421 Works with the internal Matroska demuxer only. Always enabled
5423 for absolute and hr-seeks, and this option changes behavior with
5424 relative or imprecise seeks only.
5425 You can use the --demuxer-mkv-subtitle-preroll-secs option to
5427 specify how much data the demuxer should pre-read at most in or‐
5428 der to find subtitle packets that may overlap. Setting this to 0
5429 will effectively disable this preroll mechanism. Setting a very
5430 large value can make seeking very slow, and an extremely large
5431 value would completely reread the entire file from start to seek
5432 target on every seek - seeking can become slower towards the end
5433 of the file. The details are messy, and the value is actually
5434 rounded down to the cluster with the previous video keyframe.
5435 Some files, especially files muxed with newer mkvmerge versions,
5437 have information embedded that can be used to determine what
5438 subtitle packets overlap with a seek target. In these cases, mpv
5439 will reduce the amount of data read to a minimum. (Although it
5440 will still read all data between the cluster that contains the
5441 first wanted subtitle packet, and the seek target.) If the index
5442 choice (which is the default) is specified, then prerolling will
5443 be done only if this information is actually available. If this
5444 method is used, the maximum amount of data to skip can be addi‐
5445 tionally controlled by --demuxer-mkv-subtitle-preroll-secs-index
5446 (it still uses the value of the option without -index if that is
5447 higher).
5448 See also --hr-seek-demuxer-offset option. This option can
5450 achieve a similar effect, but only if hr-seek is active. It
5451 works with any demuxer, but makes seeking much slower, as it has
5452 to decode audio and video data instead of just skipping over it.
5453 --mkv-subtitle-preroll is a deprecated alias.
5455 --demuxer-mkv-subtitle-preroll-secs=<value>
5457 See --demuxer-mkv-subtitle-preroll.
5458 --demuxer-mkv-subtitle-preroll-secs-index=<value>
5460 See --demuxer-mkv-subtitle-preroll.
5461 --demuxer-mkv-probe-start-time=<yes|no>
5463 Check the start time of Matroska files (default: yes). This sim‐
5464 ply reads the first cluster timestamps and assumes it is the
5465 start time. Technically, this also reads the first timestamp,
5466 which may increase latency by one frame (which may be relevant
5467 for live streams).
5468 --demuxer-mkv-probe-video-duration=<yes|no|full>
5470 When opening the file, seek to the end of it, and check what
5471 timestamp the last video packet has, and report that as file du‐
5472 ration. This is strictly for compatibility with Haali only. In
5473 this mode, it's possible that opening will be slower (especially
5474 when playing over http), or that behavior with broken files is
5475 much worse. So don't use this option.
5476 The yes mode merely uses the index and reads a small number of
5478 blocks from the end of the file. The full mode actually tra‐
5479 verses the entire file and can make a reliable estimate even
5480 without an index present (such as partial files).
5481 --demuxer-rawaudio-channels=<value>
5483 Number of channels (or channel layout) if --demuxer=rawaudio is
5484 used (default: stereo).
5485 --demuxer-rawaudio-format=<value>
5487 Sample format for --demuxer=rawaudio (default: s16le). Use
5488 --demuxer-rawaudio-format=help to get a list of all formats.
5489 --demuxer-rawaudio-rate=<value>
5491 Sample rate for --demuxer=rawaudio (default: 44 kHz).
5492 --demuxer-rawvideo-fps=<value>
5494 Rate in frames per second for --demuxer=rawvideo (default:
5495 25.0).
5496 --demuxer-rawvideo-w=<value>, --demuxer-rawvideo-h=<value>
5498 Image dimension in pixels for --demuxer=rawvideo.
5499 Example
5501 Play a raw YUV sample:
5503 mpv sample-720x576.yuv --demuxer=rawvideo \
5505 --demuxer-rawvideo-w=720 --demuxer-rawvideo-h=576
5506 --demuxer-rawvideo-format=<value>
5508 Color space (fourcc) in hex or string for --demuxer=rawvideo
5509 (default: YV12).
5510 --demuxer-rawvideo-mp-format=<value>
5512 Color space by internal video format for --demuxer=rawvideo. Use
5513 --demuxer-rawvideo-mp-format=help for a list of possible for‐
5514 mats.
5515 --demuxer-rawvideo-codec=<value>
5517 Set the video codec instead of selecting the rawvideo codec when
5518 using --demuxer=rawvideo. This uses the same values as codec
5519 names in --vd (but it does not accept decoder names).
5520 --demuxer-rawvideo-size=<value>
5522 Frame size in bytes when using --demuxer=rawvideo.
5523 --demuxer-cue-codepage=<codepage>
5525 Specify the CUE sheet codepage. (See --sub-codepage for de‐
5526 tails.)
5527 --demuxer-max-bytes=<bytesize>
5529 This controls how much the demuxer is allowed to buffer ahead.
5530 The demuxer will normally try to read ahead as much as neces‐
5531 sary, or as much is requested with --demuxer-readahead-secs. The
5532 option can be used to restrict the maximum readahead. This lim‐
5533 its excessive readahead in case of broken files or desynced
5534 playback. The demuxer will stop reading additional packets as
5535 soon as one of the limits is reached. (The limits still can be
5536 slightly overstepped due to technical reasons.)
5537 Set these limits higher if you get a packet queue overflow warn‐
5539 ing, and you think normal playback would be possible with a
5540 larger packet queue.
5541 See --list-options for defaults and value range. <bytesize> op‐
5543 tions accept suffixes such as KiB and MiB.
5544 --demuxer-max-back-bytes=<bytesize>
5546 This controls how much past data the demuxer is allowed to pre‐
5547 serve. This is useful only if the cache is enabled.
5548 Unlike the forward cache, there is no control how many seconds
5550 are actually cached - it will simply use as much memory this op‐
5551 tion allows. Setting this option to 0 will strictly disable any
5552 back buffer, but this will lead to the situation that the for‐
5553 ward seek range starts after the current playback position (as
5554 it removes past packets that are seek points).
5555 If the end of the file is reached, the remaining unused forward
5557 buffer space is "donated" to the backbuffer (unless the back‐
5558 buffer size is set to 0, or --demuxer-donate-buffer is set to
5559 no). This still limits the total cache usage to the sum of the
5560 forward and backward cache, and effectively makes better use of
5561 the total allowed memory budget. (The opposite does not happen:
5562 free backward buffer is never "donated" to the forward buffer.)
5563 Keep in mind that other buffers in the player (like decoders)
5565 will cause the demuxer to cache "future" frames in the back buf‐
5566 fer, which can skew the impression about how much data the back‐
5567 buffer contains.
5568 See --list-options for defaults and value range.
5570 --demuxer-donate-buffer=<yes|no>
5572 Whether to let the back buffer use part of the forward buffer
5573 (default: yes). If set to yes, the "donation" behavior de‐
5574 scribed in the option description for --demuxer-max-back-bytes
5575 is enabled. This means the back buffer may use up memory up to
5576 the sum of the forward and back buffer options, minus the active
5577 size of the forward buffer. If set to no, the options strictly
5578 limit the forward and back buffer sizes separately.
5579 Note that if the end of the file is reached, the buffered data
5581 stays the same, even if you seek back within the cache. This is
5582 because the back buffer is only reduced when new data is read.
5583 --demuxer-seekable-cache=<yes|no|auto>
5585 Debugging option to control whether seeking can use the demuxer
5586 cache (default: auto). Normally you don't ever need to set this;
5587 the default auto does the right thing and enables cache seeking
5588 it if --cache is set to yes (or is implied yes if --cache=auto).
5589 If enabled, short seek offsets will not trigger a low level de‐
5591 muxer seek (which means for example that slow network round
5592 trips or FFmpeg seek bugs can be avoided). If a seek cannot hap‐
5593 pen within the cached range, a low level seek will be triggered.
5594 Seeking outside of the cache will start a new cached range, but
5595 can discard the old cache range if the demuxer exhibits certain
5596 unsupported behavior.
5597 The special value auto means yes in the same situation as
5599 --cache-secs is used (i.e. when the stream appears to be a net‐
5600 work stream or the stream cache is enabled).
5601 --demuxer-force-retry-on-eof=<yes|no>
5603 Whether to keep retrying making the demuxer thread read more
5604 packets each time the decoder dequeues a packet, even if the end
5605 of the file was reached (default: no). This does not really make
5606 sense, but was the default behavior in mpv 0.32.0 and earlier.
5607 This option will be silently removed after a while, and exists
5608 only to restore the old behavior for testing, in case this was
5609 actually needed somewhere. This does _not_ help with files that
5610 are being appended to (in these cases use appending://, or dis‐
5611 able the cache).
5612 --demuxer-thread=<yes|no>
5614 Run the demuxer in a separate thread, and let it prefetch a cer‐
5615 tain amount of packets (default: yes). Having this enabled leads
5616 to smoother playback, enables features like prefetching, and
5617 prevents that stuck network freezes the player. On the other
5618 hand, it can add overhead, or the background prefetching can hog
5619 CPU resources.
5620 Disabling this option is not recommended. Use it for debugging
5622 only.
5623 --demuxer-termination-timeout=<seconds>
5625 Number of seconds the player should wait to shutdown the demuxer
5626 (default: 0.1). The player will wait up to this much time before
5627 it closes the stream layer forcefully. Forceful closing usually
5628 means the network I/O is given no chance to close its connec‐
5629 tions gracefully (of course the OS can still close TCP connec‐
5630 tions properly), and might result in annoying messages being
5631 logged, and in some cases, confused remote servers.
5632 This timeout is usually only applied when loading has finished
5634 properly. If loading is aborted by the user, or in some corner
5635 cases like removing external tracks sourced from network during
5636 playback, forceful closing is always used.
5637 --demuxer-readahead-secs=<seconds>
5639 If --demuxer-thread is enabled, this controls how much the de‐
5640 muxer should buffer ahead in seconds (default: 1). As long as no
5641 packet has a timestamp difference higher than the readahead
5642 amount relative to the last packet returned to the decoder, the
5643 demuxer keeps reading.
5644 Note that enabling the cache (such as --cache=yes, or if the in‐
5646 put is considered a network stream, and --cache=auto is used),
5647 this option is mostly ignored. (--cache-secs will override this.
5648 Technically, the maximum of both options is used.)
5649 The main purpose of this option is to limit the readhead for lo‐
5651 cal playback, since a large readahead value is not overly useful
5652 in this case.
5653 (This value tends to be fuzzy, because many file formats don't
5655 store linear timestamps.)
5656 --demuxer-hysteresis-secs=<seconds>
5658 Once the --demuxer-max-bytes limit is reached, this value can be
5659 used to specify a hysteresis before the demuxer will buffer
5660 ahead again. This specifies the maximum number of seconds from
5661 the current playback position that needs to be remaining in the
5662 cache before the demuxer will continue buffering ahead.
5663 For example, with a value of 10 seconds specified, the demuxer
5665 will buffer ahead up to --demuxer-max-bytes and won't start
5666 buffering ahead again until there is only 10 seconds of content
5667 left in the cache. When the demuxer starts buffering ahead
5668 again, it will buffer ahead up to --demuxer-max-bytes and stop
5669 until there's only 10 seconds of content remaining in the cache,
5670 and so on.
5671 This can provide significant power savings and reduce load by
5673 making the demuxer only buffer ahead in chunks at a time rather
5674 than buffering ahead nonstop to keep the cache filled.
5675 If you want to save power and reduce load, configure this to a
5677 small number that's much lower than --cache-secs or --de‐
5678 muxer-readahead-secs. If it takes a long time to buffer any‐
5679 thing at all for a given stream (like when reading from a very
5680 slow disk is involved), then the hysteresis value should be
5681 larger to compensate.
5682 The default value is 0 seconds, which disables the caching hys‐
5684 teresis. A value of 10 seconds probably works well for most use‐
5685 cases.
5686 --prefetch-playlist=<yes|no>
5688 Prefetch next playlist entry while playback of the current entry
5689 is ending (default: no).
5690 This does not prefill the cache with the video data of the next
5692 URL. Prefetching video data is supported only for the current
5693 playlist entry, and depends on the demuxer cache settings (on by
5694 default). This merely opens the URL of the next playlist entry
5695 as soon the current URL is fully read.
5696 This does not work with URLs resolved by the youtube-dl wrapper,
5698 and it won't.
5699 This can give subtly wrong results if per-file options are used,
5701 or if options are changed in the time window between prefetching
5702 start and next file played.
5703 This can occasionally make wrong prefetching decisions. For ex‐
5705 ample, it can't predict whether you go backwards in the
5706 playlist, and assumes you won't edit the playlist.
5707 Highly experimental.
5709 --force-seekable=<yes|no>
5711 If the player thinks that the media is not seekable (e.g. play‐
5712 ing from a pipe, or it's an http stream with a server that
5713 doesn't support range requests), seeking will be disabled. This
5714 option can forcibly enable it. For seeks within the cache,
5715 there's a good chance of success.
5716 --demuxer-cache-wait=<yes|no>
5718 Before starting playback, read data until either the end of the
5719 file was reached, or the demuxer cache has reached maximum ca‐
5720 pacity. Only once this is done, playback starts. This intention‐
5721 ally happens before the initial seek triggered with --start.
5722 This does not change any runtime behavior after the initial
5723 caching. This option is useless if the file cannot be cached
5724 completely.
5725 --rar-list-all-volumes=<yes|no>
5727 When opening multi-volume rar files, open all volumes to create
5728 a full list of contained files (default: no). If disabled, only
5729 the archive entries whose headers are located within the first
5730 volume are listed (and thus played when opening a .rar file with
5731 mpv). Doing so speeds up opening, and the typical idiotic
5732 use-case of playing uncompressed multi-volume rar files that
5733 contain a single media file is made faster.
5734 Opening is still slow, because for unknown, idiotic, and unnec‐
5736 essary reasons libarchive opens all volumes anyway when playing
5737 the main file, even though mpv iterated no archive entries yet.
5738 --directory-mode=<recursive|lazy|ignore>
5740 When opening a directory, open subdirectories recursively,
5741 lazily or not at all (default: recursive).
5742 Values other then recursive can lead to problems with resuming
5744 playlists (RESUMING PLAYBACK) and possibly other things.
5745 Input
5747 --native-keyrepeat
5748 Use system settings for keyrepeat delay and rate, instead of
5749 --input-ar-delay and --input-ar-rate. (Whether this applies de‐
5750 pends on the VO backend and how it handles keyboard input. Does
5751 not apply to terminal input.)
5752 --input-ar-delay
5754 Delay in milliseconds before we start to autorepeat a key (0 to
5755 disable).
5756 --input-ar-rate
5758 Number of key presses to generate per second on autorepeat.
5759 --input-conf=<filename>
5761 Specify input configuration file other than the default location
5762 in the mpv configuration directory (usually ~/.config/mpv/in‐
5763 put.conf).
5764 --no-input-default-bindings
5766 Disable default-level ("weak") key bindings. These are bindings
5767 which config files like input.conf can override. It currently
5768 affects the builtin key bindings, and keys which scripts bind
5769 using mp.add_key_binding (but not mp.add_forced_key_binding be‐
5770 cause this overrides input.conf).
5771 --no-input-builtin-bindings
5773 Disable loading of built-in key bindings during start-up. This
5774 option is applied only during (lib)mpv initialization, and if
5775 used then it will not be not possible to enable them later. May
5776 be useful to libmpv clients.
5777 --input-cmdlist
5779 Prints all commands that can be bound to keys.
5780 --input-doubleclick-time=<milliseconds>
5782 Time in milliseconds to recognize two consecutive button presses
5783 as a double-click (default: 300).
5784 --input-keylist
5786 Prints all keys that can be bound to commands.
5787 --input-key-fifo-size=<2-65000>
5789 Specify the size of the FIFO that buffers key events (default:
5790 7). If it is too small, some events may be lost. The main disad‐
5791 vantage of setting it to a very large value is that if you hold
5792 down a key triggering some particularly slow command then the
5793 player may be unresponsive while it processes all the queued
5794 commands.
5795 --input-test
5797 Input test mode. Instead of executing commands on key presses,
5798 mpv will show the keys and the bound commands on the OSD. Has to
5799 be used with a dummy video, and the normal ways to quit the
5800 player will not work (key bindings that normally quit will be
5801 shown on OSD only, just like any other binding). See INPUT.CONF.
5802 --input-terminal, --no-input-terminal
5804 --no-input-terminal prevents the player from reading key events
5805 from standard input. Useful when reading data from standard in‐
5806 put. This is automatically enabled when - is found on the com‐
5807 mand line. There are situations where you have to set it manu‐
5808 ally, e.g. if you open /dev/stdin (or the equivalent on your
5809 system), use stdin in a playlist or intend to read from stdin
5810 later on via the loadfile or loadlist input commands.
5811 --input-ipc-server=<filename>
5813 Enable the IPC support and create the listening socket at the
5814 given path.
5815 On Linux and Unix, the given path is a regular filesystem path.
5817 On Windows, named pipes are used, so the path refers to the pipe
5818 namespace (\\.\pipe\<name>). If the \\.\pipe\ prefix is missing,
5819 mpv will add it automatically before creating the pipe, so --in‐
5820 put-ipc-server=/tmp/mpv-socket and --in‐
5821 put-ipc-server=\\.\pipe\tmp\mpv-socket are equivalent for IPC on
5822 Windows.
5823 See JSON IPC for details.
5825 --input-ipc-client=fd://<N>
5827 Connect a single IPC client to the given FD. This is somewhat
5828 similar to --input-ipc-server, except no socket is created, and
5829 instead the passed FD is treated like a socket connection re‐
5830 ceived from accept(). In practice, you could pass either a FD
5831 created by socketpair(), or a pipe. In both cases, you must
5832 sure the FD is actually inherited by mpv (do not set the POSIX
5833 CLOEXEC flag).
5834 The player quits when the connection is closed.
5836 This is somewhat similar to the removed --input-file option, ex‐
5838 cept it supports only integer FDs, and cannot open actual paths.
5839 Example
5841 --input-ipc-client=fd://123
5843 NOTE:
5845 Does not and will not work on Windows.
5846 WARNING:
5848 Writing to the input-ipc-server option at runtime will start
5849 another instance of an IPC client handler for the in‐
5850 put-ipc-client option, because initialization is bundled, and
5851 this thing is stupid. This is a bug. Writing to in‐
5852 put-ipc-client at runtime will start another IPC client han‐
5853 dler for the new value, without stopping the old one, even if
5854 the FD value is the same (but the string is different e.g.
5855 due to whitespace). This is not a bug.
5856 --input-gamepad=<yes|no>
5858 Enable/disable SDL2 Gamepad support. Disabled by default.
5859 --input-cursor, --no-input-cursor
5861 Permit mpv to receive pointer events reported by the video out‐
5862 put driver. Necessary to use the OSC, or to select the buttons
5863 in DVD menus. Support depends on the VO in use.
5864 --input-cursor-passthrough, --no-input-cursor-passthrough
5866 (X11 and Wayland only) Tell the backend windowing system to al‐
5867 low pointer events to passthrough the mpv window. This allows
5868 windows under mpv to instead receive pointer events as if the
5869 mpv window was never there.
5870 --input-media-keys=<yes|no>
5872 On systems where mpv can choose between receiving media keys or
5873 letting the system handle them - this option controls whether
5874 mpv should receive them.
5875 Default: yes (except for libmpv). macOS and Windows only, be‐
5877 cause elsewhere mpv doesn't have a choice - the system decides
5878 whether to send media keys to mpv. For instance, on X11 or Way‐
5879 land, system-wide media keys are not implemented. Whether media
5880 keys work when the mpv window is focused is implementation-de‐
5881 fined.
5882 --input-right-alt-gr, --no-input-right-alt-gr
5884 (Cocoa and Windows only) Use the right Alt key as Alt Gr to pro‐
5885 duce special characters. If disabled, count the right Alt as an
5886 Alt modifier key. Enabled by default.
5887 --input-vo-keyboard=<yes|no>
5889 Disable all keyboard input on for VOs which can't participate in
5890 proper keyboard input dispatching. May not affect all VOs. Gen‐
5891 erally useful for embedding only.
5892 On X11, a sub-window with input enabled grabs all keyboard input
5894 as long as it is 1. a child of a focused window, and 2. the
5895 mouse is inside of the sub-window. It can steal away all key‐
5896 board input from the application embedding the mpv window, and
5897 on the other hand, the mpv window will receive no input if the
5898 mouse is outside of the mpv window, even though mpv has focus.
5899 Modern toolkits work around this weird X11 behavior, but naively
5900 embedding foreign windows breaks it.
5901 The only way to handle this reasonably is using the XEmbed pro‐
5903 tocol, which was designed to solve these problems. GTK provides
5904 GtkSocket, which supports XEmbed. Qt doesn't seem to provide
5905 anything working in newer versions.
5906 If the embedder supports XEmbed, input should work with default
5908 settings and with this option disabled. Note that input-de‐
5909 fault-bindings is disabled by default in libmpv as well - it
5910 should be enabled if you want the mpv default key bindings.
5911 (This option was renamed from --input-x11-keyboard.)
5913 OSD
5915 --osc, --no-osc
5916 Whether to load the on-screen-controller (default: yes).
5917 --no-osd-bar, --osd-bar
5919 Disable display of the OSD bar.
5920 You can configure this on a per-command basis in input.conf us‐
5922 ing osd- prefixes, see Input Command Prefixes. If you want to
5923 disable the OSD completely, use --osd-level=0.
5924 --osd-on-seek=<no,bar,msg,msg-bar>
5926 Set what is displayed on the OSD during seeks. The default is
5927 bar.
5928 You can configure this on a per-command basis in input.conf us‐
5930 ing osd- prefixes, see Input Command Prefixes.
5931 --osd-duration=<time>
5933 Set the duration of the OSD messages in ms (default: 1000).
5934 --osd-font=<name>
5936 Specify font to use for OSD. The default is sans-serif.
5937 Examples
5939 • --osd-font='Bitstream Vera Sans'
5941 • --osd-font='Comic Sans MS'
5943 --osd-font-size=<size>
5945 Specify the OSD font size. See --sub-font-size for details.
5946 Default: 55.
5948 --osd-msg1=<string>
5950 Show this string as message on OSD with OSD level 1 (visible by
5951 default). The message will be visible by default, and as long
5952 as no other message covers it, and the OSD level isn't changed
5953 (see --osd-level). Expands properties; see Property Expansion.
5954 --osd-msg2=<string>
5956 Similar to --osd-msg1, but for OSD level 2. If this is an empty
5957 string (default), then the playback time is shown.
5958 --osd-msg3=<string>
5960 Similar to --osd-msg1, but for OSD level 3. If this is an empty
5961 string (default), then the playback time, duration, and some
5962 more information is shown.
5963 This is used for the show-progress command (by default mapped to
5965 P), and when seeking if enabled with --osd-on-seek or by osd-
5966 prefixes in input.conf (see Input Command Prefixes).
5967 --osd-status-msg is a legacy equivalent (but with a minor dif‐
5969 ference).
5970 --osd-status-msg=<string>
5972 Show a custom string during playback instead of the standard
5973 status text. This overrides the status text used for
5974 --osd-level=3, when using the show-progress command (by default
5975 mapped to P), and when seeking if enabled with --osd-on-seek or
5976 osd- prefixes in input.conf (see Input Command Prefixes). Ex‐
5977 pands properties. See Property Expansion.
5978 This option has been replaced with --osd-msg3. The only differ‐
5980 ence is that this option implicitly includes ${osd-sym-cc}. This
5981 option is ignored if --osd-msg3 is not empty.
5982 --osd-playing-msg=<string>
5984 Show a message on OSD when playback starts. The string is ex‐
5985 panded for properties, e.g. --osd-playing-msg='file: ${file‐
5986 name}' will show the message file: followed by a space and the
5987 currently played filename.
5988 See Property Expansion.
5990 --osd-playing-msg-duration=<time>
5992 Set the duration of osd-playing-msg in ms. If this is unset,
5993 osd-playing-msg stays on screen for the duration of osd-dura‐
5994 tion.
5995 --osd-bar-align-x=<-1-1>
5997 Position of the OSD bar. -1 is far left, 0 is centered, 1 is far
5998 right. Fractional values (like 0.5) are allowed.
5999 --osd-bar-align-y=<-1-1>
6001 Position of the OSD bar. -1 is top, 0 is centered, 1 is bottom.
6002 Fractional values (like 0.5) are allowed.
6003 --osd-bar-w=<1-100>
6005 Width of the OSD bar, in percentage of the screen width (de‐
6006 fault: 75). A value of 50 means the bar is half the screen
6007 wide.
6008 --osd-bar-h=<0.1-50>
6010 Height of the OSD bar, in percentage of the screen height (de‐
6011 fault: 3.125).
6012 --osd-back-color=<color>
6014 See --sub-color. Color used for OSD text background.
6015 --osd-blur=<0..20.0>
6017 Gaussian blur factor. 0 means no blur applied (default).
6018 --osd-bold=<yes|no>
6020 Format text on bold.
6021 --osd-italic=<yes|no>
6023 Format text on italic.
6024 --osd-border-color=<color>
6026 See --sub-color. Color used for the OSD font border.
6027 NOTE:
6029 ignored when --osd-back-color is specified (or more exactly:
6030 when that option is not set to completely transparent).
6031 --osd-border-size=<size>
6033 Size of the OSD font border in scaled pixels (see
6034 --sub-font-size for details). A value of 0 disables borders.
6035 Default: 3.
6037 --osd-color=<color>
6039 Specify the color used for OSD. See --sub-color for details.
6040 --osd-fractions
6042 Show OSD times with fractions of seconds (in millisecond preci‐
6043 sion). Useful to see the exact timestamp of a video frame.
6044 --osd-level=<0-3>
6046 Specifies which mode the OSD should start in.
6047 0 OSD completely disabled (subtitles only)
6049 1 enabled (shows up only on user interaction)
6051 2 enabled + current time visible by default
6053 3 enabled + --osd-status-msg (current time and status by
6055 default)
6056 --osd-margin-x=<size>
6058 Left and right screen margin for the OSD in scaled pixels (see
6059 --sub-font-size for details).
6060 This option specifies the distance of the OSD to the left, as
6062 well as at which distance from the right border long OSD text
6063 will be broken.
6064 Default: 25.
6066 --osd-margin-y=<size>
6068 Top and bottom screen margin for the OSD in scaled pixels (see
6069 --sub-font-size for details).
6070 This option specifies the vertical margins of the OSD.
6072 Default: 22.
6074 --osd-align-x=<left|center|right>
6076 Control to which corner of the screen OSD should be aligned to
6077 (default: left).
6078 --osd-align-y=<top|center|bottom>
6080 Vertical position (default: top). Details see --osd-align-x.
6081 --osd-scale=<factor>
6083 OSD font size multiplier, multiplied with --osd-font-size value.
6084 --osd-scale-by-window=<yes|no>
6086 Whether to scale the OSD with the window size (default: yes). If
6087 this is disabled, --osd-font-size and other OSD options that use
6088 scaled pixels are always in actual pixels. The effect is that
6089 changing the window size won't change the OSD font size.
6090 --osd-shadow-color=<color>
6092 See --sub-color. Color used for OSD shadow.
6093 --osd-shadow-offset=<size>
6095 Displacement of the OSD shadow in scaled pixels (see
6096 --sub-font-size for details). A value of 0 disables shadows.
6097 Default: 0.
6099 --osd-spacing=<size>
6101 Horizontal OSD/sub font spacing in scaled pixels (see
6102 --sub-font-size for details). This value is added to the normal
6103 letter spacing. Negative values are allowed.
6104 Default: 0.
6106 --video-osd=<yes|no>
6108 Enabled OSD rendering on the video window (default: yes). This
6109 can be used in situations where terminal OSD is preferred. If
6110 you just want to disable all OSD rendering, use --osd-level=0.
6111 It does not affect subtitles or overlays created by scripts (in
6113 particular, the OSC needs to be disabled with --no-osc).
6114 This option is somewhat experimental and could be replaced by
6116 another mechanism in the future.
6117 --osd-font-provider=<...>
6119 See --sub-font-provider for details and accepted values. Note
6120 that unlike subtitles, OSD never uses embedded fonts from media
6121 files.
6122 --osd-fonts-dir=<path>
6124 See --sub-fonts-dir for details. Defaults to ~~/fonts.
6125 Screenshot
6127 --screenshot-format=<type>
6128 Set the image file type used for saving screenshots.
6129 Available choices:
6131 png PNG
6133 jpg JPEG (default)
6135 jpeg JPEG (alias for jpg)
6137 webp WebP
6139 jxl JPEG XL
6141 avif AVIF
6143 --screenshot-tag-colorspace=<yes|no>
6145 Tag screenshots with the appropriate colorspace (default: yes).
6146 Note that not all formats support this. When it is unsupported,
6148 or when this option is disabled, screenshots will be converted
6149 to sRGB before being written.
6150 --screenshot-high-bit-depth=<yes|no>
6152 If possible, write screenshots with a bit depth similar to the
6153 source video (default: yes). This is interesting in particular
6154 for PNG, as this sometimes triggers writing 16 bit PNGs with
6155 huge file sizes. This will also include an unused alpha channel
6156 in the resulting files if 16 bit is used.
6157 --screenshot-template=<template>
6159 Specify the filename template used to save screenshots. The tem‐
6160 plate specifies the filename without file extension, and can
6161 contain format specifiers, which will be substituted when taking
6162 a screenshot. By default, the template is mpv-shot%n, which re‐
6163 sults in filenames like mpv-shot0012.png for example.
6164 The template can start with a relative or absolute path, in or‐
6166 der to specify a directory location where screenshots should be
6167 saved.
6168 If the final screenshot filename points to an already existing
6170 file, the file will not be overwritten. The screenshot will ei‐
6171 ther not be saved, or if the template contains %n, saved using
6172 different, newly generated filename.
6173 Allowed format specifiers:
6175 %[#][0X]n
6177 A sequence number, padded with zeros to length X (de‐
6178 fault: 04). E.g. passing the format %04n will yield 0012
6179 on the 12th screenshot. The number is incremented every
6180 time a screenshot is taken or if the file already exists.
6181 The length X must be in the range 0-9. With the optional
6182 # sign, mpv will use the lowest available number. For ex‐
6183 ample, if you take three screenshots--0001, 0002,
6184 0003--and delete the first two, the next two screenshots
6185 will not be 0004 and 0005, but 0001 and 0002 again.
6186 %f Filename of the currently played video.
6188 %F Same as %f, but strip the file extension, including the
6190 dot.
6191 %x Directory path of the currently played video. If the
6193 video is not on the filesystem (but e.g. http://), this
6194 expand to an empty string.
6195 %X{fallback}
6197 Same as %x, but if the video file is not on the filesys‐
6198 tem, return the fallback string inside the {...}.
6199 %p Current playback time, in the same format as used in the
6201 OSD. The result is a string of the form "HH:MM:SS". For
6202 example, if the video is at the time position 5 minutes
6203 and 34 seconds, %p will be replaced with "00:05:34".
6204 %P Similar to %p, but extended with the playback time in
6206 milliseconds. It is formatted as "HH:MM:SS.mmm", with
6207 "mmm" being the millisecond part of the playback time.
6208 NOTE:
6210 This is a simple way for getting unique per-frame
6211 timestamps. (Frame numbers would be more intuitive,
6212 but are not easily implementable because container
6213 formats usually use time stamps for identifying
6214 frames.)
6215 %wX Specify the current playback time using the format string
6217 X. %p is like %wH:%wM:%wS, and %P is like
6218 %wH:%wM:%wS.%wT.
6219 Valid format specifiers:
6221 %wH hour (padded with 0 to two digits)
6223 %wh hour (not padded)
6225 %wM minutes (00-59)
6227 %wm total minutes (includes hours, unlike %wM)
6229 %wS seconds (00-59)
6231 %ws total seconds (includes hours and minutes)
6233 %wf like %ws, but as float
6235 %wT milliseconds (000-999)
6237 %tX Specify the current local date/time using the format X.
6239 This format specifier uses the UNIX strftime() function
6240 internally, and inserts the result of passing "%X" to
6241 strftime. For example, %tm will insert the number of the
6242 current month as number. You have to use multiple %tX
6243 specifiers to build a full date/time string.
6244 %{prop[:fallback text]}
6246 Insert the value of the input property 'prop'. E.g.
6247 %{filename} is the same as %f. If the property does not
6248 exist or is not available, an error text is inserted, un‐
6249 less a fallback is specified.
6250 %% Replaced with the % character itself.
6252 --screenshot-directory=<path>
6254 Store screenshots in this directory. This path is joined with
6255 the filename generated by --screenshot-template. If the template
6256 filename is already absolute, the directory is ignored.
6257 If the directory does not exist, it is created on the first
6259 screenshot. If it is not a directory, an error is generated when
6260 trying to write a screenshot.
6261 This option is not set by default, and thus will write screen‐
6263 shots to the directory from which mpv was started. In pseudo-gui
6264 mode (see PSEUDO GUI MODE), this is set to the desktop.
6265 --screenshot-jpeg-quality=<0-100>
6267 Set the JPEG quality level. Higher means better quality. The de‐
6268 fault is 90.
6269 --screenshot-jpeg-source-chroma=<yes|no>
6271 Write JPEG files with the same chroma subsampling as the video
6272 (default: yes). If disabled, the libjpeg default is used.
6273 --screenshot-png-compression=<0-9>
6275 Set the PNG compression level. Higher means better compression.
6276 This will affect the file size of the written screenshot file
6277 and the time it takes to write a screenshot. Too high compres‐
6278 sion might occupy enough CPU time to interrupt playback. The de‐
6279 fault is 7.
6280 --screenshot-png-filter=<0-5>
6282 Set the filter applied prior to PNG compression. 0 is none, 1 is
6283 "sub", 2 is "up", 3 is "average", 4 is "Paeth", and 5 is
6284 "mixed". This affects the level of compression that can be
6285 achieved. For most images, "mixed" achieves the best compression
6286 ratio, hence it is the default.
6287 --screenshot-webp-lossless=<yes|no>
6289 Write lossless WebP files. --screenshot-webp-quality is ignored
6290 if this is set. The default is no.
6291 --screenshot-webp-quality=<0-100>
6293 Set the WebP quality level. Higher means better quality. The de‐
6294 fault is 75.
6295 --screenshot-webp-compression=<0-6>
6297 Set the WebP compression level. Higher means better compression,
6298 but takes more CPU time. Note that this also affects the screen‐
6299 shot quality when used with lossy WebP files. The default is 4.
6300 --screenshot-jxl-distance=<0-15>
6302 Set the JPEG XL Butteraugli distance. Lower means better qual‐
6303 ity. Lossless is 0.0, and 1.0 is approximately equivalent to
6304 JPEG quality 90 for photographic content. Use 0.1 for "visually
6305 lossless" screenshots. The default is 1.0.
6306 --screenshot-jxl-effort=<1-9>
6308 Set the JPEG XL compression effort. Higher effort (usually)
6309 means better compression, but takes more CPU time. The default
6310 is 4.
6311 --screenshot-avif-encoder=<encoder>
6313 Specify the AV1 encoder to be used by libavcodec for encoding
6314 avif screenshots.
6315 Default: libaom-av1
6317 --screenshot-avif-pixfmt=<format>
6319 Specify the pixel format to the libavcodec encoder.
6320 Default: yuv420p
6322 --screenshot-avif-opts=key1=value1,key2=value2,...
6324 Specifies libavcodec options for selected encoder. For more in‐
6325 formation, consult the FFmpeg documentation.
6326 Default: usage=allintra,crf=32,cpu-used=8,tune=ssim
6328 Note: the default is only guaranteed to work with the libaom-av1
6330 encoder. Above options may not be valid and or optimal for
6331 other encoders.
6332 This is a key/value list option. See List Options for details.
6334 Example
6336 "--screenshot-avif-opts=crf=32,aq-mode=complexity"
6338 sets the crf to 32 and quantization (aq-mode) to com‐
6339 plexity based.
6340 --screenshot-sw=<yes|no>
6342 Whether to use software rendering for screenshots (default: no).
6343 If set to no, the screenshot will be rendered by the current VO
6345 (only vo_gpu or vo_gpu_next currently). The advantage is that
6346 this will (probably) always show up as in the video window, be‐
6347 cause the same code is used for rendering. But since the ren‐
6348 derer needs to be reinitialized, this can be slow and interrupt
6349 playback.
6350 If set to yes, the software scaler is used to convert the video
6352 to RGB (or whatever the target screenshot requires). In this
6353 case, conversion will run in a separate thread and will probably
6354 not interrupt playback. The software renderer may lack some ca‐
6355 pabilities, such as HDR rendering. If window mode is used, the
6356 image will also be scaled in software which may not accurately
6357 reflect the actual visible result.
6358 Software Scaler
6360 --sws-scaler=<name>
6361 Specify the software scaler algorithm to be used with
6362 --vf=scale. This also affects video output drivers which lack
6363 hardware acceleration, e.g. x11. See also --vf=scale.
6364 To get a list of available scalers, run --sws-scaler=help.
6366 Default: bicubic.
6368 --sws-lgb=<0-100>
6370 Software scaler Gaussian blur filter (luma). See --sws-scaler.
6371 --sws-cgb=<0-100>
6373 Software scaler Gaussian blur filter (chroma). See --sws-scaler.
6374 --sws-ls=<-100-100>
6376 Software scaler sharpen filter (luma). See --sws-scaler.
6377 --sws-cs=<-100-100>
6379 Software scaler sharpen filter (chroma). See --sws-scaler.
6380 --sws-chs=<h>
6382 Software scaler chroma horizontal shifting. See --sws-scaler.
6383 --sws-cvs=<v>
6385 Software scaler chroma vertical shifting. See --sws-scaler.
6386 --sws-bitexact=<yes|no>
6388 Unknown functionality (default: no). Consult libswscale source
6389 code. The primary purpose of this, as far as libswscale API
6390 goes), is to produce exactly the same output for the same input
6391 on all platforms (output has the same "bits" everywhere, thus
6392 "bitexact"). Typically disables optimizations.
6393 --sws-fast=<yes|no>
6395 Allow optimizations that help with performance, but reduce qual‐
6396 ity (default: no).
6397 VOs like drm and x11 will benefit a lot from using --sws-fast.
6399 You may need to set other options, like --sws-scaler. The
6400 builtin sws-fast profile sets this option and some others to
6401 gain performance for reduced quality. Also see --sws-allow-zimg.
6402 --sws-allow-zimg=<yes|no>
6404 Allow using zimg (if the component using the internal swscale
6405 wrapper explicitly allows so) (default: yes). In this case, zimg
6406 may be used, if the internal zimg wrapper supports the input and
6407 output formats. It will silently or noisily fall back to libsws‐
6408 cale if one of these conditions does not apply.
6409 If zimg is used, the other --sws- options are ignored, and the
6411 --zimg- options are used instead.
6412 If the internal component using the swscale wrapper hooks up
6414 logging correctly, a verbose priority log message will indicate
6415 whether zimg is being used.
6416 Most things which need software conversion can make use of this.
6418 NOTE:
6420 Do note that zimg may be slower than libswscale. Usually,
6421 it's faster on x86 platforms, but slower on ARM (due to lack
6422 of ARM specific optimizations). The mpv zimg wrapper uses un‐
6423 optimized repacking for some formats, for which zimg cannot
6424 be blamed.
6425 --zimg-scaler=<point|bilinear|bicubic|spline16|spline36|lanczos>
6427 Zimg luma scaler to use (default: lanczos).
6428 --zimg-scaler-param-a=<default|float>, --zimg-scaler-param-b=<de‐
6430 fault|float>
6431 Set scaler parameters. By default, these are set to the special
6432 string default, which maps to a scaler-specific default value.
6433 Ignored if the scaler is not tunable.
6434 lanczos
6436 --zimg-scaler-param-a is the number of taps.
6437 bicubic
6439 a and b are the bicubic b and c parameters.
6440 --zimg-scaler-chroma=...
6442 Same as --zimg-scaler, for for chroma interpolation (default:
6443 bilinear).
6444 --zimg-scaler-chroma-param-a, --zimg-scaler-chroma-param-b
6446 Same as --zimg-scaler-param-a / --zimg-scaler-param-b, for
6447 chroma.
6448 --zimg-dither=<no|ordered|random|error-diffusion>
6450 Dithering (default: random).
6451 --zimg-threads=<auto|integer>
6453 Set the maximum number of threads to use for scaling (default:
6454 auto). auto uses the number of logical cores on the current ma‐
6455 chine. Note that the scaler may use less threads (or even just 1
6456 thread) depending on stuff. Passing a value of 1 disables
6457 threading and always scales the image in a single operation.
6458 Higher thread counts waste resources, but make it typically
6459 faster.
6460 Note that some zimg git versions had bugs that will corrupt the
6462 output if threads are used.
6463 --zimg-fast=<yes|no>
6465 Allow optimizations that help with performance, but reduce qual‐
6466 ity (default: yes). Currently, this may simplify gamma conver‐
6467 sion operations.
6468 Audio Resampler
6470 This controls the default options of any resampling done by mpv (but
6471 not within libavfilter, within the system audio API resampler, or any
6472 other places).
6473 It also sets the defaults for the lavrresample audio filter.
6475 --audio-resample-filter-size=<length>
6477 Length of the filter with respect to the lower sampling rate.
6478 (default: 16)
6479 --audio-resample-phase-shift=<count>
6481 Log2 of the number of polyphase entries. (..., 10->1024,
6482 11->2048, 12->4096, ...) (default: 10->1024)
6483 --audio-resample-cutoff=<cutoff>
6485 Cutoff frequency (0.0-1.0), default set depending upon filter
6486 length.
6487 --audio-resample-linear=<yes|no>
6489 If set then filters will be linearly interpolated between
6490 polyphase entries. (default: no)
6491 --audio-normalize-downmix=<yes|no>
6493 Enable/disable normalization if surround audio is downmixed to
6494 stereo (default: no). If this is disabled, downmix can cause
6495 clipping. If it's enabled, the output might be too quiet. It de‐
6496 pends on the source audio.
6497 Technically, this changes the normalize suboption of the lavrre‐
6499 sample audio filter, which performs the downmixing.
6500 If downmix happens outside of mpv for some reason, or in the de‐
6502 coder (decoder downmixing), or in the audio output (system
6503 mixer), this has no effect.
6504 --audio-resample-max-output-size=<length>
6506 Limit maximum size of audio frames filtered at once, in ms (de‐
6507 fault: 40). The output size size is limited in order to make
6508 resample speed changes react faster. This is necessary espe‐
6509 cially if decoders or filters output very large frame sizes
6510 (like some lossless codecs or some DRC filters). This option
6511 does not affect the resampling algorithm in any way.
6512 For testing/debugging only. Can be removed or changed any time.
6514 --audio-swresample-o=<string>
6516 Set AVOptions on the SwrContext or AVAudioResampleContext. These
6517 should be documented by FFmpeg or Libav.
6518 This is a key/value list option. See List Options for details.
6520 Terminal
6522 --quiet
6523 Make console output less verbose; in particular, prevents the
6524 status line (i.e. AV: 3.4 (00:00:03.37) / 5320.6 ...) from being
6525 displayed. Particularly useful on slow terminals or broken ones
6526 which do not properly handle carriage return (i.e. \r).
6527 See also: --really-quiet and --msg-level.
6529 --really-quiet
6531 Display even less output and status messages than with --quiet.
6532 --no-terminal, --terminal
6534 Disable any use of the terminal and stdin/stdout/stderr. This
6535 completely silences any message output.
6536 Unlike --really-quiet, this disables input and terminal initial‐
6538 ization as well.
6539 --no-msg-color
6541 Disable colorful console output on terminals.
6542 --msg-level=<module1=level1,module2=level2,...>
6544 Control verbosity directly for each module. The all module
6545 changes the verbosity of all the modules. The verbosity changes
6546 from this option are applied in order from left to right, and
6547 each item can override a previous one.
6548 Run mpv with --msg-level=all=trace to see all messages mpv out‐
6550 puts. You can use the module names printed in the output (pre‐
6551 fixed to each line in [...]) to limit the output to interesting
6552 modules.
6553 This also affects --log-file, and in certain cases libmpv API
6555 logging.
6556 NOTE:
6558 Some messages are printed before the command line is parsed
6559 and are therefore not affected by --msg-level. To control
6560 these messages, you have to use the MPV_VERBOSE environment
6561 variable; see ENVIRONMENT VARIABLES for details.
6562 Available levels:
6564 no complete silence
6566 fatal fatal messages only
6568 error error messages
6570 warn warning messages
6572 info informational messages
6574 status status messages (default)
6576 v verbose messages
6578 debug debug messages
6580 trace very noisy debug messages
6582 Example
6584 mpv --msg-level=ao/sndio=no
6586 Completely silences the output of ao_sndio, which uses the
6588 log prefix [ao/sndio].
6589 mpv --msg-level=all=warn,ao/alsa=error
6591 Only show warnings or worse, and let the ao_alsa output show
6593 errors only.
6594 --term-osd=<auto|no|force>
6596 Control whether OSD messages are shown on the console when no
6597 video output is available (default: auto).
6598 auto use terminal OSD if no video output active
6600 no disable terminal OSD
6602 force use terminal OSD even if video output active
6604 The auto mode also enables terminal OSD if --video-osd=no was
6606 set.
6607 --term-osd-bar, --no-term-osd-bar
6609 Enable printing a progress bar under the status line on the ter‐
6610 minal. (Disabled by default.)
6611 --term-osd-bar-chars=<string>
6613 Customize the --term-osd-bar feature. The string is expected to
6614 consist of 5 characters (start, left space, position indicator,
6615 right space, end). You can use Unicode characters, but note that
6616 double- width characters will not be treated correctly.
6617 Default: [-+-].
6619 --term-playing-msg=<string>
6621 Print out a string after starting playback. The string is ex‐
6622 panded for properties, e.g. --term-playing-msg='file: ${file‐
6623 name}' will print the string file: followed by a space and the
6624 currently played filename.
6625 See Property Expansion.
6627 --term-status-msg=<string>
6629 Print out a custom string during playback instead of the stan‐
6630 dard status line. Expands properties. See Property Expansion.
6631 --term-title=<string>
6633 Set the terminal title. Currently, this simply concatenates the
6634 escape sequence setting the window title with the provided
6635 (property expanded) string. This will mess up if the expanded
6636 string contain bytes that end the escape sequence, or if the
6637 terminal does not understand the sequence. The latter probably
6638 includes the regrettable win32.
6639 Expands properties. See Property Expansion.
6641 --msg-module
6643 Prepend module name to each console message.
6644 --msg-time
6646 Prepend timing information to each console message. The time is
6647 in seconds since the player process was started (technically,
6648 slightly later actually), using a monotonic time source depend‐
6649 ing on the OS. This is CLOCK_MONOTONIC on sane UNIX variants.
6650 Cache
6652 --cache=<yes|no|auto>
6653 Decide whether to use network cache settings (default: auto).
6654 If enabled, use up to --cache-secs for the cache size (but still
6656 limited to --demuxer-max-bytes), and make the cached data seek‐
6657 able (if possible). If disabled, --cache-pause and related are
6658 implicitly disabled.
6659 The auto choice enables this depending on whether the stream is
6661 thought to involve network accesses or other slow media (this is
6662 an imperfect heuristic).
6663 Before mpv 0.30.0, this used to accept a number, which specified
6665 the size of the cache in kilobytes. Use e.g. --cache --de‐
6666 muxer-max-bytes=123k instead.
6667 --no-cache
6669 Turn off input stream caching. See --cache.
6670 --cache-secs=<seconds>
6672 How many seconds of audio/video to prefetch if the cache is ac‐
6673 tive. This overrides the --demuxer-readahead-secs option if and
6674 only if the cache is enabled and the value is larger. The de‐
6675 fault value is set to something very high, so the actually
6676 achieved readahead will usually be limited by the value of the
6677 --demuxer-max-bytes option. Setting this option is usually only
6678 useful for limiting readahead.
6679 --cache-on-disk=<yes|no>
6681 Write packet data to a temporary file, instead of keeping them
6682 in memory. This makes sense only with --cache. If the normal
6683 cache is disabled, this option is ignored.
6684 The cache file is append-only. Even if the player appears to
6686 prune data, the file space freed by it is not reused. The cache
6687 file is deleted when playback is closed.
6688 Note that packet metadata is still kept in memory. --de‐
6690 muxer-max-bytes and related options are applied to metadata
6691 only. The size of this metadata varies, but 50 MB per hour of
6692 media is typical. The cache statistics will report this metadats
6693 size, instead of the size of the cache file. If the metadata
6694 hits the size limits, the metadata is pruned (but not the cache
6695 file).
6696 When the media is closed, the cache file is deleted. A cache
6698 file is generally worthless after the media is closed, and it's
6699 hard to retrieve any media data from it (it's not supported by
6700 design).
6701 If the option is enabled at runtime, the cache file is created,
6703 but old data will remain in the memory cache. If the option is
6704 disabled at runtime, old data remains in the disk cache, and the
6705 cache file is not closed until the media is closed. If the op‐
6706 tion is disabled and enabled again, it will continue to use the
6707 cache file that was opened first.
6708 --cache-dir=<path>
6710 Directory where to create temporary files. Cache is stored in
6711 the system's cache directory (usually ~/.cache/mpv) if this is
6712 unset.
6713 Currently, this is used for --cache-on-disk only.
6715 --cache-pause=<yes|no>
6717 Whether the player should automatically pause when the cache
6718 runs out of data and stalls decoding/playback (default: yes). If
6719 enabled, it will pause and unpause once more data is available,
6720 aka "buffering".
6721 --cache-pause-wait=<seconds>
6723 Number of seconds the packet cache should have buffered before
6724 starting playback again if "buffering" was entered (default: 1).
6725 This can be used to control how long the player rebuffers if
6726 --cache-pause is enabled, and the demuxer underruns. If the
6727 given time is higher than the maximum set with --cache-secs or
6728 --demuxer-readahead-secs, or prefetching ends before that for
6729 some other reason (like file end or maximum configured cache
6730 size reached), playback resumes earlier.
6731 --cache-pause-initial=<yes|no>
6733 Enter "buffering" mode before starting playback (default: no).
6734 This can be used to ensure playback starts smoothly, in exchange
6735 for waiting some time to prefetch network data (as controlled by
6736 --cache-pause-wait). For example, some common behavior is that
6737 playback starts, but network caches immediately underrun when
6738 trying to decode more data as playback progresses.
6739 Another thing that can happen is that the network prefetching is
6741 so CPU demanding (due to demuxing in the background) that play‐
6742 back drops frames at first. In these cases, it helps enabling
6743 this option, and setting --cache-secs and --cache-pause-wait to
6744 roughly the same value.
6745 This option also triggers when playback is restarted after seek‐
6747 ing.
6748 --cache-unlink-files=<immediate|whendone|no>
6750 Whether or when to unlink cache files (default: immediate). This
6751 affects cache files which are inherently temporary, and which
6752 make no sense to remain on disk after the player terminates.
6753 This is a debugging option.
6754 immediate
6756 Unlink cache file after they were created. The cache
6757 files won't be visible anymore, even though they're in
6758 use. This ensures they are guaranteed to be removed from
6759 disk when the player terminates, even if it crashes.
6760 whendone
6762 Delete cache files after they are closed.
6763 no Don't delete cache files. They will consume disk space
6765 without having a use.
6766 Currently, this is used for --cache-on-disk only.
6768 --stream-buffer-size=<bytesize>
6770 Size of the low level stream byte buffer (default: 128KB). This
6771 is used as buffer between demuxer and low level I/O (e.g. sock‐
6772 ets). Generally, this can be very small, and the main purpose is
6773 similar to the internal buffer FILE in the C standard library
6774 will have.
6775 Half of the buffer is always used for guaranteed seek back,
6777 which is important for unseekable input.
6778 There are known cases where this can help performance to set a
6780 large buffer:
6781 1. mp4 files. libavformat may trigger many small seeks in
6783 both directions, depending on how the file was muxed.
6784 2. Certain network filesystems, which do not have a cache,
6786 and where small reads can be inefficient.
6787 In other cases, setting this to a large value can reduce perfor‐
6789 mance.
6790 Usually, read accesses are at half the buffer size, but it may
6792 happen that accesses are done alternating with smaller and
6793 larger sizes (this is due to the internal ring buffer
6794 wrap-around).
6795 See --list-options for defaults and value range. <bytesize> op‐
6797 tions accept suffixes such as KiB and MiB.
6798 --vd-queue-enable=<yes|no>, --ad-queue-enable
6800 Enable running the video/audio decoder on a separate thread (de‐
6801 fault: no). If enabled, the decoder is run on a separate
6802 thread, and a frame queue is put between decoder and higher
6803 level playback logic. The size of the frame queue is defined by
6804 the other options below.
6805 This is probably quite pointless. libavcodec already has multi‐
6807 threaded decoding (enabled by default), which makes this largely
6808 unnecessary. It might help in some corner cases with high band‐
6809 width video that is slow to decode (in these cases libavcodec
6810 would block the playback logic, while using a decoding thread
6811 would distribute the decoding time evenly without affecting the
6812 playback logic). In other situations, it will simply make seek‐
6813 ing slower and use significantly more memory.
6814 The queue size is restricted by the other --vd-queue-... op‐
6816 tions. The final queue size is the minimum as indicated by the
6817 option with the lowest limit. Each decoder/track has its own
6818 queue that may use the full configured queue size.
6819 Most queue options can be changed at runtime. --vd-queue-enable
6821 itself (and the audio equivalent) update only if decoding is
6822 completely reinitialized. However, setting --vd-queue-max-sam‐
6823 ples=1 should almost lead to the same behavior as --vd-queue-en‐
6824 able=no, so that value can be used for effectively runtime en‐
6825 abling/disabling the queue.
6826 This should not be used with hardware decoding. It is possible
6828 to enable this for audio, but it makes even less sense.
6829 --vd-queue-max-bytes=<bytesize>, --ad-queue-max-bytes
6831 Maximum approximate allowed size of the queue. If exceeded, de‐
6832 coding will be stopped. The maximum size can be exceeded by
6833 about 1 frame.
6834 See --list-options for defaults and value range. <bytesize> op‐
6836 tions accept suffixes such as KiB and MiB.
6837 --vd-queue-max-samples=<int>, --ad-queue-max-samples
6839 Maximum number of frames (video) or samples (audio) of the
6840 queue. The audio size may be exceeded by about 1 frame.
6841 See --list-options for defaults and value range.
6843 --vd-queue-max-secs=<seconds>, --ad-queue-max-secs
6845 Maximum number of seconds of media in the queue. The special
6846 value 0 means no limit is set. The queue size may be exceeded by
6847 about 2 frames. Timestamp resets may lead to random queue size
6848 usage.
6849 See --list-options for defaults and value range.
6851 Network
6853 --user-agent=<string>
6854 Use <string> as user agent for HTTP streaming.
6855 --cookies, --no-cookies
6857 Support cookies when making HTTP requests. Disabled by default.
6858 --cookies-file=<filename>
6860 Read HTTP cookies from <filename>. The file is assumed to be in
6861 Netscape format.
6862 --http-header-fields=<field1,field2>
6864 Set custom HTTP fields when accessing HTTP stream.
6865 This is a string list option. See List Options for details.
6867 Example
6869 mpv --http-header-fields='Field1: value1','Field2: value2' \
6871 http://localhost:1234
6872 Will generate HTTP request:
6874 GET / HTTP/1.0
6876 Host: localhost:1234
6877 User-Agent: MPlayer
6878 Icy-MetaData: 1
6879 Field1: value1
6880 Field2: value2
6881 Connection: close
6882 --http-proxy=<proxy>
6884 URL of the HTTP/HTTPS proxy. If this is set, the http_proxy en‐
6885 vironment is ignored. The no_proxy environment variable is still
6886 respected. This option is silently ignored if it does not start
6887 with http://. Proxies are not used for https URLs. Setting this
6888 option does not try to make the ytdl script use the proxy.
6889 --tls-ca-file=<filename>
6891 Certificate authority database file for use with TLS. (Silently
6892 fails with older FFmpeg or Libav versions.)
6893 --tls-verify
6895 Verify peer certificates when using TLS (e.g. with https://...).
6896 (Silently fails with older FFmpeg or Libav versions.)
6897 --tls-cert-file
6899 A file containing a certificate to use in the handshake with the
6900 peer.
6901 --tls-key-file
6903 A file containing the private key for the certificate.
6904 --referrer=<string>
6906 Specify a referrer path or URL for HTTP requests.
6907 --network-timeout=<seconds>
6909 Specify the network timeout in seconds (default: 60 seconds).
6910 This affects at least HTTP. The special value 0 uses the FFm‐
6911 peg/Libav defaults. If a protocol is used which does not support
6912 timeouts, this option is silently ignored.
6913 WARNING:
6915 This breaks the RTSP protocol, because of inconsistent FFmpeg
6916 API regarding its internal timeout option. Not only does the
6917 RTSP timeout option accept different units (seconds instead
6918 of microseconds, causing mpv to pass it huge values), it will
6919 also overflow FFmpeg internal calculations. The worst is that
6920 merely setting the option will put RTSP into listening mode,
6921 which breaks any client uses. At time of this writing, the
6922 fix was not made effective yet. For this reason, this option
6923 is ignored (or should be ignored) on RTSP URLs. You can still
6924 set the timeout option directly with --demuxer-lavf-o.
6925 --rtsp-transport=<lavf|udp|udp_multicast|tcp|http>
6927 Select RTSP transport method (default: tcp). This selects the
6928 underlying network transport when playing rtsp://... URLs. The
6929 value lavf leaves the decision to libavformat.
6930 --hls-bitrate=<no|min|max|<rate>>
6932 If HLS streams are played, this option controls what streams are
6933 selected by default. The option allows the following parameters:
6934 no Don't do anything special. Typically, this will simply
6936 pick the first audio/video streams it can find.
6937 min Pick the streams with the lowest bitrate.
6939 max Same, but highest bitrate. (Default.)
6941 Additionally, if the option is a number, the stream with the
6943 highest rate equal or below the option value is selected.
6944 The bitrate as used is sent by the server, and there's no guar‐
6946 antee it's actually meaningful.
6947 DVB
6949 --dvbin-prog=<string>
6950 This defines the program to tune to. Usually, you may specify
6951 this by using a stream URI like "dvb://ZDF HD", but you can tune
6952 to a different channel by writing to this property at runtime.
6953 Also see dvbin-channel-switch-offset for more useful channel
6954 switching functionality.
6955 --dvbin-card=<0-15>
6957 Specifies using card number 0-15 (default: 0).
6958 --dvbin-file=<filename>
6960 Instructs mpv to read the channels list from <filename>. The de‐
6961 fault is in the mpv configuration directory (usually ~/.con‐
6962 fig/mpv) with the filename channels.conf.{sat,ter,cbl,atsc}
6963 (based on your card type) or channels.conf as a last resort.
6964 For DVB-S/2 cards, a VDR 1.7.x format channel list is recom‐
6965 mended as it allows tuning to DVB-S2 channels, enabling subti‐
6966 tles and decoding the PMT (which largely improves the demuxing).
6967 Classic mplayer format channel lists are still supported (with‐
6968 out these improvements), and for other card types, only limited
6969 VDR format channel list support is implemented (patches wel‐
6970 come). For channels with dynamic PID switching or incomplete
6971 channels.conf, --dvbin-full-transponder or the magic PID 8192
6972 are recommended.
6973 --dvbin-timeout=<1-30>
6975 Maximum number of seconds to wait when trying to tune a fre‐
6976 quency before giving up (default: 30).
6977 --dvbin-full-transponder=<yes|no>
6979 Apply no filters on program PIDs, only tune to frequency and
6980 pass full transponder to demuxer. The player frontend selects
6981 the streams from the full TS in this case, so the program which
6982 is shown initially may not match the chosen channel. Switching
6983 between the programs is possible by cycling the program prop‐
6984 erty. This is useful to record multiple programs on a single
6985 transponder, or to work around issues in the channels.conf. It
6986 is also recommended to use this for channels which switch PIDs
6987 on-the-fly, e.g. for regional news.
6988 Default: no
6990 --dvbin-channel-switch-offset=<integer>
6992 This value is not meant for setting via configuration, but used
6993 in channel switching. An input.conf can cycle this value up and
6994 down to perform channel switching. This number effectively gives
6995 the offset to the initially tuned to channel in the channel
6996 list.
6997 An example input.conf could contain: H cycle dvbin-chan‐
6999 nel-switch-offset up, K cycle dvbin-channel-switch-offset down
7000 ALSA audio output options
7002 --alsa-device=<device>
7003 Deprecated, use --audio-device (requires alsa/ prefix).
7004 --alsa-resample=yes
7006 Enable ALSA resampling plugin. (This is disabled by default, be‐
7007 cause some drivers report incorrect audio delay in some cases.)
7008 --alsa-mixer-device=<device>
7010 Set the mixer device used with ao-volume (default: default).
7011 --alsa-mixer-name=<name>
7013 Set the name of the mixer element (default: Master). This is for
7014 example PCM or Master.
7015 --alsa-mixer-index=<number>
7017 Set the index of the mixer channel (default: 0). Consider the
7018 output of "amixer scontrols", then the index is the number that
7019 follows the name of the element.
7020 --alsa-non-interleaved
7022 Allow output of non-interleaved formats (if the audio decoder
7023 uses this format). Currently disabled by default, because some
7024 popular ALSA plugins are utterly broken with non-interleaved
7025 formats.
7026 --alsa-ignore-chmap
7028 Don't read or set the channel map of the ALSA device - only re‐
7029 quest the required number of channels, and then pass the audio
7030 as-is to it. This option most likely should not be used. It can
7031 be useful for debugging, or for static setups with a specially
7032 engineered ALSA configuration (in this case you should always
7033 force the same layout with --audio-channels, or it will work
7034 only for files which use the layout implicit to your ALSA de‐
7035 vice).
7036 --alsa-buffer-time=<microseconds>
7038 Set the requested buffer time in microseconds. A value of 0
7039 skips requesting anything from the ALSA API. This and the
7040 --alsa-periods option uses the ALSA near functions to set the
7041 requested parameters. If doing so results in an empty configura‐
7042 tion set, setting these parameters is skipped.
7043 Both options control the buffer size. A low buffer size can lead
7045 to higher CPU usage and audio dropouts, while a high buffer size
7046 can lead to higher latency in volume changes and other filter‐
7047 ing.
7048 --alsa-periods=<number>
7050 Number of periods requested from the ALSA API. See --alsa-buf‐
7051 fer-time for further remarks.
7052 GPU renderer options
7054 The following video options are currently all specific to --vo=gpu,
7055 --vo=libmpv and --vo=gpu-next, which are the only VOs that implement
7056 them.
7057 --scale=<filter>
7059 The filter function to use when upscaling video.
7060 bilinear
7062 Bilinear hardware texture filtering (fastest, very low
7063 quality). This is the default for compatibility reasons.
7064 spline36
7066 Mid quality and speed. This is the default when using
7067 gpu-hq.
7068 lanczos
7070 Lanczos scaling. Provides mid quality and speed. Gener‐
7071 ally worse than spline36, but it results in a slightly
7072 sharper image which is good for some content types. The
7073 number of taps can be controlled with scale-radius, but
7074 is best left unchanged.
7075 (This filter is an alias for sinc-windowed sinc)
7077 ewa_lanczos
7079 Elliptic weighted average Lanczos scaling. Also known as
7080 Jinc. Relatively slow, but very good quality. The radius
7081 can be controlled with scale-radius. Increasing the ra‐
7082 dius makes the filter sharper but adds more ringing.
7083 (This filter is an alias for jinc-windowed jinc)
7085 ewa_lanczossharp
7087 A slightly sharpened version of ewa_lanczos, preconfig‐
7088 ured to use an ideal radius and parameter. If your hard‐
7089 ware can run it, this is probably what you should use by
7090 default.
7091 mitchell
7093 Mitchell-Netravali. The B and C parameters can be set
7094 with --scale-param1 and --scale-param2. This filter is
7095 very good at downscaling (see --dscale).
7096 oversample
7098 A version of nearest neighbour that (naively) oversamples
7099 pixels, so that pixels overlapping edges get linearly in‐
7100 terpolated instead of rounded. This essentially removes
7101 the small imperfections and judder artifacts caused by
7102 nearest-neighbour interpolation, in exchange for adding
7103 some blur. This filter is good at temporal interpolation,
7104 and also known as "smoothmotion" (see --tscale).
7105 linear A --tscale filter.
7107 There are some more filters, but most are not as useful. For a
7109 complete list, pass help as value, e.g.:
7110 mpv --scale=help
7112 --cscale=<filter>
7114 As --scale, but for interpolating chroma information. If the im‐
7115 age is not subsampled, this option is ignored entirely.
7116 --dscale=<filter>
7118 Like --scale, but apply these filters on downscaling instead. If
7119 this option is unset, the filter implied by --scale will be ap‐
7120 plied.
7121 --tscale=<filter>
7123 The filter used for interpolating the temporal axis (frames).
7124 This is only used if --interpolation is enabled. The only valid
7125 choices for --tscale are separable convolution filters (use
7126 --tscale=help to get a list). The default is mitchell.
7127 Common --tscale choices include oversample, linear, catmull_rom,
7129 mitchell, gaussian, or bicubic. These are listed in increasing
7130 order of smoothness/blurriness, with bicubic being the
7131 smoothest/blurriest and oversample being the sharpest/least
7132 smooth.
7133 --scale-param1=<value>, --scale-param2=<value>,
7135 --cscale-param1=<value>, --cscale-param2=<value>,
7136 --dscale-param1=<value>, --dscale-param2=<value>,
7137 --tscale-param1=<value>, --tscale-param2=<value>
7138 Set filter parameters. By default, these are set to the special
7139 string default, which maps to a scaler-specific default value.
7140 Ignored if the filter is not tunable. Currently, this affects
7141 the following filter parameters:
7142 bcspline
7144 Spline parameters (B and C). Defaults to 0.5 for both.
7145 gaussian
7147 Scale parameter (t). Increasing this makes the result
7148 blurrier. Defaults to 1.
7149 oversample
7151 Minimum distance to an edge before interpolation is used.
7152 Setting this to 0 will always interpolate edges, whereas
7153 setting it to 0.5 will never interpolate, thus behaving
7154 as if the regular nearest neighbour algorithm was used.
7155 Defaults to 0.0.
7156 --scale-blur=<value>, --scale-wblur=<value>, --cscale-blur=<value>,
7158 --cscale-wblur=<value>, --dscale-blur=<value>, --dscale-wblur=<value>,
7159 --tscale-blur=<value>, --tscale-wblur=<value>
7160 Kernel/window scaling factor (also known as a blur factor). De‐
7161 creasing this makes the result sharper, increasing it makes it
7162 blurrier (default 0). If set to 0, the kernel's preferred blur
7163 factor is used. Note that setting this too low (eg. 0.5) leads
7164 to bad results. It's generally recommended to stick to values
7165 between 0.8 and 1.2.
7166 --scale-clamp=<0.0-1.0>, --cscale-clamp, --dscale-clamp, --tscale-clamp
7168 Specifies a weight bias to multiply into negative coefficients.
7169 Specifying --scale-clamp=1 has the effect of removing negative
7170 weights completely, thus effectively clamping the value range to
7171 [0-1]. Values between 0.0 and 1.0 can be specified to apply only
7172 a moderate diminishment of negative weights. This is especially
7173 useful for --tscale, where it reduces excessive ringing arti‐
7174 facts in the temporal domain (which typically manifest them‐
7175 selves as short flashes or fringes of black, mostly around mov‐
7176 ing edges) in exchange for potentially adding more blur. The de‐
7177 fault for --tscale-clamp is 1.0, the others default to 0.0.
7178 --scale-cutoff=<value>, --cscale-cutoff=<value>, --dscale-cut‐
7180 off=<value>
7181 Cut off the filter kernel prematurely once the value range drops
7182 below this threshold. Doing so allows more aggressive pruning of
7183 skippable coefficients by disregarding parts of the LUT which
7184 are effectively zeroed out by the window function. Only affects
7185 polar (EWA) filters. The default is 0.001 for each, which is
7186 perceptually transparent but provides a 10%-20% speedup, depend‐
7187 ing on the exact radius and filter kernel chosen.
7188 --scale-taper=<value>, --scale-wtaper=<value>, --dscale-taper=<value>,
7190 --dscale-wtaper=<value>, --cscale-taper=<value>, --cscale-wta‐
7191 per=<value>, --tscale-taper=<value>, --tscale-wtaper=<value>
7192 Kernel/window taper factor. Increasing this flattens the filter
7193 function. Value range is 0 to 1. A value of 0 (the default)
7194 means no flattening, a value of 1 makes the filter completely
7195 flat (equivalent to a box function). Values in between mean
7196 that some portion will be flat and the actual filter function
7197 will be squeezed into the space in between.
7198 --scale-radius=<value>, --cscale-radius=<value>, --dscale-ra‐
7200 dius=<value>, --tscale-radius=<value>
7201 Set radius for tunable filters, must be a float number between
7202 0.5 and 16.0. Defaults to the filter's preferred radius if not
7203 specified. Doesn't work for every scaler and VO combination.
7204 Note that depending on filter implementation details and video
7206 scaling ratio, the radius that actually being used might be dif‐
7207 ferent (most likely being increased a bit).
7208 --scale-antiring=<value>, --cscale-antiring=<value>, --dscale-antir‐
7210 ing=<value>, --tscale-antiring=<value>
7211 Set the antiringing strength. This tries to eliminate ringing,
7212 but can introduce other artifacts in the process. Must be a
7213 float number between 0.0 and 1.0. The default value of 0.0 dis‐
7214 ables antiringing entirely.
7215 Note that this doesn't affect the special filters bilinear and
7217 bicubic_fast, nor does it affect any polar (EWA) scalers.
7218 --scale-window=<window>, --cscale-window=<window>, --dscale-win‐
7220 dow=<window>, --tscale-window=<window>
7221 (Advanced users only) Choose a custom windowing function for the
7222 kernel. Defaults to the filter's preferred window if unset. Use
7223 --scale-window=help to get a list of supported windowing func‐
7224 tions.
7225 --scale-wparam=<window>, --cscale-wparam=<window>,
7227 --cscale-wparam=<window>, --tscale-wparam=<window>
7228 (Advanced users only) Configure the parameter for the window
7229 function given by --scale-window etc. By default, these are set
7230 to the special string default, which maps to a window-specific
7231 default value. Ignored if the window is not tunable. Currently,
7232 this affects the following window parameters:
7233 kaiser Window parameter (alpha). Defaults to 6.33.
7235 blackman
7237 Window parameter (alpha). Defaults to 0.16.
7238 gaussian
7240 Scale parameter (t). Increasing this makes the window
7241 wider. Defaults to 1.
7242 --scaler-lut-size=<4..10>
7244 Set the size of the lookup texture for scaler kernels (default:
7245 6). The actual size of the texture is 2^N for an option value of
7246 N. So the lookup texture with the default setting uses 64 sam‐
7247 ples.
7248 All weights are linearly interpolated from those samples, so in‐
7250 creasing the size of lookup table might improve the accuracy of
7251 scaler.
7252 --scaler-resizes-only
7254 Disable the scaler if the video image is not resized. In that
7255 case, bilinear is used instead of whatever is set with --scale.
7256 Bilinear will reproduce the source image perfectly if no scaling
7257 is performed. Enabled by default. Note that this option never
7258 affects --cscale.
7259 --correct-downscaling
7261 When using convolution based filters, extend the filter size
7262 when downscaling. Increases quality, but reduces performance
7263 while downscaling.
7264 This will perform slightly sub-optimally for anamorphic video
7266 (but still better than without it) since it will extend the size
7267 to match only the milder of the scale factors between the axes.
7268 Note: this option is ignored when using bilinear downscaling
7270 (the default).
7271 --linear-downscaling
7273 Scale in linear light when downscaling. It should only be used
7274 with a --fbo-format that has at least 16 bit precision. This op‐
7275 tion has no effect on HDR content.
7276 --linear-upscaling
7278 Scale in linear light when upscaling. Like --linear-downscaling,
7279 it should only be used with a --fbo-format that has at least 16
7280 bits precisions. This is not usually recommended except for
7281 testing/specific purposes. Users are advised to either enable
7282 --sigmoid-upscaling or keep both options disabled (i.e. scaling
7283 in gamma light).
7284 --sigmoid-upscaling
7286 When upscaling, use a sigmoidal color transform to avoid empha‐
7287 sizing ringing artifacts. This is incompatible with and replaces
7288 --linear-upscaling. (Note that sigmoidization also requires lin‐
7289 earization, so the LINEAR rendering step fires in both cases)
7290 --sigmoid-center
7292 The center of the sigmoid curve used for --sigmoid-upscaling,
7293 must be a float between 0.0 and 1.0. Defaults to 0.75 if not
7294 specified.
7295 --sigmoid-slope
7297 The slope of the sigmoid curve used for --sigmoid-upscaling,
7298 must be a float between 1.0 and 20.0. Defaults to 6.5 if not
7299 specified.
7300 --interpolation
7302 Reduce stuttering caused by mismatches in the video fps and dis‐
7303 play refresh rate (also known as judder).
7304 WARNING:
7306 This requires setting the --video-sync option to one of the
7307 display- modes, or it will be silently disabled. This was
7308 not required before mpv 0.14.0.
7309 This essentially attempts to interpolate the missing frames by
7311 convoluting the video along the temporal axis. The filter used
7312 can be controlled using the --tscale setting.
7313 --interpolation-threshold=<0..1,-1>
7315 Threshold below which frame ratio interpolation gets disabled
7316 (default: 0.01). This is calculated as abs(disphz/vfps - 1) <
7317 threshold, where vfps is the speed-adjusted video FPS, and dis‐
7318 phz the display refresh rate. (The speed-adjusted video FPS is
7319 roughly equal to the normal video FPS, but with slowdown and
7320 speedup applied. This matters if you use --video-sync=dis‐
7321 play-resample to make video run synchronously to the display
7322 FPS, or if you change the speed property.)
7323 The default is intended to enable interpolation in scenarios
7325 where retiming with the --video-sync=display-* cannot adjust the
7326 speed of the video sufficiently for smooth playback. For example
7327 if a video is 60.00 FPS and your display refresh rate is 59.94
7328 Hz, interpolation will never be activated, since the mismatch is
7329 within 1% of the refresh rate. The default also handles the sce‐
7330 nario when mpv cannot determine the container FPS, such as dur‐
7331 ing certain live streams, and may dynamically toggle interpola‐
7332 tion on and off. In this scenario, the default would be to not
7333 use interpolation but rather to allow --video-sync=display-* to
7334 retime the video to match display refresh rate. See
7335 --video-sync-max-video-change for more information about how mpv
7336 will retime video.
7337 Also note that if you use e.g. --video-sync=display-vdrop, small
7339 deviations in the rate can disable interpolation and introduce a
7340 discontinuity every other minute.
7341 Set this to -1 to disable this logic.
7343 --interpolation-preserve
7345 Preserve the previous frames' interpolated results even when
7346 renderer parameters are changed - with the exception of options
7347 related to cropping and video placement, which always invalidate
7348 the cache. Enabling this option makes dynamic updates of ren‐
7349 derer settings slightly smoother at the cost of slightly higher
7350 latency in response to such changes. Defaults to on. (Only af‐
7351 fects --vo=gpu-next, note that --vo=gpu always invalidates in‐
7352 terpolated frames)
7353 --opengl-pbo
7355 Enable use of PBOs. On some drivers this can be faster, espe‐
7356 cially if the source video size is huge (e.g. so called "4K"
7357 video). On other drivers it might be slower or cause latency is‐
7358 sues.
7359 --dither-depth=<N|no|auto>
7361 Set dither target depth to N. Default: no.
7362 no Disable any dithering done by mpv.
7364 auto Automatic selection. If output bit depth cannot be de‐
7366 tected, 8 bits per component are assumed.
7367 8 Dither to 8 bit output.
7369 Note that the depth of the connected video display device cannot
7371 be detected. Often, LCD panels will do dithering on their own,
7372 which conflicts with this option and leads to ugly output.
7373 --dither-size-fruit=<2-8>
7375 Set the size of the dither matrix (default: 6). The actual size
7376 of the matrix is (2^N) x (2^N) for an option value of N, so a
7377 value of 6 gives a size of 64x64. The matrix is generated at
7378 startup time, and a large matrix can take rather long to compute
7379 (seconds).
7380 Used in --dither=fruit mode only.
7382 --dither=<fruit|ordered|error-diffusion|no>
7384 Select dithering algorithm (default: fruit). (Normally, the
7385 --dither-depth option controls whether dithering is enabled.)
7386 The error-diffusion option requires compute shader support. It
7388 also requires large amount of shared memory to run, the size of
7389 which depends on both the kernel (see --error-diffusion option
7390 below) and the height of video window. It will fallback to fruit
7391 dithering if there is no enough shared memory to run the shader.
7392 --temporal-dither
7394 Enable temporal dithering. (Only active if dithering is enabled
7395 in general.) This changes between 8 different dithering patterns
7396 on each frame by changing the orientation of the tiled dithering
7397 matrix. Unfortunately, this can lead to flicker on LCD displays,
7398 since these have a high reaction time.
7399 --temporal-dither-period=<1-128>
7401 Determines how often the dithering pattern is updated when
7402 --temporal-dither is in use. 1 (the default) will update on ev‐
7403 ery video frame, 2 on every other frame, etc.
7404 --error-diffusion=<kernel>
7406 The error diffusion kernel to use when --dither=error-diffusion
7407 is set.
7408 simple Propagate error to only two adjacent pixels. Fastest but
7410 low quality.
7411 sierra-lite
7413 Fast with reasonable quality. This is the default.
7414 floyd-steinberg
7416 Most notable error diffusion kernel.
7417 atkinson
7419 Looks different from other kernels because only fraction
7420 of errors will be propagated during dithering. A typical
7421 use case of this kernel is saving dithered screenshot (in
7422 window mode). This kernel produces slightly smaller file,
7423 with still reasonable dithering quality.
7424 There are other kernels (use --error-diffusion=help to list) but
7426 most of them are much slower and demanding even larger amount of
7427 shared memory. Among these kernels, burkes achieves a good bal‐
7428 ance between performance and quality, and probably is the one
7429 you want to try first.
7430 --gpu-debug
7432 Enables GPU debugging. What this means depends on the API type.
7433 For OpenGL, it calls glGetError(), and requests a debug context.
7434 For Vulkan, it enables validation layers.
7435 --opengl-swapinterval=<n>
7437 Interval in displayed frames between two buffer swaps. 1 is
7438 equivalent to enable VSYNC, 0 to disable VSYNC. Defaults to 1 if
7439 not specified.
7440 Note that this depends on proper OpenGL vsync support. On some
7442 platforms and drivers, this only works reliably when in
7443 fullscreen mode. It may also require driver-specific hacks if
7444 using multiple monitors, to ensure mpv syncs to the right one.
7445 Compositing window managers can also lead to bad results, as can
7446 missing or incorrect display FPS information (see --over‐
7447 ride-display-fps).
7448 --vulkan-device=<device name>
7450 The name of the Vulkan device to use for rendering and presenta‐
7451 tion. Use --vulkan-device=help to see the list of available de‐
7452 vices and their names. If left unspecified, the first enumerated
7453 hardware Vulkan device will be used.
7454 --vulkan-swap-mode=<mode>
7456 Controls the presentation mode of the vulkan swapchain. This is
7457 similar to the --opengl-swapinterval option.
7458 auto Use the preferred swapchain mode for the vulkan context.
7460 (Default)
7461 fifo Non-tearing, vsync blocked. Similar to "VSync on".
7463 fifo-relaxed
7465 Tearing, vsync blocked. Late frames will tear instead of
7466 stuttering.
7467 mailbox
7469 Non-tearing, not vsync blocked. Similar to "triple
7470 buffering".
7471 immediate
7473 Tearing, not vsync blocked. Similar to "VSync off".
7474 --vulkan-queue-count=<1..8>
7476 Controls the number of VkQueues used for rendering (limited by
7477 how many your device supports). In theory, using more queues
7478 could enable some parallelism between frames (when using a
7479 --swapchain-depth higher than 1), but it can also slow things
7480 down on hardware where there's no true parallelism between
7481 queues. (Default: 1)
7482 --vulkan-async-transfer
7484 Enables the use of async transfer queues on supported vulkan de‐
7485 vices. Using them allows transfer operations like texture up‐
7486 loads and blits to happen concurrently with the actual render‐
7487 ing, thus improving overall throughput and power consumption.
7488 Enabled by default, and should be relatively safe.
7489 --vulkan-async-compute
7491 Enables the use of async compute queues on supported vulkan de‐
7492 vices. Using this, in theory, allows out-of-order scheduling of
7493 compute shaders with graphics shaders, thus enabling the hard‐
7494 ware to do more effective work while waiting for pipeline bub‐
7495 bles and memory operations. Not beneficial on all GPUs. It's
7496 worth noting that if async compute is enabled, and the device
7497 supports more compute queues than graphics queues (bound by the
7498 restrictions set by --vulkan-queue-count), mpv will internally
7499 try and prefer the use of compute shaders over fragment shaders
7500 wherever possible. Enabled by default, although Nvidia users may
7501 want to disable it.
7502 --vulkan-display-display=<n>
7504 The index of the display, on the selected Vulkan device, to
7505 present on when using the displayvk GPU context. Use
7506 --vulkan-display-display=help to see the list of available dis‐
7507 plays. If left unspecified, the first enumerated display will be
7508 used.
7509 --vulkan-display-mode=<n>
7511 The index of the display mode, of the selected Vulkan display,
7512 to use when using the displayvk GPU context. Use --vulkan-dis‐
7513 play-mode=help to see the list of available modes. If left un‐
7514 specified, the first enumerated mode will be used.
7515 --vulkan-display-plane=<n>
7517 The index of the plane, on the selected Vulkan device, to
7518 present on when using the displayvk GPU context. Use
7519 --vulkan-display-plane=help to see the list of available planes.
7520 If left unspecified, the first enumerated plane will be used.
7521 --d3d11-exclusive-fs=<yes|no>
7523 Switches the D3D11 swap chain fullscreen state to 'fullscreen'
7524 when fullscreen video is requested. Also known as "exclusive
7525 fullscreen" or "D3D fullscreen" in other applications. Gives mpv
7526 full control of rendering on the swap chain's screen. Off by de‐
7527 fault.
7528 --d3d11-warp=<yes|no|auto>
7530 Use WARP (Windows Advanced Rasterization Platform) with the
7531 D3D11 GPU backend (default: auto). This is a high performance
7532 software renderer. By default, it is only used when the system
7533 has no hardware adapters that support D3D11. While the extended
7534 GPU features will work with WARP, they can be very slow.
7535 --d3d11-feature-level=<12_1|12_0|11_1|11_0|10_1|10_0|9_3|9_2|9_1>
7537 Select a specific feature level when using the D3D11 GPU back‐
7538 end. By default, the highest available feature level is used.
7539 This option can be used to select a lower feature level, which
7540 is mainly useful for debugging. Most extended GPU features will
7541 not work at 9_x feature levels.
7542 --d3d11-flip=<yes|no>
7544 Enable flip-model presentation, which avoids unnecessarily copy‐
7545 ing the backbuffer by sharing surfaces with the DWM (default:
7546 yes). This may cause performance issues with older drivers. If
7547 flip-model presentation is not supported (for example, on Win‐
7548 dows 7 without the platform update), mpv will automatically fall
7549 back to the older bitblt presentation model.
7550 --d3d11-sync-interval=<0..4>
7552 Schedule each frame to be presented for this number of VBlank
7553 intervals. (default: 1) Setting to 1 will enable VSync, setting
7554 to 0 will disable it.
7555 --d3d11-adapter=<adapter name|help>
7557 Select a specific D3D11 adapter to utilize for D3D11 rendering.
7558 Will pick the default adapter if unset. Alternatives are listed
7559 when the name "help" is given.
7560 Checks for matches based on the start of the string, case insen‐
7562 sitive. Thus, if the description of the adapter starts with the
7563 vendor name, that can be utilized as the selection parameter.
7564 Hardware decoders utilizing the D3D11 rendering abstraction's
7566 helper functionality to receive a device, such as D3D11VA or
7567 DXVA2's DXGI mode, will be affected by this choice.
7568 --d3d11-output-format=<auto|rgba8|bgra8|rgb10_a2|rgba16f>
7570 Select a specific D3D11 output format to utilize for D3D11 ren‐
7571 dering. "auto" is the default, which will pick either rgba8 or
7572 rgb10_a2 depending on the configured desktop bit depth. rgba16f
7573 and bgra8 are left out of the autodetection logic, and are
7574 available for manual testing.
7575 NOTE:
7577 Desktop bit depth querying is only available from an API
7578 available from Windows 10. Thus on older systems it will only
7579 automatically utilize the rgba8 output format.
7580 --d3d11-output-csp=<auto|srgb|linear|pq|bt.2020>
7582 Select a specific D3D11 output color space to utilize for D3D11
7583 rendering. "auto" is the default, which will select the color
7584 space of the desktop on which the swap chain is located.
7585 Values other than "srgb" and "pq" have had issues in testing, so
7587 they are mostly available for manual testing.
7588 NOTE:
7590 Swap chain color space configuration is only available from
7591 an API available from Windows 10. Thus on older systems it
7592 will not work.
7593 --d3d11va-zero-copy=<yes|no>
7595 By default, when using hardware decoding with --gpu-api=d3d11,
7596 the video image will be copied (GPU-to-GPU) from the decoder
7597 surface to a shader resource. Set this option to avoid that copy
7598 by sampling directly from the decoder image. This may increase
7599 performance and reduce power usage, but can cause the image to
7600 be sampled incorrectly on the bottom and right edges due to pad‐
7601 ding, and may invoke driver bugs, since Direct3D 11 technically
7602 does not allow sampling from a decoder surface (though most
7603 drivers support it.)
7604 Currently only relevant for --gpu-api=d3d11.
7606 --wayland-app-id=<string>
7608 Set the client app id for Wayland-based video output methods
7609 (default: mpv).
7610 --wayland-configure-bounds=<auto|yes|no>
7612 Controls whether or not mpv opts into the configure bounds event
7613 if sent by the compositor (default: auto). This restricts the
7614 initial size of the mpv window to a certain maximum size in‐
7615 tended by the compositor. In most cases, this simply just pre‐
7616 vents the mpv window from being larger than the size of the mon‐
7617 itor when it first renders. With the default value of auto, con‐
7618 figure-bounds will silently be ignored if any autofit or geome‐
7619 try type option is also set.
7620 --wayland-content-type=<auto|none|photo|video|game>
7622 If supported by the compositor, mpv will send a hint using the
7623 content-type protocol telling the compositor what type of con‐
7624 tent is being displayed. auto (default) will automatically
7625 switch between telling the compositor the content is a photo,
7626 video or possibly none depending on internal heuristics.
7627 --wayland-disable-vsync=<yes|no>
7629 Disable mpv's internal vsync for Wayland-based video output (de‐
7630 fault: no). This is mainly useful for benchmarking wayland VOs
7631 when combined with video-sync=display-desync, --no-audio, and
7632 --untimed=yes.
7633 --wayland-edge-pixels-pointer=<value>
7635 Defines the size of an edge border (default: 16) to initiate
7636 client side resize events in the wayland contexts with the
7637 mouse. This is only active if there are no server side decora‐
7638 tions from the compositor.
7639 --wayland-edge-pixels-touch=<value>
7641 Defines the size of an edge border (default: 32) to initiate
7642 client side resizes events in the wayland contexts with touch
7643 events.
7644 --spirv-compiler=<compiler>
7646 Controls which compiler is used to translate GLSL to SPIR-V.
7647 This is (currently) only relevant for --gpu-api=vulkan and
7648 --gpu-api=d3d11. The possible choices are currently only:
7649 auto Use the first available compiler. (Default)
7651 shaderc
7653 Use libshaderc, which is an API wrapper around glslang.
7654 This is generally the most preferred, if available.
7655 NOTE:
7657 This option is deprecated, since there is only one reasonable
7658 value. It may be removed in the future.
7659 --glsl-shader=<file>, --glsl-shaders=<file-list>
7661 Custom GLSL hooks. These are a flexible way to add custom frag‐
7662 ment shaders, which can be injected at almost arbitrary points
7663 in the rendering pipeline, and access all previous intermediate
7664 textures.
7665 Each use of the --glsl-shader option will add another file to
7667 the internal list of shaders, while --glsl-shaders takes a list
7668 of files, and overwrites the internal list with it. The latter
7669 is a path list option (see List Options for details).
7670 Warning
7672 The syntax is not stable yet and may change any time.
7674 The general syntax of a user shader looks like this:
7676 //!METADATA ARGS...
7678 //!METADATA ARGS...
7679 vec4 hook() {
7681 ...
7682 return something;
7683 }
7684 //!METADATA ARGS...
7686 //!METADATA ARGS...
7687 ...
7689 Each section of metadata, along with the non-metadata lines af‐
7691 ter it, defines a single block. There are currently two types of
7692 blocks, HOOKs and TEXTUREs.
7693 A TEXTURE block can set the following options:
7695 TEXTURE <name> (required)
7697 The name of this texture. Hooks can then bind the texture
7698 under this name using BIND. This must be the first option
7699 of the texture block.
7700 SIZE <width> [<height>] [<depth>] (required)
7702 The dimensions of the texture. The height and depth are
7703 optional. The type of texture (1D, 2D or 3D) depends on
7704 the number of components specified.
7705 FORMAT <name> (required)
7707 The texture format for the samples. Supported texture
7708 formats are listed in debug logging when the gpu VO is
7709 initialized (look for Texture formats:). Usually, this
7710 follows OpenGL naming conventions. For example, rgb16
7711 provides 3 channels with normalized 16 bit components.
7712 One oddity are float formats: for example, rgba16f has 16
7713 bit internal precision, but the texture data is provided
7714 as 32 bit floats, and the driver converts the data on
7715 texture upload.
7716 Although format names follow a common naming convention,
7718 not all of them are available on all hardware, drivers,
7719 GL versions, and so on.
7720 FILTER <LINEAR|NEAREST>
7722 The min/magnification filter used when sampling from this
7723 texture.
7724 BORDER <CLAMP|REPEAT|MIRROR>
7726 The border wrapping mode used when sampling from this
7727 texture.
7728 Following the metadata is a string of bytes in hexadecimal nota‐
7730 tion that define the raw texture data, corresponding to the for‐
7731 mat specified by FORMAT, on a single line with no extra white‐
7732 space.
7733 A HOOK block can set the following options:
7735 HOOK <name> (required)
7737 The texture which to hook into. May occur multiple times
7738 within a metadata block, up to a predetermined limit. See
7739 below for a list of hookable textures.
7740 DESC <title>
7742 User-friendly description of the pass. This is the name
7743 used when representing this shader in the list of passes
7744 for property vo-passes.
7745 BIND <name>
7747 Loads a texture (either coming from mpv or from a TEXTURE
7748 block) and makes it available to the pass. When binding
7749 textures from mpv, this will also set up macros to facil‐
7750 itate accessing it properly. See below for a list. By de‐
7751 fault, no textures are bound. The special name HOOKED can
7752 be used to refer to the texture that triggered this pass.
7753 SAVE <name>
7755 Gives the name of the texture to save the result of this
7756 pass into. By default, this is set to the special name
7757 HOOKED which has the effect of overwriting the hooked
7758 texture.
7759 WIDTH <szexpr>, HEIGHT <szexpr>
7761 Specifies the size of the resulting texture for this
7762 pass. szexpr refers to an expression in RPN (reverse pol‐
7763 ish notation), using the operators + - * / > < !, float‐
7764 ing point literals, and references to sizes of existing
7765 texture (such as MAIN.width or CHROMA.height), OUTPUT, or
7766 NATIVE_CROPPED (size of an input texture cropped after
7767 pan-and-scan, video-align-x/y, video-pan-x/y, etc. and
7768 possibly prescaled). By default, these are set to
7769 HOOKED.w and HOOKED.h, espectively.
7770 WHEN <szexpr>
7772 Specifies a condition that needs to be true (non-zero)
7773 for the shader stage to be evaluated. If it fails, it
7774 will silently be omitted. (Note that a shader stage like
7775 this which has a dependency on an optional hook point can
7776 still cause that hook point to be saved, which has some
7777 minor overhead)
7778 OFFSET <ox oy | ALIGN>
7780 Indicates a pixel shift (offset) introduced by this pass.
7781 These pixel offsets will be accumulated and corrected
7782 during the next scaling pass (cscale or scale). The de‐
7783 fault values are 0 0 which correspond to no shift. Note
7784 that offsets are ignored when not overwriting the hooked
7785 texture.
7786 A special value of ALIGN will attempt to fix existing
7788 offset of HOOKED by align it with reference. It requires
7789 HOOKED to be resizable (see below). It works transpar‐
7790 ently with fragment shader. For compute shader, the pre‐
7791 defined texmap macro is required to handle coordinate
7792 mapping.
7793 COMPONENTS <n>
7795 Specifies how many components of this pass's output are
7796 relevant and should be stored in the texture, up to 4
7797 (rgba). By default, this value is equal to the number of
7798 components in HOOKED.
7799 COMPUTE <bw> <bh> [<tw> <th>]
7801 Specifies that this shader should be treated as a compute
7802 shader, with the block size bw and bh. The compute shader
7803 will be dispatched with however many blocks are necessary
7804 to completely tile over the output. Within each block,
7805 there will be tw*th threads, forming a single work group.
7806 In other words: tw and th specify the work group size,
7807 which can be different from the block size. So for exam‐
7808 ple, a compute shader with bw, bh = 32 and tw, th = 8
7809 running on a 500x500 texture would dispatch 16x16 blocks
7810 (rounded up), each with 8x8 threads.
7811 Compute shaders in mpv are treated a bit different from
7813 fragment shaders. Instead of defining a vec4 hook that
7814 produces an output sample, you directly define void hook
7815 which writes to a fixed writeonly image unit named
7816 out_image (this is bound by mpv) using imageStore. To
7817 help translate texture coordinates in the absence of ver‐
7818 tices, mpv provides a special function NAME_map(id) to
7819 map from the texel space of the output image to the tex‐
7820 ture coordinates for all bound textures. In particular,
7821 NAME_pos is equivalent to NAME_map(gl_GlobalInvoca‐
7822 tionID), although using this only really makes sense if
7823 (tw,th) == (bw,bh).
7824 Each bound mpv texture (via BIND) will make available the fol‐
7826 lowing definitions to that shader pass, where NAME is the name
7827 of the bound texture:
7828 vec4 NAME_tex(vec2 pos)
7830 The sampling function to use to access the texture at a
7831 certain spot (in texture coordinate space, range [0,1]).
7832 This takes care of any necessary normalization conver‐
7833 sions.
7834 vec4 NAME_texOff(vec2 offset)
7836 Sample the texture at a certain offset in pixels. This
7837 works like NAME_tex but additionally takes care of neces‐
7838 sary rotations, so that sampling at e.g. vec2(-1,0) is
7839 always one pixel to the left.
7840 vec2 NAME_pos
7842 The local texture coordinate of that texture, range
7843 [0,1].
7844 vec2 NAME_size
7846 The (rotated) size in pixels of the texture.
7847 mat2 NAME_rot
7849 The rotation matrix associated with this texture. (Ro‐
7850 tates pixel space to texture coordinates)
7851 vec2 NAME_pt
7853 The (unrotated) size of a single pixel, range [0,1].
7854 float NAME_mul
7856 The coefficient that needs to be multiplied into the tex‐
7857 ture contents in order to normalize it to the range
7858 [0,1].
7859 sampler NAME_raw
7861 The raw bound texture itself. The use of this should be
7862 avoided unless absolutely necessary.
7863 Normally, users should use either NAME_tex or NAME_texOff to
7865 read from the texture. For some shaders however , it can be bet‐
7866 ter for performance to do custom sampling from NAME_raw, in
7867 which case care needs to be taken to respect NAME_mul and
7868 NAME_rot.
7869 In addition to these parameters, the following uniforms are also
7871 globally available:
7872 float random
7874 A random number in the range [0-1], different per frame.
7875 int frame
7877 A simple count of frames rendered, increases by one per
7878 frame and never resets (regardless of seeks).
7879 vec2 input_size
7881 The size in pixels of the input image (possibly cropped
7882 and prescaled).
7883 vec2 target_size
7885 The size in pixels of the visible part of the scaled (and
7886 possibly cropped) image.
7887 vec2 tex_offset
7889 Texture offset introduced by user shaders or options like
7890 panscan, video-align-x/y, video-pan-x/y.
7891 Internally, vo_gpu may generate any number of the following tex‐
7893 tures. Whenever a texture is rendered and saved by vo_gpu, all
7894 of the passes that have hooked into it will run, in the order
7895 they were added by the user. This is a list of the legal hook
7896 points:
7897 RGB, LUMA, CHROMA, ALPHA, XYZ (resizable)
7899 Source planes (raw). Which of these fire depends on the
7900 image format of the source.
7901 CHROMA_SCALED, ALPHA_SCALED (fixed)
7903 Source planes (upscaled). These only fire on subsampled
7904 content.
7905 NATIVE (resizable)
7907 The combined image, in the source colorspace, before con‐
7908 version to RGB.
7909 MAINPRESUB (resizable)
7911 The image, after conversion to RGB, but before
7912 --blend-subtitles=video is applied.
7913 MAIN (resizable)
7915 The main image, after conversion to RGB but before up‐
7916 scaling.
7917 LINEAR (fixed)
7919 Linear light image, before scaling. This only fires when
7920 --linear-upscaling, --linear-downscaling or --sigmoid-up‐
7921 scaling is in effect.
7922 SIGMOID (fixed)
7924 Sigmoidized light, before scaling. This only fires when
7925 --sigmoid-upscaling is in effect.
7926 PREKERNEL (fixed)
7928 The image immediately before the scaler kernel runs.
7929 POSTKERNEL (fixed)
7931 The image immediately after the scaler kernel runs.
7932 SCALED (fixed)
7934 The final upscaled image, before color management.
7935 OUTPUT (fixed)
7937 The final output image, after color management but before
7938 dithering and drawing to screen.
7939 Only the textures labelled with resizable may be transformed by
7941 the pass. When overwriting a texture marked fixed, the WIDTH,
7942 HEIGHT and OFFSET must be left at their default values.
7943 --glsl-shader=<file>
7945 CLI/config file only alias for --glsl-shaders-append.
7946 --glsl-shader-opts=param1=value1,param2=value2,...
7948 Specifies the options to use for tunable shader parameters. You
7949 can target specific named shaders by prefixing the shader name
7950 with a /, e.g. shader/param=value. Without a prefix, parameters
7951 affect all shaders. The shader name is the base part of the
7952 shader filename, without the extension. (--vo=gpu-next only)
7953 --deband
7955 Enable the debanding algorithm. This greatly reduces the amount
7956 of visible banding, blocking and other quantization artifacts,
7957 at the expense of very slightly blurring some of the finest de‐
7958 tails. In practice, it's virtually always an improvement - the
7959 only reason to disable it would be for performance.
7960 --deband-iterations=<1..16>
7962 The number of debanding steps to perform per sample. Each step
7963 reduces a bit more banding, but takes time to compute. Note that
7964 the strength of each step falls off very quickly, so high num‐
7965 bers (>4) are practically useless. (Default 1)
7966 --deband-threshold=<0..4096>
7968 The debanding filter's cut-off threshold. Higher numbers in‐
7969 crease the debanding strength dramatically but progressively di‐
7970 minish image details. (Default 32)
7971 --deband-range=<1..64>
7973 The debanding filter's initial radius. The radius increases lin‐
7974 early for each iteration. A higher radius will find more gradi‐
7975 ents, but a lower radius will smooth more aggressively. (Default
7976 16)
7977 If you increase the --deband-iterations, you should probably de‐
7979 crease this to compensate.
7980 --deband-grain=<0..4096>
7982 Add some extra noise to the image. This significantly helps
7983 cover up remaining quantization artifacts. Higher numbers add
7984 more noise. (Default 48)
7985 --corner-rounding=<0..1>
7987 If set to a value above 0.0, the output will be rendered with
7988 rounded corners, as if an alpha transparency mask had been ap‐
7989 plied. The value indicates the relative fraction of the side
7990 length to round - a value of 1.0 rounds the corners as much as
7991 possible. (--vo=gpu-next only)
7992 --sharpen=<value>
7994 If set to a value other than 0, enable an unsharp masking fil‐
7995 ter. Positive values will sharpen the image (but add more ring‐
7996 ing and aliasing). Negative values will blur the image. If your
7997 GPU is powerful enough, consider alternatives like the ewa_lanc‐
7998 zossharp scale filter, or the --scale-blur option. (Only for
7999 --vo=gpu)
8000 --opengl-glfinish
8002 Call glFinish() before swapping buffers (default: disabled).
8003 Slower, but might improve results when doing framedropping. Can
8004 completely ruin performance. The details depend entirely on the
8005 OpenGL driver.
8006 --opengl-waitvsync
8008 Call glXWaitVideoSyncSGI after each buffer swap (default: dis‐
8009 abled). This may or may not help with video timing accuracy and
8010 frame drop. It's possible that this makes video output slower,
8011 or has no effect at all.
8012 X11/GLX only.
8014 --opengl-dwmflush=<no|windowed|yes|auto>
8016 Calls DwmFlush after swapping buffers on Windows (default:
8017 auto). It also sets SwapInterval(0) to ignore the OpenGL timing.
8018 Values are: no (disabled), windowed (only in windowed mode), yes
8019 (also in full screen).
8020 The value auto will try to determine whether the compositor is
8022 active, and calls DwmFlush only if it seems to be.
8023 This may help to get more consistent frame intervals, especially
8025 with high-fps clips - which might also reduce dropped frames.
8026 Typically, a value of windowed should be enough, since full
8027 screen may bypass the DWM.
8028 Windows only.
8030 --angle-d3d11-feature-level=<11_0|10_1|10_0|9_3>
8032 Selects a specific feature level when using the ANGLE backend
8033 with D3D11. By default, the highest available feature level is
8034 used. This option can be used to select a lower feature level,
8035 which is mainly useful for debugging. Note that OpenGL ES 3.0
8036 is only supported at feature level 10_1 or higher. Most ex‐
8037 tended OpenGL features will not work at lower feature levels
8038 (similar to --gpu-dumb-mode).
8039 Windows with ANGLE only.
8041 --angle-d3d11-warp=<yes|no|auto>
8043 Use WARP (Windows Advanced Rasterization Platform) when using
8044 the ANGLE backend with D3D11 (default: auto). This is a high
8045 performance software renderer. By default, it is used when the
8046 Direct3D hardware does not support Direct3D 11 feature level
8047 9_3. While the extended OpenGL features will work with WARP,
8048 they can be very slow.
8049 Windows with ANGLE only.
8051 --angle-egl-windowing=<yes|no|auto>
8053 Use ANGLE's built in EGL windowing functions to create a swap
8054 chain (default: auto). If this is set to no and the D3D11 ren‐
8055 derer is in use, ANGLE's built in swap chain will not be used
8056 and a custom swap chain that is optimized for video rendering
8057 will be created instead. If set to auto, a custom swap chain
8058 will be used for D3D11 and the built in swap chain will be used
8059 for D3D9. This option is mainly for debugging purposes, in case
8060 the custom swap chain has poor performance or does not work.
8061 If set to yes, the --angle-max-frame-latency, --an‐
8063 gle-swapchain-length and --angle-flip options will have no ef‐
8064 fect.
8065 Windows with ANGLE only.
8067 --angle-flip=<yes|no>
8069 Enable flip-model presentation, which avoids unnecessarily copy‐
8070 ing the backbuffer by sharing surfaces with the DWM (default:
8071 yes). This may cause performance issues with older drivers. If
8072 flip-model presentation is not supported (for example, on Win‐
8073 dows 7 without the platform update), mpv will automatically fall
8074 back to the older bitblt presentation model.
8075 If set to no, the --angle-swapchain-length option will have no
8077 effect.
8078 Windows with ANGLE only.
8080 --angle-renderer=<d3d9|d3d11|auto>
8082 Forces a specific renderer when using the ANGLE backend (de‐
8083 fault: auto). In auto mode this will pick D3D11 for systems that
8084 support Direct3D 11 feature level 9_3 or higher, and D3D9 other‐
8085 wise. This option is mainly for debugging purposes. Normally
8086 there is no reason to force a specific renderer, though --an‐
8087 gle-renderer=d3d9 may give slightly better performance on old
8088 hardware. Note that the D3D9 renderer only supports OpenGL ES
8089 2.0, so most extended OpenGL features will not work if this ren‐
8090 derer is selected (similar to --gpu-dumb-mode).
8091 Windows with ANGLE only.
8093 --macos-force-dedicated-gpu=<yes|no>
8095 Deactivates the automatic graphics switching and forces the ded‐
8096 icated GPU. (default: no)
8097 macOS only.
8099 --cocoa-cb-sw-renderer=<yes|no|auto>
8101 Use the Apple Software Renderer when using cocoa-cb (default:
8102 auto). If set to no the software renderer is never used and in‐
8103 stead fails when a the usual pixel format could not be created,
8104 yes will always only use the software renderer, and auto only
8105 falls back to the software renderer when the usual pixel format
8106 couldn't be created.
8107 macOS only.
8109 --cocoa-cb-10bit-context=<yes|no>
8111 Creates a 10bit capable pixel format for the context creation
8112 (default: yes). Instead of 8bit integer framebuffer a 16bit
8113 half-float framebuffer is requested.
8114 macOS only.
8116 --macos-title-bar-appearance=<appearance>
8118 Sets the appearance of the title bar (default: auto). Not all
8119 combinations of appearances and --macos-title-bar-material mate‐
8120 rials make sense or are unique. Appearances that are not sup‐
8121 ported by you current macOS version fall back to the default
8122 value. macOS and cocoa-cb only
8123 <appearance> can be one of the following:
8125 auto Detects the system settings and sets the title bar ap‐
8127 pearance appropriately. On macOS 10.14 it also detects
8128 run time changes.
8129 aqua The standard macOS Light appearance.
8131 darkAqua
8133 The standard macOS Dark appearance. (macOS 10.14+)
8134 vibrantLight
8136 Light vibrancy appearance with.
8137 vibrantDark
8139 Dark vibrancy appearance with.
8140 aquaHighContrast
8142 Light Accessibility appearance. (macOS 10.14+)
8143 darkAquaHighContrast
8145 Dark Accessibility appearance. (macOS 10.14+)
8146 vibrantLightHighContrast
8148 Light vibrancy Accessibility appearance. (macOS 10.14+)
8149 vibrantDarkHighContrast
8151 Dark vibrancy Accessibility appearance. (macOS 10.14+)
8152 --macos-title-bar-material=<material>
8154 Sets the material of the title bar (default: titlebar). All dep‐
8155 recated materials should not be used on macOS 10.14+ because
8156 their functionality is not guaranteed. Not all combinations of
8157 materials and --macos-title-bar-appearance appearances make
8158 sense or are unique. Materials that are not supported by you
8159 current macOS version fall back to the default value. macOS and
8160 cocoa-cb only
8161 <material> can be one of the following:
8163 titlebar
8165 The standard macOS title bar material.
8166 selection
8168 The standard macOS selection material.
8169 menu The standard macOS menu material. (macOS 10.11+)
8171 popover
8173 The standard macOS popover material. (macOS 10.11+)
8174 sidebar
8176 The standard macOS sidebar material. (macOS 10.11+)
8177 headerView
8179 The standard macOS header view material. (macOS 10.14+)
8180 sheet The standard macOS sheet material. (macOS 10.14+)
8182 windowBackground
8184 The standard macOS window background material. (macOS
8185 10.14+)
8186 hudWindow
8188 The standard macOS hudWindow material. (macOS 10.14+)
8189 fullScreen
8191 The standard macOS full screen material. (macOS 10.14+)
8192 toolTip
8194 The standard macOS tool tip material. (macOS 10.14+)
8195 contentBackground
8197 The standard macOS content background material. (macOS
8198 10.14+)
8199 underWindowBackground
8201 The standard macOS under window background material.
8202 (macOS 10.14+)
8203 underPageBackground
8205 The standard macOS under page background material. (dep‐
8206 recated in macOS 10.14+)
8207 dark The standard macOS dark material. (deprecated in macOS
8209 10.14+)
8210 light The standard macOS light material. (macOS 10.14+)
8212 mediumLight
8214 The standard macOS mediumLight material. (macOS 10.11+,
8215 deprecated in macOS 10.14+)
8216 ultraDark
8218 The standard macOS ultraDark material. (macOS 10.11+
8219 deprecated in macOS 10.14+)
8220 --macos-title-bar-color=<color>
8222 Sets the color of the title bar (default: completely transpar‐
8223 ent). Is influenced by --macos-title-bar-appearance and
8224 --macos-title-bar-material. See --sub-color for color syntax.
8225 --macos-fs-animation-duration=<default|0-1000>
8227 Sets the fullscreen resize animation duration in ms (default:
8228 default). The default value is slightly less than the system's
8229 animation duration (500ms) to prevent some problems when the end
8230 of an async animation happens at the same time as the end of the
8231 system wide fullscreen animation. Setting anything higher than
8232 500ms will only prematurely cancel the resize animation after
8233 the system wide animation ended. The upper limit is still set at
8234 1000ms since it's possible that Apple or the user changes the
8235 system defaults. Anything higher than 1000ms though seems too
8236 long and shouldn't be set anyway. (macOS and cocoa-cb only)
8237 --macos-app-activation-policy=<regular|accessory|prohibited>
8239 Changes the App activation policy. With accessory the mpv icon
8240 in the Dock can be hidden. (default: regular)
8241 macOS only.
8243 --macos-geometry-calculation=<visible|whole>
8245 This changes the rectangle which is used to calculate the screen
8246 position and size of the window (default: visible). visible
8247 takes the the menu bar and Dock into account and the window is
8248 only positioned/sized within the visible screen frame rectangle,
8249 whole takes the whole screen frame rectangle and ignores the
8250 menu bar and Dock. Other previous restrictions still apply, like
8251 the window can't be placed on top of the menu bar etc.
8252 macOS only.
8254 --android-surface-size=<WxH>
8256 Set dimensions of the rendering surface used by the Android gpu
8257 context. Needs to be set by the embedding application if the
8258 dimensions change during runtime (i.e. if the device is ro‐
8259 tated), via the surfaceChanged callback.
8260 Android with --gpu-context=android only.
8262 --gpu-sw
8264 Continue even if a software renderer is detected.
8265 --gpu-context=<sys>
8267 The value auto (the default) selects the GPU context. You can
8268 also pass help to get a complete list of compiled in backends
8269 (sorted by autoprobe order).
8270 auto auto-select (default)
8272 cocoa Cocoa/macOS (deprecated, use --vo=libmpv instead)
8274 win Win32/WGL
8276 winvk VK_KHR_win32_surface
8278 angle Direct3D11 through the OpenGL ES translation layer ANGLE.
8280 This supports almost everything the win backend does (if
8281 the ANGLE build is new enough).
8282 dxinterop (experimental)
8284 Win32, using WGL for rendering and Direct3D 9Ex for pre‐
8285 sentation. Works on Nvidia and AMD. Newer Intel chips
8286 with the latest drivers may also work.
8287 d3d11 Win32, with native Direct3D 11 rendering.
8289 x11 X11/GLX (deprecated/legacy, EGL is preferred these days)
8291 x11vk VK_KHR_xlib_surface
8293 wayland
8295 Wayland/EGL
8296 waylandvk
8298 VK_KHR_wayland_surface
8299 drm DRM/EGL
8301 displayvk
8303 VK_KHR_display. This backend is roughly the Vukan equiva‐
8304 lent of DRM/EGL, allowing for direct rendering via Vulkan
8305 without a display manager.
8306 x11egl X11/EGL
8308 android
8310 Android/EGL. Requires --wid be set to an an‐
8311 droid.view.Surface.
8312 --gpu-api=<type>
8314 Controls which type of graphics APIs will be accepted:
8315 auto Use any available API (default)
8317 opengl Allow only OpenGL (requires OpenGL 2.1+ or GLES 2.0+)
8319 vulkan Allow only Vulkan (requires a valid/working --spirv-com‐
8321 piler)
8322 d3d11 Allow only --gpu-context=d3d11
8324 --opengl-es=<mode>
8326 Controls which type of OpenGL context will be accepted:
8327 auto Allow all types of OpenGL (default)
8329 yes Only allow GLES
8331 no Only allow desktop/core GL
8333 --fbo-format=<fmt>
8335 Selects the internal format of textures used for FBOs. The for‐
8336 mat can influence performance and quality of the video output.
8337 fmt can be one of: rgb8, rgb10, rgb10_a2, rgb16, rgb16f, rgb32f,
8338 rgba12, rgba16, rgba16f, rgba16hf, rgba32f.
8339 Default: auto, which first attempts to utilize 16bit float
8341 (rgba16f, rgba16hf), and falls back to rgba16 if those are not
8342 available. Finally, attempts to utilize rgb10_a2 or rgba8 if
8343 all of the previous formats are not available.
8344 --gamma-factor=<0.1..2.0>
8346 Set an additional raw gamma factor (default: 1.0). If gamma is
8347 adjusted in other ways (like with the --gamma option or key
8348 bindings and the gamma property), the value is multiplied with
8349 the other gamma value.
8350 This option is deprecated and may be removed in the future.
8352 --gamma-auto
8354 Automatically corrects the gamma value depending on ambient
8355 lighting conditions (adding a gamma boost for bright rooms).
8356 This option is deprecated and may be removed in the future.
8358 NOTE: Only implemented on macOS.
8360 --image-lut=<file>
8362 Specifies a custom LUT file (in Adobe .cube format) to apply to
8363 the colors during image decoding. The exact interpretation of
8364 the LUT depends on the value of --image-lut-type. (Only for
8365 --vo=gpu-next)
8366 --image-lut-type=<value>
8368 Controls the interpretation of color values fed to and from the
8369 LUT specified as --image-lut. Valid values are:
8370 auto Chooses the interpretation of the LUT automatically from
8372 tagged metadata, and otherwise falls back to native. (De‐
8373 fault)
8374 native Applied to the raw image contents in its native col‐
8376 orspace, before decoding to RGB. For example, for a HDR10
8377 image, this would be fed PQ-encoded YCbCr values in the
8378 range 0.0 - 1.0.
8379 normalized
8381 Applied to the normalized RGB image contents, after de‐
8382 coding from its native color encoding, but before lin‐
8383 earization.
8384 conversion
8386 Fully replaces the color decoding. A LUT of this type
8387 should ingest the image's native colorspace and output
8388 normalized non-linear RGB.
8389 --target-colorspace-hint
8391 Automatically configure the output colorspace of the display to
8392 pass through the input values of the stream (e.g. for HDR
8393 passthrough), if possible. Requires a supporting driver and
8394 --vo=gpu-next.
8395 --target-prim=<value>
8397 Specifies the primaries of the display. Video colors will be
8398 adapted to this colorspace when ICC color management is not be‐
8399 ing used. Valid values are:
8400 auto Disable any adaptation, except for atypical color spaces.
8402 Specifically, wide/unusual gamuts get automatically
8403 adapted to BT.709, while standard gamut (i.e. BT.601 and
8404 BT.709) content is not touched. (default)
8405 bt.470m
8407 ITU-R BT.470 M
8408 bt.601-525
8410 ITU-R BT.601 (525-line SD systems, eg. NTSC), SMPTE
8411 170M/240M
8412 bt.601-625
8414 ITU-R BT.601 (625-line SD systems, eg. PAL/SECAM), ITU-R
8415 BT.470 B/G
8416 bt.709 ITU-R BT.709 (HD), IEC 61966-2-4 (sRGB), SMPTE RP177 An‐
8418 nex B
8419 bt.2020
8421 ITU-R BT.2020 (UHD)
8422 apple Apple RGB
8424 adobe Adobe RGB (1998)
8426 prophoto
8428 ProPhoto RGB (ROMM)
8429 cie1931
8431 CIE 1931 RGB (not to be confused with CIE XYZ)
8432 dci-p3 DCI-P3 (Digital Cinema Colorspace), SMPTE RP431-2
8434 v-gamut
8436 Panasonic V-Gamut (VARICAM) primaries
8437 s-gamut
8439 Sony S-Gamut (S-Log) primaries
8440 --target-trc=<value>
8442 Specifies the transfer characteristics (gamma) of the display.
8443 Video colors will be adjusted to this curve when ICC color man‐
8444 agement is not being used. Valid values are:
8445 auto Disable any adaptation, except for atypical transfers.
8447 Specifically, HDR or linear light source material gets
8448 automatically converted to gamma 2.2, while SDR content
8449 is not touched. (default)
8450 bt.1886
8452 ITU-R BT.1886 curve (assuming infinite contrast)
8453 srgb IEC 61966-2-4 (sRGB)
8455 linear Linear light output
8457 gamma1.8
8459 Pure power curve (gamma 1.8), also used for Apple RGB
8460 gamma2.0
8462 Pure power curve (gamma 2.0)
8463 gamma2.2
8465 Pure power curve (gamma 2.2)
8466 gamma2.4
8468 Pure power curve (gamma 2.4)
8469 gamma2.6
8471 Pure power curve (gamma 2.6)
8472 gamma2.8
8474 Pure power curve (gamma 2.8), also used for BT.470-BG
8475 prophoto
8477 ProPhoto RGB (ROMM)
8478 pq ITU-R BT.2100 PQ (Perceptual quantizer) curve, aka SMPTE
8480 ST2084
8481 hlg ITU-R BT.2100 HLG (Hybrid Log-gamma) curve, aka ARIB
8483 STD-B67
8484 v-log Panasonic V-Log (VARICAM) curve
8486 s-log1 Sony S-Log1 curve
8488 s-log2 Sony S-Log2 curve
8490 NOTE:
8492 When using HDR output formats, mpv will encode to the speci‐
8493 fied curve but it will not set any HDMI flags or other sig‐
8494 nalling that might be required for the target device to cor‐
8495 rectly display the HDR signal. The user should independently
8496 guarantee this before using these signal formats for display.
8497 --target-peak=<auto|nits>
8499 Specifies the measured peak brightness of the output display, in
8500 cd/m^2 (AKA nits). The interpretation of this brightness depends
8501 on the configured --target-trc. In all cases, it imposes a limit
8502 on the signal values that will be sent to the display. If the
8503 source exceeds this brightness level, a tone mapping filter will
8504 be inserted. For HLG, it has the additional effect of
8505 parametrizing the inverse OOTF, in order to get colorimetrically
8506 consistent results with the mastering display. For SDR, or when
8507 using an ICC (profile (--icc-profile), setting this to a value
8508 above 203 essentially causes the display to be treated as if it
8509 were an HDR display in disguise. (See the note below)
8510 In auto mode (the default), the chosen peak is an appropriate
8512 value based on the TRC in use. For SDR curves, it uses 203. For
8513 HDR curves, it uses 203 * the transfer function's nominal peak.
8514 NOTE:
8516 When using an SDR transfer function, this is normally not
8517 needed, and setting it may lead to very unexpected results.
8518 The one time it is useful is if you want to calibrate a HDR
8519 display using traditional transfer functions and calibration
8520 equipment. In such cases, you can set your HDR display to a
8521 high brightness such as 800 cd/m^2, and then calibrate it to
8522 a standard curve like gamma2.8. Setting this value to 800
8523 would then instruct mpv to essentially treat it as an HDR
8524 display with the given peak. This may be a good alternative
8525 in environments where PQ or HLG input to the display is not
8526 possible, and makes it possible to use HDR displays with mpv
8527 regardless of operating system support for HDMI HDR metadata.
8528 In such a configuration, we highly recommend setting
8530 --tone-mapping to mobius or even clip.
8531 --target-contrast=<auto|10-1000000|inf>
8533 Specifies the measured contrast of the output display. --tar‐
8534 get-contrast in conjunction with --target-peak value is used to
8535 calculate display black point. Used in black point compensation
8536 during HDR tone-mapping. auto is the default and assumes 1000:1
8537 contrast as a typical SDR display would have or an infinite con‐
8538 trast when HDR --target-trc is used. inf contrast specifies
8539 display with perfect black level, in practice OLED. (Only for
8540 --vo=gpu-next)
8541 --target-lut=<file>
8543 Specifies a custom LUT file (in Adobe .cube format) to apply to
8544 the colors before display on-screen. This LUT is fed values in
8545 normalized RGB, after encoding into the target colorspace, so
8546 after the application of --target-trc. (Only for --vo=gpu-next)
8547 --tone-mapping=<value>
8549 Specifies the algorithm used for tone-mapping images onto the
8550 target display. This is relevant for both HDR->SDR conversion as
8551 well as gamut reduction (e.g. playing back BT.2020 content on a
8552 standard gamut display). Valid values are:
8553 auto Choose the best curve according to internal heuristics.
8555 (Default)
8556 clip Hard-clip any out-of-range values. Use this when you care
8558 about perfect color accuracy for in-range values at the
8559 cost of completely distorting out-of-range values. Not
8560 generally recommended.
8561 mobius Generalization of Reinhard to a Möbius transform with
8563 linear section. Smoothly maps out-of-range values while
8564 retaining contrast and colors for in-range material as
8565 much as possible. Use this when you care about color ac‐
8566 curacy more than detail preservation. This is somewhere
8567 in between clip and reinhard, depending on the value of
8568 --tone-mapping-param.
8569 reinhard
8571 Reinhard tone mapping algorithm. Very simple continuous
8572 curve. Preserves overall image brightness but uses non‐
8573 linear contrast, which results in flattening of details
8574 and degradation in color accuracy.
8575 hable Similar to reinhard but preserves both dark and bright
8577 details better (slightly sigmoidal), at the cost of
8578 slightly darkening / desaturating everything. Developed
8579 by John Hable for use in video games. Use this when you
8580 care about detail preservation more than color/brightness
8581 accuracy. This is roughly equivalent to --tone-map‐
8582 ping=reinhard --tone-mapping-param=0.24. If possible, you
8583 should also enable --hdr-compute-peak for the best re‐
8584 sults.
8585 bt.2390
8587 Perceptual tone mapping curve (EETF) specified in ITU-R
8588 Report BT.2390.
8589 gamma Fits a logarithmic transfer between the tone curves.
8591 linear Linearly stretches the entire reference gamut to (a lin‐
8593 ear multiple of) the display.
8594 spline Perceptually linear single-pivot polynomial.
8596 (--vo=gpu-next only)
8597 bt.2446a
8599 HDR<->SDR mapping specified in ITU-R Report BT.2446,
8600 method A. This is the recommended curve for well-mastered
8601 content. (--vo=gpu-next only)
8602 st2094-40
8604 Dynamic HDR10+ tone-mapping method specified in SMPTE
8605 ST2094-40 Annex B. In the absence of metadata, falls back
8606 to a fixed spline matched to the input/output average
8607 brightness characteristics. (--vo=gpu-next only)
8608 st2094-10
8610 Dynamic tone-mapping method specified in SMPTE ST2094-10
8611 Annex B.2. Conceptually simpler than ST2094-40, and gen‐
8612 erally produces worse results.
8613 --tone-mapping-param=<value>
8615 Set tone mapping parameters. By default, this is set to the spe‐
8616 cial string default, which maps to an algorithm-specific default
8617 value. Ignored if the tone mapping algorithm is not tunable.
8618 This affects the following tone mapping algorithms:
8619 clip Specifies an extra linear coefficient to multiply into
8621 the signal before clipping. Defaults to 1.0.
8622 mobius Specifies the transition point from linear to mobius
8624 transform. Every value below this point is guaranteed to
8625 be mapped 1:1. The higher the value, the more accurate
8626 the result will be, at the cost of losing bright details.
8627 Defaults to 0.3, which due to the steep initial slope
8628 still preserves in-range colors fairly accurately.
8629 reinhard
8631 Specifies the local contrast coefficient at the display
8632 peak. Defaults to 0.5, which means that in-gamut values
8633 will be about half as bright as when clipping.
8634 bt.2390
8636 Specifies the offset for the knee point. Defaults to 1.0,
8637 which is higher than the value from the original ITU-R
8638 specification (0.5). (--vo=gpu-next only)
8639 gamma Specifies the exponent of the function. Defaults to 1.8.
8641 linear Specifies the scale factor to use while stretching. De‐
8643 faults to 1.0.
8644 spline Specifies the knee point (in PQ space). Defaults to 0.30.
8646 st2094-10
8648 Specifies the contrast (slope) at the knee point. De‐
8649 faults to 1.0.
8650 --inverse-tone-mapping
8652 If set, allows inverse tone mapping (expanding SDR to HDR). Not
8653 supported by all tone mapping curves. Use with caution.
8654 (--vo=gpu-next only)
8655 --tone-mapping-max-boost=<1.0..10.0>
8657 Upper limit for how much the tone mapping algorithm is allowed
8658 to boost the average brightness by over-exposing the image. The
8659 default value of 1.0 allows no additional brightness boost. A
8660 value of 2.0 would allow over-exposing by a factor of 2, and so
8661 on. Raising this setting can help reveal details that would oth‐
8662 erwise be hidden in dark scenes, but raising it too high will
8663 make dark scenes appear unnaturally bright. (--vo=gpu only)
8664 --tone-mapping-mode
8666 Controls how the tone mapping function is applied to colors.
8667 auto Choose the best mode automatically. (Default)
8669 rgb Tone-map per-channel (RGB). Has a tendency to severely
8671 distort colors, desaturate highlights, and is generally
8672 not very recommended. However, this is the mode used in
8673 many displays and TVs (especially early ones), and so
8674 sometimes it's needed to reproduce the artistic intent a
8675 film was mastered with.
8676 max Tone-map on the brightest component in the video. Has a
8678 tendency to lead to weirdly oversaturated colors, and
8679 loss of dark details.
8680 hybrid A hybrid approach that uses linear tone-mapping for mid‐
8682 tones and per-channel tone mapping for highlights.
8683 luma Luminance-based method from ITU-R BT.2446a, including
8685 fixed gamut reductions to account for brightness-related
8686 perceptual nonuniformity. (--vo=gpu-next only)
8687 --tone-mapping-visualize
8689 Display a (PQ-PQ) graph of the active tone-mapping LUT. Intended
8690 only for debugging purposes. The X axis shows PQ input values,
8691 the Y axis shows PQ output values. The tone-mapping curve is
8692 shown in green/yellow. Yellow means the brightness has been
8693 boosted from the source, dark blue regions show where the
8694 brightness has been reduced. The extra colored regions and lines
8695 indicate various monitor limits, as well a reference diagonal
8696 (neutral tone-mapping) and source scene average brightness in‐
8697 formation (if available). (--vo=gpu-next only)
8698 --gamut-mapping-mode
8700 Specifies the algorithm used for reducing the gamut of images
8701 for the target display, after any tone mapping is done.
8702 auto Choose the best mode automatically. (Default)
8704 clip Hard-clip to the gamut (per-channel). Very low quality,
8706 but free.
8707 perceptual
8709 Performs a perceptually balanced gamut mapping using a
8710 soft knee function to roll-off clipped regions, and a hue
8711 shifting function to preserve saturation. (--vo=gpu-next
8712 only)
8713 relative
8715 Performs relative colorimetric clipping, while maintain‐
8716 ing an exponential relationship between brightness and
8717 chromaticity. (--vo=gpu-next only)
8718 saturation
8720 Performs simple RGB->RGB saturation mapping. The input
8721 R/G/B channels are mapped directly onto the output R/G/B
8722 channels. Will never clip, but will distort all hues
8723 and/or result in a faded look. (--vo=gpu-next only)
8724 absolute
8726 Performs absolute colorimetric clipping. Like relative,
8727 but does not adapt the white point. (--vo=gpu-next only)
8728 desaturate
8730 Performs constant-luminance colorimetric clipping, desat‐
8731 uring colors towards white until they're in-range.
8732 darken Uniformly darkens the input slightly to prevent clipping
8734 on blown-out highlights, then clamps colorimetrically to
8735 the input gamut boundary, biased slightly to preserve
8736 chromaticity over luminance. (--vo=gpu-next only)
8737 warn Performs no gamut mapping, but simply highlights
8739 out-of-gamut pixels.
8740 linear Linearly/uniformly desaturates the image in order to
8742 bring the entire image into the target gamut.
8743 (--vo=gpu-next only)
8744 --hdr-compute-peak=<auto|yes|no>
8746 Compute the HDR peak and frame average brightness per-frame in‐
8747 stead of relying on tagged metadata. These values are averaged
8748 over local regions as well as over several frames to prevent the
8749 value from jittering around too much. This option basically
8750 gives you dynamic, per-scene tone mapping. Requires compute
8751 shaders, which is a fairly recent OpenGL feature, and will prob‐
8752 ably also perform horribly on some drivers, so enable at your
8753 own risk. The special value auto (default) will enable HDR peak
8754 computation automatically if compute shaders and SSBOs are sup‐
8755 ported.
8756 --allow-delayed-peak-detect
8758 When using --hdr-compute-peak, allow delaying the detected peak
8759 by a frame when beneficial for performance. In particular, this
8760 is required to avoid an unnecessary FBO indirection when no ad‐
8761 vanced rendering is required otherwise. Has no effect if there
8762 already is an indirect pass, such as when advanced scaling is
8763 enabled. Defaults to on. (Only affects --vo=gpu-next, note that
8764 --vo=gpu always delays the peak.)
8765 --hdr-peak-decay-rate=<1.0..1000.0>
8767 The decay rate used for the HDR peak detection algorithm (de‐
8768 fault: 100.0). This is only relevant when --hdr-compute-peak is
8769 enabled. Higher values make the peak decay more slowly, leading
8770 to more stable values at the cost of more "eye adaptation"-like
8771 effects (although this is mitigated somewhat by
8772 --hdr-scene-threshold). A value of 1.0 (the lowest possible)
8773 disables all averaging, meaning each frame's value is used di‐
8774 rectly as measured, but doing this is not recommended for
8775 "noisy" sources since it may lead to excessive flicker. (In sig‐
8776 nal theory terms, this controls the time constant "tau" of an
8777 IIR low pass filter)
8778 --hdr-scene-threshold-low=<0.0..100.0>, --hdr-scene-thresh‐
8780 old-high=<0.0..100.0>
8781 The lower and upper thresholds (in dB) for a brightness differ‐
8782 ence to be considered a scene change (default: 5.5 low, 10.0
8783 high). This is only relevant when --hdr-compute-peak is enabled.
8784 Normally, small fluctuations in the frame brightness are compen‐
8785 sated for by the peak averaging mechanism, but for large jumps
8786 in the brightness this can result in the frame remaining too
8787 bright or too dark for up to several seconds, depending on the
8788 value of --hdr-peak-decay-rate. To counteract this, when the
8789 brightness between the running average and the current frame ex‐
8790 ceeds the low threshold, mpv will make the averaging filter more
8791 aggressive, up to the limit of the high threshold (at which
8792 point the filter becomes instant).
8793 --hdr-contrast-recovery=<0.0..2.0>, --hdr-contrast-smooth‐
8795 ness=<1.0..100.0>
8796 Enables the HDR contrast recovery algorithm, which is to de‐
8797 signed to enhance contrast of HDR video after tone mapping. The
8798 strength (default: 0.0) indicates the degree of contrast recov‐
8799 ery, with 0.0 being completely disabled and 1.0 being 100%
8800 strength. Values higher than 1.0 are allowed, but may result in
8801 excessive sharpening. The smoothness (default: 3.5) indicates
8802 the degree to which the HDR source is low-passed in order to ob‐
8803 tain contrast information - a value of 2.0 corresponds to 2x
8804 downscaling. Users on low DPI displays (<= 100) may want to
8805 lower this value, while users on very high DPI displays
8806 ("retina") may want to increase it. (Only for vo=gpu-next)
8807 --use-embedded-icc-profile
8809 Load the embedded ICC profile contained in media files such as
8810 PNG images. (Default: yes). Note that this option only works
8811 when also using a display ICC profile (--icc-profile or
8812 --icc-profile-auto), and also requires LittleCMS 2 support.
8813 --icc-profile=<file>
8815 Load an ICC profile and use it to transform video RGB to screen
8816 output. Needs LittleCMS 2 support compiled in. This option
8817 overrides the --target-prim, --target-trc and --icc-profile-auto
8818 options.
8819 --icc-profile-auto
8821 Automatically select the ICC display profile currently specified
8822 by the display settings of the operating system.
8823 NOTE: On Windows, the default profile must be an ICC profile.
8825 WCS profiles are not supported.
8826 Applications using libmpv with the render API need to provide
8828 the ICC profile via MPV_RENDER_PARAM_ICC_PROFILE.
8829 --icc-cache
8831 Store and load 3D LUTs created from the ICC profile on disk in
8832 the cache directory (Default: yes). This can be used to speed up
8833 loading, since LittleCMS 2 can take a while to create a 3D LUT.
8834 Note that these files contain uncompressed LUTs. Their size de‐
8835 pends on the --icc-3dlut-size, and can be very big.
8836 NOTE: This is not cleaned automatically, so old, unused cache
8838 files may stick around indefinitely.
8839 --icc-cache-dir
8841 The directory where icc cache is stored. Cache is stored in the
8842 system's cache directory (usually ~/.cache/mpv) if this is un‐
8843 set.
8844 --icc-intent=<value>
8846 Specifies the ICC intent used for the color transformation (when
8847 using --icc-profile).
8848 0 perceptual
8850 1 relative colorimetric (default)
8852 2 saturation
8854 3 absolute colorimetric
8856 --icc-3dlut-size=<r>x<g>x<b>
8858 Size of the 3D LUT generated from the ICC profile in each dimen‐
8859 sion. Default is 64x64x64. Sizes may range from 2 to 512.
8860 --icc-force-contrast=<no|0-1000000|inf>
8862 Override the target device's detected contrast ratio by a spe‐
8863 cific value. This is detected automatically from the profile if
8864 possible, but for some profiles it might be missing, causing the
8865 contrast to be assumed as infinite. As a result, video may ap‐
8866 pear darker than intended. If this is the case, setting this op‐
8867 tion might help. This only affects BT.1886 content. The default
8868 of no means to use the profile values. The special value inf
8869 causes the BT.1886 curve to be treated as a pure power gamma 2.4
8870 function.
8871 --icc-use-luma
8873 Use ICC profile luminance value. (Only for --vo=gpu-next)
8874 --lut=<file>
8876 Specifies a custom LUT (in Adobe .cube format) to apply to the
8877 colors as part of color conversion. The exact interpretation de‐
8878 pends on the value of --lut-type. (Only for --vo=gpu-next)
8879 --lut-type=<value>
8881 Controls the interpretation of color values fed to and from the
8882 LUT specified as --lut. Valid values are:
8883 auto Chooses the interpretation of the LUT automatically from
8885 tagged metadata, and otherwise falls back to native. (De‐
8886 fault)
8887 native Applied to raw image contents in its native RGB col‐
8889 orspace (non-linear light), before conversion to the out‐
8890 put color space.
8891 normalized
8893 Applied to the normalized RGB image contents, in linear
8894 light, before conversion to the output color space.
8895 conversion
8897 Fully replaces the conversion from the image color space
8898 to the output color space. If such a LUT is present, it
8899 has the highest priority, and overrides any ICC profiles,
8900 as well as options related to tone mapping and output
8901 colorimetry (--target-prim, --target-trc etc.).
8902 --blend-subtitles=<yes|video|no>
8904 Blend subtitles directly onto upscaled video frames, before in‐
8905 terpolation and/or color management (default: no). Enabling this
8906 causes subtitles to be affected by --icc-profile, --target-prim,
8907 --target-trc, --interpolation, --gamma-factor and
8908 --glsl-shaders. It also increases subtitle performance when us‐
8909 ing --interpolation.
8910 The downside of enabling this is that it restricts subtitles to
8912 the visible portion of the video, so you can't have subtitles
8913 exist in the black margins below a video (for example).
8914 If video is selected, the behavior is similar to yes, but subs
8916 are drawn at the video's native resolution, and scaled along
8917 with the video.
8918 WARNING:
8920 This changes the way subtitle colors are handled. Normally,
8921 subtitle colors are assumed to be in sRGB and color managed
8922 as such. Enabling this makes them treated as being in the
8923 video's color space instead. This is good if you want things
8924 like softsubbed ASS signs to match the video colors, but may
8925 cause SRT subtitles or similar to look slightly off.
8926 --alpha=<blend-tiles|blend|yes|no>
8928 Decides what to do if the input has an alpha component.
8929 blend-tiles
8931 Blend the frame against a 16x16 gray/white tiles back‐
8932 ground (default).
8933 blend Blend the frame against the background color (--back‐
8935 ground, normally black).
8936 yes Try to create a framebuffer with alpha component. This
8938 only makes sense if the video contains alpha information
8939 (which is extremely rare) or if you make the background
8940 color transparent. May not be supported on all platforms.
8941 If alpha framebuffers are unavailable, it silently falls
8942 back on a normal framebuffer. Note that if you set the
8943 --fbo-format option to a non-default value, a format with
8944 alpha must be specified, or this won't work. Whether this
8945 really works depends on the windowing system and desktop
8946 environment.
8947 no Ignore alpha component.
8949 --opengl-rectangle-textures
8951 Force use of rectangle textures (default: no). Normally this
8952 shouldn't have any advantages over normal textures. Note that
8953 hardware decoding overrides this flag. Could be removed any
8954 time.
8955 --background=<color>
8957 Color used to draw parts of the mpv window not covered by video.
8958 See the --sub-color option for how colors are defined.
8959 --gpu-tex-pad-x, --gpu-tex-pad-y
8961 Enlarge the video source textures by this many pixels. For de‐
8962 bugging only (normally textures are sized exactly, but due to
8963 hardware decoding interop we may have to deal with additional
8964 padding, which can be tested with these options). Could be re‐
8965 moved any time.
8966 --opengl-early-flush=<yes|no|auto>
8968 Call glFlush() after rendering a frame and before attempting to
8969 display it (default: auto). Can fix stuttering in some cases, in
8970 other cases probably causes it. The auto mode will call
8971 glFlush() only if the renderer is going to wait for a while af‐
8972 ter rendering, instead of flipping GL front and backbuffers im‐
8973 mediately (i.e. it doesn't call it in display-sync mode).
8974 On macOS this is always deactivated because it only causes per‐
8976 formance problems and other regressions.
8977 --gpu-dumb-mode=<yes|no|auto>
8979 This mode is extremely restricted, and will disable most ex‐
8980 tended features. That includes high quality scalers and custom
8981 shaders!
8982 It is intended for hardware that does not support FBOs (includ‐
8984 ing GLES, which supports it insufficiently), or to get some more
8985 performance out of bad or old hardware.
8986 This mode is forced automatically if needed, and this option is
8988 mostly useful for debugging. The default of auto will enable it
8989 automatically if nothing uses features which require FBOs.
8990 This option might be silently removed in the future.
8992 --gpu-shader-cache
8994 Store and load compiled GLSL shaders in the cache directory (De‐
8995 fault: yes). Normally, shader compilation is very fast, so this
8996 is not usually needed. It mostly matters for GPU APIs that re‐
8997 quire internally recompiling shaders to other languages, for ex‐
8998 ample anything based on ANGLE or Vulkan. Enabling this can im‐
8999 prove startup performance on these platforms.
9000 NOTE: This is not cleaned automatically, so old, unused cache
9002 files may stick around indefinitely.
9003 --gpu-shader-cache-dir
9005 The directory where gpu shader cache is stored. Cache is stored
9006 in the system's cache directory (usually ~/.cache/mpv) if this
9007 is unset.
9008 Miscellaneous
9010 --display-tags=tag1,tags2,...
9011 Set the list of tags that should be displayed on the terminal.
9012 Tags that are in the list, but are not present in the played
9013 file, will not be shown. If a value ends with *, all tags are
9014 matched by prefix (though there is no general globbing). Just
9015 passing * essentially filtering.
9016 The default includes a common list of tags, call mpv with
9018 --list-options to see it.
9019 This is a string list option. See List Options for details.
9021 --mc=<seconds/frame>
9023 Maximum A-V sync correction per frame (in seconds)
9024 --autosync=<factor>
9026 Gradually adjusts the A/V sync based on audio delay measure‐
9027 ments. Specifying --autosync=0, the default, will cause frame
9028 timing to be based entirely on audio delay measurements. Speci‐
9029 fying --autosync=1 will do the same, but will subtly change the
9030 A/V correction algorithm. An uneven video framerate in a video
9031 which plays fine with --no-audio can often be helped by setting
9032 this to an integer value greater than 1. The higher the value,
9033 the closer the timing will be to --no-audio. Try --autosync=30
9034 to smooth out problems with sound drivers which do not implement
9035 a perfect audio delay measurement. With this value, if large A/V
9036 sync offsets occur, they will only take about 1 or 2 seconds to
9037 settle out. This delay in reaction time to sudden A/V offsets
9038 should be the only side effect of turning this option on, for
9039 all sound drivers.
9040 --video-timing-offset=<seconds>
9042 Control how long before video display target time the frame
9043 should be rendered (default: 0.050). If a video frame should be
9044 displayed at a certain time, the VO will start rendering the
9045 frame earlier, and then will perform a blocking wait until the
9046 display time, and only then "swap" the frame to display. The
9047 rendering cannot start before the previous frame is displayed,
9048 so this value is implicitly limited by the video framerate. With
9049 normal video frame rates, the default value will ensure that
9050 rendering is always immediately started after the previous frame
9051 was displayed. On the other hand, setting a too high value can
9052 reduce responsiveness with low FPS value.
9053 This option is interesting for client API users using the render
9055 API because you can stop it from limiting your FPS (see mpv_ren‐
9056 der_context_render() documentation).
9057 This applies only to audio timing modes (e.g. --video-sync=au‐
9059 dio). In other modes (--video-sync=display-...), video timing
9060 relies on vsync blocking, and this option is not used.
9061 --video-sync=<audio|...>
9063 How the player synchronizes audio and video.
9064 If you use this option, you usually want to set it to dis‐
9066 play-resample to enable a timing mode that tries to not skip or
9067 repeat frames when for example playing 24fps video on a 24Hz
9068 screen.
9069 The modes starting with display- try to output video frames com‐
9071 pletely synchronously to the display, using the detected display
9072 vertical refresh rate as a hint how fast frames will be dis‐
9073 played on average. These modes change video speed slightly to
9074 match the display. See --video-sync-... options for fine tun‐
9075 ing. The robustness of this mode is further reduced by making a
9076 some idealized assumptions, which may not always apply in real‐
9077 ity. Behavior can depend on the VO and the system's video and
9078 audio drivers. Media files must use constant framerate. Sec‐
9079 tion-wise VFR might work as well with some container formats
9080 (but not e.g. mkv).
9081 Under some circumstances, the player automatically reverts to
9083 audio mode for some time or permanently. This can happen on very
9084 low framerate video, or if the framerate cannot be detected.
9085 Also in display-sync modes it can happen that interruptions to
9087 video playback (such as toggling fullscreen mode, or simply re‐
9088 sizing the window) will skip the video frames that should have
9089 been displayed, while audio mode will display them after the
9090 renderer has resumed (typically resulting in a short A/V desync
9091 and the video "catching up").
9092 Before mpv 0.30.0, there was a fallback to audio mode on severe
9094 A/V desync. This was changed for the sake of not sporadically
9095 stopping. Now, display-desync does what it promises and may
9096 desync with audio by an arbitrary amount, until it is manually
9097 fixed with a seek.
9098 These modes also require a vsync blocked presentation mode. For
9100 OpenGL, this translates to --opengl-swapinterval=1. For Vulkan,
9101 it translates to --vulkan-swap-mode=fifo (or fifo-relaxed).
9102 The modes with desync in their names do not attempt to keep au‐
9104 dio/video in sync. They will slowly (or quickly) desync, until
9105 e.g. the next seek happens. These modes are meant for testing,
9106 not serious use.
9107 audio Time video frames to audio. This is the most robust mode,
9109 because the player doesn't have to assume anything about
9110 how the display behaves. The disadvantage is that it can
9111 lead to occasional frame drops or repeats. If audio is
9112 disabled, this uses the system clock. This is the default
9113 mode.
9114 display-resample
9116 Resample audio to match the video. This mode will also
9117 try to adjust audio speed to compensate for other drift.
9118 (This means it will play the audio at a different speed
9119 every once in a while to reduce the A/V difference.)
9120 display-resample-vdrop
9122 Resample audio to match the video. Drop video frames to
9123 compensate for drift.
9124 display-resample-desync
9126 Like the previous mode, but no A/V compensation.
9127 display-tempo
9129 Same as display-resample, but apply audio speed changes
9130 to audio filters instead of resampling to avoid the
9131 change in pitch. Beware that some audio filters don't do
9132 well with a speed close to 1. It is recommend to use a
9133 conditional profile to automatically switch to dis‐
9134 play-resample when speed gets too close to 1 for your
9135 filter setup. Use (speed * video_speed_correction) to get
9136 the actual playback speed in the condition. See
9137 Conditional auto profiles for details.
9138 display-vdrop
9140 Drop or repeat video frames to compensate desyncing
9141 video. (Although it should have the same effects as au‐
9142 dio, the implementation is very different.)
9143 display-adrop
9145 Drop or repeat audio data to compensate desyncing video.
9146 This mode will cause severe audio artifacts if the real
9147 monitor refresh rate is too different from the reported
9148 or forced rate. Since mpv 0.33.0, this acts on entire au‐
9149 dio frames, instead of single samples.
9150 display-desync
9152 Sync video to display, and let audio play on its own.
9153 desync Sync video according to system clock, and let audio play
9155 on its own.
9156 --video-sync-max-factor=<value>
9158 Maximum multiple for which to try to fit the video's FPS to the
9159 display's FPS (default: 5).
9160 For example, if this is set to 1, the video FPS is forced to an
9162 integer multiple of the display FPS, as long as the speed change
9163 does not exceed the value set by --video-sync-max-video-change.
9164 See --interpolation-threshold for how this option affects inter‐
9166 polation.
9167 --video-sync-max-video-change=<value>
9169 Maximum speed difference in percent that is applied to video
9170 with --video-sync=display-... (default: 1). Display sync mode
9171 will be disabled if the monitor and video refresh way do not
9172 match within the given range. It tries multiples as well: play‐
9173 ing 30 fps video on a 60 Hz screen will duplicate every second
9174 frame. Playing 24 fps video on a 60 Hz screen will play video in
9175 a 2-3-2-3-... pattern.
9176 The default settings are not loose enough to speed up 23.976 fps
9178 video to 25 fps. We consider the pitch change too extreme to al‐
9179 low this behavior by default. Set this option to a value of 5 to
9180 enable it.
9181 Note that --video-sync=display-tempo avoids this pitch change.
9183 Also note that in the --video-sync=display-resample or
9185 --video-sync=display-tempo mode, audio speed will additionally
9186 be changed by a small amount if necessary for A/V sync. See
9187 --video-sync-max-audio-change.
9188 --video-sync-max-audio-change=<value>
9190 Maximum additional speed difference in percent that is applied
9191 to audio with --video-sync=display-... (default: 0.125). Nor‐
9192 mally, the player plays the audio at the speed of the video. But
9193 if the difference between audio and video position is too high,
9194 e.g. due to drift or other timing errors, it will attempt to
9195 speed up or slow down audio by this additional factor. Too low
9196 values could lead to video frame dropping or repeating if the
9197 A/V desync cannot be compensated, too high values could lead to
9198 chaotic frame dropping due to the audio "overshooting" and skip‐
9199 ping multiple video frames before the sync logic can react.
9200 --mf-fps=<value>
9202 Framerate used when decoding from multiple PNG or JPEG files
9203 with mf:// (default: 1).
9204 --mf-type=<value>
9206 Input file type for mf:// (available: jpeg, png, tga, sgi). By
9207 default, this is guessed from the file extension.
9208 --stream-dump=<destination-filename>
9210 Instead of playing a file, read its byte stream and write it to
9211 the given destination file. The destination is overwritten. Can
9212 be useful to test network-related behavior.
9213 --stream-lavf-o=opt1=value1,opt2=value2,...
9215 Set AVOptions on streams opened with libavformat. Unknown or
9216 misspelled options are silently ignored. (They are mentioned in
9217 the terminal output in verbose mode, i.e. --v. In general we
9218 can't print errors, because other options such as e.g. user
9219 agent are not available with all protocols, and printing errors
9220 for unknown options would end up being too noisy.)
9221 This is a key/value list option. See List Options for details.
9223 --vo-mmcss-profile=<name>
9225 (Windows only.) Set the MMCSS profile for the video renderer
9226 thread (default: Playback).
9227 --priority=<prio>
9229 (Windows only.) Set process priority for mpv according to the
9230 predefined priorities available under Windows.
9231 Possible values of <prio>: idle|belownormal|normal|abovenor‐
9233 mal|high|realtime
9234 WARNING:
9236 Using realtime priority can cause system lockup.
9237 --force-media-title=<string>
9239 Force the contents of the media-title property to this value.
9240 Useful for scripts which want to set a title, without overriding
9241 the user's setting in --title.
9242 --external-files=<file-list>
9244 Load a file and add all of its tracks. This is useful to play
9245 different files together (for example audio from one file, video
9246 from another), or for advanced --lavfi-complex used (like play‐
9247 ing two video files at the same time).
9248 Unlike --sub-files and --audio-files, this includes all tracks,
9250 and does not cause default stream selection over the "proper"
9251 file. This makes it slightly less intrusive. (In mpv 0.28.0 and
9252 before, this was not quite strictly enforced.)
9253 This is a path list option. See List Options for details.
9255 --external-file=<file>
9257 CLI/config file only alias for --external-files-append. Each use
9258 of this option will add a new external file.
9259 --cover-art-files=<file-list>
9261 Use an external file as cover art while playing audio. This
9262 makes it appear on the track list and subject to automatic track
9263 selection. Options like --audio-display control whether such
9264 tracks are supposed to be selected.
9265 (The difference to loading a file with --external-files is that
9267 video tracks will be marked as being pictures, which affects the
9268 auto-selection method. If the passed file is a video, only the
9269 first frame will be decoded and displayed. Enabling the cover
9270 art track during playback may show a random frame if the source
9271 file is a video. Normally you're not supposed to pass videos to
9272 this option, so this paragraph describes the behavior coinciden‐
9273 tally resulting from implementation details.)
9274 This is a path list option. See List Options for details.
9276 --cover-art-file=<file>
9278 CLI/config file only alias for --cover-art-files-append. Each
9279 use of this option will add a new external file.
9280 --cover-art-auto=<no|exact|fuzzy|all>
9282 Whether to load _external_ cover art automatically. Similar to
9283 --sub-auto and --audio-file-auto. If a video already has tracks
9284 (which are not marked as cover art), external cover art will not
9285 be loaded.
9286 no Don't automatically load cover art.
9288 exact Load the media filename with an image file extension (de‐
9290 fault).
9291 fuzzy Load all cover art containing the media filename.
9293 all Load all images in the current directory.
9295 See --cover-art-files for details about what constitutes cover
9297 art.
9298 See --audio-display how to control display of cover art (this
9300 can be used to disable cover art that is part of the file).
9301 --cover-art-whitelist=<no|yes>
9303 Whether to load filenames in an internal whitelist, such as
9304 cover.jpg, as cover art. If cover-art-auto is set to no, the
9305 whitelisted filenames are never loaded even if this option is
9306 set to yes.
9307 Default: yes.
9309 --autoload-files=<yes|no>
9311 Automatically load/select external files (default: yes).
9312 If set to no, then do not automatically load external files as
9314 specified by --sub-auto, --audio-file-auto and --cover-art-auto.
9315 If external files are forcibly added (like with --sub-files),
9316 they will not be auto-selected.
9317 This does not affect playlist expansion, redirection, or other
9319 loading of referenced files like with ordered chapters.
9320 --record-file=<file>
9322 Deprecated, use --stream-record, or the dump-cache command.
9323 Record the current stream to the given target file. The target
9325 file will always be overwritten without asking.
9326 This was deprecated because it isn't very nice to use. For one,
9328 seeking while this is enabled will be directly reflected in the
9329 output, which was not useful and annoying.
9330 --stream-record=<file>
9332 Write received/read data from the demuxer to the given output
9333 file. The output file will always be overwritten without asking.
9334 The output format is determined by the extension of the output
9335 file.
9336 Switching streams or seeking during recording might result in
9338 recording being stopped and/or broken files. Use with care.
9339 Seeking outside of the demuxer cache will result in "skips" in
9341 the output file, but seeking within the demuxer cache should
9342 not affect recording. One exception is when you seek back far
9343 enough to exceed the forward buffering size, in which case the
9344 cache stops actively reading. This will return in dropped data
9345 if it's a live stream.
9346 If this is set at runtime, the old file is closed, and the new
9348 file is opened. Note that this will write only data that is ap‐
9349 pended at the end of the cache, and the already cached data can‐
9350 not be written. You can try the dump-cache command as an alter‐
9351 native.
9352 External files (--audio-file etc.) are ignored by this, it works
9354 on the "main" file only. Using this with files using ordered
9355 chapters or EDL files will also not work correctly in general.
9356 There are some glitches with this because it uses FFmpeg's
9358 libavformat for writing the output file. For example, it's typi‐
9359 cal that it will only work if the output format is the same as
9360 the input format. This is the case even if it works with the
9361 ffmpeg tool. One reason for this is that ffmpeg and its li‐
9362 braries contain certain hacks and workarounds for these issues,
9363 that are unavailable to outside users.
9364 This replaces --record-file. It is similar to the ancient/re‐
9366 moved --stream-capture/--capture options, and provides better
9367 behavior in most cases (i.e. actually works).
9368 --lavfi-complex=<string>
9370 Set a "complex" libavfilter filter, which means a single filter
9371 graph can take input from multiple source audio and video
9372 tracks. The graph can result in a single audio or video output
9373 (or both).
9374 Currently, the filter graph labels are used to select the par‐
9376 ticipating input tracks and audio/video output. The following
9377 rules apply:
9378 • A label of the form aidN selects audio track N as input (e.g.
9380 aid1).
9381 • A label of the form vidN selects video track N as input.
9383 • A label named ao will be connected to the audio output.
9385 • A label named vo will be connected to the video output.
9387 Each label can be used only once. If you want to use e.g. an au‐
9389 dio stream for multiple filters, you need to use the asplit fil‐
9390 ter. Multiple video or audio outputs are not possible, but you
9391 can use filters to merge them into one.
9392 It's not possible to change the tracks connected to the filter
9394 at runtime, unless you explicitly change the lavfi-complex prop‐
9395 erty and set new track assignments. When the graph is changed,
9396 the track selection is changed according to the used labels as
9397 well.
9398 Other tracks, as long as they're not connected to the filter,
9400 and the corresponding output is not connected to the filter, can
9401 still be freely changed with the normal methods.
9402 Note that the normal filter chains (--af, --vf) are applied be‐
9404 tween the complex graphs (e.g. ao label) and the actual output.
9405 Examples
9407 • --lavfi-complex='[aid1] [aid2] amix [ao]' Play audio track
9409 1 and 2 at the same time.
9410 • --lavfi-complex='[vid1] [vid2] vstack [vo]' Stack video
9412 track 1 and 2 and play them at the same time. Note that
9413 both tracks need to have the same width, or filter initial‐
9414 ization will fail (you can add scale filters before the vs‐
9415 tack filter to fix the size). To load a video track from
9416 another file, you can use --external-file=other.mkv.
9417 • --lavfi-complex='[aid1] asplit [t1] [ao] ; [t1] showvolume
9419 [t2] ; [vid1] [t2] overlay [vo]' Play audio track 1, and
9420 overlay the measured volume for each speaker over video
9421 track 1.
9422 • null:// --lavfi-complex='life [vo]' A libavfilter
9424 source-only filter (Conways' Life Game).
9425 See the FFmpeg libavfilter documentation for details on the
9427 available filters.
9428 --metadata-codepage=<codepage>
9430 Codepage for various input metadata (default: utf-8). This af‐
9431 fects how file tags, chapter titles, etc. are interpreted. You
9432 can for example set this to auto to enable autodetection of the
9433 codepage. (This is not the default because non-UTF-8 codepages
9434 are an obscure fringe use-case.)
9435 See --sub-codepage option on how codepages are specified and
9437 further details regarding autodetection and codepage conversion.
9438 (The underlying code is the same.)
9439 Conversion is not applied to metadata that is updated at run‐
9441 time.
9442
9444 Audio output drivers are interfaces to different audio output facili‐
9445 ties. The syntax is:
9446 --ao=<driver1,driver2,...[,]>
9448 Specify a priority list of audio 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 --ao=help for a list of compiled-in audio output drivers. The
9455 driver --ao=alsa is preferred. --ao=pulse is preferred on systems
9456 where PulseAudio is used. On BSD systems, --ao=oss is preferred.
9457 Available audio output drivers are:
9459 alsa (Linux only)
9461 ALSA audio output driver
9462 See ALSA audio output options for options specific to this AO.
9464 WARNING:
9466 To get multichannel/surround audio, use --audio-chan‐
9467 nels=auto. The default for this option is auto-safe, which
9468 makes this audio output explicitly reject multichannel out‐
9469 put, as there is no way to detect whether a certain channel
9470 layout is actually supported.
9471 You can also try using the upmix plugin. This setup enables
9473 multichannel audio on the default device with automatic up‐
9474 mixing with shared access, so playing stereo and multichannel
9475 audio at the same time will work as expected.
9476 oss OSS audio output driver
9478 jack JACK (Jack Audio Connection Kit) audio output driver.
9480 The following global options are supported by this audio output:
9482 --jack-port=<name>
9484 Connects to the ports with the given name (default: phys‐
9485 ical ports).
9486 --jack-name=<client>
9488 Client name that is passed to JACK (default: mpv). Useful
9489 if you want to have certain connections established auto‐
9490 matically.
9491 --jack-autostart=<yes|no>
9493 Automatically start jackd if necessary (default: dis‐
9494 abled). Note that this tends to be unreliable and will
9495 flood stdout with server messages.
9496 --jack-connect=<yes|no>
9498 Automatically create connections to output ports (de‐
9499 fault: enabled). When enabled, the maximum number of
9500 output channels will be limited to the number of avail‐
9501 able output ports.
9502 --jack-std-channel-layout=<waveext|any>
9504 Select the standard channel layout (default: waveext).
9505 JACK itself has no notion of channel layouts (i.e. as‐
9506 signing which speaker a given channel is supposed to map
9507 to) - it just takes whatever the application outputs, and
9508 reroutes it to whatever the user defines. This means the
9509 user and the application are in charge of dealing with
9510 the channel layout. waveext uses WAVE_FORMAT_EXTENSIBLE
9511 order, which, even though it was defined by Microsoft, is
9512 the standard on many systems. The value any makes JACK
9513 accept whatever comes from the audio filter chain, re‐
9514 gardless of channel layout and without reordering. This
9515 mode is probably not very useful, other than for debug‐
9516 ging or when used with fixed setups.
9517 coreaudio (macOS only)
9519 Native macOS audio output driver using AudioUnits and the Core‐
9520 Audio sound server.
9521 Automatically redirects to coreaudio_exclusive when playing com‐
9523 pressed formats.
9524 The following global options are supported by this audio output:
9526 --coreaudio-change-physical-format=<yes|no>
9528 Change the physical format to one similar to the re‐
9529 quested audio format (default: no). This has the advan‐
9530 tage that multichannel audio output will actually work.
9531 The disadvantage is that it will change the system-wide
9532 audio settings. This is equivalent to changing the Format
9533 setting in the Audio Devices dialog in the Audio MIDI
9534 Setup utility. Note that this does not affect the se‐
9535 lected speaker setup.
9536 --coreaudio-spdif-hack=<yes|no>
9538 Try to pass through AC3/DTS data as PCM. This is useful
9539 for drivers which do not report AC3 support. It converts
9540 the AC3 data to float, and assumes the driver will do the
9541 inverse conversion, which means a typical A/V receiver
9542 will pick it up as compressed IEC framed AC3 stream, ig‐
9543 noring that it's marked as PCM. This disables normal AC3
9544 passthrough (even if the device reports it as supported).
9545 Use with extreme care.
9546 coreaudio_exclusive (macOS only)
9548 Native macOS audio output driver using direct device access and
9549 exclusive mode (bypasses the sound server).
9550 openal OpenAL audio output driver.
9552 --openal-num-buffers=<2-128>
9554 Specify the number of audio buffers to use. Lower values
9555 are better for lower CPU usage. Default: 4.
9556 --openal-num-samples=<256-32768>
9558 Specify the number of complete samples to use for each
9559 buffer. Higher values are better for lower CPU usage. De‐
9560 fault: 8192.
9561 --openal-direct-channels=<yes|no>
9563 Enable OpenAL Soft's direct channel extension when avail‐
9564 able to avoid tinting the sound with ambisonics or HRTF.
9565 Default: yes.
9566 pulse PulseAudio audio output driver
9568 The following global options are supported by this audio output:
9570 --pulse-host=<host>
9572 Specify the host to use. An empty <host> string uses a
9573 local connection, "localhost" uses network transfer (most
9574 likely not what you want).
9575 --pulse-buffer=<1-2000|native>
9577 Set the audio buffer size in milliseconds. A higher value
9578 buffers more data, and has a lower probability of buffer
9579 underruns. A smaller value makes the audio stream react
9580 faster, e.g. to playback speed changes. "native" lets the
9581 sound server determine buffers.
9582 --pulse-latency-hacks=<yes|no>
9584 Enable hacks to workaround PulseAudio timing bugs (de‐
9585 fault: no). If enabled, mpv will do elaborate latency
9586 calculations on its own. If disabled, it will use
9587 PulseAudio automatically updated timing information. Dis‐
9588 abling this might help with e.g. networked audio or some
9589 plugins, while enabling it might help in some unknown
9590 situations (it used to be required to get good behavior
9591 on old PulseAudio versions).
9592 If you have stuttering video when using pulse, try to en‐
9594 able this option. (Or try to update PulseAudio.)
9595 --pulse-allow-suspended=<yes|no>
9597 Allow mpv to use PulseAudio even if the sink is suspended
9598 (default: no). Can be useful if PulseAudio is running as
9599 a bridge to jack and mpv has its sink-input set to the
9600 one jack is using.
9601 pipewire
9603 PipeWire audio output driver
9604 The following global options are supported by this audio output:
9606 --pipewire-buffer=<1-2000|native>
9608 Set the audio buffer size in milliseconds. A higher value
9609 buffers more data, and has a lower probability of buffer
9610 underruns. A smaller value makes the audio stream react
9611 faster, e.g. to playback speed changes. "native" lets the
9612 sound server determine buffers.
9613 --pipewire-remote=<remote>
9615 Specify the PipeWire remote daemon name to connect to via
9616 local UNIX sockets. An empty <remote> string uses the
9617 default remote named pipewire-0.
9618 --pipewire-volume-mode=<channel|global>
9620 Specify if the ao-volume property should apply to the
9621 channel volumes or the global volume. By default the
9622 channel volumes are used.
9623 sdl SDL 1.2+ audio output driver. Should work on any platform sup‐
9625 ported by SDL 1.2, but may require the SDL_AUDIODRIVER environ‐
9626 ment variable to be set appropriately for your system.
9627 NOTE:
9629 This driver is for compatibility with extremely foreign envi‐
9630 ronments, such as systems where none of the other drivers are
9631 available.
9632 The following global options are supported by this audio output:
9634 --sdl-buflen=<length>
9636 Sets the audio buffer length in seconds. Is used only as
9637 a hint by the sound system. Playing a file with -v will
9638 show the requested and obtained exact buffer size. A
9639 value of 0 selects the sound system default.
9640 null Produces no audio output but maintains video playback speed. You
9642 can use --ao=null --ao-null-untimed for benchmarking.
9643 The following global options are supported by this audio output:
9645 --ao-null-untimed
9647 Do not simulate timing of a perfect audio device. This
9648 means audio decoding will go as fast as possible, instead
9649 of timing it to the system clock.
9650 --ao-null-buffer
9652 Simulated buffer length in seconds.
9653 --ao-null-outburst
9655 Simulated chunk size in samples.
9656 --ao-null-speed
9658 Simulated audio playback speed as a multiplier. Usually,
9659 a real audio device will not go exactly as fast as the
9660 system clock. It will deviate just a little, and this op‐
9661 tion helps to simulate this.
9662 --ao-null-latency
9664 Simulated device latency. This is additional to EOF.
9665 --ao-null-broken-eof
9667 Simulate broken audio drivers, which always add the fixed
9668 device latency to the reported audio playback position.
9669 --ao-null-broken-delay
9671 Simulate broken audio drivers, which don't report latency
9672 correctly.
9673 --ao-null-channel-layouts
9675 If not empty, this is a , separated list of channel lay‐
9676 outs the AO allows. This can be used to test channel lay‐
9677 out selection.
9678 --ao-null-format
9680 Force the audio output format the AO will accept. If un‐
9681 set accepts any.
9682 pcm Raw PCM/WAVE file writer audio output
9684 The following global options are supported by this audio output:
9686 --ao-pcm-waveheader=<yes|no>
9688 Include or do not include the WAVE header (default: in‐
9689 cluded). When not included, raw PCM will be generated.
9690 --ao-pcm-file=<filename>
9692 Write the sound to <filename> instead of the default au‐
9693 diodump.wav. If no-waveheader is specified, the default
9694 is audiodump.pcm.
9695 --ao-pcm-append=<yes|no>
9697 Append to the file, instead of overwriting it. Always use
9698 this with the no-waveheader option - with waveheader it's
9699 broken, because it will write a WAVE header every time
9700 the file is opened.
9701 sndio Audio output to the OpenBSD sndio sound system
9703 (Note: only supports mono, stereo, 4.0, 5.1 and 7.1 channel lay‐
9705 outs.)
9706 wasapi Audio output to the Windows Audio Session API.
9708
9710 Video output drivers are interfaces to different video output facili‐
9711 ties. The syntax is:
9712 --vo=<driver1,driver2,...[,]>
9714 Specify a priority list of video output drivers to be used.
9715 If the list has a trailing ,, mpv will fall back on drivers not con‐
9717 tained in the list.
9718 NOTE:
9720 See --vo=help for a list of compiled-in video output drivers.
9721 The recommended output driver is --vo=gpu, which is the default. All
9723 other drivers are for compatibility or special purposes. If the de‐
9724 fault does not work, it will fallback to other drivers (in the same
9725 order as listed by --vo=help).
9726 Available video output drivers are:
9728 gpu General purpose, customizable, GPU-accelerated video output
9730 driver. It supports extended scaling methods, dithering, color
9731 management, custom shaders, HDR, and more.
9732 See GPU renderer options for options specific to this VO.
9734 By default, it tries to use fast and fail-safe settings. Use the
9736 gpu-hq profile to use this driver with defaults set to high
9737 quality rendering. The profile can be applied with --pro‐
9738 file=gpu-hq and its contents can be viewed with --show-pro‐
9739 file=gpu-hq.
9740 This VO abstracts over several possible graphics APIs and win‐
9742 dowing contexts, which can be influenced using the --gpu-api and
9743 --gpu-context options.
9744 Hardware decoding over OpenGL-interop is supported to some de‐
9746 gree. Note that in this mode, some corner case might not be
9747 gracefully handled, and color space conversion and chroma upsam‐
9748 pling is generally in the hand of the hardware decoder APIs.
9749 gpu makes use of FBOs by default. Sometimes you can achieve bet‐
9751 ter quality or performance by changing the --fbo-format option
9752 to rgb16f, rgb32f or rgb. Known problems include Mesa/Intel not
9753 accepting rgb16, Mesa sometimes not being compiled with float
9754 texture support, and some macOS setups being very slow with
9755 rgb16 but fast with rgb32f. If you have problems, you can also
9756 try enabling the --gpu-dumb-mode=yes option.
9757 gpu-next
9759 Experimental video renderer based on libplacebo. This supports
9760 almost the same set of features as --vo=gpu. See GPU renderer
9761 options for a list.
9762 Should generally be faster and higher quality, but some features
9764 may still be missing or misbehave. Expect (and report!) bugs.
9765 See here for a list of known differences and bugs:
9766 https://github.com/mpv-player/mpv/wiki/GPU-Next-vs-GPU
9768 xv (X11 only)
9770 Uses the XVideo extension to enable hardware-accelerated dis‐
9771 play. This is the most compatible VO on X, but may be low-qual‐
9772 ity, and has issues with OSD and subtitle display.
9773 NOTE:
9775 This driver is for compatibility with old systems.
9776 The following global options are supported by this video output:
9778 --xv-adaptor=<number>
9780 Select a specific XVideo adapter (check xvinfo results).
9781 --xv-port=<number>
9783 Select a specific XVideo port.
9784 --xv-ck=<cur|use|set>
9786 Select the source from which the color key is taken (de‐
9787 fault: cur).
9788 cur The default takes the color key currently set in
9790 Xv.
9791 use Use but do not set the color key from mpv (use the
9793 --colorkey option to change it).
9794 set Same as use but also sets the supplied color key.
9796 --xv-ck-method=<none|man|bg|auto>
9798 Sets the color key drawing method (default: man).
9799 none Disables color-keying.
9801 man Draw the color key manually (reduces flicker in
9803 some cases).
9804 bg Set the color key as window background.
9806 auto Let Xv draw the color key.
9808 --xv-colorkey=<number>
9810 Changes the color key to an RGB value of your choice.
9811 0x000000 is black and 0xffffff is white.
9812 --xv-buffers=<number>
9814 Number of image buffers to use for the internal ring‐
9815 buffer (default: 2). Increasing this will use more mem‐
9816 ory, but might help with the X server not responding
9817 quickly enough if video FPS is close to or higher than
9818 the display refresh rate.
9819 x11 (X11 only)
9821 Shared memory video output driver without hardware acceleration
9822 that works whenever X11 is present.
9823 Since mpv 0.30.0, you may need to use --profile=sw-fast to get
9825 decent performance.
9826 NOTE:
9828 This is a fallback only, and should not be normally used.
9829 vdpau (X11 only)
9831 Uses the VDPAU interface to display and optionally also decode
9832 video. Hardware decoding is used with --hwdec=vdpau. Note that
9833 there is absolutely no reason to use this, other than compati‐
9834 bility. We strongly recommend that you use --vo=gpu with
9835 --hwdec=nvdec instead.
9836 NOTE:
9838 Earlier versions of mpv (and MPlayer, mplayer2) provided
9839 sub-options to tune vdpau post-processing, like deint,
9840 sharpen, denoise, chroma-deint, pullup, hqscaling. These
9841 sub-options are deprecated, and you should use the vdpaupp
9842 video filter instead.
9843 The following global options are supported by this video output:
9845 --vo-vdpau-sharpen=<-1-1>
9847 (Deprecated. See note about vdpaupp.)
9848 For positive values, apply a sharpening algorithm to the
9850 video, for negative values a blurring algorithm (default:
9851 0).
9852 --vo-vdpau-denoise=<0-1>
9854 (Deprecated. See note about vdpaupp.)
9855 Apply a noise reduction algorithm to the video (default:
9857 0; no noise reduction).
9858 --vo-vdpau-chroma-deint
9860 (Deprecated. See note about vdpaupp.)
9861 Makes temporal deinterlacers operate both on luma and
9863 chroma (default). Use no-chroma-deint to solely use luma
9864 and speed up advanced deinterlacing. Useful with slow
9865 video memory.
9866 --vo-vdpau-pullup
9868 (Deprecated. See note about vdpaupp.)
9869 Try to apply inverse telecine, needs motion adaptive tem‐
9871 poral deinterlacing.
9872 --vo-vdpau-hqscaling=<0-9>
9874 (Deprecated. See note about vdpaupp.)
9875 0 Use default VDPAU scaling (default).
9877 1-9 Apply high quality VDPAU scaling (needs capable
9879 hardware).
9880 --vo-vdpau-fps=<number>
9882 Override autodetected display refresh rate value (the
9883 value is needed for framedrop to allow video playback
9884 rates higher than display refresh rate, and for
9885 vsync-aware frame timing adjustments). Default 0 means
9886 use autodetected value. A positive value is interpreted
9887 as a refresh rate in Hz and overrides the autodetected
9888 value. A negative value disables all timing adjustment
9889 and framedrop logic.
9890 --vo-vdpau-composite-detect
9892 NVIDIA's current VDPAU implementation behaves somewhat
9893 differently under a compositing window manager and does
9894 not give accurate frame timing information. With this op‐
9895 tion enabled, the player tries to detect whether a com‐
9896 positing window manager is active. If one is detected,
9897 the player disables timing adjustments as if the user had
9898 specified fps=-1 (as they would be based on incorrect in‐
9899 put). This means timing is somewhat less accurate than
9900 without compositing, but with the composited mode behav‐
9901 ior of the NVIDIA driver, there is no hard playback speed
9902 limit even without the disabled logic. Enabled by de‐
9903 fault, use --vo-vdpau-composite-detect=no to disable.
9904 --vo-vdpau-queuetime-windowed=<number> and queuetime-fs=<number>
9906 Use VDPAU's presentation queue functionality to queue fu‐
9907 ture video frame changes at most this many milliseconds
9908 in advance (default: 50). See below for additional in‐
9909 formation.
9910 --vo-vdpau-output-surfaces=<2-15>
9912 Allocate this many output surfaces to display video
9913 frames (default: 3). See below for additional informa‐
9914 tion.
9915 --vo-vdpau-colorkey=<#RRGGBB|#AARRGGBB>
9917 Set the VDPAU presentation queue background color, which
9918 in practice is the colorkey used if VDPAU operates in
9919 overlay mode (default: #020507, some shade of black). If
9920 the alpha component of this value is 0, the default VDPAU
9921 colorkey will be used instead (which is usually green).
9922 --vo-vdpau-force-yuv
9924 Never accept RGBA input. This means mpv will insert a
9925 filter to convert to a YUV format before the VO. Some‐
9926 times useful to force availability of certain YUV-only
9927 features, like video equalizer or deinterlacing.
9928 Using the VDPAU frame queuing functionality controlled by the
9930 queuetime options makes mpv's frame flip timing less sensitive
9931 to system CPU load and allows mpv to start decoding the next
9932 frame(s) slightly earlier, which can reduce jitter caused by in‐
9933 dividual slow-to-decode frames. However, the NVIDIA graphics
9934 drivers can make other window behavior such as window moves
9935 choppy if VDPAU is using the blit queue (mainly happens if you
9936 have the composite extension enabled) and this feature is ac‐
9937 tive. If this happens on your system and it bothers you then you
9938 can set the queuetime value to 0 to disable this feature. The
9939 settings to use in windowed and fullscreen mode are separate be‐
9940 cause there should be no reason to disable this for fullscreen
9941 mode (as the driver issue should not affect the video itself).
9942 You can queue more frames ahead by increasing the queuetime val‐
9944 ues and the output_surfaces count (to ensure enough surfaces to
9945 buffer video for a certain time ahead you need at least as many
9946 surfaces as the video has frames during that time, plus two).
9947 This could help make video smoother in some cases. The main
9948 downsides are increased video RAM requirements for the surfaces
9949 and laggier display response to user commands (display changes
9950 only become visible some time after they're queued). The graph‐
9951 ics driver implementation may also have limits on the length of
9952 maximum queuing time or number of queued surfaces that work well
9953 or at all.
9954 direct3d (Windows only)
9956 Video output driver that uses the Direct3D interface.
9957 NOTE:
9959 This driver is for compatibility with systems that don't pro‐
9960 vide proper OpenGL drivers, and where ANGLE does not perform
9961 well.
9962 The following global options are supported by this video output:
9964 --vo-direct3d-disable-texture-align
9966 Normally texture sizes are always aligned to 16. With
9967 this option enabled, the video texture will always have
9968 exactly the same size as the video itself.
9969 Debug options. These might be incorrect, might be removed in the
9971 future, might crash, might cause slow downs, etc. Contact the
9972 developers if you actually need any of these for performance or
9973 proper operation.
9974 --vo-direct3d-force-power-of-2
9976 Always force textures to power of 2, even if the device
9977 reports non-power-of-2 texture sizes as supported.
9978 --vo-direct3d-texture-memory=<mode>
9980 Only affects operation with shaders/texturing enabled,
9981 and (E)OSD. Possible values:
9982 default (default)
9984 Use D3DPOOL_DEFAULT, with a D3DPOOL_SYSTEMMEM tex‐
9985 ture for locking. If the driver supports D3DDEV‐
9986 CAPS_TEXTURESYSTEMMEMORY, D3DPOOL_SYSTEMMEM is
9987 used directly.
9988 default-pool
9990 Use D3DPOOL_DEFAULT. (Like default, but never use
9991 a shadow-texture.)
9992 default-pool-shadow
9994 Use D3DPOOL_DEFAULT, with a D3DPOOL_SYSTEMMEM tex‐
9995 ture for locking. (Like default, but always force
9996 the shadow-texture.)
9997 managed
9999 Use D3DPOOL_MANAGED.
10000 scratch
10002 Use D3DPOOL_SCRATCH, with a D3DPOOL_SYSTEMMEM tex‐
10003 ture for locking.
10004 --vo-direct3d-swap-discard
10006 Use D3DSWAPEFFECT_DISCARD, which might be faster. Might
10007 be slower too, as it must(?) clear every frame.
10008 --vo-direct3d-exact-backbuffer
10010 Always resize the backbuffer to window size.
10011 sdl SDL 2.0+ Render video output driver, depending on system with or
10013 without hardware acceleration. Should work on all platforms sup‐
10014 ported by SDL 2.0. For tuning, refer to your copy of the file
10015 SDL_hints.h.
10016 NOTE:
10018 This driver is for compatibility with systems that don't pro‐
10019 vide proper graphics drivers.
10020 The following global options are supported by this video output:
10022 --sdl-sw
10024 Continue even if a software renderer is detected.
10025 --sdl-switch-mode
10027 Instruct SDL to switch the monitor video mode when going
10028 fullscreen.
10029 dmabuf-wayland
10031 Experimental Wayland output driver designed for use with either
10032 drm stateless or VA API hardware decoding. The driver is de‐
10033 signed to avoid any GPU to CPU copies, and to perform scaling
10034 and color space conversion using fixed-function hardware, if
10035 available, rather than GPU shaders. This frees up GPU resources
10036 for other tasks. It is highly recommended to use this VO with
10037 the appropriate --hwdec option such as auto-safe. It can still
10038 work in some circumstances without --hwdec due to mpv's internal
10039 conversion filters, but this is not recommended as it's a need‐
10040 less extra step. Correct output depends on support from your
10041 GPU, drivers, and compositor. Weston and wlroots-based composi‐
10042 tors like Sway and Intel GPUs are known to generally work.
10043 vaapi Intel VA API video output driver with support for hardware de‐
10045 coding. Note that there is absolutely no reason to use this,
10046 other than compatibility. This is low quality, and has issues
10047 with OSD. We strongly recommend that you use --vo=gpu with
10048 --hwdec=vaapi instead.
10049 The following global options are supported by this video output:
10051 --vo-vaapi-scaling=<algorithm>
10053 default
10055 Driver default (mpv default as well).
10056 fast Fast, but low quality.
10058 hq Unspecified driver dependent high-quality scaling,
10060 slow.
10061 nla non-linear anamorphic scaling
10063 --vo-vaapi-deint-mode=<mode>
10065 Select deinterlacing algorithm. Note that by default
10066 deinterlacing is initially always off, and needs to be
10067 enabled with the d key (default key binding for cycle
10068 deinterlace).
10069 This option doesn't apply if libva supports video post
10071 processing (vpp). In this case, the default for
10072 deint-mode is no, and enabling deinterlacing via user in‐
10073 teraction using the methods mentioned above actually in‐
10074 serts the vavpp video filter. If vpp is not actually sup‐
10075 ported with the libva backend in use, you can use this
10076 option to forcibly enable VO based deinterlacing.
10077 no Don't allow deinterlacing (default for newer
10079 libva).
10080 first-field
10082 Show only first field.
10083 bob bob deinterlacing (default for older libva).
10085 --vo-vaapi-scaled-osd=<yes|no>
10087 If enabled, then the OSD is rendered at video resolution
10088 and scaled to display resolution. By default, this is
10089 disabled, and the OSD is rendered at display resolution
10090 if the driver supports it.
10091 null Produces no video output. Useful for benchmarking.
10093 Usually, it's better to disable video with --no-video instead.
10095 The following global options are supported by this video output:
10097 --vo-null-fps=<value>
10099 Simulate display FPS. This artificially limits how many
10100 frames the VO accepts per second.
10101 caca Color ASCII art video output driver that works on a text con‐
10103 sole.
10104 NOTE:
10106 This driver is a joke.
10107 tct Color Unicode art video output driver that works on a text con‐
10109 sole. By default depends on support of true color by modern
10110 terminals to display the images at full color range, but
10111 256-colors output is also supported (see below). On Windows it
10112 requires an ansi terminal such as mintty.
10113 Since mpv 0.30.0, you may need to use --profile=sw-fast to get
10115 decent performance.
10116 Note: the TCT image output is not synchronized with other termi‐
10118 nal output from mpv, which can lead to broken images. The op‐
10119 tions --no-terminal or --really-quiet can help with that.
10120 --vo-tct-algo=<algo>
10122 Select how to write the pixels to the terminal.
10123 half-blocks
10125 Uses unicode LOWER HALF BLOCK character to achieve
10126 higher vertical resolution. (Default.)
10127 plain Uses spaces. Causes vertical resolution to drop
10129 twofolds, but in theory works in more places.
10130 --vo-tct-width=<width> --vo-tct-height=<height>
10132 Assume the terminal has the specified character width
10133 and/or height. These default to 80x25 if the terminal
10134 size cannot be determined.
10135 --vo-tct-256=<yes|no> (default: no)
10137 Use 256 colors - for terminals which don't support true
10138 color.
10139 kitty Graphical output for the terminal, using the kitty graphics pro‐
10141 tocol. Tested with kitty and Konsole.
10142 You may need to use --profile=sw-fast to get decent performance.
10144 Kitty size and alignment options:
10146 --vo-kitty-cols=<columns>, --vo-kitty-rows=<rows> (default: 0)
10148 Specify the terminal size in character cells, otherwise
10149 (0) read it from the terminal, or fall back to 80x25.
10150 --vo-kitty-width=<width>, --vo-kitty-height=<height> (default:
10152 0)
10153 Specify the available size in pixels, otherwise (0) read
10154 it from the terminal, or fall back to 320x240.
10155 --vo-kitty-left=<col>, --vo-kitty-top=<row> (default: 0)
10157 Specify the position in character cells where the image
10158 starts (1 is the first column or row). If 0 (default)
10159 then try to automatically determine it according to the
10160 other values and the image aspect ratio and zoom.
10161 --vo-kitty-config-clear=<yes|no> (default: yes)
10163 Whether or not to clear the terminal whenever the output
10164 is reconfigured (e.g. when video size changes).
10165 --vo-kitty-alt-screen=<yes|no> (default: yes)
10167 Whether or not to use the alternate screen buffer and re‐
10168 turn the terminal to its previous state on exit. When set
10169 to no, the last kitty image stays on screen after quit,
10170 with the cursor following it.
10171 --vo-kitty-use-shm=<yes|no> (default: no)
10173 Use shared memory objects to transfer image data to the
10174 terminal. This is much faster than sending the data as
10175 escape codes, but is not supported by as many terminals.
10176 It also only works on the local machine and not via e.g.
10177 SSH connections.
10178 This option is not implemented on Windows.
10180 sixel Graphical output for the terminal, using sixels. Tested with ml‐
10182 term and xterm.
10183 Note: the Sixel image output is not synchronized with other ter‐
10185 minal output from mpv, which can lead to broken images. The op‐
10186 tion --really-quiet can help with that, and is recommended. On
10187 some platforms, using the --vo-sixel-buffered option may work as
10188 well.
10189 You may need to use --profile=sw-fast to get decent performance.
10191 Note: at the time of writing, xterm does not enable sixel by de‐
10193 fault - launching it as xterm -ti 340 is one way to enable it.
10194 Also, xterm does not display images bigger than 1000x1000 pixels
10195 by default.
10196 To render and align sixel images correctly, mpv needs to know
10198 the terminal size both in cells and in pixels. By default it
10199 tries to use values which the terminal reports, however, due to
10200 differences between terminals this is an error-prone process
10201 which cannot be automated with certainty - some terminals report
10202 the size in pixels including the padding - e.g. xterm, while
10203 others report the actual usable number of pixels - like mlterm.
10204 Additionally, they may behave differently when maximized or in
10205 fullscreen, and mpv cannot detect this state using standard
10206 methods.
10207 Sixel size and alignment options:
10209 --vo-sixel-cols=<columns>, --vo-sixel-rows=<rows> (default: 0)
10211 Specify the terminal size in character cells, otherwise
10212 (0) read it from the terminal, or fall back to 80x25.
10213 Note that mpv doesn't use the the last row with sixel be‐
10214 cause this seems to result in scrolling.
10215 --vo-sixel-width=<width>, --vo-sixel-height=<height> (default:
10217 0)
10218 Specify the available size in pixels, otherwise (0) read
10219 it from the terminal, or fall back to 320x240. Other than
10220 excluding the last line, the height is also further
10221 rounded down to a multiple of 6 (sixel unit height) to
10222 avoid overflowing below the designated size.
10223 --vo-sixel-left=<col>, --vo-sixel-top=<row> (default: 0)
10225 Specify the position in character cells where the image
10226 starts (1 is the first column or row). If 0 (default)
10227 then try to automatically determine it according to the
10228 other values and the image aspect ratio and zoom.
10229 --vo-sixel-pad-x=<pad_x>, --vo-sixel-pad-y=<pad_y> (default: -1)
10231 Used only when mpv reads the size in pixels from the ter‐
10232 minal. Specify the number of padding pixels (on one
10233 side) which are included at the size which the terminal
10234 reports. If -1 (default) then the number of pixels is
10235 rounded down to a multiple of number of cells (per axis),
10236 to take into account padding at the report - this only
10237 works correctly when the overall padding per axis is
10238 smaller than the number of cells.
10239 --vo-sixel-config-clear=<yes|no> (default: yes)
10241 Whether or not to clear the terminal whenever the output
10242 is reconfigured (e.g. when video size changes).
10243 --vo-sixel-alt-screen=<yes|no> (default: yes)
10245 Whether or not to use the alternate screen buffer and re‐
10246 turn the terminal to its previous state on exit. When set
10247 to no, the last sixel image stays on screen after quit,
10248 with the cursor following it.
10249 --vo-sixel-exit-clear is a deprecated alias for this op‐
10251 tion and may be removed in the future.
10252 --vo-sixel-buffered=<yes|no> (default: no)
10254 Buffers the full output sequence before writing it to the
10255 terminal. On POSIX platforms, this can help prevent in‐
10256 terruption (including from other applications) and thus
10257 broken images, but may come at a performance cost with
10258 some terminals and is subject to implementation details.
10259 Sixel image quality options:
10261 --vo-sixel-dither=<algo>
10263 Selects the dither algorithm which libsixel should apply.
10264 Can be one of the below list as per libsixel's documenta‐
10265 tion.
10266 auto (Default)
10268 Let libsixel choose the dithering method.
10269 none Don't diffuse
10271 atkinson
10273 Diffuse with Bill Atkinson's method.
10274 fs Diffuse with Floyd-Steinberg method
10276 jajuni Diffuse with Jarvis, Judice & Ninke method
10278 stucki Diffuse with Stucki's method
10280 burkes Diffuse with Burkes' method
10282 arithmetic
10284 Positionally stable arithmetic dither
10285 xor Positionally stable arithmetic xor based dither
10287 --vo-sixel-fixedpalette=<yes|no> (default: yes)
10289 Use libsixel's built-in static palette using the XTERM256
10290 profile for dither. Fixed palette uses 256 colors for
10291 dithering. Note that using no (at the time of writing)
10292 will slow down xterm.
10293 --vo-sixel-reqcolors=<colors> (default: 256)
10295 Has no effect with fixed palette. Set up libsixel to use
10296 required number of colors for dynamic palette. This value
10297 depends on the terminal emulator as well. Xterm supports
10298 256 colors. Can set this to a lower value for faster per‐
10299 formance.
10300 --vo-sixel-threshold=<threshold> (default: -1)
10302 Has no effect with fixed palette. Defines the threshold
10303 to change the palette - as percentage of the number of
10304 colors, e.g. 20 will change the palette when the number
10305 of colors changed by 20%. It's a simple measure to reduce
10306 the number of palette changes, because it can be slow in
10307 some terminals (xterm). The default (-1) will choose a
10308 palette on every frame and will have better quality.
10309 image Output each frame into an image file in the current directory.
10311 Each file takes the frame number padded with leading zeros as
10312 name.
10313 The following global options are supported by this video output:
10315 --vo-image-format=<format>
10317 Select the image file format.
10318 jpg JPEG files, extension .jpg. (Default.)
10320 jpeg JPEG files, extension .jpeg.
10322 png PNG files.
10324 webp WebP files.
10326 --vo-image-png-compression=<0-9>
10328 PNG compression factor (speed vs. file size tradeoff)
10329 (default: 7)
10330 --vo-image-png-filter=<0-5>
10332 Filter applied prior to PNG compression (0 = none; 1 =
10333 sub; 2 = up; 3 = average; 4 = Paeth; 5 = mixed) (default:
10334 5)
10335 --vo-image-jpeg-quality=<0-100>
10337 JPEG quality factor (default: 90)
10338 --vo-image-jpeg-optimize=<0-100>
10340 JPEG optimization factor (default: 100)
10341 --vo-image-webp-lossless=<yes|no>
10343 Enable writing lossless WebP files (default: no)
10344 --vo-image-webp-quality=<0-100>
10346 WebP quality (default: 75)
10347 --vo-image-webp-compression=<0-6>
10349 WebP compression factor (default: 4)
10350 --vo-image-outdir=<dirname>
10352 Specify the directory to save the image files to (de‐
10353 fault: ./).
10354 libmpv For use with libmpv direct embedding. As a special case, on
10356 macOS it is used like a normal VO within mpv (cocoa-cb). Other‐
10357 wise useless in any other contexts. (See <mpv/render.h>.)
10358 This also supports many of the options the gpu VO has, depending
10360 on the backend.
10361 rpi (Raspberry Pi)
10363 Native video output on the Raspberry Pi using the MMAL API.
10364 This is deprecated. Use --vo=gpu instead, which is the default
10366 and provides the same functionality. The rpi VO will be removed
10367 in mpv 0.23.0. Its functionality was folded into --vo=gpu, which
10368 now uses RPI hardware decoding by treating it as a hardware
10369 overlay (without applying GL filtering). Also to be changed in
10370 0.23.0: the --fs flag will be reset to "no" by default (like on
10371 the other platforms).
10372 The following deprecated global options are supported by this
10374 video output:
10375 --rpi-display=<number>
10377 Select the display number on which the video overlay
10378 should be shown (default: 0).
10379 --rpi-layer=<number>
10381 Select the dispmanx layer on which the video overlay
10382 should be shown (default: -10). Note that mpv will also
10383 use the 2 layers above the selected layer, to handle the
10384 window background and OSD. Actual video rendering will
10385 happen on the layer above the selected layer.
10386 --rpi-background=<yes|no>
10388 Whether to render a black background behind the video
10389 (default: no). Normally it's better to kill the console
10390 framebuffer instead, which gives better performance.
10391 --rpi-osd=<yes|no>
10393 Enabled by default. If disabled with no, no OSD layer is
10394 created. This also means there will be no subtitles ren‐
10395 dered.
10396 drm (Direct Rendering Manager)
10398 Video output driver using Kernel Mode Setting / Direct Rendering
10399 Manager. Should be used when one doesn't want to install
10400 full-blown graphical environment (e.g. no X). Does not support
10401 hardware acceleration (if you need this, check the drm backend
10402 for gpu VO).
10403 Since mpv 0.30.0, you may need to use --profile=sw-fast to get
10405 decent performance.
10406 The following global options are supported by this video output:
10408 --drm-connector=[<gpu_number>.]<name>
10410 Select the connector to use (usually this is a monitor.)
10411 If <name> is empty or auto, mpv renders the output on the
10412 first available connector. Use --drm-connector=help to
10413 get a list of available connectors. The <gpu_number> ar‐
10414 gument can be used to disambiguate multiple graphic
10415 cards, but is deprecated in favor of --drm-device. (de‐
10416 fault: empty)
10417 --drm-device=<path>
10419 Select the DRM device file to use. If specified this
10420 overrides automatic card selection and any card number
10421 specified --drm-connector. (default: empty)
10422 --drm-mode=<preferred|highest|N|WxH[@R]>
10424 Mode to use (resolution and frame rate). Possible val‐
10425 ues:
10426 preferred
10428 Use the preferred mode for the screen on the se‐
10429 lected connector. (default)
10430 highest
10432 Use the mode with the highest resolution available
10433 on the selected connector.
10434 N Select mode by index.
10436 WxH[@R]
10438 Specify mode by width, height, and optionally re‐
10439 fresh rate. In case several modes match, selects
10440 the mode that comes first in the EDID list of
10441 modes.
10442 Use --drm-mode=help to get a list of available modes for
10444 all active connectors.
10445 --drm-draw-plane=<primary|overlay|N>
10447 Select the DRM plane to which video and OSD is drawn to,
10448 under normal circumstances. The plane can be specified as
10449 primary, which will pick the first applicable primary
10450 plane; overlay, which will pick the first applicable
10451 overlay plane; or by index. The index is zero based, and
10452 related to the CRTC. (default: primary)
10453 When using this option with the drmprime-overlay hwdec
10455 interop, only the OSD is rendered to this plane.
10456 --drm-drmprime-video-plane=<primary|overlay|N>
10458 Select the DRM plane to use for video with the drm‐
10459 prime-overlay hwdec interop (used by e.g. the rkmpp hwdec
10460 on RockChip SoCs, and v4l2 hwdec:s on various other
10461 SoC:s). The plane is unused otherwise. This option ac‐
10462 cepts the same values as --drm-draw-plane. (default:
10463 overlay)
10464 To be able to successfully play 4K video on various SoCs
10466 you might need to set --drm-draw-plane=overlay --drm-drm‐
10467 prime-video-plane=primary and setting --drm-draw-sur‐
10468 face-size=1920x1080, to render the OSD at a lower resolu‐
10469 tion (the video when handled by the hwdec will be on the
10470 drmprime-video plane and at full 4K resolution)
10471 --drm-format=<xrgb8888|xrgb2101010>
10473 Select the DRM format to use (default: xrgb8888). This
10474 allows you to choose the bit depth of the DRM mode.
10475 xrgb8888 is your usual 24 bit per pixel/8 bits per chan‐
10476 nel packed RGB format with 8 bits of padding.
10477 xrgb2101010 is a packed 30 bits per pixel/10 bits per
10478 channel packed RGB format with 2 bits of padding.
10479 There are cases when xrgb2101010 will work with the drm
10481 VO, but not with the drm backend for the gpu VO. This is
10482 because with the gpu VO, in addition to requiring support
10483 in your DRM driver, requires support for xrgb2101010 in
10484 your EGL driver
10485 --drm-draw-surface-size=<[WxH]>
10487 Sets the size of the surface used on the draw plane. The
10488 surface will then be upscaled to the current screen reso‐
10489 lution. This option can be useful when used together with
10490 the drmprime-overlay hwdec interop at high resolutions,
10491 as it allows scaling the draw plane (which in this case
10492 only handles the OSD) down to a size the GPU can handle.
10493 When used without the drmprime-overlay hwdec interop this
10495 option will just cause the video to get rendered at a
10496 different resolution and then scaled to screen size.
10497 (default: display resolution)
10499 --drm-vrr-enabled=<no|yes|auto>
10501 Toggle use of Variable Refresh Rate (VRR), aka Freesync
10502 or Adaptive Sync on compatible systems. VRR allows for
10503 the display to be refreshed at any rate within a range
10504 (usually ~40Hz-60Hz for 60Hz displays). This can help
10505 with playback of 24/25/50fps content. Support depends on
10506 the use of a compatible monitor, GPU, and a sufficiently
10507 new kernel with drivers that support the feature.
10508 no Do not attempt to enable VRR. (default)
10510 yes Attempt to enable VRR, whether the capability is
10512 reported or not.
10513 auto Attempt to enable VRR if support is reported.
10515 mediacodec_embed (Android)
10517 Renders IMGFMT_MEDIACODEC frames directly to an an‐
10518 droid.view.Surface. Requires --hwdec=mediacodec for hardware
10519 decoding, along with --vo=mediacodec_embed and
10520 --wid=(intptr_t)(*android.view.Surface).
10521 Since this video output driver uses native decoding and render‐
10523 ing routines, many of mpv's features (subtitle rendering,
10524 OSD/OSC, video filters, etc) are not available with this driver.
10525 To use hardware decoding with --vo=gpu instead, use --hwdec=me‐
10527 diacodec or mediacodec-copy along with --gpu-context=android.
10528 wlshm (Wayland only)
10530 Shared memory video output driver without hardware acceleration
10531 that works whenever Wayland is present.
10532 Since mpv 0.30.0, you may need to use --profile=sw-fast to get
10534 decent performance.
10535 NOTE:
10537 This is a fallback only, and should not be normally used.
10538
10540 Audio filters allow you to modify the audio stream and its properties.
10541 The syntax is:
10542 --af=...
10544 Setup a chain of audio filters. See --vf (VIDEO FILTERS) for the
10545 full syntax.
10546 NOTE:
10548 To get a full list of available audio filters, see --af=help.
10549 Also, keep in mind that most actual filters are available via the
10551 lavfi wrapper, which gives you access to most of libavfilter's fil‐
10552 ters. This includes all filters that have been ported from MPlayer
10553 to libavfilter.
10554 The --vf description describes how libavfilter can be used and how
10556 to workaround deprecated mpv filters.
10557 See --vf group of options for info on how --af-defaults, --af-add,
10559 --af-pre, --af-del, --af-clr, and possibly others work.
10560 Available filters are:
10562 lavcac3enc[=options]
10564 Encode multi-channel audio to AC-3 at runtime using libavcodec.
10565 Supports 16-bit native-endian input format, maximum 6 channels.
10566 The output is big-endian when outputting a raw AC-3 stream, na‐
10567 tive-endian when outputting to S/PDIF. If the input sample rate
10568 is not 48 kHz, 44.1 kHz or 32 kHz, it will be resampled to 48
10569 kHz.
10570 tospdif=<yes|no>
10572 Output raw AC-3 stream if no, output to S/PDIF for
10573 pass-through if yes (default).
10574 bitrate=<rate>
10576 The bitrate use for the AC-3 stream. Set it to 384 to get
10577 384 kbps.
10578 The default is 640. Some receivers might not be able to
10580 handle this.
10581 Valid values: 32, 40, 48, 56, 64, 80, 96, 112, 128, 160,
10583 192, 224, 256, 320, 384, 448, 512, 576, 640.
10584 The special value auto selects a default bitrate based on
10586 the input channel number:
10587 1ch 96
10589 2ch 192
10591 3ch 224
10593 4ch 384
10595 5ch 448
10597 6ch 448
10599 minch=<n>
10601 If the input channel number is less than <minch>, the
10602 filter will detach itself (default: 3).
10603 encoder=<name>
10605 Select the libavcodec encoder used. Currently, this
10606 should be an AC-3 encoder, and using another codec will
10607 fail horribly.
10608 format=format:srate:channels:out-srate:out-channels
10610 Does not do any format conversion itself. Rather, it may cause
10611 the filter system to insert necessary conversion filters before
10612 or after this filter if needed. It is primarily useful for con‐
10613 trolling the audio format going into other filters. To specify
10614 the format for audio output, see --audio-format, --audio-sam‐
10615 plerate, and --audio-channels. This filter is able to force a
10616 particular format, whereas --audio-* may be overridden by the ao
10617 based on output compatibility.
10618 All parameters are optional. The first 3 parameters restrict
10620 what the filter accepts as input. They will therefore cause con‐
10621 version filters to be inserted before this one. The out- param‐
10622 eters tell the filters or audio outputs following this filter
10623 how to interpret the data without actually doing a conversion.
10624 Setting these will probably just break things unless you really
10625 know you want this for some reason, such as testing or dealing
10626 with broken media.
10627 <format>
10629 Force conversion to this format. Use --af=format=for‐
10630 mat=help to get a list of valid formats.
10631 <srate>
10633 Force conversion to a specific sample rate. The rate is
10634 an integer, 48000 for example.
10635 <channels>
10637 Force mixing to a specific channel layout. See --au‐
10638 dio-channels option for possible values.
10639 <out-srate>
10641 <out-channels>
10643 NOTE: this filter used to be named force. The old format filter
10645 used to do conversion itself, unlike this one which lets the
10646 filter system handle the conversion.
10647 scaletempo[=option1:option2:...]
10649 Scales audio tempo without altering pitch, optionally synced to
10650 playback speed (default).
10651 This works by playing 'stride' ms of audio at normal speed then
10653 consuming 'stride*scale' ms of input audio. It pieces the
10654 strides together by blending 'overlap'% of stride with audio
10655 following the previous stride. It optionally performs a short
10656 statistical analysis on the next 'search' ms of audio to deter‐
10657 mine the best overlap position.
10658 scale=<amount>
10660 Nominal amount to scale tempo. Scales this amount in ad‐
10661 dition to speed. (default: 1.0)
10662 stride=<amount>
10664 Length in milliseconds to output each stride. Too high of
10665 a value will cause noticeable skips at high scale amounts
10666 and an echo at low scale amounts. Very low values will
10667 alter pitch. Increasing improves performance. (default:
10668 60)
10669 overlap=<percent>
10671 Percentage of stride to overlap. Decreasing improves per‐
10672 formance. (default: .20)
10673 search=<amount>
10675 Length in milliseconds to search for best overlap posi‐
10676 tion. Decreasing improves performance greatly. On slow
10677 systems, you will probably want to set this very low.
10678 (default: 14)
10679 speed=<tempo|pitch|both|none>
10681 Set response to speed change.
10682 tempo Scale tempo in sync with speed (default).
10684 pitch Reverses effect of filter. Scales pitch without
10686 altering tempo. Add this to your input.conf to
10687 step by musical semi-tones:
10688 [ multiply speed 0.9438743126816935
10690 ] multiply speed 1.059463094352953
10691 WARNING:
10693 Loses sync with video.
10694 both Scale both tempo and pitch.
10696 none Ignore speed changes.
10698 Examples
10700 mpv --af=scaletempo --speed=1.2 media.ogg
10702 Would play media at 1.2x normal speed, with audio at
10703 normal pitch. Changing playback speed would change au‐
10704 dio tempo to match.
10705 mpv --af=scaletempo=scale=1.2:speed=none --speed=1.2 me‐
10707 dia.ogg
10708 Would play media at 1.2x normal speed, with audio at
10709 normal pitch, but changing playback speed would have
10710 no effect on audio tempo.
10711 mpv --af=scaletempo=stride=30:overlap=.50:search=10 media.ogg
10713 Would tweak the quality and performance parameters.
10714 mpv --af=scaletempo=scale=1.2:speed=pitch audio.ogg
10716 Would play media at 1.2x normal speed, with audio at
10717 normal pitch. Changing playback speed would change
10718 pitch, leaving audio tempo at 1.2x.
10719 scaletempo2[=option1:option2:...]
10721 Scales audio tempo without altering pitch. The algorithm is
10722 ported from chromium and uses the Waveform Similarity Over‐
10723 lap-and-add (WSOLA) method. It seems to achieve a higher audio
10724 quality than scaletempo and rubberband.
10725 By default, the search-interval and window-size parameters have
10727 the same values as in chromium.
10728 min-speed=<speed>
10730 Mute audio if the playback speed is below <speed>. (de‐
10731 fault: 0.25)
10732 max-speed=<speed>
10734 Mute audio if the playback speed is above <speed> and
10735 <speed> != 0. (default: 4.0)
10736 search-interval=<amount>
10738 Length in milliseconds to search for best overlap posi‐
10739 tion. (default: 30)
10740 window-size=<amount>
10742 Length in milliseconds of the overlap-and-add window.
10743 (default: 20)
10744 rubberband
10746 High quality pitch correction with librubberband. This can be
10747 used in place of scaletempo, and will be used to adjust audio
10748 pitch when playing at speed different from normal. It can also
10749 be used to adjust audio pitch without changing playback speed.
10750 <pitch-scale>
10752 Sets the pitch scaling factor. Frequencies are multiplied
10753 by this value.
10754 This filter has a number of additional sub-options. You can list
10756 them with mpv --af=rubberband=help. This will also show the de‐
10757 fault values for each option. The options are not documented
10758 here, because they are merely passed to librubberband. Look at
10759 the librubberband documentation to learn what each option does:
10760 https://breakfastquay.com/rubberband/code-doc/classRubberBand_1_1RubberBandStretcher.html
10761 (The mapping of the mpv rubberband filter sub-option names and
10762 values to those of librubberband follows a simple pattern: "Op‐
10763 tion" + Name + Value.)
10764 This filter supports the following af-command commands:
10766 set-pitch
10768 Set the <pitch-scale> argument dynamically. This can be
10769 used to change the playback pitch at runtime. Note that
10770 speed is controlled using the standard speed property,
10771 not af-command.
10772 multiply-pitch <factor>
10774 Multiply the current value of <pitch-scale> dynamically.
10775 For example: 0.5 to go down by an octave, 1.5 to go up by
10776 a perfect fifth. If you want to go up or down by
10777 semi-tones, use 1.059463094352953 and 0.9438743126816935
10778 lavfi=graph
10780 Filter audio using FFmpeg's libavfilter.
10781 <graph>
10783 Libavfilter graph. See lavfi video filter for details -
10784 the graph syntax is the same.
10785 WARNING:
10787 Don't forget to quote libavfilter graphs as described
10788 in the lavfi video filter section.
10789 o=<string>
10791 AVOptions.
10792 fix-pts=<yes|no>
10794 Determine PTS based on sample count (default: no). If
10795 this is enabled, the player won't rely on libavfilter
10796 passing through PTS accurately. Instead, it pass a sam‐
10797 ple count as PTS to libavfilter, and compute the PTS used
10798 by mpv based on that and the input PTS. This helps with
10799 filters which output a recomputed PTS instead of the
10800 original PTS (including filters which require the PTS to
10801 start at 0). mpv normally expects filters to not touch
10802 the PTS (or only to the extent of changing frame bound‐
10803 aries), so this is not the default, but it will be needed
10804 to use broken filters. In practice, these broken filters
10805 will either cause slow A/V desync over time (with some
10806 files), or break playback completely if you seek or start
10807 playback from the middle of a file.
10808 drop This filter drops or repeats audio frames to adapt to playback
10810 speed. It always operates on full audio frames, because it was
10811 made to handle SPDIF (compressed audio passthrough). This is
10812 used automatically if the --video-sync=display-adrop option is
10813 used. Do not use this filter (or the given option); they are ex‐
10814 tremely low quality.
10815
10817 Video filters allow you to modify the video stream and its properties.
10818 All of the information described in this section applies to audio fil‐
10819 ters as well (generally using the prefix --af instead of --vf).
10820 The exact syntax is:
10822 --vf=<filter1[=parameter1:parameter2:...],filter2,...>
10824 Setup a chain of video filters. This consists on the filter
10825 name, and an option list of parameters after =. The parameters
10826 are separated by : (not ,, as that starts a new filter entry).
10827 Before the filter name, a label can be specified with @name:,
10829 where name is an arbitrary user-given name, which identifies the
10830 filter. This is only needed if you want to toggle the filter at
10831 runtime.
10832 A ! before the filter name means the filter is disabled by de‐
10834 fault. It will be skipped on filter creation. This is also use‐
10835 ful for runtime filter toggling.
10836 See the vf command (and toggle sub-command) for further explana‐
10838 tions and examples.
10839 The general filter entry syntax is:
10841 ["@"<label-name>":"] ["!"] <filter-name> [ "=" <filter-param‐
10842 eter-list> ]
10843 or for the special "toggle" syntax (see vf command):
10845 "@"<label-name>
10846 and the filter-parameter-list:
10848 <filter-parameter> | <filter-parameter> "," <filter-parame‐
10849 ter-list>
10850 and filter-parameter:
10852 ( <param-name> "=" <param-value> ) | <param-value>
10853 param-value can further be quoted in [ / ] in case the value
10855 contains characters like , or =. This is used in particular with
10856 the lavfi filter, which uses a very similar syntax as mpv
10857 (MPlayer historically) to specify filters and their parameters.
10858 Filters can be manipulated at run time. You can use @ labels as de‐
10860 scribed above in combination with the vf command (see COMMAND INTER‐
10861 FACE) to get more control over this. Initially disabled filters with !
10862 are useful for this as well.
10863 You can also set defaults for each filter. The defaults are applied be‐
10865 fore the normal filter parameters. This is deprecated and never worked
10866 for the libavfilter bridge.
10867 --vf-defaults=<filter1[=parameter1:parameter2:...],filter2,...>
10869 Set defaults for each filter. (Deprecated. --af-defaults is dep‐
10870 recated as well.)
10871 NOTE:
10873 To get a full list of available video filters, see --vf=help and
10874 https://ffmpeg.org/ffmpeg-filters.html .
10875 Also, keep in mind that most actual filters are available via the
10877 lavfi wrapper, which gives you access to most of libavfilter's fil‐
10878 ters. This includes all filters that have been ported from MPlayer
10879 to libavfilter.
10880 Most builtin filters are deprecated in some ways, unless they're
10882 only available in mpv (such as filters which deal with mpv
10883 specifics, or which are implemented in mpv only).
10884 If a filter is not builtin, the lavfi-bridge will be automatically
10886 tried. This bridge does not support help output, and does not verify
10887 parameters before the filter is actually used. Although the mpv syn‐
10888 tax is rather similar to libavfilter's, it's not the same. (Which
10889 means not everything accepted by vf_lavfi's graph option will be ac‐
10890 cepted by --vf.)
10891 You can also prefix the filter name with lavfi- to force the wrap‐
10893 per. This is helpful if the filter name collides with a deprecated
10894 mpv builtin filter. For example --vf=lavfi-scale=args would use
10895 libavfilter's scale filter over mpv's deprecated builtin one.
10896 Video filters are managed in lists. There are a few commands to manage
10898 the filter list.
10899 --vf-append=filter
10901 Appends the filter given as arguments to the filter list.
10902 --vf-add=filter
10904 Appends the filter given as arguments to the filter list. (Pass‐
10905 ing multiple filters is currently still possible, but depre‐
10906 cated.)
10907 --vf-pre=filter
10909 Prepends the filters given as arguments to the filter list.
10910 (Passing multiple filters is currently still possible, but dep‐
10911 recated.)
10912 --vf-remove=filter
10914 Deletes the filter from the list. The filter can be either given
10915 the way it was added (filter name and its full argument list),
10916 or by label (prefixed with @). Matching of filters works as fol‐
10917 lows: if either of the compared filters has a label set, only
10918 the labels are compared. If none of the filters have a label,
10919 the filter name, arguments, and argument order are compared.
10920 (Passing multiple filters is currently still possible, but dep‐
10921 recated.)
10922 -vf-toggle=filter
10924 Add the given filter to the list if it was not present yet, or
10925 remove it from the list if it was present. Matching of filters
10926 works as described in --vf-remove.
10927 --vf-del=filter
10929 Sort of like --vf-remove, but also accepts an index number. In‐
10930 dex numbers start at 0, negative numbers address the end of the
10931 list (-1 is the last). Deprecated.
10932 --vf-clr
10934 Completely empties the filter list.
10935 With filters that support it, you can access parameters by their name.
10937 --vf=<filter>=help
10939 Prints the parameter names and parameter value ranges for a par‐
10940 ticular filter.
10941 Available mpv-only filters are:
10943 format=fmt=<value>:colormatrix=<value>:...
10945 Applies video parameter overrides, with optional conversion. By
10946 default, this overrides the video's parameters without conver‐
10947 sion (except for the fmt parameter), but can be made to perform
10948 an appropriate conversion with convert=yes for parameters for
10949 which conversion is supported.
10950 <fmt> Image format name, e.g. rgb15, bgr24, 420p, etc. (de‐
10952 fault: don't change).
10953 This filter always performs conversion to the given for‐
10955 mat.
10956 NOTE:
10958 For a list of available formats, use --vf=for‐
10959 mat=fmt=help.
10960 NOTE:
10962 Conversion between hardware formats is supported in
10963 some cases. eg: cuda to vulkan, or vaapi to vulkan.
10964 <convert=yes|no>
10966 Force conversion of color parameters (default: no).
10967 If this is disabled (the default), the only conversion
10969 that is possibly performed is format conversion if <fmt>
10970 is set. All other parameters (like <colormatrix>) are
10971 forced without conversion. This mode is typically useful
10972 when files have been incorrectly tagged.
10973 If this is enabled, libswscale or zimg is used if any of
10975 the parameters mismatch. zimg is used of the input/output
10976 image formats are supported by mpv's zimg wrapper, and if
10977 --sws-allow-zimg=yes is used. Both libraries may not sup‐
10978 port all kinds of conversions. This typically results in
10979 silent incorrect conversion. zimg has in many cases a
10980 better chance of performing the conversion correctly.
10981 In both cases, the color parameters are set on the output
10983 stage of the image format conversion (if fmt was set).
10984 The difference is that with convert=no, the color parame‐
10985 ters are not passed on to the converter.
10986 If input and output video parameters are the same, con‐
10988 version is always skipped.
10989 When converting between hardware formats, this parameter
10991 has no effect, and the only conversion that is done is
10992 the format conversion.
10993 Examples
10995 mpv test.mkv --vf=format:colormatrix=ycgco
10997 Results in incorrect colors (if test.mkv was
10998 tagged correctly).
10999 mpv test.mkv --vf=format:colormatrix=ycgco:convert=yes
11001 --sws-allow-zimg
11002 Results in true conversion to ycgco, assuming
11003 the renderer supports it (--vo=gpu normally
11004 does). You can add --vo=xv to force a VO which
11005 definitely does not support it, which should
11006 show incorrect colors as confirmation.
11007 Using --sws-allow-zimg=no (or disabling zimg at
11009 build time) will use libswscale, which cannot
11010 perform this conversion as of this writing.
11011 <colormatrix>
11013 Controls the YUV to RGB color space conversion when play‐
11014 ing video. There are various standards. Normally, BT.601
11015 should be used for SD video, and BT.709 for HD video.
11016 (This is done by default.) Using incorrect color space
11017 results in slightly under or over saturated and shifted
11018 colors.
11019 These options are not always supported. Different video
11021 outputs provide varying degrees of support. The gpu and
11022 vdpau video output drivers usually offer full support.
11023 The xv output can set the color space if the system video
11024 driver supports it, but not input and output levels. The
11025 scale video filter can configure color space and input
11026 levels, but only if the output format is RGB (if the
11027 video output driver supports RGB output, you can force
11028 this with -vf scale,format=rgba).
11029 If this option is set to auto (which is the default), the
11031 video's color space flag will be used. If that flag is
11032 unset, the color space will be selected automatically.
11033 This is done using a simple heuristic that attempts to
11034 distinguish SD and HD video. If the video is larger than
11035 1279x576 pixels, BT.709 (HD) will be used; otherwise
11036 BT.601 (SD) is selected.
11037 Available color spaces are:
11039 auto automatic selection (default)
11041 bt.601 ITU-R BT.601 (SD)
11043 bt.709 ITU-R BT.709 (HD)
11045 bt.2020-ncl
11047 ITU-R BT.2020 non-constant luminance system
11048 bt.2020-cl
11050 ITU-R BT.2020 constant luminance system
11051 smpte-240m
11053 SMPTE-240M
11054 <colorlevels>
11056 YUV color levels used with YUV to RGB conversion. This
11057 option is only necessary when playing broken files which
11058 do not follow standard color levels or which are flagged
11059 wrong. If the video does not specify its color range, it
11060 is assumed to be limited range.
11061 The same limitations as with <colormatrix> apply.
11063 Available color ranges are:
11065 auto automatic selection (normally limited range) (de‐
11067 fault)
11068 limited
11070 limited range (16-235 for luma, 16-240 for chroma)
11071 full full range (0-255 for both luma and chroma)
11073 <primaries>
11075 RGB primaries the source file was encoded with. Normally
11076 this should be set in the file header, but when playing
11077 broken or mistagged files this can be used to override
11078 the setting.
11079 This option only affects video output drivers that per‐
11081 form color management, for example gpu with the tar‐
11082 get-prim or icc-profile suboptions set.
11083 If this option is set to auto (which is the default), the
11085 video's primaries flag will be used. If that flag is un‐
11086 set, the color space will be selected automatically, us‐
11087 ing the following heuristics: If the <colormatrix> is set
11088 or determined as BT.2020 or BT.709, the corresponding
11089 primaries are used. Otherwise, if the video height is ex‐
11090 actly 576 (PAL), BT.601-625 is used. If it's exactly 480
11091 or 486 (NTSC), BT.601-525 is used. If the video resolu‐
11092 tion is anything else, BT.709 is used.
11093 Available primaries are:
11095 auto automatic selection (default)
11097 bt.601-525
11099 ITU-R BT.601 (SD) 525-line systems (NTSC, SMPTE-C)
11100 bt.601-625
11102 ITU-R BT.601 (SD) 625-line systems (PAL, SECAM)
11103 bt.709 ITU-R BT.709 (HD) (same primaries as sRGB)
11105 bt.2020
11107 ITU-R BT.2020 (UHD)
11108 apple Apple RGB
11110 adobe Adobe RGB (1998)
11112 prophoto
11114 ProPhoto RGB (ROMM)
11115 cie1931
11117 CIE 1931 RGB
11118 dci-p3 DCI-P3 (Digital Cinema)
11120 v-gamut
11122 Panasonic V-Gamut primaries
11123 <gamma>
11125 Gamma function the source file was encoded with. Normally
11126 this should be set in the file header, but when playing
11127 broken or mistagged files this can be used to override
11128 the setting.
11129 This option only affects video output drivers that per‐
11131 form color management.
11132 If this option is set to auto (which is the default), the
11134 gamma will be set to BT.1886 for YCbCr content, sRGB for
11135 RGB content and Linear for XYZ content.
11136 Available gamma functions are:
11138 auto automatic selection (default)
11140 bt.1886
11142 ITU-R BT.1886 (EOTF corresponding to
11143 BT.601/BT.709/BT.2020)
11144 srgb IEC 61966-2-4 (sRGB)
11146 linear Linear light
11148 gamma1.8
11150 Pure power curve (gamma 1.8)
11151 gamma2.0
11153 Pure power curve (gamma 2.0)
11154 gamma2.2
11156 Pure power curve (gamma 2.2)
11157 gamma2.4
11159 Pure power curve (gamma 2.4)
11160 gamma2.6
11162 Pure power curve (gamma 2.6)
11163 gamma2.8
11165 Pure power curve (gamma 2.8)
11166 prophoto
11168 ProPhoto RGB (ROMM) curve
11169 pq ITU-R BT.2100 PQ (Perceptual quantizer) curve
11171 hlg ITU-R BT.2100 HLG (Hybrid Log-gamma) curve
11173 v-log Panasonic V-Log transfer curve
11175 s-log1 Sony S-Log1 transfer curve
11177 s-log2 Sony S-Log2 transfer curve
11179 <sig-peak>
11181 Reference peak illumination for the video file, relative
11182 to the signal's reference white level. This is mostly in‐
11183 teresting for HDR, but it can also be used tone map SDR
11184 content to simulate a different exposure. Normally in‐
11185 ferred from tags such as MaxCLL or mastering metadata.
11186 The default of 0.0 will default to the source's nominal
11188 peak luminance.
11189 <light>
11191 Light type of the scene. This is mostly correctly in‐
11192 ferred based on the gamma function, but it can be use‐
11193 ful to override this when viewing raw camera footage
11194 (e.g. V-Log), which is normally scene-referred instead
11195 of display-referred.
11196 Available light types are:
11198 auto Automatic selection (default)
11200 display
11202 Display-referred light (most content)
11203 hlg Scene-referred using the HLG OOTF (e.g. HLG con‐
11205 tent)
11206 709-1886
11208 Scene-referred using the BT709+BT1886 interaction
11209 gamma1.2
11211 Scene-referred using a pure power OOTF (gamma=1.2)
11212 <dolbyvision=yes|no>
11214 Whether or not to include Dolby Vision metadata (default:
11215 yes). If disabled, any Dolby Vision metadata will be
11216 stripped from frames.
11217 <film-grain=yes|no>
11219 Whether or not to include film grain metadata (default:
11220 yes). If disabled, any film grain metadata will be
11221 stripped from frames.
11222 <stereo-in>
11224 Set the stereo mode the video is assumed to be encoded
11225 in. Use --vf=format:stereo-in=help to list all available
11226 modes. Check with the stereo3d filter documentation to
11227 see what the names mean.
11228 <stereo-out>
11230 Set the stereo mode the video should be displayed as.
11231 Takes the same values as the stereo-in option.
11232 <rotate>
11234 Set the rotation the video is assumed to be encoded with
11235 in degrees. The special value -1 uses the input format.
11236 <w>, <h>
11238 If not 0, perform conversion to the given size. Ignored
11239 if convert=yes is not set.
11240 <dw>, <dh>
11242 Set the display size. Note that setting the display size
11243 such that the video is scaled in both directions instead
11244 of just changing the aspect ratio is an implementation
11245 detail, and might change later.
11246 <dar> Set the display aspect ratio of the video frame. This is
11248 a float, but values such as [16:9] can be passed too
11249 ([...] for quoting to prevent the option parser from in‐
11250 terpreting the : character).
11251 <force-scaler=auto|zimg|sws>
11253 Force a specific scaler backend, if applicable. This is a
11254 debug option and could go away any time.
11255 <alpha=auto|straight|premul>
11257 Set the kind of alpha the video uses. Undefined effect if
11258 the image format has no alpha channel (could be ignored
11259 or cause an error, depending on how mpv internals
11260 evolve). Setting this may or may not cause downstream im‐
11261 age processing to treat alpha differently, depending on
11262 support. With convert and zimg used, this will convert
11263 the alpha. libswscale and other FFmpeg components com‐
11264 pletely ignore this.
11265 lavfi=graph[:sws-flags[:o=opts]]
11267 Filter video using FFmpeg's libavfilter.
11268 <graph>
11270 The libavfilter graph string. The filter must have a sin‐
11271 gle video input pad and a single video output pad.
11272 See https://ffmpeg.org/ffmpeg-filters.html for syntax and
11274 available filters.
11275 WARNING:
11277 If you want to use the full filter syntax with this
11278 option, you have to quote the filter graph in order to
11279 prevent mpv's syntax and the filter graph syntax from
11280 clashing. To prevent a quoting and escaping mess, con‐
11281 sider using --lavfi-complex if you know which video
11282 track you want to use from the input file. (There is
11283 only one video track for nearly all video files any‐
11284 way.)
11285 Examples
11287 --vf=lavfi=[gradfun=20:30,vflip]
11289 gradfun filter with nonsense parameters, fol‐
11290 lowed by a vflip filter. (This demonstrates how
11291 libavfilter takes a graph and not just a single
11292 filter.) The filter graph string is quoted with
11293 [ and ]. This requires no additional quoting or
11294 escaping with some shells (like bash), while
11295 others (like zsh) require additional " quotes
11296 around the option string.
11297 '--vf=lavfi="gradfun=20:30,vflip"'
11299 Same as before, but uses quoting that should be
11300 safe with all shells. The outer ' quotes make
11301 sure that the shell does not remove the "
11302 quotes needed by mpv.
11303 '--vf=lavfi=graph="gradfun=ra‐
11305 dius=30:strength=20,vflip"'
11306 Same as before, but uses named parameters for
11307 everything.
11308 <sws-flags>
11310 If libavfilter inserts filters for pixel format conver‐
11311 sion, this option gives the flags which should be passed
11312 to libswscale. This option is numeric and takes a
11313 bit-wise combination of SWS_ flags.
11314 See https://git.videolan.org/?p=ffmpeg.git;a=blob;f=lib‐
11316 swscale/swscale.h.
11317 <o> Set AVFilterGraph options. These should be documented by
11319 FFmpeg.
11320 Example
11322 '--vf=lavfi=yadif:o="threads=2,thread_type=slice"'
11324 forces a specific threading configuration.
11325 sub=[=bottom-margin:top-margin]
11327 Moves subtitle rendering to an arbitrary point in the filter
11328 chain, or force subtitle rendering in the video filter as op‐
11329 posed to using video output OSD support.
11330 <bottom-margin>
11332 Adds a black band at the bottom of the frame. The SSA/ASS
11333 renderer can place subtitles there (with --sub-use-mar‐
11334 gins).
11335 <top-margin>
11337 Black band on the top for toptitles (with --sub-use-mar‐
11338 gins).
11339 Examples
11341 --vf=sub,eq
11343 Moves sub rendering before the eq filter. This will
11344 put both subtitle colors and video under the influence
11345 of the video equalizer settings.
11346 vapoursynth=file:buffered-frames:concurrent-frames
11348 Loads a VapourSynth filter script. This is intended for streamed
11349 processing: mpv actually provides a source filter, instead of
11350 using a native VapourSynth video source. The mpv source will an‐
11351 swer frame requests only within a small window of frames (the
11352 size of this window is controlled with the buffered-frames pa‐
11353 rameter), and requests outside of that will return errors. As
11354 such, you can't use the full power of VapourSynth, but you can
11355 use certain filters.
11356 WARNING:
11358 Do not use this filter, unless you have expert knowledge in
11359 VapourSynth, and know how to fix bugs in the mpv VapourSynth
11360 wrapper code.
11361 If you just want to play video generated by VapourSynth (i.e.
11363 using a native VapourSynth video source), it's better to use
11364 vspipe and a pipe or FIFO to feed the video to mpv. The same ap‐
11365 plies if the filter script requires random frame access (see
11366 buffered-frames parameter).
11367 file Filename of the script source. Currently, this is always
11369 a python script (.vpy in VapourSynth convention).
11370 The variable video_in is set to the mpv video source, and
11372 it is expected that the script reads video from it. (Oth‐
11373 erwise, mpv will decode no video, and the video packet
11374 queue will overflow, eventually leading to only audio
11375 playing, or worse.)
11376 The filter graph created by the script is also expected
11378 to pass through timestamps using the _DurationNum and
11379 _DurationDen frame properties.
11380 See the end of the option list for a full list of script
11382 variables defined by mpv.
11383 Example:
11385 import vapoursynth as vs
11387 from vapoursynth import core
11388 core.std.AddBorders(video_in, 10, 10, 20, 20).set_output()
11389 WARNING:
11391 The script will be reloaded on every seek. This is
11392 done to reset the filter properly on discontinuities.
11393 buffered-frames
11395 Maximum number of decoded video frames that should be
11396 buffered before the filter (default: 4). This specifies
11397 the maximum number of frames the script can request in
11398 backward direction.
11399 E.g. if buffered-frames=5, and the script just requested
11401 frame 15, it can still request frame 10, but frame 9 is
11402 not available anymore. If it requests frame 30, mpv will
11403 decode 15 more frames, and keep only frames 25-30.
11404 The only reason why this buffer exists is to serve the
11406 random access requests the VapourSynth filter can make.
11407 The VapourSynth API has a getFrameAsync function, which
11409 takes an absolute frame number. Source filters must re‐
11410 spond to all requests. For example, a source filter can
11411 request frame 2432, and then frame 3. Source filters
11412 typically implement this by pre-indexing the entire file.
11413 mpv on the other hand is stream oriented, and does not
11415 allow filters to seek. (And it would not make sense to
11416 allow it, because it would ruin performance.) Filters get
11417 frames sequentially in playback direction, and cannot re‐
11418 quest them out of order.
11419 To compensate for this mismatch, mpv allows the filter to
11421 access frames within a certain window. buffered-frames
11422 controls the size of this window. Most VapourSynth fil‐
11423 ters happen to work with this, because mpv requests
11424 frames sequentially increasing from it, and most filters
11425 only require frames "close" to the requested frame.
11426 If the filter requests a frame that has a higher frame
11428 number than the highest buffered frame, new frames will
11429 be decoded until the requested frame number is reached.
11430 Excessive frames will be flushed out in a FIFO manner
11431 (there are only at most buffered-frames in this buffer).
11432 If the filter requests a frame that has a lower frame
11434 number than the lowest buffered frame, the request cannot
11435 be satisfied, and an error is returned to the filter.
11436 This kind of error is not supposed to happen in a
11437 "proper" VapourSynth environment. What exactly happens
11438 depends on the filters involved.
11439 Increasing this buffer will not improve performance.
11441 Rather, it will waste memory, and slow down seeks (when
11442 enough frames to fill the buffer need to be decoded at
11443 once). It is only needed to prevent the error described
11444 in the previous paragraph.
11445 How many frames a filter requires depends on filter im‐
11447 plementation details, and mpv has no way of knowing. A
11448 scale filter might need only 1 frame, an interpolation
11449 filter may require a small number of frames, and the Re‐
11450 verse filter will require an infinite number of frames.
11451 If you want reliable operation to the full extend
11453 VapourSynth is capable, use vspipe.
11454 The actual number of buffered frames also depends on the
11456 value of the concurrent-frames option. Currently, both
11457 option values are multiplied to get the final buffer
11458 size.
11459 concurrent-frames
11461 Number of frames that should be requested in parallel.
11462 The level of concurrency depends on the filter and how
11463 quickly mpv can decode video to feed the filter. This
11464 value should probably be proportional to the number of
11465 cores on your machine. Most time, making it higher than
11466 the number of cores can actually make it slower.
11467 Technically, mpv will call the VapourSynth getFrameAsync
11469 function in a loop, until there are concurrent-frames
11470 frames that have not been returned by the filter yet.
11471 This also assumes that the rest of the mpv filter chain
11472 reads the output of the vapoursynth filter quickly
11473 enough. (For example, if you pause the player, filtering
11474 will stop very soon, because the filtered frames are
11475 waiting in a queue.)
11476 Actual concurrency depends on many other factors.
11478 By default, this uses the special value auto, which sets
11480 the option to the number of detected logical CPU cores.
11481 The following .vpy script variables are defined by mpv:
11483 video_in
11485 The mpv video source as vapoursynth clip. Note that this
11486 has an incorrect (very high) length set, which confuses
11487 many filters. This is necessary, because the true number
11488 of frames is unknown. You can use the Trim filter on the
11489 clip to reduce the length.
11490 video_in_dw, video_in_dh
11492 Display size of the video. Can be different from video
11493 size if the video does not use square pixels (e.g. DVD).
11494 container_fps
11496 FPS value as reported by file headers. This value can be
11497 wrong or completely broken (e.g. 0 or NaN). Even if the
11498 value is correct, if another filter changes the real FPS
11499 (by dropping or inserting frames), the value of this
11500 variable will not be useful. Note that the --fps command
11501 line option overrides this value.
11502 Useful for some filters which insist on having a FPS.
11504 display_fps
11506 Refresh rate of the current display. Note that this value
11507 can be 0.
11508 vavpp VA-API video post processing. Requires the system to support
11510 VA-API, i.e. Linux/BSD only. Works with --vo=vaapi and --vo=gpu
11511 only. Currently deinterlaces. This filter is automatically in‐
11512 serted if deinterlacing is requested (either using the d key, by
11513 default mapped to the command cycle deinterlace, or the --dein‐
11514 terlace option).
11515 deint=<method>
11517 Select the deinterlacing algorithm.
11518 no Don't perform deinterlacing.
11520 auto Select the best quality deinterlacing algorithm
11522 (default). This goes by the order of the options
11523 as documented, with motion-compensated being con‐
11524 sidered best quality.
11525 first-field
11527 Show only first field.
11528 bob bob deinterlacing.
11530 weave, motion-adaptive, motion-compensated
11532 Advanced deinterlacing algorithms. Whether these
11533 actually work depends on the GPU hardware, the GPU
11534 drivers, driver bugs, and mpv bugs.
11535 <interlaced-only>
11537 no Deinterlace all frames (default).
11539 yes Only deinterlace frames marked as interlaced.
11541 reversal-bug=<yes|no>
11543 no Use the API as it was interpreted by older Mesa
11545 drivers. While this interpretation was more obvi‐
11546 ous and intuitive, it was apparently wrong, and
11547 not shared by Intel driver developers.
11548 yes Use Intel interpretation of surface forward and
11550 backwards references (default). This is what Intel
11551 drivers and newer Mesa drivers expect. Matters
11552 only for the advanced deinterlacing algorithms.
11553 vdpaupp
11555 VDPAU video post processing. Works with --vo=vdpau and --vo=gpu
11556 only. This filter is automatically inserted if deinterlacing is
11557 requested (either using the d key, by default mapped to the com‐
11558 mand cycle deinterlace, or the --deinterlace option). When en‐
11559 abling deinterlacing, it is always preferred over software dein‐
11560 terlacer filters if the vdpau VO is used, and also if gpu is
11561 used and hardware decoding was activated at least once (i.e. vd‐
11562 pau was loaded).
11563 sharpen=<-1-1>
11565 For positive values, apply a sharpening algorithm to the
11566 video, for negative values a blurring algorithm (default:
11567 0).
11568 denoise=<0-1>
11570 Apply a noise reduction algorithm to the video (default:
11571 0; no noise reduction).
11572 deint=<yes|no>
11574 Whether deinterlacing is enabled (default: no). If en‐
11575 abled, it will use the mode selected with deint-mode.
11576 deint-mode=<first-field|bob|temporal|temporal-spatial>
11578 Select deinterlacing mode (default: temporal).
11579 Note that there's currently a mechanism that allows the
11581 vdpau VO to change the deint-mode of auto-inserted vd‐
11582 paupp filters. To avoid confusion, it's recommended not
11583 to use the --vo=vdpau suboptions related to filtering.
11584 first-field
11586 Show only first field.
11587 bob Bob deinterlacing.
11589 temporal
11591 Motion-adaptive temporal deinterlacing. May lead
11592 to A/V desync with slow video hardware and/or high
11593 resolution.
11594 temporal-spatial
11596 Motion-adaptive temporal deinterlacing with
11597 edge-guided spatial interpolation. Needs fast
11598 video hardware.
11599 chroma-deint
11601 Makes temporal deinterlacers operate both on luma and
11602 chroma (default). Use no-chroma-deint to solely use luma
11603 and speed up advanced deinterlacing. Useful with slow
11604 video memory.
11605 pullup Try to apply inverse telecine, needs motion adaptive tem‐
11607 poral deinterlacing.
11608 interlaced-only=<yes|no>
11610 If yes, only deinterlace frames marked as interlaced (de‐
11611 fault: no).
11612 hqscaling=<0-9>
11614 0 Use default VDPAU scaling (default).
11616 1-9 Apply high quality VDPAU scaling (needs capable
11618 hardware).
11619 d3d11vpp
11621 Direct3D 11 video post processing. Currently requires D3D11
11622 hardware decoding for use.
11623 deint=<yes|no>
11625 Whether deinterlacing is enabled (default: no).
11626 interlaced-only=<yes|no>
11628 If yes, only deinterlace frames marked as interlaced (de‐
11629 fault: no).
11630 mode=<blend|bob|adaptive|mocomp|ivctc|none>
11632 Tries to select a video processor with the given process‐
11633 ing capability. If a video processor supports multiple
11634 capabilities, it is not clear which algorithm is actually
11635 selected. none always falls back. On most if not all
11636 hardware, this option will probably do nothing, because a
11637 video processor usually supports all modes or none.
11638 fingerprint=...
11640 Compute video frame fingerprints and provide them as metadata.
11641 Actually, it currently barely deserved to be called fingerprint,
11642 because it does not compute "proper" fingerprints, only tiny
11643 downscaled images (but which can be used to compute image hashes
11644 or for similarity matching).
11645 The main purpose of this filter is to support the skip-logo.lua
11647 script. If this script is dropped, or mpv ever gains a way to
11648 load user-defined filters (other than VapourSynth), this filter
11649 will be removed. Due to the "special" nature of this filter, it
11650 will be removed without warning.
11651 The intended way to read from the filter is using vf-metadata
11653 (also see clear-on-query filter parameter). The property will
11654 return a list of key/value pairs as follows:
11655 fp0.pts = 1.2345
11657 fp0.hex = 1234abcdef...bcde
11658 fp1.pts = 1.4567
11659 fp1.hex = abcdef1234...6789
11660 ...
11661 fpN.pts = ...
11662 fpN.hex = ...
11663 type = gray-hex-16x16
11664 Each fp<N> entry is for a frame. The pts entry specifies the
11666 timestamp of the frame (within the filter chain; in simple cases
11667 this is the same as the display timestamp). The hex field is the
11668 hex encoded fingerprint, whose size and meaning depend on the
11669 type filter option. The type field has the same value as the
11670 option the filter was created with.
11671 This returns the frames that were filtered since the last query
11673 of the property. If clear-on-query=no was set, a query doesn't
11674 reset the list of frames. In both cases, a maximum of 10 frames
11675 is returned. If there are more frames, the oldest frames are
11676 discarded. Frames are returned in filter order.
11677 (This doesn't return a structured list for the per-frame details
11679 because the internals of the vf-metadata mechanism suck. The re‐
11680 turned format may change in the future.)
11681 This filter uses zimg for speed and profit. However, it will
11683 fallback to libswscale in a number of situations: lesser pixel
11684 formats, unaligned data pointers or strides, or if zimg fails to
11685 initialize for unknown reasons. In these cases, the filter will
11686 use more CPU. Also, it will output different fingerprints, be‐
11687 cause libswscale cannot perform the full range expansion we nor‐
11688 mally request from zimg. As a consequence, the filter may be
11689 slower and not work correctly in random situations.
11690 type=...
11692 What fingerprint to compute. Available types are:
11693 gray-hex-8x8
11695 grayscale, 8 bit, 8x8 size
11696 gray-hex-16x16
11698 grayscale, 8 bit, 16x16 size (default)
11699 Both types simply remove all colors, downscale the image,
11701 concatenate all pixel values to a byte array, and convert
11702 the array to a hex string.
11703 clear-on-query=yes|no
11705 Clear the list of frame fingerprints if the vf-metadata
11706 property for this filter is queried (default: yes). This
11707 requires some care by the user. Some types of accesses
11708 might query the filter multiple times, which leads to
11709 lost frames.
11710 print=yes|no
11712 Print computed fingerprints to the terminal (default:
11713 no). This is mostly for testing and such. Scripts should
11714 use vf-metadata to read information from this filter in‐
11715 stead.
11716 gpu=...
11718 Convert video to RGB using the OpenGL renderer normally used
11719 with --vo=gpu. This requires that the EGL implementation sup‐
11720 ports off-screen rendering on the default display. (This is the
11721 case with Mesa.)
11722 Sub-options:
11724 w=<pixels>, h=<pixels>
11726 Size of the output in pixels (default: 0). If not posi‐
11727 tive, this will use the size of the first filtered input
11728 frame.
11729 WARNING:
11731 This is highly experimental. Performance is bad, and it will
11732 not work everywhere in the first place. Some features are not
11733 supported.
11734 WARNING:
11736 This does not do OSD rendering. If you see OSD, then it has
11737 been rendered by the VO backend. (Subtitles are rendered by
11738 the gpu filter, if possible.)
11739 WARNING:
11741 If you use this with encoding mode, keep in mind that encod‐
11742 ing mode will convert the RGB filter's output back to yuv420p
11743 in software, using the configured software scaler. Using zimg
11744 might improve this, but in any case it might go against your
11745 goals when using this filter.
11746 WARNING:
11748 Do not use this with --vo=gpu. It will apply filtering twice,
11749 since most --vo=gpu options are unconditionally applied to
11750 the gpu filter. There is no mechanism in mpv to prevent this.
11751
11753 You can encode files from one format/codec to another using this facil‐
11754 ity.
11755 --o=<filename>
11757 Enables encoding mode and specifies the output file name.
11758 --of=<format>
11760 Specifies the output format (overrides autodetection by the file
11761 name extension of the file specified by -o). See --of=help for a
11762 full list of supported formats.
11763 --ofopts=<options>
11765 Specifies the output format options for libavformat. See
11766 --ofopts=help for a full list of supported options.
11767 This is a key/value list option. See List Options for details.
11769 --ofopts-add=<option>
11771 Appends the option given as an argument to the options
11772 list. (Passing multiple options is currently still possi‐
11773 ble, but deprecated.)
11774 --ofopts=""
11776 Completely empties the options list.
11777 --oac=<codec>
11779 Specifies the output audio codec. See --oac=help for a full list
11780 of supported codecs.
11781 --oaoffset=<value>
11783 Shifts audio data by the given time (in seconds) by adding/re‐
11784 moving samples at the start. Deprecated.
11785 --oacopts=<options>
11787 Specifies the output audio codec options for libavcodec. See
11788 --oacopts=help for a full list of supported options.
11789 Example
11791 "--oac=libmp3lame --oacopts=b=128000"
11793 selects 128 kbps MP3 encoding.
11794 This is a key/value list option. See List Options for details.
11796 --oacopts-add=<option>
11798 Appends the option given as an argument to the options
11799 list. (Passing multiple options is currently still possi‐
11800 ble, but deprecated.)
11801 --oacopts=""
11803 Completely empties the options list.
11804 --oafirst
11806 Force the audio stream to become the first stream in the output.
11807 By default, the order is unspecified. Deprecated.
11808 --ovc=<codec>
11810 Specifies the output video codec. See --ovc=help for a full list
11811 of supported codecs.
11812 --ovoffset=<value>
11814 Shifts video data by the given time (in seconds) by shifting the
11815 pts values. Deprecated.
11816 --ovcopts=<options>
11818 Specifies the output video codec options for libavcodec. See
11819 --ovcopts=help for a full list of supported options.
11820 Examples
11822 "--ovc=mpeg4 --ovcopts=qscale=5"
11824 selects constant quantizer scale 5 for MPEG-4 encod‐
11825 ing.
11826 "--ovc=libx264 --ovcopts=crf=23"
11828 selects VBR quality factor 23 for H.264 encoding.
11829 This is a key/value list option. See List Options for details.
11831 --ovcopts-add=<option>
11833 Appends the option given as an argument to the options
11834 list. (Passing multiple options is currently still possi‐
11835 ble, but deprecated.)
11836 --ovcopts=""
11838 Completely empties the options list.
11839 --ovfirst
11841 Force the video stream to become the first stream in the output.
11842 By default, the order is unspecified. Deprecated.
11843 --orawts
11845 Copies input pts to the output video (not supported by some out‐
11846 put container formats, e.g. AVI). In this mode, discontinuities
11847 are not fixed and all pts are passed through as-is. Never seek
11848 backwards or use multiple input files in this mode!
11849 --no-ocopy-metadata
11851 Turns off copying of metadata from input files to output files
11852 when encoding (which is enabled by default).
11853 --oset-metadata=<metadata-tag[,metadata-tag,...]>
11855 Specifies metadata to include in the output file. Supported
11856 keys vary between output formats. For example, Matroska (MKV)
11857 and FLAC allow almost arbitrary keys, while support in MP4 and
11858 MP3 is more limited.
11859 This is a key/value list option. See List Options for details.
11861 Example
11863 "--oset-metadata=title="Output title",comment="Another tag""
11865 adds a title and a comment to the output file.
11866 --oremove-metadata=<metadata-tag[,metadata-tag,...]>
11868 Specifies metadata to exclude from the output file when copying
11869 from the input file.
11870 This is a string list option. See List Options for details.
11872 Example
11874 "--oremove-metadata=comment,genre"
11876 excludes copying of the the comment and genre tags to
11877 the output file.
11878
11880 The mpv core can be controlled with commands and properties. A number
11881 of ways to interact with the player use them: key bindings (in‐
11882 put.conf), OSD (showing information with properties), JSON IPC, the
11883 client API (libmpv), and the classic slave mode.
11884 input.conf
11886 The input.conf file consists of a list of key bindings, for example:
11887 s screenshot # take a screenshot with the s key
11889 LEFT seek 15 # map the left-arrow key to seeking forward by 15 seconds
11890 Each line maps a key to an input command. Keys are specified with their
11892 literal value (upper case if combined with Shift), or a name for spe‐
11893 cial keys. For example, a maps to the a key without shift, and A maps
11894 to a with shift.
11895 The file is located in the mpv configuration directory (normally at
11897 ~/.config/mpv/input.conf depending on platform). The default bindings
11898 are defined here:
11899 https://github.com/mpv-player/mpv/blob/master/etc/input.conf
11901 A list of special keys can be obtained with
11903 mpv --input-keylist
11904 In general, keys can be combined with Shift, Ctrl and Alt:
11906 ctrl+q quit
11908 mpv can be started in input test mode, which displays key bindings and
11910 the commands they're bound to on the OSD, instead of executing the com‐
11911 mands:
11912 mpv --input-test --force-window --idle
11914 (Only closing the window will make mpv exit, pressing normal keys will
11916 merely display the binding, even if mapped to quit.)
11917 Also see Key names.
11919 input.conf syntax
11921 [Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] <command> ( ; <command>
11922 )*
11923 Note that by default, the right Alt key can be used to create special
11925 characters, and thus does not register as a modifier. The option
11926 --no-input-right-alt-gr changes this behavior.
11927 Newlines always start a new binding. # starts a comment (outside of
11929 quoted string arguments). To bind commands to the # key, SHARP can be
11930 used.
11931 <key> is either the literal character the key produces (ASCII or Uni‐
11933 code character), or a symbolic name (as printed by --input-keylist).
11934 <section> (braced with { and }) is the input section for this command.
11936 <command> is the command itself. It consists of the command name and
11938 multiple (or none) arguments, all separated by whitespace. String argu‐
11939 ments should be quoted, typically with ". See Flat command syntax.
11940 You can bind multiple commands to one key. For example:
11942 a show-text "command 1" ; show-text "command 2"
11943 It's also possible to bind a command to a sequence of keys:
11946 a-b-c show-text "command run after a, b, c have been pressed"
11947 (This is not shown in the general command syntax.)
11950 If a or a-b or b are already bound, this will run the first command
11952 that matches, and the multi-key command will never be called. Interme‐
11953 diate keys can be remapped to ignore in order to avoid this issue. The
11954 maximum number of (non-modifier) keys for combinations is currently 4.
11955 Key names
11957 All mouse and keyboard input is to converted to mpv-specific key names.
11958 Key names are either special symbolic identifiers representing a physi‐
11959 cal key, or a text key names, which are unicode code points encoded as
11960 UTF-8. These are what keyboard input would normally produce, for exam‐
11961 ple a for the A key. As a consequence, mpv uses input translated by the
11962 current OS keyboard layout, rather than physical scan codes.
11963 Currently there is the hardcoded assumption that every text key can be
11965 represented as a single unicode code point (in NFKC form).
11966 All key names can be combined with the modifiers Shift, Ctrl, Alt,
11968 Meta. They must be prefixed to the actual key name, where each modifier
11969 is followed by a + (for example ctrl+q).
11970 The Shift modifier requires some attention. For instance Shift+2 should
11972 usually be specified as key-name @ at input.conf, and similarly the
11973 combination Alt+Shift+2 is usually Alt+@, etc. Special key names like
11974 Shift+LEFT work as expected. If in doubt - use --input-test to check
11975 how a key/combination is seen by mpv.
11976 Symbolic key names and modifier names are case-insensitive. Unicode key
11978 names are case-sensitive because input bindings typically respect the
11979 shift key.
11980 Another type of key names are hexadecimal key names, that serve as
11982 fallback for special keys that are neither unicode, nor have a special
11983 mpv defined name. They will break as soon as mpv adds proper names for
11984 them, but can enable you to use a key at all if that does not happen.
11985 All symbolic names are listed by --input-keylist. --input-test is a
11987 special mode that prints all input on the OSD.
11988 Comments on some symbolic names:
11990 KP* Keypad names. Behavior varies by backend (whether they implement
11992 this, and on how they treat numlock), but typically, mpv tries
11993 to map keys on the keypad to separate names, even if they pro‐
11994 duce the same text as normal keys.
11995 MOUSE_BTN*, MBTN*
11997 Various mouse buttons.
11998 Depending on backend, the mouse wheel might also be represented
12000 as a button. In addition, MOUSE_BTN3 to MOUSE_BTN6 are depre‐
12001 cated aliases for WHEEL_UP, WHEEL_DOWN, WHEEL_LEFT, WHEEL_RIGHT.
12002 MBTN* are aliases for MOUSE_BTN*.
12004 WHEEL_*
12006 Mouse wheels (typically).
12007 AXIS_* Deprecated aliases for WHEEL_*.
12009 *_DBL Mouse button double clicks.
12011 MOUSE_MOVE, MOUSE_ENTER, MOUSE_LEAVE
12013 Emitted by mouse move events. Enter/leave happens when the mouse
12014 enters or leave the mpv window (or the current mouse region, us‐
12015 ing the deprecated mouse region input section mechanism).
12016 CLOSE_WIN
12018 Pseudo key emitted when closing the mpv window using the OS win‐
12019 dow manager (for example, by clicking the close button in the
12020 window title bar).
12021 GAMEPAD_*
12023 Keys emitted by the SDL gamepad backend.
12024 UNMAPPED
12026 Pseudo-key that matches any unmapped key. (You should probably
12027 avoid this if possible, because it might change behavior or get
12028 removed in the future.)
12029 ANY_UNICODE
12031 Pseudo-key that matches any key that produces text. (You should
12032 probably avoid this if possible, because it might change behav‐
12033 ior or get removed in the future.)
12034 Flat command syntax
12036 This is the syntax used in input.conf, and referred to "input.conf syn‐
12037 tax" in a number of other places.
12038 <command> ::= [<prefixes>] <command_name> (<argument>)*
12040 <argument> ::= (<unquoted> | " <double_quoted> " | ' <single_quoted> ' | `X <custom_quoted> X`)
12041 command_name is an unquoted string with the command name itself. See
12044 List of Input Commands for a list.
12045 Arguments are separated by whitespaces even if the command expects only
12047 one argument. Arguments with whitespaces or other special characters
12048 must be quoted, or the command cannot be parsed correctly.
12049 Double quotes interpret JSON/C-style escaping, like \t or \" or \\.
12051 JSON escapes according to RFC 8259, minus surrogate pair escapes. This
12052 is the only form which allows newlines at the value - as \n.
12053 Single quotes take the content literally, and cannot include the sin‐
12055 gle-quote character at the value.
12056 Custom quotes also take the content literally, but are more flexible
12058 than single quotes. They start with ` (back-quote) followed by any
12059 ASCII character, and end at the first occurrence of the same pair in
12060 reverse order, e.g. `-foo-` or ``bar``. The final pair sequence is not
12061 allowed at the value - in these examples -` and `` respectively. In the
12062 second example the last character of the value also can't be a
12063 back-quote.
12064 Mixed quoting at the same argument, like 'foo'"bar", is not supported.
12066 Note that argument parsing and property expansion happen at different
12068 stages. First, arguments are determined as described above, and then,
12069 where applicable, properties are expanded - regardless of argument
12070 quoting. However, expansion can still be prevented with the raw prefix
12071 or $>. See Input Command Prefixes and Property Expansion.
12072 Commands specified as arrays
12074 This applies to certain APIs, such as mp.commandv() or mp.command_na‐
12075 tive() (with array parameters) in Lua scripting, or mpv_command() or
12076 mpv_command_node() (with MPV_FORMAT_NODE_ARRAY) in the C libmpv client
12077 API.
12078 The command as well as all arguments are passed as a single array. Sim‐
12080 ilar to the Flat command syntax, you can first pass prefixes as strings
12081 (each as separate array item), then the command name as string, and
12082 then each argument as string or a native value.
12083 Since these APIs pass arguments as separate strings or native values,
12085 they do not expect quotes, and do support escaping. Technically, there
12086 is the input.conf parser, which first splits the command string into
12087 arguments, and then invokes argument parsers for each argument. The in‐
12088 put.conf parser normally handles quotes and escaping. The array command
12089 APIs mentioned above pass strings directly to the argument parsers, or
12090 can sidestep them by the ability to pass non-string values.
12091 Property expansion is disabled by default for these APIs. This can be
12093 changed with the expand-properties prefix. See Input Command Prefixes.
12094 Sometimes commands have string arguments, that in turn are actually
12096 parsed by other components (e.g. filter strings with vf add) - in these
12097 cases, you you would have to double-escape in input.conf, but not with
12098 the array APIs.
12099 For complex commands, consider using Named arguments instead, which
12101 should give slightly more compatibility. Some commands do not support
12102 named arguments and inherently take an array, though.
12103 Named arguments
12105 This applies to certain APIs, such as mp.command_native() (with tables
12106 that have string keys) in Lua scripting, or mpv_command_node() (with
12107 MPV_FORMAT_NODE_MAP) in the C libmpv client API.
12108 The name of the command is provided with a name string field. The name
12110 of each command is defined in each command description in the List of
12111 Input Commands. --input-cmdlist also lists them. See the subprocess
12112 command for an example.
12113 Some commands do not support named arguments (e.g. run command). You
12115 need to use APIs that pass arguments as arrays.
12116 Named arguments are not supported in the "flat" input.conf syntax,
12118 which means you cannot use them for key bindings in input.conf at all.
12119 Property expansion is disabled by default for these APIs. This can be
12121 changed with the expand-properties prefix. See Input Command Prefixes.
12122 List of Input Commands
12124 Commands with parameters have the parameter name enclosed in < / >.
12125 Don't add those to the actual command. Optional arguments are enclosed
12126 in [ / ]. If you don't pass them, they will be set to a default value.
12127 Remember to quote string arguments in input.conf (see Flat command syn‐
12129 tax).
12130 ignore Use this to "block" keys that should be unbound, and do nothing.
12132 Useful for disabling default bindings, without disabling all
12133 bindings with --no-input-default-bindings.
12134 seek <target> [<flags>]
12136 Change the playback position. By default, seeks by a relative
12137 amount of seconds.
12138 The second argument consists of flags controlling the seek mode:
12140 relative (default)
12142 Seek relative to current position (a negative value seeks
12143 backwards).
12144 absolute
12146 Seek to a given time (a negative value starts from the
12147 end of the file).
12148 absolute-percent
12150 Seek to a given percent position.
12151 relative-percent
12153 Seek relative to current position in percent.
12154 keyframes
12156 Always restart playback at keyframe boundaries (fast).
12157 exact Always do exact/hr/precise seeks (slow).
12159 Multiple flags can be combined, e.g.: absolute+keyframes.
12161 By default, keyframes is used for relative, relative-percent,
12163 and absolute-percent seeks, while exact is used for absolute
12164 seeks.
12165 Before mpv 0.9, the keyframes and exact flags had to be passed
12167 as 3rd parameter (essentially using a space instead of +). The
12168 3rd parameter is still parsed, but is considered deprecated.
12169 revert-seek [<flags>]
12171 Undoes the seek command, and some other commands that seek (but
12172 not necessarily all of them). Calling this command once will
12173 jump to the playback position before the seek. Calling it a sec‐
12174 ond time undoes the revert-seek command itself. This only works
12175 within a single file.
12176 The first argument is optional, and can change the behavior:
12178 mark Mark the current time position. The next normal re‐
12180 vert-seek command will seek back to this point, no matter
12181 how many seeks happened since last time.
12182 mark-permanent
12184 If set, mark the current position, and do not change the
12185 mark position before the next revert-seek command that
12186 has mark or mark-permanent set (or playback of the cur‐
12187 rent file ends). Until this happens, revert-seek will al‐
12188 ways seek to the marked point. This flag cannot be com‐
12189 bined with mark.
12190 Using it without any arguments gives you the default behavior.
12192 frame-step
12194 Play one frame, then pause. Does nothing with audio-only play‐
12195 back.
12196 frame-back-step
12198 Go back by one frame, then pause. Note that this can be very
12199 slow (it tries to be precise, not fast), and sometimes fails to
12200 behave as expected. How well this works depends on whether pre‐
12201 cise seeking works correctly (e.g. see the --hr-seek-de‐
12202 muxer-offset option). Video filters or other video post-process‐
12203 ing that modifies timing of frames (e.g. deinterlacing) should
12204 usually work, but might make backstepping silently behave incor‐
12205 rectly in corner cases. Using --hr-seek-framedrop=no should
12206 help, although it might make precise seeking slower.
12207 This does not work with audio-only playback.
12209 set <name> <value>
12211 Set the given property or option to the given value.
12212 del <name>
12214 Delete the given property. Most properties cannot be deleted.
12215 add <name> [<value>]
12217 Add the given value to the property or option. On overflow or
12218 underflow, clamp the property to the maximum. If <value> is
12219 omitted, assume 1.
12220 cycle <name> [<value>]
12222 Cycle the given property or option. The second argument can be
12223 up or down to set the cycle direction. On overflow, set the
12224 property back to the minimum, on underflow set it to the maxi‐
12225 mum. If up or down is omitted, assume up.
12226 Whether or not key-repeat is enabled by default depends on the
12228 property. Currently properties with continuous values are re‐
12229 peatable by default (like volume), while discrete values are not
12230 (like osd-level).
12231 multiply <name> <value>
12233 Similar to add, but multiplies the property or option with the
12234 numeric value.
12235 screenshot <flags>
12237 Take a screenshot.
12238 Multiple flags are available (some can be combined with +):
12240 <subtitles> (default)
12242 Save the video image, in its original resolution, and
12243 with subtitles. Some video outputs may still include the
12244 OSD in the output under certain circumstances.
12245 <video>
12247 Like subtitles, but typically without OSD or subtitles.
12248 The exact behavior depends on the selected video output.
12249 <window>
12251 Save the contents of the mpv window. Typically scaled,
12252 with OSD and subtitles. The exact behavior depends on the
12253 selected video output.
12254 <each-frame>
12256 Take a screenshot each frame. Issue this command again to
12257 stop taking screenshots. Note that you should disable
12258 frame-dropping when using this mode - or you might re‐
12259 ceive duplicate images in cases when a frame was dropped.
12260 This flag can be combined with the other flags, e.g.
12261 video+each-frame.
12262 Older mpv versions required passing single and each-frame as
12264 second argument (and did not have flags). This syntax is still
12265 understood, but deprecated and might be removed in the future.
12266 If you combine this command with another one using ;, you can
12268 use the async flag to make encoding/writing the image file asyn‐
12269 chronous. For normal standalone commands, this is always asyn‐
12270 chronous, and the flag has no effect. (This behavior changed
12271 with mpv 0.29.0.)
12272 On success, returns a mpv_node with a filename field set to the
12274 saved screenshot location.
12275 screenshot-to-file <filename> <flags>
12277 Take a screenshot and save it to a given file. The format of the
12278 file will be guessed by the extension (and --screenshot-format
12279 is ignored - the behavior when the extension is missing or un‐
12280 known is arbitrary).
12281 The second argument is like the first argument to screenshot and
12283 supports subtitles, video, window.
12284 If the file already exists, it's overwritten.
12286 Like all input command parameters, the filename is subject to
12288 property expansion as described in Property Expansion.
12289 playlist-next <flags>
12291 Go to the next entry on the playlist.
12292 First argument:
12294 weak (default)
12296 If the last file on the playlist is currently played, do
12297 nothing.
12298 force Terminate playback if there are no more files on the
12300 playlist.
12301 playlist-prev <flags>
12303 Go to the previous entry on the playlist.
12304 First argument:
12306 weak (default)
12308 If the first file on the playlist is currently played, do
12309 nothing.
12310 force Terminate playback if the first file is being played.
12312 playlist-play-index <integer|current|none>
12314 Start (or restart) playback of the given playlist index. In ad‐
12315 dition to the 0-based playlist entry index, it supports the fol‐
12316 lowing values:
12317 <current>
12319 The current playlist entry (as in playlist-current-pos)
12320 will be played again (unload and reload). If none is set,
12321 playback is stopped. (In corner cases, playlist-cur‐
12322 rent-pos can point to a playlist entry even if playback
12323 is currently inactive,
12324 <none> Playback is stopped. If idle mode (--idle) is enabled,
12326 the player will enter idle mode, otherwise it will exit.
12327 This command is similar to loadfile in that it only manipulates
12329 the state of what to play next, without waiting until the cur‐
12330 rent file is unloaded, and the next one is loaded.
12331 Setting playlist-pos or similar properties can have a similar
12333 effect to this command. However, it's more explicit, and guaran‐
12334 tees that playback is restarted if for example the new playlist
12335 entry is the same as the previous one.
12336 loadfile <url> [<flags> [<options>]]
12338 Load the given file or URL and play it. Technically, this is
12339 just a playlist manipulation command (which either replaces the
12340 playlist or appends an entry to it). Actual file loading happens
12341 independently. For example, a loadfile command that replaces the
12342 current file with a new one returns before the current file is
12343 stopped, and the new file even begins loading.
12344 Second argument:
12346 <replace> (default)
12348 Stop playback of the current file, and play the new file
12349 immediately.
12350 <append>
12352 Append the file to the playlist.
12353 <append-play>
12355 Append the file, and if nothing is currently playing,
12356 start playback. (Always starts with the added file, even
12357 if the playlist was not empty before running this com‐
12358 mand.)
12359 The third argument is a list of options and values which should
12361 be set while the file is playing. It is of the form
12362 opt1=value1,opt2=value2,... When using the client API, this can
12363 be a MPV_FORMAT_NODE_MAP (or a Lua table), however the values
12364 themselves must be strings currently. These options are set dur‐
12365 ing playback, and restored to the previous value at end of play‐
12366 back (see Per-File Options).
12367 loadlist <url> [<flags>]
12369 Load the given playlist file or URL (like --playlist).
12370 Second argument:
12372 <replace> (default)
12374 Stop playback and replace the internal playlist with the
12375 new one.
12376 <append>
12378 Append the new playlist at the end of the current inter‐
12379 nal playlist.
12380 <append-play>
12382 Append the new playlist, and if nothing is currently
12383 playing, start playback. (Always starts with the new
12384 playlist, even if the internal playlist was not empty be‐
12385 fore running this command.)
12386 playlist-clear
12388 Clear the playlist, except the currently played file.
12389 playlist-remove <index>
12391 Remove the playlist entry at the given index. Index values start
12392 counting with 0. The special value current removes the current
12393 entry. Note that removing the current entry also stops playback
12394 and starts playing the next entry.
12395 playlist-move <index1> <index2>
12397 Move the playlist entry at index1, so that it takes the place of
12398 the entry index2. (Paradoxically, the moved playlist entry will
12399 not have the index value index2 after moving if index1 was lower
12400 than index2, because index2 refers to the target entry, not the
12401 index the entry will have after moving.)
12402 playlist-shuffle
12404 Shuffle the playlist. This is similar to what is done on start
12405 if the --shuffle option is used.
12406 playlist-unshuffle
12408 Attempt to revert the previous playlist-shuffle command. This
12409 works only once (multiple successive playlist-unshuffle commands
12410 do nothing). May not work correctly if new recursive playlists
12411 have been opened since a playlist-shuffle command.
12412 run <command> [<arg1> [<arg2> [...]]]
12414 Run the given command. Unlike in MPlayer/mplayer2 and earlier
12415 versions of mpv (0.2.x and older), this doesn't call the shell.
12416 Instead, the command is run directly, with each argument passed
12417 separately. Each argument is expanded like in Property Expan‐
12418 sion.
12419 This command has a variable number of arguments, and cannot be
12421 used with named arguments.
12422 The program is run in a detached way. mpv doesn't wait until the
12424 command is completed, but continues playback right after spawn‐
12425 ing it.
12426 To get the old behavior, use /bin/sh and -c as the first two ar‐
12428 guments.
12429 Example
12431 run "/bin/sh" "-c" "echo ${title} > /tmp/playing"
12433 This is not a particularly good example, because it
12435 doesn't handle escaping, and a specially prepared file
12436 might allow an attacker to execute arbitrary shell
12437 commands. It is recommended to write a small shell
12438 script, and call that with run.
12439 subprocess
12441 Similar to run, but gives more control about process execution
12442 to the caller, and does does not detach the process.
12443 You can avoid blocking until the process terminates by running
12445 this command asynchronously. (For example mp.command_na‐
12446 tive_async() in Lua scripting.)
12447 This has the following named arguments. The order of them is not
12449 guaranteed, so you should always call them with named arguments,
12450 see Named arguments.
12451 args (MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING])
12453 Array of strings with the command as first argument, and
12454 subsequent command line arguments following. This is just
12455 like the run command argument list.
12456 The first array entry is either an absolute path to the
12458 executable, or a filename with no path components, in
12459 which case the executable is searched in the directories
12460 in the PATH environment variable. On Unix, this is equiv‐
12461 alent to posix_spawnp and execvp behavior.
12462 playback_only (MPV_FORMAT_FLAG)
12464 Boolean indicating whether the process should be killed
12465 when playback of the current playlist entry terminates
12466 (optional, default: true). If enabled, stopping playback
12467 will automatically kill the process, and you can't start
12468 it outside of playback.
12469 capture_size (MPV_FORMAT_INT64)
12471 Integer setting the maximum number of stdout plus stderr
12472 bytes that can be captured (optional, default: 64MB). If
12473 the number of bytes exceeds this, capturing is stopped.
12474 The limit is per captured stream.
12475 capture_stdout (MPV_FORMAT_FLAG)
12477 Capture all data the process outputs to stdout and return
12478 it once the process ends (optional, default: no).
12479 capture_stderr (MPV_FORMAT_FLAG)
12481 Same as capture_stdout, but for stderr.
12482 detach (MPV_FORMAT_FLAG)
12484 Whether to run the process in detached mode (optional,
12485 default: no). In this mode, the process is run in a new
12486 process session, and the command does not wait for the
12487 process to terminate. If neither capture_stdout nor cap‐
12488 ture_stderr have been set to true, the command returns
12489 immediately after the new process has been started, oth‐
12490 erwise the command will read as long as the pipes are
12491 open.
12492 env (MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING])
12494 Set a list of environment variables for the new process
12495 (default: empty). If an empty list is passed, the envi‐
12496 ronment of the mpv process is used instead. (Unlike the
12497 underlying OS mechanisms, the mpv command cannot start a
12498 process with empty environment. Fortunately, that is com‐
12499 pletely useless.) The format of the list is as in the ex‐
12500 ecle() syscall. Each string item defines an environment
12501 variable as in NAME=VALUE.
12502 On Lua, you may use utils.get_env_list() to retrieve the
12504 current environment if you e.g. simply want to add a new
12505 variable.
12506 stdin_data (MPV_FORMAT_STRING)
12508 Feed the given string to the new process' stdin. Since
12509 this is a string, you cannot pass arbitrary binary data.
12510 If the process terminates or closes the pipe before all
12511 data is written, the remaining data is silently dis‐
12512 carded. Probably does not work on win32.
12513 passthrough_stdin (MPV_FORMAT_FLAG)
12515 If enabled, wire the new process' stdin to mpv's stdin
12516 (default: no). Before mpv 0.33.0, this argument did not
12517 exist, but the behavior was as if this was set to true.
12518 The command returns the following result (as MPV_FOR‐
12520 MAT_NODE_MAP):
12521 status (MPV_FORMAT_INT64)
12523 Typically this is the process exit code (0 or positive)
12524 if the process terminates normally, or negative for other
12525 errors (failed to start, terminated by mpv, and others).
12526 The meaning of negative values is undefined, other than
12527 meaning error (and does not correspond to OS low level
12528 exit status values).
12529 On Windows, it can happen that a negative return value is
12531 returned even if the process terminates normally, because
12532 the win32 UINT exit code is assigned to an int variable
12533 before being set as int64_t field in the result map. This
12534 might be fixed later.
12535 stdout (MPV_FORMAT_BYTE_ARRAY)
12537 Captured stdout stream, limited to capture_size.
12538 stderr (MPV_FORMAT_BYTE_ARRAY)
12540 Same as stdout, but for stderr.
12541 error_string (MPV_FORMAT_STRING)
12543 Empty string if the process terminated normally. The
12544 string killed if the process was terminated in an unusual
12545 way. The string init if the process could not be started.
12546 On Windows, killed is only returned when the process has
12548 been killed by mpv as a result of playback_only being set
12549 to true.
12550 killed_by_us (MPV_FORMAT_FLAG)
12552 Whether the process has been killed by mpv, for example
12553 as a result of playback_only being set to true, aborting
12554 the command (e.g. by mp.abort_async_command()), or if the
12555 player is about to exit.
12556 Note that the command itself will always return success as long
12558 as the parameters are correct. Whether the process could be
12559 spawned or whether it was somehow killed or returned an error
12560 status has to be queried from the result value.
12561 This command can be asynchronously aborted via API. Also see
12563 Asynchronous command details. Only the run command can start
12564 processes in a truly detached way.
12565 NOTE:
12567 The subprocess will always be terminated on player exit if it
12568 wasn't started in detached mode, even if playback_only is
12569 false.
12570 Warning
12572 Don't forget to set the playback_only field to false
12574 if you want the command to run while the player is in
12575 idle mode, or if you don't want the end of playback to
12576 kill the command.
12577 Example
12579 local r = mp.command_native({
12581 name = "subprocess",
12582 playback_only = false,
12583 capture_stdout = true,
12584 args = {"cat", "/proc/cpuinfo"},
12585 })
12586 if r.status == 0 then
12587 print("result: " .. r.stdout)
12588 end
12589 This is a fairly useless Lua example, which demonstrates how
12591 to run a process in a blocking manner, and retrieving its
12592 stdout output.
12593 quit [<code>]
12595 Exit the player. If an argument is given, it's used as process
12596 exit code.
12597 quit-watch-later [<code>]
12599 Exit player, and store current playback position. Playing that
12600 file later will seek to the previous position on start. The (op‐
12601 tional) argument is exactly as in the quit command. See RESUMING
12602 PLAYBACK.
12603 sub-add <url> [<flags> [<title> [<lang>]]]
12605 Load the given subtitle file or stream. By default, it is se‐
12606 lected as current subtitle after loading.
12607 The flags argument is one of the following values:
12609 <select>
12611 Select the subtitle immediately (default).
12612 <auto>
12614 Don't select the subtitle. (Or in some special situations,
12615 let the default stream selection mechanism decide.)
12616 <cached>
12618 Select the subtitle. If a subtitle with the same filename was
12619 already added, that one is selected, instead of loading a du‐
12620 plicate entry. (In this case, title/language are ignored,
12621 and if the was changed since it was loaded, these changes
12622 won't be reflected.)
12623 The title argument sets the track title in the UI.
12625 The lang argument sets the track language, and can also influ‐
12627 ence stream selection with flags set to auto.
12628 sub-remove [<id>]
12630 Remove the given subtitle track. If the id argument is missing,
12631 remove the current track. (Works on external subtitle files
12632 only.)
12633 sub-reload [<id>]
12635 Reload the given subtitle tracks. If the id argument is missing,
12636 reload the current track. (Works on external subtitle files
12637 only.)
12638 This works by unloading and re-adding the subtitle track.
12640 sub-step <skip> <flags>
12642 Change subtitle timing such, that the subtitle event after the
12643 next <skip> subtitle events is displayed. <skip> can be negative
12644 to step backwards.
12645 Secondary argument:
12647 primary (default)
12649 Steps through the primary subtitles.
12650 secondary
12652 Steps through the secondary subtitles.
12653 sub-seek <skip> <flags>
12655 Seek to the next (skip set to 1) or the previous (skip set to
12656 -1) subtitle. This is similar to sub-step, except that it seeks
12657 video and audio instead of adjusting the subtitle delay.
12658 Secondary argument:
12660 primary (default)
12662 Seeks through the primary subtitles.
12663 secondary
12665 Seeks through the secondary subtitles.
12666 For embedded subtitles (like with Matroska), this works only
12668 with subtitle events that have already been displayed, or are
12669 within a short prefetch range.
12670 print-text <text>
12672 Print text to stdout. The string can contain properties (see
12673 Property Expansion). Take care to put the argument in quotes.
12674 show-text <text> [<duration>|-1 [<level>]]
12676 Show text on the OSD. The string can contain properties, which
12677 are expanded as described in Property Expansion. This can be
12678 used to show playback time, filename, and so on.
12679 <duration>
12681 The time in ms to show the message for. By default, it
12682 uses the same value as --osd-duration.
12683 <level>
12685 The minimum OSD level to show the text at (see
12686 --osd-level).
12687 expand-text <string>
12689 Property-expand the argument and return the expanded string.
12690 This can be used only through the client API or from a script
12691 using mp.command_native. (see Property Expansion).
12692 expand-path "<string>"
12694 Expand a path's double-tilde placeholders into a platform-spe‐
12695 cific path. As expand-text, this can only be used through the
12696 client API or from a script using mp.command_native.
12697 Example
12699 mp.osd_message(mp.command_native({"expand-path",
12701 "~~home/"}))
12702 This line of Lua would show the location of the user's
12704 mpv configuration directory on the OSD.
12705 show-progress
12707 Show the progress bar, the elapsed time and the total duration
12708 of the file on the OSD.
12709 write-watch-later-config
12711 Write the resume config file that the quit-watch-later command
12712 writes, but continue playback normally.
12713 delete-watch-later-config [<filename>]
12715 Delete any existing resume config file that was written by
12716 quit-watch-later or write-watch-later-config. If a filename is
12717 specified, then the deleted config is for that file; otherwise,
12718 it is the same one as would be written by quit-watch-later or
12719 write-watch-later-config in the current circumstance.
12720 stop [<flags>]
12722 Stop playback and clear playlist. With default settings, this is
12723 essentially like quit. Useful for the client API: playback can
12724 be stopped without terminating the player.
12725 The first argument is optional, and supports the following
12727 flags:
12728 keep-playlist
12730 Do not clear the playlist.
12731 mouse <x> <y> [<button> [<mode>]]
12733 Send a mouse event with given coordinate (<x>, <y>).
12734 Second argument:
12736 <button>
12738 The button number of clicked mouse button. This should be
12739 one of 0-19. If <button> is omitted, only the position
12740 will be updated.
12741 Third argument:
12743 <single> (default)
12745 The mouse event represents regular single click.
12746 <double>
12748 The mouse event represents double-click.
12749 keypress <name>
12751 Send a key event through mpv's input handler, triggering what‐
12752 ever behavior is configured to that key. name uses the in‐
12753 put.conf naming scheme for keys and modifiers. Useful for the
12754 client API: key events can be sent to libmpv to handle inter‐
12755 nally.
12756 keydown <name>
12758 Similar to keypress, but sets the KEYDOWN flag so that if the
12759 key is bound to a repeatable command, it will be run repeatedly
12760 with mpv's key repeat timing until the keyup command is called.
12761 keyup [<name>]
12763 Set the KEYUP flag, stopping any repeated behavior that had been
12764 triggered. name is optional. If name is not given or is an empty
12765 string, KEYUP will be set on all keys. Otherwise, KEYUP will
12766 only be set on the key specified by name.
12767 keybind <name> <command>
12769 Binds a key to an input command. command must be a complete com‐
12770 mand containing all the desired arguments and flags. Both name
12771 and command use the input.conf naming scheme. This is primarily
12772 useful for the client API.
12773 audio-add <url> [<flags> [<title> [<lang>]]]
12775 Load the given audio file. See sub-add command.
12776 audio-remove [<id>]
12778 Remove the given audio track. See sub-remove command.
12779 audio-reload [<id>]
12781 Reload the given audio tracks. See sub-reload command.
12782 video-add <url> [<flags> [<title> [<lang> [<albumart>]]]]
12784 Load the given video file. See sub-add command for common op‐
12785 tions.
12786 albumart (MPV_FORMAT_FLAG)
12788 If enabled, mpv will load the given video as album art.
12789 video-remove [<id>]
12791 Remove the given video track. See sub-remove command.
12792 video-reload [<id>]
12794 Reload the given video tracks. See sub-reload command.
12795 rescan-external-files [<mode>]
12797 Rescan external files according to the current --sub-auto, --au‐
12798 dio-file-auto and --cover-art-auto settings. This can be used to
12799 auto-load external files after the file was loaded.
12800 The mode argument is one of the following:
12802 <reselect> (default)
12804 Select the default audio and subtitle streams, which typ‐
12805 ically selects external files with the highest prefer‐
12806 ence. (The implementation is not perfect, and could be
12807 improved on request.)
12808 <keep-selection>
12810 Do not change current track selections.
12811 Input Commands that are Possibly Subject to Change
12813 af <operation> <value>
12814 Change audio filter chain. See vf command.
12815 vf <operation> <value>
12817 Change video filter chain.
12818 The semantics are exactly the same as with option parsing (see
12820 VIDEO FILTERS). As such the text below is a redundant and incom‐
12821 plete summary.
12822 The first argument decides what happens:
12824 <set> Overwrite the previous filter chain with the new one.
12826 <add> Append the new filter chain to the previous one.
12828 <toggle>
12830 Check if the given filter (with the exact parameters) is
12831 already in the video chain. If it is, remove the filter.
12832 If it isn't, add the filter. (If several filters are
12833 passed to the command, this is done for each filter.)
12834 A special variant is combining this with labels, and us‐
12836 ing @name without filter name and parameters as filter
12837 entry. This toggles the enable/disable flag.
12838 <remove>
12840 Like toggle, but always remove the given filter from the
12841 chain.
12842 <del> Remove the given filters from the video chain. Unlike in
12844 the other cases, the second parameter is a comma sepa‐
12845 rated list of filter names or integer indexes. 0 would
12846 denote the first filter. Negative indexes start from the
12847 last filter, and -1 denotes the last filter. Deprecated,
12848 use remove.
12849 <clr> Remove all filters. Note that like the other sub-com‐
12851 mands, this does not control automatically inserted fil‐
12852 ters.
12853 The argument is always needed. E.g. in case of clr use vf clr
12855 "".
12856 You can assign labels to filter by prefixing them with @name:
12858 (where name is a user-chosen arbitrary identifier). Labels can
12859 be used to refer to filters by name in all of the filter chain
12860 modification commands. For add, using an already used label
12861 will replace the existing filter.
12862 The vf command shows the list of requested filters on the OSD
12864 after changing the filter chain. This is roughly equivalent to
12865 show-text ${vf}. Note that auto-inserted filters for format con‐
12866 version are not shown on the list, only what was requested by
12867 the user.
12868 Normally, the commands will check whether the video chain is
12870 recreated successfully, and will undo the operation on failure.
12871 If the command is run before video is configured (can happen if
12872 the command is run immediately after opening a file and before a
12873 video frame is decoded), this check can't be run. Then it can
12874 happen that creating the video chain fails.
12875 Example for input.conf
12877 • a vf set vflip turn the video upside-down on the a key
12879 • b vf set "" remove all video filters on b
12881 • c vf toggle gradfun toggle debanding on c
12883 Example how to toggle disabled filters at runtime
12885 • Add something like vf-add=@deband:!gradfun to mpv.conf.
12887 The @deband: is the label, an arbitrary, user-given name
12888 for this filter entry. The ! before the filter name dis‐
12889 ables the filter by default. Everything after this is the
12890 normal filter name and possibly filter parameters, like in
12891 the normal --vf syntax.
12892 • Add a vf toggle @deband to input.conf. This toggles the
12894 "disabled" flag for the filter with the label deband when
12895 the a key is hit.
12896 cycle-values [<"!reverse">] <property> <value1> [<value2> [...]]
12898 Cycle through a list of values. Each invocation of the command
12899 will set the given property to the next value in the list. The
12900 command will use the current value of the property/option, and
12901 use it to determine the current position in the list of values.
12902 Once it has found it, it will set the next value in the list
12903 (wrapping around to the first item if needed).
12904 This command has a variable number of arguments, and cannot be
12906 used with named arguments.
12907 The special argument !reverse can be used to cycle the value
12909 list in reverse. The only advantage is that you don't need to
12910 reverse the value list yourself when adding a second key binding
12911 for cycling backwards.
12912 enable-section <name> [<flags>]
12914 This command is deprecated, except for mpv-internal uses.
12915 Enable all key bindings in the named input section.
12917 The enabled input sections form a stack. Bindings in sections on
12919 the top of the stack are preferred to lower sections. This com‐
12920 mand puts the section on top of the stack. If the section was
12921 already on the stack, it is implicitly removed beforehand. (A
12922 section cannot be on the stack more than once.)
12923 The flags parameter can be a combination (separated by +) of the
12925 following flags:
12926 <exclusive>
12928 All sections enabled before the newly enabled section are
12929 disabled. They will be re-enabled as soon as all exclu‐
12930 sive sections above them are removed. In other words, the
12931 new section shadows all previous sections.
12932 <allow-hide-cursor>
12934 This feature can't be used through the public API.
12935 <allow-vo-dragging>
12937 Same.
12938 disable-section <name>
12940 This command is deprecated, except for mpv-internal uses.
12941 Disable the named input section. Undoes enable-section.
12943 define-section <name> <contents> [<flags>]
12945 This command is deprecated, except for mpv-internal uses.
12946 Create a named input section, or replace the contents of an al‐
12948 ready existing input section. The contents parameter uses the
12949 same syntax as the input.conf file (except that using the sec‐
12950 tion syntax in it is not allowed), including the need to sepa‐
12951 rate bindings with a newline character.
12952 If the contents parameter is an empty string, the section is re‐
12954 moved.
12955 The section with the name default is the normal input section.
12957 In general, input sections have to be enabled with the en‐
12959 able-section command, or they are ignored.
12960 The last parameter has the following meaning:
12962 <default> (also used if parameter omitted)
12964 Use a key binding defined by this section only if the
12965 user hasn't already bound this key to a command.
12966 <force>
12968 Always bind a key. (The input section that was made ac‐
12969 tive most recently wins if there are ambiguities.)
12970 This command can be used to dispatch arbitrary keys to a script
12972 or a client API user. If the input section defines script-bind‐
12973 ing commands, it is also possible to get separate events on key
12974 up/down, and relatively detailed information about the key
12975 state. The special key name unmapped can be used to match any
12976 unmapped key.
12977 overlay-add <id> <x> <y> <file> <offset> <fmt> <w> <h> <stride>
12979 Add an OSD overlay sourced from raw data. This might be useful
12980 for scripts and applications controlling mpv, and which want to
12981 display things on top of the video window.
12982 Overlays are usually displayed in screen resolution, but with
12984 some VOs, the resolution is reduced to that of the video's. You
12985 can read the osd-width and osd-height properties. At least with
12986 --vo-xv and anamorphic video (such as DVD), osd-par should be
12987 read as well, and the overlay should be aspect-compensated.
12988 This has the following named arguments. The order of them is not
12990 guaranteed, so you should always call them with named arguments,
12991 see Named arguments.
12992 id is an integer between 0 and 63 identifying the overlay ele‐
12994 ment. The ID can be used to add multiple overlay parts, update a
12995 part by using this command with an already existing ID, or to
12996 remove a part with overlay-remove. Using a previously unused ID
12997 will add a new overlay, while reusing an ID will update it.
12998 x and y specify the position where the OSD should be displayed.
13000 file specifies the file the raw image data is read from. It can
13002 be either a numeric UNIX file descriptor prefixed with @ (e.g.
13003 @4), or a filename. The file will be mapped into memory with
13004 mmap(), copied, and unmapped before the command returns (changed
13005 in mpv 0.18.1).
13006 It is also possible to pass a raw memory address for use as bit‐
13008 map memory by passing a memory address as integer prefixed with
13009 an & character. Passing the wrong thing here will crash the
13010 player. This mode might be useful for use with libmpv. The off‐
13011 set parameter is simply added to the memory address (since mpv
13012 0.8.0, ignored before).
13013 offset is the byte offset of the first pixel in the source file.
13015 (The current implementation always mmap's the whole file from
13016 position 0 to the end of the image, so large offsets should be
13017 avoided. Before mpv 0.8.0, the offset was actually passed di‐
13018 rectly to mmap, but it was changed to make using it easier.)
13019 fmt is a string identifying the image format. Currently, only
13021 bgra is defined. This format has 4 bytes per pixels, with 8 bits
13022 per component. The least significant 8 bits are blue, and the
13023 most significant 8 bits are alpha (in little endian, the compo‐
13024 nents are B-G-R-A, with B as first byte). This uses premulti‐
13025 plied alpha: every color component is already multiplied with
13026 the alpha component. This means the numeric value of each compo‐
13027 nent is equal to or smaller than the alpha component. (Violating
13028 this rule will lead to different results with different VOs: nu‐
13029 meric overflows resulting from blending broken alpha values is
13030 considered something that shouldn't happen, and consequently im‐
13031 plementations don't ensure that you get predictable behavior in
13032 this case.)
13033 w, h, and stride specify the size of the overlay. w is the visi‐
13035 ble width of the overlay, while stride gives the width in bytes
13036 in memory. In the simple case, and with the bgra format,
13037 stride==4*w. In general, the total amount of memory accessed is
13038 stride * h. (Technically, the minimum size would be stride * (h
13039 - 1) + w * 4, but for simplicity, the player will access all
13040 stride * h bytes.)
13041 NOTE:
13043 Before mpv 0.18.1, you had to do manual "double buffering"
13044 when updating an overlay by replacing it with a different
13045 memory buffer. Since mpv 0.18.1, the memory is simply copied
13046 and doesn't reference any of the memory indicated by the com‐
13047 mand's arguments after the command returns. If you want to
13048 use this command before mpv 0.18.1, reads the old docs to see
13049 how to handle this correctly.
13050 overlay-remove <id>
13052 Remove an overlay added with overlay-add and the same ID. Does
13053 nothing if no overlay with this ID exists.
13054 osd-overlay
13056 Add/update/remove an OSD overlay.
13057 (Although this sounds similar to overlay-add, osd-overlay is for
13059 text overlays, while overlay-add is for bitmaps. Maybe over‐
13060 lay-add will be merged into osd-overlay to remove this oddity.)
13061 You can use this to add text overlays in ASS format. ASS has ad‐
13063 vanced positioning and rendering tags, which can be used to ren‐
13064 der almost any kind of vector graphics.
13065 This command accepts the following parameters:
13067 id Arbitrary integer that identifies the overlay. Multiple
13069 overlays can be added by calling this command with dif‐
13070 ferent id parameters. Calling this command with the same
13071 id replaces the previously set overlay.
13072 There is a separate namespace for each libmpv client
13074 (i.e. IPC connection, script), so IDs can be made up and
13075 assigned by the API user without conflicting with other
13076 API users.
13077 If the libmpv client is destroyed, all overlays associ‐
13079 ated with it are also deleted. In particular, connecting
13080 via --input-ipc-server, adding an overlay, and discon‐
13081 necting will remove the overlay immediately again.
13082 format String that gives the type of the overlay. Accepts the
13084 following values (HTML rendering of this is broken, view
13085 the generated manpage instead, or the raw RST source):
13086 ass-events
13088 The data parameter is a string. The string is
13089 split on the newline character. Every line is
13090 turned into the Text part of a Dialogue ASS event.
13091 Timing is unused (but behavior of timing dependent
13092 ASS tags may change in future mpv versions).
13093 Note that it's better to put multiple lines into
13095 data, instead of adding multiple OSD overlays.
13096 This provides 2 ASS Styles. OSD contains the text
13098 style as defined by the current --osd-... options.
13099 Default is similar, and contains style that OSD
13100 would have if all options were set to the default.
13101 In addition, the res_x and res_y options specify
13103 the value of the ASS PlayResX and PlayResY header
13104 fields. If res_y is set to 0, PlayResY is initial‐
13105 ized to an arbitrary default value (but note that
13106 the default for this command is 720, not 0). If
13107 res_x is set to 0, PlayResX is set based on res_y
13108 such that a virtual ASS pixel has a square pixel
13109 aspect ratio.
13110 none Special value that causes the overlay to be re‐
13112 moved. Most parameters other than id and format
13113 are mostly ignored.
13114 data String defining the overlay contents according to the
13116 format parameter.
13117 res_x, res_y
13119 Used if format is set to ass-events (see description
13120 there). Optional, defaults to 0/720.
13121 z The Z order of the overlay. Optional, defaults to 0.
13123 Note that Z order between different overlays of different
13125 formats is static, and cannot be changed (currently, this
13126 means that bitmap overlays added by overlay-add are al‐
13127 ways on top of the ASS overlays added by osd-overlay). In
13128 addition, the builtin OSD components are always below any
13129 of the custom OSD. (This includes subtitles of any kind
13130 as well as text rendered by show-text.)
13131 It's possible that future mpv versions will randomly
13133 change how Z order between different OSD formats and
13134 builtin OSD is handled.
13135 hidden If set to true, do not display this (default: false).
13137 compute_bounds
13139 If set to true, attempt to determine bounds and write
13140 them to the command's result value as x0, x1, y0, y1 rec‐
13141 tangle (default: false). If the rectangle is empty, not
13142 known, or somehow degenerate, it is not set. x1/y1 is the
13143 coordinate of the bottom exclusive corner of the rectan‐
13144 gle.
13145 The result value may depend on the VO window size, and is
13147 based on the last known window size at the time of the
13148 call. This means the results may be different from what
13149 is actually rendered.
13150 For ass-events, the result rectangle is recomputed to
13152 PlayRes coordinates (res_x/res_y). If window size is not
13153 known, a fallback is chosen.
13154 You should be aware that this mechanism is very ineffi‐
13156 cient, as it renders the full result, and then uses the
13157 bounding box of the rendered bitmap list (even if hidden
13158 is set). It will flush various caches. Its results also
13159 depend on the used libass version.
13160 This feature is experimental, and may change in some way
13162 again.
13163 NOTE:
13165 Always use named arguments (mpv_command_node()). Lua scripts
13166 should use the mp.create_osd_overlay() helper instead of in‐
13167 voking this command directly.
13168 script-message [<arg1> [<arg2> [...]]]
13170 Send a message to all clients, and pass it the following list of
13171 arguments. What this message means, how many arguments it
13172 takes, and what the arguments mean is fully up to the receiver
13173 and the sender. Every client receives the message, so be careful
13174 about name clashes (or use script-message-to).
13175 This command has a variable number of arguments, and cannot be
13177 used with named arguments.
13178 script-message-to <target> [<arg1> [<arg2> [...]]]
13180 Same as script-message, but send it only to the client named
13181 <target>. Each client (scripts etc.) has a unique name. For ex‐
13182 ample, Lua scripts can get their name via mp.get_script_name().
13183 Note that client names only consist of alphanumeric characters
13184 and _.
13185 This command has a variable number of arguments, and cannot be
13187 used with named arguments.
13188 script-binding <name>
13190 Invoke a script-provided key binding. This can be used to remap
13191 key bindings provided by external Lua scripts.
13192 The argument is the name of the binding.
13194 It can optionally be prefixed with the name of the script, using
13196 / as separator, e.g. script-binding scriptname/bindingname. Note
13197 that script names only consist of alphanumeric characters and _.
13198 For completeness, here is how this command works internally. The
13200 details could change any time. On any matching key event,
13201 script-message-to or script-message is called (depending on
13202 whether the script name is included), with the following argu‐
13203 ments:
13204 1. The string key-binding.
13206 2. The name of the binding (as established above).
13208 3. The key state as string (see below).
13210 4. The key name (since mpv 0.15.0).
13212 5. The text the key would produce, or empty string if not appli‐
13214 cable.
13215 The 5th argument is only set if no modifiers are present (using
13217 the shift key with a letter is normally not emitted as having a
13218 modifier, and results in upper case text instead, but some back‐
13219 ends may mess up).
13220 The key state consists of 2 characters:
13222 1. One of d (key was pressed down), u (was released), r (key is
13224 still down, and was repeated; only if key repeat is enabled
13225 for this binding), p (key was pressed; happens if up/down
13226 can't be tracked).
13227 2. Whether the event originates from the mouse, either m (mouse
13229 button) or - (something else).
13230 Future versions can add more arguments and more key state char‐
13232 acters to support more input peculiarities.
13233 ab-loop
13235 Cycle through A-B loop states. The first command will set the A
13236 point (the ab-loop-a property); the second the B point, and the
13237 third will clear both points.
13238 drop-buffers
13240 Drop audio/video/demuxer buffers, and restart from fresh. Might
13241 help with unseekable streams that are going out of sync. This
13242 command might be changed or removed in the future.
13243 screenshot-raw [<flags>]
13245 Return a screenshot in memory. This can be used only through the
13246 client API. The MPV_FORMAT_NODE_MAP returned by this command has
13247 the w, h, stride fields set to obvious contents. The format
13248 field is set to bgr0 by default. This format is organized as
13249 B8G8R8X8 (where B is the LSB). The contents of the padding X are
13250 undefined. The data field is of type MPV_FORMAT_BYTE_ARRAY with
13251 the actual image data. The image is freed as soon as the result
13252 mpv_node is freed. As usual with client API semantics, you are
13253 not allowed to write to the image data.
13254 The stride is the number of bytes from a pixel at (x0, y0) to
13256 the pixel at (x0, y0 + 1). This can be larger than w * 4 if the
13257 image was cropped, or if there is padding. This number can be
13258 negative as well. You access a pixel with byte_index = y *
13259 stride + x * 4 (assuming the bgr0 format).
13260 The flags argument is like the first argument to screenshot and
13262 supports subtitles, video, window.
13263 vf-command <label> <command> <argument>
13265 Send a command to the filter with the given <label>. Use all to
13266 send it to all filters at once. The command and argument string
13267 is filter specific. Currently, this only works with the lavfi
13268 filter - see the libavfilter documentation for which commands a
13269 filter supports.
13270 Note that the <label> is a mpv filter label, not a libavfilter
13272 filter name.
13273 af-command <label> <command> <argument>
13275 Same as vf-command, but for audio filters.
13276 apply-profile <name> [<mode>]
13278 Apply the contents of a named profile. This is like using pro‐
13279 file=name in a config file, except you can map it to a key bind‐
13280 ing to change it at runtime.
13281 The mode argument:
13283 default
13285 Apply the profile. Default if the argument is omitted.
13286 restore
13288 Restore options set by a previous apply-profile command
13289 for this profile. Only works if the profile has pro‐
13290 file-restore set to a relevant mode. Prints a warning if
13291 nothing could be done. See Runtime profiles for details.
13292 load-script <filename>
13294 Load a script, similar to the --script option. Whether this
13295 waits for the script to finish initialization or not changed
13296 multiple times, and the future behavior is left undefined.
13297 On success, returns a mpv_node with a client_id field set to the
13299 return value of the mpv_client_id() API call of the newly cre‐
13300 ated script handle.
13301 change-list <name> <operation> <value>
13303 This command changes list options as described in List Options.
13304 The <name> parameter is the normal option name, while <opera‐
13305 tion> is the suffix or action used on the option.
13306 Some operations take no value, but the command still requires
13308 the value parameter. In these cases, the value must be an empty
13309 string.
13310 Example
13312 change-list glsl-shaders append file.glsl
13314 Add a filename to the glsl-shaders list. The command
13316 line equivalent is --glsl-shaders-append=file.glsl or
13317 alternatively --glsl-shader=file.glsl.
13318 dump-cache <start> <end> <filename>
13320 Dump the current cache to the given filename. The <filename>
13321 file is overwritten if it already exists. <start> and <end> give
13322 the time range of what to dump. If no data is cached at the
13323 given time range, nothing may be dumped (creating a file with no
13324 packets).
13325 Dumping a larger part of the cache will freeze the player. No
13327 effort was made to fix this, as this feature was meant mostly
13328 for creating small excerpts.
13329 See --stream-record for various caveats that mostly apply to
13331 this command too, as both use the same underlying code for writ‐
13332 ing the output file.
13333 If <filename> is an empty string, an ongoing dump-cache is
13335 stopped.
13336 If <end> is no, then continuous dumping is enabled. Then, after
13338 dumping the existing parts of the cache, anything read from net‐
13339 work is appended to the cache as well. This behaves similar to
13340 --stream-record (although it does not conflict with that option,
13341 and they can be both active at the same time).
13342 If the <end> time is after the cache, the command will _not_
13344 wait and write newly received data to it.
13345 The end of the resulting file may be slightly damaged or incom‐
13347 plete at the end. (Not enough effort was made to ensure that the
13348 end lines up properly.)
13349 Note that this command will finish only once dumping ends. That
13351 means it works similar to the screenshot command, just that it
13352 can block much longer. If continuous dumping is used, the com‐
13353 mand will not finish until playback is stopped, an error hap‐
13354 pens, another dump-cache command is run, or an API like
13355 mp.abort_async_command was called to explicitly stop the com‐
13356 mand. See Synchronous vs. Asynchronous.
13357 NOTE:
13359 This was mostly created for network streams. For local files,
13360 there may be much better methods to create excerpts and such.
13361 There are tons of much more user-friendly Lua scripts, that
13362 will re-encode parts of a file by spawning a separate in‐
13363 stance of ffmpeg. With network streams, this is not that eas‐
13364 ily possible, as the stream would have to be downloaded
13365 again. Even if --stream-record is used to record the stream
13366 to the local filesystem, there may be problems, because the
13367 recorded file is still written to.
13368 This command is experimental, and all details about it may
13370 change in the future.
13371 ab-loop-dump-cache <filename>
13373 Essentially calls dump-cache with the current AB-loop points as
13374 arguments. Like dump-cache, this will overwrite the file at
13375 <filename>. Likewise, if the B point is set to no, it will enter
13376 continuous dumping after the existing cache was dumped.
13377 The author reserves the right to remove this command if enough
13379 motivation is found to move this functionality to a trivial Lua
13380 script.
13381 ab-loop-align-cache
13383 Re-adjust the A/B loop points to the start and end within the
13384 cache the ab-loop-dump-cache command will (probably) dump. Basi‐
13385 cally, it aligns the times on keyframes. The guess might be off
13386 especially at the end (due to granularity issues due to remux‐
13387 ing). If the cache shrinks in the meantime, the points set by
13388 the command will not be the effective parameters either.
13389 This command has an even more uncertain future than
13391 ab-loop-dump-cache and might disappear without replacement if
13392 the author decides it's useless.
13393 Undocumented commands: ao-reload (experimental/internal).
13395 List of events
13397 This is a partial list of events. This section describes what
13398 mpv_event_to_node() returns, and which is what scripting APIs and the
13399 JSON IPC sees. Note that the C API has separate C-level declarations
13400 with mpv_event, which may be slightly different.
13401 Note that events are asynchronous: the player core continues running
13403 while events are delivered to scripts and other clients. In some cases,
13404 you can use hooks to enforce synchronous execution.
13405 All events can have the following fields:
13407 event Name as the event (as returned by mpv_event_name()).
13409 id The reply_userdata field (opaque user value). If reply_userdata
13411 is 0, the field is not added.
13412 error Set to an error string (as returned by mpv_error_string()). This
13414 field is missing if no error happened, or the event type does
13415 not report error. Most events leave this unset.
13416 This list uses the event name field value, and the C API symbol in
13418 brackets:
13419 start-file (MPV_EVENT_START_FILE)
13421 Happens right before a new file is loaded. When you receive
13422 this, the player is loading the file (or possibly already done
13423 with it).
13424 This has the following fields:
13426 playlist_entry_id
13428 Playlist entry ID of the file being loaded now.
13429 end-file (MPV_EVENT_END_FILE)
13431 Happens after a file was unloaded. Typically, the player will
13432 load the next file right away, or quit if this was the last
13433 file.
13434 The event has the following fields:
13436 reason Has one of these values:
13438 eof The file has ended. This can (but doesn't have to)
13440 include incomplete files or broken network connec‐
13441 tions under circumstances.
13442 stop Playback was ended by a command.
13444 quit Playback was ended by sending the quit command.
13446 error An error happened. In this case, an error field is
13448 present with the error string.
13449 redirect
13451 Happens with playlists and similar. Details see
13452 MPV_END_FILE_REASON_REDIRECT in the C API.
13453 unknown
13455 Unknown. Normally doesn't happen, unless the Lua
13456 API is out of sync with the C API. (Likewise, it
13457 could happen that your script gets reason strings
13458 that did not exist yet at the time your script was
13459 written.)
13460 playlist_entry_id
13462 Playlist entry ID of the file that was being played or
13463 attempted to be played. This has the same value as the
13464 playlist_entry_id field in the corresponding start-file
13465 event.
13466 file_error
13468 Set to mpv error string describing the approximate reason
13469 why playback failed. Unset if no error known. (In Lua
13470 scripting, this value was set on the error field di‐
13471 rectly. This is deprecated since mpv 0.33.0. In the fu‐
13472 ture, this error field will be unset for this specific
13473 event.)
13474 playlist_insert_id
13476 If loading ended, because the playlist entry to be played
13477 was for example a playlist, and the current playlist en‐
13478 try is replaced with a number of other entries. This may
13479 happen at least with MPV_END_FILE_REASON_REDIRECT (other
13480 event types may use this for similar but different pur‐
13481 poses in the future). In this case, playlist_insert_id
13482 will be set to the playlist entry ID of the first in‐
13483 serted entry, and playlist_insert_num_entries to the to‐
13484 tal number of inserted playlist entries. Note this in
13485 this specific case, the ID of the last inserted entry is
13486 playlist_insert_id+num-1. Beware that depending on cir‐
13487 cumstances, you may observe the new playlist entries be‐
13488 fore seeing the event (e.g. reading the "playlist" prop‐
13489 erty or getting a property change notification before re‐
13490 ceiving the event). If this is 0 in the C API, this
13491 field isn't added.
13492 playlist_insert_num_entries
13494 See playlist_insert_id. Only present if playlist_in‐
13495 sert_id is present.
13496 file-loaded (MPV_EVENT_FILE_LOADED)
13498 Happens after a file was loaded and begins playback.
13499 seek (MPV_EVENT_SEEK)
13501 Happens on seeking. (This might include cases when the player
13502 seeks internally, even without user interaction. This includes
13503 e.g. segment changes when playing ordered chapters Matroska
13504 files.)
13505 playback-restart (MPV_EVENT_PLAYBACK_RESTART)
13507 Start of playback after seek or after file was loaded.
13508 shutdown (MPV_EVENT_SHUTDOWN)
13510 Sent when the player quits, and the script should terminate.
13511 Normally handled automatically. See Details on the script ini‐
13512 tialization and lifecycle.
13513 log-message (MPV_EVENT_LOG_MESSAGE)
13515 Receives messages enabled with mpv_request_log_messages() (Lua:
13516 mp.enable_messages).
13517 This contains, in addition to the default event fields, the fol‐
13519 lowing fields:
13520 prefix The module prefix, identifies the sender of the message.
13522 This is what the terminal player puts in front of the
13523 message text when using the --v option, and is also what
13524 is used for --msg-level.
13525 level The log level as string. See msg.log for possible log
13527 level names. Note that later versions of mpv might add
13528 new levels or remove (undocumented) existing ones.
13529 text The log message. The text will end with a newline charac‐
13531 ter. Sometimes it can contain multiple lines.
13532 Keep in mind that these messages are meant to be hints for hu‐
13534 mans. You should not parse them, and prefix/level/text of mes‐
13535 sages might change any time.
13536 hook The event has the following fields:
13538 hook_id
13540 ID to pass to mpv_hook_continue(). The Lua scripting
13541 wrapper provides a better API around this with
13542 mp.add_hook().
13543 get-property-reply (MPV_EVENT_GET_PROPERTY_REPLY)
13545 See C API.
13546 set-property-reply (MPV_EVENT_SET_PROPERTY_REPLY)
13548 See C API.
13549 command-reply (MPV_EVENT_COMMAND_REPLY)
13551 This is one of the commands for which the `error field is mean‐
13552 ingful.
13553 JSON IPC and Lua and possibly other backends treat this spe‐
13555 cially and may not pass the actual event to the user. See C API.
13556 The event has the following fields:
13558 result The result (on success) of any mpv_node type, if any.
13560 client-message (MPV_EVENT_CLIENT_MESSAGE)
13562 Lua and possibly other backends treat this specially and may not
13563 pass the actual event to the user.
13564 The event has the following fields:
13566 args Array of strings with the message data.
13568 video-reconfig (MPV_EVENT_VIDEO_RECONFIG)
13570 Happens on video output or filter reconfig.
13571 audio-reconfig (MPV_EVENT_AUDIO_RECONFIG)
13573 Happens on audio output or filter reconfig.
13574 property-change (MPV_EVENT_PROPERTY_CHANGE)
13576 Happens when a property that is being observed changes value.
13577 The event has the following fields:
13579 name The name of the property.
13581 data The new value of the property.
13583 The following events also happen, but are deprecated: idle, tick Use
13585 mpv_observe_property() (Lua: mp.observe_property()) instead.
13586 Hooks
13588 Hooks are synchronous events between player core and a script or simi‐
13589 lar. This applies to client API (including the Lua scripting inter‐
13590 face). Normally, events are supposed to be asynchronous, and the hook
13591 API provides an awkward and obscure way to handle events that require
13592 stricter coordination. There are no API stability guarantees made. Not
13593 following the protocol exactly can make the player freeze randomly. Ba‐
13594 sically, nobody should use this API.
13595 The C API is described in the header files. The Lua API is described in
13597 the Lua section.
13598 Before a hook is actually invoked on an API clients, it will attempt to
13600 return new values for all observed properties that were changed before
13601 the hook. This may make it easier for an application to set defined
13602 "barriers" between property change notifications by registering hooks.
13603 (That means these hooks will have an effect, even if you do nothing and
13604 make them continue immediately.)
13605 The following hooks are currently defined:
13607 on_load
13609 Called when a file is to be opened, before anything is actually
13610 done. For example, you could read and write the
13611 stream-open-filename property to redirect an URL to something
13612 else (consider support for streaming sites which rarely give the
13613 user a direct media URL), or you could set per-file options with
13614 by setting the property file-local-options/<option name>. The
13615 player will wait until all hooks are run.
13616 Ordered after start-file and before playback-restart.
13618 on_load_fail
13620 Called after after a file has been opened, but failed to. This
13621 can be used to provide a fallback in case native demuxers failed
13622 to recognize the file, instead of always running before the na‐
13623 tive demuxers like on_load. Demux will only be retried if
13624 stream-open-filename was changed. If it fails again, this hook
13625 is _not_ called again, and loading definitely fails.
13626 Ordered after on_load, and before playback-restart and end-file.
13628 on_preloaded
13630 Called after a file has been opened, and before tracks are se‐
13631 lected and decoders are created. This has some usefulness if an
13632 API users wants to select tracks manually, based on the set of
13633 available tracks. It's also useful to initialize --lavfi-complex
13634 in a specific way by API, without having to "probe" the avail‐
13635 able streams at first.
13636 Note that this does not yet apply default track selection. Which
13638 operations exactly can be done and not be done, and what infor‐
13639 mation is available and what is not yet available yet, is all
13640 subject to change.
13641 Ordered after on_load_fail etc. and before playback-restart.
13643 on_unload
13645 Run before closing a file, and before actually uninitializing
13646 everything. It's not possible to resume playback in this state.
13647 Ordered before end-file. Will also happen in the error case
13649 (then after on_load_fail).
13650 on_before_start_file
13652 Run before a start-file event is sent. (If any client changes
13653 the current playlist entry, or sends a quit command to the
13654 player, the corresponding event will not actually happen after
13655 the hook returns.) Useful to drain property changes before a
13656 new file is loaded.
13657 on_after_end_file
13659 Run after an end-file event. Useful to drain property changes
13660 after a file has finished.
13661 Input Command Prefixes
13663 These prefixes are placed between key name and the actual command. Mul‐
13664 tiple prefixes can be specified. They are separated by whitespace.
13665 osd-auto
13667 Use the default behavior for this command. This is the default
13668 for input.conf commands. Some libmpv/scripting/IPC APIs do not
13669 use this as default, but use no-osd instead.
13670 no-osd Do not use any OSD for this command.
13672 osd-bar
13674 If possible, show a bar with this command. Seek commands will
13675 show the progress bar, property changing commands may show the
13676 newly set value.
13677 osd-msg
13679 If possible, show an OSD message with this command. Seek command
13680 show the current playback time, property changing commands show
13681 the newly set value as text.
13682 osd-msg-bar
13684 Combine osd-bar and osd-msg.
13685 raw Do not expand properties in string arguments. (Like "${prop‐
13687 erty-name}".) This is the default for some libmpv/scripting/IPC
13688 APIs.
13689 expand-properties
13691 All string arguments are expanded as described in Property Ex‐
13692 pansion. This is the default for input.conf commands.
13693 repeatable
13695 For some commands, keeping a key pressed doesn't run the command
13696 repeatedly. This prefix forces enabling key repeat in any case.
13697 For a list of commands: the first command determines the re‐
13698 peatability of the whole list (up to and including version 0.33
13699 - a list was always repeatable).
13700 async Allow asynchronous execution (if possible). Note that only a few
13702 commands will support this (usually this is explicitly docu‐
13703 mented). Some commands are asynchronous by default (or rather,
13704 their effects might manifest after completion of the command).
13705 The semantics of this flag might change in the future. Set it
13706 only if you don't rely on the effects of this command being
13707 fully realized when it returns. See Synchronous vs. Asynchro‐
13708 nous.
13709 sync Allow synchronous execution (if possible). Normally, all com‐
13711 mands are synchronous by default, but some are asynchronous by
13712 default for compatibility with older behavior.
13713 All of the osd prefixes are still overridden by the global --osd-level
13715 settings.
13716 Synchronous vs. Asynchronous
13718 The async and sync prefix matter only for how the issuer of the command
13719 waits on the completion of the command. Normally it does not affect how
13720 the command behaves by itself. There are the following cases:
13721 • Normal input.conf commands are always run asynchronously. Slow run‐
13723 ning commands are queued up or run in parallel.
13724 • "Multi" input.conf commands (1 key binding, concatenated with ;) will
13726 be executed in order, except for commands that are async (either pre‐
13727 fixed with async, or async by default for some commands). The async
13728 commands are run in a detached manner, possibly in parallel to the
13729 remaining sync commands in the list.
13730 • Normal Lua and libmpv commands (e.g. mpv_command()) are run in a
13732 blocking manner, unless the async prefix is used, or the command is
13733 async by default. This means in the sync case the caller will block,
13734 even if the core continues playback. Async mode runs the command in a
13735 detached manner.
13736 • Async libmpv command API (e.g. mpv_command_async()) never blocks the
13738 caller, and always notify their completion with a message. The sync
13739 and async prefixes make no difference.
13740 • Lua also provides APIs for running async commands, which behave simi‐
13742 lar to the C counterparts.
13743 • In all cases, async mode can still run commands in a synchronous man‐
13745 ner, even in detached mode. This can for example happen in cases when
13746 a command does not have an asynchronous implementation. The async
13747 libmpv API still never blocks the caller in these cases.
13748 Before mpv 0.29.0, the async prefix was only used by screenshot com‐
13750 mands, and made them run the file saving code in a detached manner.
13751 This is the default now, and async changes behavior only in the ways
13752 mentioned above.
13753 Currently the following commands have different waiting characteristics
13755 with sync vs. async: sub-add, audio-add, sub-reload, audio-reload, res‐
13756 can-external-files, screenshot, screenshot-to-file, dump-cache,
13757 ab-loop-dump-cache.
13758 Asynchronous command details
13760 On the API level, every asynchronous command is bound to the context
13761 which started it. For example, an asynchronous command started by
13762 mpv_command_async is bound to the mpv_handle passed to the function.
13763 Only this mpv_handle receives the completion notification
13764 (MPV_EVENT_COMMAND_REPLY), and only this handle can abort a still run‐
13765 ning command directly. If the mpv_handle is destroyed, any still run‐
13766 ning async. commands started by it are terminated.
13767 The scripting APIs and JSON IPC give each script/connection its own im‐
13769 plicit mpv_handle.
13770 If the player is closed, the core may abort all pending async. commands
13772 on its own (like a forced mpv_abort_async_command() call for each pend‐
13773 ing command on behalf of the API user). This happens at the same time
13774 MPV_EVENT_SHUTDOWN is sent, and there is no way to prevent this.
13775 Input Sections
13777 Input sections group a set of bindings, and enable or disable them at
13778 once. In input.conf, each key binding is assigned to an input section,
13779 rather than actually having explicit text sections.
13780 See also: enable-section and disable-section commands.
13782 Predefined bindings:
13784 default
13786 Bindings without input section are implicitly assigned to this
13787 section. It is enabled by default during normal playback.
13788 encode Section which is active in encoding mode. It is enabled exclu‐
13790 sively, so that bindings in the default sections are ignored.
13791 Properties
13793 Properties are used to set mpv options during runtime, or to query ar‐
13794 bitrary information. They can be manipulated with the set/add/cycle
13795 commands, and retrieved with show-text, or anything else that uses
13796 property expansion. (See Property Expansion.)
13797 The property name is annotated with RW to indicate whether the property
13799 is generally writable.
13800 If an option is referenced, the property will normally take/return ex‐
13802 actly the same values as the option. In these cases, properties are
13803 merely a way to change an option at runtime.
13804 Property list
13806 NOTE:
13807 Most options can be set at runtime via properties as well. Just re‐
13808 move the leading -- from the option name. These are not documented
13809 below, see OPTIONS instead. Only properties which do not exist as
13810 option with the same name, or which have very different behavior
13811 from the options are documented below.
13812 Properties marked as (RW) are writeable, while those that aren't are
13814 read-only.
13815 audio-speed-correction, video-speed-correction
13817 Factor multiplied with speed at which the player attempts to
13818 play the file. Usually it's exactly 1. (Display sync mode will
13819 make this useful.)
13820 OSD formatting will display it in the form of +1.23456%, with
13822 the number being (raw - 1) * 100 for the given raw property
13823 value.
13824 display-sync-active
13826 Whether --video-sync=display is actually active.
13827 filename
13829 Currently played file, with path stripped. If this is an URL,
13830 try to undo percent encoding as well. (The result is not neces‐
13831 sarily correct, but looks better for display purposes. Use the
13832 path property to get an unmodified filename.)
13833 This has a sub-property:
13835 filename/no-ext
13837 Like the filename property, but if the text contains a .,
13838 strip all text after the last .. Usually this removes the
13839 file extension.
13840 file-size
13842 Length in bytes of the source file/stream. (This is the same as
13843 ${stream-end}. For segmented/multi-part files, this will return
13844 the size of the main or manifest file, whatever it is.)
13845 estimated-frame-count
13847 Total number of frames in current file.
13848 NOTE:
13850 This is only an estimate. (It's computed from two unreliable
13851 quantities: fps and stream length.)
13852 estimated-frame-number
13854 Number of current frame in current stream.
13855 NOTE:
13857 This is only an estimate. (It's computed from two unreliable
13858 quantities: fps and possibly rounded timestamps.)
13859 pid Process-id of mpv.
13861 path Full path of the currently played file. Usually this is exactly
13863 the same string you pass on the mpv command line or the loadfile
13864 command, even if it's a relative path. If you expect an absolute
13865 path, you will have to determine it yourself, for example by us‐
13866 ing the working-directory property.
13867 stream-open-filename
13869 The full path to the currently played media. This is different
13870 from path only in special cases. In particular, if --ytdl=yes is
13871 used, and the URL is detected by youtube-dl, then the script
13872 will set this property to the actual media URL. This property
13873 should be set only during the on_load or on_load_fail hooks,
13874 otherwise it will have no effect (or may do something implemen‐
13875 tation defined in the future). The property is reset if playback
13876 of the current media ends.
13877 media-title
13879 If the currently played file has a title tag, use that.
13880 Otherwise, return the filename property.
13882 file-format
13884 Symbolic name of the file format. In some cases, this is a
13885 comma-separated list of format names, e.g. mp4 is
13886 mov,mp4,m4a,3gp,3g2,mj2 (the list may grow in the future for any
13887 format).
13888 current-demuxer
13890 Name of the current demuxer. (This is useless.)
13891 (Renamed from demuxer.)
13893 stream-path
13895 Filename (full path) of the stream layer filename. (This is
13896 probably useless and is almost never different from path.)
13897 stream-pos
13899 Raw byte position in source stream. Technically, this returns
13900 the position of the most recent packet passed to a decoder.
13901 stream-end
13903 Raw end position in bytes in source stream.
13904 duration
13906 Duration of the current file in seconds. If the duration is un‐
13907 known, the property is unavailable. Note that the file duration
13908 is not always exactly known, so this is an estimate.
13909 This replaces the length property, which was deprecated after
13911 the mpv 0.9 release. (The semantics are the same.)
13912 avsync Last A/V synchronization difference. Unavailable if audio or
13914 video is disabled.
13915 total-avsync-change
13917 Total A-V sync correction done. Unavailable if audio or video is
13918 disabled.
13919 decoder-frame-drop-count
13921 Video frames dropped by decoder, because video is too far behind
13922 audio (when using --framedrop=decoder). Sometimes, this may be
13923 incremented in other situations, e.g. when video packets are
13924 damaged, or the decoder doesn't follow the usual rules. Unavail‐
13925 able if video is disabled.
13926 drop-frame-count is a deprecated alias.
13928 frame-drop-count
13930 Frames dropped by VO (when using --framedrop=vo).
13931 vo-drop-frame-count is a deprecated alias.
13933 mistimed-frame-count
13935 Number of video frames that were not timed correctly in dis‐
13936 play-sync mode for the sake of keeping A/V sync. This does not
13937 include external circumstances, such as video rendering being
13938 too slow or the graphics driver somehow skipping a vsync. It
13939 does not include rounding errors either (which can happen espe‐
13940 cially with bad source timestamps). For example, using the dis‐
13941 play-desync mode should never change this value from 0.
13942 vsync-ratio
13944 For how many vsyncs a frame is displayed on average. This is
13945 available if display-sync is active only. For 30 FPS video on a
13946 60 Hz screen, this will be 2. This is the moving average of what
13947 actually has been scheduled, so 24 FPS on 60 Hz will never re‐
13948 main exactly on 2.5, but jitter depending on the last frame dis‐
13949 played.
13950 vo-delayed-frame-count
13952 Estimated number of frames delayed due to external circumstances
13953 in display-sync mode. Note that in general, mpv has to guess
13954 that this is happening, and the guess can be inaccurate.
13955 percent-pos (RW)
13957 Position in current file (0-100). The advantage over using this
13958 instead of calculating it out of other properties is that it
13959 properly falls back to estimating the playback position from the
13960 byte position, if the file duration is not known.
13961 time-pos (RW)
13963 Position in current file in seconds.
13964 time-start
13966 Deprecated. Always returns 0. Before mpv 0.14, this used to re‐
13967 turn the start time of the file (could affect e.g. transport
13968 streams). See --rebase-start-time option.
13969 time-remaining
13971 Remaining length of the file in seconds. Note that the file du‐
13972 ration is not always exactly known, so this is an estimate.
13973 audio-pts
13975 Current audio playback position in current file in seconds. Un‐
13976 like time-pos, this updates more often than once per frame. For
13977 audio-only files, it is mostly equivalent to time-pos, while for
13978 video-only files this property is not available.
13979 playtime-remaining
13981 time-remaining scaled by the current speed.
13982 playback-time (RW)
13984 Position in current file in seconds. Unlike time-pos, the time
13985 is clamped to the range of the file. (Inaccurate file durations
13986 etc. could make it go out of range. Useful on attempts to seek
13987 outside of the file, as the seek target time is considered the
13988 current position during seeking.)
13989 chapter (RW)
13991 Current chapter number. The number of the first chapter is 0.
13992 edition (RW)
13994 Current MKV edition number. Setting this property to a different
13995 value will restart playback. The number of the first edition is
13996 0.
13997 Before mpv 0.31.0, this showed the actual edition selected at
13999 runtime, if you didn't set the option or property manually. With
14000 mpv 0.31.0 and later, this strictly returns the user-set option
14001 or property value, and the current-edition property was added to
14002 return the runtime selected edition (this matters with --edi‐
14003 tion=auto, the default).
14004 current-edition
14006 Currently selected edition. This property is unavailable if no
14007 file is loaded, or the file has no editions. (Matroska files
14008 make a difference between having no editions and a single edi‐
14009 tion, which will be reflected by the property, although in prac‐
14010 tice it does not matter.)
14011 chapters
14013 Number of chapters.
14014 editions
14016 Number of MKV editions.
14017 edition-list
14019 List of editions, current entry marked. Currently, the raw prop‐
14020 erty value is useless.
14021 This has a number of sub-properties. Replace N with the 0-based
14023 edition index.
14024 edition-list/count
14026 Number of editions. If there are no editions, this can be
14027 0 or 1 (1 if there's a useless dummy edition).
14028 edition-list/N/id (RW)
14030 Edition ID as integer. Use this to set the edition prop‐
14031 erty. Currently, this is the same as the edition index.
14032 edition-list/N/default
14034 Whether this is the default edition.
14035 edition-list/N/title
14037 Edition title as stored in the file. Not always avail‐
14038 able.
14039 When querying the property with the client API using MPV_FOR‐
14041 MAT_NODE, or with Lua mp.get_property_native, this will return a
14042 mpv_node with the following contents:
14043 MPV_FORMAT_NODE_ARRAY
14045 MPV_FORMAT_NODE_MAP (for each edition)
14046 "id" MPV_FORMAT_INT64
14047 "title" MPV_FORMAT_STRING
14048 "default" MPV_FORMAT_FLAG
14049 metadata
14051 Metadata key/value pairs.
14052 If the property is accessed with Lua's mp.get_property_native,
14054 this returns a table with metadata keys mapping to metadata val‐
14055 ues. If it is accessed with the client API, this returns a
14056 MPV_FORMAT_NODE_MAP, with tag keys mapping to tag values.
14057 For OSD, it returns a formatted list. Trying to retrieve this
14059 property as a raw string doesn't work.
14060 This has a number of sub-properties:
14062 metadata/by-key/<key>
14064 Value of metadata entry <key>.
14065 metadata/list/count
14067 Number of metadata entries.
14068 metadata/list/N/key
14070 Key name of the Nth metadata entry. (The first entry is
14071 0).
14072 metadata/list/N/value
14074 Value of the Nth metadata entry.
14075 metadata/<key>
14077 Old version of metadata/by-key/<key>. Use is discouraged,
14078 because the metadata key string could conflict with other
14079 sub-properties.
14080 The layout of this property might be subject to change. Sugges‐
14082 tions are welcome how exactly this property should work.
14083 When querying the property with the client API using MPV_FOR‐
14085 MAT_NODE, or with Lua mp.get_property_native, this will return a
14086 mpv_node with the following contents:
14087 MPV_FORMAT_NODE_MAP
14089 (key and string value for each metadata entry)
14090 filtered-metadata
14092 Like metadata, but includes only fields listed in the --dis‐
14093 play-tags option. This is the same set of tags that is printed
14094 to the terminal.
14095 chapter-metadata
14097 Metadata of current chapter. Works similar to metadata property.
14098 It also allows the same access methods (using sub-properties).
14099 Per-chapter metadata is very rare. Usually, only the chapter
14101 name (title) is set.
14102 For accessing other information, like chapter start, see the
14104 chapter-list property.
14105 vf-metadata/<filter-label>
14107 Metadata added by video filters. Accessed by the filter label,
14108 which, if not explicitly specified using the @filter-label: syn‐
14109 tax, will be <filter-name>NN.
14110 Works similar to metadata property. It allows the same access
14112 methods (using sub-properties).
14113 An example of this kind of metadata are the cropping parameters
14115 added by --vf=lavfi=cropdetect.
14116 af-metadata/<filter-label>
14118 Equivalent to vf-metadata/<filter-label>, but for audio filters.
14119 idle-active
14121 Returns yes/true if no file is loaded, but the player is staying
14122 around because of the --idle option.
14123 (Renamed from idle.)
14125 core-idle
14127 Whether the playback core is paused. This can differ from pause
14128 in special situations, such as when the player pauses itself due
14129 to low network cache.
14130 This also returns yes/true if playback is restarting or if noth‐
14132 ing is playing at all. In other words, it's only no/false if
14133 there's actually video playing. (Behavior since mpv 0.7.0.)
14134 cache-speed
14136 Current I/O read speed between the cache and the lower layer
14137 (like network). This gives the number bytes per seconds over a
14138 1 second window (using the type MPV_FORMAT_INT64 for the client
14139 API).
14140 This is the same as demuxer-cache-state/raw-input-rate.
14142 demuxer-cache-duration
14144 Approximate duration of video buffered in the demuxer, in sec‐
14145 onds. The guess is very unreliable, and often the property will
14146 not be available at all, even if data is buffered.
14147 demuxer-cache-time
14149 Approximate time of video buffered in the demuxer, in seconds.
14150 Same as demuxer-cache-duration but returns the last timestamp of
14151 buffered data in demuxer.
14152 demuxer-cache-idle
14154 Whether the demuxer is idle, which means that the demuxer cache
14155 is filled to the requested amount, and is currently not reading
14156 more data.
14157 demuxer-cache-state
14159 Each entry in seekable-ranges represents a region in the demuxer
14160 cache that can be seeked to, with a start and end fields con‐
14161 taining the respective timestamps. If there are multiple demux‐
14162 ers active, this only returns information about the "main" de‐
14163 muxer, but might be changed in future to return unified informa‐
14164 tion about all demuxers. The ranges are in arbitrary order. Of‐
14165 ten, ranges will overlap for a bit, before being joined. In
14166 broken corner cases, ranges may overlap all over the place.
14167 The end of a seek range is usually smaller than the value re‐
14169 turned by the demuxer-cache-time property, because that property
14170 returns the guessed buffering amount, while the seek ranges rep‐
14171 resent the buffered data that can actually be used for cached
14172 seeking.
14173 bof-cached indicates whether the seek range with the lowest
14175 timestamp points to the beginning of the stream (BOF). This im‐
14176 plies you cannot seek before this position at all. eof-cached
14177 indicates whether the seek range with the highest timestamp
14178 points to the end of the stream (EOF). If both bof-cached and
14179 eof-cached are true, and there's only 1 cache range, the entire
14180 stream is cached.
14181 fw-bytes is the number of bytes of packets buffered in the range
14183 starting from the current decoding position. This is a rough es‐
14184 timate (may not account correctly for various overhead), and
14185 stops at the demuxer position (it ignores seek ranges after it).
14186 file-cache-bytes is the number of bytes stored in the file
14188 cache. This includes all overhead, and possibly unused data
14189 (like pruned data). This member is missing if the file cache
14190 wasn't enabled with --cache-on-disk=yes.
14191 cache-end is demuxer-cache-time. Missing if unavailable.
14193 reader-pts is the approximate timestamp of the start of the
14195 buffered range. Missing if unavailable.
14196 cache-duration is demuxer-cache-duration. Missing if unavail‐
14198 able.
14199 raw-input-rate is the estimated input rate of the network layer
14201 (or any other byte-oriented input layer) in bytes per second.
14202 May be inaccurate or missing.
14203 When querying the property with the client API using MPV_FOR‐
14205 MAT_NODE, or with Lua mp.get_property_native, this will return a
14206 mpv_node with the following contents:
14207 MPV_FORMAT_NODE_MAP
14209 "seekable-ranges" MPV_FORMAT_NODE_ARRAY
14210 MPV_FORMAT_NODE_MAP
14211 "start" MPV_FORMAT_DOUBLE
14212 "end" MPV_FORMAT_DOUBLE
14213 "bof-cached" MPV_FORMAT_FLAG
14214 "eof-cached" MPV_FORMAT_FLAG
14215 "fw-bytes" MPV_FORMAT_INT64
14216 "file-cache-bytes" MPV_FORMAT_INT64
14217 "cache-end" MPV_FORMAT_DOUBLE
14218 "reader-pts" MPV_FORMAT_DOUBLE
14219 "cache-duration" MPV_FORMAT_DOUBLE
14220 "raw-input-rate" MPV_FORMAT_INT64
14221 Other fields (might be changed or removed in the future):
14223 eof Whether the reader thread has hit the end of the file.
14225 underrun
14227 Whether the reader thread could not satisfy a decoder's
14228 request for a new packet.
14229 idle Whether the thread is currently not reading.
14231 total-bytes
14233 Sum of packet bytes (plus some overhead estimation) of
14234 the entire packet queue, including cached seekable
14235 ranges.
14236 demuxer-via-network
14238 Whether the stream demuxed via the main demuxer is most likely
14239 played via network. What constitutes "network" is not always
14240 clear, might be used for other types of untrusted streams, could
14241 be wrong in certain cases, and its definition might be changing.
14242 Also, external files (like separate audio files or streams) do
14243 not influence the value of this property (currently).
14244 demuxer-start-time
14246 The start time reported by the demuxer in fractional seconds.
14247 paused-for-cache
14249 Whether playback is paused because of waiting for the cache.
14250 cache-buffering-state
14252 The percentage (0-100) of the cache fill status until the player
14253 will unpause (related to paused-for-cache).
14254 eof-reached
14256 Whether the end of playback was reached. Note that this is usu‐
14257 ally interesting only if --keep-open is enabled, since otherwise
14258 the player will immediately play the next file (or exit or enter
14259 idle mode), and in these cases the eof-reached property will
14260 logically be cleared immediately after it's set.
14261 seeking
14263 Whether the player is currently seeking, or otherwise trying to
14264 restart playback. (It's possible that it returns yes/true while
14265 a file is loaded. This is because the same underlying code is
14266 used for seeking and resyncing.)
14267 mixer-active
14269 Whether the audio mixer is active.
14270 This option is relatively useless. Before mpv 0.18.1, it could
14272 be used to infer behavior of the volume property.
14273 ao-volume (RW)
14275 System volume. This property is available only if mpv audio out‐
14276 put is currently active, and only if the underlying implementa‐
14277 tion supports volume control. What this option does depends on
14278 the API. For example, on ALSA this usually changes system-wide
14279 audio, while with PulseAudio this controls per-application vol‐
14280 ume.
14281 ao-mute (RW)
14283 Similar to ao-volume, but controls the mute state. May be unim‐
14284 plemented even if ao-volume works.
14285 audio-codec
14287 Audio codec selected for decoding.
14288 audio-codec-name
14290 Audio codec.
14291 audio-params
14293 Audio format as output by the audio decoder. This has a number
14294 of sub-properties:
14295 audio-params/format
14297 The sample format as string. This uses the same names as
14298 used in other places of mpv.
14299 audio-params/samplerate
14301 Samplerate.
14302 audio-params/channels
14304 The channel layout as a string. This is similar to what
14305 the --audio-channels accepts.
14306 audio-params/hr-channels
14308 As channels, but instead of the possibly cryptic actual
14309 layout sent to the audio device, return a hopefully more
14310 human readable form. (Usually only au‐
14311 dio-out-params/hr-channels makes sense.)
14312 audio-params/channel-count
14314 Number of audio channels. This is redundant to the chan‐
14315 nels field described above.
14316 When querying the property with the client API using MPV_FOR‐
14318 MAT_NODE, or with Lua mp.get_property_native, this will return a
14319 mpv_node with the following contents:
14320 MPV_FORMAT_NODE_MAP
14322 "format" MPV_FORMAT_STRING
14323 "samplerate" MPV_FORMAT_INT64
14324 "channels" MPV_FORMAT_STRING
14325 "channel-count" MPV_FORMAT_INT64
14326 "hr-channels" MPV_FORMAT_STRING
14327 audio-out-params
14329 Same as audio-params, but the format of the data written to the
14330 audio API.
14331 colormatrix
14333 Redirects to video-params/colormatrix. This parameter (as well
14334 as similar ones) can be overridden with the format video filter.
14335 colormatrix-input-range
14337 See colormatrix.
14338 colormatrix-primaries
14340 See colormatrix.
14341 hwdec (RW)
14343 Reflects the --hwdec option.
14344 Writing to it may change the currently used hardware decoder, if
14346 possible. (Internally, the player may reinitialize the decoder,
14347 and will perform a seek to refresh the video properly.) You can
14348 watch the other hwdec properties to see whether this was suc‐
14349 cessful.
14350 Unlike in mpv 0.9.x and before, this does not return the cur‐
14352 rently active hardware decoder. Since mpv 0.18.0, hwdec-current
14353 is available for this purpose.
14354 hwdec-current
14356 The current hardware decoding in use. If decoding is active, re‐
14357 turn one of the values used by the hwdec option/property.
14358 no/false indicates software decoding. If no decoder is loaded,
14359 the property is unavailable.
14360 hwdec-interop
14362 This returns the currently loaded hardware decoding/output in‐
14363 terop driver. This is known only once the VO has opened (and
14364 possibly later). With some VOs (like gpu), this might be never
14365 known in advance, but only when the decoder attempted to create
14366 the hw decoder successfully. (Using --gpu-hwdec-interop can load
14367 it eagerly.) If there are multiple drivers loaded, they will be
14368 separated by ,.
14369 If no VO is active or no interop driver is known, this property
14371 is unavailable.
14372 This does not necessarily use the same values as hwdec. There
14374 can be multiple interop drivers for the same hardware decoder,
14375 depending on platform and VO.
14376 video-format
14378 Video format as string.
14379 video-codec
14381 Video codec selected for decoding.
14382 width, height
14384 Video size. This uses the size of the video as decoded, or if no
14385 video frame has been decoded yet, the (possibly incorrect) con‐
14386 tainer indicated size.
14387 video-params
14389 Video parameters, as output by the decoder (with overrides like
14390 aspect etc. applied). This has a number of sub-properties:
14391 video-params/pixelformat
14393 The pixel format as string. This uses the same names as
14394 used in other places of mpv.
14395 video-params/hw-pixelformat
14397 The underlying pixel format as string. This is relevant
14398 for some cases of hardware decoding and unavailable oth‐
14399 erwise.
14400 video-params/average-bpp
14402 Average bits-per-pixel as integer. Subsampled planar for‐
14403 mats use a different resolution, which is the reason this
14404 value can sometimes be odd or confusing. Can be unavail‐
14405 able with some formats.
14406 video-params/w, video-params/h
14408 Video size as integers, with no aspect correction ap‐
14409 plied.
14410 video-params/dw, video-params/dh
14412 Video size as integers, scaled for correct aspect ratio.
14413 video-params/aspect
14415 Display aspect ratio as float.
14416 video-params/par
14418 Pixel aspect ratio.
14419 video-params/colormatrix
14421 The colormatrix in use as string. (Exact values subject
14422 to change.)
14423 video-params/colorlevels
14425 The colorlevels as string. (Exact values subject to
14426 change.)
14427 video-params/primaries
14429 The primaries in use as string. (Exact values subject to
14430 change.)
14431 video-params/gamma
14433 The gamma function in use as string. (Exact values sub‐
14434 ject to change.)
14435 video-params/sig-peak
14437 The video file's tagged signal peak as float.
14438 video-params/light
14440 The light type in use as a string. (Exact values subject
14441 to change.)
14442 video-params/chroma-location
14444 Chroma location as string. (Exact values subject to
14445 change.)
14446 video-params/rotate
14448 Intended display rotation in degrees (clockwise).
14449 video-params/stereo-in
14451 Source file stereo 3D mode. (See the format video fil‐
14452 ter's stereo-in option.)
14453 video-params/alpha
14455 Alpha type. If the format has no alpha channel, this will
14456 be unavailable (but in future releases, it could change
14457 to no). If alpha is present, this is set to straight or
14458 premul.
14459 When querying the property with the client API using MPV_FOR‐
14461 MAT_NODE, or with Lua mp.get_property_native, this will return a
14462 mpv_node with the following contents:
14463 MPV_FORMAT_NODE_MAP
14465 "pixelformat" MPV_FORMAT_STRING
14466 "hw-pixelformat" MPV_FORMAT_STRING
14467 "w" MPV_FORMAT_INT64
14468 "h" MPV_FORMAT_INT64
14469 "dw" MPV_FORMAT_INT64
14470 "dh" MPV_FORMAT_INT64
14471 "aspect" MPV_FORMAT_DOUBLE
14472 "par" MPV_FORMAT_DOUBLE
14473 "colormatrix" MPV_FORMAT_STRING
14474 "colorlevels" MPV_FORMAT_STRING
14475 "primaries" MPV_FORMAT_STRING
14476 "gamma" MPV_FORMAT_STRING
14477 "sig-peak" MPV_FORMAT_DOUBLE
14478 "light" MPV_FORMAT_STRING
14479 "chroma-location" MPV_FORMAT_STRING
14480 "rotate" MPV_FORMAT_INT64
14481 "stereo-in" MPV_FORMAT_STRING
14482 "average-bpp" MPV_FORMAT_INT64
14483 "alpha" MPV_FORMAT_STRING
14484 dwidth, dheight
14486 Video display size. This is the video size after filters and as‐
14487 pect scaling have been applied. The actual video window size can
14488 still be different from this, e.g. if the user resized the video
14489 window manually.
14490 These have the same values as video-out-params/dw and
14492 video-out-params/dh.
14493 video-dec-params
14495 Exactly like video-params, but no overrides applied.
14496 video-out-params
14498 Same as video-params, but after video filters have been applied.
14499 If there are no video filters in use, this will contain the same
14500 values as video-params. Note that this is still not necessarily
14501 what the video window uses, since the user can change the window
14502 size, and all real VOs do their own scaling independently from
14503 the filter chain.
14504 Has the same sub-properties as video-params.
14506 video-frame-info
14508 Approximate information of the current frame. Note that if any
14509 of these are used on OSD, the information might be off by a few
14510 frames due to OSD redrawing and frame display being somewhat
14511 disconnected, and you might have to pause and force a redraw.
14512 This has a number of sub-properties:
14514 video-frame-info/picture-type
14516 The type of the picture. It can be "I" (intra), "P" (pre‐
14517 dicted), "B" (bi-dir predicted) or unavailable.
14518 video-frame-info/interlaced
14520 Whether the content of the frame is interlaced.
14521 video-frame-info/tff
14523 If the content is interlaced, whether the top field is
14524 displayed first.
14525 video-frame-info/repeat
14527 Whether the frame must be delayed when decoding.
14528 container-fps
14530 Container FPS. This can easily contain bogus values. For videos
14531 that use modern container formats or video codecs, this will of‐
14532 ten be incorrect.
14533 (Renamed from fps.)
14535 estimated-vf-fps
14537 Estimated/measured FPS of the video filter chain output. (If no
14538 filters are used, this corresponds to decoder output.) This uses
14539 the average of the 10 past frame durations to calculate the FPS.
14540 It will be inaccurate if frame-dropping is involved (such as
14541 when framedrop is explicitly enabled, or after precise seeking).
14542 Files with imprecise timestamps (such as Matroska) might lead to
14543 unstable results.
14544 window-scale (RW)
14546 Window size multiplier. Setting this will resize the video win‐
14547 dow to the values contained in dwidth and dheight multiplied
14548 with the value set with this property. Setting 1 will resize to
14549 original video size (or to be exact, the size the video filters
14550 output). 2 will set the double size, 0.5 halves the size.
14551 Note that setting a value identical to its previous value will
14553 not resize the window. That's because this property mirrors the
14554 window-scale option, and setting an option to its previous value
14555 is ignored. If this value is set while the window is in a
14556 fullscreen, the multiplier is not applied until the window is
14557 taken out of that state. Writing this property to a maximized
14558 window can unmaximize the window depending on the OS and window
14559 manager. If the window does not unmaximize, the multiplier will
14560 be applied if the user unmaximizes the window later.
14561 See current-window-scale for the value derived from the actual
14563 window size.
14564 Since mpv 0.31.0, this always returns the previously set value
14566 (or the default value), instead of the value implied by the ac‐
14567 tual window size. Before mpv 0.31.0, this returned what cur‐
14568 rent-window-scale returns now, after the window was created.
14569 current-window-scale (RW)
14571 The window-scale value calculated from the current window size.
14572 This has the same value as window-scale if the window size was
14573 not changed since setting the option, and the window size was
14574 not restricted in other ways. If the window is fullscreened,
14575 this will return the scale value calculated from the last
14576 non-fullscreen size of the window. The property is unavailable
14577 if no video is active.
14578 When setting this property in the fullscreen or maximized state,
14580 the behavior is the same as window-scale. In all other cases,
14581 setting the value of this property will always resize the win‐
14582 dow. This does not affect the value of window-scale.
14583 focused
14585 Whether the window has focus. Might not be supported by all VOs.
14586 display-names
14588 Names of the displays that the mpv window covers. On X11, these
14589 are the xrandr names (LVDS1, HDMI1, DP1, VGA1, etc.). On Win‐
14590 dows, these are the GDI names (\.DISPLAY1, \.DISPLAY2, etc.) and
14591 the first display in the list will be the one that Windows con‐
14592 siders associated with the window (as determined by the Monitor‐
14593 FromWindow API.) On macOS these are the Display Product Names as
14594 used in the System Information and only one display name is re‐
14595 turned since a window can only be on one screen.
14596 display-fps
14598 The refresh rate of the current display. Currently, this is the
14599 lowest FPS of any display covered by the video, as retrieved by
14600 the underlying system APIs (e.g. xrandr on X11). It is not the
14601 measured FPS. It's not necessarily available on all platforms.
14602 Note that any of the listed facts may change any time without a
14603 warning.
14604 Writing to this property is deprecated. It has the same effect
14606 as writing to override-display-fps. Since mpv 0.31.0, this prop‐
14607 erty is unavailable if no display FPS was reported (e.g. if no
14608 video is active), while in older versions, it returned the
14609 --display-fps option value.
14610 estimated-display-fps
14612 The actual rate at which display refreshes seem to occur, mea‐
14613 sured by system time. Only available if display-sync mode (as
14614 selected by --video-sync) is active.
14615 vsync-jitter
14617 Estimated deviation factor of the vsync duration.
14618 display-width, display-height
14620 The current display's horizontal and vertical resolution in pix‐
14621 els. Whether or not these values update as the mpv window
14622 changes displays depends on the windowing backend. It may not be
14623 available on all platforms.
14624 display-hidpi-scale
14626 The HiDPI scale factor as reported by the windowing backend. If
14627 no VO is active, or if the VO does not report a value, this
14628 property is unavailable. It may be saner to report an absolute
14629 DPI, however, this is the way HiDPI support is implemented on
14630 most OS APIs. See also --hidpi-window-scale.
14631 video-aspect (RW)
14633 Deprecated. This is tied to --video-aspect-override, but always
14634 reports the current video aspect if video is active.
14635 The read and write components of this option can be split up
14637 into video-params/aspect and video-aspect-override respectively.
14638 osd-width, osd-height
14640 Last known OSD width (can be 0). This is needed if you want to
14641 use the overlay-add command. It gives you the actual OSD/window
14642 size (not including decorations drawn by the OS window manager).
14643 Alias to osd-dimensions/w and osd-dimensions/h.
14645 osd-par
14647 Last known OSD display pixel aspect (can be 0).
14648 Alias to osd-dimensions/osd-par.
14650 osd-dimensions
14652 Last known OSD dimensions.
14653 Has the following sub-properties (which can be read as MPV_FOR‐
14655 MAT_NODE or Lua table with mp.get_property_native):
14656 osd-dimensions/w
14658 Size of the VO window in OSD render units (usually pix‐
14659 els, but may be scaled pixels with VOs like xv).
14660 osd-dimensions/h
14662 Size of the VO window in OSD render units,
14663 osd-dimensions/par
14665 Pixel aspect ratio of the OSD (usually 1).
14666 osd-dimensions/aspect
14668 Display aspect ratio of the VO window. (Computing from
14669 the properties above.)
14670 osd-dimensions/mt, osd-dimensions/mb, osd-dimensions/ml, osd-di‐
14672 mensions/mr
14673 OSD to video margins (top, bottom, left, right). This de‐
14674 scribes the area into which the video is rendered.
14675 Any of these properties may be unavailable or set to dummy val‐
14677 ues if the VO window is not created or visible.
14678 window-id
14680 Read-only - mpv's window id. May not always be available, i.e
14681 due to window not being opened yet or not being supported by the
14682 VO.
14683 mouse-pos
14685 Read-only - last known mouse position, normalizd to OSD dimen‐
14686 sions.
14687 Has the following sub-properties (which can be read as MPV_FOR‐
14689 MAT_NODE or Lua table with mp.get_property_native):
14690 mouse-pos/x, mouse-pos/y
14692 Last known coordinates of the mouse pointer.
14693 mouse-pos/hover
14695 Boolean - whether the mouse pointer hovers the video win‐
14696 dow. The coordinates should be ignored when this value is
14697 false, because the video backends update them only when
14698 the pointer hovers the window.
14699 sub-text
14701 The current subtitle text regardless of sub visibility. Format‐
14702 ting is stripped. If the subtitle is not text-based (i.e. DVD/BD
14703 subtitles), an empty string is returned.
14704 sub-text-ass
14706 Like sub-text, but return the text in ASS format. Text subtitles
14707 in other formats are converted. For native ASS subtitles, events
14708 that do not contain any text (but vector drawings etc.) are not
14709 filtered out. If multiple events match with the current playback
14710 time, they are concatenated with line breaks. Contains only the
14711 "Text" part of the events.
14712 This property is not enough to render ASS subtitles correctly,
14714 because ASS header and per-event metadata are not returned. You
14715 likely need to do further filtering on the returned string to
14716 make it useful.
14717 secondary-sub-text
14719 Same as sub-text, but for the secondary subtitles.
14720 sub-start
14722 The current subtitle start time (in seconds). If there's multi‐
14723 ple current subtitles, returns the first start time. If no cur‐
14724 rent subtitle is present null is returned instead.
14725 secondary-sub-start
14727 Same as sub-start, but for the secondary subtitles.
14728 sub-end
14730 The current subtitle end time (in seconds). If there's multiple
14731 current subtitles, return the last end time. If no current sub‐
14732 title is present, or if it's present but has unknown or incor‐
14733 rect duration, null is returned instead.
14734 secondary-sub-end
14736 Same as sub-end, but for the secondary subtitles.
14737 sub-forced-only-cur
14739 Read-only - whether the current subtitle track is being shown in
14740 forced-only mode.
14741 playlist-pos (RW)
14743 Current position on playlist. The first entry is on position 0.
14744 Writing to this property may start playback at the new position.
14745 In some cases, this is not necessarily the currently playing
14747 file. See explanation of current and playing flags in playlist.
14748 If there the playlist is empty, or if it's non-empty, but no en‐
14750 try is "current", this property returns -1. Likewise, writing -1
14751 will put the player into idle mode (or exit playback if idle
14752 mode is not enabled). If an out of range index is written to the
14753 property, this behaves as if writing -1. (Before mpv 0.33.0,
14754 instead of returning -1, this property was unavailable if no
14755 playlist entry was current.)
14756 Writing the current value back to the property is subject to
14758 change. Currently, it will restart playback of the playlist en‐
14759 try. But in the future, writing the current value will be ig‐
14760 nored. Use the playlist-play-index command to get guaranteed be‐
14761 havior.
14762 playlist-pos-1 (RW)
14764 Same as playlist-pos, but 1-based.
14765 playlist-current-pos (RW)
14767 Index of the "current" item on playlist. This usually, but not
14768 necessarily, the currently playing item (see playlist-play‐
14769 ing-pos). Depending on the exact internal state of the player,
14770 it may refer to the playlist item to play next, or the playlist
14771 item used to determine what to play next.
14772 For reading, this is exactly the same as playlist-pos.
14774 For writing, this only sets the position of the "current" item,
14776 without stopping playback of the current file (or starting play‐
14777 back, if this is done in idle mode). Use -1 to remove the cur‐
14778 rent flag.
14779 This property is only vaguely useful. If set during playback, it
14781 will typically cause the playlist entry after it to be played
14782 next. Another possibly odd observable state is that if
14783 playlist-next is run during playback, this property is set to
14784 the playlist entry to play next (unlike the previous case).
14785 There is an internal flag that decides whether the current
14786 playlist entry or the next one should be played, and this flag
14787 is currently inaccessible for API users. (Whether this behavior
14788 will kept is possibly subject to change.)
14789 playlist-playing-pos
14791 Index of the "playing" item on playlist. A playlist item is
14792 "playing" if it's being loaded, actually playing, or being un‐
14793 loaded. This property is set during the MPV_EVENT_START_FILE
14794 (start-file) and the MPV_EVENT_START_END (end-file) events. Out‐
14795 side of that, it returns -1. If the playlist entry was somehow
14796 removed during playback, but playback hasn't stopped yet, or is
14797 in progress of being stopped, it also returns -1. (This can
14798 happen at least during state transitions.)
14799 In the "playing" state, this is usually the same as
14801 playlist-pos, except during state changes, or if playlist-cur‐
14802 rent-pos was written explicitly.
14803 playlist-count
14805 Number of total playlist entries.
14806 playlist
14808 Playlist, current entry marked. Currently, the raw property
14809 value is useless.
14810 This has a number of sub-properties. Replace N with the 0-based
14812 playlist entry index.
14813 playlist/count
14815 Number of playlist entries (same as playlist-count).
14816 playlist/N/filename
14818 Filename of the Nth entry.
14819 playlist/N/playing
14821 yes/true if the playlist-playing-pos property points to
14822 this entry, no/false or unavailable otherwise.
14823 playlist/N/current
14825 yes/true if the playlist-current-pos property points to
14826 this entry, no/false or unavailable otherwise.
14827 playlist/N/title
14829 Name of the Nth entry. Available if the playlist file
14830 contains such fields and mpv's parser supports it for the
14831 given playlist format, or if the playlist entry has been
14832 opened before and a media-title other then then filename
14833 has been acquired.
14834 playlist/N/id
14836 Unique ID for this entry. This is an automatically as‐
14837 signed integer ID that is unique for the entire life time
14838 of the current mpv core instance. Other commands, events,
14839 etc. use this as playlist_entry_id fields.
14840 When querying the property with the client API using MPV_FOR‐
14842 MAT_NODE, or with Lua mp.get_property_native, this will return a
14843 mpv_node with the following contents:
14844 MPV_FORMAT_NODE_ARRAY
14846 MPV_FORMAT_NODE_MAP (for each playlist entry)
14847 "filename" MPV_FORMAT_STRING
14848 "current" MPV_FORMAT_FLAG (might be missing; since mpv 0.7.0)
14849 "playing" MPV_FORMAT_FLAG (same)
14850 "title" MPV_FORMAT_STRING (optional)
14851 "id" MPV_FORMAT_INT64
14852 track-list
14854 List of audio/video/sub tracks, current entry marked. Currently,
14855 the raw property value is useless.
14856 This has a number of sub-properties. Replace N with the 0-based
14858 track index.
14859 track-list/count
14861 Total number of tracks.
14862 track-list/N/id
14864 The ID as it's used for -sid/--aid/--vid. This is unique
14865 within tracks of the same type (sub/audio/video), but
14866 otherwise not.
14867 track-list/N/type
14869 String describing the media type. One of audio, video,
14870 sub.
14871 track-list/N/src-id
14873 Track ID as used in the source file. Not always avail‐
14874 able. (It is missing if the format has no native ID, if
14875 the track is a pseudo-track that does not exist in this
14876 way in the actual file, or if the format is handled by
14877 libavformat, and the format was not whitelisted as having
14878 track IDs.)
14879 track-list/N/title
14881 Track title as it is stored in the file. Not always
14882 available.
14883 track-list/N/lang
14885 Track language as identified by the file. Not always
14886 available.
14887 track-list/N/image
14889 yes/true if this is a video track that consists of a sin‐
14890 gle picture, no/false or unavailable otherwise. The
14891 heuristic used to determine if a stream is an image
14892 doesn't attempt to detect images in codecs normally used
14893 for videos. Otherwise, it is reliable.
14894 track-list/N/albumart
14896 yes/true if this is an image embedded in an audio file or
14897 external cover art, no/false or unavailable otherwise.
14898 track-list/N/default
14900 yes/true if the track has the default flag set in the
14901 file, no/false or unavailable otherwise.
14902 track-list/N/forced
14904 yes/true if the track has the forced flag set in the
14905 file, no/false or unavailable otherwise.
14906 track-list/N/auto-forced-only
14908 yes/true if the track was autoselected in forced-only
14909 mode, no/false or unavailable otherwise.
14910 track-list/N/codec
14912 The codec name used by this track, for example h264. Un‐
14913 available in some rare cases.
14914 track-list/N/external
14916 yes/true if the track is an external file, no/false or
14917 unavailable otherwise. This is set for separate subtitle
14918 files.
14919 track-list/N/external-filename
14921 The filename if the track is from an external file, un‐
14922 available otherwise.
14923 track-list/N/selected
14925 yes/true if the track is currently decoded, no/false or
14926 unavailable otherwise.
14927 track-list/N/main-selection
14929 It indicates the selection order of tracks for the same
14930 type. If a track is not selected, or is selected by the
14931 --lavfi-complex, it is not available. For subtitle
14932 tracks, 0 represents the sid, and 1 represents the sec‐
14933 ondary-sid.
14934 track-list/N/ff-index
14936 The stream index as usually used by the FFmpeg utilities.
14937 Note that this can be potentially wrong if a demuxer
14938 other than libavformat (--demuxer=lavf) is used. For mkv
14939 files, the index will usually match even if the default
14940 (builtin) demuxer is used, but there is no hard guaran‐
14941 tee.
14942 track-list/N/decoder-desc
14944 If this track is being decoded, the human-readable de‐
14945 coder name,
14946 track-list/N/demux-w, track-list/N/demux-h
14948 Video size hint as indicated by the container. (Not al‐
14949 ways accurate.)
14950 track-list/N/demux-channel-count
14952 Number of audio channels as indicated by the container.
14953 (Not always accurate - in particular, the track could be
14954 decoded as a different number of channels.)
14955 track-list/N/demux-channels
14957 Channel layout as indicated by the container. (Not always
14958 accurate.)
14959 track-list/N/demux-samplerate
14961 Audio sample rate as indicated by the container. (Not al‐
14962 ways accurate.)
14963 track-list/N/demux-fps
14965 Video FPS as indicated by the container. (Not always ac‐
14966 curate.)
14967 track-list/N/demux-bitrate
14969 Audio average bitrate, in bits per second. (Not always
14970 accurate.)
14971 track-list/N/demux-rotation
14973 Video clockwise rotation metadata, in degrees.
14974 track-list/N/demux-par
14976 Pixel aspect ratio.
14977 track-list/N/audio-channels (deprecated)
14979 Deprecated alias for track-list/N/demux-channel-count.
14980 track-list/N/replaygain-track-peak, track-list/N/replay‐
14982 gain-track-gain
14983 Per-track replaygain values. Only available for audio
14984 tracks with corresponding information stored in the
14985 source file.
14986 track-list/N/replaygain-album-peak, track-list/N/replaygain-al‐
14988 bum-gain
14989 Per-album replaygain values. If the file has per-track
14990 but no per-album information, the per-album values will
14991 be copied from the per-track values currently. It's pos‐
14992 sible that future mpv versions will make these properties
14993 unavailable instead in this case.
14994 When querying the property with the client API using MPV_FOR‐
14996 MAT_NODE, or with Lua mp.get_property_native, this will return a
14997 mpv_node with the following contents:
14998 MPV_FORMAT_NODE_ARRAY
15000 MPV_FORMAT_NODE_MAP (for each track)
15001 "id" MPV_FORMAT_INT64
15002 "type" MPV_FORMAT_STRING
15003 "src-id" MPV_FORMAT_INT64
15004 "title" MPV_FORMAT_STRING
15005 "lang" MPV_FORMAT_STRING
15006 "image" MPV_FORMAT_FLAG
15007 "albumart" MPV_FORMAT_FLAG
15008 "default" MPV_FORMAT_FLAG
15009 "forced" MPV_FORMAT_FLAG
15010 "selected" MPV_FORMAT_FLAG
15011 "main-selection" MPV_FORMAT_INT64
15012 "external" MPV_FORMAT_FLAG
15013 "external-filename" MPV_FORMAT_STRING
15014 "codec" MPV_FORMAT_STRING
15015 "ff-index" MPV_FORMAT_INT64
15016 "decoder-desc" MPV_FORMAT_STRING
15017 "demux-w" MPV_FORMAT_INT64
15018 "demux-h" MPV_FORMAT_INT64
15019 "demux-channel-count" MPV_FORMAT_INT64
15020 "demux-channels" MPV_FORMAT_STRING
15021 "demux-samplerate" MPV_FORMAT_INT64
15022 "demux-fps" MPV_FORMAT_DOUBLE
15023 "demux-bitrate" MPV_FORMAT_INT64
15024 "demux-rotation" MPV_FORMAT_INT64
15025 "demux-par" MPV_FORMAT_DOUBLE
15026 "audio-channels" MPV_FORMAT_INT64
15027 "replaygain-track-peak" MPV_FORMAT_DOUBLE
15028 "replaygain-track-gain" MPV_FORMAT_DOUBLE
15029 "replaygain-album-peak" MPV_FORMAT_DOUBLE
15030 "replaygain-album-gain" MPV_FORMAT_DOUBLE
15031 current-tracks/...
15033 This gives access to currently selected tracks. It redirects to
15034 the correct entry in track-list.
15035 The following sub-entries are defined: video, audio, sub, sub2
15037 For example, current-tracks/audio/lang returns the current audio
15039 track's language field (the same value as track-list/N/lang).
15040 If tracks of the requested type are selected via --lavfi-com‐
15042 plex, the first one is returned.
15043 chapter-list (RW)
15045 List of chapters, current entry marked. Currently, the raw prop‐
15046 erty value is useless.
15047 This has a number of sub-properties. Replace N with the 0-based
15049 chapter index.
15050 chapter-list/count
15052 Number of chapters.
15053 chapter-list/N/title
15055 Chapter title as stored in the file. Not always avail‐
15056 able.
15057 chapter-list/N/time
15059 Chapter start time in seconds as float.
15060 When querying the property with the client API using MPV_FOR‐
15062 MAT_NODE, or with Lua mp.get_property_native, this will return a
15063 mpv_node with the following contents:
15064 MPV_FORMAT_NODE_ARRAY
15066 MPV_FORMAT_NODE_MAP (for each chapter)
15067 "title" MPV_FORMAT_STRING
15068 "time" MPV_FORMAT_DOUBLE
15069 af, vf (RW)
15071 See --vf/--af and the vf/af command.
15072 When querying the property with the client API using MPV_FOR‐
15074 MAT_NODE, or with Lua mp.get_property_native, this will return a
15075 mpv_node with the following contents:
15076 MPV_FORMAT_NODE_ARRAY
15078 MPV_FORMAT_NODE_MAP (for each filter entry)
15079 "name" MPV_FORMAT_STRING
15080 "label" MPV_FORMAT_STRING [optional]
15081 "enabled" MPV_FORMAT_FLAG [optional]
15082 "params" MPV_FORMAT_NODE_MAP [optional]
15083 "key" MPV_FORMAT_STRING
15084 "value" MPV_FORMAT_STRING
15085 It's also possible to write the property using this format.
15087 seekable
15089 Whether it's generally possible to seek in the current file.
15090 partially-seekable
15092 Whether the current file is considered seekable, but only be‐
15093 cause the cache is active. This means small relative seeks may
15094 be fine, but larger seeks may fail anyway. Whether a seek will
15095 succeed or not is generally not known in advance.
15096 If this property returns yes/true, so will seekable.
15098 playback-abort
15100 Whether playback is stopped or is to be stopped. (Useful in ob‐
15101 scure situations like during on_load hook processing, when the
15102 user can stop playback, but the script has to explicitly end
15103 processing.)
15104 cursor-autohide (RW)
15106 See --cursor-autohide. Setting this to a new value will always
15107 update the cursor, and reset the internal timer.
15108 osd-sym-cc
15110 Inserts the current OSD symbol as opaque OSD control code (cc).
15111 This makes sense only with the show-text command or options
15112 which set OSD messages. The control code is implementation spe‐
15113 cific and is useless for anything else.
15114 osd-ass-cc
15116 ${osd-ass-cc/0} disables escaping ASS sequences of text in OSD,
15117 ${osd-ass-cc/1} enables it again. By default, ASS sequences are
15118 escaped to avoid accidental formatting, and this property can
15119 disable this behavior. Note that the properties return an opaque
15120 OSD control code, which only makes sense for the show-text com‐
15121 mand or options which set OSD messages.
15122 Example
15124 • --osd-msg3='This is ${osd-ass-cc/0}{\\b1}bold text'
15126 • show-text "This is ${osd-ass-cc/0}{\\b1}bold text"
15128 Any ASS override tags as understood by libass can be used.
15130 Note that you need to escape the \ character, because the string
15132 is processed for C escape sequences before passing it to the OSD
15133 code. See Flat command syntax for details.
15134 A list of tags can be found here:
15136 https://aeg-dev.github.io/AegiSite/docs/3.2/ass_tags/
15137 vo-configured
15139 Whether the VO is configured right now. Usually this corresponds
15140 to whether the video window is visible. If the --force-window
15141 option is used, this usually always returns yes/true.
15142 vo-passes
15144 Contains introspection about the VO's active render passes and
15145 their execution times. Not implemented by all VOs.
15146 This is further subdivided into two frame types, vo-passes/fresh
15148 for fresh frames (which have to be uploaded, scaled, etc.) and
15149 vo-passes/redraw for redrawn frames (which only have to be
15150 re-painted). The number of passes for any given subtype can
15151 change from frame to frame, and should not be relied upon.
15152 Each frame type has a number of further sub-properties. Replace
15154 TYPE with the frame type, N with the 0-based pass index, and M
15155 with the 0-based sample index.
15156 vo-passes/TYPE/count
15158 Number of passes.
15159 vo-passes/TYPE/N/desc
15161 Human-friendy description of the pass.
15162 vo-passes/TYPE/N/last
15164 Last measured execution time, in nanoseconds.
15165 vo-passes/TYPE/N/avg
15167 Average execution time of this pass, in nanoseconds. The
15168 exact timeframe varies, but it should generally be a
15169 handful of seconds.
15170 vo-passes/TYPE/N/peak
15172 The peak execution time (highest value) within this aver‐
15173 aging range, in nanoseconds.
15174 vo-passes/TYPE/N/count
15176 The number of samples for this pass.
15177 vo-passes/TYPE/N/samples/M
15179 The raw execution time of a specific sample for this
15180 pass, in nanoseconds.
15181 When querying the property with the client API using MPV_FOR‐
15183 MAT_NODE, or with Lua mp.get_property_native, this will return a
15184 mpv_node with the following contents:
15185 MPV_FORMAT_NODE_MAP
15187 "TYPE" MPV_FORMAT_NODE_ARRAY
15188 MPV_FORMAT_NODE_MAP
15189 "desc" MPV_FORMAT_STRING
15190 "last" MPV_FORMAT_INT64
15191 "avg" MPV_FORMAT_INT64
15192 "peak" MPV_FORMAT_INT64
15193 "count" MPV_FORMAT_INT64
15194 "samples" MPV_FORMAT_NODE_ARRAY
15195 MP_FORMAT_INT64
15196 Note that directly accessing this structure via subkeys is not
15198 supported, the only access is through aforementioned MPV_FOR‐
15199 MAT_NODE.
15200 perf-info
15202 Further performance data. Querying this property triggers inter‐
15203 nal collection of some data, and may slow down the player. Each
15204 query will reset some internal state. Property change notifica‐
15205 tion doesn't and won't work. All of this may change in the fu‐
15206 ture, so don't use this. The builtin stats script is supposed to
15207 be the only user; since it's bundled and built with the source
15208 code, it can use knowledge of mpv internal to render the infor‐
15209 mation properly. See stats script description for some details.
15210 video-bitrate, audio-bitrate, sub-bitrate
15212 Bitrate values calculated on the packet level. This works by di‐
15213 viding the bit size of all packets between two keyframes by
15214 their presentation timestamp distance. (This uses the timestamps
15215 are stored in the file, so e.g. playback speed does not influ‐
15216 ence the returned values.) In particular, the video bitrate will
15217 update only per keyframe, and show the "past" bitrate. To make
15218 the property more UI friendly, updates to these properties are
15219 throttled in a certain way.
15220 The unit is bits per second. OSD formatting turns these values
15222 in kilobits (or megabits, if appropriate), which can be pre‐
15223 vented by using the raw property value, e.g. with ${=video-bi‐
15224 trate}.
15225 Note that the accuracy of these properties is influenced by a
15227 few factors. If the underlying demuxer rewrites the packets on
15228 demuxing (done for some file formats), the bitrate might be
15229 slightly off. If timestamps are bad or jittery (like in Ma‐
15230 troska), even constant bitrate streams might show fluctuating
15231 bitrate.
15232 How exactly these values are calculated might change in the fu‐
15234 ture.
15235 In earlier versions of mpv, these properties returned a static
15237 (but bad) guess using a completely different method.
15238 packet-video-bitrate, packet-audio-bitrate, packet-sub-bitrate
15240 Old and deprecated properties for video-bitrate, audio-bitrate,
15241 sub-bitrate. They behave exactly the same, but return a value in
15242 kilobits. Also, they don't have any OSD formatting, though the
15243 same can be achieved with e.g. ${=video-bitrate}.
15244 These properties shouldn't be used anymore.
15246 audio-device-list
15248 The list of discovered audio devices. This is mostly for use
15249 with the client API, and reflects what --audio-device=help with
15250 the command line player returns.
15251 When querying the property with the client API using MPV_FOR‐
15253 MAT_NODE, or with Lua mp.get_property_native, this will return a
15254 mpv_node with the following contents:
15255 MPV_FORMAT_NODE_ARRAY
15257 MPV_FORMAT_NODE_MAP (for each device entry)
15258 "name" MPV_FORMAT_STRING
15259 "description" MPV_FORMAT_STRING
15260 The name is what is to be passed to the --audio-device option
15262 (and often a rather cryptic audio API-specific ID), while de‐
15263 scription is human readable free form text. The description is
15264 set to the device name (minus mpv-specific <driver>/ prefix) if
15265 no description is available or the description would have been
15266 an empty string.
15267 The special entry with the name set to auto selects the default
15269 audio output driver and the default device.
15270 The property can be watched with the property observation mecha‐
15272 nism in the client API and in Lua scripts. (Technically, change
15273 notification is enabled the first time this property is read.)
15274 audio-device (RW)
15276 Set the audio device. This directly reads/writes the --audio-de‐
15277 vice option, but on write accesses, the audio output will be
15278 scheduled for reloading.
15279 Writing this property while no audio output is active will not
15281 automatically enable audio. (This is also true in the case when
15282 audio was disabled due to reinitialization failure after a pre‐
15283 vious write access to audio-device.)
15284 This property also doesn't tell you which audio device is actu‐
15286 ally in use.
15287 How these details are handled may change in the future.
15289 current-vo
15291 Current video output driver (name as used with --vo).
15292 current-ao
15294 Current audio output driver (name as used with --ao).
15295 shared-script-properties (RW)
15297 This is a key/value map of arbitrary strings shared between
15298 scripts for general use. The player itself does not use any data
15299 in it (although some builtin scripts may). The property is not
15300 preserved across player restarts.
15301 This is very primitive, inefficient, and annoying to use. It's a
15303 makeshift solution which could go away any time (for example,
15304 when a better solution becomes available). This is also why this
15305 property has an annoying name. You should avoid using it, unless
15306 you absolutely have to.
15307 Lua scripting has helpers starting with
15309 utils.shared_script_property_. They are undocumented because
15310 you should not use this property. If you still think you must,
15311 you should use the helpers instead of the property directly.
15312 You are supposed to use the change-list command to modify the
15314 contents. Reading, modifying, and writing the property manually
15315 could data loss if two scripts update different keys at the same
15316 time due to lack of synchronization. The Lua helpers take care
15317 of this.
15318 (There is no way to ensure synchronization if two scripts try to
15320 update the same key at the same time.)
15321 user-data (RW)
15323 This is a recursive key/value map of arbitrary nodes shared be‐
15324 tween clients for general use (i.e. scripts, IPC clients, host
15325 applications, etc). The player itself does not use any data in
15326 it (although some builtin scripts may). The property is not
15327 preserved across player restarts.
15328 This is a more powerful replacement for shared-script-proper‐
15330 ties.
15331 Sub-paths can be accessed directly; e.g.
15333 user-data/my-script/state/a can be read, written, or observed.
15334 The top-level object itself cannot be written directly; write to
15336 sub-paths instead.
15337 Converting this property or its sub-properties to strings will
15339 give a JSON representation. If converting a leaf-level object
15340 (i.e. not a map or array) and not using raw mode, the underlying
15341 content will be given (e.g. strings will be printed directly,
15342 rather than quoted and JSON-escaped).
15343 working-directory
15345 The working directory of the mpv process. Can be useful for JSON
15346 IPC users, because the command line player usually works with
15347 relative paths.
15348 protocol-list
15350 List of protocol prefixes potentially recognized by the player.
15351 They are returned without trailing :// suffix (which is still
15352 always required). In some cases, the protocol will not actually
15353 be supported (consider https if ffmpeg is not compiled with TLS
15354 support).
15355 decoder-list
15357 List of decoders supported. This lists decoders which can be
15358 passed to --vd and --ad.
15359 codec Canonical codec name, which identifies the format the de‐
15361 coder can handle.
15362 driver The name of the decoder itself. Often, this is the same
15364 as codec. Sometimes it can be different. It is used to
15365 distinguish multiple decoders for the same codec.
15366 description
15368 Human readable description of the decoder and codec.
15369 When querying the property with the client API using MPV_FOR‐
15371 MAT_NODE, or with Lua mp.get_property_native, this will return a
15372 mpv_node with the following contents:
15373 MPV_FORMAT_NODE_ARRAY
15375 MPV_FORMAT_NODE_MAP (for each decoder entry)
15376 "codec" MPV_FORMAT_STRING
15377 "driver" MPV_FORMAT_STRING
15378 "description" MPV_FORMAT_STRING
15379 encoder-list
15381 List of libavcodec encoders. This has the same format as de‐
15382 coder-list. The encoder names (driver entries) can be passed to
15383 --ovc and --oac (without the lavc: prefix required by --vd and
15384 --ad).
15385 demuxer-lavf-list
15387 List of available libavformat demuxers' names. This can be used
15388 to check for support for a specific format or use with --de‐
15389 muxer-lavf-format.
15390 input-key-list
15392 List of Key names, same as output by --input-keylist.
15393 mpv-version
15395 The mpv version/copyright string. Depending on how the binary
15396 was built, it might contain either a release version, or just a
15397 git hash.
15398 mpv-configuration
15400 The configuration arguments that were passed to the build sys‐
15401 tem. If the meson version used to compile mpv is older than
15402 1.1.0, then a hardcoded string of a few, arbitrary options is
15403 displayed instead.
15404 ffmpeg-version
15406 The contents of the av_version_info() API call. This is a string
15407 which identifies the build in some way, either through a release
15408 version number, or a git hash. This applies to Libav as well
15409 (the property is still named the same.) This property is un‐
15410 available if mpv is linked against older FFmpeg and Libav ver‐
15411 sions.
15412 libass-version
15414 The value of ass_library_version(). This is an integer, encoded
15415 in a somewhat weird form (apparently "hex BCD"), indicating the
15416 release version of the libass library linked to mpv.
15417 platform
15419 Returns a string describing what target platform mpv was built
15420 for. The value of this is dependent on what the underlying build
15421 system detects. Some of the most common values are: windows,
15422 darwin (macos or ios), linux, android, and freebsd. Note that
15423 this is not a complete listing.
15424 options/<name> (RW)
15426 The value of option --<name>. Most options can be changed at
15427 runtime by writing to this property. Note that many options re‐
15428 quire reloading the file for changes to take effect. If there is
15429 an equivalent property, prefer setting the property instead.
15430 There shouldn't be any reason to access options/<name> instead
15432 of <name>, except in situations in which the properties have
15433 different behavior or conflicting semantics.
15434 file-local-options/<name> (RW)
15436 Similar to options/<name>, but when setting an option through
15437 this property, the option is reset to its old value once the
15438 current file has stopped playing. Trying to write an option
15439 while no file is playing (or is being loaded) results in an er‐
15440 ror.
15441 (Note that if an option is marked as file-local, even options/
15443 will access the local value, and the old value, which will be
15444 restored on end of playback, cannot be read or written until end
15445 of playback.)
15446 option-info/<name>
15448 Additional per-option information.
15449 This has a number of sub-properties. Replace <name> with the
15451 name of a top-level option. No guarantee of stability is given
15452 to any of these sub-properties - they may change radically in
15453 the feature.
15454 option-info/<name>/name
15456 The name of the option.
15457 option-info/<name>/type
15459 The name of the option type, like String or Integer. For
15460 many complex types, this isn't very accurate.
15461 option-info/<name>/set-from-commandline
15463 Whether the option was set from the mpv command line.
15464 What this is set to if the option is e.g. changed at run‐
15465 time is left undefined (meaning it could change in the
15466 future).
15467 option-info/<name>/set-locally
15469 Whether the option was set per-file. This is the case
15470 with automatically loaded profiles, file-dir configs, and
15471 other cases. It means the option value will be restored
15472 to the value before playback start when playback ends.
15473 option-info/<name>/default-value
15475 The default value of the option. May not always be avail‐
15476 able.
15477 option-info/<name>/min, option-info/<name>/max
15479 Integer minimum and maximum values allowed for the op‐
15480 tion. Only available if the options are numeric, and the
15481 minimum/maximum has been set internally. It's also possi‐
15482 ble that only one of these is set.
15483 option-info/<name>/choices
15485 If the option is a choice option, the possible choices.
15486 Choices that are integers may or may not be included
15487 (they can be implied by min and max). Note that options
15488 which behave like choice options, but are not actual
15489 choice options internally, may not have this info avail‐
15490 able.
15491 property-list
15493 The list of top-level properties.
15494 profile-list
15496 The list of profiles and their contents. This is highly imple‐
15497 mentation-specific, and may change any time. Currently, it re‐
15498 turns an array of options for each profile. Each option has a
15499 name and a value, with the value currently always being a
15500 string. Note that the options array is not a map, as order mat‐
15501 ters and duplicate entries are possible. Recursive profiles are
15502 not expanded, and show up as special profile options.
15503 The profile-restore field is currently missing if it holds the
15505 default value (either because it was not set, or set explicitly
15506 to default), but in the future it might hold the value default.
15507 command-list
15509 The list of input commands. This returns an array of maps, where
15510 each map node represents a command. This map currently only has
15511 a single entry: name for the name of the command. (This property
15512 is supposed to be a replacement for --input-cmdlist. The option
15513 dumps some more information, but it's a valid feature request to
15514 extend this property if needed.)
15515 input-bindings
15517 The list of current input key bindings. This returns an array of
15518 maps, where each map node represents a binding for a single
15519 key/command. This map has the following entries:
15520 key The key name. This is normalized and may look slightly
15522 different from how it was specified in the source (e.g.
15523 in input.conf).
15524 cmd The command mapped to the key. (Currently, this is ex‐
15526 actly the same string as specified in the source, other
15527 than stripping whitespace and comments. It's possible
15528 that it will be normalized in the future.)
15529 is_weak
15531 If set to true, any existing and active user bindings
15532 will take priority.
15533 owner If this entry exists, the name of the script (or similar)
15535 which added this binding.
15536 section
15538 Name of the section this binding is part of. This is a
15539 rarely used mechanism. This entry may be removed or
15540 change meaning in the future.
15541 priority
15543 A number. Bindings with a higher value are preferred over
15544 bindings with a lower value. If the value is negative,
15545 this binding is inactive and will not be triggered by in‐
15546 put. Note that mpv does not use this value internally,
15547 and matching of bindings may work slightly differently in
15548 some cases. In addition, this value is dynamic and can
15549 change around at runtime.
15550 comment
15552 If available, the comment following the command on the
15553 same line. (For example, the input.conf entry f cycle bla
15554 # toggle bla would result in an entry with comment =
15555 "toggle bla", cmd = "cycle bla".)
15556 This property is read-only, and change notification is not sup‐
15558 ported. Currently, there is no mechanism to change key bindings
15559 at runtime, other than scripts adding or removing their own
15560 bindings.
15561 Inconsistencies between options and properties
15563 You can access (almost) all options as properties, though there are
15564 some caveats with some properties (due to historical reasons):
15565 vid, aid, sid
15567 While playback is active, these return the actually active
15568 tracks. For example, if you set aid=5, and the currently played
15569 file contains no audio track with ID 5, the aid property will
15570 return no.
15571 Before mpv 0.31.0, you could set existing tracks at runtime
15573 only.
15574 display-fps
15576 This inconsistent behavior is deprecated. Post-deprecation, the
15577 reported value and the option value are cleanly separated (over‐
15578 ride-display-fps for the option value).
15579 vf, af If you set the properties during playback, and the filter chain
15581 fails to reinitialize, the option will be set, but the runtime
15582 filter chain does not change. On the other hand, the next video
15583 to be played will fail, because the initial filter chain cannot
15584 be created.
15585 This behavior changed in mpv 0.31.0. Before this, the new value
15587 was rejected iff a video (for vf) or an audio (for af) track was
15588 active. If playback was not active, the behavior was the same as
15589 the current one.
15590 playlist
15592 The property is read-only and returns the current internal
15593 playlist. The option is for loading playlist during command line
15594 parsing. For client API uses, you should use the loadlist com‐
15595 mand instead.
15596 profile, include
15598 These are write-only, and will perform actions as they are writ‐
15599 ten to, exactly as if they were used on the mpv CLI commandline.
15600 Their only use is when using libmpv before mpv_initialize(),
15601 which in turn is probably only useful in encoding mode. Normal
15602 libmpv users should use other mechanisms, such as the apply-pro‐
15603 file command, and the mpv_load_config_file API function. Avoid
15604 these properties.
15605 Property Expansion
15607 All string arguments to input commands as well as certain options (like
15608 --term-playing-msg) are subject to property expansion. Note that prop‐
15609 erty expansion does not work in places where e.g. numeric parameters
15610 are expected. (For example, the add command does not do property ex‐
15611 pansion. The set command is an exception and not a general rule.)
15612 Example for input.conf
15614 i show-text "Filename: ${filename}"
15616 shows the filename of the current file when pressing the i
15617 key
15618 Whether property expansion is enabled by default depends on which API
15620 is used (see Flat command syntax, Commands specified as arrays and
15621 Named arguments), but it can always be enabled with the expand-proper‐
15622 ties prefix or disabled with the raw prefix, as described in Input Com‐
15623 mand Prefixes.
15624 The following expansions are supported:
15626 ${NAME}
15628 Expands to the value of the property NAME. If retrieving the
15629 property fails, expand to an error string. (Use ${NAME:} with a
15630 trailing : to expand to an empty string instead.) If NAME is
15631 prefixed with =, expand to the raw value of the property (see
15632 section below).
15633 ${NAME:STR}
15635 Expands to the value of the property NAME, or STR if the prop‐
15636 erty cannot be retrieved. STR is expanded recursively.
15637 ${?NAME:STR}
15639 Expands to STR (recursively) if the property NAME is available.
15640 ${!NAME:STR}
15642 Expands to STR (recursively) if the property NAME cannot be re‐
15643 trieved.
15644 ${?NAME==VALUE:STR}
15646 Expands to STR (recursively) if the property NAME expands to a
15647 string equal to VALUE. You can prefix NAME with = in order to
15648 compare the raw value of a property (see section below). If the
15649 property is unavailable, or other errors happen when retrieving
15650 it, the value is never considered equal. Note that VALUE can't
15651 contain any of the characters : or }. Also, it is possible that
15652 escaping with " or % might be added in the future, should the
15653 need arise.
15654 ${!NAME==VALUE:STR}
15656 Same as with the ? variant, but STR is expanded if the value is
15657 not equal. (Using the same semantics as with ?.)
15658 $$ Expands to $.
15660 $} Expands to }. (To produce this character inside recursive expan‐
15662 sion.)
15663 $> Disable property expansion and special handling of $ for the
15665 rest of the string.
15666 In places where property expansion is allowed, C-style escapes are of‐
15668 ten accepted as well. Example:
15669 • \n becomes a newline character
15671 • \\ expands to \
15673 Raw and Formatted Properties
15675 Normally, properties are formatted as human-readable text, meant to be
15676 displayed on OSD or on the terminal. It is possible to retrieve an un‐
15677 formatted (raw) value from a property by prefixing its name with =.
15678 These raw values can be parsed by other programs and follow the same
15679 conventions as the options associated with the properties.
15680 Examples
15682 • ${time-pos} expands to 00:14:23 (if playback position is at 14
15684 minutes 23 seconds)
15685 • ${=time-pos} expands to 863.4 (same time, plus 400 milliseconds -
15687 milliseconds are normally not shown in the formatted case)
15688 Sometimes, the difference in amount of information carried by raw and
15690 formatted property values can be rather big. In some cases, raw values
15691 have more information, like higher precision than seconds with
15692 time-pos. Sometimes it is the other way around, e.g. aid shows track
15693 title and language in the formatted case, but only the track number if
15694 it is raw.
15695
15697 The On Screen Controller (short: OSC) is a minimal GUI integrated with
15698 mpv to offer basic mouse-controllability. It is intended to make inter‐
15699 action easier for new users and to enable precise and direct seeking.
15700 The OSC is enabled by default if mpv was compiled with Lua support. It
15702 can be disabled entirely using the --osc=no option.
15703 Using the OSC
15705 By default, the OSC will show up whenever the mouse is moved inside the
15706 player window and will hide if the mouse is not moved outside the OSC
15707 for 0.5 seconds or if the mouse leaves the window.
15708 The Interface
15710 +---------+----------+------------------------------------------+----------+
15711 | pl prev | pl next | title | cache |
15712 +------+--+---+------+---------+-----------+------+-------+-----+-----+----+
15713 | play | skip | skip | time | seekbar | time | audio | sub | vol | fs |
15714 | | back | frwd | elapsed | | left | | | | |
15715 +------+------+------+---------+-----------+------+-------+-----+-----+----+
15716 pl prev
15718 ┌──────────────┬────────────────────────────┐
15720 │left-click │ play previous file in │
15721 │ │ playlist │
15722 ├──────────────┼────────────────────────────┤
15723 │right-click │ show playlist │
15724 ├──────────────┼────────────────────────────┤
15725 │shift+L-click │ show playlist │
15726 └──────────────┴────────────────────────────┘
15727 pl next
15729 ┌──────────────┬────────────────────────────┐
15731 │left-click │ play next file in playlist │
15732 ├──────────────┼────────────────────────────┤
15733 │right-click │ show playlist │
15734 ├──────────────┼────────────────────────────┤
15735 │shift+L-click │ show playlist │
15736 └──────────────┴────────────────────────────┘
15737 title
15739 Displays current media-title, filename, custom title, or target chapter
15740 name while hovering the seekbar.
15741 ┌────────────┬────────────────────────────┐
15744 │left-click │ show playlist position and │
15745 │ │ length and full title │
15746 ├────────────┼────────────────────────────┤
15747 │right-click │ show filename │
15748 └────────────┴────────────────────────────┘
15749 cache
15751 Shows current cache fill status
15752 play
15755 ┌───────────┬───────────────────┐
15757 │left-click │ toggle play/pause │
15758 └───────────┴───────────────────┘
15759 skip back
15761 ┌──────────────┬────────────────────────────┐
15763 │left-click │ go to beginning of chapter │
15764 │ │ / previous chapter │
15765 ├──────────────┼────────────────────────────┤
15766 │right-click │ show chapters │
15767 ├──────────────┼────────────────────────────┤
15768 │shift+L-click │ show chapters │
15769 └──────────────┴────────────────────────────┘
15770 skip frwd
15772 ┌──────────────┬────────────────────┐
15774 │left-click │ go to next chapter │
15775 ├──────────────┼────────────────────┤
15776 │right-click │ show chapters │
15777 ├──────────────┼────────────────────┤
15778 │shift+L-click │ show chapters │
15779 └──────────────┴────────────────────┘
15780 time elapsed
15782 Shows current playback position timestamp
15783 ┌───────────┬────────────────────────────┐
15786 │left-click │ toggle displaying time‐ │
15787 │ │ codes with milliseconds │
15788 └───────────┴────────────────────────────┘
15789 seekbar
15791 Indicates current playback position and position of chapters
15792 ┌───────────┬──────────────────┐
15795 │left-click │ seek to position │
15796 └───────────┴──────────────────┘
15797 time left
15799 Shows remaining playback time timestamp
15800 ┌───────────┬────────────────────────────┐
15803 │left-click │ toggle between total and │
15804 │ │ remaining time │
15805 └───────────┴────────────────────────────┘
15806 audio and sub
15808 Displays selected track and amount of available tracks
15809 ┌──────────────┬────────────────────────────┐
15812 │left-click │ cycle audio/sub tracks │
15813 │ │ forward │
15814 ├──────────────┼────────────────────────────┤
15815 │right-click │ cycle audio/sub tracks │
15816 │ │ backwards │
15817 ├──────────────┼────────────────────────────┤
15818 │shift+L-click │ show available audio/sub │
15819 │ │ tracks │
15820 └──────────────┴────────────────────────────┘
15821 vol
15823 ┌────────────┬────────────────┐
15825 │left-click │ toggle mute │
15826 ├────────────┼────────────────┤
15827 │mouse wheel │ volume up/down │
15828 └────────────┴────────────────┘
15829 fs
15831 ┌───────────┬───────────────────┐
15833 │left-click │ toggle fullscreen │
15834 └───────────┴───────────────────┘
15835 Key Bindings
15837 These key bindings are active by default if nothing else is already
15838 bound to these keys. In case of collision, the function needs to be
15839 bound to a different key. See the Script Commands section.
15840 ┌────┬────────────────────────────┐
15842 │del │ Cycles visibility between │
15843 │ │ never / auto (mouse-move) │
15844 │ │ / always │
15845 └────┴────────────────────────────┘
15846 Configuration
15848 The OSC offers limited configuration through a config file
15849 script-opts/osc.conf placed in mpv's user dir and through the
15850 --script-opts command-line option. Options provided through the com‐
15851 mand-line will override those from the config file.
15852 Config Syntax
15854 The config file must exactly follow the following syntax:
15855 # this is a comment
15857 optionA=value1
15858 optionB=value2
15859 # can only be used at the beginning of a line and there may be no spa‐
15861 ces around the = or anywhere else.
15862 Command-line Syntax
15864 To avoid collisions with other scripts, all options need to be prefixed
15865 with osc-.
15866 Example:
15868 --script-opts=osc-optionA=value1,osc-optionB=value2
15870 Configurable Options
15872 layout Default: bottombar
15873 The layout for the OSC. Currently available are: box, slimbox,
15875 bottombar and topbar. Default pre-0.21.0 was 'box'.
15876 seekbarstyle
15878 Default: bar
15879 Sets the style of the playback position marker and overall shape
15881 of the seekbar: bar, diamond or knob.
15882 seekbarhandlesize
15884 Default: 0.6
15885 Size ratio of the seek handle if seekbarstyle is set to diamond
15887 or knob. This is relative to the full height of the seekbar.
15888 seekbarkeyframes
15890 Default: yes
15891 Controls the mode used to seek when dragging the seekbar. If set
15893 to yes, default seeking mode is used (usually keyframes, but
15894 player defaults and heuristics can change it to exact). If set
15895 to no, exact seeking on mouse drags will be used instead.
15896 Keyframes are preferred, but exact seeks may be useful in cases
15897 where keyframes cannot be found. Note that using exact seeks can
15898 potentially make mouse dragging much slower.
15899 seekrangestyle
15901 Default: inverted
15902 Display seekable ranges on the seekbar. bar shows them on the
15904 full height of the bar, line as a thick line and inverted as a
15905 thin line that is inverted over playback position markers. none
15906 will hide them. Additionally, slider will show a permanent han‐
15907 dle inside the seekbar with cached ranges marked inside. Note
15908 that these will look differently based on the seekbarstyle op‐
15909 tion. Also, slider does not work with seekbarstyle set to bar.
15910 seekrangeseparate
15912 Default: yes
15913 Controls whether to show line-style seekable ranges on top of
15915 the seekbar or separately if seekbarstyle is set to bar.
15916 seekrangealpha
15918 Default: 200
15919 Alpha of the seekable ranges, 0 (opaque) to 255 (fully transpar‐
15921 ent).
15922 deadzonesize
15924 Default: 0.5
15925 Size of the deadzone. The deadzone is an area that makes the
15927 mouse act like leaving the window. Movement there won't make the
15928 OSC show up and it will hide immediately if the mouse enters it.
15929 The deadzone starts at the window border opposite to the OSC and
15930 the size controls how much of the window it will span. Values
15931 between 0.0 and 1.0, where 0 means the OSC will always popup
15932 with mouse movement in the window, and 1 means the OSC will only
15933 show up when the mouse hovers it. Default pre-0.21.0 was 0.
15934 minmousemove
15936 Default: 0
15937 Minimum amount of pixels the mouse has to move between ticks to
15939 make the OSC show up. Default pre-0.21.0 was 3.
15940 showwindowed
15942 Default: yes
15943 Enable the OSC when windowed
15945 showfullscreen
15947 Default: yes
15948 Enable the OSC when fullscreen
15950 idlescreen
15952 Default: yes
15953 Show the mpv logo and message when idle
15955 scalewindowed
15957 Default: 1.0
15958 Scale factor of the OSC when windowed.
15960 scalefullscreen
15962 Default: 1.0
15963 Scale factor of the OSC when fullscreen
15965 scaleforcedwindow
15967 Default: 2.0
15968 Scale factor of the OSC when rendered on a forced (dummy) window
15970 vidscale
15972 Default: yes
15973 Scale the OSC with the video no tries to keep the OSC size con‐
15975 stant as much as the window size allows
15976 valign Default: 0.8
15978 Vertical alignment, -1 (top) to 1 (bottom)
15980 halign Default: 0.0
15982 Horizontal alignment, -1 (left) to 1 (right)
15984 barmargin
15986 Default: 0
15987 Margin from bottom (bottombar) or top (topbar), in pixels
15989 boxalpha
15991 Default: 80
15992 Alpha of the background box, 0 (opaque) to 255 (fully transpar‐
15994 ent)
15995 hidetimeout
15997 Default: 500
15998 Duration in ms until the OSC hides if no mouse movement, must
16000 not be negative
16001 fadeduration
16003 Default: 200
16004 Duration of fade out in ms, 0 = no fade
16006 title Default: ${media-title}
16008 String that supports property expansion that will be displayed
16010 as OSC title. ASS tags are escaped, and newlines and trailing
16011 slashes are stripped.
16012 tooltipborder
16014 Default: 1
16015 Size of the tooltip outline when using bottombar or topbar lay‐
16017 outs
16018 timetotal
16020 Default: no
16021 Show total time instead of time remaining
16023 timems Default: no
16025 Display timecodes with milliseconds
16027 tcspace
16029 Default: 100 (allowed: 50-200)
16030 Adjust space reserved for timecodes (current time and time re‐
16032 maining) in the bottombar and topbar layouts. The timecode width
16033 depends on the font, and with some fonts the spacing near the
16034 timecodes becomes too small. Use values above 100 to increase
16035 that spacing, or below 100 to decrease it.
16036 visibility
16038 Default: auto (auto hide/show on mouse move)
16039 Also supports never and always
16041 boxmaxchars
16043 Default: 80
16044 Max chars for the osc title at the box layout. mpv does not mea‐
16046 sure the text width on screen and so it needs to limit it by
16047 number of chars. The default is conservative to allow wide fonts
16048 to be used without overflow. However, with many common fonts a
16049 bigger number can be used. YMMV.
16050 boxvideo
16052 Default: no
16053 Whether to overlay the osc over the video (no), or to box the
16055 video within the areas not covered by the osc (yes). If this op‐
16056 tion is set, the osc may overwrite the --video-margin-ratio-*
16057 options, even if the user has set them. (It will not overwrite
16058 them if all of them are set to default values.) Additionally,
16059 visibility must be set to always. Otherwise, this option does
16060 nothing.
16061 Currently, this is supported for the bottombar and topbar layout
16063 only. The other layouts do not change if this option is set.
16064 Separately, if window controls are present (see below), they
16065 will be affected regardless of which osc layout is in use.
16066 The border is static and appears even if the OSC is configured
16068 to appear only on mouse interaction. If the OSC is invisible,
16069 the border is simply filled with the background color (black by
16070 default).
16071 This currently still makes the OSC overlap with subtitles (if
16073 the --sub-use-margins option is set to yes, the default). This
16074 may be fixed later.
16075 This does not work correctly with video outputs like --vo=xv,
16077 which render OSD into the unscaled video.
16078 windowcontrols
16080 Default: auto (Show window controls if there is no window bor‐
16081 der)
16082 Whether to show window management controls over the video, and
16084 if so, which side of the window to place them. This may be de‐
16085 sirable when the window has no decorations, either because they
16086 have been explicitly disabled (border=no) or because the current
16087 platform doesn't support them (eg: gnome-shell with wayland).
16088 The set of window controls is fixed, offering minimize, maxi‐
16090 mize, and quit. Not all platforms implement minimize and maxi‐
16091 mize, but quit will always work.
16092 windowcontrols_alignment
16094 Default: right
16095 If window controls are shown, indicates which side should they
16097 be aligned to.
16098 Supports left and right which will place the controls on those
16100 respective sides.
16101 greenandgrumpy
16103 Default: no
16104 Set to yes to reduce festivity (i.e. disable santa hat in Decem‐
16106 ber.)
16107 livemarkers
16109 Default: yes
16110 Update chapter markers positions on duration changes, e.g. live
16112 streams. The updates are unoptimized - consider disabling it on
16113 very low-end systems.
16114 chapters_osd, playlist_osd
16116 Default: yes
16117 Whether to display the chapters/playlist at the OSD when
16119 left-clicking the next/previous OSC buttons, respectively.
16120 chapter_fmt
16122 Default: Chapter: %s
16123 Template for the chapter-name display when hovering the seekbar.
16125 Use no to disable chapter display on hover. Otherwise it's a lua
16126 string.format template and %s is replaced with the actual name.
16127 unicodeminus
16129 Default: no
16130 Use a Unicode minus sign instead of an ASCII hyphen when dis‐
16132 playing the remaining playback time.
16133 Script Commands
16135 The OSC script listens to certain script commands. These commands can
16136 bound in input.conf, or sent by other scripts.
16137 osc-message
16139 Show a message on screen using the OSC. First argument is the
16140 message, second the duration in seconds.
16141 osc-visibility
16143 Controls visibility mode never / auto (on mouse move) / always
16144 and also cycle to cycle between the modes
16145 Example
16147 You could put this into input.conf to hide the OSC with the a key and
16149 to set auto mode (the default) with b:
16150 a script-message osc-visibility never
16152 b script-message osc-visibility auto
16153 osc-idlescreen
16155 Controls the visibility of the mpv logo on idle. Valid arguments
16156 are yes, no, and cycle to toggle between yes and no.
16157 osc-playlist, osc-chapterlist, osc-tracklist
16159 Shows a limited view of the respective type of list using the
16160 OSC. First argument is duration in seconds.
16161
16163 This builtin script displays information and statistics for the cur‐
16164 rently played file. It is enabled by default if mpv was compiled with
16165 Lua support. It can be disabled entirely using the --load-stats-over‐
16166 lay=no option.
16167 Usage
16169 The following key bindings are active by default unless something else
16170 is already bound to them:
16171 ┌──┬────────────────────────────┐
16173 │i │ Show stats for a fixed du‐ │
16174 │ │ ration │
16175 ├──┼────────────────────────────┤
16176 │I │ Toggle stats (shown until │
16177 │ │ toggled again) │
16178 └──┴────────────────────────────┘
16179 While the stats are visible on screen the following key bindings are
16181 active, regardless of existing bindings. They allow you to switch be‐
16182 tween pages of stats:
16183 ┌──┬────────────────────────────┐
16185 │1 │ Show usual stats │
16186 ├──┼────────────────────────────┤
16187 │2 │ Show frame timings │
16188 │ │ (scroll) │
16189 ├──┼────────────────────────────┤
16190 │3 │ Input cache stats │
16191 ├──┼────────────────────────────┤
16192 │4 │ Active key bindings │
16193 │ │ (scroll) │
16194 ├──┼────────────────────────────┤
16195 │0 │ Internal stuff (scroll) │
16196 └──┴────────────────────────────┘
16197 On pages which support scroll, these key bindings are also active:
16199 ┌─────┬──────────────────────┐
16201 │UP │ Scroll one line up │
16202 ├─────┼──────────────────────┤
16203 │DOWN │ Scroll one line down │
16204 └─────┴──────────────────────┘
16205 Configuration
16207 This script can be customized through a config file
16208 script-opts/stats.conf placed in mpv's user directory and through the
16209 --script-opts command-line option. The configuration syntax is de‐
16210 scribed in ON SCREEN CONTROLLER.
16211 Configurable Options
16213 key_page_1
16214 Default: 1
16215 key_page_2
16217 Default: 2
16218 key_page_3
16220 Default: 3
16221 key_page_4
16223 Default: 4
16224 key_page_0
16226 Default: 0
16227 Key bindings for page switching while stats are displayed.
16229 key_scroll_up
16231 Default: UP
16232 key_scroll_down
16234 Default: DOWN
16235 scroll_lines
16237 Default: 1
16238 Scroll key bindings and number of lines to scroll on pages which
16240 support it.
16241 duration
16243 Default: 4
16244 How long the stats are shown in seconds (oneshot).
16246 redraw_delay
16248 Default: 1
16249 How long it takes to refresh the displayed stats in seconds
16251 (toggling).
16252 persistent_overlay
16254 Default: no
16255 When no, other scripts printing text to the screen can overwrite
16257 the displayed stats. When yes, displayed stats are persistently
16258 shown for the respective duration. This can result in overlap‐
16259 ping text when multiple scripts decide to print text at the same
16260 time.
16261 plot_perfdata
16263 Default: yes
16264 Show graphs for performance data (page 2).
16266 plot_vsync_ratio
16268 Default: yes
16269 plot_vsync_jitter
16271 Default: yes
16272 Show graphs for vsync and jitter values (page 1). Only when tog‐
16274 gled.
16275 flush_graph_data
16277 Default: yes
16278 Clear data buffers used for drawing graphs when toggling.
16280 font Default: sans-serif
16282 Font name. Should support as many font weights as possible for
16284 optimal visual experience.
16285 font_mono
16287 Default: monospace
16288 Font name for parts where monospaced characters are necessary to
16290 align text. Currently, monospaced digits are sufficient.
16291 font_size
16293 Default: 8
16294 Font size used to render text.
16296 font_color
16298 Default: FFFFFF
16299 Font color.
16301 border_size
16303 Default: 0.8
16304 Size of border drawn around the font.
16306 border_color
16308 Default: 262626
16309 Color of drawn border.
16311 alpha Default: 11
16313 Transparency for drawn text.
16315 plot_bg_border_color
16317 Default: 0000FF
16318 Border color used for drawing graphs.
16320 plot_bg_color
16322 Default: 262626
16323 Background color used for drawing graphs.
16325 plot_color
16327 Default: FFFFFF
16328 Color used for drawing graphs.
16330 Note: colors are given as hexadecimal values and use ASS tag order:
16332 BBGGRR (blue green red).
16333 Different key bindings
16335 Additional keys can be configured in input.conf to display the stats:
16336 e script-binding stats/display-stats
16338 E script-binding stats/display-stats-toggle
16339 And to display a certain page directly:
16341 i script-binding stats/display-page-1
16343 e script-binding stats/display-page-2
16344 Active key bindings page
16346 Lists the active key bindings and the commands they're bound to, ex‐
16347 cluding the interactive keys of the stats script itself. See also --in‐
16348 put-test for more detailed view of each binding.
16349 The keys are grouped automatically using a simple analysis of the com‐
16351 mand string, and one should not expect documentation-level grouping ac‐
16352 curacy, however, it should still be reasonably useful.
16353 Using --idle --script-opts=stats-bindlist=yes will print the list to
16355 the terminal and quit immediately. By default long lines are shortened
16356 to 79 chars, and terminal escape sequences are enabled. A different
16357 length limit can be set by changing yes to a number (at least 40), and
16358 escape sequences can be disabled by adding - before the value, e.g.
16359 ...=-yes or ...=-120.
16360 Like with --input-test, the list includes bindings from input.conf and
16362 from user scripts. Use --no-config to list only built-in bindings.
16363 Internal stuff page
16365 Most entries shown on this page have rather vague meaning. Likely none
16366 of this is useful for you. Don't attempt to use it. Forget its exis‐
16367 tence.
16368 Selecting this for the first time will start collecting some internal
16370 performance data. That means performance will be slightly lower than
16371 normal for the rest of the time the player is running (even if the
16372 stats page is closed). Note that the stats page itself uses a lot of
16373 CPU and even GPU resources, and may have a heavy impact on performance.
16374 The displayed information is accumulated over the redraw delay (shown
16376 as poll-time field).
16377 This adds entries for each Lua script. If there are too many scripts
16379 running, parts of the list will simply be out of the screen, but it can
16380 be scrolled.
16381 If the underlying platform does not support pthread per thread times,
16383 the displayed times will be 0 or something random (I suspect that at
16384 time of this writing, only Linux provides the correct via pthread APIs
16385 for per thread times).
16386 Most entries are added lazily and only during data collection, which is
16388 why entries may pop up randomly after some time. It's also why the mem‐
16389 ory usage entries for scripts that have been inactive since the start
16390 of data collection are missing.
16391 Memory usage is approximate and does not reflect internal fragmenta‐
16393 tion.
16394 JS scripts memory reporting is disabled by default because collecting
16396 the data at the JS side has an overhead. It can be enabled by exporting
16397 the env var MPV_LEAK_REPORT=1 before starting mpv, and will increase JS
16398 memory usage.
16399 If entries have /time and /cpu variants, the former gives the real time
16401 (monotonic clock), while the latter the thread CPU time (only if the
16402 corresponding pthread API works and is supported).
16403
16405 The console is a REPL for mpv input commands. It is displayed on the
16406 video window. It also shows log messages. It can be disabled entirely
16407 using the --load-osd-console=no option.
16408 Keybindings
16410 ` Show the console.
16411 ESC Hide the console.
16413 ENTER, Ctrl+J and Ctrl+M
16415 Run the typed command.
16416 Shift+ENTER
16418 Type a literal newline character.
16419 LEFT and Ctrl+B
16421 Move the cursor to the previous character.
16422 RIGHT and Ctrl+F
16424 Move the cursor to the next character.
16425 Ctrl+LEFT and Alt+B
16427 Move the cursor to the beginning of the current word, or if be‐
16428 tween words, to the beginning of the previous word.
16429 Ctrl+RIGHT and Alt+F
16431 Move the cursor to the end of the current word, or if between
16432 words, to the end of the next word.
16433 HOME and Ctrl+A
16435 Move the cursor to the start of the current line.
16436 END and Ctrl+E
16438 Move the cursor to the end of the current line.
16439 BACKSPACE and Ctrl+H
16441 Delete the previous character.
16442 Ctrl+D Hide the console if the current line is empty, otherwise delete
16444 the next character.
16445 Ctrl+BACKSPACE and Ctrl+W
16447 Delete text from the cursor to the beginning of the current
16448 word, or if between words, to the beginning of the previous
16449 word.
16450 Ctrl+DEL and Alt+D
16452 Delete text from the cursor to the end of the current word, or
16453 if between words, to the end of the next word.
16454 Ctrl+U Delete text from the cursor to the beginning of the current
16456 line.
16457 Ctrl+K Delete text from the cursor to the end of the current line.
16459 Ctrl+C Clear the current line.
16461 UP and Ctrl+P
16463 Move back in the command history.
16464 DOWN and Ctrl+N
16466 Move forward in the command history.
16467 PGUP Go to the first command in the history.
16469 PGDN Stop navigating the command history.
16471 INSERT Toggle insert mode.
16473 Ctrl+V Paste text (uses the clipboard on X11 and Wayland).
16475 Shift+INSERT
16477 Paste text (uses the primary selection on X11 and Wayland).
16478 TAB and Ctrl+I
16480 Complete the command or property name at the cursor.
16481 Ctrl+L Clear all log messages from the console.
16483 Commands
16485 script-message-to console type <text> [<cursor_pos>]
16486 Show the console and pre-fill it with the provided text, option‐
16487 ally specifying the initial cursor position as a positive inte‐
16488 ger starting from 1.
16489 Example for input.conf
16491 % script-message-to console type "seek absolute-per‐
16493 cent" 6
16494 Known issues
16496 • Pasting text is slow on Windows
16497 • Non-ASCII keyboard input has restrictions
16499 • The cursor keys move between Unicode code-points, not grapheme clus‐
16501 ters
16502 Configuration
16504 This script can be customized through a config file script-opts/con‐
16505 sole.conf placed in mpv's user directory and through the --script-opts
16506 command-line option. The configuration syntax is described in ON SCREEN
16507 CONTROLLER.
16508 Key bindings can be changed in a standard way, see for example
16510 stats.lua documentation.
16511 Configurable Options
16513 scale Default: 1
16514 All drawing is scaled by this value, including the text borders
16516 and the cursor.
16517 If the VO backend in use has HiDPI scale reporting implemented,
16519 the option value is scaled with the reported HiDPI scale.
16520 font Default: unset (picks a hardcoded font depending on detected
16522 platform)
16523 Set the font used for the REPL and the console. This probably
16525 doesn't have to be a monospaced font.
16526 font_size
16528 Default: 16
16529 Set the font size used for the REPL and the console. This will
16531 be multiplied by "scale".
16532 border_size
16534 Default: 1
16535 Set the font border size used for the REPL and the console.
16537 history_dedup
16539 Default: true
16540 Remove duplicate entries in history as to only keep the latest
16542 one.
16543
16545 mpv can load Lua scripts. (See Script location.)
16546 mpv provides the built-in module mp, which contains functions to send
16548 commands to the mpv core and to retrieve information about playback
16549 state, user settings, file information, and so on.
16550 These scripts can be used to control mpv in a similar way to slave
16552 mode. Technically, the Lua code uses the client API internally.
16553 Example
16555 A script which leaves fullscreen mode when the player is paused:
16556 function on_pause_change(name, value)
16558 if value == true then
16559 mp.set_property("fullscreen", "no")
16560 end
16561 end
16562 mp.observe_property("pause", "bool", on_pause_change)
16563 Script location
16565 Scripts can be passed to the --script option, and are automatically
16566 loaded from the scripts subdirectory of the mpv configuration directory
16567 (usually ~/.config/mpv/scripts/).
16568 A script can be a single file. The file extension is used to select the
16570 scripting backend to use for it. For Lua, it is .lua. If the extension
16571 is not recognized, an error is printed. (If an error happens, the ex‐
16572 tension is either mistyped, or the backend was not compiled into your
16573 mpv binary.)
16574 mpv internally loads the script's name by stripping the .lua extension
16576 and replacing all nonalphanumeric characters with _. E.g., my-tools.lua
16577 becomes my_tools. If there are several scripts with the same name, it
16578 is made unique by appending a number. This is the name returned by
16579 mp.get_script_name().
16580 Entries with .disable extension are always ignored.
16582 If a script is a directory (either if a directory is passed to
16584 --script, or any sub-directories in the script directory, such as for
16585 example ~/.config/mpv/scripts/something/), then the directory repre‐
16586 sents a single script. The player will try to load a file named main.x,
16587 where x is replaced with the file extension. For example, if main.lua
16588 exists, it is loaded with the Lua scripting backend.
16589 You must not put any other files or directories that start with main.
16591 into the script's top level directory. If the script directory contains
16592 for example both main.lua and main.js, only one of them will be loaded
16593 (and which one depends on mpv internals that may change any time).
16594 Likewise, if there is for example main.foo, your script will break as
16595 soon as mpv adds a backend that uses the .foo file extension.
16596 mpv also appends the top level directory of the script to the start of
16598 Lua's package path so you can import scripts from there too. Be aware
16599 that this will shadow Lua libraries that use the same package path.
16600 (Single file scripts do not include mpv specific directory the Lua
16601 package path. This was silently changed in mpv 0.32.0.)
16602 Using a script directory is the recommended way to package a script
16604 that consists of multiple source files, or requires other files (you
16605 can use mp.get_script_directory() to get the location and e.g. load
16606 data files).
16607 Making a script a git repository, basically a repository which contains
16609 a main.lua file in the root directory, makes scripts easily updateable
16610 (without the dangers of auto-updates). Another suggestion is to use git
16611 submodules to share common files or libraries.
16612 Details on the script initialization and lifecycle
16614 Your script will be loaded by the player at program start from the
16615 scripts configuration subdirectory, or from a path specified with the
16616 --script option. Some scripts are loaded internally (like --osc). Each
16617 script runs in its own thread. Your script is first run "as is", and
16618 once that is done, the event loop is entered. This event loop will dis‐
16619 patch events received by mpv and call your own event handlers which you
16620 have registered with mp.register_event, or timers added with
16621 mp.add_timeout or similar. Note that since the script starts execution
16622 concurrently with player initialization, some properties may not be
16623 populated with meaningful values until the relevant subsystems have
16624 initialized.
16625 When the player quits, all scripts will be asked to terminate. This
16627 happens via a shutdown event, which by default will make the event loop
16628 return. If your script got into an endless loop, mpv will probably be‐
16629 have fine during playback, but it won't terminate when quitting, be‐
16630 cause it's waiting on your script.
16631 Internally, the C code will call the Lua function mp_event_loop after
16633 loading a Lua script. This function is normally defined by the default
16634 prelude loaded before your script (see player/lua/defaults.lua in the
16635 mpv sources). The event loop will wait for events and dispatch events
16636 registered with mp.register_event. It will also handle timers added
16637 with mp.add_timeout and similar (by waiting with a timeout).
16638 Since mpv 0.6.0, the player will wait until the script is fully loaded
16640 before continuing normal operation. The player considers a script as
16641 fully loaded as soon as it starts waiting for mpv events (or it exits).
16642 In practice this means the player will more or less hang until the
16643 script returns from the main chunk (and mp_event_loop is called), or
16644 the script calls mp_event_loop or mp.dispatch_events directly. This is
16645 done to make it possible for a script to fully setup event handlers
16646 etc. before playback actually starts. In older mpv versions, this hap‐
16647 pened asynchronously. With mpv 0.29.0, this changes slightly, and it
16648 merely waits for scripts to be loaded in this manner before starting
16649 playback as part of the player initialization phase. Scripts run though
16650 initialization in parallel. This might change again.
16651 mp functions
16653 The mp module is preloaded, although it can be loaded manually with re‐
16654 quire 'mp'. It provides the core client API.
16655 mp.command(string)
16657 Run the given command. This is similar to the commands used in
16658 input.conf. See List of Input Commands.
16659 By default, this will show something on the OSD (depending on
16661 the command), as if it was used in input.conf. See Input Command
16662 Prefixes how to influence OSD usage per command.
16663 Returns true on success, or nil, error on error.
16665 mp.commandv(arg1, arg2, ...)
16667 Similar to mp.command, but pass each command argument as sepa‐
16668 rate parameter. This has the advantage that you don't have to
16669 care about quoting and escaping in some cases.
16670 Example:
16672 mp.command("loadfile " .. filename .. " append")
16674 mp.commandv("loadfile", filename, "append")
16675 These two commands are equivalent, except that the first version
16677 breaks if the filename contains spaces or certain special char‐
16678 acters.
16679 Note that properties are not expanded. You can use either
16681 mp.command, the expand-properties prefix, or the mp.get_property
16682 family of functions.
16683 Unlike mp.command, this will not use OSD by default either (ex‐
16685 cept for some OSD-specific commands).
16686 mp.command_native(table [,def])
16688 Similar to mp.commandv, but pass the argument list as table.
16689 This has the advantage that in at least some cases, arguments
16690 can be passed as native types. It also allows you to use named
16691 argument.
16692 If the table is an array, each array item is like an argument in
16694 mp.commandv() (but can be a native type instead of a string).
16695 If the table contains string keys, it's interpreted as command
16697 with named arguments. This requires at least an entry with the
16698 key name to be present, which must be a string, and contains the
16699 command name. The special entry _flags is optional, and if
16700 present, must be an array of Input Command Prefixes to apply.
16701 All other entries are interpreted as arguments.
16702 Returns a result table on success (usually empty), or def, error
16704 on error. def is the second parameter provided to the function,
16705 and is nil if it's missing.
16706 mp.command_native_async(table [,fn])
16708 Like mp.command_native(), but the command is ran asynchronously
16709 (as far as possible), and upon completion, fn is called. fn has
16710 three arguments: fn(success, result, error):
16711 success
16713 Always a Boolean and is true if the command was
16714 successful, otherwise false.
16715 result The result value (can be nil) in case of success, nil
16717 otherwise (as returned by mp.command_native()).
16718 error The error string in case of an error, nil otherwise.
16720 Returns a table with undefined contents, which can be used as
16722 argument for mp.abort_async_command.
16723 If starting the command failed for some reason, nil, error is
16725 returned, and fn is called indicating failure, using the same
16726 error value.
16727 fn is always called asynchronously, even if the command failed
16729 to start.
16730 mp.abort_async_command(t)
16732 Abort a mp.command_native_async call. The argument is the return
16733 value of that command (which starts asynchronous execution of
16734 the command). Whether this works and how long it takes depends
16735 on the command and the situation. The abort call itself is asyn‐
16736 chronous. Does not return anything.
16737 mp.del_property(name [,def])
16739 Delete the given property. See mp.get_property and Properties
16740 for more information about properties. Most properties cannot be
16741 deleted.
16742 Returns true on success, or nil, error on error.
16744 mp.get_property(name [,def])
16746 Return the value of the given property as string. These are the
16747 same properties as used in input.conf. See Properties for a list
16748 of properties. The returned string is formatted similar to
16749 ${=name} (see Property Expansion).
16750 Returns the string on success, or def, error on error. def is
16752 the second parameter provided to the function, and is nil if
16753 it's missing.
16754 mp.get_property_osd(name [,def])
16756 Similar to mp.get_property, but return the property value for‐
16757 matted for OSD. This is the same string as printed with ${name}
16758 when used in input.conf.
16759 Returns the string on success, or def, error on error. def is
16761 the second parameter provided to the function, and is an empty
16762 string if it's missing. Unlike get_property(), assigning the re‐
16763 turn value to a variable will always result in a string.
16764 mp.get_property_bool(name [,def])
16766 Similar to mp.get_property, but return the property value as
16767 Boolean.
16768 Returns a Boolean on success, or def, error on error.
16770 mp.get_property_number(name [,def])
16772 Similar to mp.get_property, but return the property value as
16773 number.
16774 Note that while Lua does not distinguish between integers and
16776 floats, mpv internals do. This function simply request a double
16777 float from mpv, and mpv will usually convert integer property
16778 values to float.
16779 Returns a number on success, or def, error on error.
16781 mp.get_property_native(name [,def])
16783 Similar to mp.get_property, but return the property value using
16784 the best Lua type for the property. Most time, this will return
16785 a string, Boolean, or number. Some properties (for example chap‐
16786 ter-list) are returned as tables.
16787 Returns a value on success, or def, error on error. Note that
16789 nil might be a possible, valid value too in some corner cases.
16790 mp.set_property(name, value)
16792 Set the given property to the given string value. See
16793 mp.get_property and Properties for more information about prop‐
16794 erties.
16795 Returns true on success, or nil, error on error.
16797 mp.set_property_bool(name, value)
16799 Similar to mp.set_property, but set the given property to the
16800 given Boolean value.
16801 mp.set_property_number(name, value)
16803 Similar to mp.set_property, but set the given property to the
16804 given numeric value.
16805 Note that while Lua does not distinguish between integers and
16807 floats, mpv internals do. This function will test whether the
16808 number can be represented as integer, and if so, it will pass an
16809 integer value to mpv, otherwise a double float.
16810 mp.set_property_native(name, value)
16812 Similar to mp.set_property, but set the given property using its
16813 native type.
16814 Since there are several data types which cannot represented na‐
16816 tively in Lua, this might not always work as expected. For exam‐
16817 ple, while the Lua wrapper can do some guesswork to decide
16818 whether a Lua table is an array or a map, this would fail with
16819 empty tables. Also, there are not many properties for which it
16820 makes sense to use this, instead of set_property, set_prop‐
16821 erty_bool, set_property_number. For these reasons, this func‐
16822 tion should probably be avoided for now, except for properties
16823 that use tables natively.
16824 mp.get_time()
16826 Return the current mpv internal time in seconds as a number.
16827 This is basically the system time, with an arbitrary offset.
16828 mp.add_key_binding(key, name|fn [,fn [,flags]])
16830 Register callback to be run on a key binding. The binding will
16831 be mapped to the given key, which is a string describing the
16832 physical key. This uses the same key names as in input.conf, and
16833 also allows combinations (e.g. ctrl+a). If the key is empty or
16834 nil, no physical key is registered, but the user still can cre‐
16835 ate own bindings (see below).
16836 After calling this function, key presses will cause the function
16838 fn to be called (unless the user remapped the key with another
16839 binding).
16840 The name argument should be a short symbolic string. It allows
16842 the user to remap the key binding via input.conf using the
16843 script-message command, and the name of the key binding (see be‐
16844 low for an example). The name should be unique across other
16845 bindings in the same script - if not, the previous binding with
16846 the same name will be overwritten. You can omit the name, in
16847 which case a random name is generated internally. (Omitting
16848 works as follows: either pass nil for name, or pass the fn argu‐
16849 ment in place of the name. The latter is not recommended and is
16850 handled for compatibility only.)
16851 The last argument is used for optional flags. This is a table,
16853 which can have the following entries:
16854 repeatable
16856 If set to true, enables key repeat for this specific
16857 binding.
16858 complex
16860 If set to true, then fn is called on both key up and
16861 down events (as well as key repeat, if enabled), with
16862 the first argument being a table. This table has the
16863 following entries (and may contain undocumented ones):
16864 event Set to one of the strings down, repeat, up
16866 or press (the latter if key up/down can't
16867 be tracked).
16868 is_mouse
16870 Boolean Whether the event was caused by a
16871 mouse button.
16872 key_name
16874 The name of they key that triggered this,
16875 or nil if invoked artificially. If the key
16876 name is unknown, it's an empty string.
16877 key_text
16879 Text if triggered by a text key, otherwise
16880 nil. See description of script-binding com‐
16881 mand for details (this field is equivalent
16882 to the 5th argument).
16883 Internally, key bindings are dispatched via the script-mes‐
16885 sage-to or script-binding input commands and mp.regis‐
16886 ter_script_message.
16887 Trying to map multiple commands to a key will essentially prefer
16889 a random binding, while the other bindings are not called. It is
16890 guaranteed that user defined bindings in the central input.conf
16891 are preferred over bindings added with this function (but see
16892 mp.add_forced_key_binding).
16893 Example:
16895 function something_handler()
16897 print("the key was pressed")
16898 end
16899 mp.add_key_binding("x", "something", something_handler)
16900 This will print the message the key was pressed when x was
16902 pressed.
16903 The user can remap these key bindings. Then the user has to put
16905 the following into their input.conf to remap the command to the
16906 y key:
16907 y script-binding something
16909 This will print the message when the key y is pressed. (x will
16911 still work, unless the user remaps it.)
16912 You can also explicitly send a message to a named script only.
16914 Assume the above script was using the filename fooscript.lua:
16915 y script-binding fooscript/something
16917 mp.add_forced_key_binding(...)
16919 This works almost the same as mp.add_key_binding, but registers
16920 the key binding in a way that will overwrite the user's custom
16921 bindings in their input.conf. (mp.add_key_binding overwrites de‐
16922 fault key bindings only, but not those by the user's in‐
16923 put.conf.)
16924 mp.remove_key_binding(name)
16926 Remove a key binding added with mp.add_key_binding or
16927 mp.add_forced_key_binding. Use the same name as you used when
16928 adding the bindings. It's not possible to remove bindings for
16929 which you omitted the name.
16930 mp.register_event(name, fn)
16932 Call a specific function when an event happens. The event name
16933 is a string, and the function fn is a Lua function value.
16934 Some events have associated data. This is put into a Lua table
16936 and passed as argument to fn. The Lua table by default contains
16937 a name field, which is a string containing the event name. If
16938 the event has an error associated, the error field is set to a
16939 string describing the error, on success it's not set.
16940 If multiple functions are registered for the same event, they
16942 are run in registration order, which the first registered func‐
16943 tion running before all the other ones.
16944 Returns true if such an event exists, false otherwise.
16946 See Events and List of events for details.
16948 mp.unregister_event(fn)
16950 Undo mp.register_event(..., fn). This removes all event handlers
16951 that are equal to the fn parameter. This uses normal Lua == com‐
16952 parison, so be careful when dealing with closures.
16953 mp.observe_property(name, type, fn)
16955 Watch a property for changes. If the property name is changed,
16956 then the function fn(name) will be called. type can be nil, or
16957 be set to one of none, native, bool, string, or number. none is
16958 the same as nil. For all other values, the new value of the
16959 property will be passed as second argument to fn, using
16960 mp.get_property_<type> to retrieve it. This means if type is for
16961 example string, fn is roughly called as in fn(name, mp.get_prop‐
16962 erty_string(name)).
16963 If possible, change events are coalesced. If a property is
16965 changed a bunch of times in a row, only the last change triggers
16966 the change function. (The exact behavior depends on timing and
16967 other things.)
16968 If a property is unavailable, or on error, the value argument to
16970 fn is nil. (The observe_property() call always succeeds, even if
16971 a property does not exist.)
16972 In some cases the function is not called even if the property
16974 changes. This depends on the property, and it's a valid feature
16975 request to ask for better update handling of a specific prop‐
16976 erty.
16977 If the type is none or nil, sporadic property change events are
16979 possible. This means the change function fn can be called even
16980 if the property doesn't actually change.
16981 You always get an initial change notification. This is meant to
16983 initialize the user's state to the current value of the prop‐
16984 erty.
16985 mp.unobserve_property(fn)
16987 Undo mp.observe_property(..., fn). This removes all property
16988 handlers that are equal to the fn parameter. This uses normal
16989 Lua == comparison, so be careful when dealing with closures.
16990 mp.add_timeout(seconds, fn)
16992 Call the given function fn when the given number of seconds has
16993 elapsed. Note that the number of seconds can be fractional. For
16994 now, the timer's resolution may be as low as 50 ms, although
16995 this will be improved in the future.
16996 This is a one-shot timer: it will be removed when it's fired.
16998 Returns a timer object. See mp.add_periodic_timer for details.
17000 mp.add_periodic_timer(seconds, fn)
17002 Call the given function periodically. This is like mp.add_time‐
17003 out, but the timer is re-added after the function fn is run.
17004 Returns a timer object. The timer object provides the following
17006 methods:
17007 stop() Disable the timer. Does nothing if the timer is
17009 already disabled. This will remember the current
17010 elapsed time when stopping, so that resume() es‐
17011 sentially unpauses the timer.
17012 kill() Disable the timer. Resets the elapsed time. re‐
17014 sume() will restart the timer.
17015 resume()
17017 Restart the timer. If the timer was disabled with
17018 stop(), this will resume at the time it was
17019 stopped. If the timer was disabled with kill(), or
17020 if it's a previously fired one-shot timer (added
17021 with add_timeout()), this starts the timer from
17022 the beginning, using the initially configured
17023 timeout.
17024 is_enabled()
17026 Whether the timer is currently enabled or was pre‐
17027 viously disabled (e.g. by stop() or kill()).
17028 timeout (RW)
17030 This field contains the current timeout period.
17031 This value is not updated as time progresses. It's
17032 only used to calculate when the timer should fire
17033 next when the timer expires.
17034 If you write this, you can call t:kill() ; t:re‐
17036 sume() to reset the current timeout to the new
17037 one. (t:stop() won't use the new timeout.)
17038 oneshot (RW)
17040 Whether the timer is periodic (false) or fires
17041 just once (true). This value is used when the
17042 timer expires (but before the timer callback func‐
17043 tion fn is run).
17044 Note that these are methods, and you have to call them using :
17046 instead of . (Refer to
17047 https://www.lua.org/manual/5.2/manual.html#3.4.9 .)
17048 Example:
17050 seconds = 0
17052 timer = mp.add_periodic_timer(1, function()
17053 print("called every second")
17054 # stop it after 10 seconds
17055 seconds = seconds + 1
17056 if seconds >= 10 then
17057 timer:kill()
17058 end
17059 end)
17060 mp.get_opt(key)
17062 Return a setting from the --script-opts option. It's up to the
17063 user and the script how this mechanism is used. Currently, all
17064 scripts can access this equally, so you should be careful about
17065 collisions.
17066 mp.get_script_name()
17068 Return the name of the current script. The name is usually made
17069 of the filename of the script, with directory and file extension
17070 removed. If there are several scripts which would have the same
17071 name, it's made unique by appending a number. Any nonalphanu‐
17072 meric characters are replaced with _.
17073 Example
17075 The script /path/to/foo-script.lua becomes foo_script.
17077 mp.get_script_directory()
17079 Return the directory if this is a script packaged as directory
17080 (see Script location for a description). Return nothing if this
17081 is a single file script.
17082 mp.osd_message(text [,duration])
17084 Show an OSD message on the screen. duration is in seconds, and
17085 is optional (uses --osd-duration by default).
17086 Advanced mp functions
17088 These also live in the mp module, but are documented separately as they
17089 are useful only in special situations.
17090 mp.get_wakeup_pipe()
17092 Calls mpv_get_wakeup_pipe() and returns the read end of the
17093 wakeup pipe. This is deprecated, but still works. (See client.h
17094 for details.)
17095 mp.get_next_timeout()
17097 Return the relative time in seconds when the next timer
17098 (mp.add_timeout and similar) expires. If there is no timer, re‐
17099 turn nil.
17100 mp.dispatch_events([allow_wait])
17102 This can be used to run custom event loops. If you want to have
17103 direct control what the Lua script does (instead of being called
17104 by the default event loop), you can set the global variable
17105 mp_event_loop to your own function running the event loop. From
17106 your event loop, you should call mp.dispatch_events() to dequeue
17107 and dispatch mpv events.
17108 If the allow_wait parameter is set to true, the function will
17110 block until the next event is received or the next timer ex‐
17111 pires. Otherwise (and this is the default behavior), it returns
17112 as soon as the event loop is emptied. It's strongly recommended
17113 to use mp.get_next_timeout() and mp.get_wakeup_pipe() if you're
17114 interested in properly working notification of new events and
17115 working timers.
17116 mp.register_idle(fn)
17118 Register an event loop idle handler. Idle handlers are called
17119 before the script goes to sleep after handling all new events.
17120 This can be used for example to delay processing of property
17121 change events: if you're observing multiple properties at once,
17122 you might not want to act on each property change, but only when
17123 all change notifications have been received.
17124 mp.unregister_idle(fn)
17126 Undo mp.register_idle(fn). This removes all idle handlers that
17127 are equal to the fn parameter. This uses normal Lua == compari‐
17128 son, so be careful when dealing with closures.
17129 mp.enable_messages(level)
17131 Set the minimum log level of which mpv message output to re‐
17132 ceive. These messages are normally printed to the terminal. By
17133 calling this function, you can set the minimum log level of mes‐
17134 sages which should be received with the log-message event. See
17135 the description of this event for details. The level is a
17136 string, see msg.log for allowed log levels.
17137 mp.register_script_message(name, fn)
17139 This is a helper to dispatch script-message or script-message-to
17140 invocations to Lua functions. fn is called if script-message or
17141 script-message-to (with this script as destination) is run with
17142 name as first parameter. The other parameters are passed to fn.
17143 If a message with the given name is already registered, it's
17144 overwritten.
17145 Used by mp.add_key_binding, so be careful about name collisions.
17147 mp.unregister_script_message(name)
17149 Undo a previous registration with mp.register_script_message.
17150 Does nothing if the name wasn't registered.
17151 mp.create_osd_overlay(format)
17153 Create an OSD overlay. This is a very thin wrapper around the
17154 osd-overlay command. The function returns a table, which mostly
17155 contains fields that will be passed to osd-overlay. The format
17156 parameter is used to initialize the format field. The data field
17157 contains the text to be used as overlay. For details, see the
17158 osd-overlay command.
17159 In addition, it provides the following methods:
17161 update()
17163 Commit the OSD overlay to the screen, or in other words,
17164 run the osd-overlay command with the current fields of
17165 the overlay table. Returns the result of the osd-overlay
17166 command itself.
17167 remove()
17169 Remove the overlay from the screen. A update() call will
17170 add it again.
17171 Example:
17173 ov = mp.create_osd_overlay("ass-events")
17175 ov.data = "{\\an5}{\\b1}hello world!"
17176 ov:update()
17177 The advantage of using this wrapper (as opposed to running
17179 osd-overlay directly) is that the id field is allocated automat‐
17180 ically.
17181 mp.get_osd_size()
17183 Returns a tuple of osd_width, osd_height, osd_par. The first two
17184 give the size of the OSD in pixels (for video outputs like
17185 --vo=xv, this may be "scaled" pixels). The third is the display
17186 pixel aspect ratio.
17187 May return invalid/nonsense values if OSD is not initialized
17189 yet.
17190 mp.msg functions
17192 This module allows outputting messages to the terminal, and can be
17193 loaded with require 'mp.msg'.
17194 msg.log(level, ...)
17196 The level parameter is the message priority. It's a string and
17197 one of fatal, error, warn, info, v, debug, trace. The user's
17198 settings will determine which of these messages will be visible.
17199 Normally, all messages are visible, except v, debug and trace.
17200 The parameters after that are all converted to strings. Spaces
17202 are inserted to separate multiple parameters.
17203 You don't need to add newlines.
17205 msg.fatal(...), msg.error(...), msg.warn(...), msg.info(...), msg.ver‐
17207 bose(...), msg.debug(...), msg.trace(...)
17208 All of these are shortcuts and equivalent to the corresponding
17209 msg.log(level, ...) call.
17210 mp.options functions
17212 mpv comes with a built-in module to manage options from config-files
17213 and the command-line. All you have to do is to supply a table with de‐
17214 fault options to the read_options function. The function will overwrite
17215 the default values with values found in the config-file and the com‐
17216 mand-line (in that order).
17217 options.read_options(table [, identifier [, on_update]])
17219 A table with key-value pairs. The type of the default values is
17220 important for converting the values read from the config file or
17221 command-line back. Do not use nil as a default value!
17222 The identifier is used to identify the config-file and the com‐
17224 mand-line options. These needs to unique to avoid collisions
17225 with other scripts. Defaults to mp.get_script_name() if the pa‐
17226 rameter is nil or missing.
17227 The on_update parameter enables run-time updates of all matching
17229 option values via the script-opts option/property. If any of the
17230 matching options changes, the values in the table (which was
17231 originally passed to the function) are changed, and on_up‐
17232 date(list) is called. list is a table where each updated option
17233 has a list[option_name] = true entry. There is no initial
17234 on_update() call. This never re-reads the config file.
17235 script-opts is always applied on the original config file, ig‐
17236 noring previous script-opts values (for example, if an option is
17237 removed from script-opts at runtime, the option will have the
17238 value in the config file). table entries are only written for
17239 option values whose values effectively change (this is important
17240 if the script changes table entries independently).
17241 Example implementation:
17243 require 'mp.options'
17245 local options = {
17246 optionA = "defaultvalueA",
17247 optionB = -0.5,
17248 optionC = true,
17249 }
17250 read_options(options, "myscript")
17251 print(options.optionA)
17252 The config file will be stored in script-opts/identifier.conf in mpv's
17254 user folder. Comment lines can be started with # and stray spaces are
17255 not removed. Boolean values will be represented with yes/no.
17256 Example config:
17258 # comment
17260 optionA=Hello World
17261 optionB=9999
17262 optionC=no
17263 Command-line options are read from the --script-opts parameter. To
17265 avoid collisions, all keys have to be prefixed with identifier-.
17266 Example command-line:
17268 --script-opts=myscript-optionA=TEST,myscript-optionB=0,myscript-optionC=yes
17270 mp.utils functions
17272 This built-in module provides generic helper functions for Lua, and
17273 have strictly speaking nothing to do with mpv or video/audio playback.
17274 They are provided for convenience. Most compensate for Lua's scarce
17275 standard library.
17276 Be warned that any of these functions might disappear any time. They
17278 are not strictly part of the guaranteed API.
17279 utils.getcwd()
17281 Returns the directory that mpv was launched from. On error, nil,
17282 error is returned.
17283 utils.readdir(path [, filter])
17285 Enumerate all entries at the given path on the filesystem, and
17286 return them as array. Each entry is a directory entry (without
17287 the path). The list is unsorted (in whatever order the operat‐
17288 ing system returns it).
17289 If the filter argument is given, it must be one of the following
17291 strings:
17292 files List regular files only. This excludes directories,
17294 special files (like UNIX device files or FIFOs), and
17295 dead symlinks. It includes UNIX symlinks to regular
17296 files.
17297 dirs List directories only, or symlinks to directories. .
17299 and .. are not included.
17300 normal Include the results of both files and dirs. (This is
17302 the default.)
17303 all List all entries, even device files, dead symlinks,
17305 FIFOs, and the . and .. entries.
17306 On error, nil, error is returned.
17308 utils.file_info(path)
17310 Stats the given path for information and returns a table with
17311 the following entries:
17312 mode protection bits (on Windows, always 755 (octal) for
17314 directories and 644 (octal) for files)
17315 size size in bytes
17317 atime time of last access
17319 mtime time of last modification
17321 ctime time of last metadata change
17323 is_file
17325 Whether path is a regular file (boolean)
17326 is_dir Whether path is a directory (boolean)
17328 mode and size are integers. Timestamps (atime, mtime and ctime)
17330 are integer seconds since the Unix epoch (Unix time). The bool‐
17331 eans is_file and is_dir are provided as a convenience; they can
17332 be and are derived from mode.
17333 On error (e.g. path does not exist), nil, error is returned.
17335 utils.split_path(path)
17337 Split a path into directory component and filename component,
17338 and return them. The first return value is always the directory.
17339 The second return value is the trailing part of the path, the
17340 directory entry.
17341 utils.join_path(p1, p2)
17343 Return the concatenation of the 2 paths. Tries to be clever. For
17344 example, if p2 is an absolute path, p2 is returned without
17345 change.
17346 utils.subprocess(t)
17348 Runs an external process and waits until it exits. Returns
17349 process status and the captured output. This is a legacy wrapper
17350 around calling the subprocess command with mp.command_native. It
17351 does the following things:
17352 • copy the table t
17354 • rename cancellable field to playback_only
17356 • rename max_size to capture_size
17358 • set capture_stdout field to true if unset
17360 • set name field to subprocess
17362 • call mp.command_native(copied_t)
17364 • if the command failed, create a dummy result table
17366 • copy error_string to error field if the string is non-empty
17368 • return the result table
17370 It is recommended to use mp.command_native or mp.command_na‐
17372 tive_async directly, instead of calling this legacy wrapper. It
17373 is for compatibility only.
17374 See the subprocess documentation for semantics and further pa‐
17376 rameters.
17377 utils.subprocess_detached(t)
17379 Runs an external process and detaches it from mpv's control.
17380 The parameter t is a table. The function reads the following en‐
17382 tries:
17383 args Array of strings of the same semantics as the args
17385 used in the subprocess function.
17386 The function returns nil.
17388 This is a legacy wrapper around calling the run command with
17390 mp.commandv and other functions.
17391 utils.getpid()
17393 Returns the process ID of the running mpv process. This can be
17394 used to identify the calling mpv when launching (detached) sub‐
17395 processes.
17396 utils.get_env_list()
17398 Returns the C environment as a list of strings. (Do not confuse
17399 this with the Lua "environment", which is an unrelated concept.)
17400 utils.parse_json(str [, trail])
17402 Parses the given string argument as JSON, and returns it as a
17403 Lua table. On error, returns nil, error. (Currently, error is
17404 just a string reading error, because there is no fine-grained
17405 error reporting of any kind.)
17406 The returned value uses similar conventions as mp.get_prop‐
17408 erty_native() to distinguish empty objects and arrays.
17409 If the trail parameter is true (or any value equal to true),
17411 then trailing non-whitespace text is tolerated by the function,
17412 and the trailing text is returned as 3rd return value. (The 3rd
17413 return value is always there, but with trail set, no error is
17414 raised.)
17415 utils.format_json(v)
17417 Format the given Lua table (or value) as a JSON string and re‐
17418 turn it. On error, returns nil, error. (Errors usually only hap‐
17419 pen on value types incompatible with JSON.)
17420 The argument value uses similar conventions as mp.set_prop‐
17422 erty_native() to distinguish empty objects and arrays.
17423 utils.to_string(v)
17425 Turn the given value into a string. Formats tables and their
17426 contents. This doesn't do anything special; it is only needed
17427 because Lua is terrible.
17428 Events
17430 Events are notifications from player core to scripts. You can register
17431 an event handler with mp.register_event.
17432 Note that all scripts (and other parts of the player) receive events
17434 equally, and there's no such thing as blocking other scripts from re‐
17435 ceiving events.
17436 Example:
17438 function my_fn(event)
17440 print("start of playback!")
17441 end
17442 mp.register_event("file-loaded", my_fn)
17444 For the existing event types, see List of events.
17446 Extras
17448 This documents experimental features, or features that are "too spe‐
17449 cial" to guarantee a stable interface.
17450 mp.add_hook(type, priority, fn)
17452 Add a hook callback for type (a string identifying a certain
17453 kind of hook). These hooks allow the player to call script func‐
17454 tions and wait for their result (normally, the Lua scripting in‐
17455 terface is asynchronous from the point of view of the player
17456 core). priority is an arbitrary integer that allows ordering
17457 among hooks of the same kind. Using the value 50 is recommended
17458 as neutral default value.
17459 fn(hook) is the function that will be called during execution of
17461 the hook. The parameter passed to it (hook) is a Lua object that
17462 can control further aspects about the currently invoked hook. It
17463 provides the following methods:
17464 defer()
17466 Returning from the hook function should not automati‐
17467 cally continue the hook. Instead, the API user wants
17468 to call hook:cont() on its own at a later point in
17469 time (before or after the function has returned).
17470 cont() Continue the hook. Doesn't need to be called unless
17472 defer() was called.
17473 See Hooks for currently existing hooks and what they do - only
17475 the hook list is interesting; handling hook execution is done by
17476 the Lua script function automatically.
17477
17479 JavaScript support in mpv is near identical to its Lua support. Use
17480 this section as reference on differences and availability of APIs, but
17481 otherwise you should refer to the Lua documentation for API details and
17482 general scripting in mpv.
17483 Example
17485 JavaScript code which leaves fullscreen mode when the player is paused:
17486 function on_pause_change(name, value) {
17488 if (value == true)
17489 mp.set_property("fullscreen", "no");
17490 }
17491 mp.observe_property("pause", "bool", on_pause_change);
17492 Similarities with Lua
17494 mpv tries to load a script file as JavaScript if it has a .js exten‐
17495 sion, but otherwise, the documented Lua options, script directories,
17496 loading, etc apply to JavaScript files too.
17497 Script initialization and lifecycle is the same as with Lua, and most
17499 of the Lua functions at the modules mp, mp.utils, mp.msg and mp.options
17500 are available to JavaScript with identical APIs - including running
17501 commands, getting/setting properties, registering events/key-bind‐
17502 ings/hooks, etc.
17503 Differences from Lua
17505 No need to load modules. mp, mp.utils, mp.msg and mp.options are pre‐
17506 loaded, and you can use e.g. var cwd = mp.utils.getcwd(); without prior
17507 setup.
17508 Errors are slightly different. Where the Lua APIs return nil for error,
17510 the JavaScript ones return undefined. Where Lua returns something, er‐
17511 ror JavaScript returns only something - and makes error available via
17512 mp.last_error(). Note that only some of the functions have this addi‐
17513 tional error value - typically the same ones which have it in Lua.
17514 Standard APIs are preferred. For instance setTimeout and JSON.stringify
17516 are available, but mp.add_timeout and mp.utils.format_json are not.
17517 No standard library. This means that interaction with anything outside
17519 of mpv is limited to the available APIs, typically via mp.utils. How‐
17520 ever, some file functions were added, and CommonJS require is available
17521 too - where the loaded modules have the same privileges as normal
17522 scripts.
17523 Language features - ECMAScript 5
17525 The scripting backend which mpv currently uses is MuJS - a compatible
17526 minimal ES5 interpreter. As such, String.substring is implemented for
17527 instance, while the common but non-standard String.substr is not.
17528 Please consult the MuJS pages on language features and platform support
17529 - https://mujs.com .
17530 Unsupported Lua APIs and their JS alternatives
17532 mp.add_timeout(seconds, fn) JS: id = setTimeout(fn, ms)
17533 mp.add_periodic_timer(seconds, fn) JS: id = setInterval(fn, ms)
17535 utils.parse_json(str [, trail]) JS: JSON.parse(str)
17537 utils.format_json(v) JS: JSON.stringify(v)
17539 utils.to_string(v) see dump below.
17541 mp.get_next_timeout() see event loop below.
17543 mp.dispatch_events([allow_wait]) see event loop below.
17545 Scripting APIs - identical to Lua
17547 (LE) - Last-Error, indicates that mp.last_error() can be used after the
17548 call to test for success (empty string) or failure (non empty reason
17549 string). Where the Lua APIs use nil to indicate error, JS APIs use un‐
17550 defined.
17551 mp.command(string) (LE)
17553 mp.commandv(arg1, arg2, ...) (LE)
17555 mp.command_native(table [,def]) (LE)
17557 id = mp.command_native_async(table [,fn]) (LE) Notes: id is true-thy on
17559 success, error is empty string on success.
17560 mp.abort_async_command(id)
17562 mp.del_property(name) (LE)
17564 mp.get_property(name [,def]) (LE)
17566 mp.get_property_osd(name [,def]) (LE)
17568 mp.get_property_bool(name [,def]) (LE)
17570 mp.get_property_number(name [,def]) (LE)
17572 mp.get_property_native(name [,def]) (LE)
17574 mp.set_property(name, value) (LE)
17576 mp.set_property_bool(name, value) (LE)
17578 mp.set_property_number(name, value) (LE)
17580 mp.set_property_native(name, value) (LE)
17582 mp.get_time()
17584 mp.add_key_binding(key, name|fn [,fn [,flags]])
17586 mp.add_forced_key_binding(...)
17588 mp.remove_key_binding(name)
17590 mp.register_event(name, fn)
17592 mp.unregister_event(fn)
17594 mp.observe_property(name, type, fn)
17596 mp.unobserve_property(fn)
17598 mp.get_opt(key)
17600 mp.get_script_name()
17602 mp.get_script_directory()
17604 mp.osd_message(text [,duration])
17606 mp.get_wakeup_pipe()
17608 mp.register_idle(fn)
17610 mp.unregister_idle(fn)
17612 mp.enable_messages(level)
17614 mp.register_script_message(name, fn)
17616 mp.unregister_script_message(name)
17618 mp.create_osd_overlay(format)
17620 mp.get_osd_size() (returned object has properties: width, height, as‐
17622 pect)
17623 mp.msg.log(level, ...)
17625 mp.msg.fatal(...)
17627 mp.msg.error(...)
17629 mp.msg.warn(...)
17631 mp.msg.info(...)
17633 mp.msg.verbose(...)
17635 mp.msg.debug(...)
17637 mp.msg.trace(...)
17639 mp.utils.getcwd() (LE)
17641 mp.utils.readdir(path [, filter]) (LE)
17643 mp.utils.file_info(path) (LE) Note: like lua - this does NOT expand
17645 meta-paths like ~~/foo (other JS file functions do expand meta paths).
17646 mp.utils.split_path(path)
17648 mp.utils.join_path(p1, p2)
17650 mp.utils.subprocess(t)
17652 mp.utils.subprocess_detached(t)
17654 mp.utils.get_env_list()
17656 mp.utils.getpid() (LE)
17658 mp.add_hook(type, priority, fn(hook))
17660 mp.options.read_options(obj [, identifier [, on_update]]) (types:
17662 string/boolean/number)
17663 Additional utilities
17665 mp.last_error()
17666 If used after an API call which updates last error, returns an
17667 empty string if the API call succeeded, or a non-empty error
17668 reason string otherwise.
17669 Error.stack (string)
17671 When using try { ... } catch(e) { ... }, then e.stack is the
17672 stack trace of the error - if it was created using the Er‐
17673 ror(...) constructor.
17674 print (global)
17676 A convenient alias to mp.msg.info.
17677 dump (global)
17679 Like print but also expands objects and arrays recursively.
17680 mp.utils.getenv(name)
17682 Returns the value of the host environment variable name, or un‐
17683 defined if the variable is not defined.
17684 mp.utils.get_user_path(path)
17686 Trivial wrapper of the expand-path mpv command, returns a
17687 string. read_file, write_file, append_file and require already
17688 expand the path internally and accept mpv meta-paths like
17689 ~~desktop/foo.
17690 mp.utils.read_file(fname [,max])
17692 Returns the content of file fname as string. If max is provided
17693 and not negative, limit the read to max bytes.
17694 mp.utils.write_file(fname, str)
17696 (Over)write file fname with text content str. fname must be pre‐
17697 fixed with file:// as simple protection against accidental argu‐
17698 ments switch, e.g. mp.utils.write_file("file://~/abc.txt",
17699 "hello world").
17700 mp.utils.append_file(fname, str)
17702 Same as mp.utils.write_file if the file fname does not exist. If
17703 it does exist then append instead of overwrite.
17704 Note: read_file, write_file and append_file throw on errors, allow text
17706 content only.
17707 mp.get_time_ms()
17709 Same as mp.get_time() but in ms instead of seconds.
17710 mp.get_script_file()
17712 Returns the file name of the current script.
17713 exit() (global)
17715 Make the script exit at the end of the current event loop itera‐
17716 tion. Note: please remove added key bindings before calling
17717 exit().
17718 mp.utils.compile_js(fname, content_str)
17720 Compiles the JS code content_str as file name fname (without
17721 loading anything from the filesystem), and returns it as a func‐
17722 tion. Very similar to a Function constructor, but shows at stack
17723 traces as fname.
17724 mp.module_paths
17726 Global modules search paths array for the require function (see
17727 below).
17728 Timers (global)
17730 The standard HTML/node.js timers are available:
17731 id = setTimeout(fn [,duration [,arg1 [,arg2...]]])
17733 id = setTimeout(code_string [,duration])
17735 clearTimeout(id)
17737 id = setInterval(fn [,duration [,arg1 [,arg2...]]])
17739 id = setInterval(code_string [,duration])
17741 clearInterval(id)
17743 setTimeout and setInterval return id, and later call fn (or execute
17745 code_string) after duration ms. Interval also repeat every duration.
17746 duration has a minimum and default value of 0, code_string is a plain
17748 string which is evaluated as JS code, and [,arg1 [,arg2..]] are used as
17749 arguments (if provided) when calling back fn.
17750 The clear...(id) functions cancel timer id, and are irreversible.
17752 Note: timers always call back asynchronously, e.g. setTimeout(fn) will
17754 never call fn before returning. fn will be called either at the end of
17755 this event loop iteration or at a later event loop iteration. This is
17756 true also for intervals - which also never call back twice at the same
17757 event loop iteration.
17758 Additionally, timers are processed after the event queue is empty, so
17760 it's valid to use setTimeout(fn) as a one-time idle observer.
17761 CommonJS modules and require(id)
17763 CommonJS Modules are a standard system where scripts can export common
17764 functions for use by other scripts. Specifically, a module is a script
17765 which adds properties (functions, etc) to its pre-existing exports ob‐
17766 ject, which another script can access with require(module-id). This
17767 runs the module and returns its exports object. Further calls to re‐
17768 quire for the same module will return its cached exports object without
17769 running the module again.
17770 Modules and require are supported, standard compliant, and generally
17772 similar to node.js. However, most node.js modules won't run due to
17773 missing modules such as fs, process, etc, but some node.js modules with
17774 minimal dependencies do work. In general, this is for mpv modules and
17775 not a node.js replacement.
17776 A .js file extension is always added to id, e.g. require("./foo") will
17778 load the file ./foo.js and return its exports object.
17779 An id which starts with ./ or ../ is relative to the script or module
17781 which require it. Otherwise it's considered a top-level id (CommonJS
17782 term).
17783 Top-level id is evaluated as absolute filesystem path if possible, e.g.
17785 /x/y or ~/x. Otherwise it's considered a global module id and searched
17786 according to mp.module_paths in normal array order, e.g. require("x")
17787 tries to load x.js at one of the array paths, and id foo/x tries to
17788 load x.js inside dir foo at one of the paths.
17789 The mp.module_paths array is empty by default except for scripts which
17791 are loaded as a directory where it contains one item - <directory>/mod‐
17792 ules/ . The array may be updated from a script (or using custom init -
17793 see below) which will affect future calls to require for global module
17794 id's which are not already loaded/cached.
17795 No global variable, but a module's this at its top lexical scope is the
17797 global object - also in strict mode. If you have a module which needs
17798 global as the global object, you could do this.global = this; before
17799 require.
17800 Functions and variables declared at a module don't pollute the global
17802 object.
17803 Custom initialization
17805 After mpv initializes the JavaScript environment for a script but be‐
17806 fore it loads the script - it tries to run the file init.js at the root
17807 of the mpv configuration directory. Code at this file can update the
17808 environment further for all scripts. E.g. if it contains mp.mod‐
17809 ule_paths.push("/foo") then require at all scripts will search global
17810 module id's also at /foo (do NOT do mp.module_paths = ["/foo"]; because
17811 this will remove existing paths - like <script-dir>/modules for scripts
17812 which load from a directory).
17813 The custom-init file is ignored if mpv is invoked with --no-config.
17815 Before mpv 0.34, the file name was .init.js (with dot) at the same dir.
17817 The event loop
17819 The event loop poll/dispatch mpv events as long as the queue is not
17820 empty, then processes the timers, then waits for the next event, and
17821 repeats this forever.
17822 You could put this code at your script to replace the built-in event
17824 loop, and also print every event which mpv sends to your script:
17825 function mp_event_loop() {
17827 var wait = 0;
17828 do {
17829 var e = mp.wait_event(wait);
17830 dump(e); // there could be a lot of prints...
17831 if (e.event != "none") {
17832 mp.dispatch_event(e);
17833 wait = 0;
17834 } else {
17835 wait = mp.process_timers() / 1000;
17836 if (wait != 0) {
17837 mp.notify_idle_observers();
17838 wait = mp.peek_timers_wait() / 1000;
17839 }
17840 }
17841 } while (mp.keep_running);
17842 }
17843 mp_event_loop is a name which mpv tries to call after the script loads.
17845 The internal implementation is similar to this (without dump though..).
17846 e = mp.wait_event(wait) returns when the next mpv event arrives, or af‐
17848 ter wait seconds if positive and no mpv events arrived. wait value of 0
17849 returns immediately (with e.event == "none" if the queue is empty).
17850 mp.dispatch_event(e) calls back the handlers registered for e.event, if
17852 there are such (event handlers, property observers, script messages,
17853 etc).
17854 mp.process_timers() calls back the already-added, non-canceled due
17856 timers, and returns the duration in ms till the next due timer (possi‐
17857 bly 0), or -1 if there are no pending timers. Must not be called recur‐
17858 sively.
17859 mp.notify_idle_observers() calls back the idle observers, which we do
17861 when we're about to sleep (wait != 0), but the observers may add timers
17862 or take non-negligible duration to complete, so we re-calculate wait
17863 afterwards.
17864 mp.peek_timers_wait() returns the same values as mp.process_timers()
17866 but without doing anything. Invalid result if called from a timer call‐
17867 back.
17868 Note: exit() is also registered for the shutdown event, and its imple‐
17870 mentation is a simple mp.keep_running = false.
17871
17873 mpv can be controlled by external programs using the JSON-based IPC
17874 protocol. It can be enabled by specifying the path to a unix socket or
17875 a named pipe using the option --input-ipc-server. Clients can connect
17876 to this socket and send commands to the player or receive events from
17877 it.
17878 WARNING:
17880 This is not intended to be a secure network protocol. It is explic‐
17881 itly insecure: there is no authentication, no encryption, and the
17882 commands themselves are insecure too. For example, the run command
17883 is exposed, which can run arbitrary system commands. The use-case is
17884 controlling the player locally. This is not different from the
17885 MPlayer slave protocol.
17886 Socat example
17888 You can use the socat tool to send commands (and receive replies) from
17889 the shell. Assuming mpv was started with:
17890 mpv file.mkv --input-ipc-server=/tmp/mpvsocket
17892 Then you can control it using socat:
17894 > echo '{ "command": ["get_property", "playback-time"] }' | socat - /tmp/mpvsocket
17896 {"data":190.482000,"error":"success"}
17897 In this case, socat copies data between stdin/stdout and the mpv socket
17899 connection.
17900 See the --idle option how to make mpv start without exiting immediately
17902 or playing a file.
17903 It's also possible to send input.conf style text-only commands:
17905 > echo 'show-text ${playback-time}' | socat - /tmp/mpvsocket
17907 But you won't get a reply over the socket. (This particular command
17909 shows the playback time on the player's OSD.)
17910 Command Prompt example
17912 Unfortunately, it's not as easy to test the IPC protocol on Windows,
17913 since Windows ports of socat (in Cygwin and MSYS2) don't understand
17914 named pipes. In the absence of a simple tool to send and receive from
17915 bidirectional pipes, the echo command can be used to send commands, but
17916 not receive replies from the command prompt.
17917 Assuming mpv was started with:
17919 mpv file.mkv --input-ipc-server=\\.\pipe\mpvsocket
17921 You can send commands from a command prompt:
17923 echo show-text ${playback-time} >\\.\pipe\mpvsocket
17925 To be able to simultaneously read and write from the IPC pipe, like on
17927 Linux, it's necessary to write an external program that uses overlapped
17928 file I/O (or some wrapper like .NET's NamedPipeClientStream.)
17929 You can open the pipe in PuTTY as "serial" device. This is not very
17931 comfortable, but gives a way to test interactively without having to
17932 write code.
17933 Protocol
17935 The protocol uses UTF-8-only JSON as defined by RFC-8259. Unlike stan‐
17936 dard JSON, "u" escape sequences are not allowed to construct surrogate
17937 pairs. To avoid getting conflicts, encode all text characters including
17938 and above codepoint U+0020 as UTF-8. mpv might output broken UTF-8 in
17939 corner cases (see "UTF-8" section below).
17940 Clients can execute commands on the player by sending JSON messages of
17942 the following form:
17943 { "command": ["command_name", "param1", "param2", ...] }
17945 where command_name is the name of the command to be executed, followed
17947 by a list of parameters. Parameters must be formatted as native JSON
17948 values (integers, strings, booleans, ...). Every message must be termi‐
17949 nated with \n. Additionally, \n must not appear anywhere inside the
17950 message. In practice this means that messages should be minified before
17951 being sent to mpv.
17952 mpv will then send back a reply indicating whether the command was run
17954 correctly, and an additional field holding the command-specific return
17955 data (it can also be null).
17956 { "error": "success", "data": null }
17958 mpv will also send events to clients with JSON messages of the follow‐
17960 ing form:
17961 { "event": "event_name" }
17963 where event_name is the name of the event. Additional event-specific
17965 fields can also be present. See List of events for a list of all sup‐
17966 ported events.
17967 Because events can occur at any time, it may be difficult at times to
17969 determine which response goes with which command. Commands may option‐
17970 ally include a request_id which, if provided in the command request,
17971 will be copied verbatim into the response. mpv does not interpret the
17972 request_id in any way; it is solely for the use of the requester. The
17973 only requirement is that the request_id field must be an integer (a
17974 number without fractional parts in the range -2^63..2^63-1). Using
17975 other types is deprecated and will currently show a warning. In the fu‐
17976 ture, this will raise an error.
17977 For example, this request:
17979 { "command": ["get_property", "time-pos"], "request_id": 100 }
17981 Would generate this response:
17983 { "error": "success", "data": 1.468135, "request_id": 100 }
17985 If you don't specify a request_id, command replies will set it to 0.
17987 All commands, replies, and events are separated from each other with a
17989 line break character (\n).
17990 If the first character (after skipping whitespace) is not {, the com‐
17992 mand will be interpreted as non-JSON text command, as they are used in
17993 input.conf (or mpv_command_string() in the client API). Additionally,
17994 lines starting with # and empty lines are ignored.
17995 Currently, embedded 0 bytes terminate the current line, but you should
17997 not rely on this.
17998 Data flow
18000 Currently, the mpv-side IPC implementation does not service the socket
18001 while a command is executed and the reply is written. It is for example
18002 not possible that other events, that happened during the execution of
18003 the command, are written to the socket before the reply is written.
18004 This might change in the future. The only guarantee is that replies to
18006 IPC messages are sent in sequence.
18007 Also, since socket I/O is inherently asynchronous, it is possible that
18009 you read unrelated event messages from the socket, before you read the
18010 reply to the previous command you sent. In this case, these events were
18011 queued by the mpv side before it read and started processing your com‐
18012 mand message.
18013 If the mpv-side IPC implementation switches away from blocking writes
18015 and blocking command execution, it may attempt to send events at any
18016 time.
18017 You can also use asynchronous commands, which can return in any order,
18019 and which do not block IPC protocol interaction at all while the com‐
18020 mand is executed in the background.
18021 Asynchronous commands
18023 Command can be run asynchronously. This behaves exactly as with normal
18024 command execution, except that execution is not blocking. Other com‐
18025 mands can be sent while it's executing, and command completion can be
18026 arbitrarily reordered.
18027 The async field controls this. If present, it must be a boolean. If
18029 missing, false is assumed.
18030 For example, this initiates an asynchronous command:
18032 { "command": ["screenshot"], "request_id": 123, "async": true }
18034 And this is the completion:
18036 {"request_id":123,"error":"success","data":null}
18038 By design, you will not get a confirmation that the command was
18040 started. If a command is long running, sending the message will not
18041 lead to any reply until much later when the command finishes.
18042 Some commands execute synchronously, but these will behave like asyn‐
18044 chronous commands that finished execution immediately.
18045 Cancellation of asynchronous commands is available in the libmpv API,
18047 but has not yet been implemented in the IPC protocol.
18048 Commands with named arguments
18050 If the command field is a JSON object, named arguments are expected.
18051 This is described in the C API mpv_command_node() documentation (the
18052 MPV_FORMAT_NODE_MAP case). In some cases, this may make commands more
18053 readable, while some obscure commands basically require using named ar‐
18054 guments.
18055 Currently, only "proper" commands (as listed by List of Input Commands)
18057 support named arguments.
18058 Commands
18060 In addition to the commands described in List of Input Commands, a few
18061 extra commands can also be used as part of the protocol:
18062 client_name
18064 Return the name of the client as string. This is the string
18065 ipc-N with N being an integer number.
18066 get_time_us
18068 Return the current mpv internal time in microseconds as a num‐
18069 ber. This is basically the system time, with an arbitrary off‐
18070 set.
18071 get_property
18073 Return the value of the given property. The value will be sent
18074 in the data field of the replay message.
18075 Example:
18077 { "command": ["get_property", "volume"] }
18079 { "data": 50.0, "error": "success" }
18080 get_property_string
18082 Like get_property, but the resulting data will always be a
18083 string.
18084 Example:
18086 { "command": ["get_property_string", "volume"] }
18088 { "data": "50.000000", "error": "success" }
18089 set_property
18091 Set the given property to the given value. See Properties for
18092 more information about properties.
18093 Example:
18095 { "command": ["set_property", "pause", true] }
18097 { "error": "success" }
18098 set_property_string
18100 Alias for set_property. Both commands accept native values and
18101 strings.
18102 observe_property
18104 Watch a property for changes. If the given property is changed,
18105 then an event of type property-change will be generated
18106 Example:
18108 { "command": ["observe_property", 1, "volume"] }
18110 { "error": "success" }
18111 { "event": "property-change", "id": 1, "data": 52.0, "name": "volume" }
18112 WARNING:
18114 If the connection is closed, the IPC client is destroyed in‐
18115 ternally, and the observed properties are unregistered. This
18116 happens for example when sending commands to a socket with
18117 separate socat invocations. This can make it seem like prop‐
18118 erty observation does not work. You must keep the IPC connec‐
18119 tion open to make it work.
18120 observe_property_string
18122 Like observe_property, but the resulting data will always be a
18123 string.
18124 Example:
18126 { "command": ["observe_property_string", 1, "volume"] }
18128 { "error": "success" }
18129 { "event": "property-change", "id": 1, "data": "52.000000", "name": "volume" }
18130 unobserve_property
18132 Undo observe_property or observe_property_string. This requires
18133 the numeric id passed to the observed command as argument.
18134 Example:
18136 { "command": ["unobserve_property", 1] }
18138 { "error": "success" }
18139 request_log_messages
18141 Enable output of mpv log messages. They will be received as
18142 events. The parameter to this command is the log-level (see
18143 mpv_request_log_messages C API function).
18144 Log message output is meant for humans only (mostly for debug‐
18146 ging). Attempting to retrieve information by parsing these mes‐
18147 sages will just lead to breakages with future mpv releases. In‐
18148 stead, make a feature request, and ask for a proper event that
18149 returns the information you need.
18150 enable_event, disable_event
18152 Enables or disables the named event. Mirrors the mpv_re‐
18153 quest_event C API function. If the string all is used instead of
18154 an event name, all events are enabled or disabled.
18155 By default, most events are enabled, and there is not much use
18157 for this command.
18158 get_version
18160 Returns the client API version the C API of the remote mpv in‐
18161 stance provides.
18162 See also: DOCS/client-api-changes.rst.
18164 UTF-8
18166 Normally, all strings are in UTF-8. Sometimes it can happen that
18167 strings are in some broken encoding (often happens with file tags and
18168 such, and filenames on many Unixes are not required to be in UTF-8 ei‐
18169 ther). This means that mpv sometimes sends invalid JSON. If that is a
18170 problem for the client application's parser, it should filter the raw
18171 data for invalid UTF-8 sequences and perform the desired replacement,
18172 before feeding the data to its JSON parser.
18173 mpv will not attempt to construct invalid UTF-8 with broken "u" escape
18175 sequences. This includes surrogate pairs.
18176 JSON extensions
18178 The following non-standard extensions are supported:
18179 • a list or object item can have a trailing ","
18181 • object syntax accepts "=" in addition of ":"
18183 • object keys can be unquoted, if they start with a character in
18185 "A-Za-z_" and contain only characters in "A-Za-z0-9_"
18186 • byte escapes with "xAB" are allowed (with AB being a 2 digit hex
18188 number)
18189 Example:
18191 { objkey = "value\x0A" }
18193 Is equivalent to:
18195 { "objkey": "value\n" }
18197 Alternative ways of starting clients
18199 You can create an anonymous IPC connection without having to set --in‐
18200 put-ipc-server. This is achieved through a mpv pseudo scripting backend
18201 that starts processes.
18202 You can put .run file extension in the mpv scripts directory in its
18204 config directory (see the FILES section for details), or load them
18205 through other means (see Script location). These scripts are simply ex‐
18206 ecuted with the OS native mechanism (as if you ran them in the shell).
18207 They must have a proper shebang and have the executable bit set.
18208 When executed, a socket (the IPC connection) is passed to them through
18210 file descriptor inheritance. The file descriptor is indicated as the
18211 special command line argument --mpv-ipc-fd=N, where N is the numeric
18212 file descriptor.
18213 The rest is the same as with a normal --input-ipc-server IPC connec‐
18215 tion. mpv does not attempt to observe or other interact with the
18216 started script process.
18217 This does not work in Windows yet.
18219
18221 There is no real changelog, but you can look at the following things:
18222 • The release changelog, which should contain most user-visible
18224 changes, including new features and bug fixes:
18225 https://github.com/mpv-player/mpv/releases
18227 • The git log, which is the "real" changelog
18229 • The file
18231 https://github.com/mpv-player/mpv/blob/master/DOCS/interface-changes.rst
18232 documents changes to the command and user interface, such as options
18233 and properties. (It usually documents breaking changes only, addi‐
18234 tions and enhancements are often not listed.)
18235 • C API changes are listed in
18237 https://github.com/mpv-player/mpv/blob/master/DOCS/client-api-changes.rst
18238 • The file mplayer-changes.rst in the DOCS sub directory on the git
18240 repository, which used to be in place of this section. It documents
18241 some changes that happened since mplayer2 forked off MPlayer. (Not
18242 updated anymore.)
18243
18245 mpv can be embedded into other programs as video/audio playback back‐
18246 end. The recommended way to do so is using libmpv. See libmpv/client.h
18247 in the mpv source code repository. This provides a C API. Bindings for
18248 other languages might be available (see wiki).
18249 Since libmpv merely allows access to underlying mechanisms that can
18251 control mpv, further documentation is spread over a few places:
18252 • https://github.com/mpv-player/mpv/blob/master/libmpv/client.h
18254 • https://mpv.io/manual/master/#options
18256 • https://mpv.io/manual/master/#list-of-input-commands
18258 • https://mpv.io/manual/master/#properties
18260 • https://github.com/mpv-player/mpv-examples/tree/master/libmpv
18262
18264 You can write C plugins for mpv. These use the libmpv API, although
18265 they do not use the libmpv library itself.
18266 They are available on Linux/BSD platforms only and enabled by default
18268 if the compiler supports linking with the -rdynamic flag.
18269 C plugins location
18271 C plugins are put into the mpv scripts directory in its config direc‐
18272 tory (see the FILES section for details). They must have a .so file ex‐
18273 tension. They can also be explicitly loaded with the --script option.
18274 API
18276 A C plugin must export the following function:
18277 int mpv_open_cplugin(mpv_handle *handle)
18279 The plugin function will be called on loading time. This function does
18281 not return as long as your plugin is loaded (it runs in its own
18282 thread). The handle will be deallocated as soon as the plugin function
18283 returns.
18284 The return value is interpreted as error status. A value of 0 is inter‐
18286 preted as success, while -1 signals an error. In the latter case, the
18287 player prints an uninformative error message that loading failed.
18288 Return values other than 0 and -1 are reserved, and trigger undefined
18290 behavior.
18291 Within the plugin function, you can call libmpv API functions. The han‐
18293 dle is created by mpv_create_client() (or actually an internal equiva‐
18294 lent), and belongs to you. You can call mpv_wait_event() to wait for
18295 things happening, and so on.
18296 Note that the player might block until your plugin calls
18298 mpv_wait_event() for the first time. This gives you a chance to install
18299 initial hooks etc. before playback begins.
18300 The details are quite similar to Lua scripts.
18302 Linkage to libmpv
18304 The current implementation requires that your plugins are not linked
18305 against libmpv. What your plugins use are not symbols from a libmpv bi‐
18306 nary, but symbols from the mpv host binary.
18307 Examples
18309 See:
18310 • https://github.com/mpv-player/mpv-examples/tree/master/cplugins
18312
18314 There are a number of environment variables that can be used to control
18315 the behavior of mpv.
18316 HOME, XDG_CONFIG_HOME
18318 Used to determine mpv config directory. If XDG_CONFIG_HOME is
18319 not set, $HOME/.config/mpv is used.
18320 $HOME/.mpv is always added to the list of config search paths
18322 with a lower priority.
18323 MPV_HOME
18325 Directory where mpv looks for user settings. Overrides HOME, and
18326 mpv will try to load the config file as $MPV_HOME/mpv.conf.
18327 MPV_VERBOSE (see also -v and --msg-level)
18329 Set the initial verbosity level across all message modules (de‐
18330 fault: 0). This is an integer, and the resulting verbosity cor‐
18331 responds to the number of --v options passed to the command
18332 line.
18333 MPV_LEAK_REPORT
18335 If set to 1, enable internal talloc leak reporting. If set to
18336 another value, disable leak reporting. If unset, use the de‐
18337 fault, which normally is 0. If mpv was built with --en‐
18338 able-ta-leak-report, the default is 1. If leak reporting was
18339 disabled at compile time (NDEBUG in custom CFLAGS), this envi‐
18340 ronment variable is ignored.
18341 LADSPA_PATH
18343 Specifies the search path for LADSPA plugins. If it is unset,
18344 fully qualified path names must be used.
18345 DISPLAY
18347 Standard X11 display name to use.
18348 FFmpeg/Libav:
18350 This library accesses various environment variables. However,
18351 they are not centrally documented, and documenting them is not
18352 our job. Therefore, this list is incomplete.
18353 Notable environment variables:
18355 http_proxy
18357 URL to proxy for http:// and https:// URLs.
18358 no_proxy
18360 List of domain patterns for which no proxy should be
18361 used. List entries are separated by ,. Patterns can in‐
18362 clude *.
18363 libdvdcss:
18365 DVDCSS_CACHE
18367 Specify a directory in which to store title key values.
18368 This will speed up descrambling of DVDs which are in the
18369 cache. The DVDCSS_CACHE directory is created if it does
18370 not exist, and a subdirectory is created named after the
18371 DVD's title or manufacturing date. If DVDCSS_CACHE is not
18372 set or is empty, libdvdcss will use the default value
18373 which is ${HOME}/.dvdcss/ under Unix and the roaming ap‐
18374 plication data directory (%APPDATA%) under Windows. The
18375 special value "off" disables caching.
18376 DVDCSS_METHOD
18378 Sets the authentication and decryption method that libd‐
18379 vdcss will use to read scrambled discs. Can be one of ti‐
18380 tle, key or disc.
18381 key is the default method. libdvdcss will use a set of
18383 calculated player keys to try to get the disc key.
18384 This can fail if the drive does not recognize any
18385 of the player keys.
18386 disc is a fallback method when key has failed. Instead
18388 of using player keys, libdvdcss will crack the
18389 disc key using a brute force algorithm. This
18390 process is CPU intensive and requires 64 MB of
18391 memory to store temporary data.
18392 title is the fallback when all other methods have
18394 failed. It does not rely on a key exchange with
18395 the DVD drive, but rather uses a crypto attack to
18396 guess the title key. On rare cases this may fail
18397 because there is not enough encrypted data on the
18398 disc to perform a statistical attack, but on the
18399 other hand it is the only way to decrypt a DVD
18400 stored on a hard disc, or a DVD with the wrong re‐
18401 gion on an RPC2 drive.
18402 DVDCSS_RAW_DEVICE
18404 Specify the raw device to use. Exact usage will depend on
18405 your operating system, the Linux utility to set up raw
18406 devices is raw(8) for instance. Please note that on most
18407 operating systems, using a raw device requires highly
18408 aligned buffers: Linux requires a 2048 bytes alignment
18409 (which is the size of a DVD sector).
18410 DVDCSS_VERBOSE
18412 Sets the libdvdcss verbosity level.
18413 0 Outputs no messages at all.
18415 1 Outputs error messages to stderr.
18417 2 Outputs error messages and debug messages to
18419 stderr.
18420 DVDREAD_NOKEYS
18422 Skip retrieving all keys on startup. Currently disabled.
18423 HOME FIXME: Document this.
18425
18427 Normally mpv returns 0 as exit code after finishing playback success‐
18428 fully. If errors happen, the following exit codes can be returned:
18429 1 Error initializing mpv. This is also returned if unknown op‐
18431 tions are passed to mpv.
18432 2 The file passed to mpv couldn't be played. This is somewhat
18434 fuzzy: currently, playback of a file is considered to be suc‐
18435 cessful if initialization was mostly successful, even if
18436 playback fails immediately after initialization.
18437 3 There were some files that could be played, and some files
18439 which couldn't (using the definition of success from above).
18440 4 Quit due to a signal, Ctrl+c in a VO window (by default), or
18442 from the default quit key bindings in encoding mode.
18443 Note that quitting the player manually will always lead to exit code 0,
18445 overriding the exit code that would be returned normally. Also, the
18446 quit input command can take an exit code: in this case, that exit code
18447 is returned.
18448
18450 Note that this section assumes Linux/BSD. On other platforms the paths
18451 may be different. For Windows-specifics, see FILES ON WINDOWS section.
18452 /usr/local/etc/mpv/mpv.conf
18454 mpv system-wide settings (depends on --prefix passed to config‐
18455 ure - mpv in default configuration will use /usr/local/etc/mpv/
18456 as config directory, while most Linux distributions will set it
18457 to /etc/mpv/).
18458 ~/.cache/mpv
18460 The standard cache directory. Certain options within mpv may
18461 cause it to write cache files to disk. This can be overridden by
18462 environment variables, in ascending order:
18463 1 If $XDG_CACHE_HOME is set, then the derived cache direc‐
18465 tory will be $XDG_CACHE_HOME/mpv.
18466 2 If $MPV_HOME is set, then the derived cache directory
18468 will be $MPV_HOME.
18469 If the directory does not exist, mpv will try to create it auto‐
18471 matically.
18472 ~/.config/mpv
18474 The standard configuration directory. This can be overridden by
18475 environment variables, in ascending order:
18476 1 If $XDG_CONFIG_HOME is set, then the derived configura‐
18478 tion directory will be $XDG_CONFIG_HOME/mpv.
18479 2 If $MPV_HOME is set, then the derived configuration di‐
18481 rectory will be $MPV_HOME.
18482 If this directory, nor the original configuration directory (see
18484 below) do not exist, mpv tries to create this directory automat‐
18485 ically.
18486 ~/.mpv/
18488 The original (pre 0.5.0) configuration directory. It will con‐
18489 tinue to be read if present. If this directory is present and
18490 the standard configuration directory is not present, then cache
18491 files and watch later config files will also be written to this
18492 directory.
18493 If both this directory and the standard configuration directory
18495 are present, configuration will be read from both with the stan‐
18496 dard configuration directory content taking precedence. However,
18497 you should fully migrate to the standard directory and a warning
18498 will be shown in this situation.
18499 ~/.config/mpv/mpv.conf
18501 mpv user settings (see CONFIGURATION FILES section)
18502 ~/.config/mpv/input.conf
18504 key bindings (see INPUT.CONF section)
18505 ~/.config/mpv/fonts.conf
18507 Fontconfig fonts.conf that is customized for mpv. You should in‐
18508 clude system fonts.conf in this file or mpv would not know about
18509 fonts that you already have in the system.
18510 Only available when libass is built with fontconfig.
18512 ~/.config/mpv/subfont.ttf
18514 fallback subtitle font
18515 ~/.config/mpv/fonts/
18517 Default location for --sub-fonts-dir (see Subtitles) and
18518 --osd-fonts-dir (see OSD).
18519 ~/.config/mpv/scripts/
18521 All files in this directory are loaded as if they were passed to
18522 the --script option. They are loaded in alphabetical order.
18523 The --load-scripts=no option disables loading these files.
18525 See Script location for details.
18527 ~/.local/state/mpv/watch_later/
18529 Contains temporary config files needed for resuming playback of
18530 files with the watch later feature. See for example the Q key
18531 binding, or the quit-watch-later input command.
18532 This can be overridden by environment variables, in ascending
18534 order:
18535 1 If $XDG_STATE_HOME is set, then the derived watch later
18537 directory will be $XDG_STATE_HOME/mpv/watch_later.
18538 2 If $MPV_HOME is set, then the derived watch later direc‐
18540 tory will be $MPV_HOME/watch_later.
18541 Each file is a small config file which is loaded if the corre‐
18543 sponding media file is loaded. It contains the playback position
18544 and some (not necessarily all) settings that were changed during
18545 playback. The filenames are hashed from the full paths of the
18546 media files. It's in general not possible to extract the media
18547 filename from this hash. However, you can set the --write-file‐
18548 name-in-watch-later-config option, and the player will add the
18549 media filename to the contents of the resume config file.
18550 ~/.config/mpv/script-opts/osc.conf
18552 This is loaded by the OSC script. See the ON SCREEN CONTROLLER
18553 docs for details.
18554 Other files in this directory are specific to the corresponding
18556 scripts as well, and the mpv core doesn't touch them.
18557
18559 On win32 (if compiled with MinGW, but not Cygwin), the default config
18560 file locations are different. They are generally located under %APP‐
18561 DATA%/mpv/. For example, the path to mpv.conf is %APP‐
18562 DATA%/mpv/mpv.conf, which maps to a system and user-specific path, for
18563 example
18564 C:\users\USERNAME\AppData\Roaming\mpv\mpv.conf
18565 You can find the exact path by running echo %APPDATA%\mpv\mpv.conf in
18567 cmd.exe.
18568 Other config files (such as input.conf) are in the same directory. See
18570 the FILES section above.
18571 The cache directory is located at %LOCALAPPDATA%/mpv.
18573 The environment variable $MPV_HOME completely overrides these, like on
18575 UNIX.
18576 If a directory named portable_config next to the mpv.exe exists, all
18578 config will be loaded from this directory only. Watch later config
18579 files and cache files are written to this directory as well. (This ex‐
18580 ists on Windows only and is redundant with $MPV_HOME. However, since
18581 Windows is very scripting unfriendly, a wrapper script just setting
18582 $MPV_HOME, like you could do it on other systems, won't work. porta‐
18583 ble_config is provided for convenience to get around this restriction.)
18584 Config files located in the same directory as mpv.exe are loaded with
18586 lower priority. Some config files are loaded only once, which means
18587 that e.g. of 2 input.conf files located in two config directories, only
18588 the one from the directory with higher priority will be loaded.
18589 A third config directory with the lowest priority is the directory
18591 named mpv in the same directory as mpv.exe. This used to be the direc‐
18592 tory with the highest priority, but is now discouraged to use and might
18593 be removed in the future.
18594 Note that mpv likes to mix / and \ path separators for simplicity.
18596 kernel32.dll accepts this, but cmd.exe does not.
18597
18599 On macOS the watch later directory is located at ~/.con‐
18600 fig/mpv/watch_later/ and the cache directory is set to ~/Li‐
18601 brary/Caches/io.mpv/. These directories can't be overwritten by enviro‐
18602 ment variables. Everything else is the same as FILES.
18603
18605 GPLv2+
18606 MPV(1)