1 .\" Man page generated from reStructuredText.
2 .
3 .TH MPV 1 "" "" "multimedia"
4 .SH NAME
5 mpv \- a media player
6 .
7 .nr rst2man-indent-level 0
8 .
9 .de1 rstReportMargin
10 \\$1 \\n[an-margin]
11 level \\n[rst2man-indent-level]
12 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
13 -
14 \\n[rst2man-indent0]
15 \\n[rst2man-indent1]
16 \\n[rst2man-indent2]
17 ..
18 .de1 INDENT
19 .\" .rstReportMargin pre:
20 . RS \\$1
21 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
22 . nr rst2man-indent-level +1
23 .\" .rstReportMargin post:
24 ..
25 .de UNINDENT
26 . RE
27 .\" indent \\n[an-margin]
28 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
29 .nr rst2man-indent-level -1
30 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
31 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
32 ..
33 .SH SYNOPSIS
34 .nf
35 \fBmpv\fP [options] [file|URL|PLAYLIST|\-]
36 \fBmpv\fP [options] files
37 .fi
38 .sp
39 .SH DESCRIPTION
40 .sp
41 \fBmpv\fP is a media player based on MPlayer and mplayer2. It supports a wide variety of video
42 file formats, audio and video codecs, and subtitle types. Special input URL
43 types are available to read input from a variety of sources other than disk
44 files. Depending on platform, a variety of different video and audio output
45 methods are supported.
46 .sp
47 Usage examples to get you started quickly can be found at the end of this man
48 page.
49 .SH INTERACTIVE CONTROL
50 .sp
51 mpv has a fully configurable, command\-driven control layer which allows you
52 to control mpv using keyboard, mouse, or remote control (there is no
53 LIRC support \- configure remotes as input devices instead).
54 .sp
55 See the \fB\-\-input\-\fP options for ways to customize it.
56 .sp
57 The following listings are not necessarily complete. See \fBetc/input.conf\fP for
58 a list of default bindings. User \fBinput.conf\fP files and Lua scripts can
59 define additional key bindings.
60 .SS Keyboard Control
61 .INDENT 0.0
62 .TP
63 .B LEFT and RIGHT
64 Seek backward/forward 5 seconds. Shift+arrow does a 1 second exact seek
65 (see \fB\-\-hr\-seek\fP).
66 .TP
67 .B UP and DOWN
68 Seek forward/backward 1 minute. Shift+arrow does a 5 second exact seek (see
69 \fB\-\-hr\-seek\fP).
70 .TP
71 .B Ctrl+LEFT and Ctrl+RIGHT
72 Seek to the previous/next subtitle. Subject to some restrictions and
73 might not always work; see \fBsub\-seek\fP command.
74 .TP
75 .B Ctrl+Shift+Left and Ctrl+Shift+Right
76 Adjust subtitle delay so that the next or previous subtitle is displayed
77 now. This is especially useful to sync subtitles to audio.
78 .TP
79 .B [ and ]
80 Decrease/increase current playback speed by 10%.
81 .TP
82 .B { and }
83 Halve/double current playback speed.
84 .TP
85 .B BACKSPACE
86 Reset playback speed to normal.
87 .TP
88 .B Shift+BACKSPACE
89 Undo the last seek. This works only if the playlist entry was not changed.
90 Hitting it a second time will go back to the original position.
91 See \fBrevert\-seek\fP command for details.
92 .TP
93 .B Shift+Ctrl+BACKSPACE
94 Mark the current position. This will then be used by \fBShift+BACKSPACE\fP
95 as revert position (once you seek back, the marker will be reset). You can
96 use this to seek around in the file and then return to the exact position
97 where you left off.
98 .TP
99 .B < and >
100 Go backward/forward in the playlist.
101 .TP
102 .B ENTER
103 Go forward in the playlist.
104 .TP
105 .B p / SPACE
106 Pause (pressing again unpauses).
107 .TP
108 .B \&.
109 Step forward. Pressing once will pause, every consecutive press will
110 play one frame and then go into pause mode again.
111 .UNINDENT
112 .INDENT 0.0
113 .TP
114 .B ,
115 Step backward. Pressing once will pause, every consecutive press will
116 play one frame in reverse and then go into pause mode again.
117 .TP
118 .B q
119 Stop playing and quit.
120 .TP
121 .B Q
122 Like \fBq\fP, but store the current playback position. Playing the same file
123 later will resume at the old playback position if possible.
124 .TP
125 .B / and *
126 Decrease/increase volume.
127 .TP
128 .B 9 and 0
129 Decrease/increase volume.
130 .TP
131 .B m
132 Mute sound.
133 .TP
134 .B _
135 Cycle through the available video tracks.
136 .TP
137 .B #
138 Cycle through the available audio tracks.
139 .TP
140 .B f
141 Toggle fullscreen (see also \fB\-\-fs\fP).
142 .TP
143 .B ESC
144 Exit fullscreen mode.
145 .TP
146 .B T
147 Toggle stay\-on\-top (see also \fB\-\-ontop\fP).
148 .TP
149 .B w and W
150 Decrease/increase pan\-and\-scan range. The \fBe\fP key does the same as
151 \fBW\fP currently, but use is discouraged.
152 .TP
153 .B o (also P)
154 Show progression bar, elapsed time and total duration on the OSD.
155 .TP
156 .B O
157 Toggle OSD states between normal and playback time/duration.
158 .TP
159 .B v
160 Toggle subtitle visibility.
161 .TP
162 .B j and J
163 Cycle through the available subtitles.
164 .TP
165 .B z and Z
166 Adjust subtitle delay by +/\- 0.1 seconds. The \fBx\fP key does the same as
167 \fBZ\fP currently, but use is discouraged.
168 .TP
169 .B l
170 Set/clear A\-B loop points. See \fBab\-loop\fP command for details.
171 .TP
172 .B L
173 Toggle infinite looping.
174 .TP
175 .B Ctrl + and Ctrl \-
176 Adjust audio delay (A/V sync) by +/\- 0.1 seconds.
177 .TP
178 .B Shift+g and Shift+f
179 Adjust subtitle font size by +/\- 10%.
180 .TP
181 .B u
182 Switch between applying no style overrides to SSA/ASS subtitles, and
183 overriding them almost completely with the normal subtitle style. See
184 \fB\-\-sub\-ass\-override\fP for more info.
185 .TP
186 .B V
187 Toggle subtitle VSFilter aspect compatibility mode. See
188 \fB\-\-sub\-ass\-vsfilter\-aspect\-compat\fP for more info.
189 .TP
190 .B r and R
191 Move subtitles up/down. The \fBt\fP key does the same as \fBR\fP currently, but
192 use is discouraged.
193 .TP
194 .B s
195 Take a screenshot.
196 .TP
197 .B S
198 Take a screenshot, without subtitles. (Whether this works depends on VO
199 driver support.)
200 .TP
201 .B Ctrl s
202 Take a screenshot, as the window shows it (with subtitles, OSD, and scaled
203 video).
204 .TP
205 .B PGUP and PGDWN
206 Seek to the beginning of the previous/next chapter. In most cases,
207 "previous" will actually go to the beginning of the current chapter; see
208 \fB\-\-chapter\-seek\-threshold\fP\&.
209 .TP
210 .B Shift+PGUP and Shift+PGDWN
211 Seek backward or forward by 10 minutes. (This used to be mapped to
212 PGUP/PGDWN without Shift.)
213 .TP
214 .B d
215 Activate/deactivate deinterlacer.
216 .TP
217 .B A
218 Cycle aspect ratio override.
219 .TP
220 .B Ctrl h
221 Toggle hardware video decoding on/off.
222 .TP
223 .B Alt+LEFT, Alt+RIGHT, Alt+UP, Alt+DOWN
224 Move the video rectangle (panning).
225 .TP
226 .B Alt + and Alt \-
227 Combining \fBAlt\fP with the \fB+\fP or \fB\-\fP keys changes video zoom.
228 .TP
229 .B Alt+BACKSPACE
230 Reset the pan/zoom settings.
231 .TP
232 .B F8
233 Show the playlist and the current position in it (useful only if a UI window
234 is used, broken on the terminal).
235 .TP
236 .B F9
237 Show the list of audio and subtitle streams (useful only if a UI window is
238 used, broken on the terminal).
239 .TP
240 .B i and I
241 Show/toggle an overlay displaying statistics about the currently playing
242 file such as codec, framerate, number of dropped frames and so on. See
243 \fI\%STATS\fP for more information.
244 .TP
245 .B del
246 Cycles visibility between never / auto (mouse\-move) / always
247 .TP
248 .B \(ga
249 Show the console. (ESC closes it again. See \fI\%CONSOLE\fP\&.)
250 .UNINDENT
251 .sp
252 (The following keys are valid only when using a video output that supports the
253 corresponding adjustment.)
254 .INDENT 0.0
255 .TP
256 .B 1 and 2
257 Adjust contrast.
258 .TP
259 .B 3 and 4
260 Adjust brightness.
261 .TP
262 .B 5 and 6
263 Adjust gamma.
264 .TP
265 .B 7 and 8
266 Adjust saturation.
267 .TP
268 .B Alt+0 (and command+0 on OSX)
269 Resize video window to half its original size.
270 .TP
271 .B Alt+1 (and command+1 on OSX)
272 Resize video window to its original size.
273 .TP
274 .B Alt+2 (and command+2 on OSX)
275 Resize video window to double its original size.
276 .TP
277 .B command + f (OSX only)
278 Toggle fullscreen (see also \fB\-\-fs\fP).
279 .UNINDENT
280 .sp
281 (The following keys are valid if you have a keyboard with multimedia keys.)
282 .INDENT 0.0
283 .TP
284 .B PAUSE
285 Pause.
286 .TP
287 .B STOP
288 Stop playing and quit.
289 .TP
290 .B PREVIOUS and NEXT
291 Seek backward/forward 1 minute.
292 .UNINDENT
293 .sp
294 If you miss some older key bindings, look at \fBetc/restore\-old\-bindings.conf\fP
295 in the mpv git repository.
296 .SS Mouse Control
297 .INDENT 0.0
298 .TP
299 .B Left double click
300 Toggle fullscreen on/off.
301 .TP
302 .B Right click
303 Toggle pause on/off.
304 .TP
305 .B Forward/Back button
306 Skip to next/previous entry in playlist.
307 .TP
308 .B Wheel up/down
309 Seek forward/backward 10 seconds.
310 .TP
311 .B Wheel left/right
312 Decrease/increase volume.
313 .UNINDENT
314 .SH USAGE
315 .sp
316 Command line arguments starting with \fB\-\fP are interpreted as options,
317 everything else as filenames or URLs. All options except \fIflag\fP options (or
318 choice options which include \fByes\fP) require a parameter in the form
319 \fB\-\-option=value\fP\&.
320 .sp
321 One exception is the lone \fB\-\fP (without anything else), which means media data
322 will be read from stdin. Also, \fB\-\-\fP (without anything else) will make the
323 player interpret all following arguments as filenames, even if they start with
324 \fB\-\fP\&. (To play a file named \fB\-\fP, you need to use \fB\&./\-\fP\&.)
325 .sp
326 Every \fIflag\fP option has a \fIno\-flag\fP counterpart, e.g. the opposite of the
327 \fB\-\-fs\fP option is \fB\-\-no\-fs\fP\&. \fB\-\-fs=yes\fP is same as \fB\-\-fs\fP, \fB\-\-fs=no\fP
328 is the same as \fB\-\-no\-fs\fP\&.
329 .sp
330 If an option is marked as \fI(XXX only)\fP, it will only work in combination with
331 the \fIXXX\fP option or if \fIXXX\fP is compiled in.
332 .SS Legacy option syntax
333 .sp
334 The \fB\-\-option=value\fP syntax is not strictly enforced, and the alternative
335 legacy syntax \fB\-option value\fP and \fB\-option=value\fP will also work. This is
336 mostly for compatibility with MPlayer. Using these should be avoided. Their
337 semantics can change any time in the future.
338 .sp
339 For example, the alternative syntax will consider an argument following the
340 option a filename. \fBmpv \-fs no\fP will attempt to play a file named \fBno\fP,
341 because \fB\-\-fs\fP is a flag option that requires no parameter. If an option
342 changes and its parameter becomes optional, then a command line using the
343 alternative syntax will break.
344 .sp
345 Until mpv 0.31.0, there was no difference whether an option started with \fB\-\-\fP
346 or a single \fB\-\fP\&. Newer mpv releases strictly expect that you pass the option
347 value after a \fB=\fP\&. For example, before \fBmpv \-\-log\-file f.txt\fP would write
348 a log to \fBf.txt\fP, but now this command line fails, as \fB\-\-log\-file\fP expects
349 an option value, and \fBf.txt\fP is simply considered a normal file to be played
350 (as in \fBmpv f.txt\fP).
351 .sp
352 The future plan is that \fB\-option value\fP will not work anymore, and options
353 with a single \fB\-\fP behave the same as \fB\-\-\fP options.
354 .SS Escaping spaces and other special characters
355 .sp
356 Keep in mind that the shell will partially parse and mangle the arguments you
357 pass to mpv. For example, you might need to quote or escape options and
358 filenames:
359 .INDENT 0.0
360 .INDENT 3.5
361 \fBmpv "filename with spaces.mkv" \-\-title="window title"\fP
362 .UNINDENT
363 .UNINDENT
364 .sp
365 It gets more complicated if the suboption parser is involved. The suboption
366 parser puts several options into a single string, and passes them to a
367 component at once, instead of using multiple options on the level of the
368 command line.
369 .sp
370 The suboption parser can quote strings with \fB"\fP and \fB[...]\fP\&.
371 Additionally, there is a special form of quoting with \fB%n%\fP described below.
372 .sp
373 For example, assume the hypothetical \fBfoo\fP filter can take multiple options:
374 .INDENT 0.0
375 .INDENT 3.5
376 \fBmpv test.mkv \-\-vf=foo:option1=value1:option2:option3=value3,bar\fP
377 .UNINDENT
378 .UNINDENT
379 .sp
380 This passes \fBoption1\fP and \fBoption3\fP to the \fBfoo\fP filter, with \fBoption2\fP
381 as flag (implicitly \fBoption2=yes\fP), and adds a \fBbar\fP filter after that. If
382 an option contains spaces or characters like \fB,\fP or \fB:\fP, you need to quote
383 them:
384 .INDENT 0.0
385 .INDENT 3.5
386 \fBmpv \(aq\-\-vf=foo:option1="option value with spaces",bar\(aq\fP
387 .UNINDENT
388 .UNINDENT
389 .sp
390 Shells may actually strip some quotes from the string passed to the commandline,
391 so the example quotes the string twice, ensuring that mpv receives the \fB"\fP
392 quotes.
393 .sp
394 The \fB[...]\fP form of quotes wraps everything between \fB[\fP and \fB]\fP\&. It\(aqs
395 useful with shells that don\(aqt interpret these characters in the middle of
396 an argument (like bash). These quotes are balanced (since mpv 0.9.0): the \fB[\fP
397 and \fB]\fP nest, and the quote terminates on the last \fB]\fP that has no matching
398 \fB[\fP within the string. (For example, \fB[a[b]c]\fP results in \fBa[b]c\fP\&.)
399 .sp
400 The fixed\-length quoting syntax is intended for use with external
401 scripts and programs.
402 .sp
403 It is started with \fB%\fP and has the following format:
404 .INDENT 0.0
405 .INDENT 3.5
406 .sp
407 .nf
408 .ft C
409 %n%string_of_length_n
410 .ft P
411 .fi
412 .UNINDENT
413 .UNINDENT
414 .INDENT 0.0
415 .INDENT 3.5
416 .IP "Examples"
417 .sp
418 \fBmpv \(aq\-\-vf=foo:option1=%11%quoted text\(aq test.avi\fP
419 .sp
420 Or in a script:
421 .sp
422 \fBmpv \-\-vf=foo:option1=%\(gaexpr length "$NAME"\(ga%"$NAME" test.avi\fP
423 .UNINDENT
424 .UNINDENT
425 .sp
426 Suboptions passed to the client API are also subject to escaping. Using
427 \fBmpv_set_option_string()\fP is exactly like passing \fB\-\-name=data\fP to the
428 command line (but without shell processing of the string). Some options
429 support passing values in a more structured way instead of flat strings, and
430 can avoid the suboption parsing mess. For example, \fB\-\-vf\fP supports
431 \fBMPV_FORMAT_NODE\fP, which lets you pass suboptions as a nested data structure
432 of maps and arrays.
433 .SS Paths
434 .sp
435 Some care must be taken when passing arbitrary paths and filenames to mpv. For
436 example, paths starting with \fB\-\fP will be interpreted as options. Likewise,
437 if a path contains the sequence \fB://\fP, the string before that might be
438 interpreted as protocol prefix, even though \fB://\fP can be part of a legal
439 UNIX path. To avoid problems with arbitrary paths, you should be sure that
440 absolute paths passed to mpv start with \fB/\fP, and prefix relative paths with
441 \fB\&./\fP\&.
442 .sp
443 Using the \fBfile://\fP pseudo\-protocol is discouraged, because it involves
444 strange URL unescaping rules.
445 .sp
446 The name \fB\-\fP itself is interpreted as stdin, and will cause mpv to disable
447 console controls. (Which makes it suitable for playing data piped to stdin.)
448 .sp
449 The special argument \fB\-\-\fP can be used to stop mpv from interpreting the
450 following arguments as options.
451 .sp
452 When using the client API, you should strictly avoid using \fBmpv_command_string\fP
453 for invoking the \fBloadfile\fP command, and instead prefer e.g. \fBmpv_command\fP
454 to avoid the need for filename escaping.
455 .sp
456 For paths passed to suboptions, the situation is further complicated by the
457 need to escape special characters. To work this around, the path can be
458 additionally wrapped in the fixed\-length syntax, e.g. \fB%n%string_of_length_n\fP
459 (see above).
460 .sp
461 Some mpv options interpret paths starting with \fB~\fP\&. Currently, the prefix
462 \fB~~/\fP expands to the mpv configuration directory (usually \fB~/.config/mpv/\fP).
463 \fB~/\fP expands to the user\(aqs home directory. (The trailing \fB/\fP is always
464 required.) The following paths are currently recognized:
465 .TS
466 center;
467 |l|l|.
468 _
469 T{
470 Name
471 T} T{
472 Meaning
473 T}
474 _
475 T{
476 \fB~~/\fP
477 T} T{
478 mpv config dir (for example \fB~/.config/mpv/\fP)
479 T}
480 _
481 T{
482 \fB~/\fP
483 T} T{
484 user home directory root (similar to shell, \fB$HOME\fP)
485 T}
486 _
487 T{
488 \fB~~home/\fP
489 T} T{
490 same as \fB~~/\fP
491 T}
492 _
493 T{
494 \fB~~global/\fP
495 T} T{
496 the global config path, if available (not on win32)
497 T}
498 _
499 T{
500 \fB~~osxbundle/\fP
501 T} T{
502 the OSX bundle resource path (OSX only)
503 T}
504 _
505 T{
506 \fB~~desktop/\fP
507 T} T{
508 the path to the desktop (win32, OSX)
509 T}
510 _
511 T{
512 \fB~~exe_dir\fP
513 T} T{
514 win32 only: the path to the directory containing the exe (for
515 config file purposes; \fB$MPV_HOME\fP overrides it)
516 T}
517 _
518 T{
519 \fB~~old_home\fP
520 T} T{
521 do not use
522 T}
523 _
524 .TE
525 .SS Per\-File Options
526 .sp
527 When playing multiple files, any option given on the command line usually
528 affects all files. Example:
529 .INDENT 0.0
530 .INDENT 3.5
531 .sp
532 .nf
533 .ft C
534 mpv \-\-a file1.mkv \-\-b file2.mkv \-\-c
535 .ft P
536 .fi
537 .UNINDENT
538 .UNINDENT
539 .TS
540 center;
541 |l|l|.
542 _
543 T{
544 File
545 T} T{
546 Active options
547 T}
548 _
549 T{
550 file1.mkv
551 T} T{
552 \fB\-\-a \-\-b \-\-c\fP
553 T}
554 _
555 T{
556 file2.mkv
557 T} T{
558 \fB\-\-a \-\-b \-\-c\fP
559 T}
560 _
561 .TE
562 .sp
563 (This is different from MPlayer and mplayer2.)
564 .sp
565 Also, if any option is changed at runtime (via input commands), they are not
566 reset when a new file is played.
567 .sp
568 Sometimes, it is useful to change options per\-file. This can be achieved by
569 adding the special per\-file markers \fB\-\-{\fP and \fB\-\-}\fP\&. (Note that you must
570 escape these on some shells.) Example:
571 .INDENT 0.0
572 .INDENT 3.5
573 .sp
574 .nf
575 .ft C
576 mpv \-\-a file1.mkv \-\-b \-\-\e{ \-\-c file2.mkv \-\-d file3.mkv \-\-e \-\-\e} file4.mkv \-\-f
577 .ft P
578 .fi
579 .UNINDENT
580 .UNINDENT
581 .TS
582 center;
583 |l|l|.
584 _
585 T{
586 File
587 T} T{
588 Active options
589 T}
590 _
591 T{
592 file1.mkv
593 T} T{
594 \fB\-\-a \-\-b \-\-f\fP
595 T}
596 _
597 T{
598 file2.mkv
599 T} T{
600 \fB\-\-a \-\-b \-\-f \-\-c \-\-d \-\-e\fP
601 T}
602 _
603 T{
604 file3.mkv
605 T} T{
606 \fB\-\-a \-\-b \-\-f \-\-c \-\-d \-\-e\fP
607 T}
608 _
609 T{
610 file4.mkv
611 T} T{
612 \fB\-\-a \-\-b \-\-f\fP
613 T}
614 _
615 .TE
616 .sp
617 Additionally, any file\-local option changed at runtime is reset when the current
618 file stops playing. If option \fB\-\-c\fP is changed during playback of
619 \fBfile2.mkv\fP, it is reset when advancing to \fBfile3.mkv\fP\&. This only affects
620 file\-local options. The option \fB\-\-a\fP is never reset here.
621 .SS List Options
622 .sp
623 Some options which store lists of option values can have action suffixes. For
624 example, the \fB\-\-display\-tags\fP option takes a \fB,\fP\-separated list of tags, but
625 the option also allows you to append a single tag with \fB\-\-display\-tags\-append\fP,
626 and the tag name can for example contain a literal \fB,\fP without the need for
627 escaping.
628 .SS String list and path list options
629 .sp
630 String lists are separated by \fB,\fP\&. The strings are not parsed or interpreted
631 by the option system itself. However, most
632 .sp
633 Path or file list options use \fB:\fP (Unix) or \fB;\fP (Windows) as separator,
634 instead of \fB,\fP\&.
635 .sp
636 They support the following operations:
637 .TS
638 center;
639 |l|l|.
640 _
641 T{
642 Suffix
643 T} T{
644 Meaning
645 T}
646 _
647 T{
648 \-set
649 T} T{
650 Set a list of items (using the list separator, interprets escapes)
651 T}
652 _
653 T{
654 \-append
655 T} T{
656 Append single item (does not interpret escapes)
657 T}
658 _
659 T{
660 \-add
661 T} T{
662 Append 1 or more items (same syntax as \-set)
663 T}
664 _
665 T{
666 \-pre
667 T} T{
668 Prepend 1 or more items (same syntax as \-set)
669 T}
670 _
671 T{
672 \-clr
673 T} T{
674 Clear the option (remove all items)
675 T}
676 _
677 T{
678 \-remove
679 T} T{
680 Delete item if present (does not interpret escapes)
681 T}
682 _
683 T{
684 \-del
685 T} T{
686 Delete 1 or more items by integer index (deprecated)
687 T}
688 _
689 T{
690 \-toggle
691 T} T{
692 Append an item, or remove if if it already exists (no escapes)
693 T}
694 _
695 .TE
696 .sp
697 \fB\-append\fP is meant as a simple way to append a single item without having
698 to escape the argument (you may still need to escape on the shell level).
699 .SS Key/value list options
700 .sp
701 A key/value list is a list of key/value string pairs. In programming languages,
702 this type of data structure is often called a map or a dictionary. The order
703 normally does not matter, although in some cases the order might matter.
704 .sp
705 They support the following operations:
706 .TS
707 center;
708 |l|l|.
709 _
710 T{
711 Suffix
712 T} T{
713 Meaning
714 T}
715 _
716 T{
717 \-set
718 T} T{
719 Set a list of items (using \fB,\fP as separator)
720 T}
721 _
722 T{
723 \-append
724 T} T{
725 Append a single item (escapes for the key, no escapes for the value)
726 T}
727 _
728 T{
729 \-add
730 T} T{
731 Append 1 or more items (same syntax as \-set)
732 T}
733 _
734 T{
735 \-remove
736 T} T{
737 Delete item by key if present (does not interpret escapes)
738 T}
739 _
740 .TE
741 .sp
742 Keys are unique within the list. If an already present key is set, the existing
743 key is removed before the new value is appended.
744 .sp
745 If you want to pass a value without interpreting it for escapes or \fB,\fP, it is
746 recommended to use the \fB\-add\fP variant. When using libmpv, prefer using
747 \fBMPV_FORMAT_NODE_MAP\fP; when using a scripting backend or the JSON IPC, use an
748 appropriate structured data type.
749 .sp
750 Prior to mpv 0.33, \fB:\fP was also recognized as separator by \fB\-set\fP\&.
751 .SS Filter options
752 .sp
753 This is a very complex option type for the \fB\-\-af\fP and \fB\-\-vf\fP options only.
754 They often require complicated escaping. See \fI\%VIDEO FILTERS\fP for details. They
755 support the following operations:
756 .TS
757 center;
758 |l|l|.
759 _
760 T{
761 Suffix
762 T} T{
763 Meaning
764 T}
765 _
766 T{
767 \-set
768 T} T{
769 Set a list of filters (using \fB,\fP as separator)
770 T}
771 _
772 T{
773 \-append
774 T} T{
775 Append single filter
776 T}
777 _
778 T{
779 \-add
780 T} T{
781 Append 1 or more filters (same syntax as \-set)
782 T}
783 _
784 T{
785 \-pre
786 T} T{
787 Prepend 1 or more filters (same syntax as \-set)
788 T}
789 _
790 T{
791 \-clr
792 T} T{
793 Clear the option (remove all filters)
794 T}
795 _
796 T{
797 \-remove
798 T} T{
799 Delete filter if present
800 T}
801 _
802 T{
803 \-del
804 T} T{
805 Delete 1 or more filters by integer index or filter label (deprecated)
806 T}
807 _
808 T{
809 \-toggle
810 T} T{
811 Append a filter, or remove if if it already exists
812 T}
813 _
814 T{
815 \-help
816 T} T{
817 Pseudo operation that prints a help text to the terminal
818 T}
819 _
820 .TE
821 .SS General
822 .sp
823 Without suffix, the operation used is normally \fB\-set\fP\&.
824 .sp
825 Although some operations allow specifying multiple items, using this is strongly
826 discouraged and deprecated, except for \fB\-set\fP\&. There is a chance that
827 operations like \fB\-add\fP and \fB\-pre\fP will work like \fB\-append\fP and accept a
828 single, unescaped item only (so the \fB,\fP separator will not be interpreted and
829 is passed on as part of the value).
830 .sp
831 Some options (like \fB\-\-sub\-file\fP, \fB\-\-audio\-file\fP, \fB\-\-glsl\-shader\fP) are
832 aliases for the proper option with \fB\-append\fP action. For example,
833 \fB\-\-sub\-file\fP is an alias for \fB\-\-sub\-files\-append\fP\&.
834 .sp
835 Options of this type can be changed at runtime using the \fBchange\-list\fP
836 command, which takes the suffix (without the \fB\-\fP) as separate operation
837 parameter.
838 .SH CONFIGURATION FILES
839 .SS Location and Syntax
840 .sp
841 You can put all of the options in configuration files which will be read every
842 time mpv is run. The system\-wide configuration file \(aqmpv.conf\(aq is in your
843 configuration directory (e.g. \fB/etc/mpv\fP or \fB/usr/local/etc/mpv\fP), the
844 user\-specific one is \fB~/.config/mpv/mpv.conf\fP\&. For details and platform
845 specifics (in particular Windows paths) see the \fI\%FILES\fP section.
846 .sp
847 User\-specific options override system\-wide options and options given on the
848 command line override either. The syntax of the configuration files is
849 \fBoption=value\fP\&. Everything after a \fI#\fP is considered a comment. Options
850 that work without values can be enabled by setting them to \fIyes\fP and disabled by
851 setting them to \fIno\fP\&. Even suboptions can be specified in this way.
852 .INDENT 0.0
853 .INDENT 3.5
854 .IP "Example configuration file"
855 .INDENT 0.0
856 .INDENT 3.5
857 .sp
858 .nf
859 .ft C
860 # Use GPU\-accelerated video output by default.
861 vo=gpu
862 # Use quotes for text that can contain spaces:
863 term\-status\-msg="Time: ${time\-pos}"
864 .ft P
865 .fi
866 .UNINDENT
867 .UNINDENT
868 .UNINDENT
869 .UNINDENT
870 .SS Escaping spaces and special characters
871 .sp
872 This is done like with command line options. The shell is not involved here,
873 but option values still need to be quoted as a whole if it contains certain
874 characters like spaces. A config entry can be quoted with \fB"\fP,
875 as well as with the fixed\-length syntax (\fB%n%\fP) mentioned before. This is like
876 passing the exact contents of the quoted string as command line option. C\-style
877 escapes are currently _not_ interpreted on this level, although some options do
878 this manually. (This is a mess and should probably be changed at some point.)
879 .SS Putting Command Line Options into the Configuration File
880 .sp
881 Almost all command line options can be put into the configuration file. Here
882 is a small guide:
883 .TS
884 center;
885 |l|l|.
886 _
887 T{
888 Option
889 T} T{
890 Configuration file entry
891 T}
892 _
893 T{
894 \fB\-\-flag\fP
895 T} T{
896 \fBflag\fP
897 T}
898 _
899 T{
900 \fB\-opt val\fP
901 T} T{
902 \fBopt=val\fP
903 T}
904 _
905 T{
906 \fB\-\-opt=val\fP
907 T} T{
908 \fBopt=val\fP
909 T}
910 _
911 T{
912 \fB\-opt "has spaces"\fP
913 T} T{
914 \fBopt="has spaces"\fP
915 T}
916 _
917 .TE
918 .SS File\-specific Configuration Files
919 .sp
920 You can also write file\-specific configuration files. If you wish to have a
921 configuration file for a file called \(aqvideo.avi\(aq, create a file named
922 \(aqvideo.avi.conf\(aq with the file\-specific options in it and put it in
923 \fB~/.config/mpv/\fP\&. You can also put the configuration file in the same directory
924 as the file to be played. Both require you to set the \fB\-\-use\-filedir\-conf\fP
925 option (either on the command line or in your global config file). If a
926 file\-specific configuration file is found in the same directory, no
927 file\-specific configuration is loaded from \fB~/.config/mpv\fP\&. In addition, the
928 \fB\-\-use\-filedir\-conf\fP option enables directory\-specific configuration files.
929 For this, mpv first tries to load a mpv.conf from the same directory
930 as the file played and then tries to load any file\-specific configuration.
931 .SS Profiles
932 .sp
933 To ease working with different configurations, profiles can be defined in the
934 configuration files. A profile starts with its name in square brackets,
935 e.g. \fB[my\-profile]\fP\&. All following options will be part of the profile. A
936 description (shown by \fB\-\-profile=help\fP) can be defined with the
937 \fBprofile\-desc\fP option. To end the profile, start another one or use the
938 profile name \fBdefault\fP to continue with normal options.
939 .sp
940 You can list profiles with \fB\-\-profile=help\fP, and show the contents of a
941 profile with \fB\-\-show\-profile=<name>\fP (replace \fB<name>\fP with the profile
942 name). You can apply profiles on start with the \fB\-\-profile=<name>\fP option,
943 or at runtime with the \fBapply\-profile <name>\fP command.
944 .INDENT 0.0
945 .INDENT 3.5
946 .IP "Example mpv config file with profiles"
947 .INDENT 0.0
948 .INDENT 3.5
949 .sp
950 .nf
951 .ft C
952 # normal top\-level option
953 fullscreen=yes
954
955 # a profile that can be enabled with \-\-profile=big\-cache
956 [big\-cache]
957 cache=yes
958 demuxer\-max\-bytes=123400KiB
959 demuxer\-readahead\-secs=20
960
961 [slow]
962 profile\-desc="some profile name"
963 # reference a builtin profile
964 profile=gpu\-hq
965
966 [fast]
967 vo=vdpau
968
969 # using a profile again extends it
970 [slow]
971 framedrop=no
972 # you can also include other profiles
973 profile=big\-cache
974 .ft P
975 .fi
976 .UNINDENT
977 .UNINDENT
978 .UNINDENT
979 .UNINDENT
980 .SS Runtime profiles
981 .sp
982 Profiles can be set at runtime with \fBapply\-profile\fP command. Since this
983 operation is "destructive" (every item in a profile is simply set as an
984 option, overwriting the previous value), you can\(aqt just enable and disable
985 profiles again.
986 .sp
987 As a partial remedy, there is a way to make profiles save old option values
988 before overwriting them with the profile values, and then restoring the old
989 values at a later point using \fBapply\-profile <profile\-name> restore\fP\&.
990 .sp
991 This can be enabled with the \fBprofile\-restore\fP option, which takes one of
992 the following options:
993 .INDENT 0.0
994 .INDENT 3.5
995 .INDENT 0.0
996 .TP
997 .B \fBdefault\fP
998 Does nothing, and nothing can be restored (default).
999 .TP
1000 .B \fBcopy\fP
1001 When applying a profile, copy the old values of all profile options to a
1002 backup before setting them from the profile. These options are reset to
1003 their old values using the backup when restoring.
1004 .sp
1005 Every profile has its own list of backed up values. If the backup
1006 already exists (e.g. if \fBapply\-profile name\fP was called more than
1007 once in a row), the existing backup is no changed. The restore operation
1008 will remove the backup.
1009 .sp
1010 It\(aqs important to know that restoring does not "undo" setting an option,
1011 but simply copies the old option value. Consider for example \fBvf\-add\fP,
1012 appends an entry to \fBvf\fP\&. This mechanism will simply copy the entire
1013 \fBvf\fP list, and does _not_ execute the inverse of \fBvf\-add\fP (that
1014 would be \fBvf\-remove\fP) on restoring.
1015 .sp
1016 Note that if a profile contains recursive profiles (via the \fBprofile\fP
1017 option), the options in these recursive profiles are treated as if they
1018 were part of this profile. The referenced profile\(aqs backup list is not
1019 used when creating or using the backup. Restoring a profile does not
1020 restore referenced profiles, only the options of referenced profiles (as
1021 if they were part of the main profile).
1022 .TP
1023 .B \fBcopy\-equal\fP
1024 Similar to \fBcopy\fP, but restore an option only if it has the same value
1025 as the value effectively set by the profile. This tries to deal with
1026 the situation when the user does not want the option to be reset after
1027 interactively changing it.
1028 .UNINDENT
1029 .UNINDENT
1030 .UNINDENT
1031 .INDENT 0.0
1032 .INDENT 3.5
1033 .IP "Example"
1034 .INDENT 0.0
1035 .INDENT 3.5
1036 .sp
1037 .nf
1038 .ft C
1039 [something]
1040 profile\-restore=copy\-equal
1041 vf\-add=rotate=90
1042 .ft P
1043 .fi
1044 .UNINDENT
1045 .UNINDENT
1046 .sp
1047 Then running these commands will result in behavior as commented:
1048 .INDENT 0.0
1049 .INDENT 3.5
1050 .sp
1051 .nf
1052 .ft C
1053 set vf vflip
1054 apply\-profile something
1055 vf\-add=hflip
1056 apply\-profile something
1057 # vf == vflip,rotate=90,hflip,rotate=90
1058 apply\-profile something restore
1059 # vf == vflip
1060 .ft P
1061 .fi
1062 .UNINDENT
1063 .UNINDENT
1064 .UNINDENT
1065 .UNINDENT
1066 .SS Conditional auto profiles
1067 .sp
1068 Profiles which have the \fBprofile\-cond\fP option set are applied automatically
1069 if the associated condition matches (unless auto profiles are disabled). The
1070 option takes a string, which is interpreted as Lua condition. If evaluating the
1071 expression returns true, the profile is applied, if it returns false, it is
1072 ignored. This Lua code execution is not sandboxed.
1073 .sp
1074 Any variables in condition expressions can reference properties. If an
1075 identifier is not already defined by Lua or mpv, it is interpreted as property.
1076 For example, \fBpause\fP would return the current pause status. If the variable
1077 name contains any \fB_\fP characters, they are turned into \fB\-\fP\&. For example,
1078 \fBplayback_time\fP would return the property \fBplayback\-time\fP\&.
1079 .sp
1080 A more robust way to access properties is using \fBp.property_name\fP or
1081 \fBget("property\-name", default_value)\fP\&. The automatic variable to property
1082 magic will break if a new identifier with the same name is introduced (for
1083 example, if a function named \fBpause()\fP were added, \fBpause\fP would return a
1084 function value instead of the value of the \fBpause\fP property).
1085 .sp
1086 Note that if a property is not available, it will return \fBnil\fP, which can
1087 cause errors if used in expressions. These are logged in verbose mode, and the
1088 expression is considered to be false.
1089 .sp
1090 Whenever a property referenced by a profile condition changes, the condition
1091 is re\-evaluated. If the return value of the condition changes from false or
1092 error to true, the profile is applied.
1093 .sp
1094 This mechanism tries to "unapply" profiles once the condition changes from true
1095 to false. If you want to use this, you need to set \fBprofile\-restore\fP for the
1096 profile. Another possibility it to create another profile with an inverse
1097 condition to undo the other profile.
1098 .sp
1099 Recursive profiles can be used. But it is discouraged to reference other
1100 conditional profiles in a conditional profile, since this can lead to tricky
1101 and unintuitive behavior.
1102 .INDENT 0.0
1103 .INDENT 3.5
1104 .IP "Example"
1105 .sp
1106 Make only HD video look funny:
1107 .INDENT 0.0
1108 .INDENT 3.5
1109 .sp
1110 .nf
1111 .ft C
1112 [something]
1113 profile\-desc=HD video sucks
1114 profile\-cond=width >= 1280
1115 hue=\-50
1116 .ft P
1117 .fi
1118 .UNINDENT
1119 .UNINDENT
1120 .sp
1121 If you want the profile to be reverted if the condition goes to false again,
1122 you can set \fBprofile\-restore\fP:
1123 .INDENT 0.0
1124 .INDENT 3.5
1125 .sp
1126 .nf
1127 .ft C
1128 [something]
1129 profile\-desc=Mess up video when entering fullscreen
1130 profile\-cond=fullscreen
1131 profile\-restore=copy
1132 vf\-add=rotate=90
1133 .ft P
1134 .fi
1135 .UNINDENT
1136 .UNINDENT
1137 .sp
1138 This appends the \fBrotate\fP filter to the video filter chain when entering
1139 fullscreen. When leaving fullscreen, the \fBvf\fP option is set to the value
1140 it had before entering fullscreen. Note that this would also remove any
1141 other filters that were added during fullscreen mode by the user. Avoiding
1142 this is trickier, and could for example be solved by adding a second profile
1143 with an inverse condition and operation:
1144 .INDENT 0.0
1145 .INDENT 3.5
1146 .sp
1147 .nf
1148 .ft C
1149 [something]
1150 profile\-cond=fullscreen
1151 vf\-add=@rot:rotate=90
1152
1153 [something\-inv]
1154 profile\-cond=not fullscreen
1155 vf\-remove=@rot
1156 .ft P
1157 .fi
1158 .UNINDENT
1159 .UNINDENT
1160 .UNINDENT
1161 .UNINDENT
1162 .sp
1163 \fBWARNING:\fP
1164 .INDENT 0.0
1165 .INDENT 3.5
1166 Every time an involved property changes, the condition is evaluated again.
1167 If your condition uses \fBp.playback_time\fP for example, the condition is
1168 re\-evaluated approximately on every video frame. This is probably slow.
1169 .UNINDENT
1170 .UNINDENT
1171 .sp
1172 This feature is managed by an internal Lua script. Conditions are executed as
1173 Lua code within this script. Its environment contains at least the following
1174 things:
1175 .INDENT 0.0
1176 .TP
1177 .B \fB(function environment table)\fP
1178 Every Lua function has an environment table. This is used for identifier
1179 access. There is no named Lua symbol for it; it is implicit.
1180 .sp
1181 The environment does "magic" accesses to mpv properties. If an identifier
1182 is not already defined in \fB_G\fP, it retrieves the mpv property of the same
1183 name. Any occurrences of \fB_\fP in the name are replaced with \fB\-\fP before
1184 reading the property. The returned value is as retrieved by
1185 \fBmp.get_property_native(name)\fP\&. Internally, a cache of property values,
1186 updated by observing the property is used instead, so properties that are
1187 not observable will be stuck at the initial value forever.
1188 .sp
1189 If you want to access properties, that actually contain \fB_\fP in the name,
1190 use \fBget()\fP (which does not perform transliteration).
1191 .sp
1192 Internally, the environment table has a \fB__index\fP meta method set, which
1193 performs the access logic.
1194 .TP
1195 .B \fBp\fP
1196 A "magic" table similar to the environment table. Unlike the latter, this
1197 does not prefer accessing variables defined in \fB_G\fP \- it always accesses
1198 properties.
1199 .TP
1200 .B \fBget(name [, def])\fP
1201 Read a property and return its value. If the property value is \fBnil\fP (e.g.
1202 if the property does not exist), \fBdef\fP is returned.
1203 .sp
1204 This is superficially similar to \fBmp.get_property_native(name)\fP\&. An
1205 important difference is that this accesses the property cache, and enables
1206 the change detection logic (which is essential to the dynamic runtime
1207 behavior of auto profiles). Also, it does not return an error value as
1208 second return value.
1209 .sp
1210 The "magic" tables mentioned above use this function as backend. It does not
1211 perform the \fB_\fP transliteration.
1212 .UNINDENT
1213 .sp
1214 In addition, the same environment as in a blank mpv Lua script is present. For
1215 example, \fBmath\fP is defined and gives access to the Lua standard math library.
1216 .sp
1217 \fBWARNING:\fP
1218 .INDENT 0.0
1219 .INDENT 3.5
1220 This feature is subject to change indefinitely. You might be forced to
1221 adjust your profiles on mpv updates.
1222 .UNINDENT
1223 .UNINDENT
1224 .SS Legacy auto profiles
1225 .sp
1226 Some profiles are loaded automatically using a legacy mechanism. The following
1227 example demonstrates this:
1228 .INDENT 0.0
1229 .INDENT 3.5
1230 .IP "Auto profile loading"
1231 .INDENT 0.0
1232 .INDENT 3.5
1233 .sp
1234 .nf
1235 .ft C
1236 [extension.mkv]
1237 profile\-desc="profile for .mkv files"
1238 vf=vflip
1239 .ft P
1240 .fi
1241 .UNINDENT
1242 .UNINDENT
1243 .UNINDENT
1244 .UNINDENT
1245 .sp
1246 The profile name follows the schema \fBtype.name\fP, where type can be
1247 \fBprotocol\fP for the input/output protocol in use (see \fB\-\-list\-protocols\fP),
1248 and \fBextension\fP for the extension of the path of the currently played file
1249 (\fInot\fP the file format).
1250 .sp
1251 This feature is very limited, and is considered soft\-deprecated. Use conditional
1252 auto profiles.
1253 .SH USING MPV FROM OTHER PROGRAMS OR SCRIPTS
1254 .sp
1255 There are three choices for using mpv from other programs or scripts:
1256 .INDENT 0.0
1257 .INDENT 3.5
1258 .INDENT 0.0
1259 .IP 1. 3
1260 Calling it as UNIX process. If you do this, \fIdo not parse terminal output\fP\&.
1261 The terminal output is intended for humans, and may change any time. In
1262 addition, terminal behavior itself may change any time. Compatibility
1263 cannot be guaranteed.
1264 .sp
1265 Your code should work even if you pass \fB\-\-no\-terminal\fP\&. Do not attempt
1266 to simulate user input by sending terminal control codes to mpv\(aqs stdin.
1267 If you need interactive control, using \fB\-\-input\-ipc\-server\fP is
1268 recommended. This gives you access to the \fI\%JSON IPC\fP over unix domain
1269 sockets (or named pipes on Windows).
1270 .sp
1271 Depending on what you do, passing \fB\-\-no\-config\fP or \fB\-\-config\-dir\fP may
1272 be a good idea to avoid conflicts with the normal mpv user configuration
1273 intended for CLI playback.
1274 .sp
1275 Using \fB\-\-input\-ipc\-server\fP is also suitable for purposes like remote
1276 control (however, the IPC protocol itself is not "secure" and not
1277 intended to be so).
1278 .IP 2. 3
1279 Using libmpv. This is generally recommended when mpv is used as playback
1280 backend for a completely different application. The provided C API is
1281 very close to CLI mechanisms and the scripting API.
1282 .sp
1283 Note that even though libmpv has different defaults, it can be configured
1284 to work exactly like the CLI player (except command line parsing is
1285 unavailable).
1286 .sp
1287 See \fI\%EMBEDDING INTO OTHER PROGRAMS (LIBMPV)\fP\&.
1288 .IP 3. 3
1289 As a user script (\fI\%LUA SCRIPTING\fP, \fI\%JAVASCRIPT\fP, \fI\%C PLUGINS\fP). This is
1290 recommended when the goal is to "enhance" the CLI player. Scripts get
1291 access to the entire client API of mpv.
1292 .sp
1293 This is the standard way to create third\-party extensions for the player.
1294 .UNINDENT
1295 .UNINDENT
1296 .UNINDENT
1297 .sp
1298 All these access the client API, which is the sum of the various mechanisms
1299 provided by the player core, as documented here: \fI\%OPTIONS\fP,
1300 \fI\%List of Input Commands\fP, \fI\%Properties\fP, \fI\%List of events\fP (also see C API),
1301 \fI\%Hooks\fP\&.
1302 .SH TAKING SCREENSHOTS
1303 .sp
1304 Screenshots of the currently played file can be taken using the \(aqscreenshot\(aq
1305 input mode command, which is by default bound to the \fBs\fP key. Files named
1306 \fBmpv\-shotNNNN.jpg\fP will be saved in the working directory, using the first
1307 available number \- no files will be overwritten. In pseudo\-GUI mode, the
1308 screenshot will be saved somewhere else. See \fI\%PSEUDO GUI MODE\fP\&.
1309 .sp
1310 A screenshot will usually contain the unscaled video contents at the end of the
1311 video filter chain and subtitles. By default, \fBS\fP takes screenshots without
1312 subtitles, while \fBs\fP includes subtitles.
1313 .sp
1314 Unlike with MPlayer, the \fBscreenshot\fP video filter is not required. This
1315 filter was never required in mpv, and has been removed.
1316 .SH TERMINAL STATUS LINE
1317 .sp
1318 During playback, mpv shows the playback status on the terminal. It looks like
1319 something like this:
1320 .INDENT 0.0
1321 .INDENT 3.5
1322 \fBAV: 00:03:12 / 00:24:25 (13%) A\-V: \-0.000\fP
1323 .UNINDENT
1324 .UNINDENT
1325 .sp
1326 The status line can be overridden with the \fB\-\-term\-status\-msg\fP option.
1327 .sp
1328 The following is a list of things that can show up in the status line. Input
1329 properties, that can be used to get the same information manually, are also
1330 listed.
1331 .INDENT 0.0
1332 .IP \(bu 2
1333 \fBAV:\fP or \fBV:\fP (video only) or \fBA:\fP (audio only)
1334 .IP \(bu 2
1335 The current time position in \fBHH:MM:SS\fP format (\fBplayback\-time\fP property)
1336 .IP \(bu 2
1337 The total file duration (absent if unknown) (\fBduration\fP property)
1338 .IP \(bu 2
1339 Playback speed, e.g. \(ga\(ga x2.0\(ga\(ga. Only visible if the speed is not normal. This
1340 is the user\-requested speed, and not the actual speed (usually they should
1341 be the same, unless playback is too slow). (\fBspeed\fP property.)
1342 .IP \(bu 2
1343 Playback percentage, e.g. \fB(13%)\fP\&. How much of the file has been played.
1344 Normally calculated out of playback position and duration, but can fallback
1345 to other methods (like byte position) if these are not available.
1346 (\fBpercent\-pos\fP property.)
1347 .IP \(bu 2
1348 The audio/video sync as \fBA\-V: 0.000\fP\&. This is the difference between
1349 audio and video time. Normally it should be 0 or close to 0. If it\(aqs growing,
1350 it might indicate a playback problem. (\fBavsync\fP property.)
1351 .IP \(bu 2
1352 Total A/V sync change, e.g. \fBct: \-0.417\fP\&. Normally invisible. Can show up
1353 if there is audio "missing", or not enough frames can be dropped. Usually
1354 this will indicate a problem. (\fBtotal\-avsync\-change\fP property.)
1355 .IP \(bu 2
1356 Encoding state in \fB{...}\fP, only shown in encoding mode.
1357 .IP \(bu 2
1358 Display sync state. If display sync is active (\fBdisplay\-sync\-active\fP
1359 property), this shows \fBDS: 2.500/13\fP, where the first number is average
1360 number of vsyncs per video frame (e.g. 2.5 when playing 24Hz videos on 60Hz
1361 screens), which might jitter if the ratio doesn\(aqt round off, or there are
1362 mistimed frames (\fBvsync\-ratio\fP), and the second number of estimated number
1363 of vsyncs which took too long (\fBvo\-delayed\-frame\-count\fP property). The
1364 latter is a heuristic, as it\(aqs generally not possible to determine this with
1365 certainty.
1366 .IP \(bu 2
1367 Dropped frames, e.g. \fBDropped: 4\fP\&. Shows up only if the count is not 0. Can
1368 grow if the video framerate is higher than that of the display, or if video
1369 rendering is too slow. May also be incremented on "hiccups" and when the video
1370 frame couldn\(aqt be displayed on time. (\fBframe\-drop\-count\fP property.)
1371 If the decoder drops frames, the number of decoder\-dropped frames is appended
1372 to the display as well, e.g.: \fBDropped: 4/34\fP\&. This happens only if
1373 decoder frame dropping is enabled with the \fB\-\-framedrop\fP options.
1374 (\fBdecoder\-frame\-drop\-count\fP property.)
1375 .IP \(bu 2
1376 Cache state, e.g. \fBCache: 2s/134KB\fP\&. Visible if the stream cache is enabled.
1377 The first value shows the amount of video buffered in the demuxer in seconds,
1378 the second value shows the estimated size of the buffered amount in kilobytes.
1379 (\fBdemuxer\-cache\-duration\fP and \fBdemuxer\-cache\-state\fP properties.)
1380 .UNINDENT
1381 .SH LOW LATENCY PLAYBACK
1382 .sp
1383 mpv is optimized for normal video playback, meaning it actually tries to buffer
1384 as much data as it seems to make sense. This will increase latency. Reducing
1385 latency is possible only by specifically disabling features which increase
1386 latency.
1387 .sp
1388 The builtin \fBlow\-latency\fP profile tries to apply some of the options which can
1389 reduce latency. You can use \fB\-\-profile=low\-latency\fP to apply all of them. You
1390 can list the contents with \fB\-\-show\-profile=low\-latency\fP (some of the options
1391 are quite obscure, and may change every mpv release).
1392 .sp
1393 Be aware that some of the options can reduce playback quality.
1394 .sp
1395 Most latency is actually caused by inconvenient timing behavior. You can disable
1396 this with \fB\-\-untimed\fP, but it will likely break, unless the stream has no
1397 audio, and the input feeds data to the player at a constant rate.
1398 .sp
1399 Another common problem is with MJPEG streams. These do not signal the correct
1400 framerate. Using \fB\-\-untimed\fP or \fB\-\-no\-correct\-pts \-\-fps=60\fP might help.
1401 .sp
1402 For livestreams, data can build up due to pausing the stream, due to slightly
1403 lower playback rate, or "buffering" pauses. If the demuxer cache is enabled,
1404 these can be skipped manually. The experimental \fBdrop\-buffers\fP command can
1405 be used to discard any buffered data, though it\(aqs very disruptive.
1406 .sp
1407 In some cases, manually tuning TCP buffer sizes and such can help to reduce
1408 latency.
1409 .sp
1410 Additional options that can be tried:
1411 .INDENT 0.0
1412 .IP \(bu 2
1413 \fB\-\-opengl\-glfinish=yes\fP, can reduce buffering in the graphics driver
1414 .IP \(bu 2
1415 \fB\-\-opengl\-swapinterval=0\fP, same
1416 .IP \(bu 2
1417 \fB\-\-vo=xv\fP, same
1418 .IP \(bu 2
1419 without audio \fB\-\-framedrop=no \-\-speed=1.01\fP may help for live sources
1420 (results can be mixed)
1421 .UNINDENT
1422 .SH PROTOCOLS
1423 .sp
1424 \fBhttp://...\fP, \fBhttps://\fP, ...
1425 .INDENT 0.0
1426 .INDENT 3.5
1427 Many network protocols are supported, but the protocol prefix must always
1428 be specified. mpv will never attempt to guess whether a filename is
1429 actually a network address. A protocol prefix is always required.
1430 .sp
1431 Note that not all prefixes are documented here. Undocumented prefixes are
1432 either aliases to documented protocols, or are just redirections to
1433 protocols implemented and documented in FFmpeg.
1434 .sp
1435 \fBdata:\fP is supported in FFmpeg (not in Libav), but needs to be in the
1436 format \fBdata://\fP\&. This is done to avoid ambiguity with filenames. You
1437 can also prefix it with \fBlavf://\fP or \fBffmpeg://\fP\&.
1438 .UNINDENT
1439 .UNINDENT
1440 .sp
1441 \fBytdl://...\fP
1442 .INDENT 0.0
1443 .INDENT 3.5
1444 By default, the youtube\-dl hook script only looks at http(s) URLs. Prefixing
1445 an URL with \fBytdl://\fP forces it to be always processed by the script. This
1446 can also be used to invoke special youtube\-dl functionality like playing a
1447 video by ID or invoking search.
1448 .sp
1449 Keep in mind that you can\(aqt pass youtube\-dl command line options by this,
1450 and you have to use \fB\-\-ytdl\-raw\-options\fP instead.
1451 .UNINDENT
1452 .UNINDENT
1453 .sp
1454 \fB\-\fP
1455 .INDENT 0.0
1456 .INDENT 3.5
1457 Play data from stdin.
1458 .UNINDENT
1459 .UNINDENT
1460 .sp
1461 \fBsmb://PATH\fP
1462 .INDENT 0.0
1463 .INDENT 3.5
1464 Play a path from Samba share. (Requires FFmpeg support.)
1465 .UNINDENT
1466 .UNINDENT
1467 .sp
1468 \fBbd://[title][/device]\fP \fB\-\-bluray\-device=PATH\fP
1469 .INDENT 0.0
1470 .INDENT 3.5
1471 Play a Blu\-ray disc. Since libbluray 1.0.1, you can read from ISO files
1472 by passing them to \fB\-\-bluray\-device\fP\&.
1473 .sp
1474 \fBtitle\fP can be: \fBlongest\fP or \fBfirst\fP (selects the default
1475 playlist); \fBmpls/<number>\fP (selects <number>.mpls playlist);
1476 \fB<number>\fP (select playlist with the same index). mpv will list
1477 the available playlists on loading.
1478 .sp
1479 \fBbluray://\fP is an alias.
1480 .UNINDENT
1481 .UNINDENT
1482 .sp
1483 \fBdvd://[title][/device]\fP \fB\-\-dvd\-device=PATH\fP
1484 .INDENT 0.0
1485 .INDENT 3.5
1486 Play a DVD. DVD menus are not supported. If no title is given, the longest
1487 title is auto\-selected. Without \fB\-\-dvd\-device\fP, it will probably try
1488 to open an actual optical drive, if available and implemented for the OS.
1489 .sp
1490 \fBdvdnav://\fP is an old alias for \fBdvd://\fP and does exactly the same
1491 thing.
1492 .UNINDENT
1493 .UNINDENT
1494 .sp
1495 \fBdvb://[cardnumber@]channel\fP \fB\-\-dvbin\-...\fP
1496 .INDENT 0.0
1497 .INDENT 3.5
1498 Digital TV via DVB. (Linux only.)
1499 .UNINDENT
1500 .UNINDENT
1501 .sp
1502 \fBmf://[filemask|@listfile]\fP \fB\-\-mf\-...\fP
1503 .INDENT 0.0
1504 .INDENT 3.5
1505 Play a series of images as video.
1506 .UNINDENT
1507 .UNINDENT
1508 .sp
1509 \fBcdda://[device]\fP \fB\-\-cdrom\-device=PATH\fP \fB\-\-cdda\-...\fP
1510 .INDENT 0.0
1511 .INDENT 3.5
1512 Play CD.
1513 .UNINDENT
1514 .UNINDENT
1515 .sp
1516 \fBlavf://...\fP
1517 .INDENT 0.0
1518 .INDENT 3.5
1519 Access any FFmpeg/Libav libavformat protocol. Basically, this passed the
1520 string after the \fB//\fP directly to libavformat.
1521 .UNINDENT
1522 .UNINDENT
1523 .sp
1524 \fBav://type:options\fP
1525 .INDENT 0.0
1526 .INDENT 3.5
1527 This is intended for using libavdevice inputs. \fBtype\fP is the libavdevice
1528 demuxer name, and \fBoptions\fP is the (pseudo\-)filename passed to the
1529 demuxer.
1530 .INDENT 0.0
1531 .INDENT 3.5
1532 .IP "Example"
1533 .INDENT 0.0
1534 .INDENT 3.5
1535 .sp
1536 .nf
1537 .ft C
1538 mpv av://v4l2:/dev/video0 \-\-profile=low\-latency \-\-untimed
1539 .ft P
1540 .fi
1541 .UNINDENT
1542 .UNINDENT
1543 .sp
1544 This plays video from the first v4l input with nearly the lowest latency
1545 possible. It\(aqs a good replacement for the removed \fBtv://\fP input.
1546 Using \fB\-\-untimed\fP is a hack to output a captured frame immediately,
1547 instead of respecting the input framerate. (There may be better ways to
1548 handle this in the future.)
1549 .UNINDENT
1550 .UNINDENT
1551 .sp
1552 \fBavdevice://\fP is an alias.
1553 .UNINDENT
1554 .UNINDENT
1555 .sp
1556 \fBfile://PATH\fP
1557 .INDENT 0.0
1558 .INDENT 3.5
1559 A local path as URL. Might be useful in some special use\-cases. Note that
1560 \fBPATH\fP itself should start with a third \fB/\fP to make the path an
1561 absolute path.
1562 .UNINDENT
1563 .UNINDENT
1564 .sp
1565 \fBappending://PATH\fP
1566 .INDENT 0.0
1567 .INDENT 3.5
1568 Play a local file, but assume it\(aqs being appended to. This is useful for
1569 example for files that are currently being downloaded to disk. This will
1570 block playback, and stop playback only if no new data was appended after
1571 a timeout of about 2 seconds.
1572 .sp
1573 Using this is still a bit of a bad idea, because there is no way to detect
1574 if a file is actually being appended, or if it\(aqs still written. If you\(aqre
1575 trying to play the output of some program, consider using a pipe
1576 (\fBsomething | mpv \-\fP). If it really has to be a file on disk, use tail to
1577 make it wait forever, e.g. \fBtail \-f \-c +0 file.mkv | mpv \-\fP\&.
1578 .UNINDENT
1579 .UNINDENT
1580 .sp
1581 \fBfd://123\fP
1582 .INDENT 0.0
1583 .INDENT 3.5
1584 Read data from the given file descriptor (for example 123). This is similar
1585 to piping data to stdin via \fB\-\fP, but can use an arbitrary file descriptor.
1586 mpv may modify some file descriptor properties when the stream layer "opens"
1587 it.
1588 .UNINDENT
1589 .UNINDENT
1590 .sp
1591 \fBfdclose://123\fP
1592 .INDENT 0.0
1593 .INDENT 3.5
1594 Like \fBfd://\fP, but the file descriptor is closed after use. When using this
1595 you need to ensure that the same fd URL will only be used once.
1596 .UNINDENT
1597 .UNINDENT
1598 .sp
1599 \fBedl://[edl specification as in edl\-mpv.rst]\fP
1600 .INDENT 0.0
1601 .INDENT 3.5
1602 Stitch together parts of multiple files and play them.
1603 .UNINDENT
1604 .UNINDENT
1605 .sp
1606 \fBslice://start[\-end]@URL\fP
1607 .INDENT 0.0
1608 .INDENT 3.5
1609 Read a slice of a stream.
1610 .sp
1611 \fBstart\fP and \fBend\fP represent a byte range and accept
1612 suffixes such as \fBKiB\fP and \fBMiB\fP\&. \fBend\fP is optional.
1613 .sp
1614 if \fBend\fP starts with \fB+\fP, it is considered as offset from \fBstart\fP\&.
1615 .sp
1616 Only works with seekable streams.
1617 .sp
1618 Examples:
1619 .INDENT 0.0
1620 .INDENT 3.5
1621 .sp
1622 .nf
1623 .ft C
1624 mpv slice://1g\-2g@cap.ts
1625
1626 This starts reading from cap.ts after seeking 1 GiB, then
1627 reads until reaching 2 GiB or end of file.
1628
1629 mpv slice://1g\-+2g@cap.ts
1630
1631 This starts reading from cap.ts after seeking 1 GiB, then
1632 reads until reaching 3 GiB or end of file.
1633
1634 mpv slice://100m@appending://cap.ts
1635
1636 This starts reading from cap.ts after seeking 100MiB, then
1637 reads until end of file.
1638 .ft P
1639 .fi
1640 .UNINDENT
1641 .UNINDENT
1642 .UNINDENT
1643 .UNINDENT
1644 .sp
1645 \fBnull://\fP
1646 .INDENT 0.0
1647 .INDENT 3.5
1648 Simulate an empty file. If opened for writing, it will discard all data.
1649 The \fBnull\fP demuxer will specifically pass autoprobing if this protocol
1650 is used (while it\(aqs not automatically invoked for empty files).
1651 .UNINDENT
1652 .UNINDENT
1653 .sp
1654 \fBmemory://data\fP
1655 .INDENT 0.0
1656 .INDENT 3.5
1657 Use the \fBdata\fP part as source data.
1658 .UNINDENT
1659 .UNINDENT
1660 .sp
1661 \fBhex://data\fP
1662 .INDENT 0.0
1663 .INDENT 3.5
1664 Like \fBmemory://\fP, but the string is interpreted as hexdump.
1665 .UNINDENT
1666 .UNINDENT
1667 .SH PSEUDO GUI MODE
1668 .sp
1669 mpv has no official GUI, other than the OSC (\fI\%ON SCREEN CONTROLLER\fP), which
1670 is not a full GUI and is not meant to be. However, to compensate for the lack
1671 of expected GUI behavior, mpv will in some cases start with some settings
1672 changed to behave slightly more like a GUI mode.
1673 .sp
1674 Currently this happens only in the following cases:
1675 .INDENT 0.0
1676 .IP \(bu 2
1677 if started using the \fBmpv.desktop\fP file on Linux (e.g. started from menus
1678 or file associations provided by desktop environments)
1679 .IP \(bu 2
1680 if started from explorer.exe on Windows (technically, if it was started on
1681 Windows, and all of the stdout/stderr/stdin handles are unset)
1682 .IP \(bu 2
1683 started out of the bundle on OSX
1684 .IP \(bu 2
1685 if you manually use \fB\-\-player\-operation\-mode=pseudo\-gui\fP on the command line
1686 .UNINDENT
1687 .sp
1688 This mode applies options from the builtin profile \fBbuiltin\-pseudo\-gui\fP, but
1689 only if these haven\(aqt been set in the user\(aqs config file or on the command line,
1690 which is the main difference to using \fB\-\-profile=builtin\-pseudo\-gui\fP\&.
1691 .sp
1692 The profile is currently defined as follows:
1693 .INDENT 0.0
1694 .INDENT 3.5
1695 .sp
1696 .nf
1697 .ft C
1698 [builtin\-pseudo\-gui]
1699 terminal=no
1700 force\-window=yes
1701 idle=once
1702 screenshot\-directory=~~desktop/
1703 .ft P
1704 .fi
1705 .UNINDENT
1706 .UNINDENT
1707 .sp
1708 The \fBpseudo\-gui\fP profile exists for compatibility. The options in the
1709 \fBpseudo\-gui\fP profile are applied unconditionally. In addition, the profile
1710 makes sure to enable the pseudo\-GUI mode, so that \fB\-\-profile=pseudo\-gui\fP
1711 works like in older mpv releases:
1712 .INDENT 0.0
1713 .INDENT 3.5
1714 .sp
1715 .nf
1716 .ft C
1717 [pseudo\-gui]
1718 player\-operation\-mode=pseudo\-gui
1719 .ft P
1720 .fi
1721 .UNINDENT
1722 .UNINDENT
1723 .sp
1724 \fBWARNING:\fP
1725 .INDENT 0.0
1726 .INDENT 3.5
1727 Currently, you can extend the \fBpseudo\-gui\fP profile in the config file the
1728 normal way. This is deprecated. In future mpv releases, the behavior might
1729 change, and not apply your additional settings, and/or use a different
1730 profile name.
1731 .UNINDENT
1732 .UNINDENT
1733 .SH LINUX DESKTOP ISSUES
1734 .sp
1735 This subsection describes common problems on the Linux desktop. None of these
1736 problems exist on systems like Windows or OSX.
1737 .SS Disabling Screensaver
1738 .sp
1739 By default, mpv tries to disable the OS screensaver during playback (only if
1740 a VO using the OS GUI API is active). \fB\-\-stop\-screensaver=no\fP disables this.
1741 .sp
1742 A common problem is that Linux desktop environments ignore the standard
1743 screensaver APIs on which mpv relies. In particular, mpv uses the Screen Saver
1744 extension (XSS) on X11, and the idle\-inhibit on Wayland.
1745 .sp
1746 GNOME is one of the worst offenders, and ignores even the now widely supported
1747 idle\-inhibit protocol. (This is either due to a combination of malice and
1748 incompetence, but since implementing this protocol would only take a few lines
1749 of code, it is most likely the former. You will also notice how GNOME advocates
1750 react offended whenever their sabotage is pointed out, which indicates either
1751 hypocrisy, or even worse ignorance.)
1752 .sp
1753 Such incompatible desktop environments (i.e. which ignore standards) typically
1754 require using a DBus API. This is ridiculous in several ways. The immediate
1755 practical problem is that it would require adding a quite unwieldy dependency
1756 for a DBus library, somehow integrating its mainloop into mpv, and other
1757 generally unacceptable things.
1758 .sp
1759 However, since mpv does not officially support GNOME, this is not much of a
1760 problem. If you are one of those miserable users who want to use mpv on GNOME,
1761 report a bug on the GNOME issue tracker:
1762 \fI\%https://gitlab.gnome.org/groups/GNOME/\-/issues\fP
1763 .sp
1764 Alternatively, you may be able to write a Lua script that calls the
1765 \fBxdg\-screensaver\fP command line program. (By the way, this a command line
1766 program is an utterly horrible kludge that tries to identify your DE, and then
1767 tries to send the correct DBus command via a DBus CLI tool.) If you find the
1768 idea of having to write a script just so your screensaver doesn\(aqt kick in
1769 ridiculous, do not use GNOME, or use GNOME video software instead of mpv (good
1770 luck).
1771 .sp
1772 Before mpv 0.33.0, the X11 backend ran \fBxdg\-screensaver reset\fP in 10 second
1773 intervals when not paused. This hack was removed in 0.33.0.
1774 .SH OPTIONS
1775 .SS Track Selection
1776 .INDENT 0.0
1777 .TP
1778 .B \fB\-\-alang=<languagecode[,languagecode,...]>\fP
1779 Specify a priority list of audio languages to use. Different container
1780 formats employ different language codes. DVDs use ISO 639\-1 two\-letter
1781 language codes, Matroska, MPEG\-TS and NUT use ISO 639\-2 three\-letter
1782 language codes, while OGM uses a free\-form identifier. See also \fB\-\-aid\fP\&.
1783 .sp
1784 This is a string list option. See \fI\%List Options\fP for details.
1785 .INDENT 7.0
1786 .INDENT 3.5
1787 .IP "Examples"
1788 .INDENT 0.0
1789 .IP \(bu 2
1790 \fBmpv dvd://1 \-\-alang=hu,en\fP chooses the Hungarian language track
1791 on a DVD and falls back on English if Hungarian is not available.
1792 .IP \(bu 2
1793 \fBmpv \-\-alang=jpn example.mkv\fP plays a Matroska file with Japanese
1794 audio.
1795 .UNINDENT
1796 .UNINDENT
1797 .UNINDENT
1798 .TP
1799 .B \fB\-\-slang=<languagecode[,languagecode,...]>\fP
1800 Specify a priority list of subtitle languages to use. Different container
1801 formats employ different language codes. DVDs use ISO 639\-1 two letter
1802 language codes, Matroska uses ISO 639\-2 three letter language codes while
1803 OGM uses a free\-form identifier. See also \fB\-\-sid\fP\&.
1804 .sp
1805 This is a string list option. See \fI\%List Options\fP for details.
1806 .INDENT 7.0
1807 .INDENT 3.5
1808 .IP "Examples"
1809 .INDENT 0.0
1810 .IP \(bu 2
1811 \fBmpv dvd://1 \-\-slang=hu,en\fP chooses the Hungarian subtitle track on
1812 a DVD and falls back on English if Hungarian is not available.
1813 .IP \(bu 2
1814 \fBmpv \-\-slang=jpn example.mkv\fP plays a Matroska file with Japanese
1815 subtitles.
1816 .UNINDENT
1817 .UNINDENT
1818 .UNINDENT
1819 .TP
1820 .B \fB\-\-vlang=<...>\fP
1821 Equivalent to \fB\-\-alang\fP and \fB\-\-slang\fP, for video tracks.
1822 .sp
1823 This is a string list option. See \fI\%List Options\fP for details.
1824 .TP
1825 .B \fB\-\-aid=<ID|auto|no>\fP
1826 Select audio track. \fBauto\fP selects the default, \fBno\fP disables audio.
1827 See also \fB\-\-alang\fP\&. mpv normally prints available audio tracks on the
1828 terminal when starting playback of a file.
1829 .sp
1830 \fB\-\-audio\fP is an alias for \fB\-\-aid\fP\&.
1831 .sp
1832 \fB\-\-aid=no\fP or \fB\-\-audio=no\fP or \fB\-\-no\-audio\fP disables audio playback.
1833 (The latter variant does not work with the client API.)
1834 .sp
1835 \fBNOTE:\fP
1836 .INDENT 7.0
1837 .INDENT 3.5
1838 The track selection options (\fB\-\-aid\fP but also \fB\-\-sid\fP and the
1839 others) sometimes expose behavior that may appear strange. Also, the
1840 behavior tends to change around with each mpv release.
1841 .sp
1842 The track selection properties will return the option value outside of
1843 playback (as expected), but during playbac, the affective track
1844 selection is returned. For example, with \fB\-\-aid=auto\fP, the \fBaid\fP
1845 property will suddenly return \fB2\fP after playback initialization
1846 (assuming the file has at least 2 audio tracks, and the second is the
1847 default).
1848 .sp
1849 At mpv 0.32.0 (and some releases before), if you passed a track value
1850 for which a corresponding track didn\(aqt exist (e.g. \fB\-\-aid=2\fP and there
1851 was only 1 audio track), the \fBaid\fP property returned \fBno\fP\&. However if
1852 another audio track was added during playback, and you tried to set the
1853 \fBaid\fP property to \fB2\fP, nothing happened, because the \fBaid\fP option
1854 still had the value \fB2\fP, and writing the same value has no effect.
1855 .sp
1856 With mpv 0.33.0, the behavior was changed. Now track selection options
1857 are reset to \fBauto\fP at playback initialization, if the option had
1858 tries to select a track that does not exist. The same is done if the
1859 track exists, but fails to initialize. The consequence is that unlike
1860 before mpv 0.33.0, the user\(aqs track selection parameters are clobbered
1861 in certain situations.
1862 .sp
1863 Also since mpv 0.33.0, trying to select a track by number will strictly
1864 select this track. Before this change, trying to select a track which
1865 did not exist would fall back to track default selection at playback
1866 initialization. The new behavior is more consistent.
1867 .sp
1868 Setting a track selection property at runtime, and then playing a new
1869 file might reset the track selection to defaults, if the fingerprint
1870 of the track list of the new file is different.
1871 .sp
1872 Be aware of tricky combinations of all of all of the above: for example,
1873 \fBmpv \-\-aid=2 file_with_2_audio_tracks.mkv file_with_1_audio_track.mkv\fP
1874 would first play the correct track, and the second file without audio.
1875 If you then go back the first file, its first audio track will be played,
1876 and the second file is played with audio. If you do the same thing again
1877 but instead of using \fB\-\-aid=2\fP you run \fBset aid 2\fP while the file is
1878 playing, then changing to the second file will play its audio track.
1879 This is because runtime selection enables the fingerprint heuristic.
1880 .sp
1881 Most likely this is not the end.
1882 .UNINDENT
1883 .UNINDENT
1884 .TP
1885 .B \fB\-\-sid=<ID|auto|no>\fP
1886 Display the subtitle stream specified by \fB<ID>\fP\&. \fBauto\fP selects
1887 the default, \fBno\fP disables subtitles.
1888 .sp
1889 \fB\-\-sub\fP is an alias for \fB\-\-sid\fP\&.
1890 .sp
1891 \fB\-\-sid=no\fP or \fB\-\-sub=no\fP or \fB\-\-no\-sub\fP disables subtitle decoding.
1892 (The latter variant does not work with the client API.)
1893 .TP
1894 .B \fB\-\-vid=<ID|auto|no>\fP
1895 Select video channel. \fBauto\fP selects the default, \fBno\fP disables video.
1896 .sp
1897 \fB\-\-video\fP is an alias for \fB\-\-vid\fP\&.
1898 .sp
1899 \fB\-\-vid=no\fP or \fB\-\-video=no\fP or \fB\-\-no\-video\fP disables video playback.
1900 (The latter variant does not work with the client API.)
1901 .sp
1902 If video is disabled, mpv will try to download the audio only if media is
1903 streamed with youtube\-dl, because it saves bandwidth. This is done by
1904 setting the ytdl_format to "bestaudio/best" in the ytdl_hook.lua script.
1905 .TP
1906 .B \fB\-\-edition=<ID|auto>\fP
1907 (Matroska files only)
1908 Specify the edition (set of chapters) to use, where 0 is the first. If set
1909 to \fBauto\fP (the default), mpv will choose the first edition declared as a
1910 default, or if there is no default, the first edition defined.
1911 .TP
1912 .B \fB\-\-track\-auto\-selection=<yes|no>\fP
1913 Enable the default track auto\-selection (default: yes). Enabling this will
1914 make the player select streams according to \fB\-\-aid\fP, \fB\-\-alang\fP, and
1915 others. If it is disabled, no tracks are selected. In addition, the player
1916 will not exit if no tracks are selected, and wait instead (this wait mode
1917 is similar to pausing, but the pause option is not set).
1918 .sp
1919 This is useful with \fB\-\-lavfi\-complex\fP: you can start playback in this
1920 mode, and then set select tracks at runtime by setting the filter graph.
1921 Note that if \fB\-\-lavfi\-complex\fP is set before playback is started, the
1922 referenced tracks are always selected.
1923 .TP
1924 .B \fB\-\-subs\-with\-matching\-audio=<yes|no>\fP
1925 When autoselecting a subtitle track, select a non\-forced one even if the selected
1926 audio stream matches your preferred subtitle language (default: yes). Disable this
1927 if you\(aqd like to only show subtitles for foreign audio or onscreen text.
1928 .UNINDENT
1929 .SS Playback Control
1930 .INDENT 0.0
1931 .TP
1932 .B \fB\-\-start=<relative time>\fP
1933 Seek to given time position.
1934 .sp
1935 The general format for times is \fB[+|\-][[hh:]mm:]ss[.ms]\fP\&. If the time is
1936 prefixed with \fB\-\fP, the time is considered relative from the end of the
1937 file (as signaled by the demuxer/the file). A \fB+\fP is usually ignored (but
1938 see below).
1939 .sp
1940 The following alternative time specifications are recognized:
1941 .sp
1942 \fBpp%\fP seeks to percent position pp (0\-100).
1943 .sp
1944 \fB#c\fP seeks to chapter number c. (Chapters start from 1.)
1945 .sp
1946 \fBnone\fP resets any previously set option (useful for libmpv).
1947 .sp
1948 If \fB\-\-rebase\-start\-time=no\fP is given, then prefixing times with \fB+\fP
1949 makes the time relative to the start of the file. A timestamp without
1950 prefix is considered an absolute time, i.e. should seek to a frame with a
1951 timestamp as the file contains it. As a bug, but also a hidden feature,
1952 putting 1 or more spaces before the \fB+\fP or \fB\-\fP always interprets the
1953 time as absolute, which can be used to seek to negative timestamps (useful
1954 for debugging at most).
1955 .INDENT 7.0
1956 .INDENT 3.5
1957 .IP "Examples"
1958 .INDENT 0.0
1959 .TP
1960 .B \fB\-\-start=+56\fP, \fB\-\-start=00:56\fP
1961 Seeks to the start time + 56 seconds.
1962 .TP
1963 .B \fB\-\-start=\-56\fP, \fB\-\-start=\-00:56\fP
1964 Seeks to the end time \- 56 seconds.
1965 .TP
1966 .B \fB\-\-start=01:10:00\fP
1967 Seeks to 1 hour 10 min.
1968 .TP
1969 .B \fB\-\-start=50%\fP
1970 Seeks to the middle of the file.
1971 .TP
1972 .B \fB\-\-start=30 \-\-end=40\fP
1973 Seeks to 30 seconds, plays 10 seconds, and exits.
1974 .TP
1975 .B \fB\-\-start=\-3:20 \-\-length=10\fP
1976 Seeks to 3 minutes and 20 seconds before the end of the file, plays
1977 10 seconds, and exits.
1978 .TP
1979 .B \fB\-\-start=\(aq#2\(aq \-\-end=\(aq#4\(aq\fP
1980 Plays chapters 2 and 3, and exits.
1981 .UNINDENT
1982 .UNINDENT
1983 .UNINDENT
1984 .TP
1985 .B \fB\-\-end=<relative time>\fP
1986 Stop at given time. Use \fB\-\-length\fP if the time should be relative
1987 to \fB\-\-start\fP\&. See \fB\-\-start\fP for valid option values and examples.
1988 .TP
1989 .B \fB\-\-length=<relative time>\fP
1990 Stop after a given time relative to the start time.
1991 See \fB\-\-start\fP for valid option values and examples.
1992 .sp
1993 If both \fB\-\-end\fP and \fB\-\-length\fP are provided, playback will stop when it
1994 reaches either of the two endpoints.
1995 .sp
1996 Obscurity note: this does not work correctly if \fB\-\-rebase\-start\-time=no\fP,
1997 and the specified time is not an "absolute" time, as defined in the
1998 \fB\-\-start\fP option description.
1999 .TP
2000 .B \fB\-\-rebase\-start\-time=<yes|no>\fP
2001 Whether to move the file start time to \fB00:00:00\fP (default: yes). This
2002 is less awkward for files which start at a random timestamp, such as
2003 transport streams. On the other hand, if there are timestamp resets, the
2004 resulting behavior can be rather weird. For this reason, and in case you
2005 are actually interested in the real timestamps, this behavior can be
2006 disabled with \fBno\fP\&.
2007 .TP
2008 .B \fB\-\-speed=<0.01\-100>\fP
2009 Slow down or speed up playback by the factor given as parameter.
2010 .sp
2011 If \fB\-\-audio\-pitch\-correction\fP (on by default) is used, playing with a
2012 speed higher than normal automatically inserts the \fBscaletempo\fP audio
2013 filter.
2014 .TP
2015 .B \fB\-\-pause\fP
2016 Start the player in paused state.
2017 .TP
2018 .B \fB\-\-shuffle\fP
2019 Play files in random order.
2020 .TP
2021 .B \fB\-\-playlist\-start=<auto|index>\fP
2022 Set which file on the internal playlist to start playback with. The index
2023 is an integer, with 0 meaning the first file. The value \fBauto\fP means that
2024 the selection of the entry to play is left to the playback resume mechanism
2025 (default). If an entry with the given index doesn\(aqt exist, the behavior is
2026 unspecified and might change in future mpv versions. The same applies if
2027 the playlist contains further playlists (don\(aqt expect any reasonable
2028 behavior). Passing a playlist file to mpv should work with this option,
2029 though. E.g. \fBmpv playlist.m3u \-\-playlist\-start=123\fP will work as expected,
2030 as long as \fBplaylist.m3u\fP does not link to further playlists.
2031 .sp
2032 The value \fBno\fP is a deprecated alias for \fBauto\fP\&.
2033 .TP
2034 .B \fB\-\-playlist=<filename>\fP
2035 Play files according to a playlist file. Supports some common formats. If
2036 no format is detected, it will be treated as list of files, separated by
2037 newline characters. You may need this option to load plaintext files as
2038 a playlist. Note that XML playlist formats are not supported.
2039 .sp
2040 This option forces \fB\-\-demuxer=playlist\fP to interpret the playlist file.
2041 Some playlist formats, notably CUE and optical disc formats, need to use
2042 different demuxers and will not work with this option. They still can be
2043 played directly, without using this option.
2044 .sp
2045 You can play playlists directly, without this option. Before mpv version
2046 0.31.0, this option disabled any security mechanisms that might be in
2047 place, but since 0.31.0 it uses the same security mechanisms as playing a
2048 playlist file directly. If you trust the playlist file, you can disable
2049 any security checks with \fB\-\-load\-unsafe\-playlists\fP\&. Because playlists
2050 can load other playlist entries, consider applying this option only to the
2051 playlist itself and not its entries, using something along these lines:
2052 .INDENT 7.0
2053 .INDENT 3.5
2054 \fBmpv \-\-{ \-\-playlist=filename \-\-load\-unsafe\-playlists \-\-}\fP
2055 .UNINDENT
2056 .UNINDENT
2057 .sp
2058 \fBWARNING:\fP
2059 .INDENT 7.0
2060 .INDENT 3.5
2061 The way older versions of mpv played playlist files via \fB\-\-playlist\fP
2062 was not safe against maliciously constructed files. Such files may
2063 trigger harmful actions. This has been the case for all verions of
2064 mpv prior to 0.31.0, and all MPlayer versions, but unfortunately this
2065 fact was not well documented earlier, and some people have even
2066 misguidedly recommended the use of \fB\-\-playlist\fP with untrusted
2067 sources. Do NOT use \fB\-\-playlist\fP with random internet sources or
2068 files you do not trust if you are not sure your mpv is at least 0.31.0.
2069 .sp
2070 In particular, playlists can contain entries using protocols other than
2071 local files, such as special protocols like \fBavdevice://\fP (which are
2072 inherently unsafe).
2073 .UNINDENT
2074 .UNINDENT
2075 .TP
2076 .B \fB\-\-chapter\-merge\-threshold=<number>\fP
2077 Threshold for merging almost consecutive ordered chapter parts in
2078 milliseconds (default: 100). Some Matroska files with ordered chapters
2079 have inaccurate chapter end timestamps, causing a small gap between the
2080 end of one chapter and the start of the next one when they should match.
2081 If the end of one playback part is less than the given threshold away from
2082 the start of the next one then keep playing video normally over the
2083 chapter change instead of doing a seek.
2084 .TP
2085 .B \fB\-\-chapter\-seek\-threshold=<seconds>\fP
2086 Distance in seconds from the beginning of a chapter within which a backward
2087 chapter seek will go to the previous chapter (default: 5.0). Past this
2088 threshold, a backward chapter seek will go to the beginning of the current
2089 chapter instead. A negative value means always go back to the previous
2090 chapter.
2091 .TP
2092 .B \fB\-\-hr\-seek=<no|absolute|yes|default>\fP
2093 Select when to use precise seeks that are not limited to keyframes. Such
2094 seeks require decoding video from the previous keyframe up to the target
2095 position and so can take some time depending on decoding performance. For
2096 some video formats, precise seeks are disabled. This option selects the
2097 default choice to use for seeks; it is possible to explicitly override that
2098 default in the definition of key bindings and in input commands.
2099 .INDENT 7.0
2100 .TP
2101 .B no
2102 Never use precise seeks.
2103 .TP
2104 .B absolute
2105 Use precise seeks if the seek is to an absolute position in the
2106 file, such as a chapter seek, but not for relative seeks like
2107 the default behavior of arrow keys (default).
2108 .TP
2109 .B default
2110 Like \fBabsolute\fP, but enable hr\-seeks in audio\-only cases. The
2111 exact behavior is implementation specific and may change with
2112 new releases.
2113 .TP
2114 .B yes
2115 Use precise seeks whenever possible.
2116 .TP
2117 .B always
2118 Same as \fByes\fP (for compatibility).
2119 .UNINDENT
2120 .TP
2121 .B \fB\-\-hr\-seek\-demuxer\-offset=<seconds>\fP
2122 This option exists to work around failures to do precise seeks (as in
2123 \fB\-\-hr\-seek\fP) caused by bugs or limitations in the demuxers for some file
2124 formats. Some demuxers fail to seek to a keyframe before the given target
2125 position, going to a later position instead. The value of this option is
2126 subtracted from the time stamp given to the demuxer. Thus, if you set this
2127 option to 1.5 and try to do a precise seek to 60 seconds, the demuxer is
2128 told to seek to time 58.5, which hopefully reduces the chance that it
2129 erroneously goes to some time later than 60 seconds. The downside of
2130 setting this option is that precise seeks become slower, as video between
2131 the earlier demuxer position and the real target may be unnecessarily
2132 decoded.
2133 .TP
2134 .B \fB\-\-hr\-seek\-framedrop=<yes|no>\fP
2135 Allow the video decoder to drop frames during seek, if these frames are
2136 before the seek target. If this is enabled, precise seeking can be faster,
2137 but if you\(aqre using video filters which modify timestamps or add new
2138 frames, it can lead to precise seeking skipping the target frame. This
2139 e.g. can break frame backstepping when deinterlacing is enabled.
2140 .sp
2141 Default: \fByes\fP
2142 .TP
2143 .B \fB\-\-index=<mode>\fP
2144 Controls how to seek in files. Note that if the index is missing from a
2145 file, it will be built on the fly by default, so you don\(aqt need to change
2146 this. But it might help with some broken files.
2147 .INDENT 7.0
2148 .TP
2149 .B default
2150 use an index if the file has one, or build it if missing
2151 .TP
2152 .B recreate
2153 don\(aqt read or use the file\(aqs index
2154 .UNINDENT
2155 .sp
2156 \fBNOTE:\fP
2157 .INDENT 7.0
2158 .INDENT 3.5
2159 This option only works if the underlying media supports seeking
2160 (i.e. not with stdin, pipe, etc).
2161 .UNINDENT
2162 .UNINDENT
2163 .TP
2164 .B \fB\-\-load\-unsafe\-playlists\fP
2165 Load URLs from playlists which are considered unsafe (default: no). This
2166 includes special protocols and anything that doesn\(aqt refer to normal files.
2167 Local files and HTTP links on the other hand are always considered safe.
2168 .sp
2169 In addition, if a playlist is loaded while this is set, the added playlist
2170 entries are not marked as originating from network or potentially unsafe
2171 location. (Instead, the behavior is as if the playlist entries were provided
2172 directly to mpv command line or \fBloadfile\fP command.)
2173 .TP
2174 .B \fB\-\-access\-references=<yes|no>\fP
2175 Follow any references in the file being opened (default: yes). Disabling
2176 this is helpful if the file is automatically scanned (e.g. thumbnail
2177 generation). If the thumbnail scanner for example encounters a playlist
2178 file, which contains network URLs, and the scanner should not open these,
2179 enabling this option will prevent it. This option also disables ordered
2180 chapters, mov reference files, opening of archives, and a number of other
2181 features.
2182 .sp
2183 On older FFmpeg versions, this will not work in some cases. Some FFmpeg
2184 demuxers might not respect this option.
2185 .sp
2186 This option does not prevent opening of paired subtitle files and such. Use
2187 \fB\-\-autoload\-files=no\fP to prevent this.
2188 .sp
2189 This option does not always work if you open non\-files (for example using
2190 \fBdvd://directory\fP would open a whole bunch of files in the given
2191 directory). Prefixing the filename with \fB\&./\fP if it doesn\(aqt start with
2192 a \fB/\fP will avoid this.
2193 .TP
2194 .B \fB\-\-loop\-playlist=<N|inf|force|no>\fP, \fB\-\-loop\-playlist\fP
2195 Loops playback \fBN\fP times. A value of \fB1\fP plays it one time (default),
2196 \fB2\fP two times, etc. \fBinf\fP means forever. \fBno\fP is the same as \fB1\fP and
2197 disables looping. If several files are specified on command line, the
2198 entire playlist is looped. \fB\-\-loop\-playlist\fP is the same as
2199 \fB\-\-loop\-playlist=inf\fP\&.
2200 .sp
2201 The \fBforce\fP mode is like \fBinf\fP, but does not skip playlist entries
2202 which have been marked as failing. This means the player might waste CPU
2203 time trying to loop a file that doesn\(aqt exist. But it might be useful for
2204 playing webradios under very bad network conditions.
2205 .TP
2206 .B \fB\-\-loop\-file=<N|inf|no>\fP, \fB\-\-loop=<N|inf|no>\fP
2207 Loop a single file N times. \fBinf\fP means forever, \fBno\fP means normal
2208 playback. For compatibility, \fB\-\-loop\-file\fP and \fB\-\-loop\-file=yes\fP are
2209 also accepted, and are the same as \fB\-\-loop\-file=inf\fP\&.
2210 .sp
2211 The difference to \fB\-\-loop\-playlist\fP is that this doesn\(aqt loop the playlist,
2212 just the file itself. If the playlist contains only a single file, the
2213 difference between the two option is that this option performs a seek on
2214 loop, instead of reloading the file.
2215 .sp
2216 \fB\-\-loop\fP is an alias for this option.
2217 .TP
2218 .B \fB\-\-ab\-loop\-a=<time>\fP, \fB\-\-ab\-loop\-b=<time>\fP
2219 Set loop points. If playback passes the \fBb\fP timestamp, it will seek to
2220 the \fBa\fP timestamp. Seeking past the \fBb\fP point doesn\(aqt loop (this is
2221 intentional).
2222 .sp
2223 If \fBa\fP is after \fBb\fP, the behavior is as if the points were given in
2224 the right order, and the player will seek to \fBb\fP after crossing through
2225 \fBa\fP\&. This is different from old behavior, where looping was disabled (and
2226 as a bug, looped back to \fBa\fP on the end of the file).
2227 .sp
2228 If either options are set to \fBno\fP (or unset), looping is disabled. This
2229 is different from old behavior, where an unset \fBa\fP implied the start of
2230 the file, and an unset \fBb\fP the end of the file.
2231 .sp
2232 The loop\-points can be adjusted at runtime with the corresponding
2233 properties. See also \fBab\-loop\fP command.
2234 .TP
2235 .B \fB\-\-ab\-loop\-count=<N|inf>\fP
2236 Run A\-B loops only N times, then ignore the A\-B loop points (default: inf).
2237 Every finished loop iteration will decrement this option by 1 (unless it is
2238 set to \fBinf\fP or 0). \fBinf\fP means that looping goes on forever. If this
2239 option is set to 0, A\-B looping is ignored, and even the \fBab\-loop\fP command
2240 will not enable looping again (the command will show \fB(disabled)\fP on the
2241 OSD message if both loop points are set, but \fBab\-loop\-count\fP is 0).
2242 .TP
2243 .B \fB\-\-ordered\-chapters\fP, \fB\-\-no\-ordered\-chapters\fP
2244 Enabled by default.
2245 Disable support for Matroska ordered chapters. mpv will not load or
2246 search for video segments from other files, and will also ignore any
2247 chapter order specified for the main file.
2248 .TP
2249 .B \fB\-\-ordered\-chapters\-files=<playlist\-file>\fP
2250 Loads the given file as playlist, and tries to use the files contained in
2251 it as reference files when opening a Matroska file that uses ordered
2252 chapters. This overrides the normal mechanism for loading referenced
2253 files by scanning the same directory the main file is located in.
2254 .sp
2255 Useful for loading ordered chapter files that are not located on the local
2256 filesystem, or if the referenced files are in different directories.
2257 .sp
2258 Note: a playlist can be as simple as a text file containing filenames
2259 separated by newlines.
2260 .TP
2261 .B \fB\-\-chapters\-file=<filename>\fP
2262 Load chapters from this file, instead of using the chapter metadata found
2263 in the main file.
2264 .sp
2265 This accepts a media file (like mkv) or even a pseudo\-format like ffmetadata
2266 and uses its chapters to replace the current file\(aqs chapters. This doesn\(aqt
2267 work with OGM or XML chapters directly.
2268 .TP
2269 .B \fB\-\-sstep=<sec>\fP
2270 Skip <sec> seconds after every frame.
2271 .sp
2272 \fBNOTE:\fP
2273 .INDENT 7.0
2274 .INDENT 3.5
2275 Without \fB\-\-hr\-seek\fP, skipping will snap to keyframes.
2276 .UNINDENT
2277 .UNINDENT
2278 .TP
2279 .B \fB\-\-stop\-playback\-on\-init\-failure=<yes|no>\fP
2280 Stop playback if either audio or video fails to initialize (default: no).
2281 With \fBno\fP, playback will continue in video\-only or audio\-only mode if one
2282 of them fails. This doesn\(aqt affect playback of audio\-only or video\-only
2283 files.
2284 .TP
2285 .B \fB\-\-play\-dir=<forward|+|backward|\->\fP
2286 Control the playback direction (default: forward). Setting \fBbackward\fP
2287 will attempt to play the file in reverse direction, with decreasing
2288 playback time. If this is set on playback starts, playback will start from
2289 the end of the file. If this is changed at during playback, a hr\-seek will
2290 be issued to change the direction.
2291 .sp
2292 \fB+\fP and \fB\-\fP are aliases for \fBforward\fP and \fBbackward\fP\&.
2293 .sp
2294 The rest of this option description pertains to the \fBbackward\fP mode.
2295 .sp
2296 \fBNOTE:\fP
2297 .INDENT 7.0
2298 .INDENT 3.5
2299 Backward playback is extremely fragile. It may not always work, is much
2300 slower than forward playback, and breaks certain other features. How
2301 well it works depends mainly on the file being played. Generally, it
2302 will show good results (or results at all) only if the stars align.
2303 .UNINDENT
2304 .UNINDENT
2305 .sp
2306 mpv, as well as most media formats, were designed for forward playback
2307 only. Backward playback is bolted on top of mpv, and tries to make a medium
2308 effort to make backward playback work. Depending on your use\-case, another
2309 tool may work much better.
2310 .sp
2311 Backward playback is not exactly a 1st class feature. Implementation
2312 tradeoffs were made, that are bad for backward playback, but in turn do not
2313 cause disadvantages for normal playback. Various possible optimizations are
2314 not implemented in order to keep the complexity down. Normally, a media
2315 player is highly pipelined (future data is prepared in separate threads, so
2316 it is available in realtime when the next stage needs it), but backward
2317 playback will essentially stall the pipeline at various random points.
2318 .sp
2319 For example, for intra\-only codecs are trivially backward playable, and
2320 tools built around them may make efficient use of them (consider video
2321 editors or camera viewers). mpv won\(aqt be efficient in this case, because it
2322 uses its generic backward playback algorithm, that on top of it is not very
2323 optimized.
2324 .sp
2325 If you just want to quickly go backward through the video and just show
2326 "keyframes", just use forward playback, and hold down the left cursor key
2327 (which on CLI with default config sends many small relative seek commands).
2328 .sp
2329 The implementation consists of mostly 3 parts:
2330 .INDENT 7.0
2331 .IP \(bu 2
2332 Backward demuxing. This relies on the demuxer cache, so the demuxer cache
2333 should (or must, didn\(aqt test it) be enabled, and its size will affect
2334 performance. If the cache is too small or too large, quadratic runtime
2335 behavior may result.
2336 .IP \(bu 2
2337 Backward decoding. The decoder library used (libavcodec) does not support
2338 this. It is emulated by feeding bits of data in forward, putting the
2339 result in a queue, returning the queue data to the VO in reverse, and
2340 then starting over at an earlier position. This can require buffering an
2341 extreme amount of decoded data, and also completely breaks pipelining.
2342 .IP \(bu 2
2343 Backward output. This is relatively simple, because the decoder returns
2344 the frames in the needed order. However, this may cause various problems
2345 because filters see audio and video going backward.
2346 .UNINDENT
2347 .sp
2348 Known problems:
2349 .INDENT 7.0
2350 .IP \(bu 2
2351 It\(aqs fragile. If anything doesn\(aqt work, random non\-useful behavior may
2352 occur. In simple cases, the player will just play nonsense and artifacts.
2353 In other cases, it may get stuck or heat the CPU. (Exceeding memory usage
2354 significantly beyond the user\-set limits would be a bug, though.)
2355 .IP \(bu 2
2356 Performance and resource usage isn\(aqt good. In part this is inherent to
2357 backward playback of normal media formats, and in parts due to
2358 implementation choices and tradeoffs.
2359 .IP \(bu 2
2360 This is extremely reliant on good demuxer behavior. Although backward
2361 demuxing requires no special demuxer support, it is required that the
2362 demuxer performs seeks reliably, fulfills some specific requirements
2363 about packet metadata, and has deterministic behavior.
2364 .IP \(bu 2
2365 Starting playback exactly from the end may or may not work, depending on
2366 seeking behavior and file duration detection.
2367 .IP \(bu 2
2368 Some container formats, audio, and video codecs are not supported due to
2369 their behavior. There is no list, and the player usually does not detect
2370 them. Certain live streams (including TV captures) may exhibit problems
2371 in particular, as well as some lossy audio codecs. h264 intra\-refresh is
2372 known not to work due to problems with libavcodec. WAV and some other raw
2373 audio formats tend to have problems \- there are hacks for dealing with
2374 them, which may or may not work.
2375 .IP \(bu 2
2376 Backward demuxing of subtitles is not supported. Subtitle display still
2377 works for some external text subtitle formats. (These are fully read into
2378 memory, and only backward display is needed.) Text subtitles that are
2379 cached in the subtitle renderer also have a chance to be displayed
2380 correctly.
2381 .IP \(bu 2
2382 Some features dealing with playback of broken or hard to deal with files
2383 will not work fully (such as timestamp correction).
2384 .IP \(bu 2
2385 If demuxer low level seeks (i.e. seeking the actual demuxer instead of
2386 just within the demuxer cache) are performed by backward playback, the
2387 created seek ranges may not join, because not enough overlap is achieved.
2388 .IP \(bu 2
2389 Trying to use this with hardware video decoding will probably exhaust all
2390 your GPU memory and then crash a thing or two. Or it will fail because
2391 \fB\-\-hwdec\-extra\-frames\fP will certainly be set too low.
2392 .IP \(bu 2
2393 Stream recording is broken. \fB\-\-stream\-record\fP may keep working if you
2394 backward play within a cached region only.
2395 .IP \(bu 2
2396 Relative seeks may behave weird. Small seeks backward (towards smaller
2397 time, i.e. \fBseek \-1\fP) may not really seek properly, and audio will
2398 remain muted for a while. Using hr\-seek is recommended, which should have
2399 none of these problems.
2400 .IP \(bu 2
2401 Some things are just weird. For example, while seek commands manipulate
2402 playback time in the expected way (provided they work correctly), the
2403 framestep commands are transposed. Backstepping will perform very
2404 expensive work to step forward by 1 frame.
2405 .UNINDENT
2406 .sp
2407 Tuning:
2408 .INDENT 7.0
2409 .IP \(bu 2
2410 Remove all \fB\-\-vf\fP/\fB\-\-af\fP filters you have set. Disable hardware
2411 decoding. Disable idiotic nonsense like SPDIF passthrough.
2412 .IP \(bu 2
2413 Increasing \fB\-\-video\-reversal\-buffer\fP might help if reversal queue
2414 overflow is reported, which may happen in high bitrate video, or video
2415 with large GOP. Hardware decoding mostly ignores this, and you need to
2416 increase \fB\-\-hwdec\-extra\-frames\fP instead (until you get playback without
2417 logged errors).
2418 .IP \(bu 2
2419 The demuxer cache is essential for backward demuxing. Make sure to set
2420 \fB\-\-cache=yes\fP\&. The cache size might matter. If it\(aqs too small, a queue
2421 overflow will be logged, and backward playback cannot continue, or it
2422 performs too many low level seeks. If it\(aqs too large, implementation
2423 tradeoffs may cause general performance issues. Use
2424 \fB\-\-demuxer\-max\-bytes\fP to potentially increase the amount of packets the
2425 demuxer layer can queue for reverse demuxing (basically it\(aqs the
2426 \fB\-\-video\-reversal\-buffer\fP equivalent for the demuxer layer).
2427 .IP \(bu 2
2428 Setting \fB\-\-vd\-queue\-enable=yes\fP can help a lot to make playback smooth
2429 (once it works).
2430 .IP \(bu 2
2431 \fB\-\-demuxer\-backward\-playback\-step\fP also factors into how many seeks may
2432 be performed, and whether backward demuxing could break due to queue
2433 overflow. If it\(aqs set too high, the backstep operation needs to search
2434 through more packets all the time, even if the cache is large enough.
2435 .IP \(bu 2
2436 Setting \fB\-\-demuxer\-cache\-wait\fP may be useful to cache the entire file
2437 into the demuxer cache. Set \fB\-\-demuxer\-max\-bytes\fP to a large size to
2438 make sure it can read the entire cache; \fB\-\-demuxer\-max\-back\-bytes\fP
2439 should also be set to a large size to prevent that tries to trim the
2440 cache.
2441 .IP \(bu 2
2442 If audio artifacts are audible, even though the AO does not underrun,
2443 increasing \fB\-\-audio\-backward\-overlap\fP might help in some cases.
2444 .UNINDENT
2445 .TP
2446 .B \fB\-\-video\-reversal\-buffer=<bytesize>\fP, \fB\-\-audio\-reversal\-buffer=<bytesize>\fP
2447 For backward decoding. Backward decoding decodes forward in steps, and then
2448 reverses the decoder output. These options control the approximate maximum
2449 amount of bytes that can be buffered. The main use of this is to avoid
2450 unbounded resource usage; during normal backward playback, it\(aqs not supposed
2451 to hit the limit, and if it does, it will drop frames and complain about it.
2452 .sp
2453 Use this option if you get reversal queue overflow errors during backward
2454 playback. Increase the size until the warning disappears. Usually, the video
2455 buffer will overflow first, especially if it\(aqs high resolution video.
2456 .sp
2457 This does not work correctly if video hardware decoding is used. The video
2458 frame size will not include the referenced GPU and driver memory. Some
2459 hardware decoders may also be limited by \fB\-\-hwdec\-extra\-frames\fP\&.
2460 .sp
2461 How large the queue size needs to be depends entirely on the way the media
2462 was encoded. Audio typically requires a very small buffer, while video can
2463 require excessively large buffers.
2464 .sp
2465 (Technically, this allows the last frame to exceed the limit. Also, this
2466 does not account for other buffered frames, such as inside the decoder or
2467 the video output.)
2468 .sp
2469 This does not affect demuxer cache behavior at all.
2470 .sp
2471 See \fB\-\-list\-options\fP for defaults and value range. \fB<bytesize>\fP options
2472 accept suffixes such as \fBKiB\fP and \fBMiB\fP\&.
2473 .TP
2474 .B \fB\-\-video\-backward\-overlap=<auto|number>\fP, \fB\-\-audio\-backward\-overlap=<auto|number>\fP
2475 Number of overlapping keyframe ranges to use for backward decoding (default:
2476 auto) ("keyframe" to be understood as in the mpv/ffmpeg specific meaning).
2477 Backward decoding works by forward decoding in small steps. Some codecs
2478 cannot restart decoding from any packet (even if it\(aqs marked as seek point),
2479 which becomes noticeable with backward decoding (in theory this is a problem
2480 with seeking too, but \fB\-\-hr\-seek\-demuxer\-offset\fP can fix it for seeking).
2481 In particular, MDCT based audio codecs are affected.
2482 .sp
2483 The solution is to feed a previous packet to the decoder each time, and then
2484 discard the output. This option controls how many packets to feed. The
2485 \fBauto\fP choice is currently hardcoded to 0 for video, and uses 1 for lossy
2486 audio, 0 for lossless audio. For some specific lossy audio codecs, this is
2487 set to 2.
2488 .sp
2489 \fB\-\-video\-backward\-overlap\fP can potentially handle intra\-refresh video,
2490 depending on the exact conditions. You may have to use the
2491 \fB\-\-vd\-lavc\-show\-all\fP option as well.
2492 .TP
2493 .B \fB\-\-video\-backward\-batch=<number>\fP, \fB\-\-audio\-backward\-batch=<number>\fP
2494 Number of keyframe ranges to decode at once when backward decoding (default:
2495 1 for video, 10 for audio). Another pointless tuning parameter nobody should
2496 use. This should affect performance only. In theory, setting a number higher
2497 than 1 for audio will reduce overhead due to less frequent backstep
2498 operations and less redundant decoding work due to fewer decoded overlap
2499 frames (see \fB\-\-audio\-backward\-overlap\fP). On the other hand, it requires
2500 a larger reversal buffer, and could make playback less smooth due to
2501 breaking pipelining (e.g. by decoding a lot, and then doing nothing for a
2502 while).
2503 .sp
2504 It probably never makes sense to set \fB\-\-video\-backward\-batch\fP\&. But in
2505 theory, it could help with intra\-only video codecs by reducing backstep
2506 operations.
2507 .TP
2508 .B \fB\-\-demuxer\-backward\-playback\-step=<seconds>\fP
2509 Number of seconds the demuxer should seek back to get new packets during
2510 backward playback (default: 60). This is useful for tuning backward
2511 playback, see \fB\-\-play\-dir\fP for details.
2512 .sp
2513 Setting this to a very low value or 0 may make the player think seeking is
2514 broken, or may make it perform multiple seeks.
2515 .sp
2516 Setting this to a high value may lead to quadratic runtime behavior.
2517 .UNINDENT
2518 .SS Program Behavior
2519 .INDENT 0.0
2520 .TP
2521 .B \fB\-\-help\fP, \fB\-\-h\fP
2522 Show short summary of options.
2523 .sp
2524 You can also pass a string to this option, which will list all top\-level
2525 options which contain the string in the name, e.g. \fB\-\-h=scale\fP for all
2526 options that contain the word \fBscale\fP\&. The special string \fB*\fP lists
2527 all top\-level options.
2528 .TP
2529 .B \fB\-v\fP
2530 Increment verbosity level, one level for each \fB\-v\fP found on the command
2531 line.
2532 .TP
2533 .B \fB\-\-version, \-V\fP
2534 Print version string and exit.
2535 .TP
2536 .B \fB\-\-no\-config\fP
2537 Do not load default configuration files. This prevents loading of both the
2538 user\-level and system\-wide \fBmpv.conf\fP and \fBinput.conf\fP files. Other
2539 configuration files are blocked as well, such as resume playback files.
2540 .sp
2541 \fBNOTE:\fP
2542 .INDENT 7.0
2543 .INDENT 3.5
2544 Files explicitly requested by command line options, like
2545 \fB\-\-include\fP or \fB\-\-use\-filedir\-conf\fP, will still be loaded.
2546 .UNINDENT
2547 .UNINDENT
2548 .sp
2549 See also: \fB\-\-config\-dir\fP\&.
2550 .TP
2551 .B \fB\-\-list\-options\fP
2552 Prints all available options.
2553 .TP
2554 .B \fB\-\-list\-properties\fP
2555 Print a list of the available properties.
2556 .TP
2557 .B \fB\-\-list\-protocols\fP
2558 Print a list of the supported protocols.
2559 .TP
2560 .B \fB\-\-log\-file=<path>\fP
2561 Opens the given path for writing, and print log messages to it. Existing
2562 files will be truncated. The log level is at least \fB\-v \-v\fP, but
2563 can be raised via \fB\-\-msg\-level\fP (the option cannot lower it below the
2564 forced minimum log level).
2565 .sp
2566 A special case is the macOS bundle, it will create a log file at
2567 \fB~/Library/Logs/mpv.log\fP by default.
2568 .TP
2569 .B \fB\-\-config\-dir=<path>\fP
2570 Force a different configuration directory. If this is set, the given
2571 directory is used to load configuration files, and all other configuration
2572 directories are ignored. This means the global mpv configuration directory
2573 as well as per\-user directories are ignored, and overrides through
2574 environment variables (\fBMPV_HOME\fP) are also ignored.
2575 .sp
2576 Note that the \fB\-\-no\-config\fP option takes precedence over this option.
2577 .TP
2578 .B \fB\-\-save\-position\-on\-quit\fP
2579 Always save the current playback position on quit. When this file is
2580 played again later, the player will seek to the old playback position on
2581 start. This does not happen if playback of a file is stopped in any other
2582 way than quitting. For example, going to the next file in the playlist
2583 will not save the position, and start playback at beginning the next time
2584 the file is played.
2585 .sp
2586 This behavior is disabled by default, but is always available when quitting
2587 the player with Shift+Q.
2588 .TP
2589 .B \fB\-\-watch\-later\-directory=<path>\fP
2590 The directory in which to store the "watch later" temporary files.
2591 .sp
2592 The default is a subdirectory named "watch_later" underneath the
2593 config directory (usually \fB~/.config/mpv/\fP).
2594 .TP
2595 .B \fB\-\-dump\-stats=<filename>\fP
2596 Write certain statistics to the given file. The file is truncated on
2597 opening. The file will contain raw samples, each with a timestamp. To
2598 make this file into a readable, the script \fBTOOLS/stats\-conv.py\fP can be
2599 used (which currently displays it as a graph).
2600 .sp
2601 This option is useful for debugging only.
2602 .TP
2603 .B \fB\-\-idle=<no|yes|once>\fP
2604 Makes mpv wait idly instead of quitting when there is no file to play.
2605 Mostly useful in input mode, where mpv can be controlled through input
2606 commands. (Default: \fBno\fP)
2607 .sp
2608 \fBonce\fP will only idle at start and let the player close once the
2609 first playlist has finished playing back.
2610 .TP
2611 .B \fB\-\-include=<configuration\-file>\fP
2612 Specify configuration file to be parsed after the default ones.
2613 .TP
2614 .B \fB\-\-load\-scripts=<yes|no>\fP
2615 If set to \fBno\fP, don\(aqt auto\-load scripts from the \fBscripts\fP
2616 configuration subdirectory (usually \fB~/.config/mpv/scripts/\fP).
2617 (Default: \fByes\fP)
2618 .TP
2619 .B \fB\-\-script=<filename>\fP, \fB\-\-scripts=file1.lua:file2.lua:...\fP
2620 Load a Lua script. The second option allows you to load multiple scripts by
2621 separating them with the path separator (\fB:\fP on Unix, \fB;\fP on Windows).
2622 .sp
2623 \fB\-\-scripts\fP is a path list option. See \fI\%List Options\fP for details.
2624 .TP
2625 .B \fB\-\-script\-opts=key1=value1,key2=value2,...\fP
2626 Set options for scripts. A script can query an option by key. If an
2627 option is used and what semantics the option value has depends entirely on
2628 the loaded scripts. Values not claimed by any scripts are ignored.
2629 .sp
2630 This is a key/value list option. See \fI\%List Options\fP for details.
2631 .TP
2632 .B \fB\-\-merge\-files\fP
2633 Pretend that all files passed to mpv are concatenated into a single, big
2634 file. This uses timeline/EDL support internally.
2635 .TP
2636 .B \fB\-\-no\-resume\-playback\fP
2637 Do not restore playback position from the \fBwatch_later\fP configuration
2638 subdirectory (usually \fB~/.config/mpv/watch_later/\fP).
2639 See \fBquit\-watch\-later\fP input command.
2640 .TP
2641 .B \fB\-\-resume\-playback\-check\-mtime\fP
2642 Only restore the playback position from the \fBwatch_later\fP configuration
2643 subdirectory (usually \fB~/.config/mpv/watch_later/\fP) if the file\(aqs
2644 modification time is the same as at the time of saving. This may prevent
2645 skipping forward in files with the same name which have different content.
2646 (Default: \fBno\fP)
2647 .TP
2648 .B \fB\-\-profile=<profile1,profile2,...>\fP
2649 Use the given profile(s), \fB\-\-profile=help\fP displays a list of the
2650 defined profiles.
2651 .TP
2652 .B \fB\-\-reset\-on\-next\-file=<all|option1,option2,...>\fP
2653 Normally, mpv will try to keep all settings when playing the next file on
2654 the playlist, even if they were changed by the user during playback. (This
2655 behavior is the opposite of MPlayer\(aqs, which tries to reset all settings
2656 when starting next file.)
2657 .sp
2658 Default: Do not reset anything.
2659 .sp
2660 This can be changed with this option. It accepts a list of options, and
2661 mpv will reset the value of these options on playback start to the initial
2662 value. The initial value is either the default value, or as set by the
2663 config file or command line.
2664 .sp
2665 In some cases, this might not work as expected. For example, \fB\-\-volume\fP
2666 will only be reset if it is explicitly set in the config file or the
2667 command line.
2668 .sp
2669 The special name \fBall\fP resets as many options as possible.
2670 .sp
2671 This is a string list option. See \fI\%List Options\fP for details.
2672 .INDENT 7.0
2673 .INDENT 3.5
2674 .IP "Examples"
2675 .INDENT 0.0
2676 .IP \(bu 2
2677 \fB\-\-reset\-on\-next\-file=pause\fP
2678 Reset pause mode when switching to the next file.
2679 .IP \(bu 2
2680 \fB\-\-reset\-on\-next\-file=fullscreen,speed\fP
2681 Reset fullscreen and playback speed settings if they were changed
2682 during playback.
2683 .IP \(bu 2
2684 \fB\-\-reset\-on\-next\-file=all\fP
2685 Try to reset all settings that were changed during playback.
2686 .UNINDENT
2687 .UNINDENT
2688 .UNINDENT
2689 .TP
2690 .B \fB\-\-write\-filename\-in\-watch\-later\-config\fP
2691 Prepend the watch later config files with the name of the file they refer
2692 to. This is simply written as comment on the top of the file.
2693 .sp
2694 \fBWARNING:\fP
2695 .INDENT 7.0
2696 .INDENT 3.5
2697 This option may expose privacy\-sensitive information and is thus
2698 disabled by default.
2699 .UNINDENT
2700 .UNINDENT
2701 .TP
2702 .B \fB\-\-ignore\-path\-in\-watch\-later\-config\fP
2703 Ignore path (i.e. use filename only) when using watch later feature.
2704 (Default: disabled)
2705 .TP
2706 .B \fB\-\-show\-profile=<profile>\fP
2707 Show the description and content of a profile. Lists all profiles if no
2708 parameter is provided.
2709 .TP
2710 .B \fB\-\-use\-filedir\-conf\fP
2711 Look for a file\-specific configuration file in the same directory as the
2712 file that is being played. See \fI\%File\-specific Configuration Files\fP\&.
2713 .sp
2714 \fBWARNING:\fP
2715 .INDENT 7.0
2716 .INDENT 3.5
2717 May be dangerous if playing from untrusted media.
2718 .UNINDENT
2719 .UNINDENT
2720 .TP
2721 .B \fB\-\-ytdl\fP, \fB\-\-no\-ytdl\fP
2722 Enable the youtube\-dl hook\-script. It will look at the input URL, and will
2723 play the video located on the website. This works with many streaming sites,
2724 not just the one that the script is named after. This requires a recent
2725 version of youtube\-dl to be installed on the system. (Enabled by default.)
2726 .sp
2727 If the script can\(aqt do anything with an URL, it will do nothing.
2728 .sp
2729 This accepts a set of options, which can be passed to it with the
2730 \fB\-\-script\-opts\fP option (using \fBytdl_hook\-\fP as prefix):
2731 .INDENT 7.0
2732 .TP
2733 .B \fBtry_ytdl_first=<yes|no>\fP
2734 If \(aqyes\(aq will try parsing the URL with youtube\-dl first, instead of the
2735 default where it\(aqs only after mpv failed to open it. This mostly depends
2736 on whether most of your URLs need youtube\-dl parsing.
2737 .TP
2738 .B \fBexclude=<URL1|URL2|...\fP
2739 A \fB|\fP\-separated list of URL patterns which mpv should not use with
2740 youtube\-dl. The patterns are matched after the \fBhttp(s)://\fP part of
2741 the URL.
2742 .sp
2743 \fB^\fP matches the beginning of the URL, \fB$\fP matches its end, and you
2744 should use \fB%\fP before any of the characters \fB^$()%|,.[]*+\-?\fP to
2745 match that character.
2746 .INDENT 7.0
2747 .INDENT 3.5
2748 .IP "Examples"
2749 .INDENT 0.0
2750 .IP \(bu 2
2751 \fB\-\-script\-opts=ytdl_hook\-exclude=\(aq^youtube%.com\(aq\fP
2752 will exclude any URL that starts with \fBhttp://youtube.com\fP or
2753 \fBhttps://youtube.com\fP\&.
2754 .IP \(bu 2
2755 \fB\-\-script\-opts=ytdl_hook\-exclude=\(aq%.mkv$|%.mp4$\(aq\fP
2756 will exclude any URL that ends with \fB\&.mkv\fP or \fB\&.mp4\fP\&.
2757 .UNINDENT
2758 .UNINDENT
2759 .UNINDENT
2760 .sp
2761 See more lua patterns here: \fI\%https://www.lua.org/manual/5.1/manual.html#5.4.1\fP
2762 .TP
2763 .B \fBall_formats=<yes|no>\fP
2764 If \(aqyes\(aq will attempt to add all formats found reported by youtube\-dl
2765 (default: no). Each format is added as a separate track. In addition,
2766 they are delay\-loaded, and actually opened only when a track is selected
2767 (this should keep load times as low as without this option).
2768 .sp
2769 It adds average bitrate metadata, if available, which means you can use
2770 \fB\-\-hls\-bitrate\fP to decide which track to select. (HLS used to be the
2771 only format whose alternative quality streams were exposed in a similar
2772 way, thus the option name.)
2773 .sp
2774 Tracks which represent formats that were selected by youtube\-dl as
2775 default will have the default flag set. This means mpv should generally
2776 still select formats chosen with \fB\-\-ytdl\-format\fP by default.
2777 .sp
2778 Although this mechanism makes it possible to switch streams at runtime,
2779 it\(aqs not suitable for this purpose for various technical reasons. (It\(aqs
2780 slow, which can\(aqt be really fixed.) In general, this option is not
2781 useful, and was only added to show that it\(aqs possible.
2782 .sp
2783 There are two cases that must be considered when doing quality/bandwidth
2784 selection:
2785 .INDENT 7.0
2786 .INDENT 3.5
2787 .INDENT 0.0
2788 .IP 1. 3
2789 Completely separate audio and video streams (DASH\-like). Each of
2790 these streams contain either only audio or video, so you can
2791 mix and combine audio/video bandwidths without restriction. This
2792 intuitively matches best with the concept of selecting quality
2793 by track (what \fBall_formats\fP is supposed to do).
2794 .IP 2. 3
2795 Separate sets of muxed audio and video streams. Each version of
2796 the media contains both an audio and video stream, and they are
2797 interleaved. In order not to waste bandwidth, you should only
2798 select one of these versions (if, for example, you select an
2799 audio stream, then video will be downloaded, even if you selected
2800 video from a different stream).
2801 .sp
2802 mpv will still represent them as separate tracks, but will set
2803 the title of each track to \fBmuxed\-N\fP, where \fBN\fP is replaced
2804 with the youtube\-dl format ID of the originating stream.
2805 .UNINDENT
2806 .UNINDENT
2807 .UNINDENT
2808 .sp
2809 Some sites will mix 1. and 2., but we assume that they do so for
2810 compatibility reasons, and there is no reason to use them at all.
2811 .TP
2812 .B \fBforce_all_formats=<yes|no>\fP
2813 If set to \(aqyes\(aq, and \fBall_formats\fP is also set to \(aqyes\(aq, this will
2814 try to represent all youtube\-dl reported formats as tracks, even if
2815 mpv would normally use the direct URL reported by it (default: yes).
2816 .sp
2817 It appears this normally makes a difference if youtube\-dl works on a
2818 master HLS playlist.
2819 .sp
2820 If this is set to \(aqno\(aq, this specific kind of stream is treated like
2821 \fBall_formats\fP is set to \(aqno\(aq, and the stream selection as done by
2822 youtube\-dl (via \fB\-\-ytdl\-format\fP) is used.
2823 .TP
2824 .B \fBuse_manifests=<yes|no>\fP
2825 Make mpv use the master manifest URL for formats like HLS and DASH,
2826 if available, allowing for video/audio selection in runtime (default:
2827 no). It\(aqs disabled ("no") by default for performance reasons.
2828 .TP
2829 .B \fBytdl_path=youtube\-dl\fP
2830 Configure path to youtube\-dl executable or a compatible fork\(aqs.
2831 The default "youtube\-dl" looks for the executable in PATH. In a Windows
2832 environment the suffix extension ".exe" is always appended.
2833 .UNINDENT
2834 .INDENT 7.0
2835 .INDENT 3.5
2836 .IP "Why do the option names mix \fB_\fP and \fB\-\fP?"
2837 .sp
2838 I have no idea.
2839 .UNINDENT
2840 .UNINDENT
2841 .TP
2842 .B \fB\-\-ytdl\-format=<ytdl|best|worst|mp4|webm|...>\fP
2843 Video format/quality that is directly passed to youtube\-dl. The possible
2844 values are specific to the website and the video, for a given url the
2845 available formats can be found with the command
2846 \fByoutube\-dl \-\-list\-formats URL\fP\&. See youtube\-dl\(aqs documentation for
2847 available aliases.
2848 (Default: \fBbestvideo+bestaudio/best\fP)
2849 .sp
2850 The \fBytdl\fP value does not pass a \fB\-\-format\fP option to youtube\-dl at all,
2851 and thus does not override its default. Note that sometimes youtube\-dl
2852 returns a format that mpv cannot use, and in these cases the mpv default
2853 may work better.
2854 .TP
2855 .B \fB\-\-ytdl\-raw\-options=<key>=<value>[,<key>=<value>[,...]]\fP
2856 Pass arbitrary options to youtube\-dl. Parameter and argument should be
2857 passed as a key\-value pair. Options without argument must include \fB=\fP\&.
2858 .sp
2859 There is no sanity checking so it\(aqs possible to break things (i.e.
2860 passing invalid parameters to youtube\-dl).
2861 .sp
2862 A proxy URL can be passed for youtube\-dl to use it in parsing the website.
2863 This is useful for geo\-restricted URLs. After youtube\-dl parsing, some
2864 URLs also require a proxy for playback, so this can pass that proxy
2865 information to mpv. Take note that SOCKS proxies aren\(aqt supported and
2866 https URLs also bypass the proxy. This is a limitation in FFmpeg.
2867 .sp
2868 This is a key/value list option. See \fI\%List Options\fP for details.
2869 .INDENT 7.0
2870 .INDENT 3.5
2871 .IP "Example"
2872 .INDENT 0.0
2873 .IP \(bu 2
2874 \fB\-\-ytdl\-raw\-options=username=user,password=pass\fP
2875 .IP \(bu 2
2876 \fB\-\-ytdl\-raw\-options=force\-ipv6=\fP
2877 .IP \(bu 2
2878 \fB\-\-ytdl\-raw\-options=proxy=[http://127.0.0.1:3128]\fP
2879 .IP \(bu 2
2880 \fB\-\-ytdl\-raw\-options\-append=proxy=http://127.0.0.1:3128\fP
2881 .UNINDENT
2882 .UNINDENT
2883 .UNINDENT
2884 .TP
2885 .B \fB\-\-load\-stats\-overlay=<yes|no>\fP
2886 Enable the builtin script that shows useful playback information on a key
2887 binding (default: yes). By default, the \fBi\fP key is used (\fBI\fP to make
2888 the overlay permanent).
2889 .TP
2890 .B \fB\-\-load\-osd\-console=<yes|no>\fP
2891 Enable the builtin script that shows a console on a key binding and lets
2892 you enter commands (default: yes). By default,. The \fB\'\fP key is used to
2893 show the console, and \fBESC\fP to hide it again. (This is based on a user
2894 script called \fBrepl.lua\fP\&.)
2895 .TP
2896 .B \fB\-\-load\-auto\-profiles=<yes|no|auto>\fP
2897 Enable the builtin script that does auto profiles (default: auto). See
2898 \fI\%Conditional auto profiles\fP for details. \fBauto\fP will load the script,
2899 but immediately unload it if there are no conditional profiles.
2900 .TP
2901 .B \fB\-\-player\-operation\-mode=<cplayer|pseudo\-gui>\fP
2902 For enabling "pseudo GUI mode", which means that the defaults for some
2903 options are changed. This option should not normally be used directly, but
2904 only by mpv internally, or mpv\-provided scripts, config files, or .desktop
2905 files. See \fI\%PSEUDO GUI MODE\fP for details.
2906 .UNINDENT
2907 .SS Video
2908 .INDENT 0.0
2909 .TP
2910 .B \fB\-\-vo=<driver>\fP
2911 Specify the video output backend to be used. See \fI\%VIDEO OUTPUT DRIVERS\fP for
2912 details and descriptions of available drivers.
2913 .TP
2914 .B \fB\-\-vd=<...>\fP
2915 Specify a priority list of video decoders to be used, according to their
2916 family and name. See \fB\-\-ad\fP for further details. Both of these options
2917 use the same syntax and semantics; the only difference is that they
2918 operate on different codec lists.
2919 .sp
2920 \fBNOTE:\fP
2921 .INDENT 7.0
2922 .INDENT 3.5
2923 See \fB\-\-vd=help\fP for a full list of available decoders.
2924 .UNINDENT
2925 .UNINDENT
2926 .TP
2927 .B \fB\-\-vf=<filter1[=parameter1:parameter2:...],filter2,...>\fP
2928 Specify a list of video filters to apply to the video stream. See
2929 \fI\%VIDEO FILTERS\fP for details and descriptions of the available filters.
2930 The option variants \fB\-\-vf\-add\fP, \fB\-\-vf\-pre\fP, \fB\-\-vf\-del\fP and
2931 \fB\-\-vf\-clr\fP exist to modify a previously specified list, but you
2932 should not need these for typical use.
2933 .TP
2934 .B \fB\-\-untimed\fP
2935 Do not sleep when outputting video frames. Useful for benchmarks when used
2936 with \fB\-\-no\-audio.\fP
2937 .TP
2938 .B \fB\-\-framedrop=<mode>\fP
2939 Skip displaying some frames to maintain A/V sync on slow systems, or
2940 playing high framerate video on video outputs that have an upper framerate
2941 limit.
2942 .sp
2943 The argument selects the drop methods, and can be one of the following:
2944 .INDENT 7.0
2945 .TP
2946 .B <no>
2947 Disable any frame dropping. Not recommended, for testing only.
2948 .TP
2949 .B <vo>
2950 Drop late frames on video output (default). This still decodes and
2951 filters all frames, but doesn\(aqt render them on the VO. Drops are
2952 indicated in the terminal status line as \fBDropped:\fP field.
2953 .sp
2954 In audio sync. mode, this drops frames that are outdated at the time of
2955 display. If the decoder is too slow, in theory all frames would have to
2956 be dropped (because all frames are too late) \- to avoid this, frame
2957 dropping stops if the effective framerate is below 10 FPS.
2958 .sp
2959 In display\-sync. modes (see \fB\-\-video\-sync\fP), this affects only how
2960 A/V drops or repeats frames. If this mode is disabled, A/V desync will
2961 in theory not affect video scheduling anymore (much like the
2962 \fBdisplay\-resample\-desync\fP mode). However, even if disabled, frames
2963 will still be skipped (i.e. dropped) according to the ratio between
2964 video and display frequencies.
2965 .sp
2966 This is the recommended mode, and the default.
2967 .TP
2968 .B <decoder>
2969 Old, decoder\-based framedrop mode. (This is the same as \fB\-\-framedrop=yes\fP
2970 in mpv 0.5.x and before.) This tells the decoder to skip frames (unless
2971 they are needed to decode future frames). May help with slow systems,
2972 but can produce unwatchable choppy output, or even freeze the display
2973 completely.
2974 .sp
2975 This uses a heuristic which may not make sense, and in general cannot
2976 achieve good results, because the decoder\(aqs frame dropping cannot be
2977 controlled in a predictable manner. Not recommended.
2978 .sp
2979 Even if you want to use this, prefer \fBdecoder+vo\fP for better results.
2980 .sp
2981 The \fB\-\-vd\-lavc\-framedrop\fP option controls what frames to drop.
2982 .TP
2983 .B <decoder+vo>
2984 Enable both modes. Not recommended. Better than just \fBdecoder\fP mode.
2985 .UNINDENT
2986 .sp
2987 \fBNOTE:\fP
2988 .INDENT 7.0
2989 .INDENT 3.5
2990 \fB\-\-vo=vdpau\fP has its own code for the \fBvo\fP framedrop mode. Slight
2991 differences to other VOs are possible.
2992 .UNINDENT
2993 .UNINDENT
2994 .TP
2995 .B \fB\-\-video\-latency\-hacks=<yes|no>\fP
2996 Enable some things which tend to reduce video latency by 1 or 2 frames
2997 (default: no). Note that this option might be removed without notice once
2998 the player\(aqs timing code does not inherently need to do these things
2999 anymore.
3000 .sp
3001 This does:
3002 .INDENT 7.0
3003 .IP \(bu 2
3004 Use the demuxer reported FPS for frame dropping. This avoids the
3005 player needing to decode 1 frame in advance, lowering total latency in
3006 effect. This also means that if the demuxer reported FPS is wrong, or
3007 the video filter chain changes FPS (e.g. deinterlacing), then it could
3008 drop too many or not enough frames.
3009 .IP \(bu 2
3010 Disable waiting for the first video frame. Normally the player waits for
3011 the first video frame to be fully rendered before starting playback
3012 properly. Some VOs will lazily initialize stuff when rendering the first
3013 frame, so if this is not done, there is some likeliness that the VO has
3014 to drop some frames if rendering the first frame takes longer than needed.
3015 .UNINDENT
3016 .TP
3017 .B \fB\-\-override\-display\-fps=<fps>\fP
3018 Set the display FPS used with the \fB\-\-video\-sync=display\-*\fP modes. By
3019 default, a detected value is used. Keep in mind that setting an incorrect
3020 value (even if slightly incorrect) can ruin video playback. On multi\-monitor
3021 systems, there is a chance that the detected value is from the wrong
3022 monitor.
3023 .sp
3024 Set this option only if you have reason to believe the automatically
3025 determined value is wrong.
3026 .TP
3027 .B \fB\-\-display\-fps=<fps>\fP
3028 Deprecated alias for \fB\-\-override\-display\-fps\fP\&.
3029 .TP
3030 .B \fB\-\-hwdec=<api>\fP
3031 Specify the hardware video decoding API that should be used if possible.
3032 Whether hardware decoding is actually done depends on the video codec. If
3033 hardware decoding is not possible, mpv will fall back on software decoding.
3034 .sp
3035 Hardware decoding is not enabled by default, because it is typically an
3036 additional source of errors. It is worth using only if your CPU is too
3037 slow to decode a specific video.
3038 .sp
3039 \fBNOTE:\fP
3040 .INDENT 7.0
3041 .INDENT 3.5
3042 Use the \fBCtrl+h\fP shortcut to toggle hardware decoding at runtime. It
3043 toggles this option between \fBauto\fP and \fBno\fP\&.
3044 .sp
3045 Always enabling HW decoding by putting it into the config file is
3046 discouraged. If you use the Ubuntu package, delete \fB/etc/mpv/mpv.conf\fP,
3047 as the package tries to enable HW decoding by default by setting
3048 \fBhwdec=vaapi\fP (which is less than ideal, and may even cause
3049 sub\-optimal wrappers to be used). Or at least change it to
3050 \fBhwdec=auto\-safe\fP\&.
3051 .UNINDENT
3052 .UNINDENT
3053 .sp
3054 Use one of the auto modes if you want to enable hardware decoding.
3055 Explicitly selecting the mode is mostly meant for testing and debugging.
3056 It\(aqs a bad idea to put explicit selection into the config file if you
3057 want thing to just keep working after updates and so on.
3058 .sp
3059 \fBNOTE:\fP
3060 .INDENT 7.0
3061 .INDENT 3.5
3062 Even if enabled, hardware decoding is still only white\-listed for some
3063 codecs. See \fB\-\-hwdec\-codecs\fP to enable hardware decoding in more cases.
3064 .UNINDENT
3065 .UNINDENT
3066 .INDENT 7.0
3067 .INDENT 3.5
3068 .IP "Which method to choose?"
3069 .INDENT 0.0
3070 .IP \(bu 2
3071 If you only want to enable hardware decoding at runtime, don\(aqt set the
3072 parameter, or put \fBhwdec=no\fP into your \fBmpv.conf\fP (relevant on
3073 distros which force\-enable it by default, such as on Ubuntu). Use the
3074 \fBCtrl+h\fP default binding to enable it at runtime.
3075 .IP \(bu 2
3076 If you\(aqre not sure, but want hardware decoding always enabled by
3077 default, put \fBhwdec=auto\-safe\fP into your \fBmpv.conf\fP, and
3078 acknowledge that this use case is not "really" supported and may cause
3079 problems.
3080 .IP \(bu 2
3081 If you want to test available hardware decoding methods, pass
3082 \fB\-\-hwdec=auto \-\-hwdec\-codecs=all\fP and look at the terminal output.
3083 .IP \(bu 2
3084 If you\(aqre a developer, or want to perform elaborate tests, you may
3085 need any of the other possible option values.
3086 .UNINDENT
3087 .UNINDENT
3088 .UNINDENT
3089 .sp
3090 \fB<api>\fP can be one of the following:
3091 .INDENT 7.0
3092 .TP
3093 .B no
3094 always use software decoding (default)
3095 .TP
3096 .B auto
3097 forcibly enable any hw decoder found (see below)
3098 .TP
3099 .B yes
3100 exactly the same as \fBauto\fP
3101 .TP
3102 .B auto\-safe
3103 enable any whitelisted hw decoder (see below)
3104 .TP
3105 .B auto\-copy
3106 enable best hw decoder with copy\-back (see below)
3107 .TP
3108 .B vdpau
3109 requires \fB\-\-vo=gpu\fP with X11, or \fB\-\-vo=vdpau\fP (Linux only)
3110 .TP
3111 .B vdpau\-copy
3112 copies video back into system RAM (Linux with some GPUs only)
3113 .TP
3114 .B vaapi
3115 requires \fB\-\-vo=gpu\fP or \fB\-\-vo=vaapi\fP (Linux only)
3116 .TP
3117 .B vaapi\-copy
3118 copies video back into system RAM (Linux with some GPUs only)
3119 .TP
3120 .B videotoolbox
3121 requires \fB\-\-vo=gpu\fP (OS X 10.8 and up),
3122 or \fB\-\-vo=libmpv\fP (iOS 9.0 and up)
3123 .TP
3124 .B videotoolbox\-copy
3125 copies video back into system RAM (OS X 10.8 or iOS 9.0 and up)
3126 .TP
3127 .B dxva2
3128 requires \fB\-\-vo=gpu\fP with \fB\-\-gpu\-context=d3d11\fP,
3129 \fB\-\-gpu\-context=angle\fP or \fB\-\-gpu\-context=dxinterop\fP
3130 (Windows only)
3131 .TP
3132 .B dxva2\-copy
3133 copies video back to system RAM (Windows only)
3134 .TP
3135 .B d3d11va
3136 requires \fB\-\-vo=gpu\fP with \fB\-\-gpu\-context=d3d11\fP or
3137 \fB\-\-gpu\-context=angle\fP (Windows 8+ only)
3138 .TP
3139 .B d3d11va\-copy
3140 copies video back to system RAM (Windows 8+ only)
3141 .TP
3142 .B mediacodec
3143 requires \fB\-\-vo=mediacodec_embed\fP (Android only)
3144 .TP
3145 .B mediacodec\-copy
3146 copies video back to system RAM (Android only)
3147 .TP
3148 .B mmal
3149 requires \fB\-\-vo=gpu\fP (Raspberry Pi only \- default if available)
3150 .TP
3151 .B mmal\-copy
3152 copies video back to system RAM (Raspberry Pi only)
3153 .TP
3154 .B nvdec
3155 requires \fB\-\-vo=gpu\fP (Any platform CUDA is available)
3156 .TP
3157 .B nvdec\-copy
3158 copies video back to system RAM (Any platform CUDA is available)
3159 .TP
3160 .B cuda
3161 requires \fB\-\-vo=gpu\fP (Any platform CUDA is available)
3162 .TP
3163 .B cuda\-copy
3164 copies video back to system RAM (Any platform CUDA is available)
3165 .TP
3166 .B crystalhd
3167 copies video back to system RAM (Any platform supported by hardware)
3168 .TP
3169 .B rkmpp
3170 requires \fB\-\-vo=gpu\fP (some RockChip devices only)
3171 .UNINDENT
3172 .sp
3173 \fBauto\fP tries to automatically enable hardware decoding using the first
3174 available method. This still depends what VO you are using. For example,
3175 if you are not using \fB\-\-vo=gpu\fP or \fB\-\-vo=vdpau\fP, vdpau decoding will
3176 never be enabled. Also note that if the first found method doesn\(aqt actually
3177 work, it will always fall back to software decoding, instead of trying the
3178 next method (might matter on some Linux systems).
3179 .sp
3180 \fBauto\-safe\fP is similar to \fBauto\fP, but allows only whitelisted methods
3181 that are considered "safe". This is supposed to be a reasonable way to
3182 enable hardware decdoding by default in a config file (even though you
3183 shouldn\(aqt do that anyway; prefer runtime enabling with \fBCtrl+h\fP). Unlike
3184 \fBauto\fP, this will not try to enable unknown or known\-to\-be\-bad methods. In
3185 addition, this may disable hardware decoding in other situations when it\(aqs
3186 known to cause problems, but currently this mechanism is quite primitive.
3187 (As an example for something that still causes problems: certain
3188 combinations of HEVC and Intel chips on Windows tend to cause mpv to crash,
3189 most likely due to driver bugs.)
3190 .sp
3191 \fBauto\-copy\-safe\fP selects the union of methods selected with \fBauto\-safe\fP
3192 and \fBauto\-copy\fP\&.
3193 .sp
3194 \fBauto\-copy\fP selects only modes that copy the video data back to system
3195 memory after decoding. This selects modes like \fBvaapi\-copy\fP (and so on).
3196 If none of these work, hardware decoding is disabled. This mode is usually
3197 guaranteed to incur no additional quality loss compared to software
3198 decoding (assuming modern codecs and an error free video stream), and will
3199 allow CPU processing with video filters. This mode works with all video
3200 filters and VOs.
3201 .sp
3202 Because these copy the decoded video back to system RAM, they\(aqre often less
3203 efficient than the direct modes, and may not help too much over software
3204 decoding.
3205 .sp
3206 \fBNOTE:\fP
3207 .INDENT 7.0
3208 .INDENT 3.5
3209 Most non\-copy methods only work with the OpenGL GPU backend. Currently,
3210 only the \fBvaapi\fP, \fBnvdec\fP and \fBcuda\fP methods work with Vulkan.
3211 .UNINDENT
3212 .UNINDENT
3213 .sp
3214 The \fBvaapi\fP mode, if used with \fB\-\-vo=gpu\fP, requires Mesa 11, and most
3215 likely works with Intel and AMD GPUs only. It also requires the opengl EGL
3216 backend.
3217 .sp
3218 \fBnvdec\fP and \fBnvdec\-copy\fP are the newest, and recommended method to do
3219 hardware decoding on Nvidia GPUs.
3220 .sp
3221 \fBcuda\fP and \fBcuda\-copy\fP are an older implementation of hardware decoding
3222 on Nvidia GPUs that uses Nvidia\(aqs bitstream parsers rather than FFmpeg\(aqs.
3223 This can lead to feature deficiencies, such as incorrect playback of HDR
3224 content, and \fBnvdec\fP/\fBnvdec\-copy\fP should always be preferred unless you
3225 specifically need Nvidia\(aqs deinterlacing algorithms. To use this
3226 deinterlacing you must pass the option:
3227 \fBvd\-lavc\-o=deint=[weave|bob|adaptive]\fP\&.
3228 Pass \fBweave\fP (or leave the option unset) to not attempt any
3229 deinterlacing.
3230 .INDENT 7.0
3231 .INDENT 3.5
3232 .IP "Quality reduction with hardware decoding"
3233 .sp
3234 In theory, hardware decoding does not reduce video quality (at least
3235 for the codecs h264 and HEVC). However, due to restrictions in video
3236 output APIs, as well as bugs in the actual hardware decoders, there can
3237 be some loss, or even blatantly incorrect results.
3238 .sp
3239 In some cases, RGB conversion is forced, which means the RGB conversion
3240 is performed by the hardware decoding API, instead of the shaders
3241 used by \fB\-\-vo=gpu\fP\&. This means certain colorspaces may not display
3242 correctly, and certain filtering (such as debanding) cannot be applied
3243 in an ideal way. This will also usually force the use of low quality
3244 chroma scalers instead of the one specified by \fB\-\-cscale\fP\&. In other
3245 cases, hardware decoding can also reduce the bit depth of the decoded
3246 image, which can introduce banding or precision loss for 10\-bit files.
3247 .sp
3248 \fBvdpau\fP always does RGB conversion in hardware, which does not
3249 support newer colorspaces like BT.2020 correctly. However, \fBvdpau\fP
3250 doesn\(aqt support 10 bit or HDR encodings, so these limitations are
3251 unlikely to be relevant.
3252 .sp
3253 \fBvaapi\fP and \fBd3d11va\fP are safe. Enabling deinterlacing (or simply
3254 their respective post\-processing filters) will possibly at least reduce
3255 color quality by converting the output to a 8 bit format.
3256 .sp
3257 \fBdxva2\fP is not safe. It appears to always use BT.601 for forced RGB
3258 conversion, but actual behavior depends on the GPU drivers. Some drivers
3259 appear to convert to limited range RGB, which gives a faded appearance.
3260 In addition to driver\-specific behavior, global system settings might
3261 affect this additionally. This can give incorrect results even with
3262 completely ordinary video sources.
3263 .sp
3264 \fBrpi\fP always uses the hardware overlay renderer, even with
3265 \fB\-\-vo=gpu\fP\&.
3266 .sp
3267 \fBcuda\fP should usually be safe, but depending on how a file/stream
3268 has been mixed, it has been reported to corrupt the timestamps causing
3269 glitched, flashing frames. It can also sometimes cause massive
3270 framedrops for unknown reasons. Caution is advised, and \fBnvdec\fP
3271 should always be preferred.
3272 .sp
3273 \fBcrystalhd\fP is not safe. It always converts to 4:2:2 YUV, which
3274 may be lossy, depending on how chroma sub\-sampling is done during
3275 conversion. It also discards the top left pixel of each frame for
3276 some reason.
3277 .sp
3278 All other methods, in particular the copy\-back methods (like
3279 \fBdxva2\-copy\fP etc.) should hopefully be safe, although they can still
3280 cause random decoding issues. At the very least, they shouldn\(aqt affect
3281 the colors of the image.
3282 .sp
3283 In particular, \fBauto\-copy\fP will only select "safe" modes
3284 (although potentially slower than other methods), but there\(aqs still no
3285 guarantee the chosen hardware decoder will actually work correctly.
3286 .sp
3287 In general, it\(aqs very strongly advised to avoid hardware decoding
3288 unless \fBabsolutely\fP necessary, i.e. if your CPU is insufficient to
3289 decode the file in questions. If you run into any weird decoding issues,
3290 frame glitches or discoloration, and you have \fB\-\-hwdec\fP turned on,
3291 the first thing you should try is disabling it.
3292 .UNINDENT
3293 .UNINDENT
3294 .TP
3295 .B \fB\-\-gpu\-hwdec\-interop=<auto|all|no|name>\fP
3296 This option is for troubleshooting hwdec interop issues. Since it\(aqs a
3297 debugging option, its semantics may change at any time.
3298 .sp
3299 This is useful for the \fBgpu\fP and \fBlibmpv\fP VOs for selecting which
3300 hwdec interop context to use exactly. Effectively it also can be used
3301 to block loading of certain backends.
3302 .sp
3303 If set to \fBauto\fP (default), the behavior depends on the VO: for \fBgpu\fP,
3304 it does nothing, and the interop context is loaded on demand (when the
3305 decoder probes for \fB\-\-hwdec\fP support). For \fBlibmpv\fP, which has
3306 has no on\-demand loading, this is equivalent to \fBall\fP\&.
3307 .sp
3308 The empty string is equivalent to \fBauto\fP\&.
3309 .sp
3310 If set to \fBall\fP, it attempts to load all interop contexts at GL context
3311 creation time.
3312 .sp
3313 Other than that, a specific backend can be set, and the list of them can
3314 be queried with \fBhelp\fP (mpv CLI only).
3315 .sp
3316 Runtime changes to this are ignored (the current option value is used
3317 whenever the renderer is created).
3318 .sp
3319 The old aliases \fB\-\-opengl\-hwdec\-interop\fP and \fB\-\-hwdec\-preload\fP are
3320 barely related to this anymore, but will be somewhat compatible in some
3321 cases.
3322 .TP
3323 .B \fB\-\-hwdec\-extra\-frames=<N>\fP
3324 Number of GPU frames hardware decoding should preallocate (default: see
3325 \fB\-\-list\-options\fP output). If this is too low, frame allocation may fail
3326 during decoding, and video frames might get dropped and/or corrupted.
3327 Setting it too high simply wastes GPU memory and has no advantages.
3328 .sp
3329 This value is used only for hardware decoding APIs which require
3330 preallocating surfaces (known examples include \fBd3d11va\fP and \fBvaapi\fP).
3331 For other APIs, frames are allocated as needed. The details depend on the
3332 libavcodec implementations of the hardware decoders.
3333 .sp
3334 The required number of surfaces depends on dynamic runtime situations. The
3335 default is a fixed value that is thought to be sufficient for most uses. But
3336 in certain situations, it may not be enough.
3337 .TP
3338 .B \fB\-\-hwdec\-image\-format=<name>\fP
3339 Set the internal pixel format used by hardware decoding via \fB\-\-hwdec\fP
3340 (default \fBno\fP). The special value \fBno\fP selects an implementation
3341 specific standard format. Most decoder implementations support only one
3342 format, and will fail to initialize if the format is not supported.
3343 .sp
3344 Some implementations might support multiple formats. In particular,
3345 videotoolbox is known to require \fBuyvy422\fP for good performance on some
3346 older hardware. d3d11va can always use \fByuv420p\fP, which uses an opaque
3347 format, with likely no advantages.
3348 .TP
3349 .B \fB\-\-cuda\-decode\-device=<auto|0..>\fP
3350 Choose the GPU device used for decoding when using the \fBcuda\fP or
3351 \fBnvdec\fP hwdecs with the OpenGL GPU backend, and with the \fBcuda\-copy\fP
3352 or \fBnvdec\-copy\fP hwdecs in all cases.
3353 .sp
3354 For the OpenGL GPU backend, the default device used for decoding is the one
3355 being used to provide \fBgpu\fP output (and in the vast majority of cases,
3356 only one GPU will be present).
3357 .sp
3358 For the \fBcopy\fP hwdecs, the default device will be the first device
3359 enumerated by the CUDA libraries \- however that is done.
3360 .sp
3361 For the Vulkan GPU backend, decoding must always happen on the display
3362 device, and this option has no effect.
3363 .TP
3364 .B \fB\-\-vaapi\-device=<device file>\fP
3365 Choose the DRM device for \fBvaapi\-copy\fP\&. This should be the path to a
3366 DRM device file. (Default: \fB/dev/dri/renderD128\fP)
3367 .TP
3368 .B \fB\-\-panscan=<0.0\-1.0>\fP
3369 Enables pan\-and\-scan functionality (cropping the sides of e.g. a 16:9
3370 video to make it fit a 4:3 display without black bands). The range
3371 controls how much of the image is cropped. May not work with all video
3372 output drivers.
3373 .sp
3374 This option has no effect if \fB\-\-video\-unscaled\fP option is used.
3375 .TP
3376 .B \fB\-\-video\-aspect\-override=<ratio|no>\fP
3377 Override video aspect ratio, in case aspect information is incorrect or
3378 missing in the file being played.
3379 .sp
3380 These values have special meaning:
3381 .INDENT 7.0
3382 .TP
3383 .B 0
3384 disable aspect ratio handling, pretend the video has square pixels
3385 .TP
3386 .B no
3387 same as \fB0\fP
3388 .TP
3389 .B \-1
3390 use the video stream or container aspect (default)
3391 .UNINDENT
3392 .sp
3393 But note that handling of these special values might change in the future.
3394 .INDENT 7.0
3395 .INDENT 3.5
3396 .IP "Examples"
3397 .INDENT 0.0
3398 .IP \(bu 2
3399 \fB\-\-video\-aspect\-override=4:3\fP or \fB\-\-video\-aspect\-override=1.3333\fP
3400 .IP \(bu 2
3401 \fB\-\-video\-aspect\-override=16:9\fP or \fB\-\-video\-aspect\-override=1.7777\fP
3402 .IP \(bu 2
3403 \fB\-\-no\-video\-aspect\-override\fP or \fB\-\-video\-aspect\-override=no\fP
3404 .UNINDENT
3405 .UNINDENT
3406 .UNINDENT
3407 .TP
3408 .B \fB\-\-video\-aspect\-method=<bitstream|container>\fP
3409 This sets the default video aspect determination method (if the aspect is
3410 _not_ overridden by the user with \fB\-\-video\-aspect\-override\fP or others).
3411 .INDENT 7.0
3412 .TP
3413 .B container
3414 Strictly prefer the container aspect ratio. This is apparently
3415 the default behavior with VLC, at least with Matroska. Note that
3416 if the container has no aspect ratio set, the behavior is the
3417 same as with bitstream.
3418 .TP
3419 .B bitstream
3420 Strictly prefer the bitstream aspect ratio, unless the bitstream
3421 aspect ratio is not set. This is apparently the default behavior
3422 with XBMC/kodi, at least with Matroska.
3423 .UNINDENT
3424 .sp
3425 The current default for mpv is \fBcontainer\fP\&.
3426 .sp
3427 Normally you should not set this. Try the various choices if you encounter
3428 video that has the wrong aspect ratio in mpv, but seems to be correct in
3429 other players.
3430 .TP
3431 .B \fB\-\-video\-unscaled=<no|yes|downscale\-big>\fP
3432 Disable scaling of the video. If the window is larger than the video,
3433 black bars are added. Otherwise, the video is cropped, unless the option
3434 is set to \fBdownscale\-big\fP, in which case the video is fit to window. The
3435 video still can be influenced by the other \fB\-\-video\-...\fP options. This
3436 option disables the effect of \fB\-\-panscan\fP\&.
3437 .sp
3438 Note that the scaler algorithm may still be used, even if the video isn\(aqt
3439 scaled. For example, this can influence chroma conversion. The video will
3440 also still be scaled in one dimension if the source uses non\-square pixels
3441 (e.g. anamorphic widescreen DVDs).
3442 .sp
3443 This option is disabled if the \fB\-\-no\-keepaspect\fP option is used.
3444 .TP
3445 .B \fB\-\-video\-pan\-x=<value>\fP, \fB\-\-video\-pan\-y=<value>\fP
3446 Moves the displayed video rectangle by the given value in the X or Y
3447 direction. The unit is in fractions of the size of the scaled video (the
3448 full size, even if parts of the video are not visible due to panscan or
3449 other options).
3450 .sp
3451 For example, displaying a 1280x720 video fullscreen on a 1680x1050 screen
3452 with \fB\-\-video\-pan\-x=\-0.1\fP would move the video 168 pixels to the left
3453 (making 128 pixels of the source video invisible).
3454 .sp
3455 This option is disabled if the \fB\-\-no\-keepaspect\fP option is used.
3456 .TP
3457 .B \fB\-\-video\-rotate=<0\-359|no>\fP
3458 Rotate the video clockwise, in degrees. Currently supports 90° steps only.
3459 If \fBno\fP is given, the video is never rotated, even if the file has
3460 rotation metadata. (The rotation value is added to the rotation metadata,
3461 which means the value \fB0\fP would rotate the video according to the
3462 rotation metadata.)
3463 .TP
3464 .B \fB\-\-video\-zoom=<value>\fP
3465 Adjust the video display scale factor by the given value. The parameter is
3466 given log 2. For example, \fB\-\-video\-zoom=0\fP is unscaled,
3467 \fB\-\-video\-zoom=1\fP is twice the size, \fB\-\-video\-zoom=\-2\fP is one fourth of
3468 the size, and so on.
3469 .sp
3470 This option is disabled if the \fB\-\-no\-keepaspect\fP option is used.
3471 .TP
3472 .B \fB\-\-video\-scale\-x=<value>\fP, \fB\-\-video\-scale\-y=<value>\fP
3473 Multiply the video display size with the given value (default: 1.0). If a
3474 non\-default value is used, this will be different from the window size, so
3475 video will be either cut off, or black bars are added.
3476 .sp
3477 This value is multiplied with the value derived from \fB\-\-video\-zoom\fP and
3478 the normal video aspect aspect ratio. This option is disabled if the
3479 \fB\-\-no\-keepaspect\fP option is used.
3480 .TP
3481 .B \fB\-\-video\-align\-x=<\-1\-1>\fP, \fB\-\-video\-align\-y=<\-1\-1>\fP
3482 Moves the video rectangle within the black borders, which are usually added
3483 to pad the video to screen if video and screen aspect ratios are different.
3484 \fB\-\-video\-align\-y=\-1\fP would move the video to the top of the screen
3485 (leaving a border only on the bottom), a value of \fB0\fP centers it
3486 (default), and a value of \fB1\fP would put the video at the bottom of the
3487 screen.
3488 .sp
3489 If video and screen aspect match perfectly, these options do nothing.
3490 .sp
3491 This option is disabled if the \fB\-\-no\-keepaspect\fP option is used.
3492 .TP
3493 .B \fB\-\-video\-margin\-ratio\-left=<val>\fP, \fB\-\-video\-margin\-ratio\-right=<val>\fP, \fB\-\-video\-margin\-ratio\-top=<val>\fP, \fB\-\-video\-margin\-ratio\-bottom=<val>\fP
3494 Set extra video margins on each border (default: 0). Each value is a ratio
3495 of the window size, using a range 0.0\-1.0. For example, setting the option
3496 \fB\-\-video\-margin\-ratio\-right=0.2\fP at a window size of 1000 pixels will add
3497 a 200 pixels border on the right side of the window.
3498 .sp
3499 The video is "boxed" by these margins. The window size is not changed. In
3500 particular it does not enlarge the window, and the margins will cause the
3501 video to be downscaled by default. This may or may not change in the future.
3502 .sp
3503 The margins are applied after 90° video rotation, but before any other video
3504 transformations.
3505 .sp
3506 This option is disabled if the \fB\-\-no\-keepaspect\fP option is used.
3507 .sp
3508 Subtitles still may use the margins, depending on \fB\-\-sub\-use\-margins\fP and
3509 similar options.
3510 .sp
3511 These options were created for the OSC. Some odd decisions, such as making
3512 the margin values a ratio (instead of pixels), were made for the sake of
3513 the OSC. It\(aqs possible that these options may be replaced by ones that are
3514 more generally useful. The behavior of these options may change to fit
3515 OSC requirements better, too.
3516 .TP
3517 .B \fB\-\-correct\-pts\fP, \fB\-\-no\-correct\-pts\fP
3518 \fB\-\-no\-correct\-pts\fP switches mpv to a mode where video timing is
3519 determined using a fixed framerate value (either using the \fB\-\-fps\fP
3520 option, or using file information). Sometimes, files with very broken
3521 timestamps can be played somewhat well in this mode. Note that video
3522 filters, subtitle rendering, seeking (including hr\-seeks and backstepping),
3523 and audio synchronization can be completely broken in this mode.
3524 .TP
3525 .B \fB\-\-fps=<float>\fP
3526 Override video framerate. Useful if the original value is wrong or missing.
3527 .sp
3528 \fBNOTE:\fP
3529 .INDENT 7.0
3530 .INDENT 3.5
3531 Works in \fB\-\-no\-correct\-pts\fP mode only.
3532 .UNINDENT
3533 .UNINDENT
3534 .TP
3535 .B \fB\-\-deinterlace=<yes|no>\fP
3536 Enable or disable interlacing (default: no).
3537 Interlaced video shows ugly comb\-like artifacts, which are visible on
3538 fast movement. Enabling this typically inserts the yadif video filter in
3539 order to deinterlace the video, or lets the video output apply deinterlacing
3540 if supported.
3541 .sp
3542 This behaves exactly like the \fBdeinterlace\fP input property (usually
3543 mapped to \fBd\fP).
3544 .sp
3545 Keep in mind that this \fBwill\fP conflict with manually inserted
3546 deinterlacing filters, unless you take care. (Since mpv 0.27.0, even the
3547 hardware deinterlace filters will conflict. Also since that version,
3548 \fB\-\-deinterlace=auto\fP was removed, which used to mean that the default
3549 interlacing option of possibly inserted video filters was used.)
3550 .sp
3551 Note that this will make video look worse if it\(aqs not actually interlaced.
3552 .TP
3553 .B \fB\-\-frames=<number>\fP
3554 Play/convert only first \fB<number>\fP video frames, then quit.
3555 .sp
3556 \fB\-\-frames=0\fP loads the file, but immediately quits before initializing
3557 playback. (Might be useful for scripts which just want to determine some
3558 file properties.)
3559 .sp
3560 For audio\-only playback, any value greater than 0 will quit playback
3561 immediately after initialization. The value 0 works as with video.
3562 .TP
3563 .B \fB\-\-video\-output\-levels=<outputlevels>\fP
3564 RGB color levels used with YUV to RGB conversion. Normally, output devices
3565 such as PC monitors use full range color levels. However, some TVs and
3566 video monitors expect studio RGB levels. Providing full range output to a
3567 device expecting studio level input results in crushed blacks and whites,
3568 the reverse in dim gray blacks and dim whites.
3569 .sp
3570 Not all VOs support this option. Some will silently ignore it.
3571 .sp
3572 Available color ranges are:
3573 .INDENT 7.0
3574 .TP
3575 .B auto
3576 automatic selection (equals to full range) (default)
3577 .TP
3578 .B limited
3579 limited range (16\-235 per component), studio levels
3580 .TP
3581 .B full
3582 full range (0\-255 per component), PC levels
3583 .UNINDENT
3584 .sp
3585 \fBNOTE:\fP
3586 .INDENT 7.0
3587 .INDENT 3.5
3588 It is advisable to use your graphics driver\(aqs color range option
3589 instead, if available.
3590 .UNINDENT
3591 .UNINDENT
3592 .TP
3593 .B \fB\-\-hwdec\-codecs=<codec1,codec2,...|all>\fP
3594 Allow hardware decoding for a given list of codecs only. The special value
3595 \fBall\fP always allows all codecs.
3596 .sp
3597 You can get the list of allowed codecs with \fBmpv \-\-vd=help\fP\&. Remove the
3598 prefix, e.g. instead of \fBlavc:h264\fP use \fBh264\fP\&.
3599 .sp
3600 By default, this is set to \fBh264,vc1,hevc,vp9,av1\fP\&. Note that
3601 the hardware acceleration special codecs like \fBh264_vdpau\fP are not
3602 relevant anymore, and in fact have been removed from Libav in this form.
3603 .sp
3604 This is usually only needed with broken GPUs, where a codec is reported
3605 as supported, but decoding causes more problems than it solves.
3606 .INDENT 7.0
3607 .INDENT 3.5
3608 .IP "Example"
3609 .INDENT 0.0
3610 .TP
3611 .B \fBmpv \-\-hwdec=vdpau \-\-vo=vdpau \-\-hwdec\-codecs=h264,mpeg2video\fP
3612 Enable vdpau decoding for h264 and mpeg2 only.
3613 .UNINDENT
3614 .UNINDENT
3615 .UNINDENT
3616 .TP
3617 .B \fB\-\-vd\-lavc\-check\-hw\-profile=<yes|no>\fP
3618 Check hardware decoder profile (default: yes). If \fBno\fP is set, the
3619 highest profile of the hardware decoder is unconditionally selected, and
3620 decoding is forced even if the profile of the video is higher than that.
3621 The result is most likely broken decoding, but may also help if the
3622 detected or reported profiles are somehow incorrect.
3623 .TP
3624 .B \fB\-\-vd\-lavc\-software\-fallback=<yes|no|N>\fP
3625 Fallback to software decoding if the hardware\-accelerated decoder fails
3626 (default: 3). If this is a number, then fallback will be triggered if
3627 N frames fail to decode in a row. 1 is equivalent to \fByes\fP\&.
3628 .sp
3629 Setting this to a higher number might break the playback start fallback: if
3630 a fallback happens, parts of the file will be skipped, approximately by to
3631 the number of packets that could not be decoded. Values below an unspecified
3632 count will not have this problem, because mpv retains the packets.
3633 .TP
3634 .B \fB\-\-vd\-lavc\-dr=<yes|no>\fP
3635 Enable direct rendering (default: yes). If this is set to \fByes\fP, the
3636 video will be decoded directly to GPU video memory (or staging buffers).
3637 This can speed up video upload, and may help with large resolutions or
3638 slow hardware. This works only with the following VOs:
3639 .INDENT 7.0
3640 .INDENT 3.5
3641 .INDENT 0.0
3642 .IP \(bu 2
3643 \fBgpu\fP: requires at least OpenGL 4.4 or Vulkan.
3644 .UNINDENT
3645 .UNINDENT
3646 .UNINDENT
3647 .sp
3648 (In particular, this can\(aqt be made work with \fBopengl\-cb\fP, but the libmpv
3649 render API has optional support.)
3650 .sp
3651 Using video filters of any kind that write to the image data (or output
3652 newly allocated frames) will silently disable the DR code path.
3653 .TP
3654 .B \fB\-\-vd\-lavc\-bitexact\fP
3655 Only use bit\-exact algorithms in all decoding steps (for codec testing).
3656 .TP
3657 .B \fB\-\-vd\-lavc\-fast\fP (MPEG\-2, MPEG\-4, and H.264 only)
3658 Enable optimizations which do not comply with the format specification and
3659 potentially cause problems, like simpler dequantization, simpler motion
3660 compensation, assuming use of the default quantization matrix, assuming YUV
3661 4:2:0 and skipping a few checks to detect damaged bitstreams.
3662 .TP
3663 .B \fB\-\-vd\-lavc\-o=<key>=<value>[,<key>=<value>[,...]]\fP
3664 Pass AVOptions to libavcodec decoder. Note, a patch to make the \fBo=\fP
3665 unneeded and pass all unknown options through the AVOption system is
3666 welcome. A full list of AVOptions can be found in the FFmpeg manual.
3667 .sp
3668 Some options which used to be direct options can be set with this
3669 mechanism, like \fBbug\fP, \fBgray\fP, \fBidct\fP, \fBec\fP, \fBvismv\fP,
3670 \fBskip_top\fP (was \fBst\fP), \fBskip_bottom\fP (was \fBsb\fP), \fBdebug\fP\&.
3671 .sp
3672 This is a key/value list option. See \fI\%List Options\fP for details.
3673 .INDENT 7.0
3674 .INDENT 3.5
3675 .IP "Example"
3676 .sp
3677 \fB\-\-vd\-lavc\-o=debug=pict\fP
3678 .UNINDENT
3679 .UNINDENT
3680 .TP
3681 .B \fB\-\-vd\-lavc\-show\-all=<yes|no>\fP
3682 Show even broken/corrupt frames (default: no). If this option is set to
3683 no, libavcodec won\(aqt output frames that were either decoded before an
3684 initial keyframe was decoded, or frames that are recognized as corrupted.
3685 .TP
3686 .B \fB\-\-vd\-lavc\-skiploopfilter=<skipvalue> (H.264 only)\fP
3687 Skips the loop filter (AKA deblocking) during H.264 decoding. Since
3688 the filtered frame is supposed to be used as reference for decoding
3689 dependent frames, this has a worse effect on quality than not doing
3690 deblocking on e.g. MPEG\-2 video. But at least for high bitrate HDTV,
3691 this provides a big speedup with little visible quality loss.
3692 .sp
3693 \fB<skipvalue>\fP can be one of the following:
3694 .INDENT 7.0
3695 .TP
3696 .B none
3697 Never skip.
3698 .TP
3699 .B default
3700 Skip useless processing steps (e.g. 0 size packets in AVI).
3701 .TP
3702 .B nonref
3703 Skip frames that are not referenced (i.e. not used for
3704 decoding other frames, the error cannot "build up").
3705 .TP
3706 .B bidir
3707 Skip B\-Frames.
3708 .TP
3709 .B nonkey
3710 Skip all frames except keyframes.
3711 .TP
3712 .B all
3713 Skip all frames.
3714 .UNINDENT
3715 .TP
3716 .B \fB\-\-vd\-lavc\-skipidct=<skipvalue> (MPEG\-1/2 only)\fP
3717 Skips the IDCT step. This degrades quality a lot in almost all cases
3718 (see skiploopfilter for available skip values).
3719 .TP
3720 .B \fB\-\-vd\-lavc\-skipframe=<skipvalue>\fP
3721 Skips decoding of frames completely. Big speedup, but jerky motion and
3722 sometimes bad artifacts (see skiploopfilter for available skip values).
3723 .TP
3724 .B \fB\-\-vd\-lavc\-framedrop=<skipvalue>\fP
3725 Set framedropping mode used with \fB\-\-framedrop\fP (see skiploopfilter for
3726 available skip values).
3727 .TP
3728 .B \fB\-\-vd\-lavc\-threads=<N>\fP
3729 Number of threads to use for decoding. Whether threading is actually
3730 supported depends on codec (default: 0). 0 means autodetect number of cores
3731 on the machine and use that, up to the maximum of 16. You can set more than
3732 16 threads manually.
3733 .TP
3734 .B \fB\-\-vd\-lavc\-assume\-old\-x264=<yes|no>\fP
3735 Assume the video was encoded by an old, buggy x264 version (default: no).
3736 Normally, this is autodetected by libavcodec. But if the bitstream contains
3737 no x264 version info (or it was somehow skipped), and the stream was in fact
3738 encoded by an old x264 version (build 150 or earlier), and if the stream
3739 uses \fB4:4:4\fP chroma, then libavcodec will by default show corrupted video.
3740 This option sets the libavcodec \fBx264_build\fP option to \fB150\fP, which
3741 means that if the stream contains no version info, or was not encoded by
3742 x264 at all, it assumes it was encoded by the old version. Enabling this
3743 option is pretty safe if you want your broken files to work, but in theory
3744 this can break on streams not encoded by x264, or if a stream encoded by a
3745 newer x264 version contains no version info.
3746 .TP
3747 .B \fB\-\-swapchain\-depth=<N>\fP
3748 Allow up to N in\-flight frames. This essentially controls the frame
3749 latency. Increasing the swapchain depth can improve pipelining and prevent
3750 missed vsyncs, but increases visible latency. This option only mandates an
3751 upper limit, the implementation can use a lower latency than requested
3752 internally. A setting of 1 means that the VO will wait for every frame to
3753 become visible before starting to render the next frame. (Default: 3)
3754 .UNINDENT
3755 .SS Audio
3756 .INDENT 0.0
3757 .TP
3758 .B \fB\-\-audio\-pitch\-correction=<yes|no>\fP
3759 If this is enabled (default), playing with a speed different from normal
3760 automatically inserts the \fBscaletempo\fP audio filter. For details, see
3761 audio filter section.
3762 .TP
3763 .B \fB\-\-audio\-device=<name>\fP
3764 Use the given audio device. This consists of the audio output name, e.g.
3765 \fBalsa\fP, followed by \fB/\fP, followed by the audio output specific device
3766 name. The default value for this option is \fBauto\fP, which tries every audio
3767 output in preference order with the default device.
3768 .sp
3769 You can list audio devices with \fB\-\-audio\-device=help\fP\&. This outputs the
3770 device name in quotes, followed by a description. The device name is what
3771 you have to pass to the \fB\-\-audio\-device\fP option. The list of audio devices
3772 can be retrieved by API by using the \fBaudio\-device\-list\fP property.
3773 .sp
3774 While the option normally takes one of the strings as indicated by the
3775 methods above, you can also force the device for most AOs by building it
3776 manually. For example \fBname/foobar\fP forces the AO \fBname\fP to use the
3777 device \fBfoobar\fP\&. However, the \fB\-\-ao\fP option will strictly force a
3778 specific AO. To avoid confusion, don\(aqt use \fB\-\-ao\fP and \fB\-\-audio\-device\fP
3779 together.
3780 .INDENT 7.0
3781 .INDENT 3.5
3782 .IP "Example for ALSA"
3783 .sp
3784 MPlayer and mplayer2 required you to replace any \(aq,\(aq with \(aq.\(aq and
3785 any \(aq:\(aq with \(aq=\(aq in the ALSA device name. For example, to use the
3786 device named \fBdmix:default\fP, you had to do:
3787 .INDENT 0.0
3788 .INDENT 3.5
3789 \fB\-ao alsa:device=dmix=default\fP
3790 .UNINDENT
3791 .UNINDENT
3792 .sp
3793 In mpv you could instead use:
3794 .INDENT 0.0
3795 .INDENT 3.5
3796 \fB\-\-audio\-device=alsa/dmix:default\fP
3797 .UNINDENT
3798 .UNINDENT
3799 .UNINDENT
3800 .UNINDENT
3801 .TP
3802 .B \fB\-\-audio\-exclusive=<yes|no>\fP
3803 Enable exclusive output mode. In this mode, the system is usually locked
3804 out, and only mpv will be able to output audio.
3805 .sp
3806 This only works for some audio outputs, such as \fBwasapi\fP and
3807 \fBcoreaudio\fP\&. Other audio outputs silently ignore this options. They either
3808 have no concept of exclusive mode, or the mpv side of the implementation is
3809 missing.
3810 .TP
3811 .B \fB\-\-audio\-fallback\-to\-null=<yes|no>\fP
3812 If no audio device can be opened, behave as if \fB\-\-ao=null\fP was given. This
3813 is useful in combination with \fB\-\-audio\-device\fP: instead of causing an
3814 error if the selected device does not exist, the client API user (or a
3815 Lua script) could let playback continue normally, and check the
3816 \fBcurrent\-ao\fP and \fBaudio\-device\-list\fP properties to make high\-level
3817 decisions about how to continue.
3818 .TP
3819 .B \fB\-\-ao=<driver>\fP
3820 Specify the audio output drivers to be used. See \fI\%AUDIO OUTPUT DRIVERS\fP for
3821 details and descriptions of available drivers.
3822 .TP
3823 .B \fB\-\-af=<filter1[=parameter1:parameter2:...],filter2,...>\fP
3824 Specify a list of audio filters to apply to the audio stream. See
3825 \fI\%AUDIO FILTERS\fP for details and descriptions of the available filters.
3826 The option variants \fB\-\-af\-add\fP, \fB\-\-af\-pre\fP, \fB\-\-af\-del\fP and
3827 \fB\-\-af\-clr\fP exist to modify a previously specified list, but you
3828 should not need these for typical use.
3829 .TP
3830 .B \fB\-\-audio\-spdif=<codecs>\fP
3831 List of codecs for which compressed audio passthrough should be used. This
3832 works for both classic S/PDIF and HDMI.
3833 .sp
3834 Possible codecs are \fBac3\fP, \fBdts\fP, \fBdts\-hd\fP, \fBeac3\fP, \fBtruehd\fP\&.
3835 Multiple codecs can be specified by separating them with \fB,\fP\&. \fBdts\fP
3836 refers to low bitrate DTS core, while \fBdts\-hd\fP refers to DTS MA (receiver
3837 and OS support varies). If both \fBdts\fP and \fBdts\-hd\fP are specified, it
3838 behaves equivalent to specifying \fBdts\-hd\fP only.
3839 .sp
3840 In earlier mpv versions you could use \fB\-\-ad\fP to force the spdif wrapper.
3841 This does not work anymore.
3842 .INDENT 7.0
3843 .INDENT 3.5
3844 .IP "Warning"
3845 .sp
3846 There is not much reason to use this. HDMI supports uncompressed
3847 multichannel PCM, and mpv supports lossless DTS\-HD decoding via
3848 FFmpeg\(aqs new DCA decoder (based on libdcadec).
3849 .UNINDENT
3850 .UNINDENT
3851 .TP
3852 .B \fB\-\-ad=<decoder1,decoder2,...[\-]>\fP
3853 Specify a priority list of audio decoders to be used, according to their
3854 decoder name. When determining which decoder to use, the first decoder that
3855 matches the audio format is selected. If that is unavailable, the next
3856 decoder is used. Finally, it tries all other decoders that are not
3857 explicitly selected or rejected by the option.
3858 .sp
3859 \fB\-\fP at the end of the list suppresses fallback on other available
3860 decoders not on the \fB\-\-ad\fP list. \fB+\fP in front of an entry forces the
3861 decoder. Both of these should not normally be used, because they break
3862 normal decoder auto\-selection! Both of these methods are deprecated.
3863 .INDENT 7.0
3864 .INDENT 3.5
3865 .IP "Examples"
3866 .INDENT 0.0
3867 .TP
3868 .B \fB\-\-ad=mp3float\fP
3869 Prefer the FFmpeg/Libav \fBmp3float\fP decoder over all other MP3
3870 decoders.
3871 .TP
3872 .B \fB\-\-ad=help\fP
3873 List all available decoders.
3874 .UNINDENT
3875 .UNINDENT
3876 .UNINDENT
3877 .INDENT 7.0
3878 .INDENT 3.5
3879 .IP "Warning"
3880 .sp
3881 Enabling compressed audio passthrough (AC3 and DTS via SPDIF/HDMI) with
3882 this option is not possible. Use \fB\-\-audio\-spdif\fP instead.
3883 .UNINDENT
3884 .UNINDENT
3885 .TP
3886 .B \fB\-\-volume=<value>\fP
3887 Set the startup volume. 0 means silence, 100 means no volume reduction or
3888 amplification. Negative values can be passed for compatibility, but are
3889 treated as 0.
3890 .sp
3891 Since mpv 0.18.1, this always controls the internal mixer (aka "softvol").
3892 .TP
3893 .B \fB\-\-replaygain=<no|track|album>\fP
3894 Adjust volume gain according to replaygain values stored in the file
3895 metadata. With \fB\-\-replaygain=no\fP (the default), perform no adjustment.
3896 With \fB\-\-replaygain=track\fP, apply track gain. With \fB\-\-replaygain=album\fP,
3897 apply album gain if present and fall back to track gain otherwise.
3898 .TP
3899 .B \fB\-\-replaygain\-preamp=<db>\fP
3900 Pre\-amplification gain in dB to apply to the selected replaygain gain
3901 (default: 0).
3902 .TP
3903 .B \fB\-\-replaygain\-clip=<yes|no>\fP
3904 Prevent clipping caused by replaygain by automatically lowering the
3905 gain (default). Use \fB\-\-replaygain\-clip=no\fP to disable this.
3906 .TP
3907 .B \fB\-\-replaygain\-fallback=<db>\fP
3908 Gain in dB to apply if the file has no replay gain tags. This option
3909 is always applied if the replaygain logic is somehow inactive. If this
3910 is applied, no other replaygain options are applied.
3911 .TP
3912 .B \fB\-\-audio\-delay=<sec>\fP
3913 Audio delay in seconds (positive or negative float value). Positive values
3914 delay the audio, and negative values delay the video.
3915 .TP
3916 .B \fB\-\-mute=<yes|no|auto>\fP
3917 Set startup audio mute status (default: no).
3918 .sp
3919 \fBauto\fP is a deprecated possible value that is equivalent to \fBno\fP\&.
3920 .sp
3921 See also: \fB\-\-volume\fP\&.
3922 .TP
3923 .B \fB\-\-softvol=<no|yes|auto>\fP
3924 Deprecated/unfunctional. Before mpv 0.18.1, this used to control whether
3925 to use the volume controls of the audio output driver or the internal mpv
3926 volume filter.
3927 .sp
3928 The current behavior is that softvol is always enabled, i.e. as if this
3929 option is set to \fByes\fP\&. The other behaviors are not available anymore,
3930 although \fBauto\fP almost matches current behavior in most cases.
3931 .sp
3932 The \fBno\fP behavior is still partially available through the \fBao\-volume\fP
3933 and \fBao\-mute\fP properties. But there are no options to reset these.
3934 .TP
3935 .B \fB\-\-audio\-demuxer=<[+]name>\fP
3936 Use this audio demuxer type when using \fB\-\-audio\-file\fP\&. Use a \(aq+\(aq before
3937 the name to force it; this will skip some checks. Give the demuxer name as
3938 printed by \fB\-\-audio\-demuxer=help\fP\&.
3939 .TP
3940 .B \fB\-\-ad\-lavc\-ac3drc=<level>\fP
3941 Select the Dynamic Range Compression level for AC\-3 audio streams.
3942 \fB<level>\fP is a float value ranging from 0 to 1, where 0 means no
3943 compression (which is the default) and 1 means full compression (make loud
3944 passages more silent and vice versa). Values up to 6 are also accepted, but
3945 are purely experimental. This option only shows an effect if the AC\-3 stream
3946 contains the required range compression information.
3947 .sp
3948 The standard mandates that DRC is enabled by default, but mpv (and some
3949 other players) ignore this for the sake of better audio quality.
3950 .TP
3951 .B \fB\-\-ad\-lavc\-downmix=<yes|no>\fP
3952 Whether to request audio channel downmixing from the decoder (default: no).
3953 Some decoders, like AC\-3, AAC and DTS, can remix audio on decoding. The
3954 requested number of output channels is set with the \fB\-\-audio\-channels\fP option.
3955 Useful for playing surround audio on a stereo system.
3956 .TP
3957 .B \fB\-\-ad\-lavc\-threads=<0\-16>\fP
3958 Number of threads to use for decoding. Whether threading is actually
3959 supported depends on codec. As of this writing, it\(aqs supported for some
3960 lossless codecs only. 0 means autodetect number of cores on the
3961 machine and use that, up to the maximum of 16 (default: 1).
3962 .TP
3963 .B \fB\-\-ad\-lavc\-o=<key>=<value>[,<key>=<value>[,...]]\fP
3964 Pass AVOptions to libavcodec decoder. Note, a patch to make the o=
3965 unneeded and pass all unknown options through the AVOption system is
3966 welcome. A full list of AVOptions can be found in the FFmpeg manual.
3967 .sp
3968 This is a key/value list option. See \fI\%List Options\fP for details.
3969 .TP
3970 .B \fB\-\-ad\-spdif\-dtshd=<yes|no>\fP, \fB\-\-dtshd\fP, \fB\-\-no\-dtshd\fP
3971 If DTS is passed through, use DTS\-HD.
3972 .INDENT 7.0
3973 .INDENT 3.5
3974 .IP "Warning"
3975 .sp
3976 This and enabling passthrough via \fB\-\-ad\fP are deprecated in favor of
3977 using \fB\-\-audio\-spdif=dts\-hd\fP\&.
3978 .UNINDENT
3979 .UNINDENT
3980 .TP
3981 .B \fB\-\-audio\-channels=<auto\-safe|auto|layouts>\fP
3982 Control which audio channels are output (e.g. surround vs. stereo). There
3983 are the following possibilities:
3984 .INDENT 7.0
3985 .IP \(bu 2
3986 .INDENT 2.0
3987 .TP
3988 .B \fB\-\-audio\-channels=auto\-safe\fP
3989 Use the system\(aqs preferred channel layout. If there is none (such
3990 as when accessing a hardware device instead of the system mixer),
3991 force stereo. Some audio outputs might simply accept any layout and
3992 do downmixing on their own.
3993 .sp
3994 This is the default.
3995 .UNINDENT
3996 .IP \(bu 2
3997 .INDENT 2.0
3998 .TP
3999 .B \fB\-\-audio\-channels=auto\fP
4000 Send the audio device whatever it accepts, preferring the audio\(aqs
4001 original channel layout. Can cause issues with HDMI (see the warning
4002 below).
4003 .UNINDENT
4004 .IP \(bu 2
4005 .INDENT 2.0
4006 .TP
4007 .B \fB\-\-audio\-channels=layout1,layout2,...\fP
4008 List of \fB,\fP\-separated channel layouts which should be allowed.
4009 Technically, this only adjusts the filter chain output to the best
4010 matching layout in the list, and passes the result to the audio API.
4011 It\(aqs possible that the audio API will select a different channel
4012 layout.
4013 .sp
4014 Using this mode is recommended for direct hardware output, especially
4015 over HDMI (see HDMI warning below).
4016 .UNINDENT
4017 .IP \(bu 2
4018 .INDENT 2.0
4019 .TP
4020 .B \fB\-\-audio\-channels=stereo\fP
4021 Force a plain stereo downmix. This is a special\-case of the previous
4022 item. (See paragraphs below for implications.)
4023 .UNINDENT
4024 .UNINDENT
4025 .sp
4026 If a list of layouts is given, each item can be either an explicit channel
4027 layout name (like \fB5.1\fP), or a channel number. Channel numbers refer to
4028 default layouts, e.g. 2 channels refer to stereo, 6 refers to 5.1.
4029 .sp
4030 See \fB\-\-audio\-channels=help\fP output for defined default layouts. This also
4031 lists speaker names, which can be used to express arbitrary channel
4032 layouts (e.g. \fBfl\-fr\-lfe\fP is 2.1).
4033 .sp
4034 If the list of channel layouts has only 1 item, the decoder is asked to
4035 produce according output. This sometimes triggers decoder\-downmix, which
4036 might be different from the normal mpv downmix. (Only some decoders support
4037 remixing audio, like AC\-3, AAC or DTS. You can use \fB\-\-ad\-lavc\-downmix=no\fP
4038 to make the decoder always output its native layout.) One consequence is
4039 that \fB\-\-audio\-channels=stereo\fP triggers decoder downmix, while \fBauto\fP
4040 or \fBauto\-safe\fP never will, even if they end up selecting stereo. This
4041 happens because the decision whether to use decoder downmix happens long
4042 before the audio device is opened.
4043 .sp
4044 If the channel layout of the media file (i.e. the decoder) and the AO\(aqs
4045 channel layout don\(aqt match, mpv will attempt to insert a conversion filter.
4046 You may need to change the channel layout of the system mixer to achieve
4047 your desired output as mpv does not have control over it. Another
4048 work\-around for this on some AOs is to use \fB\-\-audio\-exclusive=yes\fP to
4049 circumvent the system mixer entirely.
4050 .INDENT 7.0
4051 .INDENT 3.5
4052 .IP "Warning"
4053 .sp
4054 Using \fBauto\fP can cause issues when using audio over HDMI. The OS will
4055 typically report all channel layouts that _can_ go over HDMI, even if
4056 the receiver does not support them. If a receiver gets an unsupported
4057 channel layout, random things can happen, such as dropping the
4058 additional channels, or adding noise.
4059 .sp
4060 You are recommended to set an explicit whitelist of the layouts you
4061 want. For example, most A/V receivers connected via HDMI and that can
4062 do 7.1 would be served by: \fB\-\-audio\-channels=7.1,5.1,stereo\fP
4063 .UNINDENT
4064 .UNINDENT
4065 .TP
4066 .B \fB\-\-audio\-display=<no|attachment>\fP
4067 Setting this option to \fBattachment\fP (default) will display image
4068 attachments (e.g. album cover art) when playing audio files. It will
4069 display the first image found, and additional images are available as
4070 video tracks.
4071 .sp
4072 Setting this option to \fBno\fP disables display of video entirely when
4073 playing audio files.
4074 .sp
4075 This option has no influence on files with normal video tracks.
4076 .TP
4077 .B \fB\-\-audio\-files=<files>\fP
4078 Play audio from an external file while viewing a video.
4079 .sp
4080 This is a path list option. See \fI\%List Options\fP for details.
4081 .TP
4082 .B \fB\-\-audio\-file=<file>\fP
4083 CLI/config file only alias for \fB\-\-audio\-files\-append\fP\&. Each use of this
4084 option will add a new audio track. The details are similar to how
4085 \fB\-\-sub\-file\fP works.
4086 .TP
4087 .B \fB\-\-audio\-format=<format>\fP
4088 Select the sample format used for output from the audio filter layer to
4089 the sound card. The values that \fB<format>\fP can adopt are listed below in
4090 the description of the \fBformat\fP audio filter.
4091 .TP
4092 .B \fB\-\-audio\-samplerate=<Hz>\fP
4093 Select the output sample rate to be used (of course sound cards have
4094 limits on this). If the sample frequency selected is different from that
4095 of the current media, the lavrresample audio filter will be inserted into
4096 the audio filter layer to compensate for the difference.
4097 .TP
4098 .B \fB\-\-gapless\-audio=<no|yes|weak>\fP
4099 Try to play consecutive audio files with no silence or disruption at the
4100 point of file change. Default: \fBweak\fP\&.
4101 .INDENT 7.0
4102 .TP
4103 .B no
4104 Disable gapless audio.
4105 .TP
4106 .B yes
4107 The audio device is opened using parameters chosen for the first
4108 file played and is then kept open for gapless playback. This
4109 means that if the first file for example has a low sample rate, then
4110 the following files may get resampled to the same low sample rate,
4111 resulting in reduced sound quality. If you play files with different
4112 parameters, consider using options such as \fB\-\-audio\-samplerate\fP
4113 and \fB\-\-audio\-format\fP to explicitly select what the shared output
4114 format will be.
4115 .TP
4116 .B weak
4117 Normally, the audio device is kept open (using the format it was
4118 first initialized with). If the audio format the decoder output
4119 changes, the audio device is closed and reopened. This means that
4120 you will normally get gapless audio with files that were encoded
4121 using the same settings, but might not be gapless in other cases.
4122 The exact conditions under which the audio device is kept open is
4123 an implementation detail, and can change from version to version.
4124 Currently, the device is kept even if the sample format changes,
4125 but the sample formats are convertible.
4126 If video is still going on when there is still audio, trying to use
4127 gapless is also explicitly given up.
4128 .UNINDENT
4129 .sp
4130 \fBNOTE:\fP
4131 .INDENT 7.0
4132 .INDENT 3.5
4133 This feature is implemented in a simple manner and relies on audio
4134 output device buffering to continue playback while moving from one file
4135 to another. If playback of the new file starts slowly, for example
4136 because it is played from a remote network location or because you have
4137 specified cache settings that require time for the initial cache fill,
4138 then the buffered audio may run out before playback of the new file
4139 can start.
4140 .UNINDENT
4141 .UNINDENT
4142 .TP
4143 .B \fB\-\-initial\-audio\-sync\fP, \fB\-\-no\-initial\-audio\-sync\fP
4144 When starting a video file or after events such as seeking, mpv will by
4145 default modify the audio stream to make it start from the same timestamp
4146 as video, by either inserting silence at the start or cutting away the
4147 first samples. Disabling this option makes the player behave like older
4148 mpv versions did: video and audio are both started immediately even if
4149 their start timestamps differ, and then video timing is gradually adjusted
4150 if necessary to reach correct synchronization later.
4151 .TP
4152 .B \fB\-\-volume\-max=<100.0\-1000.0>\fP, \fB\-\-softvol\-max=<...>\fP
4153 Set the maximum amplification level in percent (default: 130). A value of
4154 130 will allow you to adjust the volume up to about double the normal level.
4155 .sp
4156 \fB\-\-softvol\-max\fP is a deprecated alias and should not be used.
4157 .TP
4158 .B \fB\-\-audio\-file\-auto=<no|exact|fuzzy|all>\fP, \fB\-\-no\-audio\-file\-auto\fP
4159 Load additional audio files matching the video filename. The parameter
4160 specifies how external audio files are matched.
4161 .INDENT 7.0
4162 .TP
4163 .B no
4164 Don\(aqt automatically load external audio files (default).
4165 .TP
4166 .B exact
4167 Load the media filename with audio file extension.
4168 .TP
4169 .B fuzzy
4170 Load all audio files containing media filename.
4171 .TP
4172 .B all
4173 Load all audio files in the current and \fB\-\-audio\-file\-paths\fP
4174 directories.
4175 .UNINDENT
4176 .TP
4177 .B \fB\-\-audio\-file\-paths=<path1:path2:...>\fP
4178 Equivalent to \fB\-\-sub\-file\-paths\fP option, but for auto\-loaded audio files.
4179 .sp
4180 This is a path list option. See \fI\%List Options\fP for details.
4181 .TP
4182 .B \fB\-\-audio\-client\-name=<name>\fP
4183 The application name the player reports to the audio API. Can be useful
4184 if you want to force a different audio profile (e.g. with PulseAudio),
4185 or to set your own application name when using libmpv.
4186 .TP
4187 .B \fB\-\-audio\-buffer=<seconds>\fP
4188 Set the audio output minimum buffer. The audio device might actually create
4189 a larger buffer if it pleases. If the device creates a smaller buffer,
4190 additional audio is buffered in an additional software buffer.
4191 .sp
4192 Making this larger will make soft\-volume and other filters react slower,
4193 introduce additional issues on playback speed change, and block the
4194 player on audio format changes. A smaller buffer might lead to audio
4195 dropouts.
4196 .sp
4197 This option should be used for testing only. If a non\-default value helps
4198 significantly, the mpv developers should be contacted.
4199 .sp
4200 Default: 0.2 (200 ms).
4201 .TP
4202 .B \fB\-\-audio\-stream\-silence=<yes|no>\fP
4203 Cash\-grab consumer audio hardware (such as A/V receivers) often ignore
4204 initial audio sent over HDMI. This can happen every time audio over HDMI
4205 is stopped and resumed. In order to compensate for this, you can enable
4206 this option to not to stop and restart audio on seeks, and fill the gaps
4207 with silence. Likewise, when pausing playback, audio is not stopped, and
4208 silence is played while paused. Note that if no audio track is selected,
4209 the audio device will still be closed immediately.
4210 .sp
4211 Not all AOs support this.
4212 .INDENT 7.0
4213 .INDENT 3.5
4214 .IP "Warning"
4215 .sp
4216 This modifies certain subtle player behavior, like A/V\-sync and underrun
4217 handling. Enabling this option is strongly discouraged.
4218 .UNINDENT
4219 .UNINDENT
4220 .TP
4221 .B \fB\-\-audio\-wait\-open=<secs>\fP
4222 This makes sense for use with \fB\-\-audio\-stream\-silence=yes\fP\&. If this option
4223 is given, the player will wait for the given amount of seconds after opening
4224 the audio device before sending actual audio data to it. Useful if your
4225 expensive hardware discards the first 1 or 2 seconds of audio data sent to
4226 it. If \fB\-\-audio\-stream\-silence=yes\fP is not set, this option will likely
4227 just waste time.
4228 .UNINDENT
4229 .SS Subtitles
4230 .sp
4231 \fBNOTE:\fP
4232 .INDENT 0.0
4233 .INDENT 3.5
4234 Changing styling and position does not work with all subtitles. Image\-based
4235 subtitles (DVD, Bluray/PGS, DVB) cannot changed for fundamental reasons.
4236 Subtitles in ASS format are normally not changed intentionally, but
4237 overriding them can be controlled with \fB\-\-sub\-ass\-override\fP\&.
4238 .sp
4239 Previously some options working on text subtitles were called
4240 \fB\-\-sub\-text\-*\fP, they are now named \fB\-\-sub\-*\fP, and those specifically
4241 for ASS have been renamed from \fB\-\-ass\-*\fP to \fB\-\-sub\-ass\-*\fP\&.
4242 They are now all in this section.
4243 .UNINDENT
4244 .UNINDENT
4245 .INDENT 0.0
4246 .TP
4247 .B \fB\-\-sub\-demuxer=<[+]name>\fP
4248 Force subtitle demuxer type for \fB\-\-sub\-file\fP\&. Give the demuxer name as
4249 printed by \fB\-\-sub\-demuxer=help\fP\&.
4250 .TP
4251 .B \fB\-\-sub\-delay=<sec>\fP
4252 Delays subtitles by \fB<sec>\fP seconds. Can be negative.
4253 .TP
4254 .B \fB\-\-sub\-files=<file\-list>\fP, \fB\-\-sub\-file=<filename>\fP
4255 Add a subtitle file to the list of external subtitles.
4256 .sp
4257 If you use \fB\-\-sub\-file\fP only once, this subtitle file is displayed by
4258 default.
4259 .sp
4260 If \fB\-\-sub\-file\fP is used multiple times, the subtitle to use can be
4261 switched at runtime by cycling subtitle tracks. It\(aqs possible to show
4262 two subtitles at once: use \fB\-\-sid\fP to select the first subtitle index,
4263 and \fB\-\-secondary\-sid\fP to select the second index. (The index is printed
4264 on the terminal output after the \fB\-\-sid=\fP in the list of streams.)
4265 .sp
4266 \fB\-\-sub\-files\fP is a path list option (see \fI\%List Options\fP for details), and
4267 can take multiple file names separated by \fB:\fP (Unix) or \fB;\fP (Windows),
4268 while \fB\-\-sub\-file\fP takes a single filename, but can be used multiple
4269 times to add multiple files. Technically, \fB\-\-sub\-file\fP is a CLI/config
4270 file only alias for \fB\-\-sub\-files\-append\fP\&.
4271 .TP
4272 .B \fB\-\-secondary\-sid=<ID|auto|no>\fP
4273 Select a secondary subtitle stream. This is similar to \fB\-\-sid\fP\&. If a
4274 secondary subtitle is selected, it will be rendered as toptitle (i.e. on
4275 the top of the screen) alongside the normal subtitle, and provides a way
4276 to render two subtitles at once.
4277 .sp
4278 There are some caveats associated with this feature. For example, bitmap
4279 subtitles will always be rendered in their usual position, so selecting a
4280 bitmap subtitle as secondary subtitle will result in overlapping subtitles.
4281 Secondary subtitles are never shown on the terminal if video is disabled.
4282 .sp
4283 \fBNOTE:\fP
4284 .INDENT 7.0
4285 .INDENT 3.5
4286 Styling and interpretation of any formatting tags is disabled for the
4287 secondary subtitle. Internally, the same mechanism as \fB\-\-no\-sub\-ass\fP
4288 is used to strip the styling.
4289 .UNINDENT
4290 .UNINDENT
4291 .sp
4292 \fBNOTE:\fP
4293 .INDENT 7.0
4294 .INDENT 3.5
4295 If the main subtitle stream contains formatting tags which display the
4296 subtitle at the top of the screen, it will overlap with the secondary
4297 subtitle. To prevent this, you could use \fB\-\-no\-sub\-ass\fP to disable
4298 styling in the main subtitle stream.
4299 .UNINDENT
4300 .UNINDENT
4301 .TP
4302 .B \fB\-\-sub\-scale=<0\-100>\fP
4303 Factor for the text subtitle font size (default: 1).
4304 .sp
4305 \fBNOTE:\fP
4306 .INDENT 7.0
4307 .INDENT 3.5
4308 This affects ASS subtitles as well, and may lead to incorrect subtitle
4309 rendering. Use with care, or use \fB\-\-sub\-font\-size\fP instead.
4310 .UNINDENT
4311 .UNINDENT
4312 .TP
4313 .B \fB\-\-sub\-scale\-by\-window=<yes|no>\fP
4314 Whether to scale subtitles with the window size (default: yes). If this is
4315 disabled, changing the window size won\(aqt change the subtitle font size.
4316 .sp
4317 Like \fB\-\-sub\-scale\fP, this can break ASS subtitles.
4318 .TP
4319 .B \fB\-\-sub\-scale\-with\-window=<yes|no>\fP
4320 Make the subtitle font size relative to the window, instead of the video.
4321 This is useful if you always want the same font size, even if the video
4322 doesn\(aqt cover the window fully, e.g. because screen aspect and window
4323 aspect mismatch (and the player adds black bars).
4324 .sp
4325 Default: yes.
4326 .sp
4327 This option is misnamed. The difference to the confusingly similar sounding
4328 option \fB\-\-sub\-scale\-by\-window\fP is that \fB\-\-sub\-scale\-with\-window\fP still
4329 scales with the approximate window size, while the other option disables
4330 this scaling.
4331 .sp
4332 Affects plain text subtitles only (or ASS if \fB\-\-sub\-ass\-override\fP is set
4333 high enough).
4334 .TP
4335 .B \fB\-\-sub\-ass\-scale\-with\-window=<yes|no>\fP
4336 Like \fB\-\-sub\-scale\-with\-window\fP, but affects subtitles in ASS format only.
4337 Like \fB\-\-sub\-scale\fP, this can break ASS subtitles.
4338 .sp
4339 Default: no.
4340 .TP
4341 .B \fB\-\-embeddedfonts=<yes|no>\fP
4342 Use fonts embedded in Matroska container files and ASS scripts (default:
4343 yes). These fonts can be used for SSA/ASS subtitle rendering.
4344 .TP
4345 .B \fB\-\-sub\-pos=<0\-150>\fP
4346 Specify the position of subtitles on the screen. The value is the vertical
4347 position of the subtitle in % of the screen height. 100 is the original
4348 position, which is often not the absolute bottom of the screen, but with
4349 some margin between the bottom and the subtitle. Values above 100 move the
4350 subtitle further down.
4351 .INDENT 7.0
4352 .INDENT 3.5
4353 .IP "Warning"
4354 .sp
4355 Text subtitles (as opposed to image subtitles) may be cut off if the
4356 value of the option is above 100. This is a libass restriction.
4357 .sp
4358 This affects ASS subtitles as well, and may lead to incorrect subtitle
4359 rendering in addition to the problem above.
4360 .sp
4361 Using \fB\-\-sub\-margin\-y\fP can achieve this in a better way.
4362 .UNINDENT
4363 .UNINDENT
4364 .TP
4365 .B \fB\-\-sub\-speed=<0.1\-10.0>\fP
4366 Multiply the subtitle event timestamps with the given value. Can be used
4367 to fix the playback speed for frame\-based subtitle formats. Affects text
4368 subtitles only.
4369 .INDENT 7.0
4370 .INDENT 3.5
4371 .IP "Example"
4372 .sp
4373 \fB\-\-sub\-speed=25/23.976\fP plays frame based subtitles which have been
4374 loaded assuming a framerate of 23.976 at 25 FPS.
4375 .UNINDENT
4376 .UNINDENT
4377 .TP
4378 .B \fB\-\-sub\-ass\-force\-style=<[Style.]Param=Value[,...]>\fP
4379 Override some style or script info parameters.
4380 .sp
4381 This is a string list option. See \fI\%List Options\fP for details.
4382 .INDENT 7.0
4383 .INDENT 3.5
4384 .IP "Examples"
4385 .INDENT 0.0
4386 .IP \(bu 2
4387 \fB\-\-sub\-ass\-force\-style=FontName=Arial,Default.Bold=1\fP
4388 .IP \(bu 2
4389 \fB\-\-sub\-ass\-force\-style=PlayResY=768\fP
4390 .UNINDENT
4391 .UNINDENT
4392 .UNINDENT
4393 .sp
4394 \fBNOTE:\fP
4395 .INDENT 7.0
4396 .INDENT 3.5
4397 Using this option may lead to incorrect subtitle rendering.
4398 .UNINDENT
4399 .UNINDENT
4400 .TP
4401 .B \fB\-\-sub\-ass\-hinting=<none|light|normal|native>\fP
4402 Set font hinting type. <type> can be:
4403 .INDENT 7.0
4404 .TP
4405 .B none
4406 no hinting (default)
4407 .TP
4408 .B light
4409 FreeType autohinter, light mode
4410 .TP
4411 .B normal
4412 FreeType autohinter, normal mode
4413 .TP
4414 .B native
4415 font native hinter
4416 .UNINDENT
4417 .INDENT 7.0
4418 .INDENT 3.5
4419 .IP "Warning"
4420 .sp
4421 Enabling hinting can lead to mispositioned text (in situations it\(aqs
4422 supposed to match up video background), or reduce the smoothness
4423 of animations with some badly authored ASS scripts. It is recommended
4424 to not use this option, unless really needed.
4425 .UNINDENT
4426 .UNINDENT
4427 .TP
4428 .B \fB\-\-sub\-ass\-line\-spacing=<value>\fP
4429 Set line spacing value for SSA/ASS renderer.
4430 .TP
4431 .B \fB\-\-sub\-ass\-shaper=<simple|complex>\fP
4432 Set the text layout engine used by libass.
4433 .INDENT 7.0
4434 .TP
4435 .B simple
4436 uses Fribidi only, fast, doesn\(aqt render some languages correctly
4437 .TP
4438 .B complex
4439 uses HarfBuzz, slower, wider language support
4440 .UNINDENT
4441 .sp
4442 \fBcomplex\fP is the default. If libass hasn\(aqt been compiled against HarfBuzz,
4443 libass silently reverts to \fBsimple\fP\&.
4444 .TP
4445 .B \fB\-\-sub\-ass\-styles=<filename>\fP
4446 Load all SSA/ASS styles found in the specified file and use them for
4447 rendering text subtitles. The syntax of the file is exactly like the \fB[V4
4448 Styles]\fP / \fB[V4+ Styles]\fP section of SSA/ASS.
4449 .sp
4450 \fBNOTE:\fP
4451 .INDENT 7.0
4452 .INDENT 3.5
4453 Using this option may lead to incorrect subtitle rendering.
4454 .UNINDENT
4455 .UNINDENT
4456 .TP
4457 .B \fB\-\-sub\-ass\-override=<yes|no|force|scale|strip>\fP
4458 Control whether user style overrides should be applied. Note that all of
4459 these overrides try to be somewhat smart about figuring out whether or not
4460 a subtitle is considered a "sign".
4461 .INDENT 7.0
4462 .TP
4463 .B no
4464 Render subtitles as specified by the subtitle scripts, without
4465 overrides.
4466 .TP
4467 .B yes
4468 Apply all the \fB\-\-sub\-ass\-*\fP style override options. Changing the
4469 default for any of these options can lead to incorrect subtitle
4470 rendering (default).
4471 .TP
4472 .B force
4473 Like \fByes\fP, but also force all \fB\-\-sub\-*\fP options. Can break
4474 rendering easily.
4475 .TP
4476 .B scale
4477 Like \fByes\fP, but also apply \fB\-\-sub\-scale\fP\&.
4478 .TP
4479 .B strip
4480 Radically strip all ASS tags and styles from the subtitle. This
4481 is equivalent to the old \fB\-\-no\-ass\fP / \fB\-\-no\-sub\-ass\fP options.
4482 .UNINDENT
4483 .sp
4484 This also controls some bitmap subtitle overrides, as well as HTML tags in
4485 formats like SRT, despite the name of the option.
4486 .TP
4487 .B \fB\-\-sub\-ass\-force\-margins\fP
4488 Enables placing toptitles and subtitles in black borders when they are
4489 available, if the subtitles are in the ASS format.
4490 .sp
4491 Default: no.
4492 .TP
4493 .B \fB\-\-sub\-use\-margins\fP
4494 Enables placing toptitles and subtitles in black borders when they are
4495 available, if the subtitles are in a plain text format (or ASS if
4496 \fB\-\-sub\-ass\-override\fP is set high enough).
4497 .sp
4498 Default: yes.
4499 .sp
4500 Renamed from \fB\-\-sub\-ass\-use\-margins\fP\&. To place ASS subtitles in the borders
4501 too (like the old option did), also add \fB\-\-sub\-ass\-force\-margins\fP\&.
4502 .TP
4503 .B \fB\-\-sub\-ass\-vsfilter\-aspect\-compat=<yes|no>\fP
4504 Stretch SSA/ASS subtitles when playing anamorphic videos for compatibility
4505 with traditional VSFilter behavior. This switch has no effect when the
4506 video is stored with square pixels.
4507 .sp
4508 The renderer historically most commonly used for the SSA/ASS subtitle
4509 formats, VSFilter, had questionable behavior that resulted in subtitles
4510 being stretched too if the video was stored in anamorphic format that
4511 required scaling for display. This behavior is usually undesirable and
4512 newer VSFilter versions may behave differently. However, many existing
4513 scripts compensate for the stretching by modifying things in the opposite
4514 direction. Thus, if such scripts are displayed "correctly", they will not
4515 appear as intended. This switch enables emulation of the old VSFilter
4516 behavior (undesirable but expected by many existing scripts).
4517 .sp
4518 Enabled by default.
4519 .TP
4520 .B \fB\-\-sub\-ass\-vsfilter\-blur\-compat=<yes|no>\fP
4521 Scale \fB\eblur\fP tags by video resolution instead of script resolution
4522 (enabled by default). This is bug in VSFilter, which according to some,
4523 can\(aqt be fixed anymore in the name of compatibility.
4524 .sp
4525 Note that this uses the actual video resolution for calculating the
4526 offset scale factor, not what the video filter chain or the video output
4527 use.
4528 .TP
4529 .B \fB\-\-sub\-ass\-vsfilter\-color\-compat=<basic|full|force\-601|no>\fP
4530 Mangle colors like (xy\-)vsfilter do (default: basic). Historically, VSFilter
4531 was not color space aware. This was no problem as long as the color space
4532 used for SD video (BT.601) was used. But when everything switched to HD
4533 (BT.709), VSFilter was still converting RGB colors to BT.601, rendered
4534 them into the video frame, and handled the frame to the video output, which
4535 would use BT.709 for conversion to RGB. The result were mangled subtitle
4536 colors. Later on, bad hacks were added on top of the ASS format to control
4537 how colors are to be mangled.
4538 .INDENT 7.0
4539 .TP
4540 .B basic
4541 Handle only BT.601\->BT.709 mangling, if the subtitles seem to
4542 indicate that this is required (default).
4543 .TP
4544 .B full
4545 Handle the full \fBYCbCr Matrix\fP header with all video color spaces
4546 supported by libass and mpv. This might lead to bad breakages in
4547 corner cases and is not strictly needed for compatibility
4548 (hopefully), which is why this is not default.
4549 .TP
4550 .B force\-601
4551 Force BT.601\->BT.709 mangling, regardless of subtitle headers
4552 or video color space.
4553 .TP
4554 .B no
4555 Disable color mangling completely. All colors are RGB.
4556 .UNINDENT
4557 .sp
4558 Choosing anything other than \fBno\fP will make the subtitle color depend on
4559 the video color space, and it\(aqs for example in theory not possible to reuse
4560 a subtitle script with another video file. The \fB\-\-sub\-ass\-override\fP
4561 option doesn\(aqt affect how this option is interpreted.
4562 .TP
4563 .B \fB\-\-stretch\-dvd\-subs=<yes|no>\fP
4564 Stretch DVD subtitles when playing anamorphic videos for better looking
4565 fonts on badly mastered DVDs. This switch has no effect when the
4566 video is stored with square pixels \- which for DVD input cannot be the case
4567 though.
4568 .sp
4569 Many studios tend to use bitmap fonts designed for square pixels when
4570 authoring DVDs, causing the fonts to look stretched on playback on DVD
4571 players. This option fixes them, however at the price of possibly
4572 misaligning some subtitles (e.g. sign translations).
4573 .sp
4574 Disabled by default.
4575 .TP
4576 .B \fB\-\-stretch\-image\-subs\-to\-screen=<yes|no>\fP
4577 Stretch DVD and other image subtitles to the screen, ignoring the video
4578 margins. This has a similar effect as \fB\-\-sub\-use\-margins\fP for text
4579 subtitles, except that the text itself will be stretched, not only just
4580 repositioned. (At least in general it is unavoidable, as an image bitmap
4581 can in theory consist of a single bitmap covering the whole screen, and
4582 the player won\(aqt know where exactly the text parts are located.)
4583 .sp
4584 This option does not display subtitles correctly. Use with care.
4585 .sp
4586 Disabled by default.
4587 .TP
4588 .B \fB\-\-image\-subs\-video\-resolution=<yes|no>\fP
4589 Override the image subtitle resolution with the video resolution
4590 (default: no). Normally, the subtitle canvas is fit into the video canvas
4591 (e.g. letterboxed). Setting this option uses the video size as subtitle
4592 canvas size. Can be useful to test broken subtitles, which often happen
4593 when the video was trancoded, while attempting to keep the old subtitles.
4594 .TP
4595 .B \fB\-\-sub\-ass\fP, \fB\-\-no\-sub\-ass\fP
4596 Render ASS subtitles natively (enabled by default).
4597 .sp
4598 \fBNOTE:\fP
4599 .INDENT 7.0
4600 .INDENT 3.5
4601 This has been deprecated by \fB\-\-sub\-ass\-override=strip\fP\&. You also
4602 may need \fB\-\-embeddedfonts=no\fP to get the same behavior. Also,
4603 using \fB\-\-sub\-ass\-override=style\fP should give better results
4604 without breaking subtitles too much.
4605 .UNINDENT
4606 .UNINDENT
4607 .sp
4608 If \fB\-\-no\-sub\-ass\fP is specified, all tags and style declarations are
4609 stripped and ignored on display. The subtitle renderer uses the font style
4610 as specified by the \fB\-\-sub\-\fP options instead.
4611 .sp
4612 \fBNOTE:\fP
4613 .INDENT 7.0
4614 .INDENT 3.5
4615 Using \fB\-\-no\-sub\-ass\fP may lead to incorrect or completely broken
4616 rendering of ASS/SSA subtitles. It can sometimes be useful to forcibly
4617 override the styling of ASS subtitles, but should be avoided in general.
4618 .UNINDENT
4619 .UNINDENT
4620 .TP
4621 .B \fB\-\-sub\-auto=<no|exact|fuzzy|all>\fP, \fB\-\-no\-sub\-auto\fP
4622 Load additional subtitle files matching the video filename. The parameter
4623 specifies how external subtitle files are matched. \fBexact\fP is enabled by
4624 default.
4625 .INDENT 7.0
4626 .TP
4627 .B no
4628 Don\(aqt automatically load external subtitle files.
4629 .TP
4630 .B exact
4631 Load the media filename with subtitle file extension and possibly
4632 language suffixes (default).
4633 .TP
4634 .B fuzzy
4635 Load all subs containing media filename.
4636 .TP
4637 .B all
4638 Load all subs in the current and \fB\-\-sub\-file\-paths\fP directories.
4639 .UNINDENT
4640 .TP
4641 .B \fB\-\-sub\-codepage=<codepage>\fP
4642 You can use this option to specify the subtitle codepage. uchardet will be
4643 used to guess the charset. (If mpv was not compiled with uchardet, then
4644 \fButf\-8\fP is the effective default.)
4645 .sp
4646 The default value for this option is \fBauto\fP, which enables autodetection.
4647 .sp
4648 The following steps are taken to determine the final codepage, in order:
4649 .INDENT 7.0
4650 .IP \(bu 2
4651 if the specific codepage has a \fB+\fP, use that codepage
4652 .IP \(bu 2
4653 if the data looks like UTF\-8, assume it is UTF\-8
4654 .IP \(bu 2
4655 if \fB\-\-sub\-codepage\fP is set to a specific codepage, use that
4656 .IP \(bu 2
4657 run uchardet, and if successful, use that
4658 .IP \(bu 2
4659 otherwise, use \fBUTF\-8\-BROKEN\fP
4660 .UNINDENT
4661 .INDENT 7.0
4662 .INDENT 3.5
4663 .IP "Examples"
4664 .INDENT 0.0
4665 .IP \(bu 2
4666 \fB\-\-sub\-codepage=latin2\fP Use Latin 2 if input is not UTF\-8.
4667 .IP \(bu 2
4668 \fB\-\-sub\-codepage=+cp1250\fP Always force recoding to cp1250.
4669 .UNINDENT
4670 .UNINDENT
4671 .UNINDENT
4672 .sp
4673 The pseudo codepage \fBUTF\-8\-BROKEN\fP is used internally. If it\(aqs set,
4674 subtitles are interpreted as UTF\-8 with "Latin 1" as fallback for bytes
4675 which are not valid UTF\-8 sequences. iconv is never involved in this mode.
4676 .sp
4677 This option changed in mpv 0.23.0. Support for the old syntax was fully
4678 removed in mpv 0.24.0.
4679 .sp
4680 \fBNOTE:\fP
4681 .INDENT 7.0
4682 .INDENT 3.5
4683 This works for text subtitle files only. Other types of subtitles (in
4684 particular subtitles in mkv files) are always assumed to be UTF\-8.
4685 .UNINDENT
4686 .UNINDENT
4687 .TP
4688 .B \fB\-\-sub\-fix\-timing=<yes|no>\fP
4689 Adjust subtitle timing is to remove minor gaps or overlaps between
4690 subtitles (if the difference is smaller than 210 ms, the gap or overlap
4691 is removed).
4692 .TP
4693 .B \fB\-\-sub\-forced\-only=<auto|yes|no>\fP
4694 Display only forced subtitles for the DVD subtitle stream selected by e.g.
4695 \fB\-\-slang\fP (default: \fBauto\fP). When set to \fBauto\fP, enabled when the
4696 \fB\-\-subs\-with\-matching\-audio\fP option is on and a non\-forced stream is selected.
4697 Enabling this will hide all subtitles in streams that don\(aqt make a distinction
4698 between forced and unforced events within a stream.
4699 .TP
4700 .B \fB\-\-sub\-fps=<rate>\fP
4701 Specify the framerate of the subtitle file (default: video fps). Affects
4702 text subtitles only.
4703 .sp
4704 \fBNOTE:\fP
4705 .INDENT 7.0
4706 .INDENT 3.5
4707 \fB<rate>\fP > video fps speeds the subtitles up for frame\-based
4708 subtitle files and slows them down for time\-based ones.
4709 .UNINDENT
4710 .UNINDENT
4711 .sp
4712 See also: \fB\-\-sub\-speed\fP\&.
4713 .TP
4714 .B \fB\-\-sub\-gauss=<0.0\-3.0>\fP
4715 Apply Gaussian blur to image subtitles (default: 0). This can help to make
4716 pixelated DVD/Vobsubs look nicer. A value other than 0 also switches to
4717 software subtitle scaling. Might be slow.
4718 .sp
4719 \fBNOTE:\fP
4720 .INDENT 7.0
4721 .INDENT 3.5
4722 Never applied to text subtitles.
4723 .UNINDENT
4724 .UNINDENT
4725 .TP
4726 .B \fB\-\-sub\-gray\fP
4727 Convert image subtitles to grayscale. Can help to make yellow DVD/Vobsubs
4728 look nicer.
4729 .sp
4730 \fBNOTE:\fP
4731 .INDENT 7.0
4732 .INDENT 3.5
4733 Never applied to text subtitles.
4734 .UNINDENT
4735 .UNINDENT
4736 .TP
4737 .B \fB\-\-sub\-paths=<path1:path2:...>\fP
4738 Deprecated, use \fB\-\-sub\-file\-paths\fP\&.
4739 .TP
4740 .B \fB\-\-sub\-file\-paths=<path\-list>\fP
4741 Specify extra directories to search for subtitles matching the video.
4742 Multiple directories can be separated by ":" (";" on Windows).
4743 Paths can be relative or absolute. Relative paths are interpreted relative
4744 to video file directory.
4745 If the file is a URL, only absolute paths and \fBsub\fP configuration
4746 subdirectory will be scanned.
4747 .INDENT 7.0
4748 .INDENT 3.5
4749 .IP "Example"
4750 .sp
4751 Assuming that \fB/path/to/video/video.avi\fP is played and
4752 \fB\-\-sub\-file\-paths=sub:subtitles\fP is specified, mpv
4753 searches for subtitle files in these directories:
4754 .INDENT 0.0
4755 .IP \(bu 2
4756 \fB/path/to/video/\fP
4757 .IP \(bu 2
4758 \fB/path/to/video/sub/\fP
4759 .IP \(bu 2
4760 \fB/path/to/video/subtitles/\fP
4761 .IP \(bu 2
4762 the \fBsub\fP configuration subdirectory (usually \fB~/.config/mpv/sub/\fP)
4763 .UNINDENT
4764 .UNINDENT
4765 .UNINDENT
4766 .sp
4767 This is a path list option. See \fI\%List Options\fP for details.
4768 .TP
4769 .B \fB\-\-sub\-visibility\fP, \fB\-\-no\-sub\-visibility\fP
4770 Can be used to disable display of subtitles, but still select and decode
4771 them.
4772 .TP
4773 .B \fB\-\-sub\-clear\-on\-seek\fP
4774 (Obscure, rarely useful.) Can be used to play broken mkv files with
4775 duplicate ReadOrder fields. ReadOrder is the first field in a
4776 Matroska\-style ASS subtitle packets. It should be unique, and libass
4777 uses it for fast elimination of duplicates. This option disables caching
4778 of subtitles across seeks, so after a seek libass can\(aqt eliminate subtitle
4779 packets with the same ReadOrder as earlier packets.
4780 .TP
4781 .B \fB\-\-teletext\-page=<1\-999>\fP
4782 This works for \fBdvb_teletext\fP subtitle streams, and if FFmpeg has been
4783 compiled with support for it.
4784 .TP
4785 .B \fB\-\-sub\-font=<name>\fP
4786 Specify font to use for subtitles that do not themselves
4787 specify a particular font. The default is \fBsans\-serif\fP\&.
4788 .INDENT 7.0
4789 .INDENT 3.5
4790 .IP "Examples"
4791 .INDENT 0.0
4792 .IP \(bu 2
4793 \fB\-\-sub\-font=\(aqBitstream Vera Sans\(aq\fP
4794 .IP \(bu 2
4795 \fB\-\-sub\-font=\(aqComic Sans MS\(aq\fP
4796 .UNINDENT
4797 .UNINDENT
4798 .UNINDENT
4799 .sp
4800 \fBNOTE:\fP
4801 .INDENT 7.0
4802 .INDENT 3.5
4803 The \fB\-\-sub\-font\fP option (and many other style related \fB\-\-sub\-\fP
4804 options) are ignored when ASS\-subtitles are rendered, unless the
4805 \fB\-\-no\-sub\-ass\fP option is specified.
4806 .sp
4807 This used to support fontconfig patterns. Starting with libass 0.13.0,
4808 this stopped working.
4809 .UNINDENT
4810 .UNINDENT
4811 .TP
4812 .B \fB\-\-sub\-font\-size=<size>\fP
4813 Specify the sub font size. The unit is the size in scaled pixels at a
4814 window height of 720. The actual pixel size is scaled with the window
4815 height: if the window height is larger or smaller than 720, the actual size
4816 of the text increases or decreases as well.
4817 .sp
4818 Default: 55.
4819 .TP
4820 .B \fB\-\-sub\-back\-color=<color>\fP
4821 See \fB\-\-sub\-color\fP\&. Color used for sub text background. You can use
4822 \fB\-\-sub\-shadow\-offset\fP to change its size relative to the text.
4823 .TP
4824 .B \fB\-\-sub\-blur=<0..20.0>\fP
4825 Gaussian blur factor. 0 means no blur applied (default).
4826 .TP
4827 .B \fB\-\-sub\-bold=<yes|no>\fP
4828 Format text on bold.
4829 .TP
4830 .B \fB\-\-sub\-italic=<yes|no>\fP
4831 Format text on italic.
4832 .TP
4833 .B \fB\-\-sub\-border\-color=<color>\fP
4834 See \fB\-\-sub\-color\fP\&. Color used for the sub font border.
4835 .sp
4836 \fBNOTE:\fP
4837 .INDENT 7.0
4838 .INDENT 3.5
4839 ignored when \fB\-\-sub\-back\-color\fP is
4840 specified (or more exactly: when that option is not set to completely
4841 transparent).
4842 .UNINDENT
4843 .UNINDENT
4844 .TP
4845 .B \fB\-\-sub\-border\-size=<size>\fP
4846 Size of the sub font border in scaled pixels (see \fB\-\-sub\-font\-size\fP
4847 for details). A value of 0 disables borders.
4848 .sp
4849 Default: 3.
4850 .TP
4851 .B \fB\-\-sub\-color=<color>\fP
4852 Specify the color used for unstyled text subtitles.
4853 .sp
4854 The color is specified in the form \fBr/g/b\fP, where each color component
4855 is specified as number in the range 0.0 to 1.0. It\(aqs also possible to
4856 specify the transparency by using \fBr/g/b/a\fP, where the alpha value 0
4857 means fully transparent, and 1.0 means opaque. If the alpha component is
4858 not given, the color is 100% opaque.
4859 .sp
4860 Passing a single number to the option sets the sub to gray, and the form
4861 \fBgray/a\fP lets you specify alpha additionally.
4862 .INDENT 7.0
4863 .INDENT 3.5
4864 .IP "Examples"
4865 .INDENT 0.0
4866 .IP \(bu 2
4867 \fB\-\-sub\-color=1.0/0.0/0.0\fP set sub to opaque red
4868 .IP \(bu 2
4869 \fB\-\-sub\-color=1.0/0.0/0.0/0.75\fP set sub to opaque red with 75% alpha
4870 .IP \(bu 2
4871 \fB\-\-sub\-color=0.5/0.75\fP set sub to 50% gray with 75% alpha
4872 .UNINDENT
4873 .UNINDENT
4874 .UNINDENT
4875 .sp
4876 Alternatively, the color can be specified as a RGB hex triplet in the form
4877 \fB#RRGGBB\fP, where each 2\-digit group expresses a color value in the
4878 range 0 (\fB00\fP) to 255 (\fBFF\fP). For example, \fB#FF0000\fP is red.
4879 This is similar to web colors. Alpha is given with \fB#AARRGGBB\fP\&.
4880 .INDENT 7.0
4881 .INDENT 3.5
4882 .IP "Examples"
4883 .INDENT 0.0
4884 .IP \(bu 2
4885 \fB\-\-sub\-color=\(aq#FF0000\(aq\fP set sub to opaque red
4886 .IP \(bu 2
4887 \fB\-\-sub\-color=\(aq#C0808080\(aq\fP set sub to 50% gray with 75% alpha
4888 .UNINDENT
4889 .UNINDENT
4890 .UNINDENT
4891 .TP
4892 .B \fB\-\-sub\-margin\-x=<size>\fP
4893 Left and right screen margin for the subs in scaled pixels (see
4894 \fB\-\-sub\-font\-size\fP for details).
4895 .sp
4896 This option specifies the distance of the sub to the left, as well as at
4897 which distance from the right border long sub text will be broken.
4898 .sp
4899 Default: 25.
4900 .TP
4901 .B \fB\-\-sub\-margin\-y=<size>\fP
4902 Top and bottom screen margin for the subs in scaled pixels (see
4903 \fB\-\-sub\-font\-size\fP for details).
4904 .sp
4905 This option specifies the vertical margins of unstyled text subtitles.
4906 If you just want to raise the vertical subtitle position, use \fB\-\-sub\-pos\fP\&.
4907 .sp
4908 Default: 22.
4909 .TP
4910 .B \fB\-\-sub\-align\-x=<left|center|right>\fP
4911 Control to which corner of the screen text subtitles should be
4912 aligned to (default: \fBcenter\fP).
4913 .sp
4914 Never applied to ASS subtitles, except in \fB\-\-no\-sub\-ass\fP mode. Likewise,
4915 this does not apply to image subtitles.
4916 .TP
4917 .B \fB\-\-sub\-align\-y=<top|center|bottom>\fP
4918 Vertical position (default: \fBbottom\fP).
4919 Details see \fB\-\-sub\-align\-x\fP\&.
4920 .TP
4921 .B \fB\-\-sub\-justify=<auto|left|center|right>\fP
4922 Control how multi line subs are justified irrespective of where they
4923 are aligned (default: \fBauto\fP which justifies as defined by
4924 \fB\-\-sub\-align\-y\fP).
4925 Left justification is recommended to make the subs easier to read
4926 as it is easier for the eyes.
4927 .TP
4928 .B \fB\-\-sub\-ass\-justify=<yes|no>\fP
4929 Applies justification as defined by \fB\-\-sub\-justify\fP on ASS subtitles
4930 if \fB\-\-sub\-ass\-override\fP is not set to \fBno\fP\&.
4931 Default: \fBno\fP\&.
4932 .TP
4933 .B \fB\-\-sub\-shadow\-color=<color>\fP
4934 See \fB\-\-sub\-color\fP\&. Color used for sub text shadow.
4935 .TP
4936 .B \fB\-\-sub\-shadow\-offset=<size>\fP
4937 Displacement of the sub text shadow in scaled pixels (see
4938 \fB\-\-sub\-font\-size\fP for details). A value of 0 disables shadows.
4939 .sp
4940 Default: 0.
4941 .TP
4942 .B \fB\-\-sub\-spacing=<size>\fP
4943 Horizontal sub font spacing in scaled pixels (see \fB\-\-sub\-font\-size\fP
4944 for details). This value is added to the normal letter spacing. Negative
4945 values are allowed.
4946 .sp
4947 Default: 0.
4948 .TP
4949 .B \fB\-\-sub\-filter\-sdh=<yes|no>\fP
4950 Applies filter removing subtitle additions for the deaf or hard\-of\-hearing (SDH).
4951 This is intended for English, but may in part work for other languages too.
4952 The intention is that it can be always enabled so may not remove
4953 all parts added.
4954 It removes speaker labels (like MAN:), upper case text in parentheses and
4955 any text in brackets.
4956 .sp
4957 Default: \fBno\fP\&.
4958 .TP
4959 .B \fB\-\-sub\-filter\-sdh\-harder=<yes|no>\fP
4960 Do harder SDH filtering (if enabled by \fB\-\-sub\-filter\-sdh\fP).
4961 Will also remove speaker labels and text within parentheses using both
4962 lower and upper case letters.
4963 .sp
4964 Default: \fBno\fP\&.
4965 .TP
4966 .B \fB\-\-sub\-filter\-regex\-...=...\fP
4967 Set a list of regular expressions to match on text subtitles, and remove any
4968 lines that match (default: empty). This is a string list option. See
4969 \fI\%List Options\fP for details. Normally, you should use
4970 \fB\-\-sub\-filter\-regex\-append=<regex>\fP, where each option use will append a
4971 new regular expression, without having to fight escaping problems.
4972 .sp
4973 List items are matched in order. If a regular expression matches, the
4974 process is stopped, and the subtitle line is discarded. The text matched
4975 against is, currently, always the \fBText\fP field of ASS events (if the
4976 subtitle format is different, it is always converted). This may include
4977 formatting tags. Matching is case\-insensitive, but how this is done depends
4978 on the libc, and most likely works in ASCII only. It does not work on
4979 bitmap/image subtitles. Unavailable on inferior OSes (requires POSIX regex
4980 support).
4981 .INDENT 7.0
4982 .INDENT 3.5
4983 .IP "Example"
4984 .sp
4985 \fB\-\-sub\-filter\-regex\-append=opensubtitles\e.org\fP filters some ads.
4986 .UNINDENT
4987 .UNINDENT
4988 .sp
4989 Technically, using a list for matching is redundant, since you could just
4990 use a single combined regular expression. But it helps with diagnosis,
4991 ease of use, and temporarily disabling or enabling individual filters.
4992 .sp
4993 \fBWARNING:\fP
4994 .INDENT 7.0
4995 .INDENT 3.5
4996 This is experimental. The semantics most likely will change, and if you
4997 use this, you should be prepared to update the option later. Ideas
4998 include replacing the regexes with a very primitive and small subset of
4999 sed, or some method to control case\-sensitivity.
5000 .UNINDENT
5001 .UNINDENT
5002 .TP
5003 .B \fB\-\-sub\-filter\-regex\-warn=<yes|no>\fP
5004 Log dropped lines with warning log level, instead of verbose (default: no).
5005 Helpful for testing.
5006 .TP
5007 .B \fB\-\-sub\-filter\-regex\-enable=<yes|no>\fP
5008 Whether to enable regex filtering (default: yes). Note that if no regexes
5009 are added to the \fB\-\-sub\-filter\-regex\fP list, setting this option to \fByes\fP
5010 has no effect. It\(aqs meant to easily disable or enable filtering
5011 temporarily.
5012 .TP
5013 .B \fB\-\-sub\-create\-cc\-track=<yes|no>\fP
5014 For every video stream, create a closed captions track (default: no). The
5015 only purpose is to make the track available for selection at the start of
5016 playback, instead of creating it lazily. This applies only to
5017 \fBATSC A53 Part 4 Closed Captions\fP (displayed by mpv as subtitle tracks
5018 using the codec \fBeia_608\fP). The CC track is marked "default" and selected
5019 according to the normal subtitle track selection rules. You can then use
5020 \fB\-\-sid\fP to explicitly select the correct track too.
5021 .sp
5022 If the video stream contains no closed captions, or if no video is being
5023 decoded, the CC track will remain empty and will not show any text.
5024 .TP
5025 .B \fB\-\-sub\-font\-provider=<auto|none|fontconfig>\fP
5026 Which libass font provider backend to use (default: auto). \fBauto\fP will
5027 attempt to use the native font provider: fontconfig on Linux, CoreText on
5028 OSX, DirectWrite on Windows. \fBfontconfig\fP forces fontconfig, if libass
5029 was built with support (if not, it behaves like \fBnone\fP).
5030 .sp
5031 The \fBnone\fP font provider effectively disables system fonts. It will still
5032 attempt to use embedded fonts (unless \fB\-\-embeddedfonts=no\fP is set; this is
5033 the same behavior as with all other font providers), \fBsubfont.ttf\fP if
5034 provided, and fonts in the \fBfonts\fP sub\-directory if provided. (The
5035 fallback is more strict than that of other font providers, and if a font
5036 name does not match, it may prefer not to render any text that uses the
5037 missing font.)
5038 .UNINDENT
5039 .SS Window
5040 .INDENT 0.0
5041 .TP
5042 .B \fB\-\-title=<string>\fP
5043 Set the window title. This is used for the video window, and if possible,
5044 also sets the audio stream title.
5045 .sp
5046 Properties are expanded. (See \fI\%Property Expansion\fP\&.)
5047 .sp
5048 \fBWARNING:\fP
5049 .INDENT 7.0
5050 .INDENT 3.5
5051 There is a danger of this causing significant CPU usage, depending on
5052 the properties used. Changing the window title is often a slow
5053 operation, and if the title changes every frame, playback can be ruined.
5054 .UNINDENT
5055 .UNINDENT
5056 .TP
5057 .B \fB\-\-screen=<default|0\-32>\fP
5058 In multi\-monitor configurations (i.e. a single desktop that spans across
5059 multiple displays), this option tells mpv which screen to display the
5060 video on.
5061 .INDENT 7.0
5062 .INDENT 3.5
5063 .IP "Note (X11)"
5064 .sp
5065 This option does not work properly with all window managers. In these
5066 cases, you can try to use \fB\-\-geometry\fP to position the window
5067 explicitly. It\(aqs also possible that the window manager provides native
5068 features to control which screens application windows should use.
5069 .UNINDENT
5070 .UNINDENT
5071 .sp
5072 See also \fB\-\-fs\-screen\fP\&.
5073 .TP
5074 .B \fB\-\-fullscreen\fP, \fB\-\-fs\fP
5075 Fullscreen playback.
5076 .TP
5077 .B \fB\-\-fs\-screen=<all|current|0\-32>\fP
5078 In multi\-monitor configurations (i.e. a single desktop that spans across
5079 multiple displays), this option tells mpv which screen to go fullscreen to.
5080 If \fBcurrent\fP is used mpv will fallback on what the user provided with
5081 the \fBscreen\fP option.
5082 .INDENT 7.0
5083 .INDENT 3.5
5084 .IP "Note (X11)"
5085 .sp
5086 This option works properly only with window managers which
5087 understand the EWMH \fB_NET_WM_FULLSCREEN_MONITORS\fP hint.
5088 .UNINDENT
5089 .UNINDENT
5090 .INDENT 7.0
5091 .INDENT 3.5
5092 .IP "Note (OS X)"
5093 .sp
5094 \fBall\fP does not work on OS X and will behave like \fBcurrent\fP\&.
5095 .UNINDENT
5096 .UNINDENT
5097 .sp
5098 See also \fB\-\-screen\fP\&.
5099 .TP
5100 .B \fB\-\-keep\-open=<yes|no|always>\fP
5101 Do not terminate when playing or seeking beyond the end of the file, and
5102 there is not next file to be played (and \fB\-\-loop\fP is not used).
5103 Instead, pause the player. When trying to seek beyond end of the file, the
5104 player will attempt to seek to the last frame.
5105 .sp
5106 Normally, this will act like \fBset pause yes\fP on EOF, unless the
5107 \fB\-\-keep\-open\-pause=no\fP option is set.
5108 .sp
5109 The following arguments can be given:
5110 .INDENT 7.0
5111 .TP
5112 .B no
5113 If the current file ends, go to the next file or terminate.
5114 (Default.)
5115 .TP
5116 .B yes
5117 Don\(aqt terminate if the current file is the last playlist entry.
5118 Equivalent to \fB\-\-keep\-open\fP without arguments.
5119 .TP
5120 .B always
5121 Like \fByes\fP, but also applies to files before the last playlist
5122 entry. This means playback will never automatically advance to
5123 the next file.
5124 .UNINDENT
5125 .sp
5126 \fBNOTE:\fP
5127 .INDENT 7.0
5128 .INDENT 3.5
5129 This option is not respected when using \fB\-\-frames\fP\&. Explicitly
5130 skipping to the next file if the binding uses \fBforce\fP will terminate
5131 playback as well.
5132 .sp
5133 Also, if errors or unusual circumstances happen, the player can quit
5134 anyway.
5135 .UNINDENT
5136 .UNINDENT
5137 .sp
5138 Since mpv 0.6.0, this doesn\(aqt pause if there is a next file in the playlist,
5139 or the playlist is looped. Approximately, this will pause when the player
5140 would normally exit, but in practice there are corner cases in which this
5141 is not the case (e.g. \fBmpv \-\-keep\-open file.mkv /dev/null\fP will play
5142 file.mkv normally, then fail to open \fB/dev/null\fP, then exit). (In
5143 mpv 0.8.0, \fBalways\fP was introduced, which restores the old behavior.)
5144 .TP
5145 .B \fB\-\-keep\-open\-pause=<yes|no>\fP
5146 If set to \fBno\fP, instead of pausing when \fB\-\-keep\-open\fP is active, just
5147 stop at end of file and continue playing forward when you seek backwards
5148 until end where it stops again. Default: \fByes\fP\&.
5149 .TP
5150 .B \fB\-\-image\-display\-duration=<seconds|inf>\fP
5151 If the current file is an image, play the image for the given amount of
5152 seconds (default: 1). \fBinf\fP means the file is kept open forever (until
5153 the user stops playback manually).
5154 .sp
5155 Unlike \fB\-\-keep\-open\fP, the player is not paused, but simply continues
5156 playback until the time has elapsed. (It should not use any resources
5157 during "playback".)
5158 .sp
5159 This affects image files, which are defined as having only 1 video frame
5160 and no audio. The player may recognize certain non\-images as images, for
5161 example if \fB\-\-length\fP is used to reduce the length to 1 frame, or if
5162 you seek to the last frame.
5163 .sp
5164 This option does not affect the framerate used for \fBmf://\fP or
5165 \fB\-\-merge\-files\fP\&. For that, use \fB\-\-mf\-fps\fP instead.
5166 .sp
5167 Setting \fB\-\-image\-display\-duration\fP hides the OSC and does not track
5168 playback time on the command\-line output, and also does not duplicate
5169 the image frame when encoding. To force the player into "dumb mode"
5170 and actually count out seconds, or to duplicate the image when
5171 encoding, you need to use \fB\-\-demuxer=lavf \-\-demuxer\-lavf\-o=loop=1\fP,
5172 and use \fB\-\-length\fP or \fB\-\-frames\fP to stop after a particular time.
5173 .TP
5174 .B \fB\-\-force\-window=<yes|no|immediate>\fP
5175 Create a video output window even if there is no video. This can be useful
5176 when pretending that mpv is a GUI application. Currently, the window
5177 always has the size 640x480, and is subject to \fB\-\-geometry\fP,
5178 \fB\-\-autofit\fP, and similar options.
5179 .sp
5180 \fBWARNING:\fP
5181 .INDENT 7.0
5182 .INDENT 3.5
5183 The window is created only after initialization (to make sure default
5184 window placement still works if the video size is different from the
5185 \fB\-\-force\-window\fP default window size). This can be a problem if
5186 initialization doesn\(aqt work perfectly, such as when opening URLs with
5187 bad network connection, or opening broken video files. The \fBimmediate\fP
5188 mode can be used to create the window always on program start, but this
5189 may cause other issues.
5190 .UNINDENT
5191 .UNINDENT
5192 .TP
5193 .B \fB\-\-taskbar\-progress\fP, \fB\-\-no\-taskbar\-progress\fP
5194 (Windows only)
5195 Enable/disable playback progress rendering in taskbar (Windows 7 and above).
5196 .sp
5197 Enabled by default.
5198 .TP
5199 .B \fB\-\-snap\-window\fP
5200 (Windows only) Snap the player window to screen edges.
5201 .TP
5202 .B \fB\-\-ontop\fP
5203 Makes the player window stay on top of other windows.
5204 .sp
5205 On Windows, if combined with fullscreen mode, this causes mpv to be
5206 treated as exclusive fullscreen window that bypasses the Desktop Window
5207 Manager.
5208 .TP
5209 .B \fB\-\-ontop\-level=<window|system|desktop|level>\fP
5210 (OS X only)
5211 Sets the level of an ontop window (default: window).
5212 .INDENT 7.0
5213 .TP
5214 .B window
5215 On top of all other windows.
5216 .TP
5217 .B system
5218 On top of system elements like Taskbar, Menubar and Dock.
5219 .TP
5220 .B desktop
5221 On top of the Dekstop behind windows and Desktop icons.
5222 .TP
5223 .B level
5224 A level as integer.
5225 .UNINDENT
5226 .TP
5227 .B \fB\-\-focus\-on\-open\fP, \fB\-\-no\-focus\-on\-open\fP
5228 (macOS only)
5229 Focus the video window on creation and makes it the front most window. This
5230 is on by default.
5231 .TP
5232 .B \fB\-\-border\fP, \fB\-\-no\-border\fP
5233 Play video with window border and decorations. Since this is on by
5234 default, use \fB\-\-no\-border\fP to disable the standard window decorations.
5235 .TP
5236 .B \fB\-\-fit\-border\fP, \fB\-\-no\-fit\-border\fP
5237 (Windows only) Fit the whole window with border and decorations on the
5238 screen. Since this is on by default, use \fB\-\-no\-fit\-border\fP to make mpv
5239 try to only fit client area with video on the screen. This behavior only
5240 applied to window/video with size exceeding size of the screen.
5241 .TP
5242 .B \fB\-\-on\-all\-workspaces\fP
5243 (X11 only)
5244 Show the video window on all virtual desktops.
5245 .TP
5246 .B \fB\-\-geometry=<[W[xH]][+\-x+\-y][/WS]>\fP, \fB\-\-geometry=<x:y>\fP
5247 Adjust the initial window position or size. \fBW\fP and \fBH\fP set the window
5248 size in pixels. \fBx\fP and \fBy\fP set the window position, measured in pixels
5249 from the top\-left corner of the screen to the top\-left corner of the image
5250 being displayed. If a percentage sign (\fB%\fP) is given after the argument,
5251 it turns the value into a percentage of the screen size in that direction.
5252 Positions are specified similar to the standard X11 \fB\-\-geometry\fP option
5253 format, in which e.g. +10\-50 means "place 10 pixels from the left border and
5254 50 pixels from the lower border" and "\-\-20+\-10" means "place 20 pixels
5255 beyond the right and 10 pixels beyond the top border". A trailing \fB/\fP
5256 followed by an integer denotes on which workspace (virtual desktop) the
5257 window should appear (X11 only).
5258 .sp
5259 If an external window is specified using the \fB\-\-wid\fP option, this
5260 option is ignored.
5261 .sp
5262 The coordinates are relative to the screen given with \fB\-\-screen\fP for the
5263 video output drivers that fully support \fB\-\-screen\fP\&.
5264 .sp
5265 \fBNOTE:\fP
5266 .INDENT 7.0
5267 .INDENT 3.5
5268 Generally only supported by GUI VOs. Ignored for encoding.
5269 .UNINDENT
5270 .UNINDENT
5271 .\" admonition: Note (OS X)
5272 .\"
5273 .\" On Mac OS X the origin of the screen coordinate system is located on the
5274 .\" bottom-left corner. For instance, ``0:0`` will place the window at the
5275 .\" bottom-left of the screen.
5276 .
5277 .INDENT 7.0
5278 .INDENT 3.5
5279 .IP "Note (X11)"
5280 .sp
5281 This option does not work properly with all window managers.
5282 .UNINDENT
5283 .UNINDENT
5284 .INDENT 7.0
5285 .INDENT 3.5
5286 .IP "Examples"
5287 .INDENT 0.0
5288 .TP
5289 .B \fB50:40\fP
5290 Places the window at x=50, y=40.
5291 .TP
5292 .B \fB50%:50%\fP
5293 Places the window in the middle of the screen.
5294 .TP
5295 .B \fB100%:100%\fP
5296 Places the window at the bottom right corner of the screen.
5297 .TP
5298 .B \fB50%\fP
5299 Sets the window width to half the screen width. Window height is set
5300 so that the window has the video aspect ratio.
5301 .TP
5302 .B \fB50%x50%\fP
5303 Forces the window width and height to half the screen width and
5304 height. Will show black borders to compensate for the video aspect
5305 ratio (with most VOs and without \fB\-\-no\-keepaspect\fP).
5306 .TP
5307 .B \fB50%+10+10/2\fP
5308 Sets the window to half the screen widths, and positions it 10
5309 pixels below/left of the top left corner of the screen, on the
5310 second workspace.
5311 .UNINDENT
5312 .UNINDENT
5313 .UNINDENT
5314 .sp
5315 See also \fB\-\-autofit\fP and \fB\-\-autofit\-larger\fP for fitting the window into
5316 a given size without changing aspect ratio.
5317 .TP
5318 .B \fB\-\-autofit=<[W[xH]]>\fP
5319 Set the initial window size to a maximum size specified by \fBWxH\fP, without
5320 changing the window\(aqs aspect ratio. The size is measured in pixels, or if
5321 a number is followed by a percentage sign (\fB%\fP), in percents of the
5322 screen size.
5323 .sp
5324 This option never changes the aspect ratio of the window. If the aspect
5325 ratio mismatches, the window\(aqs size is reduced until it fits into the
5326 specified size.
5327 .sp
5328 Window position is not taken into account, nor is it modified by this
5329 option (the window manager still may place the window differently depending
5330 on size). Use \fB\-\-geometry\fP to change the window position. Its effects
5331 are applied after this option.
5332 .sp
5333 See \fB\-\-geometry\fP for details how this is handled with multi\-monitor
5334 setups.
5335 .sp
5336 Use \fB\-\-autofit\-larger\fP instead if you just want to limit the maximum size
5337 of the window, rather than always forcing a window size.
5338 .sp
5339 Use \fB\-\-geometry\fP if you want to force both window width and height to a
5340 specific size.
5341 .sp
5342 \fBNOTE:\fP
5343 .INDENT 7.0
5344 .INDENT 3.5
5345 Generally only supported by GUI VOs. Ignored for encoding.
5346 .UNINDENT
5347 .UNINDENT
5348 .INDENT 7.0
5349 .INDENT 3.5
5350 .IP "Examples"
5351 .INDENT 0.0
5352 .TP
5353 .B \fB70%\fP
5354 Make the window width 70% of the screen size, keeping aspect ratio.
5355 .TP
5356 .B \fB1000\fP
5357 Set the window width to 1000 pixels, keeping aspect ratio.
5358 .TP
5359 .B \fB70%x60%\fP
5360 Make the window as large as possible, without being wider than 70%
5361 of the screen width, or higher than 60% of the screen height.
5362 .UNINDENT
5363 .UNINDENT
5364 .UNINDENT
5365 .TP
5366 .B \fB\-\-autofit\-larger=<[W[xH]]>\fP
5367 This option behaves exactly like \fB\-\-autofit\fP, except the window size is
5368 only changed if the window would be larger than the specified size.
5369 .INDENT 7.0
5370 .INDENT 3.5
5371 .IP "Example"
5372 .INDENT 0.0
5373 .TP
5374 .B \fB90%x80%\fP
5375 If the video is larger than 90% of the screen width or 80% of the
5376 screen height, make the window smaller until either its width is 90%
5377 of the screen, or its height is 80% of the screen.
5378 .UNINDENT
5379 .UNINDENT
5380 .UNINDENT
5381 .TP
5382 .B \fB\-\-autofit\-smaller=<[W[xH]]>\fP
5383 This option behaves exactly like \fB\-\-autofit\fP, except that it sets the
5384 minimum size of the window (just as \fB\-\-autofit\-larger\fP sets the maximum).
5385 .INDENT 7.0
5386 .INDENT 3.5
5387 .IP "Example"
5388 .INDENT 0.0
5389 .TP
5390 .B \fB500x500\fP
5391 Make the window at least 500 pixels wide and 500 pixels high
5392 (depending on the video aspect ratio, the width or height will be
5393 larger than 500 in order to keep the aspect ratio the same).
5394 .UNINDENT
5395 .UNINDENT
5396 .UNINDENT
5397 .TP
5398 .B \fB\-\-window\-scale=<factor>\fP
5399 Resize the video window to a multiple (or fraction) of the video size. This
5400 option is applied before \fB\-\-autofit\fP and other options are applied (so
5401 they override this option).
5402 .sp
5403 For example, \fB\-\-window\-scale=0.5\fP would show the window at half the
5404 video size.
5405 .TP
5406 .B \fB\-\-window\-minimized=<yes|no>\fP
5407 Whether the video window is minimized or not. Setting this will minimize,
5408 or unminimize, the video window if the current VO supports it. Note that
5409 some VOs may support minimization while not supporting unminimization
5410 (eg: Wayland).
5411 .sp
5412 Whether this option and \fB\-\-window\-maximized\fP work on program start or
5413 at runtime, and whether they\(aqre (at runtime) updated to reflect the actual
5414 window state, heavily depends on the VO and the windowing system. Some VOs
5415 simply do not implement them or parts of them, while other VOs may be
5416 restricted by the windowing systems (especially Wayland).
5417 .TP
5418 .B \fB\-\-window\-maximized=<yes|no>\fP
5419 Whether the video window is maximized or not. Setting this will maximize,
5420 or unmaximize, the video window if the current VO supports it. See
5421 \fB\-\-window\-minimized\fP for further remarks.
5422 .TP
5423 .B \fB\-\-cursor\-autohide=<number|no|always>\fP
5424 Make mouse cursor automatically hide after given number of milliseconds.
5425 \fBno\fP will disable cursor autohide. \fBalways\fP means the cursor will stay
5426 hidden.
5427 .TP
5428 .B \fB\-\-cursor\-autohide\-fs\-only\fP
5429 If this option is given, the cursor is always visible in windowed mode. In
5430 fullscreen mode, the cursor is shown or hidden according to
5431 \fB\-\-cursor\-autohide\fP\&.
5432 .TP
5433 .B \fB\-\-no\-fixed\-vo\fP, \fB\-\-fixed\-vo\fP
5434 \fB\-\-no\-fixed\-vo\fP enforces closing and reopening the video window for
5435 multiple files (one (un)initialization for each file).
5436 .TP
5437 .B \fB\-\-force\-rgba\-osd\-rendering\fP
5438 Change how some video outputs render the OSD and text subtitles. This
5439 does not change appearance of the subtitles and only has performance
5440 implications. For VOs which support native ASS rendering (like \fBgpu\fP,
5441 \fBvdpau\fP, \fBdirect3d\fP), this can be slightly faster or slower,
5442 depending on GPU drivers and hardware. For other VOs, this just makes
5443 rendering slower.
5444 .TP
5445 .B \fB\-\-force\-window\-position\fP
5446 Forcefully move mpv\(aqs video output window to default location whenever
5447 there is a change in video parameters, video stream or file. This used to
5448 be the default behavior. Currently only affects X11 VOs.
5449 .TP
5450 .B \fB\-\-no\-keepaspect\fP, \fB\-\-keepaspect\fP
5451 \fB\-\-no\-keepaspect\fP will always stretch the video to window size, and will
5452 disable the window manager hints that force the window aspect ratio.
5453 (Ignored in fullscreen mode.)
5454 .TP
5455 .B \fB\-\-no\-keepaspect\-window\fP, \fB\-\-keepaspect\-window\fP
5456 \fB\-\-keepaspect\-window\fP (the default) will lock the window size to the
5457 video aspect. \fB\-\-no\-keepaspect\-window\fP disables this behavior, and will
5458 instead add black bars if window aspect and video aspect mismatch. Whether
5459 this actually works depends on the VO backend.
5460 (Ignored in fullscreen mode.)
5461 .TP
5462 .B \fB\-\-monitoraspect=<ratio>\fP
5463 Set the aspect ratio of your monitor or TV screen. A value of 0 disables a
5464 previous setting (e.g. in the config file). Overrides the
5465 \fB\-\-monitorpixelaspect\fP setting if enabled.
5466 .sp
5467 See also \fB\-\-monitorpixelaspect\fP and \fB\-\-video\-aspect\-override\fP\&.
5468 .INDENT 7.0
5469 .INDENT 3.5
5470 .IP "Examples"
5471 .INDENT 0.0
5472 .IP \(bu 2
5473 \fB\-\-monitoraspect=4:3\fP or \fB\-\-monitoraspect=1.3333\fP
5474 .IP \(bu 2
5475 \fB\-\-monitoraspect=16:9\fP or \fB\-\-monitoraspect=1.7777\fP
5476 .UNINDENT
5477 .UNINDENT
5478 .UNINDENT
5479 .TP
5480 .B \fB\-\-hidpi\-window\-scale\fP, \fB\-\-no\-hidpi\-window\-scale\fP
5481 (OS X, Windows, X11, and Wayland only)
5482 Scale the window size according to the backing scale factor (default: yes).
5483 On regular HiDPI resolutions the window opens with double the size but appears
5484 as having the same size as on non\-HiDPI resolutions. This is the default OS X
5485 behavior.
5486 .TP
5487 .B \fB\-\-native\-fs\fP, \fB\-\-no\-native\-fs\fP
5488 (OS X only)
5489 Uses the native fullscreen mechanism of the OS (default: yes).
5490 .TP
5491 .B \fB\-\-monitorpixelaspect=<ratio>\fP
5492 Set the aspect of a single pixel of your monitor or TV screen (default:
5493 1). A value of 1 means square pixels (correct for (almost?) all LCDs). See
5494 also \fB\-\-monitoraspect\fP and \fB\-\-video\-aspect\-override\fP\&.
5495 .TP
5496 .B \fB\-\-stop\-screensaver\fP, \fB\-\-no\-stop\-screensaver\fP
5497 Turns off the screensaver (or screen blanker and similar mechanisms) at
5498 startup and turns it on again on exit (default: yes). The screensaver is
5499 always re\-enabled when the player is paused.
5500 .sp
5501 This is not supported on all video outputs or platforms. Sometimes it is
5502 implemented, but does not work (especially with Linux "desktops"). Read the
5503 \fI\%Disabling Screensaver\fP section very carefully.
5504 .TP
5505 .B \fB\-\-wid=<ID>\fP
5506 This tells mpv to attach to an existing window. If a VO is selected that
5507 supports this option, it will use that window for video output. mpv will
5508 scale the video to the size of this window, and will add black bars to
5509 compensate if the aspect ratio of the video is different.
5510 .sp
5511 On X11, the ID is interpreted as a \fBWindow\fP on X11. Unlike
5512 MPlayer/mplayer2, mpv always creates its own window, and sets the wid
5513 window as parent. The window will always be resized to cover the parent
5514 window fully. The value \fB0\fP is interpreted specially, and mpv will
5515 draw directly on the root window.
5516 .sp
5517 On win32, the ID is interpreted as \fBHWND\fP\&. Pass it as value cast to
5518 \fBintptr_t\fP\&. mpv will create its own window, and set the wid window as
5519 parent, like with X11.
5520 .sp
5521 On OSX/Cocoa, the ID is interpreted as \fBNSView*\fP\&. Pass it as value cast
5522 to \fBintptr_t\fP\&. mpv will create its own sub\-view. Because OSX does not
5523 support window embedding of foreign processes, this works only with libmpv,
5524 and will crash when used from the command line.
5525 .sp
5526 On Android, the ID is interpreted as \fBandroid.view.Surface\fP\&. Pass it as a
5527 value cast to \fBintptr_t\fP\&. Use with \fB\-\-vo=mediacodec_embed\fP and
5528 \fB\-\-hwdec=mediacodec\fP for direct rendering using MediaCodec, or with
5529 \fB\-\-vo=gpu \-\-gpu\-context=android\fP (with or without \fB\-\-hwdec=mediacodec\-copy\fP).
5530 .TP
5531 .B \fB\-\-no\-window\-dragging\fP
5532 Don\(aqt move the window when clicking on it and moving the mouse pointer.
5533 .TP
5534 .B \fB\-\-x11\-name\fP
5535 Set the window class name for X11\-based video output methods.
5536 .TP
5537 .B \fB\-\-x11\-netwm=<yes|no|auto>\fP
5538 (X11 only)
5539 Control the use of NetWM protocol features.
5540 .sp
5541 This may or may not help with broken window managers. This provides some
5542 functionality that was implemented by the now removed \fB\-\-fstype\fP option.
5543 Actually, it is not known to the developers to which degree this option
5544 was needed, so feedback is welcome.
5545 .sp
5546 Specifically, \fByes\fP will force use of NetWM fullscreen support, even if
5547 not advertised by the WM. This can be useful for WMs that are broken on
5548 purpose, like XMonad. (XMonad supposedly doesn\(aqt advertise fullscreen
5549 support, because Flash uses it. Apparently, applications which want to
5550 use fullscreen anyway are supposed to either ignore the NetWM support hints,
5551 or provide a workaround. Shame on XMonad for deliberately breaking X
5552 protocols (as if X isn\(aqt bad enough already).
5553 .sp
5554 By default, NetWM support is autodetected (\fBauto\fP).
5555 .sp
5556 This option might be removed in the future.
5557 .TP
5558 .B \fB\-\-x11\-bypass\-compositor=<yes|no|fs\-only|never>\fP
5559 If set to \fByes\fP, then ask the compositor to unredirect the mpv window
5560 (default: \fBfs\-only\fP). This uses the \fB_NET_WM_BYPASS_COMPOSITOR\fP hint.
5561 .sp
5562 \fBfs\-only\fP asks the window manager to disable the compositor only in
5563 fullscreen mode.
5564 .sp
5565 \fBno\fP sets \fB_NET_WM_BYPASS_COMPOSITOR\fP to 0, which is the default value
5566 as declared by the EWMH specification, i.e. no change is done.
5567 .sp
5568 \fBnever\fP asks the window manager to never disable the compositor.
5569 .UNINDENT
5570 .SS Disc Devices
5571 .INDENT 0.0
5572 .TP
5573 .B \fB\-\-cdrom\-device=<path>\fP
5574 Specify the CD\-ROM device (default: \fB/dev/cdrom\fP).
5575 .TP
5576 .B \fB\-\-dvd\-device=<path>\fP
5577 Specify the DVD device or .iso filename (default: \fB/dev/dvd\fP). You can
5578 also specify a directory that contains files previously copied directly
5579 from a DVD (with e.g. vobcopy).
5580 .INDENT 7.0
5581 .INDENT 3.5
5582 .IP "Example"
5583 .sp
5584 \fBmpv dvd:// \-\-dvd\-device=/path/to/dvd/\fP
5585 .UNINDENT
5586 .UNINDENT
5587 .TP
5588 .B \fB\-\-bluray\-device=<path>\fP
5589 (Blu\-ray only)
5590 Specify the Blu\-ray disc location. Must be a directory with Blu\-ray
5591 structure.
5592 .INDENT 7.0
5593 .INDENT 3.5
5594 .IP "Example"
5595 .sp
5596 \fBmpv bd:// \-\-bluray\-device=/path/to/bd/\fP
5597 .UNINDENT
5598 .UNINDENT
5599 .TP
5600 .B \fB\-\-cdda\-...\fP
5601 These options can be used to tune the CD Audio reading feature of mpv.
5602 .TP
5603 .B \fB\-\-cdda\-speed=<value>\fP
5604 Set CD spin speed.
5605 .TP
5606 .B \fB\-\-cdda\-paranoia=<0\-2>\fP
5607 Set paranoia level. Values other than 0 seem to break playback of
5608 anything but the first track.
5609 .INDENT 7.0
5610 .TP
5611 .B 0
5612 disable checking (default)
5613 .TP
5614 .B 1
5615 overlap checking only
5616 .TP
5617 .B 2
5618 full data correction and verification
5619 .UNINDENT
5620 .TP
5621 .B \fB\-\-cdda\-sector\-size=<value>\fP
5622 Set atomic read size.
5623 .TP
5624 .B \fB\-\-cdda\-overlap=<value>\fP
5625 Force minimum overlap search during verification to <value> sectors.
5626 .TP
5627 .B \fB\-\-cdda\-toc\-bias\fP
5628 Assume that the beginning offset of track 1 as reported in the TOC
5629 will be addressed as LBA 0. Some discs need this for getting track
5630 boundaries correctly.
5631 .TP
5632 .B \fB\-\-cdda\-toc\-offset=<value>\fP
5633 Add \fB<value>\fP sectors to the values reported when addressing tracks.
5634 May be negative.
5635 .TP
5636 .B \fB\-\-cdda\-skip=<yes|no>\fP
5637 (Never) accept imperfect data reconstruction.
5638 .TP
5639 .B \fB\-\-cdda\-cdtext=<yes|no>\fP
5640 Print CD text. This is disabled by default, because it ruins performance
5641 with CD\-ROM drives for unknown reasons.
5642 .TP
5643 .B \fB\-\-dvd\-speed=<speed>\fP
5644 Try to limit DVD speed (default: 0, no change). DVD base speed is 1385
5645 kB/s, so an 8x drive can read at speeds up to 11080 kB/s. Slower speeds
5646 make the drive more quiet. For watching DVDs, 2700 kB/s should be quiet and
5647 fast enough. mpv resets the speed to the drive default value on close.
5648 Values of at least 100 mean speed in kB/s. Values less than 100 mean
5649 multiples of 1385 kB/s, i.e. \fB\-\-dvd\-speed=8\fP selects 11080 kB/s.
5650 .sp
5651 \fBNOTE:\fP
5652 .INDENT 7.0
5653 .INDENT 3.5
5654 You need write access to the DVD device to change the speed.
5655 .UNINDENT
5656 .UNINDENT
5657 .TP
5658 .B \fB\-\-dvd\-angle=<ID>\fP
5659 Some DVDs contain scenes that can be viewed from multiple angles.
5660 This option tells mpv which angle to use (default: 1).
5661 .UNINDENT
5662 .SS Equalizer
5663 .INDENT 0.0
5664 .TP
5665 .B \fB\-\-brightness=<\-100\-100>\fP
5666 Adjust the brightness of the video signal (default: 0). Not supported by
5667 all video output drivers.
5668 .TP
5669 .B \fB\-\-contrast=<\-100\-100>\fP
5670 Adjust the contrast of the video signal (default: 0). Not supported by all
5671 video output drivers.
5672 .TP
5673 .B \fB\-\-saturation=<\-100\-100>\fP
5674 Adjust the saturation of the video signal (default: 0). You can get
5675 grayscale output with this option. Not supported by all video output
5676 drivers.
5677 .TP
5678 .B \fB\-\-gamma=<\-100\-100>\fP
5679 Adjust the gamma of the video signal (default: 0). Not supported by all
5680 video output drivers.
5681 .TP
5682 .B \fB\-\-hue=<\-100\-100>\fP
5683 Adjust the hue of the video signal (default: 0). You can get a colored
5684 negative of the image with this option. Not supported by all video output
5685 drivers.
5686 .UNINDENT
5687 .SS Demuxer
5688 .INDENT 0.0
5689 .TP
5690 .B \fB\-\-demuxer=<[+]name>\fP
5691 Force demuxer type. Use a \(aq+\(aq before the name to force it; this will skip
5692 some checks. Give the demuxer name as printed by \fB\-\-demuxer=help\fP\&.
5693 .TP
5694 .B \fB\-\-demuxer\-lavf\-analyzeduration=<value>\fP
5695 Maximum length in seconds to analyze the stream properties.
5696 .TP
5697 .B \fB\-\-demuxer\-lavf\-probe\-info=<yes|no|auto|nostreams>\fP
5698 Whether to probe stream information (default: auto). Technically, this
5699 controls whether libavformat\(aqs \fBavformat_find_stream_info()\fP function
5700 is called. Usually it\(aqs safer to call it, but it can also make startup
5701 slower.
5702 .sp
5703 The \fBauto\fP choice (the default) tries to skip this for a few know\-safe
5704 whitelisted formats, while calling it for everything else.
5705 .sp
5706 The \fBnostreams\fP choice only calls it if and only if the file seems to
5707 contain no streams after opening (helpful in cases when calling the function
5708 is needed to detect streams at all, such as with FLV files).
5709 .TP
5710 .B \fB\-\-demuxer\-lavf\-probescore=<1\-100>\fP
5711 Minimum required libavformat probe score. Lower values will require
5712 less data to be loaded (makes streams start faster), but makes file
5713 format detection less reliable. Can be used to force auto\-detected
5714 libavformat demuxers, even if libavformat considers the detection not
5715 reliable enough. (Default: 26.)
5716 .TP
5717 .B \fB\-\-demuxer\-lavf\-allow\-mimetype=<yes|no>\fP
5718 Allow deriving the format from the HTTP MIME type (default: yes). Set
5719 this to no in case playing things from HTTP mysteriously fails, even
5720 though the same files work from local disk.
5721 .sp
5722 This is default in order to reduce latency when opening HTTP streams.
5723 .TP
5724 .B \fB\-\-demuxer\-lavf\-format=<name>\fP
5725 Force a specific libavformat demuxer.
5726 .TP
5727 .B \fB\-\-demuxer\-lavf\-hacks=<yes|no>\fP
5728 By default, some formats will be handled differently from other formats
5729 by explicitly checking for them. Most of these compensate for weird or
5730 imperfect behavior from libavformat demuxers. Passing \fBno\fP disables
5731 these. For debugging and testing only.
5732 .TP
5733 .B \fB\-\-demuxer\-lavf\-o=<key>=<value>[,<key>=<value>[,...]]\fP
5734 Pass AVOptions to libavformat demuxer.
5735 .sp
5736 Note, a patch to make the \fIo=\fP unneeded and pass all unknown options
5737 through the AVOption system is welcome. A full list of AVOptions can
5738 be found in the FFmpeg manual. Note that some options may conflict
5739 with mpv options.
5740 .sp
5741 This is a key/value list option. See \fI\%List Options\fP for details.
5742 .INDENT 7.0
5743 .INDENT 3.5
5744 .IP "Example"
5745 .sp
5746 \fB\-\-demuxer\-lavf\-o=fflags=+ignidx\fP
5747 .UNINDENT
5748 .UNINDENT
5749 .TP
5750 .B \fB\-\-demuxer\-lavf\-probesize=<value>\fP
5751 Maximum amount of data to probe during the detection phase. In the
5752 case of MPEG\-TS this value identifies the maximum number of TS packets
5753 to scan.
5754 .TP
5755 .B \fB\-\-demuxer\-lavf\-buffersize=<value>\fP
5756 Size of the stream read buffer allocated for libavformat in bytes
5757 (default: 32768). Lowering the size could lower latency. Note that
5758 libavformat might reallocate the buffer internally, or not fully use all
5759 of it.
5760 .TP
5761 .B \fB\-\-demuxer\-lavf\-linearize\-timestamps=<yes|no|auto>\fP
5762 Attempt to linearize timestamp resets in demuxed streams (default: auto).
5763 This was tested only for single audio streams. It\(aqs unknown whether it
5764 works correctly for video (but likely won\(aqt). Note that the implementation
5765 is slightly incorrect either way, and will introduce a discontinuity by
5766 about 1 codec frame size.
5767 .sp
5768 The \fBauto\fP mode enables this for OGG audio stream. This covers the common
5769 and annoying case of OGG web radio streams. Some of these will reset
5770 timestamps to 0 every time a new song begins. This breaks the mpv seekable
5771 cache, which can\(aqt deal with timestamp resets. Note that FFmpeg/libavformat\(aqs
5772 seeking API can\(aqt deal with this either; it\(aqs likely that if this option
5773 breaks this even more, while if it\(aqs disabled, you can at least seek within
5774 the first song in the stream. Well, you won\(aqt get anything useful either
5775 way if the seek is outside of mpv\(aqs cache.
5776 .TP
5777 .B \fB\-\-demuxer\-lavf\-propagate\-opts=<yes|no>\fP
5778 Propagate FFmpeg\-level options to recursively opened connections (default:
5779 yes). This is needed because FFmpeg will apply these settings to nested
5780 AVIO contexts automatically. On the other hand, this could break in certain
5781 situations \- it\(aqs the FFmpeg API, you just can\(aqt win.
5782 .sp
5783 This affects in particular the \fB\-\-timeout\fP option and anything passed
5784 with \fB\-\-demuxer\-lavf\-o\fP\&.
5785 .sp
5786 If this option is deemed unnecessary at some point in the future, it will
5787 be removed without notice.
5788 .TP
5789 .B \fB\-\-demuxer\-mkv\-subtitle\-preroll=<yes|index|no>\fP, \fB\-\-mkv\-subtitle\-preroll\fP
5790 Try harder to show embedded soft subtitles when seeking somewhere. Normally,
5791 it can happen that the subtitle at the seek target is not shown due to how
5792 some container file formats are designed. The subtitles appear only if
5793 seeking before or exactly to the position a subtitle first appears. To
5794 make this worse, subtitles are often timed to appear a very small amount
5795 before the associated video frame, so that seeking to the video frame
5796 typically does not demux the subtitle at that position.
5797 .sp
5798 Enabling this option makes the demuxer start reading data a bit before the
5799 seek target, so that subtitles appear correctly. Note that this makes
5800 seeking slower, and is not guaranteed to always work. It only works if the
5801 subtitle is close enough to the seek target.
5802 .sp
5803 Works with the internal Matroska demuxer only. Always enabled for absolute
5804 and hr\-seeks, and this option changes behavior with relative or imprecise
5805 seeks only.
5806 .sp
5807 You can use the \fB\-\-demuxer\-mkv\-subtitle\-preroll\-secs\fP option to specify
5808 how much data the demuxer should pre\-read at most in order to find subtitle
5809 packets that may overlap. Setting this to 0 will effectively disable this
5810 preroll mechanism. Setting a very large value can make seeking very slow,
5811 and an extremely large value would completely reread the entire file from
5812 start to seek target on every seek \- seeking can become slower towards the
5813 end of the file. The details are messy, and the value is actually rounded
5814 down to the cluster with the previous video keyframe.
5815 .sp
5816 Some files, especially files muxed with newer mkvmerge versions, have
5817 information embedded that can be used to determine what subtitle packets
5818 overlap with a seek target. In these cases, mpv will reduce the amount
5819 of data read to a minimum. (Although it will still read \fIall\fP data between
5820 the cluster that contains the first wanted subtitle packet, and the seek
5821 target.) If the \fBindex\fP choice (which is the default) is specified, then
5822 prerolling will be done only if this information is actually available. If
5823 this method is used, the maximum amount of data to skip can be additionally
5824 controlled by \fB\-\-demuxer\-mkv\-subtitle\-preroll\-secs\-index\fP (it still uses
5825 the value of the option without \fB\-index\fP if that is higher).
5826 .sp
5827 See also \fB\-\-hr\-seek\-demuxer\-offset\fP option. This option can achieve a
5828 similar effect, but only if hr\-seek is active. It works with any demuxer,
5829 but makes seeking much slower, as it has to decode audio and video data
5830 instead of just skipping over it.
5831 .sp
5832 \fB\-\-mkv\-subtitle\-preroll\fP is a deprecated alias.
5833 .TP
5834 .B \fB\-\-demuxer\-mkv\-subtitle\-preroll\-secs=<value>\fP
5835 See \fB\-\-demuxer\-mkv\-subtitle\-preroll\fP\&.
5836 .TP
5837 .B \fB\-\-demuxer\-mkv\-subtitle\-preroll\-secs\-index=<value>\fP
5838 See \fB\-\-demuxer\-mkv\-subtitle\-preroll\fP\&.
5839 .TP
5840 .B \fB\-\-demuxer\-mkv\-probe\-start\-time=<yes|no>\fP
5841 Check the start time of Matroska files (default: yes). This simply reads the
5842 first cluster timestamps and assumes it is the start time. Technically, this
5843 also reads the first timestamp, which may increase latency by one frame
5844 (which may be relevant for live streams).
5845 .TP
5846 .B \fB\-\-demuxer\-mkv\-probe\-video\-duration=<yes|no|full>\fP
5847 When opening the file, seek to the end of it, and check what timestamp the
5848 last video packet has, and report that as file duration. This is strictly
5849 for compatibility with Haali only. In this mode, it\(aqs possible that opening
5850 will be slower (especially when playing over http), or that behavior with
5851 broken files is much worse. So don\(aqt use this option.
5852 .sp
5853 The \fByes\fP mode merely uses the index and reads a small number of blocks
5854 from the end of the file. The \fBfull\fP mode actually traverses the entire
5855 file and can make a reliable estimate even without an index present (such
5856 as partial files).
5857 .TP
5858 .B \fB\-\-demuxer\-rawaudio\-channels=<value>\fP
5859 Number of channels (or channel layout) if \fB\-\-demuxer=rawaudio\fP is used
5860 (default: stereo).
5861 .TP
5862 .B \fB\-\-demuxer\-rawaudio\-format=<value>\fP
5863 Sample format for \fB\-\-demuxer=rawaudio\fP (default: s16le).
5864 Use \fB\-\-demuxer\-rawaudio\-format=help\fP to get a list of all formats.
5865 .TP
5866 .B \fB\-\-demuxer\-rawaudio\-rate=<value>\fP
5867 Sample rate for \fB\-\-demuxer=rawaudio\fP (default: 44 kHz).
5868 .TP
5869 .B \fB\-\-demuxer\-rawvideo\-fps=<value>\fP
5870 Rate in frames per second for \fB\-\-demuxer=rawvideo\fP (default: 25.0).
5871 .TP
5872 .B \fB\-\-demuxer\-rawvideo\-w=<value>\fP, \fB\-\-demuxer\-rawvideo\-h=<value>\fP
5873 Image dimension in pixels for \fB\-\-demuxer=rawvideo\fP\&.
5874 .INDENT 7.0
5875 .INDENT 3.5
5876 .IP "Example"
5877 .sp
5878 Play a raw YUV sample:
5879 .INDENT 0.0
5880 .INDENT 3.5
5881 .sp
5882 .nf
5883 .ft C
5884 mpv sample\-720x576.yuv \-\-demuxer=rawvideo \e
5885 \-\-demuxer\-rawvideo\-w=720 \-\-demuxer\-rawvideo\-h=576
5886 .ft P
5887 .fi
5888 .UNINDENT
5889 .UNINDENT
5890 .UNINDENT
5891 .UNINDENT
5892 .TP
5893 .B \fB\-\-demuxer\-rawvideo\-format=<value>\fP
5894 Color space (fourcc) in hex or string for \fB\-\-demuxer=rawvideo\fP
5895 (default: \fBYV12\fP).
5896 .TP
5897 .B \fB\-\-demuxer\-rawvideo\-mp\-format=<value>\fP
5898 Color space by internal video format for \fB\-\-demuxer=rawvideo\fP\&. Use
5899 \fB\-\-demuxer\-rawvideo\-mp\-format=help\fP for a list of possible formats.
5900 .TP
5901 .B \fB\-\-demuxer\-rawvideo\-codec=<value>\fP
5902 Set the video codec instead of selecting the rawvideo codec when using
5903 \fB\-\-demuxer=rawvideo\fP\&. This uses the same values as codec names in
5904 \fB\-\-vd\fP (but it does not accept decoder names).
5905 .TP
5906 .B \fB\-\-demuxer\-rawvideo\-size=<value>\fP
5907 Frame size in bytes when using \fB\-\-demuxer=rawvideo\fP\&.
5908 .TP
5909 .B \fB\-\-demuxer\-cue\-codepage=<codepage>\fP
5910 Specify the CUE sheet codepage. (See \fB\-\-sub\-codepage\fP for details.)
5911 .TP
5912 .B \fB\-\-demuxer\-max\-bytes=<bytesize>\fP
5913 This controls how much the demuxer is allowed to buffer ahead. The demuxer
5914 will normally try to read ahead as much as necessary, or as much is
5915 requested with \fB\-\-demuxer\-readahead\-secs\fP\&. The option can be used to
5916 restrict the maximum readahead. This limits excessive readahead in case of
5917 broken files or desynced playback. The demuxer will stop reading additional
5918 packets as soon as one of the limits is reached. (The limits still can be
5919 slightly overstepped due to technical reasons.)
5920 .sp
5921 Set these limits higher if you get a packet queue overflow warning, and
5922 you think normal playback would be possible with a larger packet queue.
5923 .sp
5924 See \fB\-\-list\-options\fP for defaults and value range. \fB<bytesize>\fP options
5925 accept suffixes such as \fBKiB\fP and \fBMiB\fP\&.
5926 .TP
5927 .B \fB\-\-demuxer\-max\-back\-bytes=<bytesize>\fP
5928 This controls how much past data the demuxer is allowed to preserve. This
5929 is useful only if the cache is enabled.
5930 .sp
5931 Unlike the forward cache, there is no control how many seconds are actually
5932 cached \- it will simply use as much memory this option allows. Setting this
5933 option to 0 will strictly disable any back buffer, but this will lead to
5934 the situation that the forward seek range starts after the current playback
5935 position (as it removes past packets that are seek points).
5936 .sp
5937 If the end of the file is reached, the remaining unused forward buffer space
5938 is "donated" to the backbuffer (unless the backbuffer size is set to 0, or
5939 \fB\-\-demuxer\-donate\-buffer\fP is set to \fBno\fP).
5940 This still limits the total cache usage to the sum of the forward and
5941 backward cache, and effectively makes better use of the total allowed memory
5942 budget. (The opposite does not happen: free backward buffer is never
5943 "donated" to the forward buffer.)
5944 .sp
5945 Keep in mind that other buffers in the player (like decoders) will cause the
5946 demuxer to cache "future" frames in the back buffer, which can skew the
5947 impression about how much data the backbuffer contains.
5948 .sp
5949 See \fB\-\-list\-options\fP for defaults and value range.
5950 .TP
5951 .B \fB\-\-demuxer\-donate\-buffer=<yes|no>\fP
5952 Whether to let the back buffer use part of the forward buffer (default: yes).
5953 If set to \fByes\fP, the "donation" behavior described in the option
5954 description for \fB\-\-demuxer\-max\-back\-bytes\fP is enabled. This means the
5955 back buffer may use up memory up to the sum of the forward and back buffer
5956 options, minus the active size of the forward buffer. If set to \fBno\fP, the
5957 options strictly limit the forward and back buffer sizes separately.
5958 .sp
5959 Note that if the end of the file is reached, the buffered data stays the
5960 same, even if you seek back within the cache. This is because the back
5961 buffer is only reduced when new data is read.
5962 .TP
5963 .B \fB\-\-demuxer\-seekable\-cache=<yes|no|auto>\fP
5964 Debugging option to control whether seeking can use the demuxer cache
5965 (default: auto). Normally you don\(aqt ever need to set this; the default
5966 \fBauto\fP does the right thing and enables cache seeking it if \fB\-\-cache\fP
5967 is set to \fByes\fP (or is implied \fByes\fP if \fB\-\-cache=auto\fP).
5968 .sp
5969 If enabled, short seek offsets will not trigger a low level demuxer seek
5970 (which means for example that slow network round trips or FFmpeg seek bugs
5971 can be avoided). If a seek cannot happen within the cached range, a low
5972 level seek will be triggered. Seeking outside of the cache will start a new
5973 cached range, but can discard the old cache range if the demuxer exhibits
5974 certain unsupported behavior.
5975 .sp
5976 The special value \fBauto\fP means \fByes\fP in the same situation as
5977 \fB\-\-cache\-secs\fP is used (i.e. when the stream appears to be a network
5978 stream or the stream cache is enabled).
5979 .TP
5980 .B \fB\-\-demuxer\-force\-retry\-on\-eof=<yes|no>\fP
5981 Whether to keep retrying making the demuxer thread read more packets each
5982 time the decoder dequeues a packet, even if the end of the file was reached
5983 (default: no). This does not really make sense, but was the default behavior
5984 in mpv 0.32.0 and earlier. This option will be silently removed after a
5985 while, and exists only to restore the old behavior for testing, in case this
5986 was actually needed somewhere. This does _not_ help with files that are
5987 being appended to (in these cases use \fBappending://\fP, or disable the
5988 cache).
5989 .TP
5990 .B \fB\-\-demuxer\-thread=<yes|no>\fP
5991 Run the demuxer in a separate thread, and let it prefetch a certain amount
5992 of packets (default: yes). Having this enabled leads to smoother playback,
5993 enables features like prefetching, and prevents that stuck network freezes
5994 the player. On the other hand, it can add overhead, or the background
5995 prefetching can hog CPU resources.
5996 .sp
5997 Disabling this option is not recommended. Use it for debugging only.
5998 .TP
5999 .B \fB\-\-demuxer\-termination\-timeout=<seconds>\fP
6000 Number of seconds the player should wait to shutdown the demuxer (default:
6001 0.1). The player will wait up to this much time before it closes the
6002 stream layer forcefully. Forceful closing usually means the network I/O is
6003 given no chance to close its connections gracefully (of course the OS can
6004 still close TCP connections properly), and might result in annoying messages
6005 being logged, and in some cases, confused remote servers.
6006 .sp
6007 This timeout is usually only applied when loading has finished properly. If
6008 loading is aborted by the user, or in some corner cases like removing
6009 external tracks sourced from network during playback, forceful closing is
6010 always used.
6011 .TP
6012 .B \fB\-\-demuxer\-readahead\-secs=<seconds>\fP
6013 If \fB\-\-demuxer\-thread\fP is enabled, this controls how much the demuxer
6014 should buffer ahead in seconds (default: 1). As long as no packet has
6015 a timestamp difference higher than the readahead amount relative to the
6016 last packet returned to the decoder, the demuxer keeps reading.
6017 .sp
6018 Note that enabling the cache (such as \fB\-\-cache=yes\fP, or if the input
6019 is considered a network stream, and \fB\-\-cache=auto\fP is used), this option
6020 is mostly ignored. (\fB\-\-cache\-secs\fP will override this. Technically, the
6021 maximum of both options is used.)
6022 .sp
6023 The main purpose of this option is to limit the readhead for local playback,
6024 since a large readahead value is not overly useful in this case.
6025 .sp
6026 (This value tends to be fuzzy, because many file formats don\(aqt store linear
6027 timestamps.)
6028 .TP
6029 .B \fB\-\-prefetch\-playlist=<yes|no>\fP
6030 Prefetch next playlist entry while playback of the current entry is ending
6031 (default: no). This merely opens the URL of the next playlist entry as soon
6032 as the current URL is fully read.
6033 .sp
6034 This does \fBnot\fP work with URLs resolved by the \fByoutube\-dl\fP wrapper,
6035 and it won\(aqt.
6036 .sp
6037 This does not affect HLS (\fB\&.m3u8\fP URLs) \- HLS prefetching depends on the
6038 demuxer cache settings and is on by default.
6039 .sp
6040 This can give subtly wrong results if per\-file options are used, or if
6041 options are changed in the time window between prefetching start and next
6042 file played.
6043 .sp
6044 This can occasionally make wrong prefetching decisions. For example, it
6045 can\(aqt predict whether you go backwards in the playlist, and assumes you
6046 won\(aqt edit the playlist.
6047 .sp
6048 Highly experimental.
6049 .TP
6050 .B \fB\-\-force\-seekable=<yes|no>\fP
6051 If the player thinks that the media is not seekable (e.g. playing from a
6052 pipe, or it\(aqs an http stream with a server that doesn\(aqt support range
6053 requests), seeking will be disabled. This option can forcibly enable it.
6054 For seeks within the cache, there\(aqs a good chance of success.
6055 .TP
6056 .B \fB\-\-demuxer\-cache\-wait=<yes|no>\fP
6057 Before starting playback, read data until either the end of the file was
6058 reached, or the demuxer cache has reached maximum capacity. Only once this
6059 is done, playback starts. This intentionally happens before the initial
6060 seek triggered with \fB\-\-start\fP\&. This does not change any runtime behavior
6061 after the initial caching. This option is useless if the file cannot be
6062 cached completely.
6063 .TP
6064 .B \fB\-\-rar\-list\-all\-volumes=<yes|no>\fP
6065 When opening multi\-volume rar files, open all volumes to create a full list
6066 of contained files (default: no). If disabled, only the archive entries
6067 whose headers are located within the first volume are listed (and thus
6068 played when opening a .rar file with mpv). Doing so speeds up opening, and
6069 the typical idiotic use\-case of playing uncompressed multi\-volume rar files
6070 that contain a single media file is made faster.
6071 .sp
6072 Opening is still slow, because for unknown, idiotic, and unnecessary reasons
6073 libarchive opens all volumes anyway when playing the main file, even though
6074 mpv iterated no archive entries yet.
6075 .UNINDENT
6076 .SS Input
6077 .INDENT 0.0
6078 .TP
6079 .B \fB\-\-native\-keyrepeat\fP
6080 Use system settings for keyrepeat delay and rate, instead of
6081 \fB\-\-input\-ar\-delay\fP and \fB\-\-input\-ar\-rate\fP\&. (Whether this applies
6082 depends on the VO backend and how it handles keyboard input. Does not
6083 apply to terminal input.)
6084 .TP
6085 .B \fB\-\-input\-ar\-delay\fP
6086 Delay in milliseconds before we start to autorepeat a key (0 to disable).
6087 .TP
6088 .B \fB\-\-input\-ar\-rate\fP
6089 Number of key presses to generate per second on autorepeat.
6090 .TP
6091 .B \fB\-\-input\-conf=<filename>\fP
6092 Specify input configuration file other than the default location in the mpv
6093 configuration directory (usually \fB~/.config/mpv/input.conf\fP).
6094 .TP
6095 .B \fB\-\-no\-input\-default\-bindings\fP
6096 Disable mpv default (built\-in) key bindings.
6097 .TP
6098 .B \fB\-\-input\-cmdlist\fP
6099 Prints all commands that can be bound to keys.
6100 .TP
6101 .B \fB\-\-input\-doubleclick\-time=<milliseconds>\fP
6102 Time in milliseconds to recognize two consecutive button presses as a
6103 double\-click (default: 300).
6104 .TP
6105 .B \fB\-\-input\-keylist\fP
6106 Prints all keys that can be bound to commands.
6107 .TP
6108 .B \fB\-\-input\-key\-fifo\-size=<2\-65000>\fP
6109 Specify the size of the FIFO that buffers key events (default: 7). If it
6110 is too small, some events may be lost. The main disadvantage of setting it
6111 to a very large value is that if you hold down a key triggering some
6112 particularly slow command then the player may be unresponsive while it
6113 processes all the queued commands.
6114 .TP
6115 .B \fB\-\-input\-test\fP
6116 Input test mode. Instead of executing commands on key presses, mpv
6117 will show the keys and the bound commands on the OSD. Has to be used
6118 with a dummy video, and the normal ways to quit the player will not
6119 work (key bindings that normally quit will be shown on OSD only, just
6120 like any other binding). See \fI\%INPUT.CONF\fP\&.
6121 .TP
6122 .B \fB\-\-input\-terminal\fP, \fB\-\-no\-input\-terminal\fP
6123 \fB\-\-no\-input\-terminal\fP prevents the player from reading key events from
6124 standard input. Useful when reading data from standard input. This is
6125 automatically enabled when \fB\-\fP is found on the command line. There are
6126 situations where you have to set it manually, e.g. if you open
6127 \fB/dev/stdin\fP (or the equivalent on your system), use stdin in a playlist
6128 or intend to read from stdin later on via the loadfile or loadlist input
6129 commands.
6130 .TP
6131 .B \fB\-\-input\-ipc\-server=<filename>\fP
6132 Enable the IPC support and create the listening socket at the given path.
6133 .sp
6134 On Linux and Unix, the given path is a regular filesystem path. On Windows,
6135 named pipes are used, so the path refers to the pipe namespace
6136 (\fB\e\e.\epipe\e<name>\fP). If the \fB\e\e.\epipe\e\fP prefix is missing, mpv will add
6137 it automatically before creating the pipe, so
6138 \fB\-\-input\-ipc\-server=/tmp/mpv\-socket\fP and
6139 \fB\-\-input\-ipc\-server=\e\e.\epipe\etmp\empv\-socket\fP are equivalent for IPC on
6140 Windows.
6141 .sp
6142 See \fI\%JSON IPC\fP for details.
6143 .TP
6144 .B \fB\-\-input\-ipc\-client=fd://<N>\fP
6145 Connect a single IPC client to the given FD. This is somewhat similar to
6146 \fB\-\-input\-ipc\-server\fP, except no socket is created, and instead the passed
6147 FD is treated like a socket connection received from \fBaccept()\fP\&. In
6148 practice, you could pass either a FD created by \fBsocketpair()\fP, or a pipe.
6149 In both cases, you must sure the FD is actually inherited by mpv (do not
6150 set the POSIX \fBCLOEXEC\fP flag).
6151 .sp
6152 The player quits when the connection is closed.
6153 .sp
6154 This is somewhat similar to the removed \fB\-\-input\-file\fP option, except it
6155 supports only integer FDs, and cannot open actual paths.
6156 .INDENT 7.0
6157 .INDENT 3.5
6158 .IP "Example"
6159 .sp
6160 \fB\-\-input\-ipc\-client=fd://123\fP
6161 .UNINDENT
6162 .UNINDENT
6163 .sp
6164 \fBNOTE:\fP
6165 .INDENT 7.0
6166 .INDENT 3.5
6167 Does not and will not work on Windows.
6168 .UNINDENT
6169 .UNINDENT
6170 .sp
6171 \fBWARNING:\fP
6172 .INDENT 7.0
6173 .INDENT 3.5
6174 Writing to the \fBinput\-ipc\-server\fP option at runtime will start another
6175 instance of an IPC client handler for the \fBinput\-ipc\-client\fP option,
6176 because initialization is bundled, and this thing is stupid. This is a
6177 bug. Writing to \fBinput\-ipc\-client\fP at runtime will start another IPC
6178 client handler for the new value, without stopping the old one, even if
6179 the FD value is the same (but the string is different e.g. due to
6180 whitespace). This is not a bug.
6181 .UNINDENT
6182 .UNINDENT
6183 .TP
6184 .B \fB\-\-input\-gamepad=<yes|no>\fP
6185 Enable/disable SDL2 Gamepad support. Disabled by default.
6186 .TP
6187 .B \fB\-\-input\-cursor\fP, \fB\-\-no\-input\-cursor\fP
6188 Permit mpv to receive pointer events reported by the video output
6189 driver. Necessary to use the OSC, or to select the buttons in DVD menus.
6190 Support depends on the VO in use.
6191 .TP
6192 .B \fB\-\-input\-media\-keys=<yes|no>\fP
6193 (OS X and Windows only)
6194 Enable/disable media keys support. Enabled by default (except for libmpv).
6195 .TP
6196 .B \fB\-\-input\-right\-alt\-gr\fP, \fB\-\-no\-input\-right\-alt\-gr\fP
6197 (Cocoa and Windows only)
6198 Use the right Alt key as Alt Gr to produce special characters. If disabled,
6199 count the right Alt as an Alt modifier key. Enabled by default.
6200 .TP
6201 .B \fB\-\-input\-vo\-keyboard=<yes|no>\fP
6202 Disable all keyboard input on for VOs which can\(aqt participate in proper
6203 keyboard input dispatching. May not affect all VOs. Generally useful for
6204 embedding only.
6205 .sp
6206 On X11, a sub\-window with input enabled grabs all keyboard input as long
6207 as it is 1. a child of a focused window, and 2. the mouse is inside of
6208 the sub\-window. It can steal away all keyboard input from the
6209 application embedding the mpv window, and on the other hand, the mpv
6210 window will receive no input if the mouse is outside of the mpv window,
6211 even though mpv has focus. Modern toolkits work around this weird X11
6212 behavior, but naively embedding foreign windows breaks it.
6213 .sp
6214 The only way to handle this reasonably is using the XEmbed protocol, which
6215 was designed to solve these problems. GTK provides \fBGtkSocket\fP, which
6216 supports XEmbed. Qt doesn\(aqt seem to provide anything working in newer
6217 versions.
6218 .sp
6219 If the embedder supports XEmbed, input should work with default settings
6220 and with this option disabled. Note that \fBinput\-default\-bindings\fP is
6221 disabled by default in libmpv as well \- it should be enabled if you want
6222 the mpv default key bindings.
6223 .sp
6224 (This option was renamed from \fB\-\-input\-x11\-keyboard\fP\&.)
6225 .UNINDENT
6226 .SS OSD
6227 .INDENT 0.0
6228 .TP
6229 .B \fB\-\-osc\fP, \fB\-\-no\-osc\fP
6230 Whether to load the on\-screen\-controller (default: yes).
6231 .TP
6232 .B \fB\-\-no\-osd\-bar\fP, \fB\-\-osd\-bar\fP
6233 Disable display of the OSD bar.
6234 .sp
6235 You can configure this on a per\-command basis in input.conf using \fBosd\-\fP
6236 prefixes, see \fBInput Command Prefixes\fP\&. If you want to disable the OSD
6237 completely, use \fB\-\-osd\-level=0\fP\&.
6238 .TP
6239 .B \fB\-\-osd\-on\-seek=<no,bar,msg,msg\-bar>\fP
6240 Set what is displayed on the OSD during seeks. The default is \fBbar\fP\&.
6241 .sp
6242 You can configure this on a per\-command basis in input.conf using \fBosd\-\fP
6243 prefixes, see \fBInput Command Prefixes\fP\&.
6244 .TP
6245 .B \fB\-\-osd\-duration=<time>\fP
6246 Set the duration of the OSD messages in ms (default: 1000).
6247 .TP
6248 .B \fB\-\-osd\-font=<name>\fP
6249 Specify font to use for OSD. The default is \fBsans\-serif\fP\&.
6250 .INDENT 7.0
6251 .INDENT 3.5
6252 .IP "Examples"
6253 .INDENT 0.0
6254 .IP \(bu 2
6255 \fB\-\-osd\-font=\(aqBitstream Vera Sans\(aq\fP
6256 .IP \(bu 2
6257 \fB\-\-osd\-font=\(aqComic Sans MS\(aq\fP
6258 .UNINDENT
6259 .UNINDENT
6260 .UNINDENT
6261 .TP
6262 .B \fB\-\-osd\-font\-size=<size>\fP
6263 Specify the OSD font size. See \fB\-\-sub\-font\-size\fP for details.
6264 .sp
6265 Default: 55.
6266 .TP
6267 .B \fB\-\-osd\-msg1=<string>\fP
6268 Show this string as message on OSD with OSD level 1 (visible by default).
6269 The message will be visible by default, and as long as no other message
6270 covers it, and the OSD level isn\(aqt changed (see \fB\-\-osd\-level\fP).
6271 Expands properties; see \fI\%Property Expansion\fP\&.
6272 .TP
6273 .B \fB\-\-osd\-msg2=<string>\fP
6274 Similar to \fB\-\-osd\-msg1\fP, but for OSD level 2. If this is an empty string
6275 (default), then the playback time is shown.
6276 .TP
6277 .B \fB\-\-osd\-msg3=<string>\fP
6278 Similar to \fB\-\-osd\-msg1\fP, but for OSD level 3. If this is an empty string
6279 (default), then the playback time, duration, and some more information is
6280 shown.
6281 .sp
6282 This is used for the \fBshow\-progress\fP command (by default mapped to \fBP\fP),
6283 and when seeking if enabled with \fB\-\-osd\-on\-seek\fP or by \fBosd\-\fP prefixes
6284 in input.conf (see \fBInput Command Prefixes\fP).
6285 .sp
6286 \fB\-\-osd\-status\-msg\fP is a legacy equivalent (but with a minor difference).
6287 .TP
6288 .B \fB\-\-osd\-status\-msg=<string>\fP
6289 Show a custom string during playback instead of the standard status text.
6290 This overrides the status text used for \fB\-\-osd\-level=3\fP, when using the
6291 \fBshow\-progress\fP command (by default mapped to \fBP\fP), and when seeking if
6292 enabled with \fB\-\-osd\-on\-seek\fP or \fBosd\-\fP prefixes in input.conf (see
6293 \fBInput Command Prefixes\fP). Expands properties. See \fI\%Property Expansion\fP\&.
6294 .sp
6295 This option has been replaced with \fB\-\-osd\-msg3\fP\&. The only difference is
6296 that this option implicitly includes \fB${osd\-sym\-cc}\fP\&. This option is
6297 ignored if \fB\-\-osd\-msg3\fP is not empty.
6298 .TP
6299 .B \fB\-\-osd\-playing\-msg=<string>\fP
6300 Show a message on OSD when playback starts. The string is expanded for
6301 properties, e.g. \fB\-\-osd\-playing\-msg=\(aqfile: ${filename}\(aq\fP will show the
6302 message \fBfile:\fP followed by a space and the currently played filename.
6303 .sp
6304 See \fI\%Property Expansion\fP\&.
6305 .TP
6306 .B \fB\-\-osd\-bar\-align\-x=<\-1\-1>\fP
6307 Position of the OSD bar. \-1 is far left, 0 is centered, 1 is far right.
6308 Fractional values (like 0.5) are allowed.
6309 .TP
6310 .B \fB\-\-osd\-bar\-align\-y=<\-1\-1>\fP
6311 Position of the OSD bar. \-1 is top, 0 is centered, 1 is bottom.
6312 Fractional values (like 0.5) are allowed.
6313 .TP
6314 .B \fB\-\-osd\-bar\-w=<1\-100>\fP
6315 Width of the OSD bar, in percentage of the screen width (default: 75).
6316 A value of 50 means the bar is half the screen wide.
6317 .TP
6318 .B \fB\-\-osd\-bar\-h=<0.1\-50>\fP
6319 Height of the OSD bar, in percentage of the screen height (default: 3.125).
6320 .TP
6321 .B \fB\-\-osd\-back\-color=<color>\fP
6322 See \fB\-\-sub\-color\fP\&. Color used for OSD text background.
6323 .TP
6324 .B \fB\-\-osd\-blur=<0..20.0>\fP
6325 Gaussian blur factor. 0 means no blur applied (default).
6326 .TP
6327 .B \fB\-\-osd\-bold=<yes|no>\fP
6328 Format text on bold.
6329 .TP
6330 .B \fB\-\-osd\-italic=<yes|no>\fP
6331 Format text on italic.
6332 .TP
6333 .B \fB\-\-osd\-border\-color=<color>\fP
6334 See \fB\-\-sub\-color\fP\&. Color used for the OSD font border.
6335 .sp
6336 \fBNOTE:\fP
6337 .INDENT 7.0
6338 .INDENT 3.5
6339 ignored when \fB\-\-osd\-back\-color\fP is
6340 specified (or more exactly: when that option is not set to completely
6341 transparent).
6342 .UNINDENT
6343 .UNINDENT
6344 .TP
6345 .B \fB\-\-osd\-border\-size=<size>\fP
6346 Size of the OSD font border in scaled pixels (see \fB\-\-sub\-font\-size\fP
6347 for details). A value of 0 disables borders.
6348 .sp
6349 Default: 3.
6350 .TP
6351 .B \fB\-\-osd\-color=<color>\fP
6352 Specify the color used for OSD.
6353 See \fB\-\-sub\-color\fP for details.
6354 .TP
6355 .B \fB\-\-osd\-fractions\fP
6356 Show OSD times with fractions of seconds (in millisecond precision). Useful
6357 to see the exact timestamp of a video frame.
6358 .TP
6359 .B \fB\-\-osd\-level=<0\-3>\fP
6360 Specifies which mode the OSD should start in.
6361 .INDENT 7.0
6362 .TP
6363 .B 0
6364 OSD completely disabled (subtitles only)
6365 .TP
6366 .B 1
6367 enabled (shows up only on user interaction)
6368 .TP
6369 .B 2
6370 enabled + current time visible by default
6371 .TP
6372 .B 3
6373 enabled + \fB\-\-osd\-status\-msg\fP (current time and status by default)
6374 .UNINDENT
6375 .TP
6376 .B \fB\-\-osd\-margin\-x=<size>\fP
6377 Left and right screen margin for the OSD in scaled pixels (see
6378 \fB\-\-sub\-font\-size\fP for details).
6379 .sp
6380 This option specifies the distance of the OSD to the left, as well as at
6381 which distance from the right border long OSD text will be broken.
6382 .sp
6383 Default: 25.
6384 .TP
6385 .B \fB\-\-osd\-margin\-y=<size>\fP
6386 Top and bottom screen margin for the OSD in scaled pixels (see
6387 \fB\-\-sub\-font\-size\fP for details).
6388 .sp
6389 This option specifies the vertical margins of the OSD.
6390 .sp
6391 Default: 22.
6392 .TP
6393 .B \fB\-\-osd\-align\-x=<left|center|right>\fP
6394 Control to which corner of the screen OSD should be
6395 aligned to (default: \fBleft\fP).
6396 .TP
6397 .B \fB\-\-osd\-align\-y=<top|center|bottom>\fP
6398 Vertical position (default: \fBtop\fP).
6399 Details see \fB\-\-osd\-align\-x\fP\&.
6400 .TP
6401 .B \fB\-\-osd\-scale=<factor>\fP
6402 OSD font size multiplier, multiplied with \fB\-\-osd\-font\-size\fP value.
6403 .TP
6404 .B \fB\-\-osd\-scale\-by\-window=<yes|no>\fP
6405 Whether to scale the OSD with the window size (default: yes). If this is
6406 disabled, \fB\-\-osd\-font\-size\fP and other OSD options that use scaled pixels
6407 are always in actual pixels. The effect is that changing the window size
6408 won\(aqt change the OSD font size.
6409 .TP
6410 .B \fB\-\-osd\-shadow\-color=<color>\fP
6411 See \fB\-\-sub\-color\fP\&. Color used for OSD shadow.
6412 .TP
6413 .B \fB\-\-osd\-shadow\-offset=<size>\fP
6414 Displacement of the OSD shadow in scaled pixels (see
6415 \fB\-\-sub\-font\-size\fP for details). A value of 0 disables shadows.
6416 .sp
6417 Default: 0.
6418 .TP
6419 .B \fB\-\-osd\-spacing=<size>\fP
6420 Horizontal OSD/sub font spacing in scaled pixels (see \fB\-\-sub\-font\-size\fP
6421 for details). This value is added to the normal letter spacing. Negative
6422 values are allowed.
6423 .sp
6424 Default: 0.
6425 .TP
6426 .B \fB\-\-video\-osd=<yes|no>\fP
6427 Enabled OSD rendering on the video window (default: yes). This can be used
6428 in situations where terminal OSD is preferred. If you just want to disable
6429 all OSD rendering, use \fB\-\-osd\-level=0\fP\&.
6430 .sp
6431 It does not affect subtitles or overlays created by scripts (in particular,
6432 the OSC needs to be disabled with \fB\-\-no\-osc\fP).
6433 .sp
6434 This option is somewhat experimental and could be replaced by another
6435 mechanism in the future.
6436 .TP
6437 .B \fB\-\-osd\-font\-provider=<...>\fP
6438 See \fB\-\-sub\-font\-provider\fP for details and accepted values. Note that
6439 unlike subtitles, OSD never uses embedded fonts from media files.
6440 .UNINDENT
6441 .SS Screenshot
6442 .INDENT 0.0
6443 .TP
6444 .B \fB\-\-screenshot\-format=<type>\fP
6445 Set the image file type used for saving screenshots.
6446 .sp
6447 Available choices:
6448 .INDENT 7.0
6449 .TP
6450 .B png
6451 PNG
6452 .TP
6453 .B jpg
6454 JPEG (default)
6455 .TP
6456 .B jpeg
6457 JPEG (alias for jpg)
6458 .TP
6459 .B webp
6460 WebP
6461 .UNINDENT
6462 .TP
6463 .B \fB\-\-screenshot\-tag\-colorspace=<yes|no>\fP
6464 Tag screenshots with the appropriate colorspace.
6465 .sp
6466 Note that not all formats are supported.
6467 .sp
6468 Default: \fBno\fP\&.
6469 .TP
6470 .B \fB\-\-screenshot\-high\-bit\-depth=<yes|no>\fP
6471 If possible, write screenshots with a bit depth similar to the source
6472 video (default: yes). This is interesting in particular for PNG, as this
6473 sometimes triggers writing 16 bit PNGs with huge file sizes. This will also
6474 include an unused alpha channel in the resulting files if 16 bit is used.
6475 .TP
6476 .B \fB\-\-screenshot\-template=<template>\fP
6477 Specify the filename template used to save screenshots. The template
6478 specifies the filename without file extension, and can contain format
6479 specifiers, which will be substituted when taking a screenshot.
6480 By default, the template is \fBmpv\-shot%n\fP, which results in filenames like
6481 \fBmpv\-shot0012.png\fP for example.
6482 .sp
6483 The template can start with a relative or absolute path, in order to
6484 specify a directory location where screenshots should be saved.
6485 .sp
6486 If the final screenshot filename points to an already existing file, the
6487 file will not be overwritten. The screenshot will either not be saved, or if
6488 the template contains \fB%n\fP, saved using different, newly generated
6489 filename.
6490 .sp
6491 Allowed format specifiers:
6492 .INDENT 7.0
6493 .TP
6494 .B \fB%[#][0X]n\fP
6495 A sequence number, padded with zeros to length X (default: 04). E.g.
6496 passing the format \fB%04n\fP will yield \fB0012\fP on the 12th screenshot.
6497 The number is incremented every time a screenshot is taken or if the
6498 file already exists. The length \fBX\fP must be in the range 0\-9. With
6499 the optional # sign, mpv will use the lowest available number. For
6500 example, if you take three screenshots\-\-0001, 0002, 0003\-\-and delete
6501 the first two, the next two screenshots will not be 0004 and 0005, but
6502 0001 and 0002 again.
6503 .TP
6504 .B \fB%f\fP
6505 Filename of the currently played video.
6506 .TP
6507 .B \fB%F\fP
6508 Same as \fB%f\fP, but strip the file extension, including the dot.
6509 .TP
6510 .B \fB%x\fP
6511 Directory path of the currently played video. If the video is not on
6512 the filesystem (but e.g. \fBhttp://\fP), this expand to an empty string.
6513 .TP
6514 .B \fB%X{fallback}\fP
6515 Same as \fB%x\fP, but if the video file is not on the filesystem, return
6516 the fallback string inside the \fB{...}\fP\&.
6517 .TP
6518 .B \fB%p\fP
6519 Current playback time, in the same format as used in the OSD. The
6520 result is a string of the form "HH:MM:SS". For example, if the video is
6521 at the time position 5 minutes and 34 seconds, \fB%p\fP will be replaced
6522 with "00:05:34".
6523 .TP
6524 .B \fB%P\fP
6525 Similar to \fB%p\fP, but extended with the playback time in milliseconds.
6526 It is formatted as "HH:MM:SS.mmm", with "mmm" being the millisecond
6527 part of the playback time.
6528 .sp
6529 \fBNOTE:\fP
6530 .INDENT 7.0
6531 .INDENT 3.5
6532 This is a simple way for getting unique per\-frame timestamps. (Frame
6533 numbers would be more intuitive, but are not easily implementable
6534 because container formats usually use time stamps for identifying
6535 frames.)
6536 .UNINDENT
6537 .UNINDENT
6538 .TP
6539 .B \fB%wX\fP
6540 Specify the current playback time using the format string \fBX\fP\&.
6541 \fB%p\fP is like \fB%wH:%wM:%wS\fP, and \fB%P\fP is like \fB%wH:%wM:%wS.%wT\fP\&.
6542 .INDENT 7.0
6543 .TP
6544 .B Valid format specifiers:
6545 .INDENT 7.0
6546 .TP
6547 .B \fB%wH\fP
6548 hour (padded with 0 to two digits)
6549 .TP
6550 .B \fB%wh\fP
6551 hour (not padded)
6552 .TP
6553 .B \fB%wM\fP
6554 minutes (00\-59)
6555 .TP
6556 .B \fB%wm\fP
6557 total minutes (includes hours, unlike \fB%wM\fP)
6558 .TP
6559 .B \fB%wS\fP
6560 seconds (00\-59)
6561 .TP
6562 .B \fB%ws\fP
6563 total seconds (includes hours and minutes)
6564 .TP
6565 .B \fB%wf\fP
6566 like \fB%ws\fP, but as float
6567 .TP
6568 .B \fB%wT\fP
6569 milliseconds (000\-999)
6570 .UNINDENT
6571 .UNINDENT
6572 .TP
6573 .B \fB%tX\fP
6574 Specify the current local date/time using the format \fBX\fP\&. This format
6575 specifier uses the UNIX \fBstrftime()\fP function internally, and inserts
6576 the result of passing "%X" to \fBstrftime\fP\&. For example, \fB%tm\fP will
6577 insert the number of the current month as number. You have to use
6578 multiple \fB%tX\fP specifiers to build a full date/time string.
6579 .TP
6580 .B \fB%{prop[:fallback text]}\fP
6581 Insert the value of the input property \(aqprop\(aq. E.g. \fB%{filename}\fP is
6582 the same as \fB%f\fP\&. If the property does not exist or is not available,
6583 an error text is inserted, unless a fallback is specified.
6584 .TP
6585 .B \fB%%\fP
6586 Replaced with the \fB%\fP character itself.
6587 .UNINDENT
6588 .TP
6589 .B \fB\-\-screenshot\-directory=<path>\fP
6590 Store screenshots in this directory. This path is joined with the filename
6591 generated by \fB\-\-screenshot\-template\fP\&. If the template filename is already
6592 absolute, the directory is ignored.
6593 .sp
6594 If the directory does not exist, it is created on the first screenshot. If
6595 it is not a directory, an error is generated when trying to write a
6596 screenshot.
6597 .sp
6598 This option is not set by default, and thus will write screenshots to the
6599 directory from which mpv was started. In pseudo\-gui mode
6600 (see \fI\%PSEUDO GUI MODE\fP), this is set to the desktop.
6601 .TP
6602 .B \fB\-\-screenshot\-jpeg\-quality=<0\-100>\fP
6603 Set the JPEG quality level. Higher means better quality. The default is 90.
6604 .TP
6605 .B \fB\-\-screenshot\-jpeg\-source\-chroma=<yes|no>\fP
6606 Write JPEG files with the same chroma subsampling as the video
6607 (default: yes). If disabled, the libjpeg default is used.
6608 .TP
6609 .B \fB\-\-screenshot\-png\-compression=<0\-9>\fP
6610 Set the PNG compression level. Higher means better compression. This will
6611 affect the file size of the written screenshot file and the time it takes
6612 to write a screenshot. Too high compression might occupy enough CPU time to
6613 interrupt playback. The default is 7.
6614 .TP
6615 .B \fB\-\-screenshot\-png\-filter=<0\-5>\fP
6616 Set the filter applied prior to PNG compression. 0 is none, 1 is "sub", 2 is
6617 "up", 3 is "average", 4 is "Paeth", and 5 is "mixed". This affects the level
6618 of compression that can be achieved. For most images, "mixed" achieves the
6619 best compression ratio, hence it is the default.
6620 .TP
6621 .B \fB\-\-screenshot\-webp\-lossless=<yes|no>\fP
6622 Write lossless WebP files. \fB\-\-screenshot\-webp\-quality\fP is ignored if this
6623 is set. The default is no.
6624 .TP
6625 .B \fB\-\-screenshot\-webp\-quality=<0\-100>\fP
6626 Set the WebP quality level. Higher means better quality. The default is 75.
6627 .TP
6628 .B \fB\-\-screenshot\-webp\-compression=<0\-6>\fP
6629 Set the WebP compression level. Higher means better compression, but takes
6630 more CPU time. Note that this also affects the screenshot quality when used
6631 with lossy WebP files. The default is 4.
6632 .TP
6633 .B \fB\-\-screenshot\-sw=<yes|no>\fP
6634 Whether to use software rendering for screenshots (default: no).
6635 .sp
6636 If set to no, the screenshot will be rendered by the current VO if possible
6637 (only vo_gpu currently). The advantage is that this will (probably) always
6638 show up as in the video window, because the same code is used for rendering.
6639 But since the renderer needs to be reinitialized, this can be slow and
6640 interrupt playback. (Unless the \fBwindow\fP mode is used with the
6641 \fBscreenshot\fP command.)
6642 .sp
6643 If set to yes, the software scaler is used to convert the video to RGB (or
6644 whatever the target screenshot requires). In this case, conversion will
6645 run in a separate thread and will probably not interrupt playback. The
6646 software renderer may lack some capabilities, such as HDR rendering.
6647 .UNINDENT
6648 .SS Software Scaler
6649 .INDENT 0.0
6650 .TP
6651 .B \fB\-\-sws\-scaler=<name>\fP
6652 Specify the software scaler algorithm to be used with \fB\-\-vf=scale\fP\&. This
6653 also affects video output drivers which lack hardware acceleration,
6654 e.g. \fBx11\fP\&. See also \fB\-\-vf=scale\fP\&.
6655 .sp
6656 To get a list of available scalers, run \fB\-\-sws\-scaler=help\fP\&.
6657 .sp
6658 Default: \fBbicubic\fP\&.
6659 .TP
6660 .B \fB\-\-sws\-lgb=<0\-100>\fP
6661 Software scaler Gaussian blur filter (luma). See \fB\-\-sws\-scaler\fP\&.
6662 .TP
6663 .B \fB\-\-sws\-cgb=<0\-100>\fP
6664 Software scaler Gaussian blur filter (chroma). See \fB\-\-sws\-scaler\fP\&.
6665 .TP
6666 .B \fB\-\-sws\-ls=<\-100\-100>\fP
6667 Software scaler sharpen filter (luma). See \fB\-\-sws\-scaler\fP\&.
6668 .TP
6669 .B \fB\-\-sws\-cs=<\-100\-100>\fP
6670 Software scaler sharpen filter (chroma). See \fB\-\-sws\-scaler\fP\&.
6671 .TP
6672 .B \fB\-\-sws\-chs=<h>\fP
6673 Software scaler chroma horizontal shifting. See \fB\-\-sws\-scaler\fP\&.
6674 .TP
6675 .B \fB\-\-sws\-cvs=<v>\fP
6676 Software scaler chroma vertical shifting. See \fB\-\-sws\-scaler\fP\&.
6677 .TP
6678 .B \fB\-\-sws\-bitexact=<yes|no>\fP
6679 Unknown functionality (default: no). Consult libswscale source code. The
6680 primary purpose of this, as far as libswscale API goes), is to produce
6681 exactly the same output for the same input on all platforms (output has the
6682 same "bits" everywhere, thus "bitexact"). Typically disables optimizations.
6683 .TP
6684 .B \fB\-\-sws\-fast=<yes|no>\fP
6685 Allow optimizations that help with performance, but reduce quality (default:
6686 no).
6687 .sp
6688 VOs like \fBdrm\fP and \fBx11\fP will benefit a lot from using \fB\-\-sws\-fast\fP\&.
6689 You may need to set other options, like \fB\-\-sws\-scaler\fP\&. The builtin
6690 \fBsws\-fast\fP profile sets this option and some others to gain performance
6691 for reduced quality. Also see \fB\-\-sws\-allow\-zimg\fP\&.
6692 .TP
6693 .B \fB\-\-sws\-allow\-zimg=<yes|no>\fP
6694 Allow using zimg (if the component using the internal swscale wrapper
6695 explicitly allows so) (default: yes). In this case, zimg \fImay\fP be used, if
6696 the internal zimg wrapper supports the input and output formats. It will
6697 silently or noisily fall back to libswscale if one of these conditions does
6698 not apply.
6699 .sp
6700 If zimg is used, the other \fB\-\-sws\-\fP options are ignored, and the
6701 \fB\-\-zimg\-\fP options are used instead.
6702 .sp
6703 If the internal component using the swscale wrapper hooks up logging
6704 correctly, a verbose priority log message will indicate whether zimg is
6705 being used.
6706 .sp
6707 Most things which need software conversion can make use of this.
6708 .sp
6709 \fBNOTE:\fP
6710 .INDENT 7.0
6711 .INDENT 3.5
6712 Do note that zimg \fImay\fP be slower than libswscale. Usually,
6713 it\(aqs faster on x86 platforms, but slower on ARM (due to lack of ARM
6714 specific optimizations). The mpv zimg wrapper uses unoptimized repacking
6715 for some formats, for which zimg cannot be blamed.
6716 .UNINDENT
6717 .UNINDENT
6718 .TP
6719 .B \fB\-\-zimg\-scaler=<point|bilinear|bicubic|spline16|spline36|lanczos>\fP
6720 Zimg luma scaler to use (default: lanczos).
6721 .TP
6722 .B \fB\-\-zimg\-scaler\-param\-a=<default|float>\fP, \fB\-\-zimg\-scaler\-param\-b=<default|float>\fP
6723 Set scaler parameters. By default, these are set to the special string
6724 \fBdefault\fP, which maps to a scaler\-specific default value. Ignored if the
6725 scaler is not tunable.
6726 .INDENT 7.0
6727 .TP
6728 .B \fBlanczos\fP
6729 \fB\-\-zimg\-scaler\-param\-a\fP is the number of taps.
6730 .TP
6731 .B \fBbicubic\fP
6732 a and b are the bicubic b and c parameters.
6733 .UNINDENT
6734 .TP
6735 .B \fB\-\-zimg\-scaler\-chroma=...\fP
6736 Same as \fB\-\-zimg\-scaler\fP, for for chroma interpolation (default: bilinear).
6737 .TP
6738 .B \fB\-\-zimg\-scaler\-chroma\-param\-a\fP, \fB\-\-zimg\-scaler\-chroma\-param\-b\fP
6739 Same as \fB\-\-zimg\-scaler\-param\-a\fP / \fB\-\-zimg\-scaler\-param\-b\fP, for chroma.
6740 .TP
6741 .B \fB\-\-zimg\-dither=<no|ordered|random|error\-diffusion>\fP
6742 Dithering (default: random).
6743 .TP
6744 .B \fB\-\-zimg\-threads=<auto|integer>\fP
6745 Set the maximum number of threads to use for scaling (default: auto).
6746 \fBauto\fP uses the number of logical cores on the current machine. Note that
6747 the scaler may use less threads (or even just 1 thread) depending on stuff.
6748 Passing a value of 1 disables threading and always scales the image in a
6749 single operation. Higher thread counts waste resources, but make it
6750 typically faster.
6751 .sp
6752 Note that some zimg git versions had bugs that will corrupt the output if
6753 threads are used.
6754 .TP
6755 .B \fB\-\-zimg\-fast=<yes|no>\fP
6756 Allow optimizations that help with performance, but reduce quality (default:
6757 yes). Currently, this may simplify gamma conversion operations.
6758 .UNINDENT
6759 .SS Audio Resampler
6760 .sp
6761 This controls the default options of any resampling done by mpv (but not within
6762 libavfilter, within the system audio API resampler, or any other places).
6763 .sp
6764 It also sets the defaults for the \fBlavrresample\fP audio filter.
6765 .INDENT 0.0
6766 .TP
6767 .B \fB\-\-audio\-resample\-filter\-size=<length>\fP
6768 Length of the filter with respect to the lower sampling rate. (default:
6769 16)
6770 .TP
6771 .B \fB\-\-audio\-resample\-phase\-shift=<count>\fP
6772 Log2 of the number of polyphase entries. (..., 10\->1024, 11\->2048,
6773 12\->4096, ...) (default: 10\->1024)
6774 .TP
6775 .B \fB\-\-audio\-resample\-cutoff=<cutoff>\fP
6776 Cutoff frequency (0.0\-1.0), default set depending upon filter length.
6777 .TP
6778 .B \fB\-\-audio\-resample\-linear=<yes|no>\fP
6779 If set then filters will be linearly interpolated between polyphase
6780 entries. (default: no)
6781 .TP
6782 .B \fB\-\-audio\-normalize\-downmix=<yes|no>\fP
6783 Enable/disable normalization if surround audio is downmixed to stereo
6784 (default: no). If this is disabled, downmix can cause clipping. If it\(aqs
6785 enabled, the output might be too quiet. It depends on the source audio.
6786 .sp
6787 Technically, this changes the \fBnormalize\fP suboption of the
6788 \fBlavrresample\fP audio filter, which performs the downmixing.
6789 .sp
6790 If downmix happens outside of mpv for some reason, or in the decoder
6791 (decoder downmixing), or in the audio output (system mixer), this has no
6792 effect.
6793 .TP
6794 .B \fB\-\-audio\-resample\-max\-output\-size=<length>\fP
6795 Limit maximum size of audio frames filtered at once, in ms (default: 40).
6796 The output size size is limited in order to make resample speed changes
6797 react faster. This is necessary especially if decoders or filters output
6798 very large frame sizes (like some lossless codecs or some DRC filters).
6799 This option does not affect the resampling algorithm in any way.
6800 .sp
6801 For testing/debugging only. Can be removed or changed any time.
6802 .TP
6803 .B \fB\-\-audio\-swresample\-o=<string>\fP
6804 Set AVOptions on the SwrContext or AVAudioResampleContext. These should
6805 be documented by FFmpeg or Libav.
6806 .sp
6807 This is a key/value list option. See \fI\%List Options\fP for details.
6808 .UNINDENT
6809 .SS Terminal
6810 .INDENT 0.0
6811 .TP
6812 .B \fB\-\-quiet\fP
6813 Make console output less verbose; in particular, prevents the status line
6814 (i.e. AV: 3.4 (00:00:03.37) / 5320.6 ...) from being displayed.
6815 Particularly useful on slow terminals or broken ones which do not properly
6816 handle carriage return (i.e. \fB\er\fP).
6817 .sp
6818 See also: \fB\-\-really\-quiet\fP and \fB\-\-msg\-level\fP\&.
6819 .TP
6820 .B \fB\-\-really\-quiet\fP
6821 Display even less output and status messages than with \fB\-\-quiet\fP\&.
6822 .TP
6823 .B \fB\-\-no\-terminal\fP, \fB\-\-terminal\fP
6824 Disable any use of the terminal and stdin/stdout/stderr. This completely
6825 silences any message output.
6826 .sp
6827 Unlike \fB\-\-really\-quiet\fP, this disables input and terminal initialization
6828 as well.
6829 .TP
6830 .B \fB\-\-no\-msg\-color\fP
6831 Disable colorful console output on terminals.
6832 .TP
6833 .B \fB\-\-msg\-level=<module1=level1,module2=level2,...>\fP
6834 Control verbosity directly for each module. The \fBall\fP module changes the
6835 verbosity of all the modules. The verbosity changes from this option are
6836 applied in order from left to right, and each item can override a previous
6837 one.
6838 .sp
6839 Run mpv with \fB\-\-msg\-level=all=trace\fP to see all messages mpv outputs. You
6840 can use the module names printed in the output (prefixed to each line in
6841 \fB[...]\fP) to limit the output to interesting modules.
6842 .sp
6843 This also affects \fB\-\-log\-file\fP, and in certain cases libmpv API logging.
6844 .sp
6845 \fBNOTE:\fP
6846 .INDENT 7.0
6847 .INDENT 3.5
6848 Some messages are printed before the command line is parsed and are
6849 therefore not affected by \fB\-\-msg\-level\fP\&. To control these messages,
6850 you have to use the \fBMPV_VERBOSE\fP environment variable; see
6851 \fI\%ENVIRONMENT VARIABLES\fP for details.
6852 .UNINDENT
6853 .UNINDENT
6854 .sp
6855 Available levels:
6856 .INDENT 7.0
6857 .INDENT 3.5
6858 .INDENT 0.0
6859 .TP
6860 .B no
6861 complete silence
6862 .TP
6863 .B fatal
6864 fatal messages only
6865 .TP
6866 .B error
6867 error messages
6868 .TP
6869 .B warn
6870 warning messages
6871 .TP
6872 .B info
6873 informational messages
6874 .TP
6875 .B status
6876 status messages (default)
6877 .TP
6878 .B v
6879 verbose messages
6880 .TP
6881 .B debug
6882 debug messages
6883 .TP
6884 .B trace
6885 very noisy debug messages
6886 .UNINDENT
6887 .UNINDENT
6888 .UNINDENT
6889 .INDENT 7.0
6890 .INDENT 3.5
6891 .IP "Example"
6892 .INDENT 0.0
6893 .INDENT 3.5
6894 .sp
6895 .nf
6896 .ft C
6897 mpv \-\-msg\-level=ao/sndio=no
6898 .ft P
6899 .fi
6900 .UNINDENT
6901 .UNINDENT
6902 .sp
6903 Completely silences the output of ao_sndio, which uses the log
6904 prefix \fB[ao/sndio]\fP\&.
6905 .INDENT 0.0
6906 .INDENT 3.5
6907 .sp
6908 .nf
6909 .ft C
6910 mpv \-\-msg\-level=all=warn,ao/alsa=error
6911 .ft P
6912 .fi
6913 .UNINDENT
6914 .UNINDENT
6915 .sp
6916 Only show warnings or worse, and let the ao_alsa output show errors
6917 only.
6918 .UNINDENT
6919 .UNINDENT
6920 .TP
6921 .B \fB\-\-term\-osd=<auto|no|force>\fP
6922 Control whether OSD messages are shown on the console when no video output
6923 is available (default: auto).
6924 .INDENT 7.0
6925 .TP
6926 .B auto
6927 use terminal OSD if no video output active
6928 .TP
6929 .B no
6930 disable terminal OSD
6931 .TP
6932 .B force
6933 use terminal OSD even if video output active
6934 .UNINDENT
6935 .sp
6936 The \fBauto\fP mode also enables terminal OSD if \fB\-\-video\-osd=no\fP was set.
6937 .TP
6938 .B \fB\-\-term\-osd\-bar\fP, \fB\-\-no\-term\-osd\-bar\fP
6939 Enable printing a progress bar under the status line on the terminal.
6940 (Disabled by default.)
6941 .TP
6942 .B \fB\-\-term\-osd\-bar\-chars=<string>\fP
6943 Customize the \fB\-\-term\-osd\-bar\fP feature. The string is expected to
6944 consist of 5 characters (start, left space, position indicator,
6945 right space, end). You can use Unicode characters, but note that double\-
6946 width characters will not be treated correctly.
6947 .sp
6948 Default: \fB[\-+\-]\fP\&.
6949 .TP
6950 .B \fB\-\-term\-playing\-msg=<string>\fP
6951 Print out a string after starting playback. The string is expanded for
6952 properties, e.g. \fB\-\-term\-playing\-msg=\(aqfile: ${filename}\(aq\fP will print the string
6953 \fBfile:\fP followed by a space and the currently played filename.
6954 .sp
6955 See \fI\%Property Expansion\fP\&.
6956 .TP
6957 .B \fB\-\-term\-status\-msg=<string>\fP
6958 Print out a custom string during playback instead of the standard status
6959 line. Expands properties. See \fI\%Property Expansion\fP\&.
6960 .TP
6961 .B \fB\-\-term\-title=<string>\fP
6962 Set the terminal title. Currently, this simply concatenates the escape
6963 sequence setting the window title with the provided (property expanded)
6964 string. This will mess up if the expanded string contain bytes that end the
6965 escape sequence, or if the terminal does not understand the sequence. The
6966 latter probably includes the regrettable win32.
6967 .sp
6968 Expands properties. See \fI\%Property Expansion\fP\&.
6969 .TP
6970 .B \fB\-\-msg\-module\fP
6971 Prepend module name to each console message.
6972 .TP
6973 .B \fB\-\-msg\-time\fP
6974 Prepend timing information to each console message. The time is in
6975 seconds since the player process was started (technically, slightly
6976 later actually), using a monotonic time source depending on the OS. This
6977 is \fBCLOCK_MONOTONIC\fP on sane UNIX variants.
6978 .UNINDENT
6979 .SS Cache
6980 .INDENT 0.0
6981 .TP
6982 .B \fB\-\-cache=<yes|no|auto>\fP
6983 Decide whether to use network cache settings (default: auto).
6984 .sp
6985 If enabled, use up to \fB\-\-cache\-secs\fP for the cache size (but still limited
6986 to \fB\-\-demuxer\-max\-bytes\fP), and make the cached data seekable (if possible).
6987 If disabled, \fB\-\-cache\-pause\fP and related are implicitly disabled.
6988 .sp
6989 The \fBauto\fP choice enables this depending on whether the stream is thought
6990 to involve network accesses or other slow media (this is an imperfect
6991 heuristic).
6992 .sp
6993 Before mpv 0.30.0, this used to accept a number, which specified the size
6994 of the cache in kilobytes. Use e.g. \fB\-\-cache \-\-demuxer\-max\-bytes=123k\fP
6995 instead.
6996 .TP
6997 .B \fB\-\-no\-cache\fP
6998 Turn off input stream caching. See \fB\-\-cache\fP\&.
6999 .TP
7000 .B \fB\-\-cache\-secs=<seconds>\fP
7001 Deprecated. Once this option is removed, there will be no way to limit the
7002 cache size by time (only by size with \fB\-\-demuxer\-max\-bytes\fP). This option
7003 is considered useless, since there is no good reason to limit the cache by
7004 time, and the default value of this option is already something very high.
7005 The interaction with the other cache options is also confusing.
7006 .sp
7007 How many seconds of audio/video to prefetch if the cache is active. This
7008 overrides the \fB\-\-demuxer\-readahead\-secs\fP option if and only if the cache
7009 is enabled and the value is larger. The default value is set to something
7010 very high, so the actually achieved readahead will usually be limited by
7011 the value of the \fB\-\-demuxer\-max\-bytes\fP option. Setting this option is
7012 usually only useful for limiting readahead.
7013 .TP
7014 .B \fB\-\-cache\-on\-disk=<yes|no>\fP
7015 Write packet data to a temporary file, instead of keeping them in memory.
7016 This makes sense only with \fB\-\-cache\fP\&. If the normal cache is disabled,
7017 this option is ignored.
7018 .sp
7019 You need to set \fB\-\-cache\-dir\fP to use this.
7020 .sp
7021 The cache file is append\-only. Even if the player appears to prune data, the
7022 file space freed by it is not reused. The cache file is deleted when
7023 playback is closed.
7024 .sp
7025 Note that packet metadata is still kept in memory. \fB\-\-demuxer\-max\-bytes\fP
7026 and related options are applied to metadata \fIonly\fP\&. The size of this
7027 metadata varies, but 50 MB per hour of media is typical. The cache
7028 statistics will report this metadats size, instead of the size of the cache
7029 file. If the metadata hits the size limits, the metadata is pruned (but not
7030 the cache file).
7031 .sp
7032 When the media is closed, the cache file is deleted. A cache file is
7033 generally worthless after the media is closed, and it\(aqs hard to retrieve
7034 any media data from it (it\(aqs not supported by design).
7035 .sp
7036 If the option is enabled at runtime, the cache file is created, but old data
7037 will remain in the memory cache. If the option is disabled at runtime, old
7038 data remains in the disk cache, and the cache file is not closed until the
7039 media is closed. If the option is disabled and enabled again, it will
7040 continue to use the cache file that was opened first.
7041 .TP
7042 .B \fB\-\-cache\-dir=<path>\fP
7043 Directory where to create temporary files (default: none).
7044 .sp
7045 Currently, this is used for \fB\-\-cache\-on\-disk\fP only.
7046 .TP
7047 .B \fB\-\-cache\-pause=<yes|no>\fP
7048 Whether the player should automatically pause when the cache runs out of
7049 data and stalls decoding/playback (default: yes). If enabled, it will
7050 pause and unpause once more data is available, aka "buffering".
7051 .TP
7052 .B \fB\-\-cache\-pause\-wait=<seconds>\fP
7053 Number of seconds the packet cache should have buffered before starting
7054 playback again if "buffering" was entered (default: 1). This can be used
7055 to control how long the player rebuffers if \fB\-\-cache\-pause\fP is enabled,
7056 and the demuxer underruns. If the given time is higher than the maximum
7057 set with \fB\-\-cache\-secs\fP or \fB\-\-demuxer\-readahead\-secs\fP, or prefetching
7058 ends before that for some other reason (like file end or maximum configured
7059 cache size reached), playback resumes earlier.
7060 .TP
7061 .B \fB\-\-cache\-pause\-initial=<yes|no>\fP
7062 Enter "buffering" mode before starting playback (default: no). This can be
7063 used to ensure playback starts smoothly, in exchange for waiting some time
7064 to prefetch network data (as controlled by \fB\-\-cache\-pause\-wait\fP). For
7065 example, some common behavior is that playback starts, but network caches
7066 immediately underrun when trying to decode more data as playback progresses.
7067 .sp
7068 Another thing that can happen is that the network prefetching is so CPU
7069 demanding (due to demuxing in the background) that playback drops frames
7070 at first. In these cases, it helps enabling this option, and setting
7071 \fB\-\-cache\-secs\fP and \fB\-\-cache\-pause\-wait\fP to roughly the same value.
7072 .sp
7073 This option also triggers when playback is restarted after seeking.
7074 .TP
7075 .B \fB\-\-cache\-unlink\-files=<immediate|whendone|no>\fP
7076 Whether or when to unlink cache files (default: immediate). This affects
7077 cache files which are inherently temporary, and which make no sense to
7078 remain on disk after the player terminates. This is a debugging option.
7079 .INDENT 7.0
7080 .TP
7081 .B \fBimmediate\fP
7082 Unlink cache file after they were created. The cache files won\(aqt be
7083 visible anymore, even though they\(aqre in use. This ensures they are
7084 guaranteed to be removed from disk when the player terminates, even if
7085 it crashes.
7086 .TP
7087 .B \fBwhendone\fP
7088 Delete cache files after they are closed.
7089 .TP
7090 .B \fBno\fP
7091 Don\(aqt delete cache files. They will consume disk space without having a
7092 use.
7093 .UNINDENT
7094 .sp
7095 Currently, this is used for \fB\-\-cache\-on\-disk\fP only.
7096 .TP
7097 .B \fB\-\-stream\-buffer\-size=<bytesize>\fP
7098 Size of the low level stream byte buffer (default: 128KB). This is used as
7099 buffer between demuxer and low level I/O (e.g. sockets). Generally, this
7100 can be very small, and the main purpose is similar to the internal buffer
7101 FILE in the C standard library will have.
7102 .sp
7103 Half of the buffer is always used for guaranteed seek back, which is
7104 important for unseekable input.
7105 .sp
7106 There are known cases where this can help performance to set a large buffer:
7107 .INDENT 7.0
7108 .INDENT 3.5
7109 .INDENT 0.0
7110 .IP 1. 3
7111 mp4 files. libavformat may trigger many small seeks in both
7112 directions, depending on how the file was muxed.
7113 .IP 2. 3
7114 Certain network filesystems, which do not have a cache, and where
7115 small reads can be inefficient.
7116 .UNINDENT
7117 .UNINDENT
7118 .UNINDENT
7119 .sp
7120 In other cases, setting this to a large value can reduce performance.
7121 .sp
7122 Usually, read accesses are at half the buffer size, but it may happen that
7123 accesses are done alternating with smaller and larger sizes (this is due to
7124 the internal ring buffer wrap\-around).
7125 .sp
7126 See \fB\-\-list\-options\fP for defaults and value range. \fB<bytesize>\fP options
7127 accept suffixes such as \fBKiB\fP and \fBMiB\fP\&.
7128 .TP
7129 .B \fB\-\-vd\-queue\-enable=<yes|no>, \-\-ad\-queue\-enable\fP
7130 Enable running the video/audio decoder on a separate thread (default: no).
7131 If enabled, the decoder is run on a separate thread, and a frame queue is
7132 put between decoder and higher level playback logic. The size of the frame
7133 queue is defined by the other options below.
7134 .sp
7135 This is probably quite pointless. libavcodec already has multithreaded
7136 decoding (enabled by default), which makes this largely unnecessary. It
7137 might help in some corner cases with high bandwidth video that is slow to
7138 decode (in these cases libavcodec would block the playback logic, while
7139 using a decoding thread would distribute the decoding time evenly without
7140 affecting the playback logic). In other situations, it will simply make
7141 seeking slower and use significantly more memory.
7142 .sp
7143 The queue size is restricted by the other \fB\-\-vd\-queue\-...\fP options. The
7144 final queue size is the minimum as indicated by the option with the lowest
7145 limit. Each decoder/track has its own queue that may use the full configured
7146 queue size.
7147 .sp
7148 Most queue options can be changed at runtime. \fB\-\-vd\-queue\-enable\fP itself
7149 (and the audio equivalent) update only if decoding is completely
7150 reinitialized. However, setting \fB\-\-vd\-queue\-max\-samples=1\fP should almost
7151 lead to the same behavior as \fB\-\-vd\-queue\-enable=no\fP, so that value can
7152 be used for effectively runtime enabling/disabling the queue.
7153 .sp
7154 This should not be used with hardware decoding. It is possible to enable
7155 this for audio, but it makes even less sense.
7156 .TP
7157 .B \fB\-\-vd\-queue\-max\-bytes=<bytesize>\fP, \fB\-\-ad\-queue\-max\-bytes\fP
7158 Maximum approximate allowed size of the queue. If exceeded, decoding will
7159 be stopped. The maximum size can be exceeded by about 1 frame.
7160 .sp
7161 See \fB\-\-list\-options\fP for defaults and value range. \fB<bytesize>\fP options
7162 accept suffixes such as \fBKiB\fP and \fBMiB\fP\&.
7163 .TP
7164 .B \fB\-\-vd\-queue\-max\-samples=<int>\fP, \fB\-\-ad\-queue\-max\-samples\fP
7165 Maximum number of frames (video) or samples (audio) of the queue. The audio
7166 size may be exceeded by about 1 frame.
7167 .sp
7168 See \fB\-\-list\-options\fP for defaults and value range.
7169 .TP
7170 .B \fB\-\-vd\-queue\-max\-secs=<seconds>\fP, \fB\-\-ad\-queue\-max\-secs\fP
7171 Maximum number of seconds of media in the queue. The special value 0 means
7172 no limit is set. The queue size may be exceeded by about 2 frames. Timestamp
7173 resets may lead to random queue size usage.
7174 .sp
7175 See \fB\-\-list\-options\fP for defaults and value range.
7176 .UNINDENT
7177 .SS Network
7178 .INDENT 0.0
7179 .TP
7180 .B \fB\-\-user\-agent=<string>\fP
7181 Use \fB<string>\fP as user agent for HTTP streaming.
7182 .TP
7183 .B \fB\-\-cookies\fP, \fB\-\-no\-cookies\fP
7184 Support cookies when making HTTP requests. Disabled by default.
7185 .TP
7186 .B \fB\-\-cookies\-file=<filename>\fP
7187 Read HTTP cookies from <filename>. The file is assumed to be in Netscape
7188 format.
7189 .TP
7190 .B \fB\-\-http\-header\-fields=<field1,field2>\fP
7191 Set custom HTTP fields when accessing HTTP stream.
7192 .sp
7193 This is a string list option. See \fI\%List Options\fP for details.
7194 .INDENT 7.0
7195 .INDENT 3.5
7196 .IP "Example"
7197 .INDENT 0.0
7198 .INDENT 3.5
7199 .sp
7200 .nf
7201 .ft C
7202 mpv \-\-http\-header\-fields=\(aqField1: value1\(aq,\(aqField2: value2\(aq \e
7203 http://localhost:1234
7204 .ft P
7205 .fi
7206 .UNINDENT
7207 .UNINDENT
7208 .sp
7209 Will generate HTTP request:
7210 .INDENT 0.0
7211 .INDENT 3.5
7212 .sp
7213 .nf
7214 .ft C
7215 GET / HTTP/1.0
7216 Host: localhost:1234
7217 User\-Agent: MPlayer
7218 Icy\-MetaData: 1
7219 Field1: value1
7220 Field2: value2
7221 Connection: close
7222 .ft P
7223 .fi
7224 .UNINDENT
7225 .UNINDENT
7226 .UNINDENT
7227 .UNINDENT
7228 .TP
7229 .B \fB\-\-http\-proxy=<proxy>\fP
7230 URL of the HTTP/HTTPS proxy. If this is set, the \fBhttp_proxy\fP environment
7231 is ignored. The \fBno_proxy\fP environment variable is still respected. This
7232 option is silently ignored if it does not start with \fBhttp://\fP\&. Proxies
7233 are not used for https URLs. Setting this option does not try to make the
7234 ytdl script use the proxy.
7235 .TP
7236 .B \fB\-\-tls\-ca\-file=<filename>\fP
7237 Certificate authority database file for use with TLS. (Silently fails with
7238 older FFmpeg or Libav versions.)
7239 .TP
7240 .B \fB\-\-tls\-verify\fP
7241 Verify peer certificates when using TLS (e.g. with \fBhttps://...\fP).
7242 (Silently fails with older FFmpeg or Libav versions.)
7243 .TP
7244 .B \fB\-\-tls\-cert\-file\fP
7245 A file containing a certificate to use in the handshake with the
7246 peer.
7247 .TP
7248 .B \fB\-\-tls\-key\-file\fP
7249 A file containing the private key for the certificate.
7250 .TP
7251 .B \fB\-\-referrer=<string>\fP
7252 Specify a referrer path or URL for HTTP requests.
7253 .TP
7254 .B \fB\-\-network\-timeout=<seconds>\fP
7255 Specify the network timeout in seconds (default: 60 seconds). This affects
7256 at least HTTP. The special value 0 uses the FFmpeg/Libav defaults. If a
7257 protocol is used which does not support timeouts, this option is silently
7258 ignored.
7259 .sp
7260 \fBWARNING:\fP
7261 .INDENT 7.0
7262 .INDENT 3.5
7263 This breaks the RTSP protocol, because of inconsistent FFmpeg API
7264 regarding its internal timeout option. Not only does the RTSP timeout
7265 option accept different units (seconds instead of microseconds, causing
7266 mpv to pass it huge values), it will also overflow FFmpeg internal
7267 calculations. The worst is that merely setting the option will put RTSP
7268 into listening mode, which breaks any client uses. At time of this
7269 writing, the fix was not made effective yet. For this reason, this
7270 option is ignored (or should be ignored) on RTSP URLs. You can still
7271 set the timeout option directly with \fB\-\-demuxer\-lavf\-o\fP\&.
7272 .UNINDENT
7273 .UNINDENT
7274 .TP
7275 .B \fB\-\-rtsp\-transport=<lavf|udp|udp_multicast|tcp|http>\fP
7276 Select RTSP transport method (default: tcp). This selects the underlying
7277 network transport when playing \fBrtsp://...\fP URLs. The value \fBlavf\fP
7278 leaves the decision to libavformat.
7279 .TP
7280 .B \fB\-\-hls\-bitrate=<no|min|max|<rate>>\fP
7281 If HLS streams are played, this option controls what streams are selected
7282 by default. The option allows the following parameters:
7283 .INDENT 7.0
7284 .TP
7285 .B no
7286 Don\(aqt do anything special. Typically, this will simply pick the
7287 first audio/video streams it can find.
7288 .TP
7289 .B min
7290 Pick the streams with the lowest bitrate.
7291 .TP
7292 .B max
7293 Same, but highest bitrate. (Default.)
7294 .UNINDENT
7295 .sp
7296 Additionally, if the option is a number, the stream with the highest rate
7297 equal or below the option value is selected.
7298 .sp
7299 The bitrate as used is sent by the server, and there\(aqs no guarantee it\(aqs
7300 actually meaningful.
7301 .UNINDENT
7302 .SS DVB
7303 .INDENT 0.0
7304 .TP
7305 .B \fB\-\-dvbin\-prog=<string>\fP
7306 This defines the program to tune to. Usually, you may specify this
7307 by using a stream URI like \fB"dvb://ZDF HD"\fP, but you can tune to a
7308 different channel by writing to this property at runtime.
7309 Also see \fBdvbin\-channel\-switch\-offset\fP for more useful channel
7310 switching functionality.
7311 .TP
7312 .B \fB\-\-dvbin\-card=<0\-15>\fP
7313 Specifies using card number 0\-15 (default: 0).
7314 .TP
7315 .B \fB\-\-dvbin\-file=<filename>\fP
7316 Instructs mpv to read the channels list from \fB<filename>\fP\&. The default is
7317 in the mpv configuration directory (usually \fB~/.config/mpv\fP) with the
7318 filename \fBchannels.conf.{sat,ter,cbl,atsc}\fP (based on your card type) or
7319 \fBchannels.conf\fP as a last resort.
7320 For DVB\-S/2 cards, a VDR 1.7.x format channel list is recommended
7321 as it allows tuning to DVB\-S2 channels, enabling subtitles and
7322 decoding the PMT (which largely improves the demuxing).
7323 Classic mplayer format channel lists are still supported (without
7324 these improvements), and for other card types, only limited VDR
7325 format channel list support is implemented (patches welcome).
7326 For channels with dynamic PID switching or incomplete
7327 \fBchannels.conf\fP, \fB\-\-dvbin\-full\-transponder\fP or the magic PID
7328 \fB8192\fP are recommended.
7329 .TP
7330 .B \fB\-\-dvbin\-timeout=<1\-30>\fP
7331 Maximum number of seconds to wait when trying to tune a frequency before
7332 giving up (default: 30).
7333 .TP
7334 .B \fB\-\-dvbin\-full\-transponder=<yes|no>\fP
7335 Apply no filters on program PIDs, only tune to frequency and pass full
7336 transponder to demuxer.
7337 The player frontend selects the streams from the full TS in this case,
7338 so the program which is shown initially may not match the chosen channel.
7339 Switching between the programs is possible by cycling the \fBprogram\fP
7340 property.
7341 This is useful to record multiple programs on a single transponder,
7342 or to work around issues in the \fBchannels.conf\fP\&.
7343 It is also recommended to use this for channels which switch PIDs
7344 on\-the\-fly, e.g. for regional news.
7345 .sp
7346 Default: \fBno\fP
7347 .TP
7348 .B \fB\-\-dvbin\-channel\-switch\-offset=<integer>\fP
7349 This value is not meant for setting via configuration, but used in channel
7350 switching. An \fBinput.conf\fP can \fBcycle\fP this value \fBup\fP and \fBdown\fP
7351 to perform channel switching. This number effectively gives the offset
7352 to the initially tuned to channel in the channel list.
7353 .sp
7354 An example \fBinput.conf\fP could contain:
7355 \fBH cycle dvbin\-channel\-switch\-offset up\fP, \fBK cycle dvbin\-channel\-switch\-offset down\fP
7356 .UNINDENT
7357 .SS ALSA audio output options
7358 .INDENT 0.0
7359 .TP
7360 .B \fB\-\-alsa\-device=<device>\fP
7361 Deprecated, use \fB\-\-audio\-device\fP (requires \fBalsa/\fP prefix).
7362 .TP
7363 .B \fB\-\-alsa\-resample=yes\fP
7364 Enable ALSA resampling plugin. (This is disabled by default, because
7365 some drivers report incorrect audio delay in some cases.)
7366 .TP
7367 .B \fB\-\-alsa\-mixer\-device=<device>\fP
7368 Set the mixer device used with \fBao\-volume\fP (default: \fBdefault\fP).
7369 .TP
7370 .B \fB\-\-alsa\-mixer\-name=<name>\fP
7371 Set the name of the mixer element (default: \fBMaster\fP). This is for
7372 example \fBPCM\fP or \fBMaster\fP\&.
7373 .TP
7374 .B \fB\-\-alsa\-mixer\-index=<number>\fP
7375 Set the index of the mixer channel (default: 0). Consider the output of
7376 "\fBamixer scontrols\fP", then the index is the number that follows the
7377 name of the element.
7378 .TP
7379 .B \fB\-\-alsa\-non\-interleaved\fP
7380 Allow output of non\-interleaved formats (if the audio decoder uses
7381 this format). Currently disabled by default, because some popular
7382 ALSA plugins are utterly broken with non\-interleaved formats.
7383 .TP
7384 .B \fB\-\-alsa\-ignore\-chmap\fP
7385 Don\(aqt read or set the channel map of the ALSA device \- only request the
7386 required number of channels, and then pass the audio as\-is to it. This
7387 option most likely should not be used. It can be useful for debugging,
7388 or for static setups with a specially engineered ALSA configuration (in
7389 this case you should always force the same layout with \fB\-\-audio\-channels\fP,
7390 or it will work only for files which use the layout implicit to your
7391 ALSA device).
7392 .TP
7393 .B \fB\-\-alsa\-buffer\-time=<microseconds>\fP
7394 Set the requested buffer time in microseconds. A value of 0 skips requesting
7395 anything from the ALSA API. This and the \fB\-\-alsa\-periods\fP option uses the
7396 ALSA \fBnear\fP functions to set the requested parameters. If doing so results
7397 in an empty configuration set, setting these parameters is skipped.
7398 .sp
7399 Both options control the buffer size. A low buffer size can lead to higher
7400 CPU usage and audio dropouts, while a high buffer size can lead to higher
7401 latency in volume changes and other filtering.
7402 .TP
7403 .B \fB\-\-alsa\-periods=<number>\fP
7404 Number of periods requested from the ALSA API. See \fB\-\-alsa\-buffer\-time\fP
7405 for further remarks.
7406 .UNINDENT
7407 .SS GPU renderer options
7408 .sp
7409 The following video options are currently all specific to \fB\-\-vo=gpu\fP and
7410 \fB\-\-vo=libmpv\fP only, which are the only VOs that implement them.
7411 .INDENT 0.0
7412 .TP
7413 .B \fB\-\-scale=<filter>\fP
7414 The filter function to use when upscaling video.
7415 .INDENT 7.0
7416 .TP
7417 .B \fBbilinear\fP
7418 Bilinear hardware texture filtering (fastest, very low quality). This
7419 is the default for compatibility reasons.
7420 .TP
7421 .B \fBspline36\fP
7422 Mid quality and speed. This is the default when using \fBgpu\-hq\fP\&.
7423 .TP
7424 .B \fBlanczos\fP
7425 Lanczos scaling. Provides mid quality and speed. Generally worse than
7426 \fBspline36\fP, but it results in a slightly sharper image which is good
7427 for some content types. The number of taps can be controlled with
7428 \fBscale\-radius\fP, but is best left unchanged.
7429 .sp
7430 (This filter is an alias for \fBsinc\fP\-windowed \fBsinc\fP)
7431 .TP
7432 .B \fBewa_lanczos\fP
7433 Elliptic weighted average Lanczos scaling. Also known as Jinc.
7434 Relatively slow, but very good quality. The radius can be controlled
7435 with \fBscale\-radius\fP\&. Increasing the radius makes the filter sharper
7436 but adds more ringing.
7437 .sp
7438 (This filter is an alias for \fBjinc\fP\-windowed \fBjinc\fP)
7439 .TP
7440 .B \fBewa_lanczossharp\fP
7441 A slightly sharpened version of ewa_lanczos, preconfigured to use an
7442 ideal radius and parameter. If your hardware can run it, this is
7443 probably what you should use by default.
7444 .TP
7445 .B \fBmitchell\fP
7446 Mitchell\-Netravali. The \fBB\fP and \fBC\fP parameters can be set with
7447 \fB\-\-scale\-param1\fP and \fB\-\-scale\-param2\fP\&. This filter is very good at
7448 downscaling (see \fB\-\-dscale\fP).
7449 .TP
7450 .B \fBoversample\fP
7451 A version of nearest neighbour that (naively) oversamples pixels, so
7452 that pixels overlapping edges get linearly interpolated instead of
7453 rounded. This essentially removes the small imperfections and judder
7454 artifacts caused by nearest\-neighbour interpolation, in exchange for
7455 adding some blur. This filter is good at temporal interpolation, and
7456 also known as "smoothmotion" (see \fB\-\-tscale\fP).
7457 .TP
7458 .B \fBlinear\fP
7459 A \fB\-\-tscale\fP filter.
7460 .UNINDENT
7461 .sp
7462 There are some more filters, but most are not as useful. For a complete
7463 list, pass \fBhelp\fP as value, e.g.:
7464 .INDENT 7.0
7465 .INDENT 3.5
7466 .sp
7467 .nf
7468 .ft C
7469 mpv \-\-scale=help
7470 .ft P
7471 .fi
7472 .UNINDENT
7473 .UNINDENT
7474 .TP
7475 .B \fB\-\-cscale=<filter>\fP
7476 As \fB\-\-scale\fP, but for interpolating chroma information. If the image is
7477 not subsampled, this option is ignored entirely.
7478 .TP
7479 .B \fB\-\-dscale=<filter>\fP
7480 Like \fB\-\-scale\fP, but apply these filters on downscaling instead. If this
7481 option is unset, the filter implied by \fB\-\-scale\fP will be applied.
7482 .TP
7483 .B \fB\-\-tscale=<filter>\fP
7484 The filter used for interpolating the temporal axis (frames). This is only
7485 used if \fB\-\-interpolation\fP is enabled. The only valid choices for
7486 \fB\-\-tscale\fP are separable convolution filters (use \fB\-\-tscale=help\fP to
7487 get a list). The default is \fBmitchell\fP\&.
7488 .sp
7489 Common \fB\-\-tscale\fP choices include \fBoversample\fP, \fBlinear\fP,
7490 \fBcatmull_rom\fP, \fBmitchell\fP, \fBgaussian\fP, or \fBbicubic\fP\&. These are
7491 listed in increasing order of smoothness/blurriness, with \fBbicubic\fP
7492 being the smoothest/blurriest and \fBoversample\fP being the sharpest/least
7493 smooth.
7494 .TP
7495 .B \fB\-\-scale\-param1=<value>\fP, \fB\-\-scale\-param2=<value>\fP, \fB\-\-cscale\-param1=<value>\fP, \fB\-\-cscale\-param2=<value>\fP, \fB\-\-dscale\-param1=<value>\fP, \fB\-\-dscale\-param2=<value>\fP, \fB\-\-tscale\-param1=<value>\fP, \fB\-\-tscale\-param2=<value>\fP
7496 Set filter parameters. By default, these are set to the special string
7497 \fBdefault\fP, which maps to a scaler\-specific default value. Ignored if the
7498 filter is not tunable. Currently, this affects the following filter
7499 parameters:
7500 .INDENT 7.0
7501 .TP
7502 .B bcspline
7503 Spline parameters (\fBB\fP and \fBC\fP). Defaults to 0.5 for both.
7504 .TP
7505 .B gaussian
7506 Scale parameter (\fBt\fP). Increasing this makes the result blurrier.
7507 Defaults to 1.
7508 .TP
7509 .B oversample
7510 Minimum distance to an edge before interpolation is used. Setting this
7511 to 0 will always interpolate edges, whereas setting it to 0.5 will
7512 never interpolate, thus behaving as if the regular nearest neighbour
7513 algorithm was used. Defaults to 0.0.
7514 .UNINDENT
7515 .TP
7516 .B \fB\-\-scale\-blur=<value>\fP, \fB\-\-scale\-wblur=<value>\fP, \fB\-\-cscale\-blur=<value>\fP, \fB\-\-cscale\-wblur=<value>\fP, \fB\-\-dscale\-blur=<value>\fP, \fB\-\-dscale\-wblur=<value>\fP, \fB\-\-tscale\-blur=<value>\fP, \fB\-\-tscale\-wblur=<value>\fP
7517 Kernel/window scaling factor (also known as a blur factor). Decreasing this
7518 makes the result sharper, increasing it makes it blurrier (default 0). If
7519 set to 0, the kernel\(aqs preferred blur factor is used. Note that setting
7520 this too low (eg. 0.5) leads to bad results. It\(aqs generally recommended to
7521 stick to values between 0.8 and 1.2.
7522 .TP
7523 .B \fB\-\-scale\-clamp=<0.0\-1.0>\fP, \fB\-\-cscale\-clamp\fP, \fB\-\-dscale\-clamp\fP, \fB\-\-tscale\-clamp\fP
7524 Specifies a weight bias to multiply into negative coefficients. Specifying
7525 \fB\-\-scale\-clamp=1\fP has the effect of removing negative weights completely,
7526 thus effectively clamping the value range to [0\-1]. Values between 0.0 and
7527 1.0 can be specified to apply only a moderate diminishment of negative
7528 weights. This is especially useful for \fB\-\-tscale\fP, where it reduces
7529 excessive ringing artifacts in the temporal domain (which typically
7530 manifest themselves as short flashes or fringes of black, mostly around
7531 moving edges) in exchange for potentially adding more blur. The default for
7532 \fB\-\-tscale\-clamp\fP is 1.0, the others default to 0.0.
7533 .TP
7534 .B \fB\-\-scale\-cutoff=<value>\fP, \fB\-\-cscale\-cutoff=<value>\fP, \fB\-\-dscale\-cutoff=<value>\fP
7535 Cut off the filter kernel prematurely once the value range drops below
7536 this threshold. Doing so allows more aggressive pruning of skippable
7537 coefficients by disregarding parts of the LUT which are effectively zeroed
7538 out by the window function. Only affects polar (EWA) filters. The default
7539 is 0.001 for each, which is perceptually transparent but provides a 10%\-20%
7540 speedup, depending on the exact radius and filter kernel chosen.
7541 .TP
7542 .B \fB\-\-scale\-taper=<value>\fP, \fB\-\-scale\-wtaper=<value>\fP, \fB\-\-dscale\-taper=<value>\fP, \fB\-\-dscale\-wtaper=<value>\fP, \fB\-\-cscale\-taper=<value>\fP, \fB\-\-cscale\-wtaper=<value>\fP, \fB\-\-tscale\-taper=<value>\fP, \fB\-\-tscale\-wtaper=<value>\fP
7543 Kernel/window taper factor. Increasing this flattens the filter function.
7544 Value range is 0 to 1. A value of 0 (the default) means no flattening, a
7545 value of 1 makes the filter completely flat (equivalent to a box function).
7546 Values in between mean that some portion will be flat and the actual filter
7547 function will be squeezed into the space in between.
7548 .TP
7549 .B \fB\-\-scale\-radius=<value>\fP, \fB\-\-cscale\-radius=<value>\fP, \fB\-\-dscale\-radius=<value>\fP, \fB\-\-tscale\-radius=<value>\fP
7550 Set radius for tunable filters, must be a float number between 0.5 and
7551 16.0. Defaults to the filter\(aqs preferred radius if not specified. Doesn\(aqt
7552 work for every scaler and VO combination.
7553 .sp
7554 Note that depending on filter implementation details and video scaling
7555 ratio, the radius that actually being used might be different (most likely
7556 being increased a bit).
7557 .TP
7558 .B \fB\-\-scale\-antiring=<value>\fP, \fB\-\-cscale\-antiring=<value>\fP, \fB\-\-dscale\-antiring=<value>\fP, \fB\-\-tscale\-antiring=<value>\fP
7559 Set the antiringing strength. This tries to eliminate ringing, but can
7560 introduce other artifacts in the process. Must be a float number between
7561 0.0 and 1.0. The default value of 0.0 disables antiringing entirely.
7562 .sp
7563 Note that this doesn\(aqt affect the special filters \fBbilinear\fP and
7564 \fBbicubic_fast\fP, nor does it affect any polar (EWA) scalers.
7565 .TP
7566 .B \fB\-\-scale\-window=<window>\fP, \fB\-\-cscale\-window=<window>\fP, \fB\-\-dscale\-window=<window>\fP, \fB\-\-tscale\-window=<window>\fP
7567 (Advanced users only) Choose a custom windowing function for the kernel.
7568 Defaults to the filter\(aqs preferred window if unset. Use
7569 \fB\-\-scale\-window=help\fP to get a list of supported windowing functions.
7570 .TP
7571 .B \fB\-\-scale\-wparam=<window>\fP, \fB\-\-cscale\-wparam=<window>\fP, \fB\-\-cscale\-wparam=<window>\fP, \fB\-\-tscale\-wparam=<window>\fP
7572 (Advanced users only) Configure the parameter for the window function given
7573 by \fB\-\-scale\-window\fP etc. By default, these are set to the special string
7574 \fBdefault\fP, which maps to a window\-specific default value. Ignored if the
7575 window is not tunable. Currently, this affects the following window
7576 parameters:
7577 .INDENT 7.0
7578 .TP
7579 .B kaiser
7580 Window parameter (alpha). Defaults to 6.33.
7581 .TP
7582 .B blackman
7583 Window parameter (alpha). Defaults to 0.16.
7584 .TP
7585 .B gaussian
7586 Scale parameter (t). Increasing this makes the window wider. Defaults
7587 to 1.
7588 .UNINDENT
7589 .TP
7590 .B \fB\-\-scaler\-lut\-size=<4..10>\fP
7591 Set the size of the lookup texture for scaler kernels (default: 6). The
7592 actual size of the texture is \fB2^N\fP for an option value of \fBN\fP\&. So the
7593 lookup texture with the default setting uses 64 samples.
7594 .sp
7595 All weights are linearly interpolated from those samples, so increasing
7596 the size of lookup table might improve the accuracy of scaler.
7597 .TP
7598 .B \fB\-\-scaler\-resizes\-only\fP
7599 Disable the scaler if the video image is not resized. In that case,
7600 \fBbilinear\fP is used instead of whatever is set with \fB\-\-scale\fP\&. Bilinear
7601 will reproduce the source image perfectly if no scaling is performed.
7602 Enabled by default. Note that this option never affects \fB\-\-cscale\fP\&.
7603 .TP
7604 .B \fB\-\-correct\-downscaling\fP
7605 When using convolution based filters, extend the filter size when
7606 downscaling. Increases quality, but reduces performance while downscaling.
7607 .sp
7608 This will perform slightly sub\-optimally for anamorphic video (but still
7609 better than without it) since it will extend the size to match only the
7610 milder of the scale factors between the axes.
7611 .sp
7612 Note: this option is ignored when using bilinear downscaling (the default).
7613 .TP
7614 .B \fB\-\-linear\-downscaling\fP
7615 Scale in linear light when downscaling. It should only be used with a
7616 \fB\-\-fbo\-format\fP that has at least 16 bit precision. This option
7617 has no effect on HDR content.
7618 .TP
7619 .B \fB\-\-linear\-upscaling\fP
7620 Scale in linear light when upscaling. Like \fB\-\-linear\-downscaling\fP, it
7621 should only be used with a \fB\-\-fbo\-format\fP that has at least 16 bits
7622 precisions. This is not usually recommended except for testing/specific
7623 purposes. Users are advised to either enable \fB\-\-sigmoid\-upscaling\fP or
7624 keep both options disabled (i.e. scaling in gamma light).
7625 .TP
7626 .B \fB\-\-sigmoid\-upscaling\fP
7627 When upscaling, use a sigmoidal color transform to avoid emphasizing
7628 ringing artifacts. This is incompatible with and replaces
7629 \fB\-\-linear\-upscaling\fP\&. (Note that sigmoidization also requires
7630 linearization, so the \fBLINEAR\fP rendering step fires in both cases)
7631 .TP
7632 .B \fB\-\-sigmoid\-center\fP
7633 The center of the sigmoid curve used for \fB\-\-sigmoid\-upscaling\fP, must be a
7634 float between 0.0 and 1.0. Defaults to 0.75 if not specified.
7635 .TP
7636 .B \fB\-\-sigmoid\-slope\fP
7637 The slope of the sigmoid curve used for \fB\-\-sigmoid\-upscaling\fP, must be a
7638 float between 1.0 and 20.0. Defaults to 6.5 if not specified.
7639 .TP
7640 .B \fB\-\-interpolation\fP
7641 Reduce stuttering caused by mismatches in the video fps and display refresh
7642 rate (also known as judder).
7643 .sp
7644 \fBWARNING:\fP
7645 .INDENT 7.0
7646 .INDENT 3.5
7647 This requires setting the \fB\-\-video\-sync\fP option to one
7648 of the \fBdisplay\-\fP modes, or it will be silently disabled.
7649 This was not required before mpv 0.14.0.
7650 .UNINDENT
7651 .UNINDENT
7652 .sp
7653 This essentially attempts to interpolate the missing frames by convoluting
7654 the video along the temporal axis. The filter used can be controlled using
7655 the \fB\-\-tscale\fP setting.
7656 .TP
7657 .B \fB\-\-interpolation\-threshold=<0..1,\-1>\fP
7658 Threshold below which frame ratio interpolation gets disabled (default:
7659 \fB0.0001\fP). This is calculated as \fBabs(disphz/vfps \- 1) < threshold\fP,
7660 where \fBvfps\fP is the speed\-adjusted video FPS, and \fBdisphz\fP the
7661 display refresh rate. (The speed\-adjusted video FPS is roughly equal to
7662 the normal video FPS, but with slowdown and speedup applied. This matters
7663 if you use \fB\-\-video\-sync=display\-resample\fP to make video run synchronously
7664 to the display FPS, or if you change the \fBspeed\fP property.)
7665 .sp
7666 The default is intended to almost always enable interpolation if the
7667 playback rate is even slightly different from the display refresh rate. But
7668 note that if you use e.g. \fB\-\-video\-sync=display\-vdrop\fP, small deviations
7669 in the rate can disable interpolation and introduce a discontinuity every
7670 other minute.
7671 .sp
7672 Set this to \fB\-1\fP to disable this logic.
7673 .TP
7674 .B \fB\-\-opengl\-pbo\fP
7675 Enable use of PBOs. On some drivers this can be faster, especially if the
7676 source video size is huge (e.g. so called "4K" video). On other drivers it
7677 might be slower or cause latency issues.
7678 .TP
7679 .B \fB\-\-dither\-depth=<N|no|auto>\fP
7680 Set dither target depth to N. Default: no.
7681 .INDENT 7.0
7682 .TP
7683 .B no
7684 Disable any dithering done by mpv.
7685 .TP
7686 .B auto
7687 Automatic selection. If output bit depth cannot be detected, 8 bits per
7688 component are assumed.
7689 .TP
7690 .B 8
7691 Dither to 8 bit output.
7692 .UNINDENT
7693 .sp
7694 Note that the depth of the connected video display device cannot be
7695 detected. Often, LCD panels will do dithering on their own, which conflicts
7696 with this option and leads to ugly output.
7697 .TP
7698 .B \fB\-\-dither\-size\-fruit=<2\-8>\fP
7699 Set the size of the dither matrix (default: 6). The actual size of the
7700 matrix is \fB(2^N) x (2^N)\fP for an option value of \fBN\fP, so a value of 6
7701 gives a size of 64x64. The matrix is generated at startup time, and a large
7702 matrix can take rather long to compute (seconds).
7703 .sp
7704 Used in \fB\-\-dither=fruit\fP mode only.
7705 .TP
7706 .B \fB\-\-dither=<fruit|ordered|error\-diffusion|no>\fP
7707 Select dithering algorithm (default: fruit). (Normally, the
7708 \fB\-\-dither\-depth\fP option controls whether dithering is enabled.)
7709 .sp
7710 The \fBerror\-diffusion\fP option requires compute shader support. It also
7711 requires large amount of shared memory to run, the size of which depends on
7712 both the kernel (see \fB\-\-error\-diffusion\fP option below) and the height of
7713 video window. It will fallback to \fBfruit\fP dithering if there is no enough
7714 shared memory to run the shader.
7715 .TP
7716 .B \fB\-\-temporal\-dither\fP
7717 Enable temporal dithering. (Only active if dithering is enabled in
7718 general.) This changes between 8 different dithering patterns on each frame
7719 by changing the orientation of the tiled dithering matrix. Unfortunately,
7720 this can lead to flicker on LCD displays, since these have a high reaction
7721 time.
7722 .TP
7723 .B \fB\-\-temporal\-dither\-period=<1\-128>\fP
7724 Determines how often the dithering pattern is updated when
7725 \fB\-\-temporal\-dither\fP is in use. 1 (the default) will update on every video
7726 frame, 2 on every other frame, etc.
7727 .TP
7728 .B \fB\-\-error\-diffusion=<kernel>\fP
7729 The error diffusion kernel to use when \fB\-\-dither=error\-diffusion\fP is set.
7730 .INDENT 7.0
7731 .TP
7732 .B \fBsimple\fP
7733 Propagate error to only two adjacent pixels. Fastest but low quality.
7734 .TP
7735 .B \fBsierra\-lite\fP
7736 Fast with reasonable quality. This is the default.
7737 .TP
7738 .B \fBfloyd\-steinberg\fP
7739 Most notable error diffusion kernel.
7740 .TP
7741 .B \fBatkinson\fP
7742 Looks different from other kernels because only fraction of errors will
7743 be propagated during dithering. A typical use case of this kernel is
7744 saving dithered screenshot (in window mode). This kernel produces
7745 slightly smaller file, with still reasonable dithering quality.
7746 .UNINDENT
7747 .sp
7748 There are other kernels (use \fB\-\-error\-diffusion=help\fP to list) but most of
7749 them are much slower and demanding even larger amount of shared memory.
7750 Among these kernels, \fBburkes\fP achieves a good balance between performance
7751 and quality, and probably is the one you want to try first.
7752 .TP
7753 .B \fB\-\-gpu\-debug\fP
7754 Enables GPU debugging. What this means depends on the API type. For OpenGL,
7755 it calls \fBglGetError()\fP, and requests a debug context. For Vulkan, it
7756 enables validation layers.
7757 .TP
7758 .B \fB\-\-opengl\-swapinterval=<n>\fP
7759 Interval in displayed frames between two buffer swaps. 1 is equivalent to
7760 enable VSYNC, 0 to disable VSYNC. Defaults to 1 if not specified.
7761 .sp
7762 Note that this depends on proper OpenGL vsync support. On some platforms
7763 and drivers, this only works reliably when in fullscreen mode. It may also
7764 require driver\-specific hacks if using multiple monitors, to ensure mpv
7765 syncs to the right one. Compositing window managers can also lead to bad
7766 results, as can missing or incorrect display FPS information (see
7767 \fB\-\-override\-display\-fps\fP).
7768 .TP
7769 .B \fB\-\-vulkan\-swap\-mode=<mode>\fP
7770 Controls the presentation mode of the vulkan swapchain. This is similar
7771 to the \fB\-\-opengl\-swapinterval\fP option.
7772 .INDENT 7.0
7773 .TP
7774 .B auto
7775 Use the preferred swapchain mode for the vulkan context. (Default)
7776 .TP
7777 .B fifo
7778 Non\-tearing, vsync blocked. Similar to "VSync on".
7779 .TP
7780 .B fifo\-relaxed
7781 Tearing, vsync blocked. Late frames will tear instead of stuttering.
7782 .TP
7783 .B mailbox
7784 Non\-tearing, not vsync blocked. Similar to "triple buffering".
7785 .TP
7786 .B immediate
7787 Tearing, not vsync blocked. Similar to "VSync off".
7788 .UNINDENT
7789 .TP
7790 .B \fB\-\-vulkan\-queue\-count=<1..8>\fP
7791 Controls the number of VkQueues used for rendering (limited by how many
7792 your device supports). In theory, using more queues could enable some
7793 parallelism between frames (when using a \fB\-\-swapchain\-depth\fP higher than
7794 1), but it can also slow things down on hardware where there\(aqs no true
7795 parallelism between queues. (Default: 1)
7796 .TP
7797 .B \fB\-\-vulkan\-async\-transfer\fP
7798 Enables the use of async transfer queues on supported vulkan devices. Using
7799 them allows transfer operations like texture uploads and blits to happen
7800 concurrently with the actual rendering, thus improving overall throughput
7801 and power consumption. Enabled by default, and should be relatively safe.
7802 .TP
7803 .B \fB\-\-vulkan\-async\-compute\fP
7804 Enables the use of async compute queues on supported vulkan devices. Using
7805 this, in theory, allows out\-of\-order scheduling of compute shaders with
7806 graphics shaders, thus enabling the hardware to do more effective work while
7807 waiting for pipeline bubbles and memory operations. Not beneficial on all
7808 GPUs. It\(aqs worth noting that if async compute is enabled, and the device
7809 supports more compute queues than graphics queues (bound by the restrictions
7810 set by \fB\-\-vulkan\-queue\-count\fP), mpv will internally try and prefer the
7811 use of compute shaders over fragment shaders wherever possible. Enabled by
7812 default, although Nvidia users may want to disable it.
7813 .TP
7814 .B \fB\-\-vulkan\-disable\-events\fP
7815 Disable the use of VkEvents, for debugging purposes or for compatibility
7816 with some older drivers / vulkan portability layers that don\(aqt provide
7817 working VkEvent support.
7818 .TP
7819 .B \fB\-\-d3d11\-exclusive\-fs=<yes|no>\fP
7820 Switches the D3D11 swap chain fullscreen state to \(aqfullscreen\(aq when
7821 fullscreen video is requested. Also known as "exclusive fullscreen" or
7822 "D3D fullscreen" in other applications. Gives mpv full control of
7823 rendering on the swap chain\(aqs screen. Off by default.
7824 .TP
7825 .B \fB\-\-d3d11\-warp=<yes|no|auto>\fP
7826 Use WARP (Windows Advanced Rasterization Platform) with the D3D11 GPU
7827 backend (default: auto). This is a high performance software renderer. By
7828 default, it is only used when the system has no hardware adapters that
7829 support D3D11. While the extended GPU features will work with WARP, they
7830 can be very slow.
7831 .TP
7832 .B \fB\-\-d3d11\-feature\-level=<12_1|12_0|11_1|11_0|10_1|10_0|9_3|9_2|9_1>\fP
7833 Select a specific feature level when using the D3D11 GPU backend. By
7834 default, the highest available feature level is used. This option can be
7835 used to select a lower feature level, which is mainly useful for debugging.
7836 Most extended GPU features will not work at 9_x feature levels.
7837 .TP
7838 .B \fB\-\-d3d11\-flip=<yes|no>\fP
7839 Enable flip\-model presentation, which avoids unnecessarily copying the
7840 backbuffer by sharing surfaces with the DWM (default: yes). This may cause
7841 performance issues with older drivers. If flip\-model presentation is not
7842 supported (for example, on Windows 7 without the platform update), mpv will
7843 automatically fall back to the older bitblt presentation model.
7844 .TP
7845 .B \fB\-\-d3d11\-sync\-interval=<0..4>\fP
7846 Schedule each frame to be presented for this number of VBlank intervals.
7847 (default: 1) Setting to 1 will enable VSync, setting to 0 will disable it.
7848 .TP
7849 .B \fB\-\-d3d11\-adapter=<adapter name|help>\fP
7850 Select a specific D3D11 adapter to utilize for D3D11 rendering.
7851 Will pick the default adapter if unset. Alternatives are listed
7852 when the name "help" is given.
7853 .sp
7854 Checks for matches based on the start of the string, case
7855 insensitive. Thus, if the description of the adapter starts with
7856 the vendor name, that can be utilized as the selection parameter.
7857 .sp
7858 Hardware decoders utilizing the D3D11 rendering abstraction\(aqs helper
7859 functionality to receive a device, such as D3D11VA or DXVA2\(aqs DXGI
7860 mode, will be affected by this choice.
7861 .TP
7862 .B \fB\-\-d3d11\-output\-format=<auto|rgba8|bgra8|rgb10_a2|rgba16f>\fP
7863 Select a specific D3D11 output format to utilize for D3D11 rendering.
7864 "auto" is the default, which will pick either rgba8 or rgb10_a2 depending
7865 on the configured desktop bit depth. rgba16f and bgra8 are left out of
7866 the autodetection logic, and are available for manual testing.
7867 .sp
7868 \fBNOTE:\fP
7869 .INDENT 7.0
7870 .INDENT 3.5
7871 Desktop bit depth querying is only available from an API available
7872 from Windows 10. Thus on older systems it will only automatically
7873 utilize the rgba8 output format.
7874 .UNINDENT
7875 .UNINDENT
7876 .TP
7877 .B \fB\-\-d3d11\-output\-csp=<auto|srgb|linear|pq|bt.2020>\fP
7878 Select a specific D3D11 output color space to utilize for D3D11 rendering.
7879 "auto" is the default, which will select the color space of the desktop
7880 on which the swap chain is located.
7881 .sp
7882 Values other than "srgb" and "pq" have had issues in testing, so they
7883 are mostly available for manual testing.
7884 .sp
7885 \fBNOTE:\fP
7886 .INDENT 7.0
7887 .INDENT 3.5
7888 Swap chain color space configuration is only available from an API
7889 available from Windows 10. Thus on older systems it will not work.
7890 .UNINDENT
7891 .UNINDENT
7892 .TP
7893 .B \fB\-\-d3d11va\-zero\-copy=<yes|no>\fP
7894 By default, when using hardware decoding with \fB\-\-gpu\-api=d3d11\fP, the
7895 video image will be copied (GPU\-to\-GPU) from the decoder surface to a
7896 shader resource. Set this option to avoid that copy by sampling directly
7897 from the decoder image. This may increase performance and reduce power
7898 usage, but can cause the image to be sampled incorrectly on the bottom and
7899 right edges due to padding, and may invoke driver bugs, since Direct3D 11
7900 technically does not allow sampling from a decoder surface (though most
7901 drivers support it.)
7902 .sp
7903 Currently only relevant for \fB\-\-gpu\-api=d3d11\fP\&.
7904 .TP
7905 .B \fB\-\-wayland\-app\-id=<string>\fP
7906 Set the client app id for Wayland\-based video output methods. By default, "mpv"
7907 is used.
7908 .TP
7909 .B \fB\-\-wayland\-disable\-vsync=<yes|no>\fP
7910 Disable vsync for the wayland contexts (default: no). Useful for benchmarking
7911 the wayland context when combined with \fBvideo\-sync=display\-desync\fP,
7912 \fB\-\-no\-audio\fP, and \fB\-\-untimed=yes\fP\&. Only works with \fB\-\-gpu\-context=wayland\fP
7913 and \fB\-\-gpu\-context=waylandvk\fP\&.
7914 .TP
7915 .B \fB\-\-wayland\-edge\-pixels\-pointer=<value>\fP
7916 Defines the size of an edge border (default: 10) to initiate client side
7917 resize events in the wayland contexts with the mouse. This is only active if
7918 there are no server side decorations from the compositor.
7919 .TP
7920 .B \fB\-\-wayland\-edge\-pixels\-touch=<value>\fP
7921 Defines the size of an edge border (default: 64) to initiate client side
7922 resizes events in the wayland contexts with touch events.
7923 .TP
7924 .B \fB\-\-spirv\-compiler=<compiler>\fP
7925 Controls which compiler is used to translate GLSL to SPIR\-V. This is
7926 (currently) only relevant for \fB\-\-gpu\-api=vulkan\fP and \fI\-\-gpu\-api=d3d11\fP\&.
7927 The possible choices are currently only:
7928 .INDENT 7.0
7929 .TP
7930 .B auto
7931 Use the first available compiler. (Default)
7932 .TP
7933 .B shaderc
7934 Use libshaderc, which is an API wrapper around glslang. This is
7935 generally the most preferred, if available.
7936 .UNINDENT
7937 .sp
7938 \fBNOTE:\fP
7939 .INDENT 7.0
7940 .INDENT 3.5
7941 This option is deprecated, since there is only one reasonable value.
7942 It may be removed in the future.
7943 .UNINDENT
7944 .UNINDENT
7945 .TP
7946 .B \fB\-\-glsl\-shader=<file>\fP, \fB\-\-glsl\-shaders=<file\-list>\fP
7947 Custom GLSL hooks. These are a flexible way to add custom fragment shaders,
7948 which can be injected at almost arbitrary points in the rendering pipeline,
7949 and access all previous intermediate textures.
7950 .sp
7951 Each use of the \fB\-\-glsl\-shader\fP option will add another file to the
7952 internal list of shaders, while \fB\-\-glsl\-shaders\fP takes a list of files,
7953 and overwrites the internal list with it. The latter is a path list option
7954 (see \fI\%List Options\fP for details).
7955 .INDENT 7.0
7956 .INDENT 3.5
7957 .IP "Warning"
7958 .sp
7959 The syntax is not stable yet and may change any time.
7960 .UNINDENT
7961 .UNINDENT
7962 .sp
7963 The general syntax of a user shader looks like this:
7964 .INDENT 7.0
7965 .INDENT 3.5
7966 .sp
7967 .nf
7968 .ft C
7969 //!METADATA ARGS...
7970 //!METADATA ARGS...
7971
7972 vec4 hook() {
7973 ...
7974 return something;
7975 }
7976
7977 //!METADATA ARGS...
7978 //!METADATA ARGS...
7979
7980 \&...
7981 .ft P
7982 .fi
7983 .UNINDENT
7984 .UNINDENT
7985 .sp
7986 Each section of metadata, along with the non\-metadata lines after it,
7987 defines a single block. There are currently two types of blocks, HOOKs and
7988 TEXTUREs.
7989 .sp
7990 A \fBTEXTURE\fP block can set the following options:
7991 .INDENT 7.0
7992 .TP
7993 .B TEXTURE <name> (required)
7994 The name of this texture. Hooks can then bind the texture under this
7995 name using BIND. This must be the first option of the texture block.
7996 .TP
7997 .B SIZE <width> [<height>] [<depth>] (required)
7998 The dimensions of the texture. The height and depth are optional. The
7999 type of texture (1D, 2D or 3D) depends on the number of components
8000 specified.
8001 .TP
8002 .B FORMAT <name> (required)
8003 The texture format for the samples. Supported texture formats are listed
8004 in debug logging when the \fBgpu\fP VO is initialized (look for
8005 \fBTexture formats:\fP). Usually, this follows OpenGL naming conventions.
8006 For example, \fBrgb16\fP provides 3 channels with normalized 16 bit
8007 components. One oddity are float formats: for example, \fBrgba16f\fP has
8008 16 bit internal precision, but the texture data is provided as 32 bit
8009 floats, and the driver converts the data on texture upload.
8010 .sp
8011 Although format names follow a common naming convention, not all of them
8012 are available on all hardware, drivers, GL versions, and so on.
8013 .TP
8014 .B FILTER <LINEAR|NEAREST>
8015 The min/magnification filter used when sampling from this texture.
8016 .TP
8017 .B BORDER <CLAMP|REPEAT|MIRROR>
8018 The border wrapping mode used when sampling from this texture.
8019 .UNINDENT
8020 .sp
8021 Following the metadata is a string of bytes in hexadecimal notation that
8022 define the raw texture data, corresponding to the format specified by
8023 \fIFORMAT\fP, on a single line with no extra whitespace.
8024 .sp
8025 A \fBHOOK\fP block can set the following options:
8026 .INDENT 7.0
8027 .TP
8028 .B HOOK <name> (required)
8029 The texture which to hook into. May occur multiple times within a
8030 metadata block, up to a predetermined limit. See below for a list of
8031 hookable textures.
8032 .TP
8033 .B DESC <title>
8034 User\-friendly description of the pass. This is the name used when
8035 representing this shader in the list of passes for property
8036 \fIvo\-passes\fP\&.
8037 .TP
8038 .B BIND <name>
8039 Loads a texture (either coming from mpv or from a \fBTEXTURE\fP block)
8040 and makes it available to the pass. When binding textures from mpv,
8041 this will also set up macros to facilitate accessing it properly. See
8042 below for a list. By default, no textures are bound. The special name
8043 HOOKED can be used to refer to the texture that triggered this pass.
8044 .TP
8045 .B SAVE <name>
8046 Gives the name of the texture to save the result of this pass into. By
8047 default, this is set to the special name HOOKED which has the effect of
8048 overwriting the hooked texture.
8049 .TP
8050 .B WIDTH <szexpr>, HEIGHT <szexpr>
8051 Specifies the size of the resulting texture for this pass. \fBszexpr\fP
8052 refers to an expression in RPN (reverse polish notation), using the
8053 operators + \- * / > < !, floating point literals, and references to
8054 sizes of existing texture (such as MAIN.width or CHROMA.height),
8055 OUTPUT, or NATIVE_CROPPED (size of an input texture cropped after
8056 pan\-and\-scan, video\-align\-x/y, video\-pan\-x/y, etc. and possibly
8057 prescaled). By default, these are set to HOOKED.w and HOOKED.h,
8058 espectively.
8059 .TP
8060 .B WHEN <szexpr>
8061 Specifies a condition that needs to be true (non\-zero) for the shader
8062 stage to be evaluated. If it fails, it will silently be omitted. (Note
8063 that a shader stage like this which has a dependency on an optional
8064 hook point can still cause that hook point to be saved, which has some
8065 minor overhead)
8066 .TP
8067 .B OFFSET <ox oy | ALIGN>
8068 Indicates a pixel shift (offset) introduced by this pass. These pixel
8069 offsets will be accumulated and corrected during the next scaling pass
8070 (\fBcscale\fP or \fBscale\fP). The default values are 0 0 which correspond
8071 to no shift. Note that offsets are ignored when not overwriting the
8072 hooked texture.
8073 .sp
8074 A special value of \fBALIGN\fP will attempt to fix existing offset of
8075 HOOKED by align it with reference. It requires HOOKED to be resizable
8076 (see below). It works transparently with fragment shader. For compute
8077 shader, the predefined \fBtexmap\fP macro is required to handle coordinate
8078 mapping.
8079 .TP
8080 .B COMPONENTS <n>
8081 Specifies how many components of this pass\(aqs output are relevant and
8082 should be stored in the texture, up to 4 (rgba). By default, this value
8083 is equal to the number of components in HOOKED.
8084 .TP
8085 .B COMPUTE <bw> <bh> [<tw> <th>]
8086 Specifies that this shader should be treated as a compute shader, with
8087 the block size bw and bh. The compute shader will be dispatched with
8088 however many blocks are necessary to completely tile over the output.
8089 Within each block, there will bw tw*th threads, forming a single work
8090 group. In other words: tw and th specify the work group size, which can
8091 be different from the block size. So for example, a compute shader with
8092 bw, bh = 32 and tw, th = 8 running on a 500x500 texture would dispatch
8093 16x16 blocks (rounded up), each with 8x8 threads.
8094 .sp
8095 Compute shaders in mpv are treated a bit different from fragment
8096 shaders. Instead of defining a \fBvec4 hook\fP that produces an output
8097 sample, you directly define \fBvoid hook\fP which writes to a fixed
8098 writeonly image unit named \fBout_image\fP (this is bound by mpv) using
8099 \fIimageStore\fP\&. To help translate texture coordinates in the absence of
8100 vertices, mpv provides a special function \fBNAME_map(id)\fP to map from
8101 the texel space of the output image to the texture coordinates for all
8102 bound textures. In particular, \fBNAME_pos\fP is equivalent to
8103 \fBNAME_map(gl_GlobalInvocationID)\fP, although using this only really
8104 makes sense if (tw,th) == (bw,bh).
8105 .UNINDENT
8106 .sp
8107 Each bound mpv texture (via \fBBIND\fP) will make available the following
8108 definitions to that shader pass, where NAME is the name of the bound
8109 texture:
8110 .INDENT 7.0
8111 .TP
8112 .B vec4 NAME_tex(vec2 pos)
8113 The sampling function to use to access the texture at a certain spot
8114 (in texture coordinate space, range [0,1]). This takes care of any
8115 necessary normalization conversions.
8116 .TP
8117 .B vec4 NAME_texOff(vec2 offset)
8118 Sample the texture at a certain offset in pixels. This works like
8119 NAME_tex but additionally takes care of necessary rotations, so that
8120 sampling at e.g. vec2(\-1,0) is always one pixel to the left.
8121 .TP
8122 .B vec2 NAME_pos
8123 The local texture coordinate of that texture, range [0,1].
8124 .TP
8125 .B vec2 NAME_size
8126 The (rotated) size in pixels of the texture.
8127 .TP
8128 .B mat2 NAME_rot
8129 The rotation matrix associated with this texture. (Rotates pixel space
8130 to texture coordinates)
8131 .TP
8132 .B vec2 NAME_pt
8133 The (unrotated) size of a single pixel, range [0,1].
8134 .TP
8135 .B float NAME_mul
8136 The coefficient that needs to be multiplied into the texture contents
8137 in order to normalize it to the range [0,1].
8138 .TP
8139 .B sampler NAME_raw
8140 The raw bound texture itself. The use of this should be avoided unless
8141 absolutely necessary.
8142 .UNINDENT
8143 .sp
8144 Normally, users should use either NAME_tex or NAME_texOff to read from the
8145 texture. For some shaders however , it can be better for performance to do
8146 custom sampling from NAME_raw, in which case care needs to be taken to
8147 respect NAME_mul and NAME_rot.
8148 .sp
8149 In addition to these parameters, the following uniforms are also globally
8150 available:
8151 .INDENT 7.0
8152 .TP
8153 .B float random
8154 A random number in the range [0\-1], different per frame.
8155 .TP
8156 .B int frame
8157 A simple count of frames rendered, increases by one per frame and never
8158 resets (regardless of seeks).
8159 .TP
8160 .B vec2 input_size
8161 The size in pixels of the input image (possibly cropped and prescaled).
8162 .TP
8163 .B vec2 target_size
8164 The size in pixels of the visible part of the scaled (and possibly
8165 cropped) image.
8166 .TP
8167 .B vec2 tex_offset
8168 Texture offset introduced by user shaders or options like panscan, video\-align\-x/y, video\-pan\-x/y.
8169 .UNINDENT
8170 .sp
8171 Internally, vo_gpu may generate any number of the following textures.
8172 Whenever a texture is rendered and saved by vo_gpu, all of the passes
8173 that have hooked into it will run, in the order they were added by the
8174 user. This is a list of the legal hook points:
8175 .INDENT 7.0
8176 .TP
8177 .B RGB, LUMA, CHROMA, ALPHA, XYZ (resizable)
8178 Source planes (raw). Which of these fire depends on the image format of
8179 the source.
8180 .TP
8181 .B CHROMA_SCALED, ALPHA_SCALED (fixed)
8182 Source planes (upscaled). These only fire on subsampled content.
8183 .TP
8184 .B NATIVE (resizable)
8185 The combined image, in the source colorspace, before conversion to RGB.
8186 .TP
8187 .B MAINPRESUB (resizable)
8188 The image, after conversion to RGB, but before
8189 \fB\-\-blend\-subtitles=video\fP is applied.
8190 .TP
8191 .B MAIN (resizable)
8192 The main image, after conversion to RGB but before upscaling.
8193 .TP
8194 .B LINEAR (fixed)
8195 Linear light image, before scaling. This only fires when
8196 \fB\-\-linear\-upscaling\fP, \fB\-\-linear\-downscaling\fP or
8197 \fB\-\-sigmoid\-upscaling\fP is in effect.
8198 .TP
8199 .B SIGMOID (fixed)
8200 Sigmoidized light, before scaling. This only fires when
8201 \fB\-\-sigmoid\-upscaling\fP is in effect.
8202 .TP
8203 .B PREKERNEL (fixed)
8204 The image immediately before the scaler kernel runs.
8205 .TP
8206 .B POSTKERNEL (fixed)
8207 The image immediately after the scaler kernel runs.
8208 .TP
8209 .B SCALED (fixed)
8210 The final upscaled image, before color management.
8211 .TP
8212 .B OUTPUT (fixed)
8213 The final output image, after color management but before dithering and
8214 drawing to screen.
8215 .UNINDENT
8216 .sp
8217 Only the textures labelled with \fBresizable\fP may be transformed by the
8218 pass. When overwriting a texture marked \fBfixed\fP, the WIDTH, HEIGHT and
8219 OFFSET must be left at their default values.
8220 .TP
8221 .B \fB\-\-glsl\-shader=<file>\fP
8222 CLI/config file only alias for \fB\-\-glsl\-shaders\-append\fP\&.
8223 .TP
8224 .B \fB\-\-deband\fP
8225 Enable the debanding algorithm. This greatly reduces the amount of visible
8226 banding, blocking and other quantization artifacts, at the expense of
8227 very slightly blurring some of the finest details. In practice, it\(aqs
8228 virtually always an improvement \- the only reason to disable it would be
8229 for performance.
8230 .TP
8231 .B \fB\-\-deband\-iterations=<1..16>\fP
8232 The number of debanding steps to perform per sample. Each step reduces a
8233 bit more banding, but takes time to compute. Note that the strength of each
8234 step falls off very quickly, so high numbers (>4) are practically useless.
8235 (Default 1)
8236 .TP
8237 .B \fB\-\-deband\-threshold=<0..4096>\fP
8238 The debanding filter\(aqs cut\-off threshold. Higher numbers increase the
8239 debanding strength dramatically but progressively diminish image details.
8240 (Default 64)
8241 .TP
8242 .B \fB\-\-deband\-range=<1..64>\fP
8243 The debanding filter\(aqs initial radius. The radius increases linearly for
8244 each iteration. A higher radius will find more gradients, but a lower
8245 radius will smooth more aggressively. (Default 16)
8246 .sp
8247 If you increase the \fB\-\-deband\-iterations\fP, you should probably decrease
8248 this to compensate.
8249 .TP
8250 .B \fB\-\-deband\-grain=<0..4096>\fP
8251 Add some extra noise to the image. This significantly helps cover up
8252 remaining quantization artifacts. Higher numbers add more noise. (Default
8253 48)
8254 .TP
8255 .B \fB\-\-sharpen=<value>\fP
8256 If set to a value other than 0, enable an unsharp masking filter. Positive
8257 values will sharpen the image (but add more ringing and aliasing). Negative
8258 values will blur the image. If your GPU is powerful enough, consider
8259 alternatives like the \fBewa_lanczossharp\fP scale filter, or the
8260 \fB\-\-scale\-blur\fP option.
8261 .TP
8262 .B \fB\-\-opengl\-glfinish\fP
8263 Call \fBglFinish()\fP before swapping buffers (default: disabled). Slower,
8264 but might improve results when doing framedropping. Can completely ruin
8265 performance. The details depend entirely on the OpenGL driver.
8266 .TP
8267 .B \fB\-\-opengl\-waitvsync\fP
8268 Call \fBglXWaitVideoSyncSGI\fP after each buffer swap (default: disabled).
8269 This may or may not help with video timing accuracy and frame drop. It\(aqs
8270 possible that this makes video output slower, or has no effect at all.
8271 .sp
8272 X11/GLX only.
8273 .TP
8274 .B \fB\-\-opengl\-dwmflush=<no|windowed|yes|auto>\fP
8275 Calls \fBDwmFlush\fP after swapping buffers on Windows (default: auto). It
8276 also sets \fBSwapInterval(0)\fP to ignore the OpenGL timing. Values are: no
8277 (disabled), windowed (only in windowed mode), yes (also in full screen).
8278 .sp
8279 The value \fBauto\fP will try to determine whether the compositor is active,
8280 and calls \fBDwmFlush\fP only if it seems to be.
8281 .sp
8282 This may help to get more consistent frame intervals, especially with
8283 high\-fps clips \- which might also reduce dropped frames. Typically, a value
8284 of \fBwindowed\fP should be enough, since full screen may bypass the DWM.
8285 .sp
8286 Windows only.
8287 .TP
8288 .B \fB\-\-angle\-d3d11\-feature\-level=<11_0|10_1|10_0|9_3>\fP
8289 Selects a specific feature level when using the ANGLE backend with D3D11.
8290 By default, the highest available feature level is used. This option can be
8291 used to select a lower feature level, which is mainly useful for debugging.
8292 Note that OpenGL ES 3.0 is only supported at feature level 10_1 or higher.
8293 Most extended OpenGL features will not work at lower feature levels
8294 (similar to \fB\-\-gpu\-dumb\-mode\fP).
8295 .sp
8296 Windows with ANGLE only.
8297 .TP
8298 .B \fB\-\-angle\-d3d11\-warp=<yes|no|auto>\fP
8299 Use WARP (Windows Advanced Rasterization Platform) when using the ANGLE
8300 backend with D3D11 (default: auto). This is a high performance software
8301 renderer. By default, it is used when the Direct3D hardware does not
8302 support Direct3D 11 feature level 9_3. While the extended OpenGL features
8303 will work with WARP, they can be very slow.
8304 .sp
8305 Windows with ANGLE only.
8306 .TP
8307 .B \fB\-\-angle\-egl\-windowing=<yes|no|auto>\fP
8308 Use ANGLE\(aqs built in EGL windowing functions to create a swap chain
8309 (default: auto). If this is set to \fBno\fP and the D3D11 renderer is in use,
8310 ANGLE\(aqs built in swap chain will not be used and a custom swap chain that
8311 is optimized for video rendering will be created instead. If set to
8312 \fBauto\fP, a custom swap chain will be used for D3D11 and the built in swap
8313 chain will be used for D3D9. This option is mainly for debugging purposes,
8314 in case the custom swap chain has poor performance or does not work.
8315 .sp
8316 If set to \fByes\fP, the \fB\-\-angle\-max\-frame\-latency\fP,
8317 \fB\-\-angle\-swapchain\-length\fP and \fB\-\-angle\-flip\fP options will have no
8318 effect.
8319 .sp
8320 Windows with ANGLE only.
8321 .TP
8322 .B \fB\-\-angle\-flip=<yes|no>\fP
8323 Enable flip\-model presentation, which avoids unnecessarily copying the
8324 backbuffer by sharing surfaces with the DWM (default: yes). This may cause
8325 performance issues with older drivers. If flip\-model presentation is not
8326 supported (for example, on Windows 7 without the platform update), mpv will
8327 automatically fall back to the older bitblt presentation model.
8328 .sp
8329 If set to \fBno\fP, the \fB\-\-angle\-swapchain\-length\fP option will have no
8330 effect.
8331 .sp
8332 Windows with ANGLE only.
8333 .TP
8334 .B \fB\-\-angle\-renderer=<d3d9|d3d11|auto>\fP
8335 Forces a specific renderer when using the ANGLE backend (default: auto). In
8336 auto mode this will pick D3D11 for systems that support Direct3D 11 feature
8337 level 9_3 or higher, and D3D9 otherwise. This option is mainly for
8338 debugging purposes. Normally there is no reason to force a specific
8339 renderer, though \fB\-\-angle\-renderer=d3d9\fP may give slightly better
8340 performance on old hardware. Note that the D3D9 renderer only supports
8341 OpenGL ES 2.0, so most extended OpenGL features will not work if this
8342 renderer is selected (similar to \fB\-\-gpu\-dumb\-mode\fP).
8343 .sp
8344 Windows with ANGLE only.
8345 .TP
8346 .B \fB\-\-macos\-force\-dedicated\-gpu=<yes|no>\fP
8347 Deactivates the automatic graphics switching and forces the dedicated GPU.
8348 (default: no)
8349 .sp
8350 OS X only.
8351 .TP
8352 .B \fB\-\-cocoa\-cb\-sw\-renderer=<yes|no|auto>\fP
8353 Use the Apple Software Renderer when using cocoa\-cb (default: auto). If set
8354 to \fBno\fP the software renderer is never used and instead fails when a the
8355 usual pixel format could not be created, \fByes\fP will always only use the
8356 software renderer, and \fBauto\fP only falls back to the software renderer
8357 when the usual pixel format couldn\(aqt be created.
8358 .sp
8359 OS X only.
8360 .TP
8361 .B \fB\-\-cocoa\-cb\-10bit\-context=<yes|no>\fP
8362 Creates a 10bit capable pixel format for the context creation (default: yes).
8363 Instead of 8bit integer framebuffer a 16bit half\-float framebuffer is
8364 requested.
8365 .sp
8366 OS X only.
8367 .TP
8368 .B \fB\-\-macos\-title\-bar\-appearance=<appearance>\fP
8369 Sets the appearance of the title bar (default: auto). Not all combinations
8370 of appearances and \fB\-\-macos\-title\-bar\-material\fP materials make sense or
8371 are unique. Appearances that are not supported by you current macOS version
8372 fall back to the default value.
8373 macOS and cocoa\-cb only
8374 .sp
8375 \fB<appearance>\fP can be one of the following:
8376 .INDENT 7.0
8377 .TP
8378 .B auto
8379 Detects the system settings and sets the title
8380 bar appearance appropriately. On macOS 10.14 it
8381 also detects run time changes.
8382 .TP
8383 .B aqua
8384 The standard macOS Light appearance.
8385 .TP
8386 .B darkAqua
8387 The standard macOS Dark appearance. (macOS 10.14+)
8388 .TP
8389 .B vibrantLight
8390 Light vibrancy appearance with.
8391 .TP
8392 .B vibrantDark
8393 Dark vibrancy appearance with.
8394 .TP
8395 .B aquaHighContrast
8396 Light Accessibility appearance. (macOS 10.14+)
8397 .TP
8398 .B darkAquaHighContrast
8399 Dark Accessibility appearance. (macOS 10.14+)
8400 .TP
8401 .B vibrantLightHighContrast
8402 Light vibrancy Accessibility appearance.
8403 (macOS 10.14+)
8404 .TP
8405 .B vibrantDarkHighContrast
8406 Dark vibrancy Accessibility appearance.
8407 (macOS 10.14+)
8408 .UNINDENT
8409 .TP
8410 .B \fB\-\-macos\-title\-bar\-material=<material>\fP
8411 Sets the material of the title bar (default: titlebar). All deprecated
8412 materials should not be used on macOS 10.14+ because their functionality
8413 is not guaranteed. Not all combinations of materials and
8414 \fB\-\-macos\-title\-bar\-appearance\fP appearances make sense or are unique.
8415 Materials that are not supported by you current macOS version fall back to
8416 the default value.
8417 macOS and cocoa\-cb only
8418 .sp
8419 \fB<material>\fP can be one of the following:
8420 .INDENT 7.0
8421 .TP
8422 .B titlebar
8423 The standard macOS titel bar material.
8424 .TP
8425 .B selection
8426 The standard macOS selection material.
8427 .TP
8428 .B menu
8429 The standard macOS menu material. (macOS 10.11+)
8430 .TP
8431 .B popover
8432 The standard macOS popover material. (macOS 10.11+)
8433 .TP
8434 .B sidebar
8435 The standard macOS sidebar material. (macOS 10.11+)
8436 .TP
8437 .B headerView
8438 The standard macOS header view material.
8439 (macOS 10.14+)
8440 .TP
8441 .B sheet
8442 The standard macOS sheet material. (macOS 10.14+)
8443 .TP
8444 .B windowBackground
8445 The standard macOS window background material.
8446 (macOS 10.14+)
8447 .TP
8448 .B hudWindow
8449 The standard macOS hudWindow material. (macOS 10.14+)
8450 .TP
8451 .B fullScreen
8452 The standard macOS full screen material.
8453 (macOS 10.14+)
8454 .TP
8455 .B toolTip
8456 The standard macOS tool tip material. (macOS 10.14+)
8457 .TP
8458 .B contentBackground
8459 The standard macOS content background material.
8460 (macOS 10.14+)
8461 .TP
8462 .B underWindowBackground
8463 The standard macOS under window background material.
8464 (macOS 10.14+)
8465 .TP
8466 .B underPageBackground
8467 The standard macOS under page background material.
8468 (deprecated in macOS 10.14+)
8469 .TP
8470 .B dark
8471 The standard macOS dark material.
8472 (deprecated in macOS 10.14+)
8473 .TP
8474 .B light
8475 The standard macOS light material.
8476 (macOS 10.14+)
8477 .TP
8478 .B mediumLight
8479 The standard macOS mediumLight material.
8480 (macOS 10.11+, deprecated in macOS 10.14+)
8481 .TP
8482 .B ultraDark
8483 The standard macOS ultraDark material.
8484 (macOS 10.11+ deprecated in macOS 10.14+)
8485 .UNINDENT
8486 .TP
8487 .B \fB\-\-macos\-title\-bar\-color=<color>\fP
8488 Sets the color of the title bar (default: completely transparent). Is
8489 influenced by \fB\-\-macos\-title\-bar\-appearance\fP and
8490 \fB\-\-macos\-title\-bar\-material\fP\&.
8491 See \fB\-\-sub\-color\fP for color syntax.
8492 .TP
8493 .B \fB\-\-macos\-fs\-animation\-duration=<default|0\-1000>\fP
8494 Sets the fullscreen resize animation duration in ms (default: default).
8495 The default value is slightly less than the system\(aqs animation duration
8496 (500ms) to prevent some problems when the end of an async animation happens
8497 at the same time as the end of the system wide fullscreen animation. Setting
8498 anything higher than 500ms will only prematurely cancel the resize animation
8499 after the system wide animation ended. The upper limit is still set at
8500 1000ms since it\(aqs possible that Apple or the user changes the system
8501 defaults. Anything higher than 1000ms though seems too long and shouldn\(aqt be
8502 set anyway.
8503 OS X and cocoa\-cb only
8504 .TP
8505 .B \fB\-\-macos\-app\-activation\-policy=<regular|accessory|prohibited>\fP
8506 Changes the App activation policy. With accessory the mpv icon in the Dock
8507 can be hidden. (default: regular)
8508 .sp
8509 macOS only.
8510 .TP
8511 .B \fB\-\-android\-surface\-size=<WxH>\fP
8512 Set dimensions of the rendering surface used by the Android gpu context.
8513 Needs to be set by the embedding application if the dimensions change during
8514 runtime (i.e. if the device is rotated), via the surfaceChanged callback.
8515 .sp
8516 Android with \fB\-\-gpu\-context=android\fP only.
8517 .TP
8518 .B \fB\-\-gpu\-sw\fP
8519 Continue even if a software renderer is detected.
8520 .TP
8521 .B \fB\-\-gpu\-context=<sys>\fP
8522 The value \fBauto\fP (the default) selects the GPU context. You can also pass
8523 \fBhelp\fP to get a complete list of compiled in backends (sorted by
8524 autoprobe order).
8525 .INDENT 7.0
8526 .TP
8527 .B auto
8528 auto\-select (default)
8529 .TP
8530 .B cocoa
8531 Cocoa/OS X (deprecated, use \-\-vo=libmpv instead)
8532 .TP
8533 .B win
8534 Win32/WGL
8535 .TP
8536 .B winvk
8537 VK_KHR_win32_surface
8538 .TP
8539 .B angle
8540 Direct3D11 through the OpenGL ES translation layer ANGLE. This supports
8541 almost everything the \fBwin\fP backend does (if the ANGLE build is new
8542 enough).
8543 .TP
8544 .B dxinterop (experimental)
8545 Win32, using WGL for rendering and Direct3D 9Ex for presentation. Works
8546 on Nvidia and AMD. Newer Intel chips with the latest drivers may also
8547 work.
8548 .TP
8549 .B d3d11
8550 Win32, with native Direct3D 11 rendering.
8551 .TP
8552 .B x11
8553 X11/GLX
8554 .TP
8555 .B x11vk
8556 VK_KHR_xlib_surface
8557 .TP
8558 .B wayland
8559 Wayland/EGL
8560 .TP
8561 .B waylandvk
8562 VK_KHR_wayland_surface
8563 .TP
8564 .B drm
8565 DRM/EGL
8566 .TP
8567 .B x11egl
8568 X11/EGL
8569 .TP
8570 .B android
8571 Android/EGL. Requires \fB\-\-wid\fP be set to an \fBandroid.view.Surface\fP\&.
8572 .UNINDENT
8573 .TP
8574 .B \fB\-\-gpu\-api=<type>\fP
8575 Controls which type of graphics APIs will be accepted:
8576 .INDENT 7.0
8577 .TP
8578 .B auto
8579 Use any available API (default)
8580 .TP
8581 .B opengl
8582 Allow only OpenGL (requires OpenGL 2.1+ or GLES 2.0+)
8583 .TP
8584 .B vulkan
8585 Allow only Vulkan (requires a valid/working \fB\-\-spirv\-compiler\fP)
8586 .TP
8587 .B d3d11
8588 Allow only \fB\-\-gpu\-context=d3d11\fP
8589 .UNINDENT
8590 .TP
8591 .B \fB\-\-opengl\-es=<mode>\fP
8592 Controls which type of OpenGL context will be accepted:
8593 .INDENT 7.0
8594 .TP
8595 .B auto
8596 Allow all types of OpenGL (default)
8597 .TP
8598 .B yes
8599 Only allow GLES
8600 .TP
8601 .B no
8602 Only allow desktop/core GL
8603 .UNINDENT
8604 .TP
8605 .B \fB\-\-opengl\-restrict=<version>\fP
8606 Restricts all OpenGL versions above a certain version. Versions are encoded
8607 in hundreds, i.e. OpenGL 4.5 \-> 450. As an example, \-\-opengl\-restrict=300
8608 would restrict OpenGL 3.0 and higher, effectively only allowing 2.x
8609 contexts. Note that this only imposes a limit on context creation APIs, the
8610 actual OpenGL context may still have a higher OpenGL version. (Default: 0)
8611 .TP
8612 .B \fB\-\-fbo\-format=<fmt>\fP
8613 Selects the internal format of textures used for FBOs. The format can
8614 influence performance and quality of the video output. \fBfmt\fP can be one
8615 of: rgb8, rgb10, rgb10_a2, rgb16, rgb16f, rgb32f, rgba12, rgba16, rgba16f,
8616 rgba16hf, rgba32f.
8617 .sp
8618 Default: \fBauto\fP, which first attempts to utilize 16bit float
8619 (rgba16f, rgba16hf), and falls back to rgba16 if those are not available.
8620 Finally, attempts to utilize rgb10_a2 or rgba8 if all of the previous formats
8621 are not available.
8622 .TP
8623 .B \fB\-\-gamma\-factor=<0.1..2.0>\fP
8624 Set an additional raw gamma factor (default: 1.0). If gamma is adjusted in
8625 other ways (like with the \fB\-\-gamma\fP option or key bindings and the
8626 \fBgamma\fP property), the value is multiplied with the other gamma value.
8627 .sp
8628 Recommended values based on the environmental brightness:
8629 .INDENT 7.0
8630 .TP
8631 .B 1.0
8632 Pitch black or dimly lit room (default)
8633 .TP
8634 .B 1.1
8635 Moderately lit room, home
8636 .TP
8637 .B 1.2
8638 Brightly illuminated room, office
8639 .UNINDENT
8640 .sp
8641 NOTE: This is based around the assumptions of typical movie content, which
8642 contains an implicit end\-to\-end of about 0.8 from scene to display. For
8643 bright environments it can be useful to cancel that out.
8644 .TP
8645 .B \fB\-\-gamma\-auto\fP
8646 Automatically corrects the gamma value depending on ambient lighting
8647 conditions (adding a gamma boost for bright rooms).
8648 .sp
8649 With ambient illuminance of 16 lux, mpv will pick the 1.0 gamma value (no
8650 boost), and slightly increase the boost up until 1.2 for 256 lux.
8651 .sp
8652 NOTE: Only implemented on OS X.
8653 .TP
8654 .B \fB\-\-target\-prim=<value>\fP
8655 Specifies the primaries of the display. Video colors will be adapted to
8656 this colorspace when ICC color management is not being used. Valid values
8657 are:
8658 .INDENT 7.0
8659 .TP
8660 .B auto
8661 Disable any adaptation, except for atypical color spaces. Specifically,
8662 wide/unusual gamuts get automatically adapted to BT.709, while standard
8663 gamut (i.e. BT.601 and BT.709) content is not touched. (default)
8664 .TP
8665 .B bt.470m
8666 ITU\-R BT.470 M
8667 .TP
8668 .B bt.601\-525
8669 ITU\-R BT.601 (525\-line SD systems, eg. NTSC), SMPTE 170M/240M
8670 .TP
8671 .B bt.601\-625
8672 ITU\-R BT.601 (625\-line SD systems, eg. PAL/SECAM), ITU\-R BT.470 B/G
8673 .TP
8674 .B bt.709
8675 ITU\-R BT.709 (HD), IEC 61966\-2\-4 (sRGB), SMPTE RP177 Annex B
8676 .TP
8677 .B bt.2020
8678 ITU\-R BT.2020 (UHD)
8679 .TP
8680 .B apple
8681 Apple RGB
8682 .TP
8683 .B adobe
8684 Adobe RGB (1998)
8685 .TP
8686 .B prophoto
8687 ProPhoto RGB (ROMM)
8688 .TP
8689 .B cie1931
8690 CIE 1931 RGB (not to be confused with CIE XYZ)
8691 .TP
8692 .B dci\-p3
8693 DCI\-P3 (Digital Cinema Colorspace), SMPTE RP431\-2
8694 .TP
8695 .B v\-gamut
8696 Panasonic V\-Gamut (VARICAM) primaries
8697 .TP
8698 .B s\-gamut
8699 Sony S\-Gamut (S\-Log) primaries
8700 .UNINDENT
8701 .TP
8702 .B \fB\-\-target\-trc=<value>\fP
8703 Specifies the transfer characteristics (gamma) of the display. Video colors
8704 will be adjusted to this curve when ICC color management is not being used.
8705 Valid values are:
8706 .INDENT 7.0
8707 .TP
8708 .B auto
8709 Disable any adaptation, except for atypical transfers. Specifically,
8710 HDR or linear light source material gets automatically converted to
8711 gamma 2.2, while SDR content is not touched. (default)
8712 .TP
8713 .B bt.1886
8714 ITU\-R BT.1886 curve (assuming infinite contrast)
8715 .TP
8716 .B srgb
8717 IEC 61966\-2\-4 (sRGB)
8718 .TP
8719 .B linear
8720 Linear light output
8721 .TP
8722 .B gamma1.8
8723 Pure power curve (gamma 1.8), also used for Apple RGB
8724 .TP
8725 .B gamma2.0
8726 Pure power curve (gamma 2.0)
8727 .TP
8728 .B gamma2.2
8729 Pure power curve (gamma 2.2)
8730 .TP
8731 .B gamma2.4
8732 Pure power curve (gamma 2.4)
8733 .TP
8734 .B gamma2.6
8735 Pure power curve (gamma 2.6)
8736 .TP
8737 .B gamma2.8
8738 Pure power curve (gamma 2.8), also used for BT.470\-BG
8739 .TP
8740 .B prophoto
8741 ProPhoto RGB (ROMM)
8742 .TP
8743 .B pq
8744 ITU\-R BT.2100 PQ (Perceptual quantizer) curve, aka SMPTE ST2084
8745 .TP
8746 .B hlg
8747 ITU\-R BT.2100 HLG (Hybrid Log\-gamma) curve, aka ARIB STD\-B67
8748 .TP
8749 .B v\-log
8750 Panasonic V\-Log (VARICAM) curve
8751 .TP
8752 .B s\-log1
8753 Sony S\-Log1 curve
8754 .TP
8755 .B s\-log2
8756 Sony S\-Log2 curve
8757 .UNINDENT
8758 .sp
8759 \fBNOTE:\fP
8760 .INDENT 7.0
8761 .INDENT 3.5
8762 When using HDR output formats, mpv will encode to the specified
8763 curve but it will not set any HDMI flags or other signalling that might
8764 be required for the target device to correctly display the HDR signal.
8765 The user should independently guarantee this before using these signal
8766 formats for display.
8767 .UNINDENT
8768 .UNINDENT
8769 .TP
8770 .B \fB\-\-target\-peak=<auto|nits>\fP
8771 Specifies the measured peak brightness of the output display, in cd/m^2
8772 (AKA nits). The interpretation of this brightness depends on the configured
8773 \fB\-\-target\-trc\fP\&. In all cases, it imposes a limit on the signal values
8774 that will be sent to the display. If the source exceeds this brightness
8775 level, a tone mapping filter will be inserted. For HLG, it has the
8776 additional effect of parametrizing the inverse OOTF, in order to get
8777 colorimetrically consistent results with the mastering display. For SDR, or
8778 when using an ICC (profile (\fB\-\-icc\-profile\fP), setting this to a value
8779 above 203 essentially causes the display to be treated as if it were an HDR
8780 display in disguise. (See the note below)
8781 .sp
8782 In \fBauto\fP mode (the default), the chosen peak is an appropriate value
8783 based on the TRC in use. For SDR curves, it uses 203. For HDR curves, it
8784 uses 203 * the transfer function\(aqs nominal peak.
8785 .sp
8786 \fBNOTE:\fP
8787 .INDENT 7.0
8788 .INDENT 3.5
8789 When using an SDR transfer function, this is normally not needed, and
8790 setting it may lead to very unexpected results. The one time it \fIis\fP
8791 useful is if you want to calibrate a HDR display using traditional
8792 transfer functions and calibration equipment. In such cases, you can
8793 set your HDR display to a high brightness such as 800 cd/m^2, and then
8794 calibrate it to a standard curve like gamma2.8. Setting this value to
8795 800 would then instruct mpv to essentially treat it as an HDR display
8796 with the given peak. This may be a good alternative in environments
8797 where PQ or HLG input to the display is not possible, and makes it
8798 possible to use HDR displays with mpv regardless of operating system
8799 support for HDMI HDR metadata.
8800 .sp
8801 In such a configuration, we highly recommend setting \fB\-\-tone\-mapping\fP
8802 to \fBmobius\fP or even \fBclip\fP\&.
8803 .UNINDENT
8804 .UNINDENT
8805 .TP
8806 .B \fB\-\-tone\-mapping=<value>\fP
8807 Specifies the algorithm used for tone\-mapping images onto the target
8808 display. This is relevant for both HDR\->SDR conversion as well as gamut
8809 reduction (e.g. playing back BT.2020 content on a standard gamut display).
8810 Valid values are:
8811 .INDENT 7.0
8812 .TP
8813 .B clip
8814 Hard\-clip any out\-of\-range values. Use this when you care about
8815 perfect color accuracy for in\-range values at the cost of completely
8816 distorting out\-of\-range values. Not generally recommended.
8817 .TP
8818 .B mobius
8819 Generalization of Reinhard to a Möbius transform with linear section.
8820 Smoothly maps out\-of\-range values while retaining contrast and colors
8821 for in\-range material as much as possible. Use this when you care about
8822 color accuracy more than detail preservation. This is somewhere in
8823 between \fBclip\fP and \fBreinhard\fP, depending on the value of
8824 \fB\-\-tone\-mapping\-param\fP\&.
8825 .TP
8826 .B reinhard
8827 Reinhard tone mapping algorithm. Very simple continuous curve.
8828 Preserves overall image brightness but uses nonlinear contrast, which
8829 results in flattening of details and degradation in color accuracy.
8830 .TP
8831 .B hable
8832 Similar to \fBreinhard\fP but preserves both dark and bright details
8833 better (slightly sigmoidal), at the cost of slightly darkening /
8834 desaturating everything. Developed by John Hable for use in video
8835 games. Use this when you care about detail preservation more than
8836 color/brightness accuracy. This is roughly equivalent to
8837 \fB\-\-tone\-mapping=reinhard \-\-tone\-mapping\-param=0.24\fP\&. If possible,
8838 you should also enable \fB\-\-hdr\-compute\-peak\fP for the best results.
8839 .TP
8840 .B bt.2390
8841 Perceptual tone mapping curve (EETF) specified in ITU\-R Report BT.2390.
8842 This is the recommended curve to use for typical HDR\-mastered content.
8843 (Default)
8844 .TP
8845 .B gamma
8846 Fits a logarithmic transfer between the tone curves.
8847 .TP
8848 .B linear
8849 Linearly stretches the entire reference gamut to (a linear multiple of)
8850 the display.
8851 .UNINDENT
8852 .TP
8853 .B \fB\-\-tone\-mapping\-param=<value>\fP
8854 Set tone mapping parameters. By default, this is set to the special string
8855 \fBdefault\fP, which maps to an algorithm\-specific default value. Ignored if
8856 the tone mapping algorithm is not tunable. This affects the following tone
8857 mapping algorithms:
8858 .INDENT 7.0
8859 .TP
8860 .B clip
8861 Specifies an extra linear coefficient to multiply into the signal
8862 before clipping. Defaults to 1.0.
8863 .TP
8864 .B mobius
8865 Specifies the transition point from linear to mobius transform. Every
8866 value below this point is guaranteed to be mapped 1:1. The higher the
8867 value, the more accurate the result will be, at the cost of losing
8868 bright details. Defaults to 0.3, which due to the steep initial slope
8869 still preserves in\-range colors fairly accurately.
8870 .TP
8871 .B reinhard
8872 Specifies the local contrast coefficient at the display peak. Defaults
8873 to 0.5, which means that in\-gamut values will be about half as bright
8874 as when clipping.
8875 .TP
8876 .B gamma
8877 Specifies the exponent of the function. Defaults to 1.8.
8878 .TP
8879 .B linear
8880 Specifies the scale factor to use while stretching. Defaults to 1.0.
8881 .UNINDENT
8882 .TP
8883 .B \fB\-\-tone\-mapping\-max\-boost=<1.0..10.0>\fP
8884 Upper limit for how much the tone mapping algorithm is allowed to boost
8885 the average brightness by over\-exposing the image. The default value of 1.0
8886 allows no additional brightness boost. A value of 2.0 would allow
8887 over\-exposing by a factor of 2, and so on. Raising this setting can help
8888 reveal details that would otherwise be hidden in dark scenes, but raising
8889 it too high will make dark scenes appear unnaturally bright.
8890 .TP
8891 .B \fB\-\-hdr\-compute\-peak=<auto|yes|no>\fP
8892 Compute the HDR peak and frame average brightness per\-frame instead of
8893 relying on tagged metadata. These values are averaged over local regions as
8894 well as over several frames to prevent the value from jittering around too
8895 much. This option basically gives you dynamic, per\-scene tone mapping.
8896 Requires compute shaders, which is a fairly recent OpenGL feature, and will
8897 probably also perform horribly on some drivers, so enable at your own risk.
8898 The special value \fBauto\fP (default) will enable HDR peak computation
8899 automatically if compute shaders and SSBOs are supported.
8900 .TP
8901 .B \fB\-\-hdr\-peak\-decay\-rate=<1.0..1000.0>\fP
8902 The decay rate used for the HDR peak detection algorithm (default: 100.0).
8903 This is only relevant when \fB\-\-hdr\-compute\-peak\fP is enabled. Higher values
8904 make the peak decay more slowly, leading to more stable values at the cost
8905 of more "eye adaptation"\-like effects (although this is mitigated somewhat
8906 by \fB\-\-hdr\-scene\-threshold\fP). A value of 1.0 (the lowest possible) disables
8907 all averaging, meaning each frame\(aqs value is used directly as measured,
8908 but doing this is not recommended for "noisy" sources since it may lead
8909 to excessive flicker. (In signal theory terms, this controls the time
8910 constant "tau" of an IIR low pass filter)
8911 .TP
8912 .B \fB\-\-hdr\-scene\-threshold\-low=<0.0..100.0>\fP, \fB\-\-hdr\-scene\-threshold\-high=<0.0..100.0>\fP
8913 The lower and upper thresholds (in dB) for a brightness difference
8914 to be considered a scene change (default: 5.5 low, 10.0 high). This is only
8915 relevant when \fB\-\-hdr\-compute\-peak\fP is enabled. Normally, small
8916 fluctuations in the frame brightness are compensated for by the peak
8917 averaging mechanism, but for large jumps in the brightness this can result
8918 in the frame remaining too bright or too dark for up to several seconds,
8919 depending on the value of \fB\-\-hdr\-peak\-decay\-rate\fP\&. To counteract this,
8920 when the brightness between the running average and the current frame
8921 exceeds the low threshold, mpv will make the averaging filter more
8922 aggressive, up to the limit of the high threshold (at which point the
8923 filter becomes instant).
8924 .TP
8925 .B \fB\-\-tone\-mapping\-desaturate=<0.0..1.0>\fP
8926 Apply desaturation for highlights (default: 0.75). The parameter controls
8927 the strength of the desaturation curve. A value of 0.0 completely disables
8928 it, while a value of 1.0 means that overly bright colors will tend towards
8929 white. (This is not always the case, especially not for highlights that are
8930 near primary colors)
8931 .sp
8932 Values in between apply progressively more/less aggressive desaturation.
8933 This setting helps prevent unnaturally oversaturated colors for
8934 super\-highlights, by (smoothly) turning them into less saturated (per
8935 channel tone mapped) colors instead. This makes images feel more natural,
8936 at the cost of chromatic distortions for out\-of\-range colors. The default
8937 value of 0.75 provides a good balance. Setting this to 0.0 preserves the
8938 chromatic accuracy of the tone mapping process.
8939 .TP
8940 .B \fB\-\-tone\-mapping\-desaturate\-exponent=<0.0..20.0>\fP
8941 This setting controls the exponent of the desaturation curve, which
8942 controls how bright a color needs to be in order to start being
8943 desaturated. The default of 1.5 provides a reasonable balance. Decreasing
8944 this exponent makes the curve more aggressive.
8945 .TP
8946 .B \fB\-\-gamut\-warning\fP
8947 If enabled, mpv will mark all clipped/out\-of\-gamut pixels that exceed a
8948 given threshold (currently hard\-coded to 101%). The affected pixels will be
8949 inverted to make them stand out. Note: This option applies after the
8950 effects of all of mpv\(aqs color space transformation / tone mapping options,
8951 so it\(aqs a good idea to combine this with \fB\-\-tone\-mapping=clip\fP and use
8952 \fB\-\-target\-prim\fP to set the gamut to simulate. For example,
8953 \fB\-\-target\-prim=bt.709\fP would make mpv highlight all pixels that exceed the
8954 gamut of a standard gamut (sRGB) display. This option also does not work
8955 well with ICC profiles, since the 3DLUTs are always generated against the
8956 source color space and have chromatically\-accurate clipping built in.
8957 .TP
8958 .B \fB\-\-gamut\-clipping\fP
8959 If enabled (default: yes), mpv will colorimetrically clip out\-of\-gamut
8960 colors by desaturating them (preserving luma), rather than hard\-clipping
8961 each component individually. This should make playback of wide gamut
8962 content on typical (standard gamut) monitors look much more aesthetically
8963 pleasing and less blown\-out.
8964 .TP
8965 .B \fB\-\-use\-embedded\-icc\-profile\fP
8966 Load the embedded ICC profile contained in media files such as PNG images.
8967 (Default: yes). Note that this option only works when also using a display
8968 ICC profile (\fB\-\-icc\-profile\fP or \fB\-\-icc\-profile\-auto\fP), and also
8969 requires LittleCMS 2 support.
8970 .TP
8971 .B \fB\-\-icc\-profile=<file>\fP
8972 Load an ICC profile and use it to transform video RGB to screen output.
8973 Needs LittleCMS 2 support compiled in. This option overrides the
8974 \fB\-\-target\-prim\fP, \fB\-\-target\-trc\fP and \fB\-\-icc\-profile\-auto\fP options.
8975 .TP
8976 .B \fB\-\-icc\-profile\-auto\fP
8977 Automatically select the ICC display profile currently specified by the
8978 display settings of the operating system.
8979 .sp
8980 NOTE: On Windows, the default profile must be an ICC profile. WCS profiles
8981 are not supported.
8982 .sp
8983 Applications using libmpv with the render API need to provide the ICC
8984 profile via \fBMPV_RENDER_PARAM_ICC_PROFILE\fP\&.
8985 .TP
8986 .B \fB\-\-icc\-cache\-dir=<dirname>\fP
8987 Store and load the 3D LUTs created from the ICC profile in this directory.
8988 This can be used to speed up loading, since LittleCMS 2 can take a while to
8989 create a 3D LUT. Note that these files contain uncompressed LUTs. Their
8990 size depends on the \fB\-\-icc\-3dlut\-size\fP, and can be very big.
8991 .sp
8992 NOTE: This is not cleaned automatically, so old, unused cache files may
8993 stick around indefinitely.
8994 .TP
8995 .B \fB\-\-icc\-intent=<value>\fP
8996 Specifies the ICC intent used for the color transformation (when using
8997 \fB\-\-icc\-profile\fP).
8998 .INDENT 7.0
8999 .TP
9000 .B 0
9001 perceptual
9002 .TP
9003 .B 1
9004 relative colorimetric (default)
9005 .TP
9006 .B 2
9007 saturation
9008 .TP
9009 .B 3
9010 absolute colorimetric
9011 .UNINDENT
9012 .TP
9013 .B \fB\-\-icc\-3dlut\-size=<r>x<g>x<b>\fP
9014 Size of the 3D LUT generated from the ICC profile in each dimension.
9015 Default is 64x64x64. Sizes may range from 2 to 512.
9016 .TP
9017 .B \fB\-\-icc\-contrast=<0\-1000000|inf>\fP
9018 Specifies an upper limit on the target device\(aqs contrast ratio. This is
9019 detected automatically from the profile if possible, but for some profiles
9020 it might be missing, causing the contrast to be assumed as infinite. As a
9021 result, video may appear darker than intended. This only affects BT.1886
9022 content. The default of 0 means no limit if the detected contrast is less
9023 than 100000, and limits to 1000 otherwise. Use \fB\-\-icc\-contrast=inf\fP to
9024 preserve the infinite contrast (most likely when using OLED displays).
9025 .TP
9026 .B \fB\-\-blend\-subtitles=<yes|video|no>\fP
9027 Blend subtitles directly onto upscaled video frames, before interpolation
9028 and/or color management (default: no). Enabling this causes subtitles to be
9029 affected by \fB\-\-icc\-profile\fP, \fB\-\-target\-prim\fP, \fB\-\-target\-trc\fP,
9030 \fB\-\-interpolation\fP, \fB\-\-gamma\-factor\fP and \fB\-\-glsl\-shaders\fP\&. It also
9031 increases subtitle performance when using \fB\-\-interpolation\fP\&.
9032 .sp
9033 The downside of enabling this is that it restricts subtitles to the visible
9034 portion of the video, so you can\(aqt have subtitles exist in the black
9035 margins below a video (for example).
9036 .sp
9037 If \fBvideo\fP is selected, the behavior is similar to \fByes\fP, but subs are
9038 drawn at the video\(aqs native resolution, and scaled along with the video.
9039 .sp
9040 \fBWARNING:\fP
9041 .INDENT 7.0
9042 .INDENT 3.5
9043 This changes the way subtitle colors are handled. Normally,
9044 subtitle colors are assumed to be in sRGB and color managed as
9045 such. Enabling this makes them treated as being in the video\(aqs
9046 color space instead. This is good if you want things like
9047 softsubbed ASS signs to match the video colors, but may cause
9048 SRT subtitles or similar to look slightly off.
9049 .UNINDENT
9050 .UNINDENT
9051 .TP
9052 .B \fB\-\-alpha=<blend\-tiles|blend|yes|no>\fP
9053 Decides what to do if the input has an alpha component.
9054 .INDENT 7.0
9055 .TP
9056 .B blend\-tiles
9057 Blend the frame against a 16x16 gray/white tiles background (default).
9058 .TP
9059 .B blend
9060 Blend the frame against the background color (\fB\-\-background\fP, normally
9061 black).
9062 .TP
9063 .B yes
9064 Try to create a framebuffer with alpha component. This only makes sense
9065 if the video contains alpha information (which is extremely rare). May
9066 not be supported on all platforms. If alpha framebuffers are
9067 unavailable, it silently falls back on a normal framebuffer. Note that
9068 if you set the \fB\-\-fbo\-format\fP option to a non\-default value, a
9069 format with alpha must be specified, or this won\(aqt work.
9070 Whether this really works depends on the windowing system and desktop
9071 environment.
9072 .TP
9073 .B no
9074 Ignore alpha component.
9075 .UNINDENT
9076 .TP
9077 .B \fB\-\-opengl\-rectangle\-textures\fP
9078 Force use of rectangle textures (default: no). Normally this shouldn\(aqt have
9079 any advantages over normal textures. Note that hardware decoding overrides
9080 this flag. Could be removed any time.
9081 .TP
9082 .B \fB\-\-background=<color>\fP
9083 Color used to draw parts of the mpv window not covered by video. See the
9084 \fB\-\-sub\-color\fP option for how colors are defined.
9085 .TP
9086 .B \fB\-\-gpu\-tex\-pad\-x\fP, \fB\-\-gpu\-tex\-pad\-y\fP
9087 Enlarge the video source textures by this many pixels. For debugging only
9088 (normally textures are sized exactly, but due to hardware decoding interop
9089 we may have to deal with additional padding, which can be tested with these
9090 options). Could be removed any time.
9091 .TP
9092 .B \fB\-\-opengl\-early\-flush=<yes|no|auto>\fP
9093 Call \fBglFlush()\fP after rendering a frame and before attempting to display
9094 it (default: auto). Can fix stuttering in some cases, in other cases
9095 probably causes it. The \fBauto\fP mode will call \fBglFlush()\fP only if
9096 the renderer is going to wait for a while after rendering, instead of
9097 flipping GL front and backbuffers immediately (i.e. it doesn\(aqt call it
9098 in display\-sync mode).
9099 .sp
9100 On OSX this is always deactivated because it only causes performance
9101 problems and other regressions.
9102 .TP
9103 .B \fB\-\-gpu\-dumb\-mode=<yes|no|auto>\fP
9104 This mode is extremely restricted, and will disable most extended
9105 features. That includes high quality scalers and custom shaders!
9106 .sp
9107 It is intended for hardware that does not support FBOs (including GLES,
9108 which supports it insufficiently), or to get some more performance out of
9109 bad or old hardware.
9110 .sp
9111 This mode is forced automatically if needed, and this option is mostly
9112 useful for debugging. The default of \fBauto\fP will enable it automatically
9113 if nothing uses features which require FBOs.
9114 .sp
9115 This option might be silently removed in the future.
9116 .TP
9117 .B \fB\-\-gpu\-shader\-cache\-dir=<dirname>\fP
9118 Store and load compiled GLSL shaders in this directory. Normally, shader
9119 compilation is very fast, so this is usually not needed. It mostly matters
9120 for GPU APIs that require internally recompiling shaders to other languages,
9121 for example anything based on ANGLE or Vulkan. Enabling this can improve
9122 startup performance on these platforms.
9123 .sp
9124 NOTE: This is not cleaned automatically, so old, unused cache files may
9125 stick around indefinitely.
9126 .UNINDENT
9127 .SS Miscellaneous
9128 .INDENT 0.0
9129 .TP
9130 .B \fB\-\-display\-tags=tag1,tags2,...\fP
9131 Set the list of tags that should be displayed on the terminal. Tags that
9132 are in the list, but are not present in the played file, will not be shown.
9133 If a value ends with \fB*\fP, all tags are matched by prefix (though there
9134 is no general globbing). Just passing \fB*\fP essentially filtering.
9135 .sp
9136 The default includes a common list of tags, call mpv with \fB\-\-list\-options\fP
9137 to see it.
9138 .sp
9139 This is a string list option. See \fI\%List Options\fP for details.
9140 .TP
9141 .B \fB\-\-mc=<seconds/frame>\fP
9142 Maximum A\-V sync correction per frame (in seconds)
9143 .TP
9144 .B \fB\-\-autosync=<factor>\fP
9145 Gradually adjusts the A/V sync based on audio delay measurements.
9146 Specifying \fB\-\-autosync=0\fP, the default, will cause frame timing to be
9147 based entirely on audio delay measurements. Specifying \fB\-\-autosync=1\fP
9148 will do the same, but will subtly change the A/V correction algorithm. An
9149 uneven video framerate in a video which plays fine with \fB\-\-no\-audio\fP can
9150 often be helped by setting this to an integer value greater than 1. The
9151 higher the value, the closer the timing will be to \fB\-\-no\-audio\fP\&. Try
9152 \fB\-\-autosync=30\fP to smooth out problems with sound drivers which do not
9153 implement a perfect audio delay measurement. With this value, if large A/V
9154 sync offsets occur, they will only take about 1 or 2 seconds to settle
9155 out. This delay in reaction time to sudden A/V offsets should be the only
9156 side effect of turning this option on, for all sound drivers.
9157 .TP
9158 .B \fB\-\-video\-timing\-offset=<seconds>\fP
9159 Control how long before video display target time the frame should be
9160 rendered (default: 0.050). If a video frame should be displayed at a
9161 certain time, the VO will start rendering the frame earlier, and then will
9162 perform a blocking wait until the display time, and only then "swap" the
9163 frame to display. The rendering cannot start before the previous frame is
9164 displayed, so this value is implicitly limited by the video framerate. With
9165 normal video frame rates, the default value will ensure that rendering is
9166 always immediately started after the previous frame was displayed. On the
9167 other hand, setting a too high value can reduce responsiveness with low
9168 FPS value.
9169 .sp
9170 For client API users using the render API (or the deprecated \fBopengl\-cb\fP
9171 API), this option is interesting, because you can stop the render API
9172 from limiting your FPS (see \fBmpv_render_context_render()\fP documentation).
9173 .sp
9174 This applies only to audio timing modes (e.g. \fB\-\-video\-sync=audio\fP). In
9175 other modes (\fB\-\-video\-sync=display\-...\fP), video timing relies on vsync
9176 blocking, and this option is not used.
9177 .TP
9178 .B \fB\-\-video\-sync=<audio|...>\fP
9179 How the player synchronizes audio and video.
9180 .sp
9181 If you use this option, you usually want to set it to \fBdisplay\-resample\fP
9182 to enable a timing mode that tries to not skip or repeat frames when for
9183 example playing 24fps video on a 24Hz screen.
9184 .sp
9185 The modes starting with \fBdisplay\-\fP try to output video frames completely
9186 synchronously to the display, using the detected display vertical refresh
9187 rate as a hint how fast frames will be displayed on average. These modes
9188 change video speed slightly to match the display. See \fB\-\-video\-sync\-...\fP
9189 options for fine tuning. The robustness of this mode is further reduced by
9190 making a some idealized assumptions, which may not always apply in reality.
9191 Behavior can depend on the VO and the system\(aqs video and audio drivers.
9192 Media files must use constant framerate. Section\-wise VFR might work as well
9193 with some container formats (but not e.g. mkv).
9194 .sp
9195 Under some circumstances, the player automatically reverts to \fBaudio\fP mode
9196 for some time or permanently. This can happen on very low framerate video,
9197 or if the framerate cannot be detected.
9198 .sp
9199 Also in display\-sync modes it can happen that interruptions to video
9200 playback (such as toggling fullscreen mode, or simply resizing the window)
9201 will skip the video frames that should have been displayed, while \fBaudio\fP
9202 mode will display them after the renderer has resumed (typically resulting
9203 in a short A/V desync and the video "catching up").
9204 .sp
9205 Before mpv 0.30.0, there was a fallback to \fBaudio\fP mode on severe A/V
9206 desync. This was changed for the sake of not sporadically stopping. Now,
9207 \fBdisplay\-desync\fP does what it promises and may desync with audio by an
9208 arbitrary amount, until it is manually fixed with a seek.
9209 .sp
9210 These modes also require a vsync blocked presentation mode. For OpenGL, this
9211 translates to \fB\-\-opengl\-swapinterval=1\fP\&. For Vulkan, it translates to
9212 \fB\-\-vulkan\-swap\-mode=fifo\fP (or \fBfifo\-relaxed\fP).
9213 .sp
9214 The modes with \fBdesync\fP in their names do not attempt to keep audio/video
9215 in sync. They will slowly (or quickly) desync, until e.g. the next seek
9216 happens. These modes are meant for testing, not serious use.
9217 .INDENT 7.0
9218 .TP
9219 .B audio
9220 Time video frames to audio. This is the most robust
9221 mode, because the player doesn\(aqt have to assume anything
9222 about how the display behaves. The disadvantage is that
9223 it can lead to occasional frame drops or repeats. If
9224 audio is disabled, this uses the system clock. This is
9225 the default mode.
9226 .TP
9227 .B display\-resample
9228 Resample audio to match the video. This mode will also
9229 try to adjust audio speed to compensate for other drift.
9230 (This means it will play the audio at a different speed
9231 every once in a while to reduce the A/V difference.)
9232 .TP
9233 .B display\-resample\-vdrop
9234 Resample audio to match the video. Drop video
9235 frames to compensate for drift.
9236 .TP
9237 .B display\-resample\-desync
9238 Like the previous mode, but no A/V compensation.
9239 .TP
9240 .B display\-vdrop
9241 Drop or repeat video frames to compensate desyncing
9242 video. (Although it should have the same effects as
9243 \fBaudio\fP, the implementation is very different.)
9244 .TP
9245 .B display\-adrop
9246 Drop or repeat audio data to compensate desyncing
9247 video. See \fB\-\-video\-sync\-adrop\-size\fP\&. This mode will
9248 cause severe audio artifacts if the real monitor
9249 refresh rate is too different from the reported or
9250 forced rate. Since mpv 0.33.0, this acts on entire audio
9251 frames, instead of single samples.
9252 .TP
9253 .B display\-desync
9254 Sync video to display, and let audio play on its own.
9255 .TP
9256 .B desync
9257 Sync video according to system clock, and let audio play
9258 on its own.
9259 .UNINDENT
9260 .TP
9261 .B \fB\-\-video\-sync\-max\-factor=<value>\fP
9262 Maximum multiple for which to try to fit the video\(aqs FPS to the display\(aqs
9263 FPS (default: 5).
9264 .sp
9265 For example, if this is set to 1, the video FPS is forced to an integer
9266 multiple of the display FPS, as long as the speed change does not exceed
9267 the value set by \fB\-\-video\-sync\-max\-video\-change\fP\&.
9268 .sp
9269 This is mostly for testing, and the option may be randomly changed in the
9270 future without notice.
9271 .TP
9272 .B \fB\-\-video\-sync\-max\-video\-change=<value>\fP
9273 Maximum speed difference in percent that is applied to video with
9274 \fB\-\-video\-sync=display\-...\fP (default: 1). Display sync mode will be
9275 disabled if the monitor and video refresh way do not match within the
9276 given range. It tries multiples as well: playing 30 fps video on a 60 Hz
9277 screen will duplicate every second frame. Playing 24 fps video on a 60 Hz
9278 screen will play video in a 2\-3\-2\-3\-... pattern.
9279 .sp
9280 The default settings are not loose enough to speed up 23.976 fps video to
9281 25 fps. We consider the pitch change too extreme to allow this behavior
9282 by default. Set this option to a value of \fB5\fP to enable it.
9283 .sp
9284 Note that in the \fB\-\-video\-sync=display\-resample\fP mode, audio speed will
9285 additionally be changed by a small amount if necessary for A/V sync. See
9286 \fB\-\-video\-sync\-max\-audio\-change\fP\&.
9287 .TP
9288 .B \fB\-\-video\-sync\-max\-audio\-change=<value>\fP
9289 Maximum \fIadditional\fP speed difference in percent that is applied to audio
9290 with \fB\-\-video\-sync=display\-...\fP (default: 0.125). Normally, the player
9291 plays the audio at the speed of the video. But if the difference between
9292 audio and video position is too high, e.g. due to drift or other timing
9293 errors, it will attempt to speed up or slow down audio by this additional
9294 factor. Too low values could lead to video frame dropping or repeating if
9295 the A/V desync cannot be compensated, too high values could lead to chaotic
9296 frame dropping due to the audio "overshooting" and skipping multiple video
9297 frames before the sync logic can react.
9298 .TP
9299 .B \fB\-\-mf\-fps=<value>\fP
9300 Framerate used when decoding from multiple PNG or JPEG files with \fBmf://\fP
9301 (default: 1).
9302 .TP
9303 .B \fB\-\-mf\-type=<value>\fP
9304 Input file type for \fBmf://\fP (available: jpeg, png, tga, sgi). By default,
9305 this is guessed from the file extension.
9306 .TP
9307 .B \fB\-\-stream\-dump=<destination\-filename>\fP
9308 Instead of playing a file, read its byte stream and write it to the given
9309 destination file. The destination is overwritten. Can be useful to test
9310 network\-related behavior.
9311 .TP
9312 .B \fB\-\-stream\-lavf\-o=opt1=value1,opt2=value2,...\fP
9313 Set AVOptions on streams opened with libavformat. Unknown or misspelled
9314 options are silently ignored. (They are mentioned in the terminal output
9315 in verbose mode, i.e. \fB\-\-v\fP\&. In general we can\(aqt print errors, because
9316 other options such as e.g. user agent are not available with all protocols,
9317 and printing errors for unknown options would end up being too noisy.)
9318 .sp
9319 This is a key/value list option. See \fI\%List Options\fP for details.
9320 .TP
9321 .B \fB\-\-vo\-mmcss\-profile=<name>\fP
9322 (Windows only.)
9323 Set the MMCSS profile for the video renderer thread (default: \fBPlayback\fP).
9324 .TP
9325 .B \fB\-\-priority=<prio>\fP
9326 (Windows only.)
9327 Set process priority for mpv according to the predefined priorities
9328 available under Windows.
9329 .sp
9330 Possible values of \fB<prio>\fP:
9331 idle|belownormal|normal|abovenormal|high|realtime
9332 .sp
9333 \fBWARNING:\fP
9334 .INDENT 7.0
9335 .INDENT 3.5
9336 Using realtime priority can cause system lockup.
9337 .UNINDENT
9338 .UNINDENT
9339 .TP
9340 .B \fB\-\-force\-media\-title=<string>\fP
9341 Force the contents of the \fBmedia\-title\fP property to this value. Useful
9342 for scripts which want to set a title, without overriding the user\(aqs
9343 setting in \fB\-\-title\fP\&.
9344 .TP
9345 .B \fB\-\-external\-files=<file\-list>\fP
9346 Load a file and add all of its tracks. This is useful to play different
9347 files together (for example audio from one file, video from another), or
9348 for advanced \fB\-\-lavfi\-complex\fP used (like playing two video files at
9349 the same time).
9350 .sp
9351 Unlike \fB\-\-sub\-files\fP and \fB\-\-audio\-files\fP, this includes all tracks, and
9352 does not cause default stream selection over the "proper" file. This makes
9353 it slightly less intrusive. (In mpv 0.28.0 and before, this was not quite
9354 strictly enforced.)
9355 .sp
9356 This is a path list option. See \fI\%List Options\fP for details.
9357 .TP
9358 .B \fB\-\-external\-file=<file>\fP
9359 CLI/config file only alias for \fB\-\-external\-files\-append\fP\&. Each use of this
9360 option will add a new external file.
9361 .TP
9362 .B \fB\-\-cover\-art\-files=<file\-list>\fP
9363 Use an external file as cover art while playing audio. This makes it appear
9364 on the track list and subject to automatic track selection. Options like
9365 \fB\-\-audio\-display\fP control whether such tracks are supposed to be selected.
9366 .sp
9367 (The difference to loading a file with \fB\-\-external\-files\fP is that video
9368 tracks will be marked as being pictures, which affects the auto\-selection
9369 method. If the passed file is a video, only the first frame will be decoded
9370 and displayed. Enabling the cover art track during playback may show a
9371 random frame if the source file is a video. Normally you\(aqre not supposed to
9372 pass videos to this option, so this paragraph describes the behavior
9373 coincidentally resulting from implementation details.)
9374 .sp
9375 This is a path list option. See \fI\%List Options\fP for details.
9376 .TP
9377 .B \fB\-\-cover\-art\-file=<file>\fP
9378 CLI/config file only alias for \fB\-\-cover\-art\-files\-append\fP\&. Each use of this
9379 option will add a new external file.
9380 .TP
9381 .B \fB\-\-cover\-art\-auto=<no|fuzzy>\fP
9382 Whether to load _external_ cover art automatically (default: fuzzy). Similar
9383 to \fB\-\-sub\-auto\fP and \fB\-\-audio\-file\-auto\fP\&. However, it\(aqs currently limited
9384 to picking up a whitelist of "album art" filenames (such as \fBcover.jpg\fP),
9385 so currently only the \fBfuzzy\fP choice is available. In addition, if a video
9386 already has tracks (which are not marked as cover art), external cover art
9387 will not be loaded.
9388 .sp
9389 See \fB\-\-cover\-art\-files\fP for details about what constitutes cover art.
9390 .sp
9391 See \fB\-\-audio\-display\fP how to control display of cover art (this can be
9392 used to disable cover art that is part of the file).
9393 .TP
9394 .B \fB\-\-autoload\-files=<yes|no>\fP
9395 Automatically load/select external files (default: yes).
9396 .sp
9397 If set to \fBno\fP, then do not automatically load external files as specified
9398 by \fB\-\-sub\-auto\fP and \fB\-\-audio\-file\-auto\fP\&. If external files are forcibly
9399 added (like with \fB\-\-sub\-files\fP), they will not be auto\-selected.
9400 .sp
9401 This does not affect playlist expansion, redirection, or other loading of
9402 referenced files like with ordered chapters.
9403 .TP
9404 .B \fB\-\-record\-file=<file>\fP
9405 Deprecated, use \fB\-\-stream\-record\fP, or the \fBdump\-cache\fP command.
9406 .sp
9407 Record the current stream to the given target file. The target file will
9408 always be overwritten without asking.
9409 .sp
9410 This was deprecated because it isn\(aqt very nice to use. For one, seeking
9411 while this is enabled will be directly reflected in the output, which was
9412 not useful and annoying.
9413 .TP
9414 .B \fB\-\-stream\-record=<file>\fP
9415 Write received/read data from the demuxer to the given output file. The
9416 output file will always be overwritten without asking. The output format
9417 is determined by the extension of the output file.
9418 .sp
9419 Switching streams or seeking during recording might result in recording
9420 being stopped and/or broken files. Use with care.
9421 .sp
9422 Seeking outside of the demuxer cache will result in "skips" in the output
9423 file, but seeking within the demuxer cache should not affect recording. One
9424 exception is when you seek back far enough to exceed the forward buffering
9425 size, in which case the cache stops actively reading. This will return in
9426 dropped data if it\(aqs a live stream.
9427 .sp
9428 If this is set at runtime, the old file is closed, and the new file is
9429 opened. Note that this will write only data that is appended at the end of
9430 the cache, and the already cached data cannot be written. You can try the
9431 \fBdump\-cache\fP command as an alternative.
9432 .sp
9433 External files (\fB\-\-audio\-file\fP etc.) are ignored by this, it works on the
9434 "main" file only. Using this with files using ordered chapters or EDL files
9435 will also not work correctly in general.
9436 .sp
9437 There are some glitches with this because it uses FFmpeg\(aqs libavformat for
9438 writing the output file. For example, it\(aqs typical that it will only work if
9439 the output format is the same as the input format. This is the case even if
9440 it works with the \fBffmpeg\fP tool. One reason for this is that \fBffmpeg\fP
9441 and its libraries contain certain hacks and workarounds for these issues,
9442 that are unavailable to outside users.
9443 .sp
9444 This replaces \fB\-\-record\-file\fP\&. It is similar to the ancient/removed
9445 \fB\-\-stream\-capture\fP/\fB\-capture\fP options, and provides better behavior in
9446 most cases (i.e. actually works).
9447 .TP
9448 .B \fB\-\-lavfi\-complex=<string>\fP
9449 Set a "complex" libavfilter filter, which means a single filter graph can
9450 take input from multiple source audio and video tracks. The graph can result
9451 in a single audio or video output (or both).
9452 .sp
9453 Currently, the filter graph labels are used to select the participating
9454 input tracks and audio/video output. The following rules apply:
9455 .INDENT 7.0
9456 .IP \(bu 2
9457 A label of the form \fBaidN\fP selects audio track N as input (e.g.
9458 \fBaid1\fP).
9459 .IP \(bu 2
9460 A label of the form \fBvidN\fP selects video track N as input.
9461 .IP \(bu 2
9462 A label named \fBao\fP will be connected to the audio output.
9463 .IP \(bu 2
9464 A label named \fBvo\fP will be connected to the video output.
9465 .UNINDENT
9466 .sp
9467 Each label can be used only once. If you want to use e.g. an audio stream
9468 for multiple filters, you need to use the \fBasplit\fP filter. Multiple
9469 video or audio outputs are not possible, but you can use filters to merge
9470 them into one.
9471 .sp
9472 It\(aqs not possible to change the tracks connected to the filter at runtime,
9473 unless you explicitly change the \fBlavfi\-complex\fP property and set new
9474 track assignments. When the graph is changed, the track selection is changed
9475 according to the used labels as well.
9476 .sp
9477 Other tracks, as long as they\(aqre not connected to the filter, and the
9478 corresponding output is not connected to the filter, can still be freely
9479 changed with the normal methods.
9480 .sp
9481 Note that the normal filter chains (\fB\-\-af\fP, \fB\-\-vf\fP) are applied between
9482 the complex graphs (e.g. \fBao\fP label) and the actual output.
9483 .INDENT 7.0
9484 .INDENT 3.5
9485 .IP "Examples"
9486 .INDENT 0.0
9487 .IP \(bu 2
9488 \fB\-\-lavfi\-complex=\(aq[aid1] [aid2] amix [ao]\(aq\fP
9489 Play audio track 1 and 2 at the same time.
9490 .IP \(bu 2
9491 \fB\-\-lavfi\-complex=\(aq[vid1] [vid2] vstack [vo]\(aq\fP
9492 Stack video track 1 and 2 and play them at the same time. Note that
9493 both tracks need to have the same width, or filter initialization
9494 will fail (you can add \fBscale\fP filters before the \fBvstack\fP filter
9495 to fix the size).
9496 To load a video track from another file, you can use
9497 \fB\-\-external\-file=other.mkv\fP\&.
9498 .IP \(bu 2
9499 \fB\-\-lavfi\-complex=\(aq[aid1] asplit [t1] [ao] ; [t1] showvolume [t2] ; [vid1] [t2] overlay [vo]\(aq\fP
9500 Play audio track 1, and overlay the measured volume for each speaker
9501 over video track 1.
9502 .IP \(bu 2
9503 \fBnull:// \-\-lavfi\-complex=\(aqlife [vo]\(aq\fP
9504 A libavfilter source\-only filter (Conways\(aq Life Game).
9505 .UNINDENT
9506 .UNINDENT
9507 .UNINDENT
9508 .sp
9509 See the FFmpeg libavfilter documentation for details on the available
9510 filters.
9511 .TP
9512 .B \fB\-\-metadata\-codepage=<codepage>\fP
9513 Codepage for various input metadata (default: \fButf\-8\fP). This affects how
9514 file tags, chapter titles, etc. are interpreted. You can for example set
9515 this to \fBauto\fP to enable autodetection of the codepage. (This is not the
9516 default because non\-UTF\-8 codepages are an obscure fringe use\-case.)
9517 .sp
9518 See \fB\-\-sub\-codepage\fP option on how codepages are specified and further
9519 details regarding autodetection and codepage conversion. (The underlying
9520 code is the same.)
9521 .sp
9522 Conversion is not applied to metadata that is updated at runtime.
9523 .UNINDENT
9524 .SS Debugging
9525 .INDENT 0.0
9526 .TP
9527 .B \fB\-\-unittest=<name>\fP
9528 Run an internal unit test. There are multiple, and the name specifies which.
9529 .sp
9530 The special value \fBall\-simple\fP runs all tests which do not need further
9531 setup (other arguments and such). Some tests may need additional arguments
9532 to do anything useful.
9533 .sp
9534 On success, the player binary exits with exit status 0, otherwise it returns
9535 with an undefined non\-0 exit status (it may crash or abort itself on test
9536 failures).
9537 .sp
9538 This is only enabled if built with \fB\-\-enable\-tests\fP, and should normally
9539 be enabled and used by developers only.
9540 .UNINDENT
9541 .SH AUDIO OUTPUT DRIVERS
9542 .sp
9543 Audio output drivers are interfaces to different audio output facilities. The
9544 syntax is:
9545 .INDENT 0.0
9546 .TP
9547 .B \fB\-\-ao=<driver1,driver2,...[,]>\fP
9548 Specify a priority list of audio output drivers to be used.
9549 .UNINDENT
9550 .sp
9551 If the list has a trailing \(aq,\(aq, mpv will fall back on drivers not contained
9552 in the list.
9553 .sp
9554 \fBNOTE:\fP
9555 .INDENT 0.0
9556 .INDENT 3.5
9557 See \fB\-\-ao=help\fP for a list of compiled\-in audio output drivers. The
9558 driver \fB\-\-ao=alsa\fP is preferred. \fB\-\-ao=pulse\fP is preferred on systems
9559 where PulseAudio is used.
9560 .UNINDENT
9561 .UNINDENT
9562 .sp
9563 Available audio output drivers are:
9564 .INDENT 0.0
9565 .TP
9566 .B \fBalsa\fP (Linux only)
9567 ALSA audio output driver
9568 .sp
9569 See \fI\%ALSA audio output options\fP for options specific to this AO.
9570 .sp
9571 \fBWARNING:\fP
9572 .INDENT 7.0
9573 .INDENT 3.5
9574 To get multichannel/surround audio, use \fB\-\-audio\-channels=auto\fP\&. The
9575 default for this option is \fBauto\-safe\fP, which makes this audio output
9576 explicitly reject multichannel output, as there is no way to detect
9577 whether a certain channel layout is actually supported.
9578 .sp
9579 You can also try \fI\%using the upmix plugin\fP\&.
9580 This setup enables multichannel audio on the \fBdefault\fP device
9581 with automatic upmixing with shared access, so playing stereo
9582 and multichannel audio at the same time will work as expected.
9583 .UNINDENT
9584 .UNINDENT
9585 .TP
9586 .B \fBjack\fP
9587 JACK (Jack Audio Connection Kit) audio output driver.
9588 .sp
9589 The following global options are supported by this audio output:
9590 .INDENT 7.0
9591 .TP
9592 .B \fB\-\-jack\-port=<name>\fP
9593 Connects to the ports with the given name (default: physical ports).
9594 .TP
9595 .B \fB\-\-jack\-name=<client>\fP
9596 Client name that is passed to JACK (default: \fBmpv\fP). Useful
9597 if you want to have certain connections established automatically.
9598 .TP
9599 .B \fB\-\-jack\-autostart=<yes|no>\fP
9600 Automatically start jackd if necessary (default: disabled). Note that
9601 this tends to be unreliable and will flood stdout with server messages.
9602 .TP
9603 .B \fB\-\-jack\-connect=<yes|no>\fP
9604 Automatically create connections to output ports (default: enabled).
9605 When enabled, the maximum number of output channels will be limited to
9606 the number of available output ports.
9607 .TP
9608 .B \fB\-\-jack\-std\-channel\-layout=<waveext|any>\fP
9609 Select the standard channel layout (default: waveext). JACK itself has no
9610 notion of channel layouts (i.e. assigning which speaker a given
9611 channel is supposed to map to) \- it just takes whatever the application
9612 outputs, and reroutes it to whatever the user defines. This means the
9613 user and the application are in charge of dealing with the channel
9614 layout. \fBwaveext\fP uses WAVE_FORMAT_EXTENSIBLE order, which, even
9615 though it was defined by Microsoft, is the standard on many systems.
9616 The value \fBany\fP makes JACK accept whatever comes from the audio
9617 filter chain, regardless of channel layout and without reordering. This
9618 mode is probably not very useful, other than for debugging or when used
9619 with fixed setups.
9620 .UNINDENT
9621 .TP
9622 .B \fBcoreaudio\fP (Mac OS X only)
9623 Native Mac OS X audio output driver using AudioUnits and the CoreAudio
9624 sound server.
9625 .sp
9626 Automatically redirects to \fBcoreaudio_exclusive\fP when playing compressed
9627 formats.
9628 .sp
9629 The following global options are supported by this audio output:
9630 .INDENT 7.0
9631 .TP
9632 .B \fB\-\-coreaudio\-change\-physical\-format=<yes|no>\fP
9633 Change the physical format to one similar to the requested audio format
9634 (default: no). This has the advantage that multichannel audio output
9635 will actually work. The disadvantage is that it will change the
9636 system\-wide audio settings. This is equivalent to changing the \fBFormat\fP
9637 setting in the \fBAudio Devices\fP dialog in the \fBAudio MIDI Setup\fP
9638 utility. Note that this does not affect the selected speaker setup.
9639 .TP
9640 .B \fB\-\-coreaudio\-spdif\-hack=<yes|no>\fP
9641 Try to pass through AC3/DTS data as PCM. This is useful for drivers
9642 which do not report AC3 support. It converts the AC3 data to float,
9643 and assumes the driver will do the inverse conversion, which means
9644 a typical A/V receiver will pick it up as compressed IEC framed AC3
9645 stream, ignoring that it\(aqs marked as PCM. This disables normal AC3
9646 passthrough (even if the device reports it as supported). Use with
9647 extreme care.
9648 .UNINDENT
9649 .TP
9650 .B \fBcoreaudio_exclusive\fP (Mac OS X only)
9651 Native Mac OS X audio output driver using direct device access and
9652 exclusive mode (bypasses the sound server).
9653 .TP
9654 .B \fBopenal\fP
9655 OpenAL audio output driver. This is broken and does not work.
9656 .INDENT 7.0
9657 .TP
9658 .B \fB\-\-openal\-num\-buffers=<2\-128>\fP
9659 Specify the number of audio buffers to use. Lower values are better for
9660 lower CPU usage. Default: 4.
9661 .TP
9662 .B \fB\-\-openal\-num\-samples=<256\-32768>\fP
9663 Specify the number of complete samples to use for each buffer. Higher
9664 values are better for lower CPU usage. Default: 8192.
9665 .TP
9666 .B \fB\-\-openal\-direct\-channels=<yes|no>\fP
9667 Enable OpenAL Soft\(aqs direct channel extension when available to avoid
9668 tinting the sound with ambisonics or HRTF.
9669 Channels are dropped when when they are not available as downmixing
9670 will be disabled. Default: no.
9671 .UNINDENT
9672 .TP
9673 .B \fBpulse\fP
9674 PulseAudio audio output driver
9675 .sp
9676 The following global options are supported by this audio output:
9677 .INDENT 7.0
9678 .TP
9679 .B \fB\-\-pulse\-host=<host>\fP
9680 Specify the host to use. An empty <host> string uses a local connection,
9681 "localhost" uses network transfer (most likely not what you want).
9682 .TP
9683 .B \fB\-\-pulse\-buffer=<1\-2000|native>\fP
9684 Set the audio buffer size in milliseconds. A higher value buffers
9685 more data, and has a lower probability of buffer underruns. A smaller
9686 value makes the audio stream react faster, e.g. to playback speed
9687 changes.
9688 .TP
9689 .B \fB\-\-pulse\-latency\-hacks=<yes|no>\fP
9690 Enable hacks to workaround PulseAudio timing bugs (default: no). If
9691 enabled, mpv will do elaborate latency calculations on its own. If
9692 disabled, it will use PulseAudio automatically updated timing
9693 information. Disabling this might help with e.g. networked audio or
9694 some plugins, while enabling it might help in some unknown situations
9695 (it used to be required to get good behavior on old PulseAudio versions).
9696 .sp
9697 If you have stuttering video when using pulse, try to enable this
9698 option. (Or try to update PulseAudio.)
9699 .TP
9700 .B \fB\-\-pulse\-allow\-suspended=<yes|no>\fP
9701 Allow mpv to use PulseAudio even if the sink is suspended (default: no).
9702 Can be useful if PulseAudio is running as a bridge to jack and mpv has its sink\-input set to the one jack is using.
9703 .UNINDENT
9704 .TP
9705 .B \fBsdl\fP
9706 SDL 1.2+ audio output driver. Should work on any platform supported by SDL
9707 1.2, but may require the \fBSDL_AUDIODRIVER\fP environment variable to be set
9708 appropriately for your system.
9709 .sp
9710 \fBNOTE:\fP
9711 .INDENT 7.0
9712 .INDENT 3.5
9713 This driver is for compatibility with extremely foreign
9714 environments, such as systems where none of the other drivers
9715 are available.
9716 .UNINDENT
9717 .UNINDENT
9718 .sp
9719 The following global options are supported by this audio output:
9720 .INDENT 7.0
9721 .TP
9722 .B \fB\-\-sdl\-buflen=<length>\fP
9723 Sets the audio buffer length in seconds. Is used only as a hint by the
9724 sound system. Playing a file with \fB\-v\fP will show the requested and
9725 obtained exact buffer size. A value of 0 selects the sound system
9726 default.
9727 .UNINDENT
9728 .TP
9729 .B \fBnull\fP
9730 Produces no audio output but maintains video playback speed. You can use
9731 \fB\-\-ao=null \-\-ao\-null\-untimed\fP for benchmarking.
9732 .sp
9733 The following global options are supported by this audio output:
9734 .INDENT 7.0
9735 .TP
9736 .B \fB\-\-ao\-null\-untimed\fP
9737 Do not simulate timing of a perfect audio device. This means audio
9738 decoding will go as fast as possible, instead of timing it to the
9739 system clock.
9740 .TP
9741 .B \fB\-\-ao\-null\-buffer\fP
9742 Simulated buffer length in seconds.
9743 .TP
9744 .B \fB\-\-ao\-null\-outburst\fP
9745 Simulated chunk size in samples.
9746 .TP
9747 .B \fB\-\-ao\-null\-speed\fP
9748 Simulated audio playback speed as a multiplier. Usually, a real audio
9749 device will not go exactly as fast as the system clock. It will deviate
9750 just a little, and this option helps to simulate this.
9751 .TP
9752 .B \fB\-\-ao\-null\-latency\fP
9753 Simulated device latency. This is additional to EOF.
9754 .TP
9755 .B \fB\-\-ao\-null\-broken\-eof\fP
9756 Simulate broken audio drivers, which always add the fixed device
9757 latency to the reported audio playback position.
9758 .TP
9759 .B \fB\-\-ao\-null\-broken\-delay\fP
9760 Simulate broken audio drivers, which don\(aqt report latency correctly.
9761 .TP
9762 .B \fB\-\-ao\-null\-channel\-layouts\fP
9763 If not empty, this is a \fB,\fP separated list of channel layouts the
9764 AO allows. This can be used to test channel layout selection.
9765 .TP
9766 .B \fB\-\-ao\-null\-format\fP
9767 Force the audio output format the AO will accept. If unset accepts any.
9768 .UNINDENT
9769 .TP
9770 .B \fBpcm\fP
9771 Raw PCM/WAVE file writer audio output
9772 .sp
9773 The following global options are supported by this audio output:
9774 .INDENT 7.0
9775 .TP
9776 .B \fB\-\-ao\-pcm\-waveheader=<yes|no>\fP
9777 Include or do not include the WAVE header (default: included). When
9778 not included, raw PCM will be generated.
9779 .TP
9780 .B \fB\-\-ao\-pcm\-file=<filename>\fP
9781 Write the sound to \fB<filename>\fP instead of the default
9782 \fBaudiodump.wav\fP\&. If \fBno\-waveheader\fP is specified, the default is
9783 \fBaudiodump.pcm\fP\&.
9784 .TP
9785 .B \fB\-\-ao\-pcm\-append=<yes|no>\fP
9786 Append to the file, instead of overwriting it. Always use this with the
9787 \fBno\-waveheader\fP option \- with \fBwaveheader\fP it\(aqs broken, because
9788 it will write a WAVE header every time the file is opened.
9789 .UNINDENT
9790 .TP
9791 .B \fBwasapi\fP
9792 Audio output to the Windows Audio Session API.
9793 .UNINDENT
9794 .SH VIDEO OUTPUT DRIVERS
9795 .sp
9796 Video output drivers are interfaces to different video output facilities. The
9797 syntax is:
9798 .INDENT 0.0
9799 .TP
9800 .B \fB\-\-vo=<driver1,driver2,...[,]>\fP
9801 Specify a priority list of video output drivers to be used.
9802 .UNINDENT
9803 .sp
9804 If the list has a trailing \fB,\fP, mpv will fall back on drivers not contained
9805 in the list.
9806 .sp
9807 \fBNOTE:\fP
9808 .INDENT 0.0
9809 .INDENT 3.5
9810 See \fB\-\-vo=help\fP for a list of compiled\-in video output drivers.
9811 .sp
9812 The recommended output driver is \fB\-\-vo=gpu\fP, which is the default. All
9813 other drivers are for compatibility or special purposes. If the default
9814 does not work, it will fallback to other drivers (in the same order as
9815 listed by \fB\-\-vo=help\fP).
9816 .UNINDENT
9817 .UNINDENT
9818 .sp
9819 Available video output drivers are:
9820 .INDENT 0.0
9821 .TP
9822 .B \fBxv\fP (X11 only)
9823 Uses the XVideo extension to enable hardware\-accelerated display. This is
9824 the most compatible VO on X, but may be low\-quality, and has issues with
9825 OSD and subtitle display.
9826 .sp
9827 \fBNOTE:\fP
9828 .INDENT 7.0
9829 .INDENT 3.5
9830 This driver is for compatibility with old systems.
9831 .UNINDENT
9832 .UNINDENT
9833 .sp
9834 The following global options are supported by this video output:
9835 .INDENT 7.0
9836 .TP
9837 .B \fB\-\-xv\-adaptor=<number>\fP
9838 Select a specific XVideo adapter (check xvinfo results).
9839 .TP
9840 .B \fB\-\-xv\-port=<number>\fP
9841 Select a specific XVideo port.
9842 .TP
9843 .B \fB\-\-xv\-ck=<cur|use|set>\fP
9844 Select the source from which the color key is taken (default: cur).
9845 .INDENT 7.0
9846 .TP
9847 .B cur
9848 The default takes the color key currently set in Xv.
9849 .TP
9850 .B use
9851 Use but do not set the color key from mpv (use the \fB\-\-colorkey\fP
9852 option to change it).
9853 .TP
9854 .B set
9855 Same as use but also sets the supplied color key.
9856 .UNINDENT
9857 .TP
9858 .B \fB\-\-xv\-ck\-method=<none|man|bg|auto>\fP
9859 Sets the color key drawing method (default: man).
9860 .INDENT 7.0
9861 .TP
9862 .B none
9863 Disables color\-keying.
9864 .TP
9865 .B man
9866 Draw the color key manually (reduces flicker in some cases).
9867 .TP
9868 .B bg
9869 Set the color key as window background.
9870 .TP
9871 .B auto
9872 Let Xv draw the color key.
9873 .UNINDENT
9874 .TP
9875 .B \fB\-\-xv\-colorkey=<number>\fP
9876 Changes the color key to an RGB value of your choice. \fB0x000000\fP is
9877 black and \fB0xffffff\fP is white.
9878 .TP
9879 .B \fB\-\-xv\-buffers=<number>\fP
9880 Number of image buffers to use for the internal ringbuffer (default: 2).
9881 Increasing this will use more memory, but might help with the X server
9882 not responding quickly enough if video FPS is close to or higher than
9883 the display refresh rate.
9884 .UNINDENT
9885 .TP
9886 .B \fBx11\fP (X11 only)
9887 Shared memory video output driver without hardware acceleration that works
9888 whenever X11 is present.
9889 .sp
9890 Since mpv 0.30.0, you may need to use \fB\-\-profile=sw\-fast\fP to get decent
9891 performance.
9892 .sp
9893 \fBNOTE:\fP
9894 .INDENT 7.0
9895 .INDENT 3.5
9896 This is a fallback only, and should not be normally used.
9897 .UNINDENT
9898 .UNINDENT
9899 .TP
9900 .B \fBvdpau\fP (X11 only)
9901 Uses the VDPAU interface to display and optionally also decode video.
9902 Hardware decoding is used with \fB\-\-hwdec=vdpau\fP\&.
9903 .sp
9904 \fBNOTE:\fP
9905 .INDENT 7.0
9906 .INDENT 3.5
9907 Earlier versions of mpv (and MPlayer, mplayer2) provided sub\-options
9908 to tune vdpau post\-processing, like \fBdeint\fP, \fBsharpen\fP, \fBdenoise\fP,
9909 \fBchroma\-deint\fP, \fBpullup\fP, \fBhqscaling\fP\&. These sub\-options are
9910 deprecated, and you should use the \fBvdpaupp\fP video filter instead.
9911 .UNINDENT
9912 .UNINDENT
9913 .sp
9914 The following global options are supported by this video output:
9915 .INDENT 7.0
9916 .TP
9917 .B \fB\-\-vo\-vdpau\-sharpen=<\-1\-1>\fP
9918 (Deprecated. See note about \fBvdpaupp\fP\&.)
9919 .sp
9920 For positive values, apply a sharpening algorithm to the video, for
9921 negative values a blurring algorithm (default: 0).
9922 .TP
9923 .B \fB\-\-vo\-vdpau\-denoise=<0\-1>\fP
9924 (Deprecated. See note about \fBvdpaupp\fP\&.)
9925 .sp
9926 Apply a noise reduction algorithm to the video (default: 0; no noise
9927 reduction).
9928 .TP
9929 .B \fB\-\-vo\-vdpau\-chroma\-deint\fP
9930 (Deprecated. See note about \fBvdpaupp\fP\&.)
9931 .sp
9932 Makes temporal deinterlacers operate both on luma and chroma (default).
9933 Use no\-chroma\-deint to solely use luma and speed up advanced
9934 deinterlacing. Useful with slow video memory.
9935 .TP
9936 .B \fB\-\-vo\-vdpau\-pullup\fP
9937 (Deprecated. See note about \fBvdpaupp\fP\&.)
9938 .sp
9939 Try to apply inverse telecine, needs motion adaptive temporal
9940 deinterlacing.
9941 .TP
9942 .B \fB\-\-vo\-vdpau\-hqscaling=<0\-9>\fP
9943 (Deprecated. See note about \fBvdpaupp\fP\&.)
9944 .INDENT 7.0
9945 .TP
9946 .B 0
9947 Use default VDPAU scaling (default).
9948 .TP
9949 .B 1\-9
9950 Apply high quality VDPAU scaling (needs capable hardware).
9951 .UNINDENT
9952 .TP
9953 .B \fB\-\-vo\-vdpau\-fps=<number>\fP
9954 Override autodetected display refresh rate value (the value is needed
9955 for framedrop to allow video playback rates higher than display
9956 refresh rate, and for vsync\-aware frame timing adjustments). Default 0
9957 means use autodetected value. A positive value is interpreted as a
9958 refresh rate in Hz and overrides the autodetected value. A negative
9959 value disables all timing adjustment and framedrop logic.
9960 .TP
9961 .B \fB\-\-vo\-vdpau\-composite\-detect\fP
9962 NVIDIA\(aqs current VDPAU implementation behaves somewhat differently
9963 under a compositing window manager and does not give accurate frame
9964 timing information. With this option enabled, the player tries to
9965 detect whether a compositing window manager is active. If one is
9966 detected, the player disables timing adjustments as if the user had
9967 specified \fBfps=\-1\fP (as they would be based on incorrect input). This
9968 means timing is somewhat less accurate than without compositing, but
9969 with the composited mode behavior of the NVIDIA driver, there is no
9970 hard playback speed limit even without the disabled logic. Enabled by
9971 default, use \fB\-\-vo\-vdpau\-composite\-detect=no\fP to disable.
9972 .TP
9973 .B \fB\-\-vo\-vdpau\-queuetime\-windowed=<number>\fP and \fBqueuetime\-fs=<number>\fP
9974 Use VDPAU\(aqs presentation queue functionality to queue future video
9975 frame changes at most this many milliseconds in advance (default: 50).
9976 See below for additional information.
9977 .TP
9978 .B \fB\-\-vo\-vdpau\-output\-surfaces=<2\-15>\fP
9979 Allocate this many output surfaces to display video frames (default:
9980 3). See below for additional information.
9981 .TP
9982 .B \fB\-\-vo\-vdpau\-colorkey=<#RRGGBB|#AARRGGBB>\fP
9983 Set the VDPAU presentation queue background color, which in practice
9984 is the colorkey used if VDPAU operates in overlay mode (default:
9985 \fB#020507\fP, some shade of black). If the alpha component of this value
9986 is 0, the default VDPAU colorkey will be used instead (which is usually
9987 green).
9988 .TP
9989 .B \fB\-\-vo\-vdpau\-force\-yuv\fP
9990 Never accept RGBA input. This means mpv will insert a filter to convert
9991 to a YUV format before the VO. Sometimes useful to force availability
9992 of certain YUV\-only features, like video equalizer or deinterlacing.
9993 .UNINDENT
9994 .sp
9995 Using the VDPAU frame queuing functionality controlled by the queuetime
9996 options makes mpv\(aqs frame flip timing less sensitive to system CPU load and
9997 allows mpv to start decoding the next frame(s) slightly earlier, which can
9998 reduce jitter caused by individual slow\-to\-decode frames. However, the
9999 NVIDIA graphics drivers can make other window behavior such as window moves
10000 choppy if VDPAU is using the blit queue (mainly happens if you have the
10001 composite extension enabled) and this feature is active. If this happens on
10002 your system and it bothers you then you can set the queuetime value to 0 to
10003 disable this feature. The settings to use in windowed and fullscreen mode
10004 are separate because there should be no reason to disable this for
10005 fullscreen mode (as the driver issue should not affect the video itself).
10006 .sp
10007 You can queue more frames ahead by increasing the queuetime values and the
10008 \fBoutput_surfaces\fP count (to ensure enough surfaces to buffer video for a
10009 certain time ahead you need at least as many surfaces as the video has
10010 frames during that time, plus two). This could help make video smoother in
10011 some cases. The main downsides are increased video RAM requirements for
10012 the surfaces and laggier display response to user commands (display
10013 changes only become visible some time after they\(aqre queued). The graphics
10014 driver implementation may also have limits on the length of maximum
10015 queuing time or number of queued surfaces that work well or at all.
10016 .TP
10017 .B \fBdirect3d\fP (Windows only)
10018 Video output driver that uses the Direct3D interface.
10019 .sp
10020 \fBNOTE:\fP
10021 .INDENT 7.0
10022 .INDENT 3.5
10023 This driver is for compatibility with systems that don\(aqt provide
10024 proper OpenGL drivers, and where ANGLE does not perform well.
10025 .UNINDENT
10026 .UNINDENT
10027 .sp
10028 The following global options are supported by this video output:
10029 .INDENT 7.0
10030 .TP
10031 .B \fB\-\-vo\-direct3d\-disable\-texture\-align\fP
10032 Normally texture sizes are always aligned to 16. With this option
10033 enabled, the video texture will always have exactly the same size as
10034 the video itself.
10035 .UNINDENT
10036 .sp
10037 Debug options. These might be incorrect, might be removed in the future,
10038 might crash, might cause slow downs, etc. Contact the developers if you
10039 actually need any of these for performance or proper operation.
10040 .INDENT 7.0
10041 .TP
10042 .B \fB\-\-vo\-direct3d\-force\-power\-of\-2\fP
10043 Always force textures to power of 2, even if the device reports
10044 non\-power\-of\-2 texture sizes as supported.
10045 .TP
10046 .B \fB\-\-vo\-direct3d\-texture\-memory=<mode>\fP
10047 Only affects operation with shaders/texturing enabled, and (E)OSD.
10048 Possible values:
10049 .INDENT 7.0
10050 .TP
10051 .B \fBdefault\fP (default)
10052 Use \fBD3DPOOL_DEFAULT\fP, with a \fBD3DPOOL_SYSTEMMEM\fP texture for
10053 locking. If the driver supports \fBD3DDEVCAPS_TEXTURESYSTEMMEMORY\fP,
10054 \fBD3DPOOL_SYSTEMMEM\fP is used directly.
10055 .TP
10056 .B \fBdefault\-pool\fP
10057 Use \fBD3DPOOL_DEFAULT\fP\&. (Like \fBdefault\fP, but never use a
10058 shadow\-texture.)
10059 .TP
10060 .B \fBdefault\-pool\-shadow\fP
10061 Use \fBD3DPOOL_DEFAULT\fP, with a \fBD3DPOOL_SYSTEMMEM\fP texture for
10062 locking. (Like \fBdefault\fP, but always force the shadow\-texture.)
10063 .TP
10064 .B \fBmanaged\fP
10065 Use \fBD3DPOOL_MANAGED\fP\&.
10066 .TP
10067 .B \fBscratch\fP
10068 Use \fBD3DPOOL_SCRATCH\fP, with a \fBD3DPOOL_SYSTEMMEM\fP texture for
10069 locking.
10070 .UNINDENT
10071 .TP
10072 .B \fB\-\-vo\-direct3d\-swap\-discard\fP
10073 Use \fBD3DSWAPEFFECT_DISCARD\fP, which might be faster.
10074 Might be slower too, as it must(?) clear every frame.
10075 .TP
10076 .B \fB\-\-vo\-direct3d\-exact\-backbuffer\fP
10077 Always resize the backbuffer to window size.
10078 .UNINDENT
10079 .TP
10080 .B \fBgpu\fP
10081 General purpose, customizable, GPU\-accelerated video output driver. It
10082 supports extended scaling methods, dithering, color management, custom
10083 shaders, HDR, and more.
10084 .sp
10085 See \fI\%GPU renderer options\fP for options specific to this VO.
10086 .sp
10087 By default, it tries to use fast and fail\-safe settings. Use the
10088 \fBgpu\-hq\fP profile to use this driver with defaults set to high quality
10089 rendering. The profile can be applied with \fB\-\-profile=gpu\-hq\fP and its
10090 contents can be viewed with \fB\-\-show\-profile=gpu\-hq\fP\&.
10091 .sp
10092 This VO abstracts over several possible graphics APIs and windowing
10093 contexts, which can be influenced using the \fB\-\-gpu\-api\fP and
10094 \fB\-\-gpu\-context\fP options.
10095 .sp
10096 Hardware decoding over OpenGL\-interop is supported to some degree. Note
10097 that in this mode, some corner case might not be gracefully handled, and
10098 color space conversion and chroma upsampling is generally in the hand of
10099 the hardware decoder APIs.
10100 .sp
10101 \fBgpu\fP makes use of FBOs by default. Sometimes you can achieve better
10102 quality or performance by changing the \fB\-\-fbo\-format\fP option to
10103 \fBrgb16f\fP, \fBrgb32f\fP or \fBrgb\fP\&. Known problems include Mesa/Intel not
10104 accepting \fBrgb16\fP, Mesa sometimes not being compiled with float texture
10105 support, and some OS X setups being very slow with \fBrgb16\fP but fast
10106 with \fBrgb32f\fP\&. If you have problems, you can also try enabling the
10107 \fB\-\-gpu\-dumb\-mode=yes\fP option.
10108 .TP
10109 .B \fBsdl\fP
10110 SDL 2.0+ Render video output driver, depending on system with or without
10111 hardware acceleration. Should work on all platforms supported by SDL 2.0.
10112 For tuning, refer to your copy of the file \fBSDL_hints.h\fP\&.
10113 .sp
10114 \fBNOTE:\fP
10115 .INDENT 7.0
10116 .INDENT 3.5
10117 This driver is for compatibility with systems that don\(aqt provide
10118 proper graphics drivers.
10119 .UNINDENT
10120 .UNINDENT
10121 .sp
10122 The following global options are supported by this video output:
10123 .INDENT 7.0
10124 .TP
10125 .B \fB\-\-sdl\-sw\fP
10126 Continue even if a software renderer is detected.
10127 .TP
10128 .B \fB\-\-sdl\-switch\-mode\fP
10129 Instruct SDL to switch the monitor video mode when going fullscreen.
10130 .UNINDENT
10131 .TP
10132 .B \fBvaapi\fP
10133 Intel VA API video output driver with support for hardware decoding. Note
10134 that there is absolutely no reason to use this, other than compatibility.
10135 This is low quality, and has issues with OSD.
10136 .sp
10137 \fBNOTE:\fP
10138 .INDENT 7.0
10139 .INDENT 3.5
10140 This driver is for compatibility with crappy systems. You can
10141 use vaapi hardware decoding with \fB\-\-vo=gpu\fP too.
10142 .UNINDENT
10143 .UNINDENT
10144 .sp
10145 The following global options are supported by this video output:
10146 .INDENT 7.0
10147 .TP
10148 .B \fB\-\-vo\-vaapi\-scaling=<algorithm>\fP
10149 .INDENT 7.0
10150 .TP
10151 .B default
10152 Driver default (mpv default as well).
10153 .TP
10154 .B fast
10155 Fast, but low quality.
10156 .TP
10157 .B hq
10158 Unspecified driver dependent high\-quality scaling, slow.
10159 .TP
10160 .B nla
10161 \fBnon\-linear anamorphic scaling\fP
10162 .UNINDENT
10163 .TP
10164 .B \fB\-\-vo\-vaapi\-deint\-mode=<mode>\fP
10165 Select deinterlacing algorithm. Note that by default deinterlacing is
10166 initially always off, and needs to be enabled with the \fBd\fP key
10167 (default key binding for \fBcycle deinterlace\fP).
10168 .sp
10169 This option doesn\(aqt apply if libva supports video post processing (vpp).
10170 In this case, the default for \fBdeint\-mode\fP is \fBno\fP, and enabling
10171 deinterlacing via user interaction using the methods mentioned above
10172 actually inserts the \fBvavpp\fP video filter. If vpp is not actually
10173 supported with the libva backend in use, you can use this option to
10174 forcibly enable VO based deinterlacing.
10175 .INDENT 7.0
10176 .TP
10177 .B no
10178 Don\(aqt allow deinterlacing (default for newer libva).
10179 .TP
10180 .B first\-field
10181 Show only first field.
10182 .TP
10183 .B bob
10184 bob deinterlacing (default for older libva).
10185 .UNINDENT
10186 .TP
10187 .B \fB\-\-vo\-vaapi\-scaled\-osd=<yes|no>\fP
10188 If enabled, then the OSD is rendered at video resolution and scaled to
10189 display resolution. By default, this is disabled, and the OSD is
10190 rendered at display resolution if the driver supports it.
10191 .UNINDENT
10192 .TP
10193 .B \fBnull\fP
10194 Produces no video output. Useful for benchmarking.
10195 .sp
10196 Usually, it\(aqs better to disable video with \fB\-\-no\-video\fP instead.
10197 .sp
10198 The following global options are supported by this video output:
10199 .INDENT 7.0
10200 .TP
10201 .B \fB\-\-vo\-null\-fps=<value>\fP
10202 Simulate display FPS. This artificially limits how many frames the
10203 VO accepts per second.
10204 .UNINDENT
10205 .TP
10206 .B \fBcaca\fP
10207 Color ASCII art video output driver that works on a text console.
10208 .sp
10209 \fBNOTE:\fP
10210 .INDENT 7.0
10211 .INDENT 3.5
10212 This driver is a joke.
10213 .UNINDENT
10214 .UNINDENT
10215 .TP
10216 .B \fBtct\fP
10217 Color Unicode art video output driver that works on a text console.
10218 By default depends on support of true color by modern terminals to display
10219 the images at full color range, but 256\-colors outout is also supported (see
10220 below). On Windows it requires an ansi terminal such as mintty.
10221 .sp
10222 Since mpv 0.30.0, you may need to use \fB\-\-profile=sw\-fast\fP to get decent
10223 performance.
10224 .sp
10225 Note: the TCT image output is not synchronized with other terminal output
10226 from mpv, which can lead to broken images. The options \fB\-\-no\-terminal\fP or
10227 \fB\-\-really\-quiet\fP can help with that.
10228 .INDENT 7.0
10229 .TP
10230 .B \fB\-\-vo\-tct\-algo=<algo>\fP
10231 Select how to write the pixels to the terminal.
10232 .INDENT 7.0
10233 .TP
10234 .B half\-blocks
10235 Uses unicode LOWER HALF BLOCK character to achieve higher vertical
10236 resolution. (Default.)
10237 .TP
10238 .B plain
10239 Uses spaces. Causes vertical resolution to drop twofolds, but in
10240 theory works in more places.
10241 .UNINDENT
10242 .TP
10243 .B \fB\-\-vo\-tct\-width=<width>\fP \fB\-\-vo\-tct\-height=<height>\fP
10244 Assume the terminal has the specified character width and/or height.
10245 These default to 80x25 if the terminal size cannot be determined.
10246 .TP
10247 .B \fB\-\-vo\-tct\-256=<yes|no>\fP (default: no)
10248 Use 256 colors \- for terminals which don\(aqt support true color.
10249 .UNINDENT
10250 .TP
10251 .B \fBsixel\fP
10252 Graphical output for the terminal, using sixels. Tested with \fBmlterm\fP and
10253 \fBxterm\fP\&.
10254 .sp
10255 Note: the Sixel image output is not synchronized with other terminal output
10256 from mpv, which can lead to broken images. The option \fB\-\-really\-quiet\fP
10257 can help with that, and is recommended.
10258 .sp
10259 You may need to use \fB\-\-profile=sw\-fast\fP to get decent performance.
10260 .sp
10261 Note: at the time of writing, \fBxterm\fP does not enable sixel by default \-
10262 launching it as \fBxterm \-ti 340\fP is one way to enable it. Also, \fBxterm\fP
10263 does not display images bigger than 1000x1000 pixels by default.
10264 .sp
10265 To render and align sixel images correctly, mpv needs to know the terminal
10266 size both in cells and in pixels. By default it tries to use values which
10267 the terminal reports, however, due to differences between terminals this is
10268 an error\-prone process which cannot be automated with certainty \- some
10269 terminals report the size in pixels including the padding \- e.g. \fBxterm\fP,
10270 while others report the actual usable number of pixels \- like \fBmlterm\fP\&.
10271 Additionally, they may behave differently when maximized or in fullscreen,
10272 and mpv cannot detect this state using standard methods.
10273 .sp
10274 Sixel size and alignment options:
10275 .INDENT 7.0
10276 .TP
10277 .B \fB\-\-vo\-sixel\-cols=<columns>\fP, \fB\-\-vo\-sixel\-rows=<rows>\fP (default: 0)
10278 Specify the terminal size in character cells, otherwise (0) read it
10279 from the terminal, or fall back to 80x25. Note that mpv doesn\(aqt use the
10280 the last row with sixel because this seems to result in scrolling.
10281 .TP
10282 .B \fB\-\-vo\-sixel\-width=<width>\fP, \fB\-\-vo\-sixel\-height=<height>\fP (default: 0)
10283 Specify the available size in pixels, otherwise (0) read it from the
10284 terminal, or fall back to 320x240. Other than excluding the last line,
10285 the height is also further rounded down to a multiple of 6 (sixel unit
10286 height) to avoid overflowing below the designated size.
10287 .TP
10288 .B \fB\-\-vo\-sixel\-left=<col>\fP, \fB\-\-vo\-sixel\-top=<row>\fP (default: 0)
10289 Specify the position in character cells where the image starts (1 is
10290 the first column or row). If 0 (default) then try to automatically
10291 determine it according to the other values and the image aspect ratio
10292 and zoom.
10293 .TP
10294 .B \fB\-\-vo\-sixel\-pad\-x=<pad_x>\fP, \fB\-\-vo\-sixel\-pad\-y=<pad_y>\fP (default: \-1)
10295 Used only when mpv reads the size in pixels from the terminal.
10296 Specify the number of padding pixels (on one side) which are included
10297 at the size which the terminal reports. If \-1 (default) then the number
10298 of pixels is rounded down to a multiple of number of cells (per axis),
10299 to take into account padding at the report \- this only works correctly
10300 when the overall padding per axis is smaller than the number of cells.
10301 .UNINDENT
10302 .sp
10303 Sixel image quality options:
10304 .INDENT 7.0
10305 .TP
10306 .B \fB\-\-vo\-sixel\-dither=<algo>\fP
10307 Selects the dither algorithm which libsixel should apply.
10308 Can be one of the below list as per libsixel\(aqs documentation.
10309 .INDENT 7.0
10310 .TP
10311 .B auto
10312 Choose diffuse type automatically
10313 .TP
10314 .B none
10315 Don\(aqt diffuse
10316 .TP
10317 .B atkinson
10318 Diffuse with Bill Atkinson\(aqs method. (Default)
10319 .TP
10320 .B fs
10321 Diffuse with Floyd\-Steinberg method
10322 .TP
10323 .B jajuni
10324 Diffuse with Jarvis, Judice & Ninke method
10325 .TP
10326 .B stucki
10327 Diffuse with Stucki\(aqs method
10328 .TP
10329 .B burkes
10330 Diffuse with Burkes\(aq method
10331 .TP
10332 .B arithmetic
10333 Positionally stable arithmetic dither
10334 .TP
10335 .B xor
10336 Positionally stable arithmetic xor based dither
10337 .UNINDENT
10338 .TP
10339 .B \fB\-\-vo\-sixel\-fixedpalette=<yes|no>\fP (default: yes)
10340 Use libsixel\(aqs built\-in static palette using the XTERM256 profile
10341 for dither. Fixed palette uses 256 colors for dithering. Note that
10342 using \fBno\fP (at the time of writing) will slow down \fBxterm\fP\&.
10343 .TP
10344 .B \fB\-\-vo\-sixel\-reqcolors=<colors>\fP (default: 256)
10345 Set up libsixel to use required number of colors for dynamic palette.
10346 This value depends on the terminal emulator as well. Xterm supports
10347 256 colors. Can set this to a lower value for faster performance.
10348 This option has no effect if fixed palette is used.
10349 .TP
10350 .B \fB\-\-vo\-sixel\-threshold=<threshold>\fP (default: \-1)
10351 When using a dynamic palette, defines the threshold to change the
10352 palette \- as percentage of the number of colors, e.g. 20 will change
10353 the palette when the number of colors changed by 20%. It\(aqs a simple
10354 measure to reduce the number of palette changes, because it can be slow
10355 in some terminals (\fBxterm\fP), however, it seems that in \fBmlterm\fP it
10356 causes image corruption. The default (\-1) will change the palette
10357 on every frame and will have better quality, and no corruption in
10358 \fBmlterm\fP\&.
10359 .UNINDENT
10360 .TP
10361 .B \fBimage\fP
10362 Output each frame into an image file in the current directory. Each file
10363 takes the frame number padded with leading zeros as name.
10364 .sp
10365 The following global options are supported by this video output:
10366 .INDENT 7.0
10367 .TP
10368 .B \fB\-\-vo\-image\-format=<format>\fP
10369 Select the image file format.
10370 .INDENT 7.0
10371 .TP
10372 .B jpg
10373 JPEG files, extension .jpg. (Default.)
10374 .TP
10375 .B jpeg
10376 JPEG files, extension .jpeg.
10377 .TP
10378 .B png
10379 PNG files.
10380 .TP
10381 .B webp
10382 WebP files.
10383 .UNINDENT
10384 .TP
10385 .B \fB\-\-vo\-image\-png\-compression=<0\-9>\fP
10386 PNG compression factor (speed vs. file size tradeoff) (default: 7)
10387 .TP
10388 .B \fB\-\-vo\-image\-png\-filter=<0\-5>\fP
10389 Filter applied prior to PNG compression (0 = none; 1 = sub; 2 = up;
10390 3 = average; 4 = Paeth; 5 = mixed) (default: 5)
10391 .TP
10392 .B \fB\-\-vo\-image\-jpeg\-quality=<0\-100>\fP
10393 JPEG quality factor (default: 90)
10394 .TP
10395 .B \fB\-\-vo\-image\-jpeg\-optimize=<0\-100>\fP
10396 JPEG optimization factor (default: 100)
10397 .TP
10398 .B \fB\-\-vo\-image\-webp\-lossless=<yes|no>\fP
10399 Enable writing lossless WebP files (default: no)
10400 .TP
10401 .B \fB\-\-vo\-image\-webp\-quality=<0\-100>\fP
10402 WebP quality (default: 75)
10403 .TP
10404 .B \fB\-\-vo\-image\-webp\-compression=<0\-6>\fP
10405 WebP compression factor (default: 4)
10406 .TP
10407 .B \fB\-\-vo\-image\-outdir=<dirname>\fP
10408 Specify the directory to save the image files to (default: \fB\&./\fP).
10409 .UNINDENT
10410 .TP
10411 .B \fBlibmpv\fP
10412 For use with libmpv direct embedding. As a special case, on OS X it
10413 is used like a normal VO within mpv (cocoa\-cb). Otherwise useless in any
10414 other contexts.
10415 (See \fB<mpv/render.h>\fP\&.)
10416 .sp
10417 This also supports many of the options the \fBgpu\fP VO has, depending on the
10418 backend.
10419 .TP
10420 .B \fBrpi\fP (Raspberry Pi)
10421 Native video output on the Raspberry Pi using the MMAL API.
10422 .sp
10423 This is deprecated. Use \fB\-\-vo=gpu\fP instead, which is the default and
10424 provides the same functionality. The \fBrpi\fP VO will be removed in
10425 mpv 0.23.0. Its functionality was folded into \-\-vo=gpu, which now uses
10426 RPI hardware decoding by treating it as a hardware overlay (without applying
10427 GL filtering). Also to be changed in 0.23.0: the \-\-fs flag will be reset to
10428 "no" by default (like on the other platforms).
10429 .sp
10430 The following deprecated global options are supported by this video output:
10431 .INDENT 7.0
10432 .TP
10433 .B \fB\-\-rpi\-display=<number>\fP
10434 Select the display number on which the video overlay should be shown
10435 (default: 0).
10436 .TP
10437 .B \fB\-\-rpi\-layer=<number>\fP
10438 Select the dispmanx layer on which the video overlay should be shown
10439 (default: \-10). Note that mpv will also use the 2 layers above the
10440 selected layer, to handle the window background and OSD. Actual video
10441 rendering will happen on the layer above the selected layer.
10442 .TP
10443 .B \fB\-\-rpi\-background=<yes|no>\fP
10444 Whether to render a black background behind the video (default: no).
10445 Normally it\(aqs better to kill the console framebuffer instead, which
10446 gives better performance.
10447 .TP
10448 .B \fB\-\-rpi\-osd=<yes|no>\fP
10449 Enabled by default. If disabled with \fBno\fP, no OSD layer is created.
10450 This also means there will be no subtitles rendered.
10451 .UNINDENT
10452 .TP
10453 .B \fBdrm\fP (Direct Rendering Manager)
10454 Video output driver using Kernel Mode Setting / Direct Rendering Manager.
10455 Should be used when one doesn\(aqt want to install full\-blown graphical
10456 environment (e.g. no X). Does not support hardware acceleration (if you
10457 need this, check the \fBdrm\fP backend for \fBgpu\fP VO).
10458 .sp
10459 Since mpv 0.30.0, you may need to use \fB\-\-profile=sw\-fast\fP to get decent
10460 performance.
10461 .sp
10462 The following global options are supported by this video output:
10463 .INDENT 7.0
10464 .TP
10465 .B \fB\-\-drm\-connector=[<gpu_number>.]<name>\fP
10466 Select the connector to use (usually this is a monitor.) If \fB<name>\fP
10467 is empty or \fBauto\fP, mpv renders the output on the first available
10468 connector. Use \fB\-\-drm\-connector=help\fP to get a list of available
10469 connectors. When using multiple graphic cards, use the \fB<gpu_number>\fP
10470 argument to disambiguate.
10471 (default: empty)
10472 .TP
10473 .B \fB\-\-drm\-mode=<preferred|highest|N|WxH[@R]>\fP
10474 Mode to use (resolution and frame rate).
10475 Possible values:
10476 .INDENT 7.0
10477 .TP
10478 .B preferred
10479 Use the preferred mode for the screen on the selected
10480 connector. (default)
10481 .TP
10482 .B highest
10483 Use the mode with the highest resolution available on the
10484 selected connector.
10485 .TP
10486 .B N
10487 Select mode by index.
10488 .TP
10489 .B WxH[@R]
10490 Specify mode by width, height, and optionally refresh rate.
10491 In case several modes match, selects the mode that comes
10492 first in the EDID list of modes.
10493 .UNINDENT
10494 .sp
10495 Use \fB\-\-drm\-mode=help\fP to get a list of available modes for all active
10496 connectors.
10497 .TP
10498 .B \fB\-\-drm\-atomic=<no|auto>\fP
10499 Toggle use of atomic modesetting. Mostly useful for debugging.
10500 .INDENT 7.0
10501 .TP
10502 .B no
10503 Use legacy modesetting.
10504 .TP
10505 .B auto
10506 Use atomic modesetting, falling back to legacy modesetting if
10507 not available. (default)
10508 .UNINDENT
10509 .sp
10510 Note: Only affects \fBgpu\-context=drm\fP\&. \fBvo=drm\fP supports legacy
10511 modesetting only.
10512 .TP
10513 .B \fB\-\-drm\-draw\-plane=<primary|overlay|N>\fP
10514 Select the DRM plane to which video and OSD is drawn to, under normal
10515 circumstances. The plane can be specified as \fBprimary\fP, which will
10516 pick the first applicable primary plane; \fBoverlay\fP, which will pick
10517 the first applicable overlay plane; or by index. The index is zero
10518 based, and related to the CRTC.
10519 (default: primary)
10520 .sp
10521 When using this option with the drmprime\-drm hwdec interop, only the OSD
10522 is rendered to this plane.
10523 .TP
10524 .B \fB\-\-drm\-drmprime\-video\-plane=<primary|overlay|N>\fP
10525 Select the DRM plane to use for video with the drmprime\-drm hwdec
10526 interop (used by e.g. the rkmpp hwdec on RockChip SoCs, and v4l2 hwdec:s
10527 on various other SoC:s). The plane is unused otherwise. This option
10528 accepts the same values as \fB\-\-drm\-draw\-plane\fP\&. (default: overlay)
10529 .sp
10530 To be able to successfully play 4K video on various SoCs you might need
10531 to set \fB\-\-drm\-draw\-plane=overlay \-\-drm\-drmprime\-video\-plane=primary\fP
10532 and setting \fB\-\-drm\-draw\-surface\-size=1920x1080\fP, to render the OSD at a
10533 lower resolution (the video when handled by the hwdec will be on the
10534 drmprime\-video plane and at full 4K resolution)
10535 .TP
10536 .B \fB\-\-drm\-format=<xrgb8888|xrgb2101010>\fP
10537 Select the DRM format to use (default: xrgb8888). This allows you to
10538 choose the bit depth of the DRM mode. xrgb8888 is your usual 24 bit per
10539 pixel/8 bits per channel packed RGB format with 8 bits of padding.
10540 xrgb2101010 is a packed 30 bits per pixel/10 bits per channel packed RGB
10541 format with 2 bits of padding.
10542 .sp
10543 There are cases when xrgb2101010 will work with the \fBdrm\fP VO, but not
10544 with the \fBdrm\fP backend for the \fBgpu\fP VO. This is because with the
10545 \fBgpu\fP VO, in addition to requiring support in your DRM driver,
10546 requires support for xrgb2101010 in your EGL driver
10547 .TP
10548 .B \fB\-\-drm\-draw\-surface\-size=<[WxH]>\fP
10549 Sets the size of the surface used on the draw plane. The surface will
10550 then be upscaled to the current screen resolution. This option can be
10551 useful when used together with the drmprime\-drm hwdec interop at high
10552 resolutions, as it allows scaling the draw plane (which in this case
10553 only handles the OSD) down to a size the GPU can handle.
10554 .sp
10555 When used without the drmprime\-drm hwdec interop this option will just
10556 cause the video to get rendered at a different resolution and then
10557 scaled to screen size.
10558 .sp
10559 Note: this option is only available with DRM atomic support.
10560 (default: display resolution)
10561 .UNINDENT
10562 .TP
10563 .B \fBmediacodec_embed\fP (Android)
10564 Renders \fBIMGFMT_MEDIACODEC\fP frames directly to an \fBandroid.view.Surface\fP\&.
10565 Requires \fB\-\-hwdec=mediacodec\fP for hardware decoding, along with
10566 \fB\-\-vo=mediacodec_embed\fP and \fB\-\-wid=(intptr_t)(*android.view.Surface)\fP\&.
10567 .sp
10568 Since this video output driver uses native decoding and rendering routines,
10569 many of mpv\(aqs features (subtitle rendering, OSD/OSC, video filters, etc)
10570 are not available with this driver.
10571 .sp
10572 To use hardware decoding with \fB\-\-vo=gpu\fP instead, use
10573 \fB\-\-hwdec=mediacodec\-copy\fP along with \fB\-\-gpu\-context=android\fP\&.
10574 .TP
10575 .B \fBwlshm\fP (Wayland only)
10576 Shared memory video output driver without hardware acceleration that works
10577 whenever Wayland is present.
10578 .sp
10579 Since mpv 0.30.0, you may need to use \fB\-\-profile=sw\-fast\fP to get decent
10580 performance.
10581 .sp
10582 \fBNOTE:\fP
10583 .INDENT 7.0
10584 .INDENT 3.5
10585 This is a fallback only, and should not be normally used.
10586 .UNINDENT
10587 .UNINDENT
10588 .UNINDENT
10589 .SH AUDIO FILTERS
10590 .sp
10591 Audio filters allow you to modify the audio stream and its properties. The
10592 syntax is:
10593 .INDENT 0.0
10594 .TP
10595 .B \fB\-\-af=...\fP
10596 Setup a chain of audio filters. See \fB\-\-vf\fP (\fI\%VIDEO FILTERS\fP) for the
10597 full syntax.
10598 .UNINDENT
10599 .sp
10600 \fBNOTE:\fP
10601 .INDENT 0.0
10602 .INDENT 3.5
10603 To get a full list of available audio filters, see \fB\-\-af=help\fP\&.
10604 .sp
10605 Also, keep in mind that most actual filters are available via the \fBlavfi\fP
10606 wrapper, which gives you access to most of libavfilter\(aqs filters. This
10607 includes all filters that have been ported from MPlayer to libavfilter.
10608 .sp
10609 The \fB\-\-vf\fP description describes how libavfilter can be used and how to
10610 workaround deprecated mpv filters.
10611 .UNINDENT
10612 .UNINDENT
10613 .sp
10614 See \fB\-\-vf\fP group of options for info on how \fB\-\-af\-defaults\fP, \fB\-\-af\-add\fP,
10615 \fB\-\-af\-pre\fP, \fB\-\-af\-del\fP, \fB\-\-af\-clr\fP, and possibly others work.
10616 .sp
10617 Available filters are:
10618 .INDENT 0.0
10619 .TP
10620 .B \fBlavcac3enc[=options]\fP
10621 Encode multi\-channel audio to AC\-3 at runtime using libavcodec. Supports
10622 16\-bit native\-endian input format, maximum 6 channels. The output is
10623 big\-endian when outputting a raw AC\-3 stream, native\-endian when
10624 outputting to S/PDIF. If the input sample rate is not 48 kHz, 44.1 kHz or
10625 32 kHz, it will be resampled to 48 kHz.
10626 .INDENT 7.0
10627 .TP
10628 .B \fBtospdif=<yes|no>\fP
10629 Output raw AC\-3 stream if \fBno\fP, output to S/PDIF for
10630 pass\-through if \fByes\fP (default).
10631 .TP
10632 .B \fBbitrate=<rate>\fP
10633 The bitrate use for the AC\-3 stream. Set it to 384 to get 384 kbps.
10634 .sp
10635 The default is 640. Some receivers might not be able to handle this.
10636 .sp
10637 Valid values: 32, 40, 48, 56, 64, 80, 96, 112, 128,
10638 160, 192, 224, 256, 320, 384, 448, 512, 576, 640.
10639 .sp
10640 The special value \fBauto\fP selects a default bitrate based on the
10641 input channel number:
10642 .INDENT 7.0
10643 .TP
10644 .B 1ch
10645 96
10646 .TP
10647 .B 2ch
10648 192
10649 .TP
10650 .B 3ch
10651 224
10652 .TP
10653 .B 4ch
10654 384
10655 .TP
10656 .B 5ch
10657 448
10658 .TP
10659 .B 6ch
10660 448
10661 .UNINDENT
10662 .TP
10663 .B \fBminch=<n>\fP
10664 If the input channel number is less than \fB<minch>\fP, the filter will
10665 detach itself (default: 3).
10666 .TP
10667 .B \fBencoder=<name>\fP
10668 Select the libavcodec encoder used. Currently, this should be an AC\-3
10669 encoder, and using another codec will fail horribly.
10670 .UNINDENT
10671 .TP
10672 .B \fBformat=format:srate:channels:out\-srate:out\-channels\fP
10673 Does not do any format conversion itself. Rather, it may cause the
10674 filter system to insert necessary conversion filters before or after this
10675 filter if needed. It is primarily useful for controlling the audio format
10676 going into other filters. To specify the format for audio output, see
10677 \fB\-\-audio\-format\fP, \fB\-\-audio\-samplerate\fP, and \fB\-\-audio\-channels\fP\&. This
10678 filter is able to force a particular format, whereas \fB\-\-audio\-*\fP
10679 may be overridden by the ao based on output compatibility.
10680 .sp
10681 All parameters are optional. The first 3 parameters restrict what the filter
10682 accepts as input. They will therefore cause conversion filters to be
10683 inserted before this one. The \fBout\-\fP parameters tell the filters or audio
10684 outputs following this filter how to interpret the data without actually
10685 doing a conversion. Setting these will probably just break things unless you
10686 really know you want this for some reason, such as testing or dealing with
10687 broken media.
10688 .INDENT 7.0
10689 .TP
10690 .B \fB<format>\fP
10691 Force conversion to this format. Use \fB\-\-af=format=format=help\fP to get
10692 a list of valid formats.
10693 .TP
10694 .B \fB<srate>\fP
10695 Force conversion to a specific sample rate. The rate is an integer,
10696 48000 for example.
10697 .TP
10698 .B \fB<channels>\fP
10699 Force mixing to a specific channel layout. See \fB\-\-audio\-channels\fP option
10700 for possible values.
10701 .UNINDENT
10702 .sp
10703 \fB<out\-srate>\fP
10704 .sp
10705 \fB<out\-channels>\fP
10706 .sp
10707 \fINOTE\fP: this filter used to be named \fBforce\fP\&. The old \fBformat\fP filter
10708 used to do conversion itself, unlike this one which lets the filter system
10709 handle the conversion.
10710 .TP
10711 .B \fBscaletempo[=option1:option2:...]\fP
10712 Scales audio tempo without altering pitch, optionally synced to playback
10713 speed (default).
10714 .sp
10715 This works by playing \(aqstride\(aq ms of audio at normal speed then consuming
10716 \(aqstride*scale\(aq ms of input audio. It pieces the strides together by
10717 blending \(aqoverlap\(aq% of stride with audio following the previous stride. It
10718 optionally performs a short statistical analysis on the next \(aqsearch\(aq ms
10719 of audio to determine the best overlap position.
10720 .INDENT 7.0
10721 .TP
10722 .B \fBscale=<amount>\fP
10723 Nominal amount to scale tempo. Scales this amount in addition to
10724 speed. (default: 1.0)
10725 .TP
10726 .B \fBstride=<amount>\fP
10727 Length in milliseconds to output each stride. Too high of a value will
10728 cause noticeable skips at high scale amounts and an echo at low scale
10729 amounts. Very low values will alter pitch. Increasing improves
10730 performance. (default: 60)
10731 .TP
10732 .B \fBoverlap=<percent>\fP
10733 Percentage of stride to overlap. Decreasing improves performance.
10734 (default: .20)
10735 .TP
10736 .B \fBsearch=<amount>\fP
10737 Length in milliseconds to search for best overlap position. Decreasing
10738 improves performance greatly. On slow systems, you will probably want
10739 to set this very low. (default: 14)
10740 .TP
10741 .B \fBspeed=<tempo|pitch|both|none>\fP
10742 Set response to speed change.
10743 .INDENT 7.0
10744 .TP
10745 .B tempo
10746 Scale tempo in sync with speed (default).
10747 .TP
10748 .B pitch
10749 Reverses effect of filter. Scales pitch without altering tempo.
10750 Add this to your \fBinput.conf\fP to step by musical semi\-tones:
10751 .INDENT 7.0
10752 .INDENT 3.5
10753 .sp
10754 .nf
10755 .ft C
10756 [ multiply speed 0.9438743126816935
10757 ] multiply speed 1.059463094352953
10758 .ft P
10759 .fi
10760 .UNINDENT
10761 .UNINDENT
10762 .sp
10763 \fBWARNING:\fP
10764 .INDENT 7.0
10765 .INDENT 3.5
10766 Loses sync with video.
10767 .UNINDENT
10768 .UNINDENT
10769 .TP
10770 .B both
10771 Scale both tempo and pitch.
10772 .TP
10773 .B none
10774 Ignore speed changes.
10775 .UNINDENT
10776 .UNINDENT
10777 .INDENT 7.0
10778 .INDENT 3.5
10779 .IP "Examples"
10780 .INDENT 0.0
10781 .TP
10782 .B \fBmpv \-\-af=scaletempo \-\-speed=1.2 media.ogg\fP
10783 Would play media at 1.2x normal speed, with audio at normal
10784 pitch. Changing playback speed would change audio tempo to match.
10785 .TP
10786 .B \fBmpv \-\-af=scaletempo=scale=1.2:speed=none \-\-speed=1.2 media.ogg\fP
10787 Would play media at 1.2x normal speed, with audio at normal
10788 pitch, but changing playback speed would have no effect on audio
10789 tempo.
10790 .TP
10791 .B \fBmpv \-\-af=scaletempo=stride=30:overlap=.50:search=10 media.ogg\fP
10792 Would tweak the quality and performance parameters.
10793 .TP
10794 .B \fBmpv \-\-af=scaletempo=scale=1.2:speed=pitch audio.ogg\fP
10795 Would play media at 1.2x normal speed, with audio at normal pitch.
10796 Changing playback speed would change pitch, leaving audio tempo at
10797 1.2x.
10798 .UNINDENT
10799 .UNINDENT
10800 .UNINDENT
10801 .TP
10802 .B \fBscaletempo2[=option1:option2:...]\fP
10803 Scales audio tempo without altering pitch.
10804 The algorithm is ported from chromium and uses the
10805 Waveform Similarity Overlap\-and\-add (WSOLA) method.
10806 It seems to achieve a higher audio quality than scaletempo and rubberband.
10807 .sp
10808 By default, the \fBsearch\-interval\fP and \fBwindow\-size\fP parameters
10809 have the same values as in chromium.
10810 .INDENT 7.0
10811 .TP
10812 .B \fBmin\-speed=<speed>\fP
10813 Mute audio if the playback speed is below \fB<speed>\fP\&. (default: 0.25)
10814 .TP
10815 .B \fBmax\-speed=<speed>\fP
10816 Mute audio if the playback speed is above \fB<speed>\fP
10817 and \fB<speed> != 0\fP\&. (default: 4.0)
10818 .TP
10819 .B \fBsearch\-interval=<amount>\fP
10820 Length in milliseconds to search for best overlap position. (default: 30)
10821 .TP
10822 .B \fBwindow\-size=<amount>\fP
10823 Length in milliseconds of the overlap\-and\-add window. (default: 20)
10824 .UNINDENT
10825 .TP
10826 .B \fBrubberband\fP
10827 High quality pitch correction with librubberband. This can be used in place
10828 of \fBscaletempo\fP, and will be used to adjust audio pitch when playing
10829 at speed different from normal. It can also be used to adjust audio pitch
10830 without changing playback speed.
10831 .INDENT 7.0
10832 .TP
10833 .B \fB<pitch\-scale>\fP
10834 Sets the pitch scaling factor. Frequencies are multiplied by this value.
10835 .UNINDENT
10836 .sp
10837 This filter has a number of additional sub\-options. You can list them with
10838 \fBmpv \-\-af=rubberband=help\fP\&. This will also show the default values
10839 for each option. The options are not documented here, because they are
10840 merely passed to librubberband. Look at the librubberband documentation
10841 to learn what each option does:
10842 \fI\%http://breakfastquay.com/rubberband/code\-doc/classRubberBand_1_1RubberBandStretcher.html\fP
10843 (The mapping of the mpv rubberband filter sub\-option names and values to
10844 those of librubberband follows a simple pattern: \fB"Option" + Name + Value\fP\&.)
10845 .sp
10846 This filter supports the following \fBaf\-command\fP commands:
10847 .INDENT 7.0
10848 .TP
10849 .B \fBset\-pitch\fP
10850 Set the \fB<pitch\-scale>\fP argument dynamically. This can be used to
10851 change the playback pitch at runtime. Note that speed is controlled
10852 using the standard \fBspeed\fP property, not \fBaf\-command\fP\&.
10853 .TP
10854 .B \fBmultiply\-pitch <factor>\fP
10855 Multiply the current value of \fB<pitch\-scale>\fP dynamically. For
10856 example: 0.5 to go down by an octave, 1.5 to go up by a perfect fifth.
10857 If you want to go up or down by semi\-tones, use 1.059463094352953 and
10858 0.9438743126816935
10859 .UNINDENT
10860 .TP
10861 .B \fBlavfi=graph\fP
10862 Filter audio using FFmpeg\(aqs libavfilter.
10863 .INDENT 7.0
10864 .TP
10865 .B \fB<graph>\fP
10866 Libavfilter graph. See \fBlavfi\fP video filter for details \- the graph
10867 syntax is the same.
10868 .sp
10869 \fBWARNING:\fP
10870 .INDENT 7.0
10871 .INDENT 3.5
10872 Don\(aqt forget to quote libavfilter graphs as described in the lavfi
10873 video filter section.
10874 .UNINDENT
10875 .UNINDENT
10876 .TP
10877 .B \fBo=<string>\fP
10878 AVOptions.
10879 .TP
10880 .B \fBfix\-pts=<yes|no>\fP
10881 Determine PTS based on sample count (default: no). If this is enabled,
10882 the player won\(aqt rely on libavfilter passing through PTS accurately.
10883 Instead, it pass a sample count as PTS to libavfilter, and compute the
10884 PTS used by mpv based on that and the input PTS. This helps with filters
10885 which output a recomputed PTS instead of the original PTS (including
10886 filters which require the PTS to start at 0). mpv normally expects
10887 filters to not touch the PTS (or only to the extent of changing frame
10888 boundaries), so this is not the default, but it will be needed to use
10889 broken filters. In practice, these broken filters will either cause slow
10890 A/V desync over time (with some files), or break playback completely if
10891 you seek or start playback from the middle of a file.
10892 .UNINDENT
10893 .TP
10894 .B \fBdrop\fP
10895 This filter drops or repeats audio frames to adapt to playback speed. It
10896 always operates on full audio frames, because it was made to handle SPDIF
10897 (compressed audio passthrough). This is used automatically if the
10898 \fB\-\-video\-sync=display\-adrop\fP option is used. Do not use this filter (or
10899 the given option); they are extremely low quality.
10900 .UNINDENT
10901 .SH VIDEO FILTERS
10902 .sp
10903 Video filters allow you to modify the video stream and its properties. All of
10904 the information described in this section applies to audio filters as well
10905 (generally using the prefix \fB\-\-af\fP instead of \fB\-\-vf\fP).
10906 .sp
10907 The exact syntax is:
10908 .INDENT 0.0
10909 .TP
10910 .B \fB\-\-vf=<filter1[=parameter1:parameter2:...],filter2,...>\fP
10911 Setup a chain of video filters. This consists on the filter name, and an
10912 option list of parameters after \fB=\fP\&. The parameters are separated by
10913 \fB:\fP (not \fB,\fP, as that starts a new filter entry).
10914 .sp
10915 Before the filter name, a label can be specified with \fB@name:\fP, where
10916 name is an arbitrary user\-given name, which identifies the filter. This
10917 is only needed if you want to toggle the filter at runtime.
10918 .sp
10919 A \fB!\fP before the filter name means the filter is disabled by default. It
10920 will be skipped on filter creation. This is also useful for runtime filter
10921 toggling.
10922 .sp
10923 See the \fBvf\fP command (and \fBtoggle\fP sub\-command) for further explanations
10924 and examples.
10925 .sp
10926 The general filter entry syntax is:
10927 .INDENT 7.0
10928 .INDENT 3.5
10929 \fB["@"<label\-name>":"] ["!"] <filter\-name> [ "=" <filter\-parameter\-list> ]\fP
10930 .UNINDENT
10931 .UNINDENT
10932 .sp
10933 or for the special "toggle" syntax (see \fBvf\fP command):
10934 .INDENT 7.0
10935 .INDENT 3.5
10936 \fB"@"<label\-name>\fP
10937 .UNINDENT
10938 .UNINDENT
10939 .sp
10940 and the \fBfilter\-parameter\-list\fP:
10941 .INDENT 7.0
10942 .INDENT 3.5
10943 \fB<filter\-parameter> | <filter\-parameter> "," <filter\-parameter\-list>\fP
10944 .UNINDENT
10945 .UNINDENT
10946 .sp
10947 and \fBfilter\-parameter\fP:
10948 .INDENT 7.0
10949 .INDENT 3.5
10950 \fB( <param\-name> "=" <param\-value> ) | <param\-value>\fP
10951 .UNINDENT
10952 .UNINDENT
10953 .sp
10954 \fBparam\-value\fP can further be quoted in \fB[\fP / \fB]\fP in case the value
10955 contains characters like \fB,\fP or \fB=\fP\&. This is used in particular with
10956 the \fBlavfi\fP filter, which uses a very similar syntax as mpv (MPlayer
10957 historically) to specify filters and their parameters.
10958 .UNINDENT
10959 .sp
10960 Filters can be manipulated at run time. You can use \fB@\fP labels as described
10961 above in combination with the \fBvf\fP command (see \fI\%COMMAND INTERFACE\fP) to get
10962 more control over this. Initially disabled filters with \fB!\fP are useful for
10963 this as well.
10964 .sp
10965 You can also set defaults for each filter. The defaults are applied before the
10966 normal filter parameters. This is deprecated and never worked for the
10967 libavfilter bridge.
10968 .INDENT 0.0
10969 .TP
10970 .B \fB\-\-vf\-defaults=<filter1[=parameter1:parameter2:...],filter2,...>\fP
10971 Set defaults for each filter. (Deprecated. \fB\-\-af\-defaults\fP is deprecated
10972 as well.)
10973 .UNINDENT
10974 .sp
10975 \fBNOTE:\fP
10976 .INDENT 0.0
10977 .INDENT 3.5
10978 To get a full list of available video filters, see \fB\-\-vf=help\fP and
10979 \fI\%http://ffmpeg.org/ffmpeg\-filters.html\fP .
10980 .sp
10981 Also, keep in mind that most actual filters are available via the \fBlavfi\fP
10982 wrapper, which gives you access to most of libavfilter\(aqs filters. This
10983 includes all filters that have been ported from MPlayer to libavfilter.
10984 .sp
10985 Most builtin filters are deprecated in some ways, unless they\(aqre only available
10986 in mpv (such as filters which deal with mpv specifics, or which are
10987 implemented in mpv only).
10988 .sp
10989 If a filter is not builtin, the \fBlavfi\-bridge\fP will be automatically
10990 tried. This bridge does not support help output, and does not verify
10991 parameters before the filter is actually used. Although the mpv syntax
10992 is rather similar to libavfilter\(aqs, it\(aqs not the same. (Which means not
10993 everything accepted by vf_lavfi\(aqs \fBgraph\fP option will be accepted by
10994 \fB\-\-vf\fP\&.)
10995 .sp
10996 You can also prefix the filter name with \fBlavfi\-\fP to force the wrapper.
10997 This is helpful if the filter name collides with a deprecated mpv builtin
10998 filter. For example \fB\-\-vf=lavfi\-scale=args\fP would use libavfilter\(aqs
10999 \fBscale\fP filter over mpv\(aqs deprecated builtin one.
11000 .UNINDENT
11001 .UNINDENT
11002 .sp
11003 Video filters are managed in lists. There are a few commands to manage the
11004 filter list.
11005 .INDENT 0.0
11006 .TP
11007 .B \fB\-\-vf\-append=filter\fP
11008 Appends the filter given as arguments to the filter list.
11009 .TP
11010 .B \fB\-\-vf\-add=filter\fP
11011 Appends the filter given as arguments to the filter list. (Passing multiple
11012 filters is currently still possible, but deprecated.)
11013 .TP
11014 .B \fB\-\-vf\-pre=filter\fP
11015 Prepends the filters given as arguments to the filter list. (Passing
11016 multiple filters is currently still possible, but deprecated.)
11017 .TP
11018 .B \fB\-\-vf\-remove=filter\fP
11019 Deletes the filter from the list. The filter can be either given the way it
11020 was added (filter name and its full argument list), or by label (prefixed
11021 with \fB@\fP). Matching of filters works as follows: if either of the compared
11022 filters has a label set, only the labels are compared. If none of the
11023 filters have a label, the filter name, arguments, and argument order are
11024 compared. (Passing multiple filters is currently still possible, but
11025 deprecated.)
11026 .TP
11027 .B \fB\-vf\-toggle=filter\fP
11028 Add the given filter to the list if it was not present yet, or remove it
11029 from the list if it was present. Matching of filters works as described in
11030 \fB\-\-vf\-remove\fP\&.
11031 .TP
11032 .B \fB\-\-vf\-del=filter\fP
11033 Sort of like \fB\-\-vf\-remove\fP, but also accepts an index number. Index
11034 numbers start at 0, negative numbers address the end of the list (\-1 is the
11035 last). Deprecated.
11036 .TP
11037 .B \fB\-\-vf\-clr\fP
11038 Completely empties the filter list.
11039 .UNINDENT
11040 .sp
11041 With filters that support it, you can access parameters by their name.
11042 .INDENT 0.0
11043 .TP
11044 .B \fB\-\-vf=<filter>=help\fP
11045 Prints the parameter names and parameter value ranges for a particular
11046 filter.
11047 .UNINDENT
11048 .sp
11049 Available mpv\-only filters are:
11050 .INDENT 0.0
11051 .TP
11052 .B \fBformat=fmt=<value>:colormatrix=<value>:...\fP
11053 Applies video parameter overrides, with optional conversion. By default,
11054 this overrides the video\(aqs parameters without conversion (except for the
11055 \fBfmt\fP parameter), but can be made to perform an appropriate conversion
11056 with \fBconvert=yes\fP for parameters for which conversion is supported.
11057 .INDENT 7.0
11058 .TP
11059 .B \fB<fmt>\fP
11060 Image format name, e.g. rgb15, bgr24, 420p, etc. (default: don\(aqt change).
11061 .sp
11062 This filter always performs conversion to the given format.
11063 .sp
11064 \fBNOTE:\fP
11065 .INDENT 7.0
11066 .INDENT 3.5
11067 For a list of available formats, use \fB\-\-vf=format=fmt=help\fP\&.
11068 .UNINDENT
11069 .UNINDENT
11070 .TP
11071 .B \fB<convert=yes|no>\fP
11072 Force conversion of color parameters (default: no).
11073 .sp
11074 If this is disabled (the default), the only conversion that is possibly
11075 performed is format conversion if \fB<fmt>\fP is set. All other parameters
11076 (like \fB<colormatrix>\fP) are forced without conversion. This mode is
11077 typically useful when files have been incorrectly tagged.
11078 .sp
11079 If this is enabled, libswscale or zimg is used if any of the parameters
11080 mismatch. zimg is used of the input/output image formats are supported
11081 by mpv\(aqs zimg wrapper, and if \fB\-\-sws\-allow\-zimg=yes\fP is used. Both
11082 libraries may not support all kinds of conversions. This typically
11083 results in silent incorrect conversion. zimg has in many cases a better
11084 chance of performing the conversion correctly.
11085 .sp
11086 In both cases, the color parameters are set on the output stage of the
11087 image format conversion (if \fBfmt\fP was set). The difference is that
11088 with \fBconvert=no\fP, the color parameters are not passed on to the
11089 converter.
11090 .sp
11091 If input and output video parameters are the same, conversion is always
11092 skipped.
11093 .INDENT 7.0
11094 .INDENT 3.5
11095 .IP "Examples"
11096 .INDENT 0.0
11097 .TP
11098 .B \fBmpv test.mkv \-\-vf=format:colormatrix=ycgco\fP
11099 Results in incorrect colors (if test.mkv was tagged correctly).
11100 .TP
11101 .B \fBmpv test.mkv \-\-vf=format:colormatrix=ycgco:convert=yes \-\-sws\-allow\-zimg\fP
11102 Results in true conversion to \fBycgco\fP, assuming the renderer
11103 supports it (\fB\-\-vo=gpu\fP normally does). You can add \fB\-\-vo=xv\fP
11104 to force a VO which definitely does not support it, which should
11105 show incorrect colors as confirmation.
11106 .sp
11107 Using \fB\-\-sws\-allow\-zimg=no\fP (or disabling zimg at build time)
11108 will use libswscale, which cannot perform this conversion as
11109 of this writing.
11110 .UNINDENT
11111 .UNINDENT
11112 .UNINDENT
11113 .TP
11114 .B \fB<colormatrix>\fP
11115 Controls the YUV to RGB color space conversion when playing video. There
11116 are various standards. Normally, BT.601 should be used for SD video, and
11117 BT.709 for HD video. (This is done by default.) Using incorrect color space
11118 results in slightly under or over saturated and shifted colors.
11119 .sp
11120 These options are not always supported. Different video outputs provide
11121 varying degrees of support. The \fBgpu\fP and \fBvdpau\fP video output
11122 drivers usually offer full support. The \fBxv\fP output can set the color
11123 space if the system video driver supports it, but not input and output
11124 levels. The \fBscale\fP video filter can configure color space and input
11125 levels, but only if the output format is RGB (if the video output driver
11126 supports RGB output, you can force this with \fB\-vf scale,format=rgba\fP).
11127 .sp
11128 If this option is set to \fBauto\fP (which is the default), the video\(aqs
11129 color space flag will be used. If that flag is unset, the color space
11130 will be selected automatically. This is done using a simple heuristic that
11131 attempts to distinguish SD and HD video. If the video is larger than
11132 1279x576 pixels, BT.709 (HD) will be used; otherwise BT.601 (SD) is
11133 selected.
11134 .sp
11135 Available color spaces are:
11136 .INDENT 7.0
11137 .TP
11138 .B auto
11139 automatic selection (default)
11140 .TP
11141 .B bt.601
11142 ITU\-R BT.601 (SD)
11143 .TP
11144 .B bt.709
11145 ITU\-R BT.709 (HD)
11146 .TP
11147 .B bt.2020\-ncl
11148 ITU\-R BT.2020 non\-constant luminance system
11149 .TP
11150 .B bt.2020\-cl
11151 ITU\-R BT.2020 constant luminance system
11152 .TP
11153 .B smpte\-240m
11154 SMPTE\-240M
11155 .UNINDENT
11156 .TP
11157 .B \fB<colorlevels>\fP
11158 YUV color levels used with YUV to RGB conversion. This option is only
11159 necessary when playing broken files which do not follow standard color
11160 levels or which are flagged wrong. If the video does not specify its
11161 color range, it is assumed to be limited range.
11162 .sp
11163 The same limitations as with \fB<colormatrix>\fP apply.
11164 .sp
11165 Available color ranges are:
11166 .INDENT 7.0
11167 .TP
11168 .B auto
11169 automatic selection (normally limited range) (default)
11170 .TP
11171 .B limited
11172 limited range (16\-235 for luma, 16\-240 for chroma)
11173 .TP
11174 .B full
11175 full range (0\-255 for both luma and chroma)
11176 .UNINDENT
11177 .TP
11178 .B \fB<primaries>\fP
11179 RGB primaries the source file was encoded with. Normally this should be set
11180 in the file header, but when playing broken or mistagged files this can be
11181 used to override the setting.
11182 .sp
11183 This option only affects video output drivers that perform color
11184 management, for example \fBgpu\fP with the \fBtarget\-prim\fP or
11185 \fBicc\-profile\fP suboptions set.
11186 .sp
11187 If this option is set to \fBauto\fP (which is the default), the video\(aqs
11188 primaries flag will be used. If that flag is unset, the color space will
11189 be selected automatically, using the following heuristics: If the
11190 \fB<colormatrix>\fP is set or determined as BT.2020 or BT.709, the
11191 corresponding primaries are used. Otherwise, if the video height is
11192 exactly 576 (PAL), BT.601\-625 is used. If it\(aqs exactly 480 or 486 (NTSC),
11193 BT.601\-525 is used. If the video resolution is anything else, BT.709 is
11194 used.
11195 .sp
11196 Available primaries are:
11197 .INDENT 7.0
11198 .TP
11199 .B auto
11200 automatic selection (default)
11201 .TP
11202 .B bt.601\-525
11203 ITU\-R BT.601 (SD) 525\-line systems (NTSC, SMPTE\-C)
11204 .TP
11205 .B bt.601\-625
11206 ITU\-R BT.601 (SD) 625\-line systems (PAL, SECAM)
11207 .TP
11208 .B bt.709
11209 ITU\-R BT.709 (HD) (same primaries as sRGB)
11210 .TP
11211 .B bt.2020
11212 ITU\-R BT.2020 (UHD)
11213 .TP
11214 .B apple
11215 Apple RGB
11216 .TP
11217 .B adobe
11218 Adobe RGB (1998)
11219 .TP
11220 .B prophoto
11221 ProPhoto RGB (ROMM)
11222 .TP
11223 .B cie1931
11224 CIE 1931 RGB
11225 .TP
11226 .B dci\-p3
11227 DCI\-P3 (Digital Cinema)
11228 .TP
11229 .B v\-gamut
11230 Panasonic V\-Gamut primaries
11231 .UNINDENT
11232 .TP
11233 .B \fB<gamma>\fP
11234 Gamma function the source file was encoded with. Normally this should be set
11235 in the file header, but when playing broken or mistagged files this can be
11236 used to override the setting.
11237 .sp
11238 This option only affects video output drivers that perform color management.
11239 .sp
11240 If this option is set to \fBauto\fP (which is the default), the gamma will
11241 be set to BT.1886 for YCbCr content, sRGB for RGB content and Linear for
11242 XYZ content.
11243 .sp
11244 Available gamma functions are:
11245 .INDENT 7.0
11246 .TP
11247 .B auto
11248 automatic selection (default)
11249 .TP
11250 .B bt.1886
11251 ITU\-R BT.1886 (EOTF corresponding to BT.601/BT.709/BT.2020)
11252 .TP
11253 .B srgb
11254 IEC 61966\-2\-4 (sRGB)
11255 .TP
11256 .B linear
11257 Linear light
11258 .TP
11259 .B gamma1.8
11260 Pure power curve (gamma 1.8)
11261 .TP
11262 .B gamma2.0
11263 Pure power curve (gamma 2.0)
11264 .TP
11265 .B gamma2.2
11266 Pure power curve (gamma 2.2)
11267 .TP
11268 .B gamma2.4
11269 Pure power curve (gamma 2.4)
11270 .TP
11271 .B gamma2.6
11272 Pure power curve (gamma 2.6)
11273 .TP
11274 .B gamma2.8
11275 Pure power curve (gamma 2.8)
11276 .TP
11277 .B prophoto
11278 ProPhoto RGB (ROMM) curve
11279 .TP
11280 .B pq
11281 ITU\-R BT.2100 PQ (Perceptual quantizer) curve
11282 .TP
11283 .B hlg
11284 ITU\-R BT.2100 HLG (Hybrid Log\-gamma) curve
11285 .TP
11286 .B v\-log
11287 Panasonic V\-Log transfer curve
11288 .TP
11289 .B s\-log1
11290 Sony S\-Log1 transfer curve
11291 .TP
11292 .B s\-log2
11293 Sony S\-Log2 transfer curve
11294 .UNINDENT
11295 .TP
11296 .B \fB<sig\-peak>\fP
11297 Reference peak illumination for the video file, relative to the
11298 signal\(aqs reference white level. This is mostly interesting for HDR, but
11299 it can also be used tone map SDR content to simulate a different
11300 exposure. Normally inferred from tags such as MaxCLL or mastering
11301 metadata.
11302 .sp
11303 The default of 0.0 will default to the source\(aqs nominal peak luminance.
11304 .TP
11305 .B \fB<light>\fP
11306 .INDENT 7.0
11307 .INDENT 3.5
11308 Light type of the scene. This is mostly correctly inferred based on the
11309 gamma function, but it can be useful to override this when viewing raw
11310 camera footage (e.g. V\-Log), which is normally scene\-referred instead
11311 of display\-referred.
11312 .sp
11313 Available light types are:
11314 .UNINDENT
11315 .UNINDENT
11316 .INDENT 7.0
11317 .TP
11318 .B auto
11319 Automatic selection (default)
11320 .TP
11321 .B display
11322 Display\-referred light (most content)
11323 .TP
11324 .B hlg
11325 Scene\-referred using the HLG OOTF (e.g. HLG content)
11326 .TP
11327 .B 709\-1886
11328 Scene\-referred using the BT709+BT1886 interaction
11329 .TP
11330 .B gamma1.2
11331 Scene\-referred using a pure power OOTF (gamma=1.2)
11332 .UNINDENT
11333 .TP
11334 .B \fB<stereo\-in>\fP
11335 Set the stereo mode the video is assumed to be encoded in. Use
11336 \fB\-\-vf format:stereo\-in=help\fP to list all available modes. Check with
11337 the \fBstereo3d\fP filter documentation to see what the names mean.
11338 .TP
11339 .B \fB<stereo\-out>\fP
11340 Set the stereo mode the video should be displayed as. Takes the
11341 same values as the \fBstereo\-in\fP option.
11342 .TP
11343 .B \fB<rotate>\fP
11344 Set the rotation the video is assumed to be encoded with in degrees.
11345 The special value \fB\-1\fP uses the input format.
11346 .TP
11347 .B \fB<w>\fP, \fB<h>\fP
11348 If not 0, perform conversion to the given size. Ignored if
11349 \fBconvert=yes\fP is not set.
11350 .TP
11351 .B \fB<dw>\fP, \fB<dh>\fP
11352 Set the display size. Note that setting the display size such that
11353 the video is scaled in both directions instead of just changing the
11354 aspect ratio is an implementation detail, and might change later.
11355 .TP
11356 .B \fB<dar>\fP
11357 Set the display aspect ratio of the video frame. This is a float,
11358 but values such as \fB[16:9]\fP can be passed too (\fB[...]\fP for quoting
11359 to prevent the option parser from interpreting the \fB:\fP character).
11360 .TP
11361 .B \fB<force\-scaler=auto|zimg|sws>\fP
11362 Force a specific scaler backend, if applicable. This is a debug option
11363 and could go away any time.
11364 .TP
11365 .B \fB<alpha=auto|straight|premul>\fP
11366 Set the kind of alpha the video uses. Undefined effect if the image
11367 format has no alpha channel (could be ignored or cause an error,
11368 depending on how mpv internals evolve). Setting this may or may not
11369 cause downstream image processing to treat alpha differently, depending
11370 on support. With \fBconvert\fP and zimg used, this will convert the alpha.
11371 libswscale and other FFmpeg components completely ignore this.
11372 .UNINDENT
11373 .TP
11374 .B \fBlavfi=graph[:sws\-flags[:o=opts]]\fP
11375 Filter video using FFmpeg\(aqs libavfilter.
11376 .INDENT 7.0
11377 .TP
11378 .B \fB<graph>\fP
11379 The libavfilter graph string. The filter must have a single video input
11380 pad and a single video output pad.
11381 .sp
11382 See \fI\%https://ffmpeg.org/ffmpeg\-filters.html\fP for syntax and available
11383 filters.
11384 .sp
11385 \fBWARNING:\fP
11386 .INDENT 7.0
11387 .INDENT 3.5
11388 If you want to use the full filter syntax with this option, you have
11389 to quote the filter graph in order to prevent mpv\(aqs syntax and the
11390 filter graph syntax from clashing. To prevent a quoting and escaping
11391 mess, consider using \fB\-\-lavfi\-complex\fP if you know which video
11392 track you want to use from the input file. (There is only one video
11393 track for nearly all video files anyway.)
11394 .UNINDENT
11395 .UNINDENT
11396 .INDENT 7.0
11397 .INDENT 3.5
11398 .IP "Examples"
11399 .INDENT 0.0
11400 .TP
11401 .B \fB\-\-vf=lavfi=[gradfun=20:30,vflip]\fP
11402 \fBgradfun\fP filter with nonsense parameters, followed by a
11403 \fBvflip\fP filter. (This demonstrates how libavfilter takes a
11404 graph and not just a single filter.) The filter graph string is
11405 quoted with \fB[\fP and \fB]\fP\&. This requires no additional quoting
11406 or escaping with some shells (like bash), while others (like
11407 zsh) require additional \fB"\fP quotes around the option string.
11408 .TP
11409 .B \fB\(aq\-\-vf=lavfi="gradfun=20:30,vflip"\(aq\fP
11410 Same as before, but uses quoting that should be safe with all
11411 shells. The outer \fB\(aq\fP quotes make sure that the shell does not
11412 remove the \fB"\fP quotes needed by mpv.
11413 .TP
11414 .B \fB\(aq\-\-vf=lavfi=graph="gradfun=radius=30:strength=20,vflip"\(aq\fP
11415 Same as before, but uses named parameters for everything.
11416 .UNINDENT
11417 .UNINDENT
11418 .UNINDENT
11419 .TP
11420 .B \fB<sws\-flags>\fP
11421 If libavfilter inserts filters for pixel format conversion, this
11422 option gives the flags which should be passed to libswscale. This
11423 option is numeric and takes a bit\-wise combination of \fBSWS_\fP flags.
11424 .sp
11425 See \fBhttp://git.videolan.org/?p=ffmpeg.git;a=blob;f=libswscale/swscale.h\fP\&.
11426 .TP
11427 .B \fB<o>\fP
11428 Set AVFilterGraph options. These should be documented by FFmpeg.
11429 .INDENT 7.0
11430 .INDENT 3.5
11431 .IP "Example"
11432 .INDENT 0.0
11433 .TP
11434 .B \fB\(aq\-\-vf=lavfi=yadif:o="threads=2,thread_type=slice"\(aq\fP
11435 forces a specific threading configuration.
11436 .UNINDENT
11437 .UNINDENT
11438 .UNINDENT
11439 .UNINDENT
11440 .TP
11441 .B \fBsub=[=bottom\-margin:top\-margin]\fP
11442 Moves subtitle rendering to an arbitrary point in the filter chain, or force
11443 subtitle rendering in the video filter as opposed to using video output OSD
11444 support.
11445 .INDENT 7.0
11446 .TP
11447 .B \fB<bottom\-margin>\fP
11448 Adds a black band at the bottom of the frame. The SSA/ASS renderer can
11449 place subtitles there (with \fB\-\-sub\-use\-margins\fP).
11450 .TP
11451 .B \fB<top\-margin>\fP
11452 Black band on the top for toptitles (with \fB\-\-sub\-use\-margins\fP).
11453 .UNINDENT
11454 .INDENT 7.0
11455 .INDENT 3.5
11456 .IP "Examples"
11457 .INDENT 0.0
11458 .TP
11459 .B \fB\-\-vf=sub,eq\fP
11460 Moves sub rendering before the eq filter. This will put both
11461 subtitle colors and video under the influence of the video equalizer
11462 settings.
11463 .UNINDENT
11464 .UNINDENT
11465 .UNINDENT
11466 .TP
11467 .B \fBvapoursynth=file:buffered\-frames:concurrent\-frames\fP
11468 Loads a VapourSynth filter script. This is intended for streamed
11469 processing: mpv actually provides a source filter, instead of using a
11470 native VapourSynth video source. The mpv source will answer frame
11471 requests only within a small window of frames (the size of this window
11472 is controlled with the \fBbuffered\-frames\fP parameter), and requests outside
11473 of that will return errors. As such, you can\(aqt use the full power of
11474 VapourSynth, but you can use certain filters.
11475 .sp
11476 \fBWARNING:\fP
11477 .INDENT 7.0
11478 .INDENT 3.5
11479 Do not use this filter, unless you have expert knowledge in VapourSynth,
11480 and know how to fix bugs in the mpv VapourSynth wrapper code.
11481 .UNINDENT
11482 .UNINDENT
11483 .sp
11484 If you just want to play video generated by VapourSynth (i.e. using
11485 a native VapourSynth video source), it\(aqs better to use \fBvspipe\fP and a
11486 pipe or FIFO to feed the video to mpv. The same applies if the filter script
11487 requires random frame access (see \fBbuffered\-frames\fP parameter).
11488 .INDENT 7.0
11489 .TP
11490 .B \fBfile\fP
11491 Filename of the script source. Currently, this is always a python
11492 script (\fB\&.vpy\fP in VapourSynth convention).
11493 .sp
11494 The variable \fBvideo_in\fP is set to the mpv video source, and it is
11495 expected that the script reads video from it. (Otherwise, mpv will
11496 decode no video, and the video packet queue will overflow, eventually
11497 leading to only audio playing, or worse.)
11498 .sp
11499 The filter graph created by the script is also expected to pass through
11500 timestamps using the \fB_DurationNum\fP and \fB_DurationDen\fP frame
11501 properties.
11502 .sp
11503 See the end of the option list for a full list of script variables
11504 defined by mpv.
11505 .INDENT 7.0
11506 .INDENT 3.5
11507 .IP "Example:"
11508 .INDENT 0.0
11509 .INDENT 3.5
11510 .sp
11511 .nf
11512 .ft C
11513 import vapoursynth as vs
11514 core = vs.get_core()
11515 core.std.AddBorders(video_in, 10, 10, 20, 20).set_output()
11516 .ft P
11517 .fi
11518 .UNINDENT
11519 .UNINDENT
11520 .UNINDENT
11521 .UNINDENT
11522 .sp
11523 \fBWARNING:\fP
11524 .INDENT 7.0
11525 .INDENT 3.5
11526 The script will be reloaded on every seek. This is done to reset
11527 the filter properly on discontinuities.
11528 .UNINDENT
11529 .UNINDENT
11530 .TP
11531 .B \fBbuffered\-frames\fP
11532 Maximum number of decoded video frames that should be buffered before
11533 the filter (default: 4). This specifies the maximum number of frames
11534 the script can request in backward direction.
11535 .sp
11536 E.g. if \fBbuffered\-frames=5\fP, and the script just requested frame 15,
11537 it can still request frame 10, but frame 9 is not available anymore.
11538 If it requests frame 30, mpv will decode 15 more frames, and keep only
11539 frames 25\-30.
11540 .sp
11541 The only reason why this buffer exists is to serve the random access
11542 requests the VapourSynth filter can make.
11543 .sp
11544 The VapourSynth API has a \fBgetFrameAsync\fP function, which takes an
11545 absolute frame number. Source filters must respond to all requests. For
11546 example, a source filter can request frame 2432, and then frame 3.
11547 Source filters typically implement this by pre\-indexing the entire
11548 file.
11549 .sp
11550 mpv on the other hand is stream oriented, and does not allow filters to
11551 seek. (And it would not make sense to allow it, because it would ruin
11552 performance.) Filters get frames sequentially in playback direction, and
11553 cannot request them out of order.
11554 .sp
11555 To compensate for this mismatch, mpv allows the filter to access frames
11556 within a certain window. \fBbuffered\-frames\fP controls the size of this
11557 window. Most VapourSynth filters happen to work with this, because mpv
11558 requests frames sequentially increasing from it, and most filters only
11559 require frames "close" to the requested frame.
11560 .sp
11561 If the filter requests a frame that has a higher frame number than the
11562 highest buffered frame, new frames will be decoded until the requested
11563 frame number is reached. Excessive frames will be flushed out in a FIFO
11564 manner (there are only at most \fBbuffered\-frames\fP in this buffer).
11565 .sp
11566 If the filter requests a frame that has a lower frame number than the
11567 lowest buffered frame, the request cannot be satisfied, and an error
11568 is returned to the filter. This kind of error is not supposed to happen
11569 in a "proper" VapourSynth environment. What exactly happens depends on
11570 the filters involved.
11571 .sp
11572 Increasing this buffer will not improve performance. Rather, it will
11573 waste memory, and slow down seeks (when enough frames to fill the buffer
11574 need to be decoded at once). It is only needed to prevent the error
11575 described in the previous paragraph.
11576 .sp
11577 How many frames a filter requires depends on filter implementation
11578 details, and mpv has no way of knowing. A scale filter might need only
11579 1 frame, an interpolation filter may require a small number of frames,
11580 and the \fBReverse\fP filter will require an infinite number of frames.
11581 .sp
11582 If you want reliable operation to the full extend VapourSynth is
11583 capable, use \fBvspipe\fP\&.
11584 .sp
11585 The actual number of buffered frames also depends on the value of the
11586 \fBconcurrent\-frames\fP option. Currently, both option values are
11587 multiplied to get the final buffer size.
11588 .TP
11589 .B \fBconcurrent\-frames\fP
11590 Number of frames that should be requested in parallel. The
11591 level of concurrency depends on the filter and how quickly mpv can
11592 decode video to feed the filter. This value should probably be
11593 proportional to the number of cores on your machine. Most time,
11594 making it higher than the number of cores can actually make it
11595 slower.
11596 .sp
11597 Technically, mpv will call the VapourSynth \fBgetFrameAsync\fP function
11598 in a loop, until there are \fBconcurrent\-frames\fP frames that have not
11599 been returned by the filter yet. This also assumes that the rest of the
11600 mpv filter chain reads the output of the \fBvapoursynth\fP filter quickly
11601 enough. (For example, if you pause the player, filtering will stop very
11602 soon, because the filtered frames are waiting in a queue.)
11603 .sp
11604 Actual concurrency depends on many other factors.
11605 .sp
11606 By default, this uses the special value \fBauto\fP, which sets the option
11607 to the number of detected logical CPU cores.
11608 .UNINDENT
11609 .sp
11610 The following \fB\&.vpy\fP script variables are defined by mpv:
11611 .INDENT 7.0
11612 .TP
11613 .B \fBvideo_in\fP
11614 The mpv video source as vapoursynth clip. Note that this has an
11615 incorrect (very high) length set, which confuses many filters. This is
11616 necessary, because the true number of frames is unknown. You can use the
11617 \fBTrim\fP filter on the clip to reduce the length.
11618 .TP
11619 .B \fBvideo_in_dw\fP, \fBvideo_in_dh\fP
11620 Display size of the video. Can be different from video size if the
11621 video does not use square pixels (e.g. DVD).
11622 .TP
11623 .B \fBcontainer_fps\fP
11624 FPS value as reported by file headers. This value can be wrong or
11625 completely broken (e.g. 0 or NaN). Even if the value is correct,
11626 if another filter changes the real FPS (by dropping or inserting
11627 frames), the value of this variable will not be useful. Note that
11628 the \fB\-\-fps\fP command line option overrides this value.
11629 .sp
11630 Useful for some filters which insist on having a FPS.
11631 .TP
11632 .B \fBdisplay_fps\fP
11633 Refresh rate of the current display. Note that this value can be 0.
11634 .UNINDENT
11635 .TP
11636 .B \fBvavpp\fP
11637 VA\-API video post processing. Requires the system to support VA\-API,
11638 i.e. Linux/BSD only. Works with \fB\-\-vo=vaapi\fP and \fB\-\-vo=gpu\fP only.
11639 Currently deinterlaces. This filter is automatically inserted if
11640 deinterlacing is requested (either using the \fBd\fP key, by default mapped to
11641 the command \fBcycle deinterlace\fP, or the \fB\-\-deinterlace\fP option).
11642 .INDENT 7.0
11643 .TP
11644 .B \fBdeint=<method>\fP
11645 Select the deinterlacing algorithm.
11646 .INDENT 7.0
11647 .TP
11648 .B no
11649 Don\(aqt perform deinterlacing.
11650 .TP
11651 .B auto
11652 Select the best quality deinterlacing algorithm (default). This
11653 goes by the order of the options as documented, with
11654 \fBmotion\-compensated\fP being considered best quality.
11655 .TP
11656 .B first\-field
11657 Show only first field.
11658 .TP
11659 .B bob
11660 bob deinterlacing.
11661 .TP
11662 .B weave, motion\-adaptive, motion\-compensated
11663 Advanced deinterlacing algorithms. Whether these actually work
11664 depends on the GPU hardware, the GPU drivers, driver bugs, and
11665 mpv bugs.
11666 .UNINDENT
11667 .TP
11668 .B \fB<interlaced\-only>\fP
11669 .INDENT 7.0
11670 .TP
11671 .B no
11672 Deinterlace all frames (default).
11673 .TP
11674 .B yes
11675 Only deinterlace frames marked as interlaced.
11676 .UNINDENT
11677 .TP
11678 .B \fBreversal\-bug=<yes|no>\fP
11679 .INDENT 7.0
11680 .TP
11681 .B no
11682 Use the API as it was interpreted by older Mesa drivers. While
11683 this interpretation was more obvious and inuitive, it was
11684 apparently wrong, and not shared by Intel driver developers.
11685 .TP
11686 .B yes
11687 Use Intel interpretation of surface forward and backwards
11688 references (default). This is what Intel drivers and newer Mesa
11689 drivers expect. Matters only for the advanced deinterlacing
11690 algorithms.
11691 .UNINDENT
11692 .UNINDENT
11693 .TP
11694 .B \fBvdpaupp\fP
11695 VDPAU video post processing. Works with \fB\-\-vo=vdpau\fP and \fB\-\-vo=gpu\fP
11696 only. This filter is automatically inserted if deinterlacing is requested
11697 (either using the \fBd\fP key, by default mapped to the command
11698 \fBcycle deinterlace\fP, or the \fB\-\-deinterlace\fP option). When enabling
11699 deinterlacing, it is always preferred over software deinterlacer filters
11700 if the \fBvdpau\fP VO is used, and also if \fBgpu\fP is used and hardware
11701 decoding was activated at least once (i.e. vdpau was loaded).
11702 .INDENT 7.0
11703 .TP
11704 .B \fBsharpen=<\-1\-1>\fP
11705 For positive values, apply a sharpening algorithm to the video, for
11706 negative values a blurring algorithm (default: 0).
11707 .TP
11708 .B \fBdenoise=<0\-1>\fP
11709 Apply a noise reduction algorithm to the video (default: 0; no noise
11710 reduction).
11711 .TP
11712 .B \fBdeint=<yes|no>\fP
11713 Whether deinterlacing is enabled (default: no). If enabled, it will use
11714 the mode selected with \fBdeint\-mode\fP\&.
11715 .TP
11716 .B \fBdeint\-mode=<first\-field|bob|temporal|temporal\-spatial>\fP
11717 Select deinterlacing mode (default: temporal).
11718 .sp
11719 Note that there\(aqs currently a mechanism that allows the \fBvdpau\fP VO to
11720 change the \fBdeint\-mode\fP of auto\-inserted \fBvdpaupp\fP filters. To avoid
11721 confusion, it\(aqs recommended not to use the \fB\-\-vo=vdpau\fP suboptions
11722 related to filtering.
11723 .INDENT 7.0
11724 .TP
11725 .B first\-field
11726 Show only first field.
11727 .TP
11728 .B bob
11729 Bob deinterlacing.
11730 .TP
11731 .B temporal
11732 Motion\-adaptive temporal deinterlacing. May lead to A/V desync
11733 with slow video hardware and/or high resolution.
11734 .TP
11735 .B temporal\-spatial
11736 Motion\-adaptive temporal deinterlacing with edge\-guided spatial
11737 interpolation. Needs fast video hardware.
11738 .UNINDENT
11739 .TP
11740 .B \fBchroma\-deint\fP
11741 Makes temporal deinterlacers operate both on luma and chroma (default).
11742 Use no\-chroma\-deint to solely use luma and speed up advanced
11743 deinterlacing. Useful with slow video memory.
11744 .TP
11745 .B \fBpullup\fP
11746 Try to apply inverse telecine, needs motion adaptive temporal
11747 deinterlacing.
11748 .TP
11749 .B \fBinterlaced\-only=<yes|no>\fP
11750 If \fByes\fP, only deinterlace frames marked as interlaced (default: no).
11751 .TP
11752 .B \fBhqscaling=<0\-9>\fP
11753 .INDENT 7.0
11754 .TP
11755 .B 0
11756 Use default VDPAU scaling (default).
11757 .TP
11758 .B 1\-9
11759 Apply high quality VDPAU scaling (needs capable hardware).
11760 .UNINDENT
11761 .UNINDENT
11762 .TP
11763 .B \fBd3d11vpp\fP
11764 Direct3D 11 video post processing. Currently requires D3D11 hardware
11765 decoding for use.
11766 .INDENT 7.0
11767 .TP
11768 .B \fBdeint=<yes|no>\fP
11769 Whether deinterlacing is enabled (default: no).
11770 .TP
11771 .B \fBinterlaced\-only=<yes|no>\fP
11772 If \fByes\fP, only deinterlace frames marked as interlaced (default: no).
11773 .TP
11774 .B \fBmode=<blend|bob|adaptive|mocomp|ivctc|none>\fP
11775 Tries to select a video processor with the given processing capability.
11776 If a video processor supports multiple capabilities, it is not clear
11777 which algorithm is actually selected. \fBnone\fP always falls back. On
11778 most if not all hardware, this option will probably do nothing, because
11779 a video processor usually supports all modes or none.
11780 .UNINDENT
11781 .TP
11782 .B \fBfingerprint=...\fP
11783 Compute video frame fingerprints and provide them as metadata. Actually, it
11784 currently barely deserved to be called \fBfingerprint\fP, because it does not
11785 compute "proper" fingerprints, only tiny downscaled images (but which can be
11786 used to compute image hashes or for similarity matching).
11787 .sp
11788 The main purpose of this filter is to support the \fBskip\-logo.lua\fP script.
11789 If this script is dropped, or mpv ever gains a way to load user\-defined
11790 filters (other than VapourSynth), this filter will be removed. Due to the
11791 "special" nature of this filter, it will be removed without warning.
11792 .sp
11793 The intended way to read from the filter is using \fBvf\-metadata\fP (also
11794 see \fBclear\-on\-query\fP filter parameter). The property will return a list
11795 of key/value pairs as follows:
11796 .INDENT 7.0
11797 .INDENT 3.5
11798 .sp
11799 .nf
11800 .ft C
11801 fp0.pts = 1.2345
11802 fp0.hex = 1234abcdef...bcde
11803 fp1.pts = 1.4567
11804 fp1.hex = abcdef1234...6789
11805 \&...
11806 fpN.pts = ...
11807 fpN.hex = ...
11808 type = gray\-hex\-16x16
11809 .ft P
11810 .fi
11811 .UNINDENT
11812 .UNINDENT
11813 .sp
11814 Each \fBfp<N>\fP entry is for a frame. The \fBpts\fP entry specifies the
11815 timestamp of the frame (within the filter chain; in simple cases this is
11816 the same as the display timestamp). The \fBhex\fP field is the hex encoded
11817 fingerprint, whose size and meaning depend on the \fBtype\fP filter option.
11818 The \fBtype\fP field has the same value as the option the filter was created
11819 with.
11820 .sp
11821 This returns the frames that were filtered since the last query of the
11822 property. If \fBclear\-on\-query=no\fP was set, a query doesn\(aqt reset the list
11823 of frames. In both cases, a maximum of 10 frames is returned. If there are
11824 more frames, the oldest frames are discarded. Frames are returned in filter
11825 order.
11826 .sp
11827 (This doesn\(aqt return a structured list for the per\-frame details because the
11828 internals of the \fBvf\-metadata\fP mechanism suck. The returned format may
11829 change in the future.)
11830 .sp
11831 This filter uses zimg for speed and profit. However, it will fallback to
11832 libswscale in a number of situations: lesser pixel formats, unaligned data
11833 pointers or strides, or if zimg fails to initialize for unknown reasons. In
11834 these cases, the filter will use more CPU. Also, it will output different
11835 fingerprints, because libswscale cannot perform the full range expansion we
11836 normally request from zimg. As a consequence, the filter may be slower and
11837 not work correctly in random situations.
11838 .INDENT 7.0
11839 .TP
11840 .B \fBtype=...\fP
11841 What fingerprint to compute. Available types are:
11842 .INDENT 7.0
11843 .TP
11844 .B gray\-hex\-8x8
11845 grayscale, 8 bit, 8x8 size
11846 .TP
11847 .B gray\-hex\-16x16
11848 grayscale, 8 bit, 16x16 size (default)
11849 .UNINDENT
11850 .sp
11851 Both types simply remove all colors, downscale the image, concatenate
11852 all pixel values to a byte array, and convert the array to a hex string.
11853 .TP
11854 .B \fBclear\-on\-query=yes|no\fP
11855 Clear the list of frame fingerprints if the \fBvf\-metadata\fP property for
11856 this filter is queried (default: yes). This requires some care by the
11857 user. Some types of accesses might query the filter multiple times,
11858 which leads to lost frames.
11859 .TP
11860 .B \fBprint=yes|no\fP
11861 Print computed fingerprints the the terminal (default: no). This is
11862 mostly for testing and such. Scripts should use \fBvf\-metadata\fP to
11863 read information from this filter instead.
11864 .UNINDENT
11865 .TP
11866 .B \fBgpu=...\fP
11867 Convert video to RGB using the OpenGL renderer normally used with
11868 \fB\-\-vo=gpu\fP\&. This requires that the EGL implementation supports off\-screen
11869 rendering on the default display. (This is the case with Mesa.)
11870 .sp
11871 Sub\-options:
11872 .INDENT 7.0
11873 .TP
11874 .B \fBw=<pixels>\fP, \fBh=<pixels>\fP
11875 Size of the output in pixels (default: 0). If not positive, this will
11876 use the size of the first filtered input frame.
11877 .UNINDENT
11878 .sp
11879 \fBWARNING:\fP
11880 .INDENT 7.0
11881 .INDENT 3.5
11882 This is highly experimental. Performance is bad, and it will not work
11883 everywhere in the first place. Some features are not supported.
11884 .UNINDENT
11885 .UNINDENT
11886 .sp
11887 \fBWARNING:\fP
11888 .INDENT 7.0
11889 .INDENT 3.5
11890 This does not do OSD rendering. If you see OSD, then it has been
11891 rendered by the VO backend. (Subtitles are rendered by the \fBgpu\fP
11892 filter, if possible.)
11893 .UNINDENT
11894 .UNINDENT
11895 .sp
11896 \fBWARNING:\fP
11897 .INDENT 7.0
11898 .INDENT 3.5
11899 If you use this with encoding mode, keep in mind that encoding mode will
11900 convert the RGB filter\(aqs output back to yuv420p in software, using the
11901 configured software scaler. Using \fBzimg\fP might improve this, but in
11902 any case it might go against your goals when using this filter.
11903 .UNINDENT
11904 .UNINDENT
11905 .sp
11906 \fBWARNING:\fP
11907 .INDENT 7.0
11908 .INDENT 3.5
11909 Do not use this with \fB\-\-vo=gpu\fP\&. It will apply filtering twice, since
11910 most \fB\-\-vo=gpu\fP options are unconditionally applied to the \fBgpu\fP
11911 filter. There is no mechanism in mpv to prevent this.
11912 .UNINDENT
11913 .UNINDENT
11914 .UNINDENT
11915 .SH ENCODING
11916 .sp
11917 You can encode files from one format/codec to another using this facility.
11918 .INDENT 0.0
11919 .TP
11920 .B \fB\-\-o=<filename>\fP
11921 Enables encoding mode and specifies the output file name.
11922 .TP
11923 .B \fB\-\-of=<format>\fP
11924 Specifies the output format (overrides autodetection by the file name
11925 extension of the file specified by \fB\-o\fP). See \fB\-\-of=help\fP for a full
11926 list of supported formats.
11927 .TP
11928 .B \fB\-\-ofopts=<options>\fP
11929 Specifies the output format options for libavformat.
11930 See \fB\-\-ofopts=help\fP for a full list of supported options.
11931 .sp
11932 This is a key/value list option. See \fI\%List Options\fP for details.
11933 .INDENT 7.0
11934 .TP
11935 .B \fB\-\-ofopts\-add=<option>\fP
11936 Appends the option given as an argument to the options list. (Passing
11937 multiple options is currently still possible, but deprecated.)
11938 .TP
11939 .B \fB\-\-ofopts=""\fP
11940 Completely empties the options list.
11941 .UNINDENT
11942 .TP
11943 .B \fB\-\-oac=<codec>\fP
11944 Specifies the output audio codec. See \fB\-\-oac=help\fP for a full list of
11945 supported codecs.
11946 .TP
11947 .B \fB\-\-oaoffset=<value>\fP
11948 Shifts audio data by the given time (in seconds) by adding/removing
11949 samples at the start. Deprecated.
11950 .TP
11951 .B \fB\-\-oacopts=<options>\fP
11952 Specifies the output audio codec options for libavcodec.
11953 See \fB\-\-oacopts=help\fP for a full list of supported options.
11954 .INDENT 7.0
11955 .INDENT 3.5
11956 .IP "Example"
11957 .INDENT 0.0
11958 .TP
11959 .B "\fB\-\-oac=libmp3lame \-\-oacopts=b=128000\fP"
11960 selects 128 kbps MP3 encoding.
11961 .UNINDENT
11962 .UNINDENT
11963 .UNINDENT
11964 .sp
11965 This is a key/value list option. See \fI\%List Options\fP for details.
11966 .INDENT 7.0
11967 .TP
11968 .B \fB\-\-oacopts\-add=<option>\fP
11969 Appends the option given as an argument to the options list. (Passing
11970 multiple options is currently still possible, but deprecated.)
11971 .TP
11972 .B \fB\-\-oacopts=""\fP
11973 Completely empties the options list.
11974 .UNINDENT
11975 .TP
11976 .B \fB\-\-oafirst\fP
11977 Force the audio stream to become the first stream in the output.
11978 By default, the order is unspecified. Deprecated.
11979 .TP
11980 .B \fB\-\-ovc=<codec>\fP
11981 Specifies the output video codec. See \fB\-\-ovc=help\fP for a full list of
11982 supported codecs.
11983 .TP
11984 .B \fB\-\-ovoffset=<value>\fP
11985 Shifts video data by the given time (in seconds) by shifting the pts
11986 values. Deprecated.
11987 .TP
11988 .B \fB\-\-ovcopts=<options>\fP
11989 Specifies the output video codec options for libavcodec.
11990 See \-\-ovcopts=help for a full list of supported options.
11991 .INDENT 7.0
11992 .INDENT 3.5
11993 .IP "Examples"
11994 .INDENT 0.0
11995 .TP
11996 .B \fB"\-\-ovc=mpeg4 \-\-ovcopts=qscale=5"\fP
11997 selects constant quantizer scale 5 for MPEG\-4 encoding.
11998 .TP
11999 .B \fB"\-\-ovc=libx264 \-\-ovcopts=crf=23"\fP
12000 selects VBR quality factor 23 for H.264 encoding.
12001 .UNINDENT
12002 .UNINDENT
12003 .UNINDENT
12004 .sp
12005 This is a key/value list option. See \fI\%List Options\fP for details.
12006 .INDENT 7.0
12007 .TP
12008 .B \fB\-\-ovcopts\-add=<option>\fP
12009 Appends the option given as an argument to the options list. (Passing
12010 multiple options is currently still possible, but deprecated.)
12011 .TP
12012 .B \fB\-\-ovcopts=""\fP
12013 Completely empties the options list.
12014 .UNINDENT
12015 .TP
12016 .B \fB\-\-ovfirst\fP
12017 Force the video stream to become the first stream in the output.
12018 By default, the order is unspecified. Deprecated.
12019 .TP
12020 .B \fB\-\-orawts\fP
12021 Copies input pts to the output video (not supported by some output
12022 container formats, e.g. AVI). In this mode, discontinuities are not fixed
12023 and all pts are passed through as\-is. Never seek backwards or use multiple
12024 input files in this mode!
12025 .TP
12026 .B \fB\-\-no\-ocopy\-metadata\fP
12027 Turns off copying of metadata from input files to output files when
12028 encoding (which is enabled by default).
12029 .TP
12030 .B \fB\-\-oset\-metadata=<metadata\-tag[,metadata\-tag,...]>\fP
12031 Specifies metadata to include in the output file.
12032 Supported keys vary between output formats. For example, Matroska (MKV) and
12033 FLAC allow almost arbitrary keys, while support in MP4 and MP3 is more
12034 limited.
12035 .sp
12036 This is a key/value list option. See \fI\%List Options\fP for details.
12037 .INDENT 7.0
12038 .INDENT 3.5
12039 .IP "Example"
12040 .INDENT 0.0
12041 .TP
12042 .B "\fB\-\-oset\-metadata=title="Output title",comment="Another tag"\fP"
12043 adds a title and a comment to the output file.
12044 .UNINDENT
12045 .UNINDENT
12046 .UNINDENT
12047 .TP
12048 .B \fB\-\-oremove\-metadata=<metadata\-tag[,metadata\-tag,...]>\fP
12049 Specifies metadata to exclude from the output file when copying from the
12050 input file.
12051 .sp
12052 This is a string list option. See \fI\%List Options\fP for details.
12053 .INDENT 7.0
12054 .INDENT 3.5
12055 .IP "Example"
12056 .INDENT 0.0
12057 .TP
12058 .B "\fB\-\-oremove\-metadata=comment,genre\fP"
12059 excludes copying of the the comment and genre tags to the output
12060 file.
12061 .UNINDENT
12062 .UNINDENT
12063 .UNINDENT
12064 .UNINDENT
12065 .SH COMMAND INTERFACE
12066 .sp
12067 The mpv core can be controlled with commands and properties. A number of ways
12068 to interact with the player use them: key bindings (\fBinput.conf\fP), OSD
12069 (showing information with properties), JSON IPC, the client API (\fBlibmpv\fP),
12070 and the classic slave mode.
12071 .SS input.conf
12072 .sp
12073 The input.conf file consists of a list of key bindings, for example:
12074 .INDENT 0.0
12075 .INDENT 3.5
12076 .sp
12077 .nf
12078 .ft C
12079 s screenshot # take a screenshot with the s key
12080 LEFT seek 15 # map the left\-arrow key to seeking forward by 15 seconds
12081 .ft P
12082 .fi
12083 .UNINDENT
12084 .UNINDENT
12085 .sp
12086 Each line maps a key to an input command. Keys are specified with their literal
12087 value (upper case if combined with \fBShift\fP), or a name for special keys. For
12088 example, \fBa\fP maps to the \fBa\fP key without shift, and \fBA\fP maps to \fBa\fP
12089 with shift.
12090 .sp
12091 The file is located in the mpv configuration directory (normally at
12092 \fB~/.config/mpv/input.conf\fP depending on platform). The default bindings are
12093 defined here:
12094 .INDENT 0.0
12095 .INDENT 3.5
12096 .sp
12097 .nf
12098 .ft C
12099 https://github.com/mpv\-player/mpv/blob/master/etc/input.conf
12100 .ft P
12101 .fi
12102 .UNINDENT
12103 .UNINDENT
12104 .sp
12105 A list of special keys can be obtained with
12106 .INDENT 0.0
12107 .INDENT 3.5
12108 \fBmpv \-\-input\-keylist\fP
12109 .UNINDENT
12110 .UNINDENT
12111 .sp
12112 In general, keys can be combined with \fBShift\fP, \fBCtrl\fP and \fBAlt\fP:
12113 .INDENT 0.0
12114 .INDENT 3.5
12115 .sp
12116 .nf
12117 .ft C
12118 ctrl+q quit
12119 .ft P
12120 .fi
12121 .UNINDENT
12122 .UNINDENT
12123 .sp
12124 \fBmpv\fP can be started in input test mode, which displays key bindings and the
12125 commands they\(aqre bound to on the OSD, instead of executing the commands:
12126 .INDENT 0.0
12127 .INDENT 3.5
12128 .sp
12129 .nf
12130 .ft C
12131 mpv \-\-input\-test \-\-force\-window \-\-idle
12132 .ft P
12133 .fi
12134 .UNINDENT
12135 .UNINDENT
12136 .sp
12137 (Only closing the window will make \fBmpv\fP exit, pressing normal keys will
12138 merely display the binding, even if mapped to quit.)
12139 .sp
12140 Also see \fI\%Key names\fP\&.
12141 .SS input.conf syntax
12142 .sp
12143 \fB[Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] <command> ( ; <command> )*\fP
12144 .sp
12145 Note that by default, the right Alt key can be used to create special
12146 characters, and thus does not register as a modifier. The option
12147 \fB\-\-no\-input\-right\-alt\-gr\fP changes this behavior.
12148 .sp
12149 Newlines always start a new binding. \fB#\fP starts a comment (outside of quoted
12150 string arguments). To bind commands to the \fB#\fP key, \fBSHARP\fP can be used.
12151 .sp
12152 \fB<key>\fP is either the literal character the key produces (ASCII or Unicode
12153 character), or a symbolic name (as printed by \fB\-\-input\-keylist\fP).
12154 .sp
12155 \fB<section>\fP (braced with \fB{\fP and \fB}\fP) is the input section for this
12156 command.
12157 .sp
12158 \fB<command>\fP is the command itself. It consists of the command name and
12159 multiple (or none) commands, all separated by whitespace. String arguments
12160 need to be quoted with \fB"\fP\&. Details see \fBFlat command syntax\fP\&.
12161 .sp
12162 You can bind multiple commands to one key. For example:
12163 .nf
12164 a show\-text "command 1" ; show\-text "command 2"
12165 .fi
12166 .sp
12167 .sp
12168 It\(aqs also possible to bind a command to a sequence of keys:
12169 .nf
12170 a\-b\-c show\-text "command run after a, b, c have been pressed"
12171 .fi
12172 .sp
12173 .sp
12174 (This is not shown in the general command syntax.)
12175 .sp
12176 If \fBa\fP or \fBa\-b\fP or \fBb\fP are already bound, this will run the first command
12177 that matches, and the multi\-key command will never be called. Intermediate keys
12178 can be remapped to \fBignore\fP in order to avoid this issue. The maximum number
12179 of (non\-modifier) keys for combinations is currently 4.
12180 .SS Key names
12181 .sp
12182 All mouse and keyboard input is to converted to mpv\-specific key names. Key
12183 names are either special symbolic identifiers representing a physical key, or a
12184 text key names, which are unicode code points encoded as UTF\-8. These are what
12185 keyboard input would normally produce, for example \fBa\fP for the A key. As a
12186 consequence, mpv uses input translated by the current OS keyboard layout, rather
12187 than physical scan codes.
12188 .sp
12189 Currently there is the hardcoded assumption that every text key can be
12190 represented as a single unicode code point (in NFKC form).
12191 .sp
12192 All key names can be combined with the modifiers \fBShift\fP, \fBCtrl\fP, \fBAlt\fP,
12193 \fBMeta\fP\&. They must be prefixed to the actual key name, where each modifier
12194 is followed by a \fB+\fP (for example \fBctrl+q\fP).
12195 .sp
12196 Symbolic key names and modifier names are case\-insensitive. Unicode key names
12197 are case\-sensitive because input bindings typically respect the shift key.
12198 .sp
12199 Another type of key names are hexadecimal key names, that serve as fallback
12200 for special keys that are neither unicode, nor have a special mpv defined name.
12201 They will break as soon as mpv adds proper names for them, but can enable you
12202 to use a key at all if that does not happen.
12203 .sp
12204 All symbolic names are listed by \fB\-\-input\-keylist\fP\&. \fB\-\-input\-test\fP is a
12205 special mode that prints all input on the OSD.
12206 .sp
12207 Comments on some symbolic names:
12208 .INDENT 0.0
12209 .TP
12210 .B \fBKP*\fP
12211 Keypad names. Behavior varies by backend (whether they implement this, and
12212 on how they treat numlock), but typically, mpv tries to map keys on the
12213 keypad to separate names, even if they produce the same text as normal keys.
12214 .TP
12215 .B \fBMOUSE_BTN*\fP, \fBMBTN*\fP
12216 Various mouse buttons.
12217 .sp
12218 Depending on backend, the mouse wheel might also be represented as a button.
12219 In addition, \fBMOUSE_BTN3\fP to \fBMOUSE_BTN6\fP are deprecated aliases for
12220 \fBWHEEL_UP\fP, \fBWHEEL_DOWN\fP, \fBWHEEL_LEFT\fP, \fBWHEEL_RIGHT\fP\&.
12221 .sp
12222 \fBMBTN*\fP are aliases for \fBMOUSE_BTN*\fP\&.
12223 .TP
12224 .B \fBWHEEL_*\fP
12225 Mouse wheels (typically).
12226 .TP
12227 .B \fBAXIS_*\fP
12228 Deprecated aliases for \fBWHEEL_*\fP\&.
12229 .TP
12230 .B \fB*_DBL\fP
12231 Mouse button double clicks.
12232 .TP
12233 .B \fBMOUSE_MOVE\fP, \fBMOUSE_ENTER\fP, \fBMOUSE_LEAVE\fP
12234 Emitted by mouse move events. Enter/leave happens when the mouse enters or
12235 leave the mpv window (or the current mouse region, using the deprecated
12236 mouse region input section mechanism).
12237 .TP
12238 .B \fBCLOSE_WIN\fP
12239 Pseudo key emitted when closing the mpv window using the OS window manager
12240 (for example, by clicking the close button in the window title bar).
12241 .TP
12242 .B \fBGAMEPAD_*\fP
12243 Keys emitted by the SDL gamepad backend.
12244 .TP
12245 .B \fBUNMAPPED\fP
12246 Pseudo\-key that matches any unmapped key. (You should probably avoid this
12247 if possible, because it might change behavior or get removed in the future.)
12248 .TP
12249 .B \fBANY_UNICODE\fP
12250 Pseudo\-key that matches any key that produces text. (You should probably
12251 avoid this if possible, because it might change behavior or get removed in
12252 the future.)
12253 .UNINDENT
12254 .SS Flat command syntax
12255 .sp
12256 This is the syntax used in input.conf, and referred to "input.conf syntax" in
12257 a number of other places.
12258 .nf
12259
12260 \fB<command> ::= [<prefixes>] <command_name> (<argument>)*\fP
12261 \fB<argument> ::= (<string> | " <quoted_string> ")\fP
12262 .fi
12263 .sp
12264 .sp
12265 \fBcommand_name\fP is an unquoted string with the command name itself. See
12266 \fI\%List of Input Commands\fP for a list.
12267 .sp
12268 Arguments are separated by whitespace. This applies even to string arguments.
12269 For this reason, string arguments should be quoted with \fB"\fP\&. If a string
12270 argument contains spaces or certain special characters, quoting and possibly
12271 escaping is mandatory, or the command cannot be parsed correctly.
12272 .sp
12273 Inside quotes, C\-style escaping can be used. JSON escapes according to RFC 8259,
12274 minus surrogate pair escapes, should be a safe subset that can be used.
12275 .SS Commands specified as arrays
12276 .sp
12277 This applies to certain APIs, such as \fBmp.commandv()\fP or
12278 \fBmp.command_native()\fP (with array parameters) in Lua scripting, or
12279 \fBmpv_command()\fP or \fBmpv_command_node()\fP (with MPV_FORMAT_NODE_ARRAY) in the
12280 C libmpv client API.
12281 .sp
12282 The command as well as all arguments are passed as a single array. Similar to
12283 the \fI\%Flat command syntax\fP, you can first pass prefixes as strings (each as
12284 separate array item), then the command name as string, and then each argument
12285 as string or a native value.
12286 .sp
12287 Since these APIs pass arguments as separate strings or native values, they do
12288 not expect quotes, and do support escaping. Technically, there is the input.conf
12289 parser, which first splits the command string into arguments, and then invokes
12290 argument parsers for each argument. The input.conf parser normally handles
12291 quotes and escaping. The array command APIs mentioned above pass strings
12292 directly to the argument parsers, or can sidestep them by the ability to pass
12293 non\-string values.
12294 .sp
12295 Sometimes commands have string arguments, that in turn are actually parsed by
12296 other components (e.g. filter strings with \fBvf add\fP) \- in these cases, you
12297 you would have to double\-escape in input.conf, but not with the array APIs.
12298 .sp
12299 For complex commands, consider using \fI\%Named arguments\fP instead, which should
12300 give slightly more compatibility. Some commands do not support named arguments
12301 and inherently take an array, though.
12302 .SS Named arguments
12303 .sp
12304 This applies to certain APIs, such as \fBmp.command_native()\fP (with tables that
12305 have string keys) in Lua scripting, or \fBmpv_command_node()\fP (with
12306 MPV_FORMAT_NODE_MAP) in the C libmpv client API.
12307 .sp
12308 The name of the command is provided with a \fBname\fP string field. The name of
12309 each command is defined in each command description in the
12310 \fI\%List of Input Commands\fP\&. \fB\-\-input\-cmdlist\fP also lists them. See the
12311 \fBsubprocess\fP command for an example.
12312 .sp
12313 Some commands do not support named arguments (e.g. \fBrun\fP command). You need
12314 to use APIs that pass arguments as arrays.
12315 .sp
12316 Named arguments are not supported in the "flat" input.conf syntax, which means
12317 you cannot use them for key bindings in input.conf at all.
12318 .SS List of Input Commands
12319 .sp
12320 Commands with parameters have the parameter name enclosed in \fB<\fP / \fB>\fP\&.
12321 Don\(aqt add those to the actual command. Optional arguments are enclosed in
12322 \fB[\fP / \fB]\fP\&. If you don\(aqt pass them, they will be set to a default value.
12323 .sp
12324 Remember to quote string arguments in input.conf (see \fI\%Flat command syntax\fP).
12325 .INDENT 0.0
12326 .TP
12327 .B \fBignore\fP
12328 Use this to "block" keys that should be unbound, and do nothing. Useful for
12329 disabling default bindings, without disabling all bindings with
12330 \fB\-\-no\-input\-default\-bindings\fP\&.
12331 .TP
12332 .B \fBseek <target> [<flags>]\fP
12333 Change the playback position. By default, seeks by a relative amount of
12334 seconds.
12335 .sp
12336 The second argument consists of flags controlling the seek mode:
12337 .INDENT 7.0
12338 .TP
12339 .B relative (default)
12340 Seek relative to current position (a negative value seeks backwards).
12341 .TP
12342 .B absolute
12343 Seek to a given time (a negative value starts from the end of the file).
12344 .TP
12345 .B absolute\-percent
12346 Seek to a given percent position.
12347 .TP
12348 .B relative\-percent
12349 Seek relative to current position in percent.
12350 .TP
12351 .B keyframes
12352 Always restart playback at keyframe boundaries (fast).
12353 .TP
12354 .B exact
12355 Always do exact/hr/precise seeks (slow).
12356 .UNINDENT
12357 .sp
12358 Multiple flags can be combined, e.g.: \fBabsolute+keyframes\fP\&.
12359 .sp
12360 By default, \fBkeyframes\fP is used for \fBrelative\fP, \fBrelative\-percent\fP,
12361 and \fBabsolute\-percent\fP seeks, while \fBexact\fP is used for \fBabsolute\fP
12362 seeks.
12363 .sp
12364 Before mpv 0.9, the \fBkeyframes\fP and \fBexact\fP flags had to be passed as
12365 3rd parameter (essentially using a space instead of \fB+\fP). The 3rd
12366 parameter is still parsed, but is considered deprecated.
12367 .TP
12368 .B \fBrevert\-seek [<flags>]\fP
12369 Undoes the \fBseek\fP command, and some other commands that seek (but not
12370 necessarily all of them). Calling this command once will jump to the
12371 playback position before the seek. Calling it a second time undoes the
12372 \fBrevert\-seek\fP command itself. This only works within a single file.
12373 .sp
12374 The first argument is optional, and can change the behavior:
12375 .INDENT 7.0
12376 .TP
12377 .B mark
12378 Mark the current time position. The next normal \fBrevert\-seek\fP command
12379 will seek back to this point, no matter how many seeks happened since
12380 last time.
12381 .TP
12382 .B mark\-permanent
12383 If set, mark the current position, and do not change the mark position
12384 before the next \fBrevert\-seek\fP command that has \fBmark\fP or
12385 \fBmark\-permanent\fP set (or playback of the current file ends). Until
12386 this happens, \fBrevert\-seek\fP will always seek to the marked point. This
12387 flag cannot be combined with \fBmark\fP\&.
12388 .UNINDENT
12389 .sp
12390 Using it without any arguments gives you the default behavior.
12391 .TP
12392 .B \fBframe\-step\fP
12393 Play one frame, then pause. Does nothing with audio\-only playback.
12394 .TP
12395 .B \fBframe\-back\-step\fP
12396 Go back by one frame, then pause. Note that this can be very slow (it tries
12397 to be precise, not fast), and sometimes fails to behave as expected. How
12398 well this works depends on whether precise seeking works correctly (e.g.
12399 see the \fB\-\-hr\-seek\-demuxer\-offset\fP option). Video filters or other video
12400 post\-processing that modifies timing of frames (e.g. deinterlacing) should
12401 usually work, but might make backstepping silently behave incorrectly in
12402 corner cases. Using \fB\-\-hr\-seek\-framedrop=no\fP should help, although it
12403 might make precise seeking slower.
12404 .sp
12405 This does not work with audio\-only playback.
12406 .TP
12407 .B \fBset <name> <value>\fP
12408 Set the given property or option to the given value.
12409 .TP
12410 .B \fBadd <name> [<value>]\fP
12411 Add the given value to the property or option. On overflow or underflow,
12412 clamp the property to the maximum. If \fB<value>\fP is omitted, assume \fB1\fP\&.
12413 .TP
12414 .B \fBcycle <name> [<value>]\fP
12415 Cycle the given property or option. The second argument can be \fBup\fP or
12416 \fBdown\fP to set the cycle direction. On overflow, set the property back to
12417 the minimum, on underflow set it to the maximum. If \fBup\fP or \fBdown\fP is
12418 omitted, assume \fBup\fP\&.
12419 .TP
12420 .B \fBmultiply <name> <value>\fP
12421 Similar to \fBadd\fP, but multiplies the property or option with the numeric
12422 value.
12423 .TP
12424 .B \fBscreenshot <flags>\fP
12425 Take a screenshot.
12426 .sp
12427 Multiple flags are available (some can be combined with \fB+\fP):
12428 .INDENT 7.0
12429 .TP
12430 .B <subtitles> (default)
12431 Save the video image, in its original resolution, and with subtitles.
12432 Some video outputs may still include the OSD in the output under certain
12433 circumstances.
12434 .TP
12435 .B <video>
12436 Like \fBsubtitles\fP, but typically without OSD or subtitles. The exact
12437 behavior depends on the selected video output.
12438 .TP
12439 .B <window>
12440 Save the contents of the mpv window. Typically scaled, with OSD and
12441 subtitles. The exact behavior depends on the selected video output, and
12442 if no support is available, this will act like \fBvideo\fP\&.
12443 .TP
12444 .B <each\-frame>
12445 Take a screenshot each frame. Issue this command again to stop taking
12446 screenshots. Note that you should disable frame\-dropping when using
12447 this mode \- or you might receive duplicate images in cases when a
12448 frame was dropped. This flag can be combined with the other flags,
12449 e.g. \fBvideo+each\-frame\fP\&.
12450 .UNINDENT
12451 .sp
12452 Older mpv versions required passing \fBsingle\fP and \fBeach\-frame\fP as
12453 second argument (and did not have flags). This syntax is still understood,
12454 but deprecated and might be removed in the future.
12455 .sp
12456 If you combine this command with another one using \fB;\fP, you can use the
12457 \fBasync\fP flag to make encoding/writing the image file asynchronous. For
12458 normal standalone commands, this is always asynchronous, and the flag has
12459 no effect. (This behavior changed with mpv 0.29.0.)
12460 .TP
12461 .B \fBscreenshot\-to\-file <filename> <flags>\fP
12462 Take a screenshot and save it to a given file. The format of the file will
12463 be guessed by the extension (and \fB\-\-screenshot\-format\fP is ignored \- the
12464 behavior when the extension is missing or unknown is arbitrary).
12465 .sp
12466 The second argument is like the first argument to \fBscreenshot\fP and
12467 supports \fBsubtitles\fP, \fBvideo\fP, \fBwindow\fP\&.
12468 .sp
12469 If the file already exists, it\(aqs overwritten.
12470 .sp
12471 Like all input command parameters, the filename is subject to property
12472 expansion as described in \fI\%Property Expansion\fP\&.
12473 .TP
12474 .B \fBplaylist\-next <flags>\fP
12475 Go to the next entry on the playlist.
12476 .sp
12477 First argument:
12478 .INDENT 7.0
12479 .TP
12480 .B weak (default)
12481 If the last file on the playlist is currently played, do nothing.
12482 .TP
12483 .B force
12484 Terminate playback if there are no more files on the playlist.
12485 .UNINDENT
12486 .TP
12487 .B \fBplaylist\-prev <flags>\fP
12488 Go to the previous entry on the playlist.
12489 .sp
12490 First argument:
12491 .INDENT 7.0
12492 .TP
12493 .B weak (default)
12494 If the first file on the playlist is currently played, do nothing.
12495 .TP
12496 .B force
12497 Terminate playback if the first file is being played.
12498 .UNINDENT
12499 .TP
12500 .B \fBplaylist\-play\-index <integer|current|none>\fP
12501 Start (or restart) playback of the given playlist index. In addition to the
12502 0\-based playlist entry index, it supports the following values:
12503 .INDENT 7.0
12504 .TP
12505 .B <current>
12506 The current playlist entry (as in \fBplaylist\-current\-pos\fP) will be
12507 played again (unload and reload). If none is set, playback is stopped.
12508 (In corner cases, \fBplaylist\-current\-pos\fP can point to a playlist entry
12509 even if playback is currently inactive,
12510 .TP
12511 .B <none>
12512 Playback is stopped. If idle mode (\fB\-\-idle\fP) is enabled, the player
12513 will enter idle mode, otherwise it will exit.
12514 .UNINDENT
12515 .sp
12516 This comm and is similar to \fBloadfile\fP in that it only manipulates the
12517 state of what to play next, without waiting until the current file is
12518 unloaded, and the next one is loaded.
12519 .sp
12520 Setting \fBplaylist\-pos\fP or similar properties can have a similar effect to
12521 this command. However, it\(aqs more explicit, and guarantees that playback is
12522 restarted if for example the new playlist entry is the same as the previous
12523 one.
12524 .TP
12525 .B \fBloadfile <url> [<flags> [<options>]]\fP
12526 Load the given file or URL and play it. Technically, this is just a playlist
12527 manipulation command (which either replaces the playlist or appends an entry
12528 to it). Actual file loading happens independently. For example, a
12529 \fBloadfile\fP command that replaces the current file with a new one returns
12530 before the current file is stopped, and the new file even begins loading.
12531 .sp
12532 Second argument:
12533 .INDENT 7.0
12534 .TP
12535 .B <replace> (default)
12536 Stop playback of the current file, and play the new file immediately.
12537 .TP
12538 .B <append>
12539 Append the file to the playlist.
12540 .TP
12541 .B <append\-play>
12542 Append the file, and if nothing is currently playing, start playback.
12543 (Always starts with the added file, even if the playlist was not empty
12544 before running this command.)
12545 .UNINDENT
12546 .sp
12547 The third argument is a list of options and values which should be set
12548 while the file is playing. It is of the form \fBopt1=value1,opt2=value2,..\fP\&.
12549 When using the client API, this can be a \fBMPV_FORMAT_NODE_MAP\fP (or a Lua
12550 table), however the values themselves must be strings currently. These
12551 options are set during playback, and restored to the previous value at end
12552 of playback (see \fI\%Per\-File Options\fP).
12553 .TP
12554 .B \fBloadlist <url> [<flags>]\fP
12555 Load the given playlist file or URL (like \fB\-\-playlist\fP).
12556 .sp
12557 Second argument:
12558 .INDENT 7.0
12559 .TP
12560 .B <replace> (default)
12561 Stop playback and replace the internal playlist with the new one.
12562 .TP
12563 .B <append>
12564 Append the new playlist at the end of the current internal playlist.
12565 .UNINDENT
12566 .TP
12567 .B \fBplaylist\-clear\fP
12568 Clear the playlist, except the currently played file.
12569 .TP
12570 .B \fBplaylist\-remove <index>\fP
12571 Remove the playlist entry at the given index. Index values start counting
12572 with 0. The special value \fBcurrent\fP removes the current entry. Note that
12573 removing the current entry also stops playback and starts playing the next
12574 entry.
12575 .TP
12576 .B \fBplaylist\-move <index1> <index2>\fP
12577 Move the playlist entry at index1, so that it takes the place of the
12578 entry index2. (Paradoxically, the moved playlist entry will not have
12579 the index value index2 after moving if index1 was lower than index2,
12580 because index2 refers to the target entry, not the index the entry
12581 will have after moving.)
12582 .TP
12583 .B \fBplaylist\-shuffle\fP
12584 Shuffle the playlist. This is similar to what is done on start if the
12585 \fB\-\-shuffle\fP option is used.
12586 .TP
12587 .B \fBplaylist\-unshuffle\fP
12588 Attempt to revert the previous \fBplaylist\-shuffle\fP command. This works
12589 only once (multiple successive \fBplaylist\-unshuffle\fP commands do nothing).
12590 May not work correctly if new recursive playlists have been opened since
12591 a \fBplaylist\-shuffle\fP command.
12592 .TP
12593 .B \fBrun <command> [<arg1> [<arg2> [...]]]\fP
12594 Run the given command. Unlike in MPlayer/mplayer2 and earlier versions of
12595 mpv (0.2.x and older), this doesn\(aqt call the shell. Instead, the command
12596 is run directly, with each argument passed separately. Each argument is
12597 expanded like in \fI\%Property Expansion\fP\&.
12598 .sp
12599 This command has a variable number of arguments, and cannot be used with
12600 named arguments.
12601 .sp
12602 The program is run in a detached way. mpv doesn\(aqt wait until the command
12603 is completed, but continues playback right after spawning it.
12604 .sp
12605 To get the old behavior, use \fB/bin/sh\fP and \fB\-c\fP as the first two
12606 arguments.
12607 .INDENT 7.0
12608 .INDENT 3.5
12609 .IP "Example"
12610 .sp
12611 \fBrun "/bin/sh" "\-c" "echo ${title} > /tmp/playing"\fP
12612 .sp
12613 This is not a particularly good example, because it doesn\(aqt handle
12614 escaping, and a specially prepared file might allow an attacker to
12615 execute arbitrary shell commands. It is recommended to write a small
12616 shell script, and call that with \fBrun\fP\&.
12617 .UNINDENT
12618 .UNINDENT
12619 .TP
12620 .B \fBsubprocess\fP
12621 Similar to \fBrun\fP, but gives more control about process execution to the
12622 caller, and does does not detach the process.
12623 .sp
12624 You can avoid blocking until the process terminates by running this command
12625 asynchronously. (For example \fBmp.command_native_async()\fP in Lua scripting.)
12626 .sp
12627 This has the following named arguments. The order of them is not guaranteed,
12628 so you should always call them with named arguments, see \fI\%Named arguments\fP\&.
12629 .INDENT 7.0
12630 .TP
12631 .B \fBargs\fP (\fBMPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING]\fP)
12632 Array of strings with the command as first argument, and subsequent
12633 command line arguments following. This is just like the \fBrun\fP command
12634 argument list.
12635 .sp
12636 The first array entry is either an absolute path to the executable, or
12637 a filename with no path components, in which case the \fBPATH\fP
12638 environment variable. On Unix, this is equivalent to \fBposix_spawnp\fP
12639 and \fBexecvp\fP behavior.
12640 .TP
12641 .B \fBplayback_only\fP (\fBMPV_FORMAT_FLAG\fP)
12642 Boolean indicating whether the process should be killed when playback
12643 terminates (optional, default: true). If enabled, stopping playback
12644 will automatically kill the process, and you can\(aqt start it outside of
12645 playback.
12646 .TP
12647 .B \fBcapture_size\fP (\fBMPV_FORMAT_INT64\fP)
12648 Integer setting the maximum number of stdout plus stderr bytes that can
12649 be captured (optional, default: 64MB). If the number of bytes exceeds
12650 this, capturing is stopped. The limit is per captured stream.
12651 .TP
12652 .B \fBcapture_stdout\fP (\fBMPV_FORMAT_FLAG\fP)
12653 Capture all data the process outputs to stdout and return it once the
12654 process ends (optional, default: no).
12655 .TP
12656 .B \fBcapture_stderr\fP (\fBMPV_FORMAT_FLAG\fP)
12657 Same as \fBcapture_stdout\fP, but for stderr.
12658 .TP
12659 .B \fBdetach\fP (\fBMPV_FORMAT_FLAG\fP)
12660 Whether to run the process in detached mode (optional, default: no). In
12661 this mode, the process is run in a new process session, and the command
12662 does not wait for the process to terminate. If neither
12663 \fBcapture_stdout\fP nor \fBcapture_stderr\fP have been set to true,
12664 the command returns immediately after the new process has been started,
12665 otherwise the command will read as long as the pipes are open.
12666 .TP
12667 .B \fBenv\fP (\fBMPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING]\fP)
12668 Set a list of environment variables for the new process (default: empty).
12669 If an empty list is passed, the environment of the mpv process is used
12670 instead. (Unlike the underlying OS mechanisms, the mpv command cannot
12671 start a process with empty environment. Fortunately, that is completely
12672 useless.) The format of the list is as in the \fBexecle()\fP syscall. Each
12673 string item defines an environment variable as in \fBNANME=VALUE\fP\&.
12674 .sp
12675 On Lua, you may use \fButils.get_env_list()\fP to retrieve the current
12676 environment if you e.g. simply want to add a new variable.
12677 .TP
12678 .B \fBstdin_data\fP (\fBMPV_FORMAT_STRING\fP)
12679 Feed the given string to the new process\(aq stdin. Since this is a string,
12680 you cannot pass arbitrary binary data. If the process terminates or
12681 closes the pipe before all data is written, the remaining data is
12682 silently discarded. Probably does not work on win32.
12683 .TP
12684 .B \fBpassthrough_stdin\fP (\fBMPV_FORMAT_FLAG\fP)
12685 If enabled, wire the new process\(aq stdin to mpv\(aqs stdin (default: no).
12686 Before mpv 0.33.0, this argument did not exist, but the behavior was as
12687 if this was set to true.
12688 .UNINDENT
12689 .sp
12690 The command returns the following result (as \fBMPV_FORMAT_NODE_MAP\fP):
12691 .INDENT 7.0
12692 .TP
12693 .B \fBstatus\fP (\fBMPV_FORMAT_INT64\fP)
12694 The raw exit status of the process. It will be negative on error. The
12695 meaning of negative values is undefined, other than meaning error (and
12696 does not correspond to OS low level exit status values).
12697 .sp
12698 On Windows, it can happen that a negative return value is returned
12699 even if the process exits gracefully, because the win32 \fBUINT\fP exit
12700 code is assigned to an \fBint\fP variable before being set as \fBint64_t\fP
12701 field in the result map. This might be fixed later.
12702 .TP
12703 .B \fBstdout\fP (\fBMPV_FORMAT_BYTE_ARRAY\fP)
12704 Captured stdout stream, limited to \fBcapture_size\fP\&.
12705 .TP
12706 .B \fBstderr\fP (\fBMPV_FORMAT_BYTE_ARRAY\fP)
12707 Same as \fBstdout\fP, but for stderr.
12708 .TP
12709 .B \fBerror_string\fP (\fBMPV_FORMAT_STRING\fP)
12710 Empty string if the process exited gracefully. The string \fBkilled\fP if
12711 the process was terminated in an unusual way. The string \fBinit\fP if the
12712 process could not be started.
12713 .sp
12714 On Windows, \fBkilled\fP is only returned when the process has been
12715 killed by mpv as a result of \fBplayback_only\fP being set to true.
12716 .TP
12717 .B \fBkilled_by_us\fP (\fBMPV_FORMAT_FLAG\fP)
12718 Whether the process has been killed by mpv, for example as a result of
12719 \fBplayback_only\fP being set to true, aborting the command (e.g. by
12720 \fBmp.abort_async_command()\fP), or if the player is about to exit.
12721 .UNINDENT
12722 .sp
12723 Note that the command itself will always return success as long as the
12724 parameters are correct. Whether the process could be spawned or whether
12725 it was somehow killed or returned an error status has to be queried from
12726 the result value.
12727 .sp
12728 This command can be asynchronously aborted via API.
12729 .sp
12730 In all cases, the subprocess will be terminated on player exit. Also see
12731 \fI\%Asynchronous command details\fP\&. Only the \fBrun\fP command can start
12732 processes in a truly detached way.
12733 .INDENT 7.0
12734 .INDENT 3.5
12735 .IP "Warning"
12736 .sp
12737 Don\(aqt forget to set the \fBplayback_only\fP field if you want the command
12738 run while the player is in idle mode, or if you don\(aqt want that end of
12739 playback kills the command.
12740 .UNINDENT
12741 .UNINDENT
12742 .INDENT 7.0
12743 .INDENT 3.5
12744 .IP "Example"
12745 .INDENT 0.0
12746 .INDENT 3.5
12747 .sp
12748 .nf
12749 .ft C
12750 local r = mp.command_native({
12751 name = "subprocess",
12752 playback_only = false,
12753 capture_stdout = true,
12754 args = {"cat", "/proc/cpuinfo"},
12755 })
12756 if r.status == 0 then
12757 print("result: " .. r.stdout)
12758 end
12759 .ft P
12760 .fi
12761 .UNINDENT
12762 .UNINDENT
12763 .sp
12764 This is a fairly useless Lua example, which demonstrates how to run
12765 a process in a blocking manner, and retrieving its stdout output.
12766 .UNINDENT
12767 .UNINDENT
12768 .TP
12769 .B \fBquit [<code>]\fP
12770 Exit the player. If an argument is given, it\(aqs used as process exit code.
12771 .TP
12772 .B \fBquit\-watch\-later [<code>]\fP
12773 Exit player, and store current playback position. Playing that file later
12774 will seek to the previous position on start. The (optional) argument is
12775 exactly as in the \fBquit\fP command.
12776 .TP
12777 .B \fBsub\-add <url> [<flags> [<title> [<lang>]]]\fP
12778 Load the given subtitle file or stream. By default, it is selected as
12779 current subtitle after loading.
12780 .sp
12781 The \fBflags\fP argument is one of the following values:
12782 .sp
12783 <select>
12784 .INDENT 7.0
12785 .INDENT 3.5
12786 Select the subtitle immediately (default).
12787 .UNINDENT
12788 .UNINDENT
12789 .sp
12790 <auto>
12791 .INDENT 7.0
12792 .INDENT 3.5
12793 Don\(aqt select the subtitle. (Or in some special situations, let the
12794 default stream selection mechanism decide.)
12795 .UNINDENT
12796 .UNINDENT
12797 .sp
12798 <cached>
12799 .INDENT 7.0
12800 .INDENT 3.5
12801 Select the subtitle. If a subtitle with the same filename was already
12802 added, that one is selected, instead of loading a duplicate entry.
12803 (In this case, title/language are ignored, and if the was changed since
12804 it was loaded, these changes won\(aqt be reflected.)
12805 .UNINDENT
12806 .UNINDENT
12807 .sp
12808 The \fBtitle\fP argument sets the track title in the UI.
12809 .sp
12810 The \fBlang\fP argument sets the track language, and can also influence
12811 stream selection with \fBflags\fP set to \fBauto\fP\&.
12812 .TP
12813 .B \fBsub\-remove [<id>]\fP
12814 Remove the given subtitle track. If the \fBid\fP argument is missing, remove
12815 the current track. (Works on external subtitle files only.)
12816 .TP
12817 .B \fBsub\-reload [<id>]\fP
12818 Reload the given subtitle tracks. If the \fBid\fP argument is missing, reload
12819 the current track. (Works on external subtitle files only.)
12820 .sp
12821 This works by unloading and re\-adding the subtitle track.
12822 .TP
12823 .B \fBsub\-step <skip>\fP
12824 Change subtitle timing such, that the subtitle event after the next
12825 \fB<skip>\fP subtitle events is displayed. \fB<skip>\fP can be negative to step
12826 backwards.
12827 .TP
12828 .B \fBsub\-seek <skip>\fP
12829 Seek to the next (skip set to 1) or the previous (skip set to \-1) subtitle.
12830 This is similar to \fBsub\-step\fP, except that it seeks video and audio
12831 instead of adjusting the subtitle delay.
12832 .sp
12833 For embedded subtitles (like with Matroska), this works only with subtitle
12834 events that have already been displayed, or are within a short prefetch
12835 range.
12836 .TP
12837 .B \fBprint\-text <text>\fP
12838 Print text to stdout. The string can contain properties (see
12839 \fI\%Property Expansion\fP). Take care to put the argument in quotes.
12840 .TP
12841 .B \fBshow\-text <text> [<duration>|\-1 [<level>]]\fP
12842 Show text on the OSD. The string can contain properties, which are expanded
12843 as described in \fI\%Property Expansion\fP\&. This can be used to show playback
12844 time, filename, and so on.
12845 .INDENT 7.0
12846 .TP
12847 .B <duration>
12848 The time in ms to show the message for. By default, it uses the same
12849 value as \fB\-\-osd\-duration\fP\&.
12850 .TP
12851 .B <level>
12852 The minimum OSD level to show the text at (see \fB\-\-osd\-level\fP).
12853 .UNINDENT
12854 .TP
12855 .B \fBexpand\-text <string>\fP
12856 Property\-expand the argument and return the expanded string. This can be
12857 used only through the client API or from a script using
12858 \fBmp.command_native\fP\&. (see \fI\%Property Expansion\fP).
12859 .TP
12860 .B \fBexpand\-path "<string>"\fP
12861 Expand a path\(aqs double\-tilde placeholders into a platform\-specific path.
12862 As \fBexpand\-text\fP, this can only be used through the client API or from
12863 a script using \fBmp.command_native\fP\&.
12864 .INDENT 7.0
12865 .INDENT 3.5
12866 .IP "Example"
12867 .sp
12868 \fBmp.osd_message(mp.command_native({"expand\-path", "~~home/"}))\fP
12869 .sp
12870 This line of Lua would show the location of the user\(aqs mpv
12871 configuration directory on the OSD.
12872 .UNINDENT
12873 .UNINDENT
12874 .TP
12875 .B \fBshow\-progress\fP
12876 Show the progress bar, the elapsed time and the total duration of the file
12877 on the OSD.
12878 .TP
12879 .B \fBwrite\-watch\-later\-config\fP
12880 Write the resume config file that the \fBquit\-watch\-later\fP command writes,
12881 but continue playback normally.
12882 .TP
12883 .B \fBdelete\-watch\-later\-config [<filename>]\fP
12884 Delete any existing resume config file that was written by
12885 \fBquit\-watch\-later\fP or \fBwrite\-watch\-later\-config\fP\&. If a filename is
12886 specified, then the deleted config is for that file; otherwise, it is the
12887 same one as would be written by \fBquit\-watch\-later\fP or
12888 \fBwrite\-watch\-later\-config\fP in the current circumstance.
12889 .TP
12890 .B \fBstop [<flags>]\fP
12891 Stop playback and clear playlist. With default settings, this is
12892 essentially like \fBquit\fP\&. Useful for the client API: playback can be
12893 stopped without terminating the player.
12894 .sp
12895 The first argument is optional, and supports the following flags:
12896 .INDENT 7.0
12897 .TP
12898 .B keep\-playlist
12899 Do not clear the playlist.
12900 .UNINDENT
12901 .TP
12902 .B \fBmouse <x> <y> [<button> [<mode>]]\fP
12903 Send a mouse event with given coordinate (\fB<x>\fP, \fB<y>\fP).
12904 .sp
12905 Second argument:
12906 .INDENT 7.0
12907 .TP
12908 .B <button>
12909 The button number of clicked mouse button. This should be one of 0\-19.
12910 If \fB<button>\fP is omitted, only the position will be updated.
12911 .UNINDENT
12912 .sp
12913 Third argument:
12914 .INDENT 7.0
12915 .TP
12916 .B <single> (default)
12917 The mouse event represents regular single click.
12918 .TP
12919 .B <double>
12920 The mouse event represents double\-click.
12921 .UNINDENT
12922 .TP
12923 .B \fBkeypress <name>\fP
12924 Send a key event through mpv\(aqs input handler, triggering whatever
12925 behavior is configured to that key. \fBname\fP uses the \fBinput.conf\fP
12926 naming scheme for keys and modifiers. Useful for the client API: key events
12927 can be sent to libmpv to handle internally.
12928 .TP
12929 .B \fBkeydown <name>\fP
12930 Similar to \fBkeypress\fP, but sets the \fBKEYDOWN\fP flag so that if the key is
12931 bound to a repeatable command, it will be run repeatedly with mpv\(aqs key
12932 repeat timing until the \fBkeyup\fP command is called.
12933 .TP
12934 .B \fBkeyup [<name>]\fP
12935 Set the \fBKEYUP\fP flag, stopping any repeated behavior that had been
12936 triggered. \fBname\fP is optional. If \fBname\fP is not given or is an
12937 empty string, \fBKEYUP\fP will be set on all keys. Otherwise, \fBKEYUP\fP will
12938 only be set on the key specified by \fBname\fP\&.
12939 .TP
12940 .B \fBkeybind <name> <command>\fP
12941 Binds a key to an input command. \fBcommand\fP must be a complete command
12942 containing all the desired arguments and flags. Both \fBname\fP and
12943 \fBcommand\fP use the \fBinput.conf\fP naming scheme. This is primarily
12944 useful for the client API.
12945 .TP
12946 .B \fBaudio\-add <url> [<flags> [<title> [<lang>]]]\fP
12947 Load the given audio file. See \fBsub\-add\fP command.
12948 .TP
12949 .B \fBaudio\-remove [<id>]\fP
12950 Remove the given audio track. See \fBsub\-remove\fP command.
12951 .TP
12952 .B \fBaudio\-reload [<id>]\fP
12953 Reload the given audio tracks. See \fBsub\-reload\fP command.
12954 .TP
12955 .B \fBvideo\-add <url> [<flags> [<title> [<lang>]]]\fP
12956 Load the given video file. See \fBsub\-add\fP command.
12957 .TP
12958 .B \fBvideo\-remove [<id>]\fP
12959 Remove the given video track. See \fBsub\-remove\fP command.
12960 .TP
12961 .B \fBvideo\-reload [<id>]\fP
12962 Reload the given video tracks. See \fBsub\-reload\fP command.
12963 .TP
12964 .B \fBrescan\-external\-files [<mode>]\fP
12965 Rescan external files according to the current \fB\-\-sub\-auto\fP and
12966 \fB\-\-audio\-file\-auto\fP settings. This can be used to auto\-load external
12967 files \fIafter\fP the file was loaded.
12968 .sp
12969 The \fBmode\fP argument is one of the following:
12970 .INDENT 7.0
12971 .TP
12972 .B <reselect> (default)
12973 Select the default audio and subtitle streams, which typically selects
12974 external files with the highest preference. (The implementation is not
12975 perfect, and could be improved on request.)
12976 .TP
12977 .B <keep\-selection>
12978 Do not change current track selections.
12979 .UNINDENT
12980 .UNINDENT
12981 .SS Input Commands that are Possibly Subject to Change
12982 .INDENT 0.0
12983 .TP
12984 .B \fBaf <operation> <value>\fP
12985 Change audio filter chain. See \fBvf\fP command.
12986 .TP
12987 .B \fBvf <operation> <value>\fP
12988 Change video filter chain.
12989 .sp
12990 The semantics are exactly the same as with option parsing (see
12991 \fI\%VIDEO FILTERS\fP). As such the text below is a redundant and incomplete
12992 summary.
12993 .sp
12994 The first argument decides what happens:
12995 .INDENT 7.0
12996 .TP
12997 .B <set>
12998 Overwrite the previous filter chain with the new one.
12999 .TP
13000 .B <add>
13001 Append the new filter chain to the previous one.
13002 .TP
13003 .B <toggle>
13004 Check if the given filter (with the exact parameters) is already in the
13005 video chain. If it is, remove the filter. If it isn\(aqt, add the filter.
13006 (If several filters are passed to the command, this is done for
13007 each filter.)
13008 .sp
13009 A special variant is combining this with labels, and using \fB@name\fP
13010 without filter name and parameters as filter entry. This toggles the
13011 enable/disable flag.
13012 .TP
13013 .B <remove>
13014 Like \fBtoggle\fP, but always remove the given filter from the chain.
13015 .TP
13016 .B <del>
13017 Remove the given filters from the video chain. Unlike in the other
13018 cases, the second parameter is a comma separated list of filter names
13019 or integer indexes. \fB0\fP would denote the first filter. Negative
13020 indexes start from the last filter, and \fB\-1\fP denotes the last
13021 filter. Deprecated, use \fBremove\fP\&.
13022 .TP
13023 .B <clr>
13024 Remove all filters. Note that like the other sub\-commands, this does
13025 not control automatically inserted filters.
13026 .UNINDENT
13027 .sp
13028 The argument is always needed. E.g. in case of \fBclr\fP use \fBvf clr ""\fP\&.
13029 .sp
13030 You can assign labels to filter by prefixing them with \fB@name:\fP (where
13031 \fBname\fP is a user\-chosen arbitrary identifier). Labels can be used to
13032 refer to filters by name in all of the filter chain modification commands.
13033 For \fBadd\fP, using an already used label will replace the existing filter.
13034 .sp
13035 The \fBvf\fP command shows the list of requested filters on the OSD after
13036 changing the filter chain. This is roughly equivalent to
13037 \fBshow\-text ${vf}\fP\&. Note that auto\-inserted filters for format conversion
13038 are not shown on the list, only what was requested by the user.
13039 .sp
13040 Normally, the commands will check whether the video chain is recreated
13041 successfully, and will undo the operation on failure. If the command is run
13042 before video is configured (can happen if the command is run immediately
13043 after opening a file and before a video frame is decoded), this check can\(aqt
13044 be run. Then it can happen that creating the video chain fails.
13045 .INDENT 7.0
13046 .INDENT 3.5
13047 .IP "Example for input.conf"
13048 .INDENT 0.0
13049 .IP \(bu 2
13050 \fBa vf set flip\fP turn video upside\-down on the \fBa\fP key
13051 .IP \(bu 2
13052 \fBb vf set ""\fP remove all video filters on \fBb\fP
13053 .IP \(bu 2
13054 \fBc vf toggle gradfun\fP toggle debanding on \fBc\fP
13055 .UNINDENT
13056 .UNINDENT
13057 .UNINDENT
13058 .INDENT 7.0
13059 .INDENT 3.5
13060 .IP "Example how to toggle disabled filters at runtime"
13061 .INDENT 0.0
13062 .IP \(bu 2
13063 Add something like \fBvf\-add=@deband:!gradfun\fP to \fBmpv.conf\fP\&.
13064 The \fB@deband:\fP is the label, an arbitrary, user\-given name for this
13065 filter entry. The \fB!\fP before the filter name disables the filter by
13066 default. Everything after this is the normal filter name and possibly
13067 filter parameters, like in the normal \fB\-\-vf\fP syntax.
13068 .IP \(bu 2
13069 Add \fBa vf toggle @deband\fP to \fBinput.conf\fP\&. This toggles the
13070 "disabled" flag for the filter with the label \fBdeband\fP when the
13071 \fBa\fP key is hit.
13072 .UNINDENT
13073 .UNINDENT
13074 .UNINDENT
13075 .TP
13076 .B \fBcycle\-values [<"!reverse">] <property> <value1> [<value2> [...]]\fP
13077 Cycle through a list of values. Each invocation of the command will set the
13078 given property to the next value in the list. The command will use the
13079 current value of the property/option, and use it to determine the current
13080 position in the list of values. Once it has found it, it will set the
13081 next value in the list (wrapping around to the first item if needed).
13082 .sp
13083 This command has a variable number of arguments, and cannot be used with
13084 named arguments.
13085 .sp
13086 The special argument \fB!reverse\fP can be used to cycle the value list in
13087 reverse. The only advantage is that you don\(aqt need to reverse the value
13088 list yourself when adding a second key binding for cycling backwards.
13089 .TP
13090 .B \fBenable\-section <name> [<flags>]\fP
13091 This command is deprecated, except for mpv\-internal uses.
13092 .sp
13093 Enable all key bindings in the named input section.
13094 .sp
13095 The enabled input sections form a stack. Bindings in sections on the top of
13096 the stack are preferred to lower sections. This command puts the section
13097 on top of the stack. If the section was already on the stack, it is
13098 implicitly removed beforehand. (A section cannot be on the stack more than
13099 once.)
13100 .sp
13101 The \fBflags\fP parameter can be a combination (separated by \fB+\fP) of the
13102 following flags:
13103 .INDENT 7.0
13104 .TP
13105 .B <exclusive>
13106 All sections enabled before the newly enabled section are disabled.
13107 They will be re\-enabled as soon as all exclusive sections above them
13108 are removed. In other words, the new section shadows all previous
13109 sections.
13110 .TP
13111 .B <allow\-hide\-cursor>
13112 This feature can\(aqt be used through the public API.
13113 .TP
13114 .B <allow\-vo\-dragging>
13115 Same.
13116 .UNINDENT
13117 .TP
13118 .B \fBdisable\-section <name>\fP
13119 This command is deprecated, except for mpv\-internal uses.
13120 .sp
13121 Disable the named input section. Undoes \fBenable\-section\fP\&.
13122 .TP
13123 .B \fBdefine\-section <name> <contents> [<flags>]\fP
13124 This command is deprecated, except for mpv\-internal uses.
13125 .sp
13126 Create a named input section, or replace the contents of an already existing
13127 input section. The \fBcontents\fP parameter uses the same syntax as the
13128 \fBinput.conf\fP file (except that using the section syntax in it is not
13129 allowed), including the need to separate bindings with a newline character.
13130 .sp
13131 If the \fBcontents\fP parameter is an empty string, the section is removed.
13132 .sp
13133 The section with the name \fBdefault\fP is the normal input section.
13134 .sp
13135 In general, input sections have to be enabled with the \fBenable\-section\fP
13136 command, or they are ignored.
13137 .sp
13138 The last parameter has the following meaning:
13139 .INDENT 7.0
13140 .TP
13141 .B <default> (also used if parameter omitted)
13142 Use a key binding defined by this section only if the user hasn\(aqt
13143 already bound this key to a command.
13144 .TP
13145 .B <force>
13146 Always bind a key. (The input section that was made active most recently
13147 wins if there are ambiguities.)
13148 .UNINDENT
13149 .sp
13150 This command can be used to dispatch arbitrary keys to a script or a client
13151 API user. If the input section defines \fBscript\-binding\fP commands, it is
13152 also possible to get separate events on key up/down, and relatively detailed
13153 information about the key state. The special key name \fBunmapped\fP can be
13154 used to match any unmapped key.
13155 .TP
13156 .B \fBoverlay\-add <id> <x> <y> <file> <offset> <fmt> <w> <h> <stride>\fP
13157 Add an OSD overlay sourced from raw data. This might be useful for scripts
13158 and applications controlling mpv, and which want to display things on top
13159 of the video window.
13160 .sp
13161 Overlays are usually displayed in screen resolution, but with some VOs,
13162 the resolution is reduced to that of the video\(aqs. You can read the
13163 \fBosd\-width\fP and \fBosd\-height\fP properties. At least with \fB\-\-vo\-xv\fP and
13164 anamorphic video (such as DVD), \fBosd\-par\fP should be read as well, and the
13165 overlay should be aspect\-compensated.
13166 .sp
13167 This has the following named arguments. The order of them is not guaranteed,
13168 so you should always call them with named arguments, see \fI\%Named arguments\fP\&.
13169 .sp
13170 \fBid\fP is an integer between 0 and 63 identifying the overlay element. The
13171 ID can be used to add multiple overlay parts, update a part by using this
13172 command with an already existing ID, or to remove a part with
13173 \fBoverlay\-remove\fP\&. Using a previously unused ID will add a new overlay,
13174 while reusing an ID will update it.
13175 .sp
13176 \fBx\fP and \fBy\fP specify the position where the OSD should be displayed.
13177 .sp
13178 \fBfile\fP specifies the file the raw image data is read from. It can be
13179 either a numeric UNIX file descriptor prefixed with \fB@\fP (e.g. \fB@4\fP),
13180 or a filename. The file will be mapped into memory with \fBmmap()\fP,
13181 copied, and unmapped before the command returns (changed in mpv 0.18.1).
13182 .sp
13183 It is also possible to pass a raw memory address for use as bitmap memory
13184 by passing a memory address as integer prefixed with an \fB&\fP character.
13185 Passing the wrong thing here will crash the player. This mode might be
13186 useful for use with libmpv. The \fBoffset\fP parameter is simply added to the
13187 memory address (since mpv 0.8.0, ignored before).
13188 .sp
13189 \fBoffset\fP is the byte offset of the first pixel in the source file.
13190 (The current implementation always mmap\(aqs the whole file from position 0 to
13191 the end of the image, so large offsets should be avoided. Before mpv 0.8.0,
13192 the offset was actually passed directly to \fBmmap\fP, but it was changed to
13193 make using it easier.)
13194 .sp
13195 \fBfmt\fP is a string identifying the image format. Currently, only \fBbgra\fP
13196 is defined. This format has 4 bytes per pixels, with 8 bits per component.
13197 The least significant 8 bits are blue, and the most significant 8 bits
13198 are alpha (in little endian, the components are B\-G\-R\-A, with B as first
13199 byte). This uses premultiplied alpha: every color component is already
13200 multiplied with the alpha component. This means the numeric value of each
13201 component is equal to or smaller than the alpha component. (Violating this
13202 rule will lead to different results with different VOs: numeric overflows
13203 resulting from blending broken alpha values is considered something that
13204 shouldn\(aqt happen, and consequently implementations don\(aqt ensure that you
13205 get predictable behavior in this case.)
13206 .sp
13207 \fBw\fP, \fBh\fP, and \fBstride\fP specify the size of the overlay. \fBw\fP is the
13208 visible width of the overlay, while \fBstride\fP gives the width in bytes in
13209 memory. In the simple case, and with the \fBbgra\fP format, \fBstride==4*w\fP\&.
13210 In general, the total amount of memory accessed is \fBstride * h\fP\&.
13211 (Technically, the minimum size would be \fBstride * (h \- 1) + w * 4\fP, but
13212 for simplicity, the player will access all \fBstride * h\fP bytes.)
13213 .sp
13214 \fBNOTE:\fP
13215 .INDENT 7.0
13216 .INDENT 3.5
13217 Before mpv 0.18.1, you had to do manual "double buffering" when updating
13218 an overlay by replacing it with a different memory buffer. Since mpv
13219 0.18.1, the memory is simply copied and doesn\(aqt reference any of the
13220 memory indicated by the command\(aqs arguments after the commend returns.
13221 If you want to use this command before mpv 0.18.1, reads the old docs
13222 to see how to handle this correctly.
13223 .UNINDENT
13224 .UNINDENT
13225 .TP
13226 .B \fBoverlay\-remove <id>\fP
13227 Remove an overlay added with \fBoverlay\-add\fP and the same ID. Does nothing
13228 if no overlay with this ID exists.
13229 .TP
13230 .B \fBosd\-overlay\fP
13231 Add/update/remove an OSD overlay.
13232 .sp
13233 (Although this sounds similar to \fBoverlay\-add\fP, \fBosd\-overlay\fP is for
13234 text overlays, while \fBoverlay\-add\fP is for bitmaps. Maybe \fBoverlay\-add\fP
13235 will be merged into \fBosd\-overlay\fP to remove this oddity.)
13236 .sp
13237 You can use this to add text overlays in ASS format. ASS has advanced
13238 positioning and rendering tags, which can be used to render almost any kind
13239 of vector graphics.
13240 .sp
13241 This command accepts the following parameters:
13242 .INDENT 7.0
13243 .TP
13244 .B \fBid\fP
13245 Arbitrary integer that identifies the overlay. Multiple overlays can be
13246 added by calling this command with different \fBid\fP parameters. Calling
13247 this command with the same \fBid\fP replaces the previously set overlay.
13248 .sp
13249 There is a separate namespace for each libmpv client (i.e. IPC
13250 connection, script), so IDs can be made up and assigned by the API user
13251 without conflicting with other API users.
13252 .sp
13253 If the libmpv client is destroyed, all overlays associated with it are
13254 also deleted. In particular, connecting via \fB\-\-input\-ipc\-server\fP,
13255 adding an overlay, and disconnecting will remove the overlay immediately
13256 again.
13257 .TP
13258 .B \fBformat\fP
13259 String that gives the type of the overlay. Accepts the following values
13260 (HTML rendering of this is broken, view the generated manpage instead,
13261 or the raw RST source):
13262 .INDENT 7.0
13263 .TP
13264 .B \fBass\-events\fP
13265 The \fBdata\fP parameter is a string. The string is split on the
13266 newline character. Every line is turned into the \fBText\fP part of
13267 a \fBDialogue\fP ASS event. Timing is unused (but behavior of timing
13268 dependent ASS tags may change in future mpv versions).
13269 .sp
13270 Note that it\(aqs better to put multiple lines into \fBdata\fP, instead
13271 of adding multiple OSD overlays.
13272 .sp
13273 This provides 2 ASS \fBStyles\fP\&. \fBOSD\fP contains the text style as
13274 defined by the current \fB\-\-osd\-...\fP options. \fBDefault\fP is
13275 similar, and contains style that \fBOSD\fP would have if all options
13276 were set to the default.
13277 .sp
13278 In addition, the \fBres_x\fP and \fBres_y\fP options specify the value
13279 of the ASS \fBPlayResX\fP and \fBPlayResY\fP header fields. If \fBres_y\fP
13280 is set to 0, \fBPlayResY\fP is initialized to an arbitrary default
13281 value (but note that the default for this command is 720, not 0).
13282 If \fBres_x\fP is set to 0, \fBPlayResX\fP is set based on \fBres_y\fP
13283 such that a virtual ASS pixel has a square pixel aspect ratio.
13284 .TP
13285 .B \fBnone\fP
13286 Special value that causes the overlay to be removed. Most parameters
13287 other than \fBid\fP and \fBformat\fP are mostly ignored.
13288 .UNINDENT
13289 .TP
13290 .B \fBdata\fP
13291 String defining the overlay contents according to the \fBformat\fP
13292 parameter.
13293 .TP
13294 .B \fBres_x\fP, \fBres_y\fP
13295 Used if \fBformat\fP is set to \fBass\-events\fP (see description there).
13296 Optional, defaults to 0/720.
13297 .TP
13298 .B \fBz\fP
13299 The Z order of the overlay. Optional, defaults to 0.
13300 .sp
13301 Note that Z order between different overlays of different formats is
13302 static, and cannot be changed (currently, this means that bitmap
13303 overlays added by \fBoverlay\-add\fP are always on top of the ASS overlays
13304 added by \fBosd\-overlay\fP). In addition, the builtin OSD components are
13305 always below any of the custom OSD. (This includes subtitles of any kind
13306 as well as text rendered by \fBshow\-text\fP\&.)
13307 .sp
13308 It\(aqs possible that future mpv versions will randomly change how Z order
13309 between different OSD formats and builtin OSD is handled.
13310 .TP
13311 .B \fBhidden\fP
13312 If set to true, do not display this (default: false).
13313 .TP
13314 .B \fBcompute_bounds\fP
13315 If set to true, attempt to determine bounds and write them to the
13316 command\(aqs result value as \fBx0\fP, \fBx1\fP, \fBy0\fP, \fBy1\fP rectangle
13317 (default: false). If the rectangle is empty, not known, or somehow
13318 degenerate, it is not set. \fBx1\fP/\fBy1\fP is the coordinate of the
13319 bottom exclusive corner of the rectangle.
13320 .sp
13321 The result value may depend on the VO window size, and is based on the
13322 last known window size at the time of the call. This means the results
13323 may be different from what is actually rendered.
13324 .sp
13325 For \fBass\-events\fP, the result rectangle is recomputed to \fBPlayRes\fP
13326 coordinates (\fBres_x\fP/\fBres_y\fP). If window size is not known, a
13327 fallback is chosen.
13328 .sp
13329 You should be aware that this mechanism is very inefficient, as it
13330 renders the full result, and then uses the bounding box of the rendered
13331 bitmap list (even if \fBhidden\fP is set). It will flush various caches.
13332 Its results also depend on the used libass version.
13333 .sp
13334 This feature is experimental, and may change in some way again.
13335 .UNINDENT
13336 .sp
13337 \fBNOTE:\fP
13338 .INDENT 7.0
13339 .INDENT 3.5
13340 Always use named arguments (\fBmpv_command_node()\fP). Lua scripts should
13341 use the \fBmp.create_osd_overlay()\fP helper instead of invoking this
13342 command directly.
13343 .UNINDENT
13344 .UNINDENT
13345 .TP
13346 .B \fBscript\-message [<arg1> [<arg2> [...]]]\fP
13347 Send a message to all clients, and pass it the following list of arguments.
13348 What this message means, how many arguments it takes, and what the arguments
13349 mean is fully up to the receiver and the sender. Every client receives the
13350 message, so be careful about name clashes (or use \fBscript\-message\-to\fP).
13351 .sp
13352 This command has a variable number of arguments, and cannot be used with
13353 named arguments.
13354 .TP
13355 .B \fBscript\-message\-to <target> [<arg1> [<arg2> [...]]]\fP
13356 Same as \fBscript\-message\fP, but send it only to the client named
13357 \fB<target>\fP\&. Each client (scripts etc.) has a unique name. For example,
13358 Lua scripts can get their name via \fBmp.get_script_name()\fP\&.
13359 .sp
13360 This command has a variable number of arguments, and cannot be used with
13361 named arguments.
13362 .TP
13363 .B \fBscript\-binding <name>\fP
13364 Invoke a script\-provided key binding. This can be used to remap key
13365 bindings provided by external Lua scripts.
13366 .sp
13367 The argument is the name of the binding.
13368 .sp
13369 It can optionally be prefixed with the name of the script, using \fB/\fP as
13370 separator, e.g. \fBscript\-binding scriptname/bindingname\fP\&.
13371 .sp
13372 For completeness, here is how this command works internally. The details
13373 could change any time. On any matching key event, \fBscript\-message\-to\fP
13374 or \fBscript\-message\fP is called (depending on whether the script name is
13375 included), with the following arguments:
13376 .INDENT 7.0
13377 .IP 1. 3
13378 The string \fBkey\-binding\fP\&.
13379 .IP 2. 3
13380 The name of the binding (as established above).
13381 .IP 3. 3
13382 The key state as string (see below).
13383 .IP 4. 3
13384 The key name (since mpv 0.15.0).
13385 .IP 5. 3
13386 The text the key would produce, or empty string if not applicable.
13387 .UNINDENT
13388 .sp
13389 The 5th argument is only set if no modifiers are present (using the shift
13390 key with a letter is normally not emitted as having a modifier, and results
13391 in upper case text instead, but some backends may mess up).
13392 .sp
13393 The key state consists of 2 characters:
13394 .INDENT 7.0
13395 .IP 1. 3
13396 One of \fBd\fP (key was pressed down), \fBu\fP (was released), \fBr\fP (key
13397 is still down, and was repeated; only if key repeat is enabled for this
13398 binding), \fBp\fP (key was pressed; happens if up/down can\(aqt be tracked).
13399 .IP 2. 3
13400 Whether the event originates from the mouse, either \fBm\fP (mouse button)
13401 or \fB\-\fP (something else).
13402 .UNINDENT
13403 .sp
13404 Future versions can add more arguments and more key state characters to
13405 support more input peculiarities.
13406 .TP
13407 .B \fBab\-loop\fP
13408 Cycle through A\-B loop states. The first command will set the \fBA\fP point
13409 (the \fBab\-loop\-a\fP property); the second the \fBB\fP point, and the third
13410 will clear both points.
13411 .TP
13412 .B \fBdrop\-buffers\fP
13413 Drop audio/video/demuxer buffers, and restart from fresh. Might help with
13414 unseekable streams that are going out of sync.
13415 This command might be changed or removed in the future.
13416 .TP
13417 .B \fBscreenshot\-raw [<flags>]\fP
13418 Return a screenshot in memory. This can be used only through the client
13419 API. The MPV_FORMAT_NODE_MAP returned by this command has the \fBw\fP, \fBh\fP,
13420 \fBstride\fP fields set to obvious contents. The \fBformat\fP field is set to
13421 \fBbgr0\fP by default. This format is organized as \fBB8G8R8X8\fP (where \fBB\fP
13422 is the LSB). The contents of the padding \fBX\fP are undefined. The \fBdata\fP
13423 field is of type MPV_FORMAT_BYTE_ARRAY with the actual image data. The image
13424 is freed as soon as the result mpv_node is freed. As usual with client API
13425 semantics, you are not allowed to write to the image data.
13426 .sp
13427 The \fBstride\fP is the number of bytes from a pixel at \fB(x0, y0)\fP to the
13428 pixel at \fB(x0, y0 + 1)\fP\&. This can be larger than \fBw * 4\fP if the image
13429 was cropped, or if there is padding. This number can be negative as well.
13430 You access a pixel with \fBbyte_index = y * stride + x * 4\fP (assuming the
13431 \fBbgr0\fP format).
13432 .sp
13433 The \fBflags\fP argument is like the first argument to \fBscreenshot\fP and
13434 supports \fBsubtitles\fP, \fBvideo\fP, \fBwindow\fP\&.
13435 .TP
13436 .B \fBvf\-command <label> <command> <argument>\fP
13437 Send a command to the filter with the given \fB<label>\fP\&. Use \fBall\fP to send
13438 it to all filters at once. The command and argument string is filter
13439 specific. Currently, this only works with the \fBlavfi\fP filter \- see
13440 the libavfilter documentation for which commands a filter supports.
13441 .sp
13442 Note that the \fB<label>\fP is a mpv filter label, not a libavfilter filter
13443 name.
13444 .TP
13445 .B \fBaf\-command <label> <command> <argument>\fP
13446 Same as \fBvf\-command\fP, but for audio filters.
13447 .TP
13448 .B \fBapply\-profile <name> [<mode>]\fP
13449 Apply the contents of a named profile. This is like using \fBprofile=name\fP
13450 in a config file, except you can map it to a key binding to change it at
13451 runtime.
13452 .sp
13453 The mode argument:
13454 .INDENT 7.0
13455 .TP
13456 .B \fBdefault\fP
13457 Apply the profile. Default if the argument is omitted.
13458 .TP
13459 .B \fBrestore\fP
13460 Restore options set by a previous \fBapply\-profile\fP command for this
13461 profile. Only works if the profile has \fBprofile\-restore\fP set to a
13462 relevant mode. Prints a warning if nothing could be done. See
13463 \fI\%Runtime profiles\fP for details.
13464 .UNINDENT
13465 .TP
13466 .B \fBload\-script <filename>\fP
13467 Load a script, similar to the \fB\-\-script\fP option. Whether this waits for
13468 the script to finish initialization or not changed multiple times, and the
13469 future behavior is left undefined.
13470 .sp
13471 On success, returns a \fBmpv_node\fP with a \fBclient_id\fP field set to the
13472 return value of the \fBmpv_client_id()\fP API call of the newly created script
13473 handle.
13474 .TP
13475 .B \fBchange\-list <name> <operation> <value>\fP
13476 This command changes list options as described in \fI\%List Options\fP\&. The
13477 \fB<name>\fP parameter is the normal option name, while \fB<operation>\fP is
13478 the suffix or action used on the option.
13479 .sp
13480 Some operations take no value, but the command still requires the value
13481 parameter. In these cases, the value must be an empty string.
13482 .INDENT 7.0
13483 .INDENT 3.5
13484 .IP "Example"
13485 .sp
13486 \fBchange\-list glsl\-shaders append file.glsl\fP
13487 .sp
13488 Add a filename to the \fBglsl\-shaders\fP list. The command line
13489 equivalent is \fB\-\-glsl\-shaders\-append=file.glsl\fP or alternatively
13490 \fB\-\-glsl\-shader=file.glsl\fP\&.
13491 .UNINDENT
13492 .UNINDENT
13493 .TP
13494 .B \fBdump\-cache <start> <end> <filename>\fP
13495 Dump the current cache to the given filename. The \fB<filename>\fP file is
13496 overwritten if it already exists. \fB<start>\fP and \fB<end>\fP give the
13497 time range of what to dump. If no data is cached at the given time range,
13498 nothing may be dumped (creating a file with no packets).
13499 .sp
13500 Dumping a larger part of the cache will freeze the player. No effort was
13501 made to fix this, as this feature was meant mostly for creating small
13502 excerpts.
13503 .sp
13504 See \fB\-\-stream\-record\fP for various caveats that mostly apply to this
13505 command too, as both use the same underlying code for writing the output
13506 file.
13507 .sp
13508 If \fB<filename>\fP is an empty string, an ongoing \fBdump\-cache\fP is stopped.
13509 .sp
13510 If \fB<end>\fP is \fBno\fP, then continuous dumping is enabled. Then, after
13511 dumping the existing parts of the cache, anything read from network is
13512 appended to the cache as well. This behaves similar to \fB\-\-stream\-record\fP
13513 (although it does not conflict with that option, and they can be both active
13514 at the same time).
13515 .sp
13516 If the \fB<end>\fP time is after the cache, the command will _not_ wait and
13517 write newly received data to it.
13518 .sp
13519 The end of the resulting file may be slightly damaged or incomplete at the
13520 end. (Not enough effort was made to ensure that the end lines up properly.)
13521 .sp
13522 Note that this command will finish only once dumping ends. That means it
13523 works similar to the \fBscreenshot\fP command, just that it can block much
13524 longer. If continuous dumping is used, the command will not finish until
13525 playback is stopped, an error happens, another \fBdump\-cache\fP command is
13526 run, or an API like \fBmp.abort_async_command\fP was called to explicitly stop
13527 the command. See \fI\%Synchronous vs. Asynchronous\fP\&.
13528 .sp
13529 \fBNOTE:\fP
13530 .INDENT 7.0
13531 .INDENT 3.5
13532 This was mostly created for network streams. For local files, there may
13533 be much better methods to create excerpts and such. There are tons of
13534 much more user\-friendly Lua scripts, that will reencode parts of a file
13535 by spawning a separate instance of \fBffmpeg\fP\&. With network streams,
13536 this is not that easily possible, as the stream would have to be
13537 downloaded again. Even if \fB\-\-stream\-record\fP is used to record the
13538 stream to the local filesystem, there may be problems, because the
13539 recorded file is still written to.
13540 .UNINDENT
13541 .UNINDENT
13542 .sp
13543 This command is experimental, and all details about it may change in the
13544 future.
13545 .TP
13546 .B \fBab\-loop\-dump\-cache <filename>\fP
13547 Essentially calls \fBdump\-cache\fP with the current AB\-loop points as
13548 arguments. Like \fBdump\-cache\fP, this will overwrite the file at
13549 \fB<filename>\fP\&. Likewise, if the B point is set to \fBno\fP, it will enter
13550 continuous dumping after the existing cache was dumped.
13551 .sp
13552 The author reserves the right to remove this command if enough motivation
13553 is found to move this functionality to a trivial Lua script.
13554 .TP
13555 .B \fBab\-loop\-align\-cache\fP
13556 Re\-adjust the A/B loop points to the start and end within the cache the
13557 \fBab\-loop\-dump\-cache\fP command will (probably) dump. Basically, it aligns
13558 the times on keyframes. The guess might be off especially at the end (due to
13559 granularity issues due to remuxing). If the cache shrinks in the meantime,
13560 the points set by the command will not be the effective parameters either.
13561 .sp
13562 This command has an even more uncertain future than \fBab\-loop\-dump\-cache\fP
13563 and might disappear without replacement if the author decides it\(aqs useless.
13564 .UNINDENT
13565 .sp
13566 Undocumented commands: \fBao\-reload\fP (experimental/internal).
13567 .SS List of events
13568 .sp
13569 This is a partial list of events. This section describes what
13570 \fBmpv_event_to_node()\fP returns, and which is what scripting APIs and the JSON
13571 IPC sees. Note that the C API has separate C\-level declarations with
13572 \fBmpv_event\fP, which may be slightly different.
13573 .sp
13574 Note that events are asynchronous: the player core continues running while
13575 events are delivered to scripts and other clients. In some cases, you can hooks
13576 to enforce synchronous execution.
13577 .sp
13578 All events can have the following fields:
13579 .INDENT 0.0
13580 .TP
13581 .B \fBevent\fP
13582 Name as the event (as returned by \fBmpv_event_name()\fP).
13583 .TP
13584 .B \fBid\fP
13585 The \fBreply_userdata\fP field (opaque user value). If \fBreply_userdata\fP is 0,
13586 the field is not added.
13587 .TP
13588 .B \fBerror\fP
13589 Set to an error string (as returned by \fBmpv_error_string()\fP). This field
13590 is missing if no error happened, or the event type does not report error.
13591 Most events leave this unset.
13592 .UNINDENT
13593 .sp
13594 This list uses the event name field value, and the C API symbol in brackets:
13595 .INDENT 0.0
13596 .TP
13597 .B \fBstart\-file\fP (\fBMPV_EVENT_START_FILE\fP)
13598 Happens right before a new file is loaded. When you receive this, the
13599 player is loading the file (or possibly already done with it).
13600 .sp
13601 This has the following fields:
13602 .INDENT 7.0
13603 .TP
13604 .B \fBplaylist_entry_id\fP
13605 Playlist entry ID of the file being loaded now.
13606 .UNINDENT
13607 .TP
13608 .B \fBend\-file\fP (\fBMPV_EVENT_END_FILE\fP)
13609 Happens after a file was unloaded. Typically, the player will load the
13610 next file right away, or quit if this was the last file.
13611 .sp
13612 The event has the following fields:
13613 .INDENT 7.0
13614 .TP
13615 .B \fBreason\fP
13616 Has one of these values:
13617 .INDENT 7.0
13618 .TP
13619 .B \fBeof\fP
13620 The file has ended. This can (but doesn\(aqt have to) include
13621 incomplete files or broken network connections under
13622 circumstances.
13623 .TP
13624 .B \fBstop\fP
13625 Playback was ended by a command.
13626 .TP
13627 .B \fBquit\fP
13628 Playback was ended by sending the quit command.
13629 .TP
13630 .B \fBerror\fP
13631 An error happened. In this case, an \fBerror\fP field is present with
13632 the error string.
13633 .TP
13634 .B \fBredirect\fP
13635 Happens with playlists and similar. Details see
13636 \fBMPV_END_FILE_REASON_REDIRECT\fP in the C API.
13637 .TP
13638 .B \fBunknown\fP
13639 Unknown. Normally doesn\(aqt happen, unless the Lua API is out of sync
13640 with the C API. (Likewise, it could happen that your script gets
13641 reason strings that did not exist yet at the time your script was
13642 written.)
13643 .UNINDENT
13644 .TP
13645 .B \fBplaylist_entry_id\fP
13646 Playlist entry ID of the file that was being played or attempted to be
13647 played. This has the same value as the \fBplaylist_entry_id\fP field in the
13648 corresponding \fBstart\-file\fP event.
13649 .TP
13650 .B \fBfile_error\fP
13651 Set to mpv error string describing the approximate reason why playback
13652 failed. Unset if no error known. (In Lua scripting, this value was set
13653 on the \fBerror\fP field directly. This is deprecated since mpv 0.33.0.
13654 In the future, this \fBerror\fP field will be unset for this specific
13655 event.)
13656 .TP
13657 .B \fBplaylist_insert_id\fP
13658 If loading ended, because the playlist entry to be played was for example
13659 a playlist, and the current playlist entry is replaced with a number of
13660 other entries. This may happen at least with MPV_END_FILE_REASON_REDIRECT
13661 (other event types may use this for similar but different purposes in the
13662 future). In this case, playlist_insert_id will be set to the playlist
13663 entry ID of the first inserted entry, and playlist_insert_num_entries to
13664 the total number of inserted playlist entries. Note this in this specific
13665 case, the ID of the last inserted entry is playlist_insert_id+num\-1.
13666 Beware that depending on circumstances, you may observe the new playlist
13667 entries before seeing the event (e.g. reading the "playlist" property or
13668 getting a property change notification before receiving the event).
13669 If this is 0 in the C API, this field isn\(aqt added.
13670 .TP
13671 .B \fBplaylist_insert_num_entries\fP
13672 See playlist_insert_id. Only present if playlist_insert_id is present.
13673 .UNINDENT
13674 .TP
13675 .B \fBfile\-loaded\fP (\fBMPV_EVENT_FILE_LOADED\fP)
13676 Happens after a file was loaded and begins playback.
13677 .TP
13678 .B \fBseek\fP (\fBMPV_EVENT_SEEK\fP)
13679 Happens on seeking. (This might include cases when the player seeks
13680 internally, even without user interaction. This includes e.g. segment
13681 changes when playing ordered chapters Matroska files.)
13682 .TP
13683 .B \fBplayback\-restart\fP (\fBMPV_EVENT_PLAYBACK_RESTART\fP)
13684 Start of playback after seek or after file was loaded.
13685 .TP
13686 .B \fBshutdown\fP (\fBMPV_EVENT_SHUTDOWN\fP)
13687 Sent when the player quits, and the script should terminate. Normally
13688 handled automatically. See \fI\%Details on the script initialization and lifecycle\fP\&.
13689 .TP
13690 .B \fBlog\-message\fP (\fBMPV_EVENT_LOG_MESSAGE\fP)
13691 Receives messages enabled with \fBmpv_request_log_messages()\fP (Lua:
13692 \fBmp.enable_messages\fP).
13693 .sp
13694 This contains, in addition to the default event fields, the following
13695 fields:
13696 .INDENT 7.0
13697 .TP
13698 .B \fBprefix\fP
13699 The module prefix, identifies the sender of the message. This is what
13700 the terminal player puts in front of the message text when using the
13701 \fB\-\-v\fP option, and is also what is used for \fB\-\-msg\-level\fP\&.
13702 .TP
13703 .B \fBlevel\fP
13704 The log level as string. See \fBmsg.log\fP for possible log level names.
13705 Note that later versions of mpv might add new levels or remove
13706 (undocumented) existing ones.
13707 .TP
13708 .B \fBtext\fP
13709 The log message. The text will end with a newline character. Sometimes
13710 it can contain multiple lines.
13711 .UNINDENT
13712 .sp
13713 Keep in mind that these messages are meant to be hints for humans. You
13714 should not parse them, and prefix/level/text of messages might change
13715 any time.
13716 .TP
13717 .B \fBhook\fP
13718 The event has the following fields:
13719 .INDENT 7.0
13720 .TP
13721 .B \fBhook_id\fP
13722 ID to pass to \fBmpv_hook_continue()\fP\&. The Lua scripting wrapper
13723 provides a better API around this with \fBmp.add_hook()\fP\&.
13724 .UNINDENT
13725 .TP
13726 .B \fBget\-property\-reply\fP (\fBMPV_EVENT_GET_PROPERTY_REPLY\fP)
13727 See C API.
13728 .TP
13729 .B \fBset\-property\-reply\fP (\fBMPV_EVENT_SET_PROPERTY_REPLY\fP)
13730 See C API.
13731 .TP
13732 .B \fBcommand\-reply\fP (\fBMPV_EVENT_COMMAND_REPLY\fP)
13733 This is one of the commands for which the \fB\(gaerror\fP field is meaningful.
13734 .sp
13735 JSON IPC and Lua and possibly other backends treat this specially and may
13736 not pass the actual event to the user. See C API.
13737 .sp
13738 The event has the following fields:
13739 .INDENT 7.0
13740 .TP
13741 .B \fBresult\fP
13742 The result (on success) of any \fBmpv_node\fP type, if any.
13743 .UNINDENT
13744 .TP
13745 .B \fBclient\-message\fP (\fBMPV_EVENT_CLIENT_MESSAGE\fP)
13746 Lua and possibly other backends treat this specially and may not pass the
13747 actual event to the user.
13748 .sp
13749 The event has the following fields:
13750 .INDENT 7.0
13751 .TP
13752 .B \fBargs\fP
13753 Array of strings with the message data.
13754 .UNINDENT
13755 .TP
13756 .B \fBvideo\-reconfig\fP (\fBMPV_EVENT_VIDEO_RECONFIG\fP)
13757 Happens on video output or filter reconfig.
13758 .TP
13759 .B \fBaudio\-reconfig\fP (\fBMPV_EVENT_AUDIO_RECONFIG\fP)
13760 Happens on audio output or filter reconfig.
13761 .TP
13762 .B \fBproperty\-change\fP (\fBMPV_EVENT_PROPERTY_CHANGE\fP)
13763 Happens when a property that is being observed changes value.
13764 .sp
13765 The event has the following fields:
13766 .INDENT 7.0
13767 .TP
13768 .B \fBname\fP
13769 The name of the property.
13770 .TP
13771 .B \fBdata\fP
13772 The new value of the property.
13773 .UNINDENT
13774 .UNINDENT
13775 .sp
13776 The following events also happen, but are deprecated: \fBtracks\-changed\fP,
13777 \fBtrack\-switched\fP, \fBpause\fP, \fBunpause\fP, \fBmetadata\-update\fP, \fBidle\fP,
13778 \fBtick\fP, \fBchapter\-change\fP\&. Use \fBmpv_observe_property()\fP
13779 (Lua: \fBmp.observe_property()\fP) instead.
13780 .SS Hooks
13781 .sp
13782 Hooks are synchronous events between player core and a script or similar. This
13783 applies to client API (including the Lua scripting interface). Normally,
13784 events are supposed to be asynchronous, and the hook API provides an awkward
13785 and obscure way to handle events that require stricter coordination. There are
13786 no API stability guarantees made. Not following the protocol exactly can make
13787 the player freeze randomly. Basically, nobody should use this API.
13788 .sp
13789 The C API is described in the header files. The Lua API is described in the
13790 Lua section.
13791 .sp
13792 Before a hook is actually invoked on an API clients, it will attempt to return
13793 new values for all observed properties that were changed before the hook. This
13794 may make it easier for an application to set defined "barriers" between property
13795 change notifications by registering hooks. (That means these hooks will have an
13796 effect, even if you do nothing and make them continue immediately.)
13797 .sp
13798 The following hooks are currently defined:
13799 .INDENT 0.0
13800 .TP
13801 .B \fBon_load\fP
13802 Called when a file is to be opened, before anything is actually done.
13803 For example, you could read and write the \fBstream\-open\-filename\fP
13804 property to redirect an URL to something else (consider support for
13805 streaming sites which rarely give the user a direct media URL), or
13806 you could set per\-file options with by setting the property
13807 \fBfile\-local\-options/<option name>\fP\&. The player will wait until all
13808 hooks are run.
13809 .sp
13810 Ordered after \fBstart\-file\fP and before \fBplayback\-restart\fP\&.
13811 .TP
13812 .B \fBon_load_fail\fP
13813 Called after after a file has been opened, but failed to. This can be
13814 used to provide a fallback in case native demuxers failed to recognize
13815 the file, instead of always running before the native demuxers like
13816 \fBon_load\fP\&. Demux will only be retried if \fBstream\-open\-filename\fP
13817 was changed. If it fails again, this hook is _not_ called again, and
13818 loading definitely fails.
13819 .sp
13820 Ordered after \fBon_load\fP, and before \fBplayback\-restart\fP and \fBend\-file\fP\&.
13821 .TP
13822 .B \fBon_preloaded\fP
13823 Called after a file has been opened, and before tracks are selected and
13824 decoders are created. This has some usefulness if an API users wants
13825 to select tracks manually, based on the set of available tracks. It\(aqs
13826 also useful to initialize \fB\-\-lavfi\-complex\fP in a specific way by API,
13827 without having to "probe" the available streams at first.
13828 .sp
13829 Note that this does not yet apply default track selection. Which operations
13830 exactly can be done and not be done, and what information is available and
13831 what is not yet available yet, is all subject to change.
13832 .sp
13833 Ordered after \fBon_load_fail\fP etc. and before \fBplayback\-restart\fP\&.
13834 .TP
13835 .B \fBon_unload\fP
13836 Run before closing a file, and before actually uninitializing
13837 everything. It\(aqs not possible to resume playback in this state.
13838 .sp
13839 Ordered before \fBend\-file\fP\&. Will also happen in the error case (then after
13840 \fBon_load_fail\fP).
13841 .TP
13842 .B \fBon_before_start_file\fP
13843 Run before a \fBstart\-file\fP event is sent. (If any client changes the
13844 current playlist entry, or sends a quit command to the player, the
13845 corresponding event will not actually happen after the hook returns.)
13846 Useful to drain property changes before a new file is loaded.
13847 .TP
13848 .B \fBon_after_end_file\fP
13849 Run after an \fBend\-file\fP event. Useful to drain property changes after a
13850 file has finished.
13851 .UNINDENT
13852 .SS Input Command Prefixes
13853 .sp
13854 These prefixes are placed between key name and the actual command. Multiple
13855 prefixes can be specified. They are separated by whitespace.
13856 .INDENT 0.0
13857 .TP
13858 .B \fBosd\-auto\fP
13859 Use the default behavior for this command. This is the default for
13860 \fBinput.conf\fP commands. Some libmpv/scripting/IPC APIs do not use this as
13861 default, but use \fBno\-osd\fP instead.
13862 .TP
13863 .B \fBno\-osd\fP
13864 Do not use any OSD for this command.
13865 .TP
13866 .B \fBosd\-bar\fP
13867 If possible, show a bar with this command. Seek commands will show the
13868 progress bar, property changing commands may show the newly set value.
13869 .TP
13870 .B \fBosd\-msg\fP
13871 If possible, show an OSD message with this command. Seek command show
13872 the current playback time, property changing commands show the newly set
13873 value as text.
13874 .TP
13875 .B \fBosd\-msg\-bar\fP
13876 Combine osd\-bar and osd\-msg.
13877 .TP
13878 .B \fBraw\fP
13879 Do not expand properties in string arguments. (Like \fB"${property\-name}"\fP\&.)
13880 This is the default for some libmpv/scripting/IPC APIs.
13881 .TP
13882 .B \fBexpand\-properties\fP
13883 All string arguments are expanded as described in \fI\%Property Expansion\fP\&.
13884 This is the default for \fBinput.conf\fP commands.
13885 .TP
13886 .B \fBrepeatable\fP
13887 For some commands, keeping a key pressed doesn\(aqt run the command repeatedly.
13888 This prefix forces enabling key repeat in any case.
13889 .TP
13890 .B \fBasync\fP
13891 Allow asynchronous execution (if possible). Note that only a few commands
13892 will support this (usually this is explicitly documented). Some commands
13893 are asynchronous by default (or rather, their effects might manifest
13894 after completion of the command). The semantics of this flag might change
13895 in the future. Set it only if you don\(aqt rely on the effects of this command
13896 being fully realized when it returns. See \fI\%Synchronous vs. Asynchronous\fP\&.
13897 .TP
13898 .B \fBsync\fP
13899 Allow synchronous execution (if possible). Normally, all commands are
13900 synchronous by default, but some are asynchronous by default for
13901 compatibility with older behavior.
13902 .UNINDENT
13903 .sp
13904 All of the osd prefixes are still overridden by the global \fB\-\-osd\-level\fP
13905 settings.
13906 .SS Synchronous vs. Asynchronous
13907 .sp
13908 The \fBasync\fP and \fBsync\fP prefix matter only for how the issuer of the command
13909 waits on the completion of the command. Normally it does not affect how the
13910 command behaves by itself. There are the following cases:
13911 .INDENT 0.0
13912 .IP \(bu 2
13913 Normal input.conf commands are always run asynchronously. Slow running
13914 commands are queued up or run in parallel.
13915 .IP \(bu 2
13916 "Multi" input.conf commands (1 key binding, concatenated with \fB;\fP) will be
13917 executed in order, except for commands that are async (either prefixed with
13918 \fBasync\fP, or async by default for some commands). The async commands are
13919 run in a detached manner, possibly in parallel to the remaining sync commands
13920 in the list.
13921 .IP \(bu 2
13922 Normal Lua and libmpv commands (e.g. \fBmpv_command()\fP) are run in a blocking
13923 manner, unless the \fBasync\fP prefix is used, or the command is async by
13924 default. This means in the sync case the caller will block, even if the core
13925 continues playback. Async mode runs the command in a detached manner.
13926 .IP \(bu 2
13927 Async libmpv command API (e.g. \fBmpv_command_async()\fP) never blocks the
13928 caller, and always notify their completion with a message. The \fBsync\fP and
13929 \fBasync\fP prefixes make no difference.
13930 .IP \(bu 2
13931 Lua also provides APIs for running async commands, which behave similar to the
13932 C counterparts.
13933 .IP \(bu 2
13934 In all cases, async mode can still run commands in a synchronous manner, even
13935 in detached mode. This can for example happen in cases when a command does not
13936 have an asynchronous implementation. The async libmpv API still never blocks
13937 the caller in these cases.
13938 .UNINDENT
13939 .sp
13940 Before mpv 0.29.0, the \fBasync\fP prefix was only used by screenshot commands,
13941 and made them run the file saving code in a detached manner. This is the
13942 default now, and \fBasync\fP changes behavior only in the ways mentioned above.
13943 .sp
13944 Currently the following commands have different waiting characteristics with
13945 sync vs. async: sub\-add, audio\-add, sub\-reload, audio\-reload,
13946 rescan\-external\-files, screenshot, screenshot\-to\-file, dump\-cache,
13947 ab\-loop\-dump\-cache.
13948 .SS Asynchronous command details
13949 .sp
13950 On the API level, every asynchronous command is bound to the context which
13951 started it. For example, an asynchronous command started by \fBmpv_command_async\fP
13952 is bound to the \fBmpv_handle\fP passed to the function. Only this \fBmpv_handle\fP
13953 receives the completion notification (\fBMPV_EVENT_COMMAND_REPLY\fP), and only
13954 this handle can abort a still running command directly. If the \fBmpv_handle\fP is
13955 destroyed, any still running async. commands started by it are terminated.
13956 .sp
13957 The scripting APIs and JSON IPC give each script/connection its own implicit
13958 \fBmpv_handle\fP\&.
13959 .sp
13960 If the player is closed, the core may abort all pending async. commands on its
13961 own (like a forced \fBmpv_abort_async_command()\fP call for each pending command
13962 on behalf of the API user). This happens at the same time \fBMPV_EVENT_SHUTDOWN\fP
13963 is sent, and there is no way to prevent this.
13964 .SS Input Sections
13965 .sp
13966 Input sections group a set of bindings, and enable or disable them at once.
13967 In \fBinput.conf\fP, each key binding is assigned to an input section, rather
13968 than actually having explicit text sections.
13969 .sp
13970 See also: \fBenable\-section\fP and \fBdisable\-section\fP commands.
13971 .sp
13972 Predefined bindings:
13973 .INDENT 0.0
13974 .TP
13975 .B \fBdefault\fP
13976 Bindings without input section are implicitly assigned to this section. It
13977 is enabled by default during normal playback.
13978 .TP
13979 .B \fBencode\fP
13980 Section which is active in encoding mode. It is enabled exclusively, so
13981 that bindings in the \fBdefault\fP sections are ignored.
13982 .UNINDENT
13983 .SS Properties
13984 .sp
13985 Properties are used to set mpv options during runtime, or to query arbitrary
13986 information. They can be manipulated with the \fBset\fP/\fBadd\fP/\fBcycle\fP
13987 commands, and retrieved with \fBshow\-text\fP, or anything else that uses property
13988 expansion. (See \fI\%Property Expansion\fP\&.)
13989 .sp
13990 The property name is annotated with RW to indicate whether the property is
13991 generally writable.
13992 .sp
13993 If an option is referenced, the property will normally take/return exactly the
13994 same values as the option. In these cases, properties are merely a way to change
13995 an option at runtime.
13996 .SS Property list
13997 .sp
13998 \fBNOTE:\fP
13999 .INDENT 0.0
14000 .INDENT 3.5
14001 Most options can be set as runtime via properties as well. Just remove the
14002 leading \fB\-\-\fP from the option name. These are not documented below, see
14003 \fI\%OPTIONS\fP instead. Only properties which do not exist as option with the
14004 same name, or which have very different behavior from the options are
14005 documented below.
14006 .sp
14007 Properties marked as (RW) are writeable, while those that aren\(aqt are
14008 read\-only.
14009 .UNINDENT
14010 .UNINDENT
14011 .INDENT 0.0
14012 .TP
14013 .B \fBaudio\-speed\-correction\fP, \fBvideo\-speed\-correction\fP
14014 Factor multiplied with \fBspeed\fP at which the player attempts to play the
14015 file. Usually it\(aqs exactly 1. (Display sync mode will make this useful.)
14016 .sp
14017 OSD formatting will display it in the form of \fB+1.23456%\fP, with the number
14018 being \fB(raw \- 1) * 100\fP for the given raw property value.
14019 .TP
14020 .B \fBdisplay\-sync\-active\fP
14021 Whether \fB\-\-video\-sync=display\fP is actually active.
14022 .TP
14023 .B \fBfilename\fP
14024 Currently played file, with path stripped. If this is an URL, try to undo
14025 percent encoding as well. (The result is not necessarily correct, but
14026 looks better for display purposes. Use the \fBpath\fP property to get an
14027 unmodified filename.)
14028 .sp
14029 This has a sub\-property:
14030 .INDENT 7.0
14031 .TP
14032 .B \fBfilename/no\-ext\fP
14033 Like the \fBfilename\fP property, but if the text contains a \fB\&.\fP, strip
14034 all text after the last \fB\&.\fP\&. Usually this removes the file extension.
14035 .UNINDENT
14036 .TP
14037 .B \fBfile\-size\fP
14038 Length in bytes of the source file/stream. (This is the same as
14039 \fB${stream\-end}\fP\&. For segmented/multi\-part files, this will return the
14040 size of the main or manifest file, whatever it is.)
14041 .TP
14042 .B \fBestimated\-frame\-count\fP
14043 Total number of frames in current file.
14044 .sp
14045 \fBNOTE:\fP
14046 .INDENT 7.0
14047 .INDENT 3.5
14048 This is only an estimate. (It\(aqs computed from two unreliable
14049 quantities: fps and stream length.)
14050 .UNINDENT
14051 .UNINDENT
14052 .TP
14053 .B \fBestimated\-frame\-number\fP
14054 Number of current frame in current stream.
14055 .sp
14056 \fBNOTE:\fP
14057 .INDENT 7.0
14058 .INDENT 3.5
14059 This is only an estimate. (It\(aqs computed from two unreliable
14060 quantities: fps and possibly rounded timestamps.)
14061 .UNINDENT
14062 .UNINDENT
14063 .TP
14064 .B \fBpath\fP
14065 Full path of the currently played file. Usually this is exactly the same
14066 string you pass on the mpv command line or the \fBloadfile\fP command, even
14067 if it\(aqs a relative path. If you expect an absolute path, you will have to
14068 determine it yourself, for example by using the \fBworking\-directory\fP
14069 property.
14070 .TP
14071 .B \fBstream\-open\-filename\fP
14072 The full path to the currently played media. This is different from
14073 \fBpath\fP only in special cases. In particular, if \fB\-\-ytdl=yes\fP is used,
14074 and the URL is detected by \fByoutube\-dl\fP, then the script will set this
14075 property to the actual media URL. This property should be set only during
14076 the \fBon_load\fP or \fBon_load_fail\fP hooks, otherwise it will have no effect
14077 (or may do something implementation defined in the future). The property is
14078 reset if playback of the current media ends.
14079 .TP
14080 .B \fBmedia\-title\fP
14081 If the currently played file has a \fBtitle\fP tag, use that.
14082 .sp
14083 Otherwise, return the \fBfilename\fP property.
14084 .TP
14085 .B \fBfile\-format\fP
14086 Symbolic name of the file format. In some cases, this is a comma\-separated
14087 list of format names, e.g. mp4 is \fBmov,mp4,m4a,3gp,3g2,mj2\fP (the list
14088 may grow in the future for any format).
14089 .TP
14090 .B \fBcurrent\-demuxer\fP
14091 Name of the current demuxer. (This is useless.)
14092 .sp
14093 (Renamed from \fBdemuxer\fP\&.)
14094 .TP
14095 .B \fBstream\-path\fP
14096 Filename (full path) of the stream layer filename. (This is probably
14097 useless and is almost never different from \fBpath\fP\&.)
14098 .TP
14099 .B \fBstream\-pos\fP
14100 Raw byte position in source stream. Technically, this returns the position
14101 of the most recent packet passed to a decoder.
14102 .TP
14103 .B \fBstream\-end\fP
14104 Raw end position in bytes in source stream.
14105 .TP
14106 .B \fBduration\fP
14107 Duration of the current file in seconds. If the duration is unknown, the
14108 property is unavailable. Note that the file duration is not always exactly
14109 known, so this is an estimate.
14110 .sp
14111 This replaces the \fBlength\fP property, which was deprecated after the
14112 mpv 0.9 release. (The semantics are the same.)
14113 .TP
14114 .B \fBavsync\fP
14115 Last A/V synchronization difference. Unavailable if audio or video is
14116 disabled.
14117 .TP
14118 .B \fBtotal\-avsync\-change\fP
14119 Total A\-V sync correction done. Unavailable if audio or video is
14120 disabled.
14121 .TP
14122 .B \fBdecoder\-frame\-drop\-count\fP
14123 Video frames dropped by decoder, because video is too far behind audio (when
14124 using \fB\-\-framedrop=decoder\fP). Sometimes, this may be incremented in other
14125 situations, e.g. when video packets are damaged, or the decoder doesn\(aqt
14126 follow the usual rules. Unavailable if video is disabled.
14127 .sp
14128 \fBdrop\-frame\-count\fP is a deprecated alias.
14129 .TP
14130 .B \fBframe\-drop\-count\fP
14131 Frames dropped by VO (when using \fB\-\-framedrop=vo\fP).
14132 .sp
14133 \fBvo\-drop\-frame\-count\fP is a deprecated alias.
14134 .TP
14135 .B \fBmistimed\-frame\-count\fP
14136 Number of video frames that were not timed correctly in display\-sync mode
14137 for the sake of keeping A/V sync. This does not include external
14138 circumstances, such as video rendering being too slow or the graphics
14139 driver somehow skipping a vsync. It does not include rounding errors either
14140 (which can happen especially with bad source timestamps). For example,
14141 using the \fBdisplay\-desync\fP mode should never change this value from 0.
14142 .TP
14143 .B \fBvsync\-ratio\fP
14144 For how many vsyncs a frame is displayed on average. This is available if
14145 display\-sync is active only. For 30 FPS video on a 60 Hz screen, this will
14146 be 2. This is the moving average of what actually has been scheduled, so
14147 24 FPS on 60 Hz will never remain exactly on 2.5, but jitter depending on
14148 the last frame displayed.
14149 .TP
14150 .B \fBvo\-delayed\-frame\-count\fP
14151 Estimated number of frames delayed due to external circumstances in
14152 display\-sync mode. Note that in general, mpv has to guess that this is
14153 happening, and the guess can be inaccurate.
14154 .TP
14155 .B \fBpercent\-pos\fP (RW)
14156 Position in current file (0\-100). The advantage over using this instead of
14157 calculating it out of other properties is that it properly falls back to
14158 estimating the playback position from the byte position, if the file
14159 duration is not known.
14160 .TP
14161 .B \fBtime\-pos\fP (RW)
14162 Position in current file in seconds.
14163 .TP
14164 .B \fBtime\-start\fP
14165 Deprecated. Always returns 0. Before mpv 0.14, this used to return the start
14166 time of the file (could affect e.g. transport streams). See
14167 \fB\-\-rebase\-start\-time\fP option.
14168 .TP
14169 .B \fBtime\-remaining\fP
14170 Remaining length of the file in seconds. Note that the file duration is not
14171 always exactly known, so this is an estimate.
14172 .TP
14173 .B \fBaudio\-pts\fP
14174 Current audio playback position in current file in seconds. Unlike time\-pos,
14175 this updates more often than once per frame. For audio\-only files, it is
14176 mostly equivalent to time\-pos, while for video\-only files this property is
14177 not available.
14178 .TP
14179 .B \fBplaytime\-remaining\fP
14180 \fBtime\-remaining\fP scaled by the current \fBspeed\fP\&.
14181 .TP
14182 .B \fBplayback\-time\fP (RW)
14183 Position in current file in seconds. Unlike \fBtime\-pos\fP, the time is
14184 clamped to the range of the file. (Inaccurate file durations etc. could
14185 make it go out of range. Useful on attempts to seek outside of the file,
14186 as the seek target time is considered the current position during seeking.)
14187 .TP
14188 .B \fBchapter\fP (RW)
14189 Current chapter number. The number of the first chapter is 0.
14190 .TP
14191 .B \fBedition\fP (RW)
14192 Current MKV edition number. Setting this property to a different value will
14193 restart playback. The number of the first edition is 0.
14194 .sp
14195 Before mpv 0.31.0, this showed the actual edition selected at runtime, if
14196 you didn\(aqt set the option or property manually. With mpv 0.31.0 and later,
14197 this strictly returns the user\-set option or property value, and the
14198 \fBcurrent\-edition\fP property was added to return the runtime selected
14199 edition (this matters with \fB\-\-edition=auto\fP, the default).
14200 .TP
14201 .B \fBcurrent\-edition\fP
14202 Currently selected edition. This property is unavailable if no file is
14203 loaded, or the file has no editions. (Matroska files make a difference
14204 between having no editions and a single edition, which will be reflected by
14205 the property, although in practice it does not matter.)
14206 .TP
14207 .B \fBchapters\fP
14208 Number of chapters.
14209 .TP
14210 .B \fBeditions\fP
14211 Number of MKV editions.
14212 .TP
14213 .B \fBedition\-list\fP
14214 List of editions, current entry marked. Currently, the raw property value
14215 is useless.
14216 .sp
14217 This has a number of sub\-properties. Replace \fBN\fP with the 0\-based edition
14218 index.
14219 .INDENT 7.0
14220 .TP
14221 .B \fBedition\-list/count\fP
14222 Number of editions. If there are no editions, this can be 0 or 1 (1
14223 if there\(aqs a useless dummy edition).
14224 .TP
14225 .B \fBedition\-list/N/id\fP (RW)
14226 Edition ID as integer. Use this to set the \fBedition\fP property.
14227 Currently, this is the same as the edition index.
14228 .TP
14229 .B \fBedition\-list/N/default\fP
14230 Whether this is the default edition.
14231 .TP
14232 .B \fBedition\-list/N/title\fP
14233 Edition title as stored in the file. Not always available.
14234 .UNINDENT
14235 .sp
14236 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
14237 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
14238 the following contents:
14239 .INDENT 7.0
14240 .INDENT 3.5
14241 .sp
14242 .nf
14243 .ft C
14244 MPV_FORMAT_NODE_ARRAY
14245 MPV_FORMAT_NODE_MAP (for each edition)
14246 "id" MPV_FORMAT_INT64
14247 "title" MPV_FORMAT_STRING
14248 "default" MPV_FORMAT_FLAG
14249 .ft P
14250 .fi
14251 .UNINDENT
14252 .UNINDENT
14253 .TP
14254 .B \fBmetadata\fP
14255 Metadata key/value pairs.
14256 .sp
14257 If the property is accessed with Lua\(aqs \fBmp.get_property_native\fP, this
14258 returns a table with metadata keys mapping to metadata values. If it is
14259 accessed with the client API, this returns a \fBMPV_FORMAT_NODE_MAP\fP,
14260 with tag keys mapping to tag values.
14261 .sp
14262 For OSD, it returns a formatted list. Trying to retrieve this property as
14263 a raw string doesn\(aqt work.
14264 .sp
14265 This has a number of sub\-properties:
14266 .INDENT 7.0
14267 .TP
14268 .B \fBmetadata/by\-key/<key>\fP
14269 Value of metadata entry \fB<key>\fP\&.
14270 .TP
14271 .B \fBmetadata/list/count\fP
14272 Number of metadata entries.
14273 .TP
14274 .B \fBmetadata/list/N/key\fP
14275 Key name of the Nth metadata entry. (The first entry is \fB0\fP).
14276 .TP
14277 .B \fBmetadata/list/N/value\fP
14278 Value of the Nth metadata entry.
14279 .TP
14280 .B \fBmetadata/<key>\fP
14281 Old version of \fBmetadata/by\-key/<key>\fP\&. Use is discouraged, because
14282 the metadata key string could conflict with other sub\-properties.
14283 .UNINDENT
14284 .sp
14285 The layout of this property might be subject to change. Suggestions are
14286 welcome how exactly this property should work.
14287 .sp
14288 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
14289 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
14290 the following contents:
14291 .INDENT 7.0
14292 .INDENT 3.5
14293 .sp
14294 .nf
14295 .ft C
14296 MPV_FORMAT_NODE_MAP
14297 (key and string value for each metadata entry)
14298 .ft P
14299 .fi
14300 .UNINDENT
14301 .UNINDENT
14302 .TP
14303 .B \fBfiltered\-metadata\fP
14304 Like \fBmetadata\fP, but includes only fields listed in the \fB\-\-display\-tags\fP
14305 option. This is the same set of tags that is printed to the terminal.
14306 .TP
14307 .B \fBchapter\-metadata\fP
14308 Metadata of current chapter. Works similar to \fBmetadata\fP property. It
14309 also allows the same access methods (using sub\-properties).
14310 .sp
14311 Per\-chapter metadata is very rare. Usually, only the chapter name
14312 (\fBtitle\fP) is set.
14313 .sp
14314 For accessing other information, like chapter start, see the
14315 \fBchapter\-list\fP property.
14316 .TP
14317 .B \fBvf\-metadata/<filter\-label>\fP
14318 Metadata added by video filters. Accessed by the filter label,
14319 which, if not explicitly specified using the \fB@filter\-label:\fP syntax,
14320 will be \fB<filter\-name>NN\fP\&.
14321 .sp
14322 Works similar to \fBmetadata\fP property. It allows the same access
14323 methods (using sub\-properties).
14324 .sp
14325 An example of this kind of metadata are the cropping parameters
14326 added by \fB\-\-vf=lavfi=cropdetect\fP\&.
14327 .TP
14328 .B \fBaf\-metadata/<filter\-label>\fP
14329 Equivalent to \fBvf\-metadata/<filter\-label>\fP, but for audio filters.
14330 .TP
14331 .B \fBidle\-active\fP
14332 Returns \fByes\fP/true if no file is loaded, but the player is staying around
14333 because of the \fB\-\-idle\fP option.
14334 .sp
14335 (Renamed from \fBidle\fP\&.)
14336 .TP
14337 .B \fBcore\-idle\fP
14338 Whether the playback core is paused. This can differ from \fBpause\fP in
14339 special situations, such as when the player pauses itself due to low
14340 network cache.
14341 .sp
14342 This also returns \fByes\fP/true if playback is restarting or if nothing is
14343 playing at all. In other words, it\(aqs only \fBno\fP/false if there\(aqs actually
14344 video playing. (Behavior since mpv 0.7.0.)
14345 .TP
14346 .B \fBcache\-speed\fP
14347 Current I/O read speed between the cache and the lower layer (like network).
14348 This gives the number bytes per seconds over a 1 second window (using
14349 the type \fBMPV_FORMAT_INT64\fP for the client API).
14350 .sp
14351 This is the same as \fBdemuxer\-cache\-state/raw\-input\-rate\fP\&.
14352 .TP
14353 .B \fBdemuxer\-cache\-duration\fP
14354 Approximate duration of video buffered in the demuxer, in seconds. The
14355 guess is very unreliable, and often the property will not be available
14356 at all, even if data is buffered.
14357 .TP
14358 .B \fBdemuxer\-cache\-time\fP
14359 Approximate time of video buffered in the demuxer, in seconds. Same as
14360 \fBdemuxer\-cache\-duration\fP but returns the last timestamp of buffered
14361 data in demuxer.
14362 .TP
14363 .B \fBdemuxer\-cache\-idle\fP
14364 Whether the demuxer is idle, which means that the demuxer cache is filled
14365 to the requested amount, and is currently not reading more data.
14366 .TP
14367 .B \fBdemuxer\-cache\-state\fP
14368 Each entry in \fBseekable\-ranges\fP represents a region in the demuxer cache
14369 that can be seeked to, with a \fBstart\fP and \fBend\fP fields containing the
14370 respective timestamps. If there are multiple demuxers active, this only
14371 returns information about the "main" demuxer, but might be changed in
14372 future to return unified information about all demuxers. The ranges are in
14373 arbitrary order. Often, ranges will overlap for a bit, before being joined.
14374 In broken corner cases, ranges may overlap all over the place.
14375 .sp
14376 The end of a seek range is usually smaller than the value returned by the
14377 \fBdemuxer\-cache\-time\fP property, because that property returns the guessed
14378 buffering amount, while the seek ranges represent the buffered data that
14379 can actually be used for cached seeking.
14380 .sp
14381 \fBbof\-cached\fP indicates whether the seek range with the lowest timestamp
14382 points to the beginning of the stream (BOF). This implies you cannot seek
14383 before this position at all. \fBeof\-cached\fP indicates whether the seek range
14384 with the highest timestamp points to the end of the stream (EOF). If both
14385 \fBbof\-cached\fP and \fBeof\-cached\fP are true, and there\(aqs only 1 cache range,
14386 the entire stream is cached.
14387 .sp
14388 \fBfw\-bytes\fP is the number of bytes of packets buffered in the range
14389 starting from the current decoding position. This is a rough estimate
14390 (may not account correctly for various overhead), and stops at the
14391 demuxer position (it ignores seek ranges after it).
14392 .sp
14393 \fBfile\-cache\-bytes\fP is the number of bytes stored in the file cache. This
14394 includes all overhead, and possibly unused data (like pruned data). This
14395 member is missing if the file cache wasn\(aqt enabled with
14396 \fB\-\-cache\-on\-disk=yes\fP\&.
14397 .sp
14398 \fBcache\-end\fP is \fBdemuxer\-cache\-time\fP\&. Missing if unavailable.
14399 .sp
14400 \fBreader\-pts\fP is the approximate timestamp of the start of the buffered
14401 range. Missing if unavailable.
14402 .sp
14403 \fBcache\-duration\fP is \fBdemuxer\-cache\-duration\fP\&. Missing if unavailable.
14404 .sp
14405 \fBraw\-input\-rate\fP is the estimated input rate of the network layer (or any
14406 other byte\-oriented input layer) in bytes per second. May be inaccurate or
14407 missing.
14408 .sp
14409 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
14410 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
14411 the following contents:
14412 .INDENT 7.0
14413 .INDENT 3.5
14414 .sp
14415 .nf
14416 .ft C
14417 MPV_FORMAT_NODE_MAP
14418 "seekable\-ranges" MPV_FORMAT_NODE_ARRAY
14419 MPV_FORMAT_NODE_MAP
14420 "start" MPV_FORMAT_DOUBLE
14421 "end" MPV_FORMAT_DOUBLE
14422 "bof\-cached" MPV_FORMAT_FLAG
14423 "eof\-cached" MPV_FORMAT_FLAG
14424 "fw\-bytes" MPV_FORMAT_INT64
14425 "file\-cache\-bytes" MPV_FORMAT_INT64
14426 "cache\-end" MPV_FORMAT_DOUBLE
14427 "reader\-pts" MPV_FORMAT_DOUBLE
14428 "cache\-duration" MPV_FORMAT_DOUBLE
14429 "raw\-input\-rate" MPV_FORMAT_INT64
14430 .ft P
14431 .fi
14432 .UNINDENT
14433 .UNINDENT
14434 .sp
14435 Other fields (might be changed or removed in the future):
14436 .INDENT 7.0
14437 .TP
14438 .B \fBeof\fP
14439 Whether the reader thread has hit the end of the file.
14440 .TP
14441 .B \fBunderrun\fP
14442 Whether the reader thread could not satisfy a decoder\(aqs request for a
14443 new packet.
14444 .TP
14445 .B \fBidle\fP
14446 Whether the thread is currently not reading.
14447 .TP
14448 .B \fBtotal\-bytes\fP
14449 Sum of packet bytes (plus some overhead estimation) of the entire packet
14450 queue, including cached seekable ranges.
14451 .UNINDENT
14452 .TP
14453 .B \fBdemuxer\-via\-network\fP
14454 Whether the stream demuxed via the main demuxer is most likely played via
14455 network. What constitutes "network" is not always clear, might be used for
14456 other types of untrusted streams, could be wrong in certain cases, and its
14457 definition might be changing. Also, external files (like separate audio
14458 files or streams) do not influence the value of this property (currently).
14459 .TP
14460 .B \fBdemuxer\-start\-time\fP
14461 The start time reported by the demuxer in fractional seconds.
14462 .TP
14463 .B \fBpaused\-for\-cache\fP
14464 Whether playback is paused because of waiting for the cache.
14465 .TP
14466 .B \fBcache\-buffering\-state\fP
14467 The percentage (0\-100) of the cache fill status until the player will
14468 unpause (related to \fBpaused\-for\-cache\fP).
14469 .TP
14470 .B \fBeof\-reached\fP
14471 Whether the end of playback was reached. Note that this is usually
14472 interesting only if \fB\-\-keep\-open\fP is enabled, since otherwise the player
14473 will immediately play the next file (or exit or enter idle mode), and in
14474 these cases the \fBeof\-reached\fP property will logically be cleared
14475 immediately after it\(aqs set.
14476 .TP
14477 .B \fBseeking\fP
14478 Whether the player is currently seeking, or otherwise trying to restart
14479 playback. (It\(aqs possible that it returns \fByes\fP/true while a file is
14480 loaded. This is because the same underlying code is used for seeking and
14481 resyncing.)
14482 .TP
14483 .B \fBmixer\-active\fP
14484 Whether the audio mixer is active.
14485 .sp
14486 This option is relatively useless. Before mpv 0.18.1, it could be used to
14487 infer behavior of the \fBvolume\fP property.
14488 .TP
14489 .B \fBao\-volume\fP (RW)
14490 System volume. This property is available only if mpv audio output is
14491 currently active, and only if the underlying implementation supports volume
14492 control. What this option does depends on the API. For example, on ALSA
14493 this usually changes system\-wide audio, while with PulseAudio this controls
14494 per\-application volume.
14495 .TP
14496 .B \fBao\-mute\fP (RW)
14497 Similar to \fBao\-volume\fP, but controls the mute state. May be unimplemented
14498 even if \fBao\-volume\fP works.
14499 .TP
14500 .B \fBaudio\-codec\fP
14501 Audio codec selected for decoding.
14502 .TP
14503 .B \fBaudio\-codec\-name\fP
14504 Audio codec.
14505 .TP
14506 .B \fBaudio\-params\fP
14507 Audio format as output by the audio decoder.
14508 This has a number of sub\-properties:
14509 .INDENT 7.0
14510 .TP
14511 .B \fBaudio\-params/format\fP
14512 The sample format as string. This uses the same names as used in other
14513 places of mpv.
14514 .TP
14515 .B \fBaudio\-params/samplerate\fP
14516 Samplerate.
14517 .TP
14518 .B \fBaudio\-params/channels\fP
14519 The channel layout as a string. This is similar to what the
14520 \fB\-\-audio\-channels\fP accepts.
14521 .TP
14522 .B \fBaudio\-params/hr\-channels\fP
14523 As \fBchannels\fP, but instead of the possibly cryptic actual layout
14524 sent to the audio device, return a hopefully more human readable form.
14525 (Usually only \fBaudio\-out\-params/hr\-channels\fP makes sense.)
14526 .TP
14527 .B \fBaudio\-params/channel\-count\fP
14528 Number of audio channels. This is redundant to the \fBchannels\fP field
14529 described above.
14530 .UNINDENT
14531 .sp
14532 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
14533 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
14534 the following contents:
14535 .INDENT 7.0
14536 .INDENT 3.5
14537 .sp
14538 .nf
14539 .ft C
14540 MPV_FORMAT_NODE_MAP
14541 "format" MPV_FORMAT_STRING
14542 "samplerate" MPV_FORMAT_INT64
14543 "channels" MPV_FORMAT_STRING
14544 "channel\-count" MPV_FORMAT_INT64
14545 "hr\-channels" MPV_FORMAT_STRING
14546 .ft P
14547 .fi
14548 .UNINDENT
14549 .UNINDENT
14550 .TP
14551 .B \fBaudio\-out\-params\fP
14552 Same as \fBaudio\-params\fP, but the format of the data written to the audio
14553 API.
14554 .TP
14555 .B \fBcolormatrix\fP
14556 Redirects to \fBvideo\-params/colormatrix\fP\&. This parameter (as well as
14557 similar ones) can be overridden with the \fBformat\fP video filter.
14558 .TP
14559 .B \fBcolormatrix\-input\-range\fP
14560 See \fBcolormatrix\fP\&.
14561 .TP
14562 .B \fBcolormatrix\-primaries\fP
14563 See \fBcolormatrix\fP\&.
14564 .TP
14565 .B \fBhwdec\fP (RW)
14566 Reflects the \fB\-\-hwdec\fP option.
14567 .sp
14568 Writing to it may change the currently used hardware decoder, if possible.
14569 (Internally, the player may reinitialize the decoder, and will perform a
14570 seek to refresh the video properly.) You can watch the other hwdec
14571 properties to see whether this was successful.
14572 .sp
14573 Unlike in mpv 0.9.x and before, this does not return the currently active
14574 hardware decoder. Since mpv 0.18.0, \fBhwdec\-current\fP is available for
14575 this purpose.
14576 .TP
14577 .B \fBhwdec\-current\fP
14578 The current hardware decoding in use. If decoding is active, return one of
14579 the values used by the \fBhwdec\fP option/property. \fBno\fP/false indicates
14580 software decoding. If no decoder is loaded, the property is unavailable.
14581 .TP
14582 .B \fBhwdec\-interop\fP
14583 This returns the currently loaded hardware decoding/output interop driver.
14584 This is known only once the VO has opened (and possibly later). With some
14585 VOs (like \fBgpu\fP), this might be never known in advance, but only when
14586 the decoder attempted to create the hw decoder successfully. (Using
14587 \fB\-\-gpu\-hwdec\-interop\fP can load it eagerly.) If there are multiple
14588 drivers loaded, they will be separated by \fB,\fP\&.
14589 .sp
14590 If no VO is active or no interop driver is known, this property is
14591 unavailable.
14592 .sp
14593 This does not necessarily use the same values as \fBhwdec\fP\&. There can be
14594 multiple interop drivers for the same hardware decoder, depending on
14595 platform and VO.
14596 .TP
14597 .B \fBvideo\-format\fP
14598 Video format as string.
14599 .TP
14600 .B \fBvideo\-codec\fP
14601 Video codec selected for decoding.
14602 .TP
14603 .B \fBwidth\fP, \fBheight\fP
14604 Video size. This uses the size of the video as decoded, or if no video
14605 frame has been decoded yet, the (possibly incorrect) container indicated
14606 size.
14607 .TP
14608 .B \fBvideo\-params\fP
14609 Video parameters, as output by the decoder (with overrides like aspect
14610 etc. applied). This has a number of sub\-properties:
14611 .INDENT 7.0
14612 .TP
14613 .B \fBvideo\-params/pixelformat\fP
14614 The pixel format as string. This uses the same names as used in other
14615 places of mpv.
14616 .TP
14617 .B \fBvideo\-params/hw\-pixelformat\fP
14618 The underlying pixel format as string. This is relevant for some cases
14619 of hardware decoding and unavailable otherwise.
14620 .TP
14621 .B \fBvideo\-params/average\-bpp\fP
14622 Average bits\-per\-pixel as integer. Subsampled planar formats use a
14623 different resolution, which is the reason this value can sometimes be
14624 odd or confusing. Can be unavailable with some formats.
14625 .TP
14626 .B \fBvideo\-params/w\fP, \fBvideo\-params/h\fP
14627 Video size as integers, with no aspect correction applied.
14628 .TP
14629 .B \fBvideo\-params/dw\fP, \fBvideo\-params/dh\fP
14630 Video size as integers, scaled for correct aspect ratio.
14631 .TP
14632 .B \fBvideo\-params/aspect\fP
14633 Display aspect ratio as float.
14634 .TP
14635 .B \fBvideo\-params/par\fP
14636 Pixel aspect ratio.
14637 .TP
14638 .B \fBvideo\-params/colormatrix\fP
14639 The colormatrix in use as string. (Exact values subject to change.)
14640 .TP
14641 .B \fBvideo\-params/colorlevels\fP
14642 The colorlevels as string. (Exact values subject to change.)
14643 .TP
14644 .B \fBvideo\-params/primaries\fP
14645 The primaries in use as string. (Exact values subject to change.)
14646 .TP
14647 .B \fBvideo\-params/gamma\fP
14648 The gamma function in use as string. (Exact values subject to change.)
14649 .TP
14650 .B \fBvideo\-params/sig\-peak\fP
14651 The video file\(aqs tagged signal peak as float.
14652 .TP
14653 .B \fBvideo\-params/light\fP
14654 The light type in use as a string. (Exact values subject to change.)
14655 .TP
14656 .B \fBvideo\-params/chroma\-location\fP
14657 Chroma location as string. (Exact values subject to change.)
14658 .TP
14659 .B \fBvideo\-params/rotate\fP
14660 Intended display rotation in degrees (clockwise).
14661 .TP
14662 .B \fBvideo\-params/stereo\-in\fP
14663 Source file stereo 3D mode. (See the \fBformat\fP video filter\(aqs
14664 \fBstereo\-in\fP option.)
14665 .TP
14666 .B \fBvideo\-params/alpha\fP
14667 Alpha type. If the format has no alpha channel, this will be unavailable
14668 (but in future releases, it could change to \fBno\fP). If alpha is
14669 present, this is set to \fBstraight\fP or \fBpremul\fP\&.
14670 .UNINDENT
14671 .sp
14672 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
14673 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
14674 the following contents:
14675 .INDENT 7.0
14676 .INDENT 3.5
14677 .sp
14678 .nf
14679 .ft C
14680 MPV_FORMAT_NODE_MAP
14681 "pixelformat" MPV_FORMAT_STRING
14682 "hw\-pixelformat" MPV_FORMAT_STRING
14683 "w" MPV_FORMAT_INT64
14684 "h" MPV_FORMAT_INT64
14685 "dw" MPV_FORMAT_INT64
14686 "dh" MPV_FORMAT_INT64
14687 "aspect" MPV_FORMAT_DOUBLE
14688 "par" MPV_FORMAT_DOUBLE
14689 "colormatrix" MPV_FORMAT_STRING
14690 "colorlevels" MPV_FORMAT_STRING
14691 "primaries" MPV_FORMAT_STRING
14692 "gamma" MPV_FORMAT_STRING
14693 "sig\-peak" MPV_FORMAT_DOUBLE
14694 "light" MPV_FORMAT_STRING
14695 "chroma\-location" MPV_FORMAT_STRING
14696 "rotate" MPV_FORMAT_INT64
14697 "stereo\-in" MPV_FORMAT_STRING
14698 "average\-bpp" MPV_FORMAT_INT64
14699 "alpha" MPV_FORMAT_STRING
14700 .ft P
14701 .fi
14702 .UNINDENT
14703 .UNINDENT
14704 .TP
14705 .B \fBdwidth\fP, \fBdheight\fP
14706 Video display size. This is the video size after filters and aspect scaling
14707 have been applied. The actual video window size can still be different
14708 from this, e.g. if the user resized the video window manually.
14709 .sp
14710 These have the same values as \fBvideo\-out\-params/dw\fP and
14711 \fBvideo\-out\-params/dh\fP\&.
14712 .TP
14713 .B \fBvideo\-dec\-params\fP
14714 Exactly like \fBvideo\-params\fP, but no overrides applied.
14715 .TP
14716 .B \fBvideo\-out\-params\fP
14717 Same as \fBvideo\-params\fP, but after video filters have been applied. If
14718 there are no video filters in use, this will contain the same values as
14719 \fBvideo\-params\fP\&. Note that this is still not necessarily what the video
14720 window uses, since the user can change the window size, and all real VOs
14721 do their own scaling independently from the filter chain.
14722 .sp
14723 Has the same sub\-properties as \fBvideo\-params\fP\&.
14724 .TP
14725 .B \fBvideo\-frame\-info\fP
14726 Approximate information of the current frame. Note that if any of these
14727 are used on OSD, the information might be off by a few frames due to OSD
14728 redrawing and frame display being somewhat disconnected, and you might
14729 have to pause and force a redraw.
14730 .sp
14731 This has a number of sub\-properties:
14732 .INDENT 7.0
14733 .TP
14734 .B \fBvideo\-frame\-info/picture\-type\fP
14735 The type of the picture. It can be "I" (intra), "P" (predicted), "B"
14736 (bi\-dir predicted) or unavailable.
14737 .TP
14738 .B \fBvideo\-frame\-info/interlaced\fP
14739 Whether the content of the frame is interlaced.
14740 .TP
14741 .B \fBvideo\-frame\-info/tff\fP
14742 If the content is interlaced, whether the top field is displayed first.
14743 .TP
14744 .B \fBvideo\-frame\-info/repeat\fP
14745 Whether the frame must be delayed when decoding.
14746 .UNINDENT
14747 .TP
14748 .B \fBcontainer\-fps\fP
14749 Container FPS. This can easily contain bogus values. For videos that use
14750 modern container formats or video codecs, this will often be incorrect.
14751 .sp
14752 (Renamed from \fBfps\fP\&.)
14753 .TP
14754 .B \fBestimated\-vf\-fps\fP
14755 Estimated/measured FPS of the video filter chain output. (If no filters
14756 are used, this corresponds to decoder output.) This uses the average of
14757 the 10 past frame durations to calculate the FPS. It will be inaccurate
14758 if frame\-dropping is involved (such as when framedrop is explicitly
14759 enabled, or after precise seeking). Files with imprecise timestamps (such
14760 as Matroska) might lead to unstable results.
14761 .TP
14762 .B \fBwindow\-scale\fP (RW)
14763 Window size multiplier. Setting this will resize the video window to the
14764 values contained in \fBdwidth\fP and \fBdheight\fP multiplied with the value
14765 set with this property. Setting \fB1\fP will resize to original video size
14766 (or to be exact, the size the video filters output). \fB2\fP will set the
14767 double size, \fB0.5\fP halves the size.
14768 .sp
14769 See \fBcurrent\-window\-scale\fP for the value derived from the actual window
14770 size.
14771 .sp
14772 Since mpv 0.31.0, this always returns the previously set value (or the
14773 default value), instead of the value implied by the actual window size.
14774 Before mpv 0.31.0, this returned what \fBcurrent\-window\-scale\fP returns now,
14775 after the window was created.
14776 .TP
14777 .B \fBcurrent\-window\-scale\fP
14778 The \fBwindow\-scale\fP value calculated from the current window size. This
14779 has the same value as \fBwindow\-scale\fP if the window size was not changed
14780 since setting the option, and the window size was not restricted in other
14781 ways. The property is unavailable if no video is active.
14782 .TP
14783 .B \fBfocused\fP
14784 Whether the window has focus. Currently works only on X11, Wayland and
14785 macOS.
14786 .TP
14787 .B \fBdisplay\-names\fP
14788 Names of the displays that the mpv window covers. On X11, these
14789 are the xrandr names (LVDS1, HDMI1, DP1, VGA1, etc.). On Windows, these
14790 are the GDI names (\e.DISPLAY1, \e.DISPLAY2, etc.) and the first display
14791 in the list will be the one that Windows considers associated with the
14792 window (as determined by the MonitorFromWindow API.) On macOS these are the
14793 Display Product Names as used in the System Information and only one display
14794 name is returned since a window can only be on one screen.
14795 .TP
14796 .B \fBdisplay\-fps\fP
14797 The refresh rate of the current display. Currently, this is the lowest FPS
14798 of any display covered by the video, as retrieved by the underlying system
14799 APIs (e.g. xrandr on X11). It is not the measured FPS. It\(aqs not necessarily
14800 available on all platforms. Note that any of the listed facts may change
14801 any time without a warning.
14802 .sp
14803 Writing to this property is deprecated. It has the same effect as writing to
14804 \fBoverride\-display\-fps\fP\&. Since mpv 0.31.0, this property is unavailable
14805 if no display FPS was reported (e.g. if no video is active), while in older
14806 versions, it returned the \fB\-\-display\-fps\fP option value.
14807 .TP
14808 .B \fBestimated\-display\-fps\fP
14809 The actual rate at which display refreshes seem to occur, measured by
14810 system time. Only available if display\-sync mode (as selected by
14811 \fB\-\-video\-sync\fP) is active.
14812 .TP
14813 .B \fBvsync\-jitter\fP
14814 Estimated deviation factor of the vsync duration.
14815 .TP
14816 .B \fBdisplay\-hidpi\-scale\fP
14817 The HiDPI scale factor as reported by the windowing backend. If no VO is
14818 active, or if the VO does not report a value, this property is unavailable.
14819 It may be saner to report an absolute DPI, however, this is the way HiDPI
14820 support is implemented on most OS APIs. See also \fB\-\-hidpi\-window\-scale\fP\&.
14821 .TP
14822 .B \fBvideo\-aspect\fP (RW)
14823 Deprecated. This is tied to \fB\-\-video\-aspect\-override\fP, but always
14824 reports the current video aspect if video is active.
14825 .sp
14826 The read and write components of this option can be split up into
14827 \fBvideo\-params/aspect\fP and \fBvideo\-aspect\-override\fP respectively.
14828 .TP
14829 .B \fBosd\-width\fP, \fBosd\-height\fP
14830 Last known OSD width (can be 0). This is needed if you want to use the
14831 \fBoverlay\-add\fP command. It gives you the actual OSD size, which can be
14832 different from the window size in some cases.
14833 .sp
14834 Alias to \fBosd\-dimensions/w\fP and \fBosd\-dimensions/h\fP\&.
14835 .TP
14836 .B \fBosd\-par\fP
14837 Last known OSD display pixel aspect (can be 0).
14838 .sp
14839 Alias to \fBosd\-dimensions/osd\-par\fP\&.
14840 .TP
14841 .B \fBosd\-dimensions\fP
14842 Last known OSD dimensions.
14843 .sp
14844 Has the following sub\-properties (which can be read as \fBMPV_FORMAT_NODE\fP
14845 or Lua table with \fBmp.get_property_native\fP):
14846 .INDENT 7.0
14847 .TP
14848 .B \fBosd\-dimensions/w\fP
14849 Size of the VO window in OSD render units (usually pixels, but may be
14850 scaled pixels with VOs like \fBxv\fP).
14851 .TP
14852 .B \fBosd\-dimensions/h\fP
14853 Size of the VO window in OSD render units,
14854 .TP
14855 .B \fBosd\-dimensions/par\fP
14856 Pixel aspect ratio of the OSD (usually 1).
14857 .TP
14858 .B \fBosd\-dimensions/aspect\fP
14859 Display aspect ratio of the VO window. (Computing from the properties
14860 above.)
14861 .TP
14862 .B \fBosd\-dimensions/mt\fP, \fBosd\-dimensions/mb\fP, \fBosd\-dimensions/ml\fP, \fBosd\-dimensions/mr\fP
14863 OSD to video margins (top, bottom, left, right). This describes the
14864 area into which the video is rendered.
14865 .UNINDENT
14866 .sp
14867 Any of these properties may be unavailable or set to dummy values if the
14868 VO window is not created or visible.
14869 .TP
14870 .B \fBmouse\-pos\fP
14871 Read\-only \- last known mouse position, normalizd to OSD dimensions.
14872 .sp
14873 Has the following sub\-properties (which can be read as \fBMPV_FORMAT_NODE\fP
14874 or Lua table with \fBmp.get_property_native\fP):
14875 .INDENT 7.0
14876 .TP
14877 .B \fBmouse\-pos/x\fP, \fBmouse\-pos/y\fP
14878 Last known coordinates of the mouse pointer.
14879 .TP
14880 .B \fBmouse\-pos/hover\fP
14881 Boolean \- whether the mouse pointer hovers the video window. The
14882 coordinates should be ignored when this value is false, because the
14883 video backends update them only when the pointer hovers the window.
14884 .UNINDENT
14885 .TP
14886 .B \fBsub\-text\fP
14887 The current subtitle text regardless of sub visibility. Formatting is
14888 stripped. If the subtitle is not text\-based (i.e. DVD/BD subtitles), an
14889 empty string is returned.
14890 .sp
14891 This property is experimental and might be removed in the future.
14892 .TP
14893 .B \fBsub\-text\-ass\fP
14894 Like \fBsub\-text\fP, but return the text in ASS format. Text subtitles in
14895 other formats are converted. For native ASS subtitles, events that do
14896 not contain any text (but vector drawings etc.) are not filtered out. If
14897 multiple events match with the current playback time, they are concatenated
14898 with line breaks. Contains only the "Text" part of the events.
14899 .sp
14900 This property is not enough to render ASS subtitles correctly, because ASS
14901 header and per\-event metadata are not returned. You likely need to do
14902 further filtering on the returned string to make it useful.
14903 .sp
14904 This property is experimental and might be removed in the future.
14905 .TP
14906 .B \fBsub\-start\fP
14907 The current subtitle start time (in seconds). If there\(aqs multiple current
14908 subtitles, returns the first start time. If no current subtitle is present
14909 null is returned instead.
14910 .TP
14911 .B \fBsub\-end\fP
14912 The current subtitle end time (in seconds). If there\(aqs multiple current
14913 subtitles, return the last end time. If no current subtitle is present, or
14914 if it\(aqs present but has unknown or incorrect duration, null is returned
14915 instead.
14916 .TP
14917 .B \fBplaylist\-pos\fP (RW)
14918 Current position on playlist. The first entry is on position 0. Writing to
14919 this property may start playback at the new position.
14920 .sp
14921 In some cases, this is not necessarily the currently playing file. See
14922 explanation of \fBcurrent\fP and \fBplaying\fP flags in \fBplaylist\fP\&.
14923 .sp
14924 If there the playlist is empty, or if it\(aqs non\-empty, but no entry is
14925 "current", this property returns \-1. Likewise, writing \-1 will put the
14926 player into idle mode (or exit playback if idle mode is not enabled). If an
14927 out of range index is written to the property, this behaves as if writing \-1.
14928 (Before mpv 0.33.0, instead of returning \-1, this property was unavailable
14929 if no playlist entry was current.)
14930 .sp
14931 Writing the current value back to the property is subject to change.
14932 Currently, it will restart playback of the playlist entry. But in the
14933 future, writing the current value will be ignored. Use the
14934 \fBplaylist\-play\-index\fP command to get guaranteed behavior.
14935 .TP
14936 .B \fBplaylist\-pos\-1\fP (RW)
14937 Same as \fBplaylist\-pos\fP, but 1\-based.
14938 .TP
14939 .B \fBplaylist\-current\-pos\fP (RW)
14940 Index of the "current" item on playlist. This usually, but not necessarily,
14941 the currently playing item (see \fBplaylist\-playing\-pos\fP). Depending on the
14942 exact internal state of the player, it may refer to the playlist item to
14943 play next, or the playlist item used to determine what to play next.
14944 .sp
14945 For reading, this is exactly the same as \fBplaylist\-pos\fP\&.
14946 .sp
14947 For writing, this \fIonly\fP sets the position of the "current" item, without
14948 stopping playback of the current file (or starting playback, if this is done
14949 in idle mode). Use \-1 to remove the current flag.
14950 .sp
14951 This property is only vaguely useful. If set during playback, it will
14952 typically cause the playlist entry \fIafter\fP it to be played next. Another
14953 possibly odd observable state is that if \fBplaylist\-next\fP is run during
14954 playback, this property is set to the playlist entry to play next (unlike
14955 the previous case). There is an internal flag that decides whether the
14956 current playlist entry or the next one should be played, and this flag is
14957 currently inaccessible for API users. (Whether this behavior will kept is
14958 possibly subject to change.)
14959 .TP
14960 .B \fBplaylist\-playing\-pos\fP
14961 Index of the "playing" item on playlist. A playlist item is "playing" if
14962 it\(aqs being loaded, actually playing, or being unloaded. This property is set
14963 during the \fBMPV_EVENT_START_FILE\fP (\fBstart\-file\fP) and the
14964 \fBMPV_EVENT_START_END\fP (\fBend\-file\fP) events. Outside of that, it returns
14965 \-1. If the playlist entry was somehow removed during playback, but playback
14966 hasn\(aqt stopped yet, or is in progress of being stopped, it also returns \-1.
14967 (This can happen at least during state transitions.)
14968 .sp
14969 In the "playing" state, this is usually the same as \fBplaylist\-pos\fP, except
14970 during state changes, or if \fBplaylist\-current\-pos\fP was written explicitly.
14971 .TP
14972 .B \fBplaylist\-count\fP
14973 Number of total playlist entries.
14974 .TP
14975 .B \fBplaylist\fP
14976 Playlist, current entry marked. Currently, the raw property value is
14977 useless.
14978 .sp
14979 This has a number of sub\-properties. Replace \fBN\fP with the 0\-based playlist
14980 entry index.
14981 .INDENT 7.0
14982 .TP
14983 .B \fBplaylist/count\fP
14984 Number of playlist entries (same as \fBplaylist\-count\fP).
14985 .TP
14986 .B \fBplaylist/N/filename\fP
14987 Filename of the Nth entry.
14988 .TP
14989 .B \fBplaylist/N/playing\fP
14990 \fByes\fP/true if the \fBplaylist\-playing\-pos\fP property points to this
14991 entry, \fBno\fP/false or unavailable otherwise.
14992 .TP
14993 .B \fBplaylist/N/current\fP
14994 \fByes\fP/true if the \fBplaylist\-current\-pos\fP property points to this
14995 entry, \fBno\fP/false or unavailable otherwise.
14996 .TP
14997 .B \fBplaylist/N/title\fP
14998 Name of the Nth entry. Only available if the playlist file contains
14999 such fields, and only if mpv\(aqs parser supports it for the given
15000 playlist format.
15001 .TP
15002 .B \fBplaylist/N/id\fP
15003 Unique ID for this entry. This is an automatically assigned integer ID
15004 that is unique for the entire life time of the current mpv core
15005 instance. Other commands, events, etc. use this as \fBplaylist_entry_id\fP
15006 fields.
15007 .UNINDENT
15008 .sp
15009 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
15010 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
15011 the following contents:
15012 .INDENT 7.0
15013 .INDENT 3.5
15014 .sp
15015 .nf
15016 .ft C
15017 MPV_FORMAT_NODE_ARRAY
15018 MPV_FORMAT_NODE_MAP (for each playlist entry)
15019 "filename" MPV_FORMAT_STRING
15020 "current" MPV_FORMAT_FLAG (might be missing; since mpv 0.7.0)
15021 "playing" MPV_FORMAT_FLAG (same)
15022 "title" MPV_FORMAT_STRING (optional)
15023 "id" MPV_FORMAT_INT64
15024 .ft P
15025 .fi
15026 .UNINDENT
15027 .UNINDENT
15028 .TP
15029 .B \fBtrack\-list\fP
15030 List of audio/video/sub tracks, current entry marked. Currently, the raw
15031 property value is useless.
15032 .sp
15033 This has a number of sub\-properties. Replace \fBN\fP with the 0\-based track
15034 index.
15035 .INDENT 7.0
15036 .TP
15037 .B \fBtrack\-list/count\fP
15038 Total number of tracks.
15039 .TP
15040 .B \fBtrack\-list/N/id\fP
15041 The ID as it\(aqs used for \fB\-sid\fP/\fB\-\-aid\fP/\fB\-\-vid\fP\&. This is unique
15042 within tracks of the same type (sub/audio/video), but otherwise not.
15043 .TP
15044 .B \fBtrack\-list/N/type\fP
15045 String describing the media type. One of \fBaudio\fP, \fBvideo\fP, \fBsub\fP\&.
15046 .TP
15047 .B \fBtrack\-list/N/src\-id\fP
15048 Track ID as used in the source file. Not always available. (It is
15049 missing if the format has no native ID, if the track is a pseudo\-track
15050 that does not exist in this way in the actual file, or if the format
15051 is handled by libavformat, and the format was not whitelisted as having
15052 track IDs.)
15053 .TP
15054 .B \fBtrack\-list/N/title\fP
15055 Track title as it is stored in the file. Not always available.
15056 .TP
15057 .B \fBtrack\-list/N/lang\fP
15058 Track language as identified by the file. Not always available.
15059 .TP
15060 .B \fBtrack\-list/N/albumart\fP
15061 \fByes\fP/true if this is a video track that consists of a single
15062 picture, \fBno\fP/false or unavailable otherwise. This is used for video
15063 tracks that are really attached pictures in audio files.
15064 .TP
15065 .B \fBtrack\-list/N/default\fP
15066 \fByes\fP/true if the track has the default flag set in the file,
15067 \fBno\fP/false or unavailable otherwise.
15068 .TP
15069 .B \fBtrack\-list/N/forced\fP
15070 \fByes\fP/true if the track has the forced flag set in the file,
15071 \fBno\fP/false or unavailable otherwise.
15072 .TP
15073 .B \fBtrack\-list/N/codec\fP
15074 The codec name used by this track, for example \fBh264\fP\&. Unavailable
15075 in some rare cases.
15076 .TP
15077 .B \fBtrack\-list/N/external\fP
15078 \fByes\fP/true if the track is an external file, \fBno\fP/false or
15079 unavailable otherwise. This is set for separate subtitle files.
15080 .TP
15081 .B \fBtrack\-list/N/external\-filename\fP
15082 The filename if the track is from an external file, unavailable
15083 otherwise.
15084 .TP
15085 .B \fBtrack\-list/N/selected\fP
15086 \fByes\fP/true if the track is currently decoded, \fBno\fP/false or
15087 unavailable otherwise.
15088 .TP
15089 .B \fBtrack\-list/N/main\-selection\fP
15090 It indicates the selection order of tracks for the same type.
15091 If a track is not selected, or is selected by the \fB\-\-lavfi\-complex\fP,
15092 it is not available. For subtitle tracks, \fB0\fP represents the \fBsid\fP,
15093 and \fB1\fP represents the \fBsecondary\-sid\fP\&.
15094 .TP
15095 .B \fBtrack\-list/N/ff\-index\fP
15096 The stream index as usually used by the FFmpeg utilities. Note that
15097 this can be potentially wrong if a demuxer other than libavformat
15098 (\fB\-\-demuxer=lavf\fP) is used. For mkv files, the index will usually
15099 match even if the default (builtin) demuxer is used, but there is
15100 no hard guarantee.
15101 .TP
15102 .B \fBtrack\-list/N/decoder\-desc\fP
15103 If this track is being decoded, the human\-readable decoder name,
15104 .TP
15105 .B \fBtrack\-list/N/demux\-w\fP, \fBtrack\-list/N/demux\-h\fP
15106 Video size hint as indicated by the container. (Not always accurate.)
15107 .TP
15108 .B \fBtrack\-list/N/demux\-channel\-count\fP
15109 Number of audio channels as indicated by the container. (Not always
15110 accurate \- in particular, the track could be decoded as a different
15111 number of channels.)
15112 .TP
15113 .B \fBtrack\-list/N/demux\-channels\fP
15114 Channel layout as indicated by the container. (Not always accurate.)
15115 .TP
15116 .B \fBtrack\-list/N/demux\-samplerate\fP
15117 Audio sample rate as indicated by the container. (Not always accurate.)
15118 .TP
15119 .B \fBtrack\-list/N/demux\-fps\fP
15120 Video FPS as indicated by the container. (Not always accurate.)
15121 .TP
15122 .B \fBtrack\-list/N/demux\-bitrate\fP
15123 Audio average bitrate, in bits per second. (Not always accurate.)
15124 .TP
15125 .B \fBtrack\-list/N/demux\-rotation\fP
15126 Video clockwise rotation metadata, in degrees.
15127 .TP
15128 .B \fBtrack\-list/N/demux\-par\fP
15129 Pixel aspect ratio.
15130 .TP
15131 .B \fBtrack\-list/N/audio\-channels\fP (deprecated)
15132 Deprecated alias for \fBtrack\-list/N/demux\-channel\-count\fP\&.
15133 .TP
15134 .B \fBtrack\-list/N/replaygain\-track\-peak\fP, \fBtrack\-list/N/replaygain\-track\-gain\fP
15135 Per\-track replaygain values. Only available for audio tracks with
15136 corresponding information stored in the source file.
15137 .TP
15138 .B \fBtrack\-list/N/replaygain\-album\-peak\fP, \fBtrack\-list/N/replaygain\-album\-gain\fP
15139 Per\-album replaygain values. If the file has per\-track but no per\-album
15140 information, the per\-album values will be copied from the per\-track
15141 values currently. It\(aqs possible that future mpv versions will make
15142 these properties unavailable instead in this case.
15143 .UNINDENT
15144 .sp
15145 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
15146 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
15147 the following contents:
15148 .INDENT 7.0
15149 .INDENT 3.5
15150 .sp
15151 .nf
15152 .ft C
15153 MPV_FORMAT_NODE_ARRAY
15154 MPV_FORMAT_NODE_MAP (for each track)
15155 "id" MPV_FORMAT_INT64
15156 "type" MPV_FORMAT_STRING
15157 "src\-id" MPV_FORMAT_INT64
15158 "title" MPV_FORMAT_STRING
15159 "lang" MPV_FORMAT_STRING
15160 "albumart" MPV_FORMAT_FLAG
15161 "default" MPV_FORMAT_FLAG
15162 "forced" MPV_FORMAT_FLAG
15163 "selected" MPV_FORMAT_FLAG
15164 "main\-selection" MPV_FORMAT_INT64
15165 "external" MPV_FORMAT_FLAG
15166 "external\-filename" MPV_FORMAT_STRING
15167 "codec" MPV_FORMAT_STRING
15168 "ff\-index" MPV_FORMAT_INT64
15169 "decoder\-desc" MPV_FORMAT_STRING
15170 "demux\-w" MPV_FORMAT_INT64
15171 "demux\-h" MPV_FORMAT_INT64
15172 "demux\-channel\-count" MPV_FORMAT_INT64
15173 "demux\-channels" MPV_FORMAT_STRING
15174 "demux\-samplerate" MPV_FORMAT_INT64
15175 "demux\-fps" MPV_FORMAT_DOUBLE
15176 "demux\-bitrate" MPV_FORMAT_INT64
15177 "demux\-rotation" MPV_FORMAT_INT64
15178 "demux\-par" MPV_FORMAT_DOUBLE
15179 "audio\-channels" MPV_FORMAT_INT64
15180 "replaygain\-track\-peak" MPV_FORMAT_DOUBLE
15181 "replaygain\-track\-gain" MPV_FORMAT_DOUBLE
15182 "replaygain\-album\-peak" MPV_FORMAT_DOUBLE
15183 "replaygain\-album\-gain" MPV_FORMAT_DOUBLE
15184 .ft P
15185 .fi
15186 .UNINDENT
15187 .UNINDENT
15188 .TP
15189 .B \fBcurrent\-tracks/...\fP
15190 This gives access to currently selected tracks. It redirects to the correct
15191 entry in \fBtrack\-list\fP\&.
15192 .sp
15193 The following sub\-entries are defined: \fBvideo\fP, \fBaudio\fP, \fBsub\fP,
15194 \fBsub2\fP
15195 .sp
15196 For example, \fBcurrent\-tracks/audio/lang\fP returns the current audio track\(aqs
15197 language field (the same value as \fBtrack\-list/N/lang\fP).
15198 .sp
15199 A sub\-entry is accessible only if a track of that type is actually selected.
15200 Tracks selected via \fB\-\-lavfi\-complex\fP never appear under this property.
15201 \fBcurrent\-tracks\fP and \fBcurrent\-tracks/\fP are currently not accessible, and
15202 will not return anything.
15203 .sp
15204 Scripts etc. should not use this. They should use \fBtrack\-list\fP, loop over
15205 all tracks, and inspect the \fBselected\fP field to test whether a track is
15206 selected (or compare the \fBid\fP field to the \fBvideo\fP / \fBaudio\fP etc.
15207 options).
15208 .TP
15209 .B \fBchapter\-list\fP
15210 List of chapters, current entry marked. Currently, the raw property value
15211 is useless.
15212 .sp
15213 This has a number of sub\-properties. Replace \fBN\fP with the 0\-based chapter
15214 index.
15215 .INDENT 7.0
15216 .TP
15217 .B \fBchapter\-list/count\fP
15218 Number of chapters.
15219 .TP
15220 .B \fBchapter\-list/N/title\fP
15221 Chapter title as stored in the file. Not always available.
15222 .TP
15223 .B \fBchapter\-list/N/time\fP
15224 Chapter start time in seconds as float.
15225 .UNINDENT
15226 .sp
15227 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
15228 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
15229 the following contents:
15230 .INDENT 7.0
15231 .INDENT 3.5
15232 .sp
15233 .nf
15234 .ft C
15235 MPV_FORMAT_NODE_ARRAY
15236 MPV_FORMAT_NODE_MAP (for each chapter)
15237 "title" MPV_FORMAT_STRING
15238 "time" MPV_FORMAT_DOUBLE
15239 .ft P
15240 .fi
15241 .UNINDENT
15242 .UNINDENT
15243 .TP
15244 .B \fBaf\fP, \fBvf\fP (RW)
15245 See \fB\-\-vf\fP/\fB\-\-af\fP and the \fBvf\fP/\fBaf\fP command.
15246 .sp
15247 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
15248 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
15249 the following contents:
15250 .INDENT 7.0
15251 .INDENT 3.5
15252 .sp
15253 .nf
15254 .ft C
15255 MPV_FORMAT_NODE_ARRAY
15256 MPV_FORMAT_NODE_MAP (for each filter entry)
15257 "name" MPV_FORMAT_STRING
15258 "label" MPV_FORMAT_STRING [optional]
15259 "enabled" MPV_FORMAT_FLAG [optional]
15260 "params" MPV_FORMAT_NODE_MAP [optional]
15261 "key" MPV_FORMAT_STRING
15262 "value" MPV_FORMAT_STRING
15263 .ft P
15264 .fi
15265 .UNINDENT
15266 .UNINDENT
15267 .sp
15268 It\(aqs also possible to write the property using this format.
15269 .TP
15270 .B \fBseekable\fP
15271 Whether it\(aqs generally possible to seek in the current file.
15272 .TP
15273 .B \fBpartially\-seekable\fP
15274 Whether the current file is considered seekable, but only because the cache
15275 is active. This means small relative seeks may be fine, but larger seeks
15276 may fail anyway. Whether a seek will succeed or not is generally not known
15277 in advance.
15278 .sp
15279 If this property returns \fByes\fP/true, so will \fBseekable\fP\&.
15280 .TP
15281 .B \fBplayback\-abort\fP
15282 Whether playback is stopped or is to be stopped. (Useful in obscure
15283 situations like during \fBon_load\fP hook processing, when the user can stop
15284 playback, but the script has to explicitly end processing.)
15285 .TP
15286 .B \fBcursor\-autohide\fP (RW)
15287 See \fB\-\-cursor\-autohide\fP\&. Setting this to a new value will always update
15288 the cursor, and reset the internal timer.
15289 .TP
15290 .B \fBosd\-sym\-cc\fP
15291 Inserts the current OSD symbol as opaque OSD control code (cc). This makes
15292 sense only with the \fBshow\-text\fP command or options which set OSD messages.
15293 The control code is implementation specific and is useless for anything else.
15294 .TP
15295 .B \fBosd\-ass\-cc\fP
15296 \fB${osd\-ass\-cc/0}\fP disables escaping ASS sequences of text in OSD,
15297 \fB${osd\-ass\-cc/1}\fP enables it again. By default, ASS sequences are
15298 escaped to avoid accidental formatting, and this property can disable
15299 this behavior. Note that the properties return an opaque OSD control
15300 code, which only makes sense for the \fBshow\-text\fP command or options
15301 which set OSD messages.
15302 .INDENT 7.0
15303 .INDENT 3.5
15304 .IP "Example"
15305 .INDENT 0.0
15306 .IP \(bu 2
15307 \fB\-\-osd\-status\-msg=\(aqThis is ${osd\-ass\-cc/0}{\e\eb1}bold text\(aq\fP
15308 .IP \(bu 2
15309 \fBshow\-text "This is ${osd\-ass\-cc/0}{\eb1}bold text"\fP
15310 .UNINDENT
15311 .UNINDENT
15312 .UNINDENT
15313 .sp
15314 Any ASS override tags as understood by libass can be used.
15315 .sp
15316 Note that you need to escape the \fB\e\fP character, because the string is
15317 processed for C escape sequences before passing it to the OSD code.
15318 .sp
15319 A list of tags can be found here: \fI\%http://docs.aegisub.org/latest/ASS_Tags/\fP
15320 .TP
15321 .B \fBvo\-configured\fP
15322 Whether the VO is configured right now. Usually this corresponds to whether
15323 the video window is visible. If the \fB\-\-force\-window\fP option is used, this
15324 usually always returns \fByes\fP/true.
15325 .TP
15326 .B \fBvo\-passes\fP
15327 Contains introspection about the VO\(aqs active render passes and their
15328 execution times. Not implemented by all VOs.
15329 .sp
15330 This is further subdivided into two frame types, \fBvo\-passes/fresh\fP for
15331 fresh frames (which have to be uploaded, scaled, etc.) and
15332 \fBvo\-passes/redraw\fP for redrawn frames (which only have to be re\-painted).
15333 The number of passes for any given subtype can change from frame to frame,
15334 and should not be relied upon.
15335 .sp
15336 Each frame type has a number of further sub\-properties. Replace \fBTYPE\fP
15337 with the frame type, \fBN\fP with the 0\-based pass index, and \fBM\fP with the
15338 0\-based sample index.
15339 .INDENT 7.0
15340 .TP
15341 .B \fBvo\-passes/TYPE/count\fP
15342 Number of passes.
15343 .TP
15344 .B \fBvo\-passes/TYPE/N/desc\fP
15345 Human\-friendy description of the pass.
15346 .TP
15347 .B \fBvo\-passes/TYPE/N/last\fP
15348 Last measured execution time, in nanoseconds.
15349 .TP
15350 .B \fBvo\-passes/TYPE/N/avg\fP
15351 Average execution time of this pass, in nanoseconds. The exact
15352 timeframe varies, but it should generally be a handful of seconds.
15353 .TP
15354 .B \fBvo\-passes/TYPE/N/peak\fP
15355 The peak execution time (highest value) within this averaging range, in
15356 nanoseconds.
15357 .TP
15358 .B \fBvo\-passes/TYPE/N/count\fP
15359 The number of samples for this pass.
15360 .TP
15361 .B \fBvo\-passes/TYPE/N/samples/M\fP
15362 The raw execution time of a specific sample for this pass, in
15363 nanoseconds.
15364 .UNINDENT
15365 .sp
15366 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
15367 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
15368 the following contents:
15369 .INDENT 7.0
15370 .INDENT 3.5
15371 .sp
15372 .nf
15373 .ft C
15374 MPV_FORMAT_NODE_MAP
15375 "TYPE" MPV_FORMAT_NODE_ARRAY
15376 MPV_FORMAT_NODE_MAP
15377 "desc" MPV_FORMAT_STRING
15378 "last" MPV_FORMAT_INT64
15379 "avg" MPV_FORMAT_INT64
15380 "peak" MPV_FORMAT_INT64
15381 "count" MPV_FORMAT_INT64
15382 "samples" MPV_FORMAT_NODE_ARRAY
15383 MP_FORMAT_INT64
15384 .ft P
15385 .fi
15386 .UNINDENT
15387 .UNINDENT
15388 .sp
15389 Note that directly accessing this structure via subkeys is not supported,
15390 the only access is through aforementioned \fBMPV_FORMAT_NODE\fP\&.
15391 .TP
15392 .B \fBperf\-info\fP
15393 Further performance data. Querying this property triggers internal
15394 collection of some data, and may slow down the player. Each query will reset
15395 some internal state. Property change notification doesn\(aqt and won\(aqt work.
15396 All of this may change in the future, so don\(aqt use this. The builtin
15397 \fBstats\fP script is supposed to be the only user; since it\(aqs bundled and
15398 built with the source code, it can use knowledge of mpv internal to render
15399 the information properly. See \fBstats\fP script description for some details.
15400 .TP
15401 .B \fBvideo\-bitrate\fP, \fBaudio\-bitrate\fP, \fBsub\-bitrate\fP
15402 Bitrate values calculated on the packet level. This works by dividing the
15403 bit size of all packets between two keyframes by their presentation
15404 timestamp distance. (This uses the timestamps are stored in the file, so
15405 e.g. playback speed does not influence the returned values.) In particular,
15406 the video bitrate will update only per keyframe, and show the "past"
15407 bitrate. To make the property more UI friendly, updates to these properties
15408 are throttled in a certain way.
15409 .sp
15410 The unit is bits per second. OSD formatting turns these values in kilobits
15411 (or megabits, if appropriate), which can be prevented by using the
15412 raw property value, e.g. with \fB${=video\-bitrate}\fP\&.
15413 .sp
15414 Note that the accuracy of these properties is influenced by a few factors.
15415 If the underlying demuxer rewrites the packets on demuxing (done for some
15416 file formats), the bitrate might be slightly off. If timestamps are bad
15417 or jittery (like in Matroska), even constant bitrate streams might show
15418 fluctuating bitrate.
15419 .sp
15420 How exactly these values are calculated might change in the future.
15421 .sp
15422 In earlier versions of mpv, these properties returned a static (but bad)
15423 guess using a completely different method.
15424 .TP
15425 .B \fBpacket\-video\-bitrate\fP, \fBpacket\-audio\-bitrate\fP, \fBpacket\-sub\-bitrate\fP
15426 Old and deprecated properties for \fBvideo\-bitrate\fP, \fBaudio\-bitrate\fP,
15427 \fBsub\-bitrate\fP\&. They behave exactly the same, but return a value in
15428 kilobits. Also, they don\(aqt have any OSD formatting, though the same can be
15429 achieved with e.g. \fB${=video\-bitrate}\fP\&.
15430 .sp
15431 These properties shouldn\(aqt be used anymore.
15432 .TP
15433 .B \fBaudio\-device\-list\fP
15434 The list of discovered audio devices. This is mostly for use with the
15435 client API, and reflects what \fB\-\-audio\-device=help\fP with the command line
15436 player returns.
15437 .sp
15438 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
15439 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
15440 the following contents:
15441 .INDENT 7.0
15442 .INDENT 3.5
15443 .sp
15444 .nf
15445 .ft C
15446 MPV_FORMAT_NODE_ARRAY
15447 MPV_FORMAT_NODE_MAP (for each device entry)
15448 "name" MPV_FORMAT_STRING
15449 "description" MPV_FORMAT_STRING
15450 .ft P
15451 .fi
15452 .UNINDENT
15453 .UNINDENT
15454 .sp
15455 The \fBname\fP is what is to be passed to the \fB\-\-audio\-device\fP option (and
15456 often a rather cryptic audio API\-specific ID), while \fBdescription\fP is
15457 human readable free form text. The description is set to the device name
15458 (minus mpv\-specific \fB<driver>/\fP prefix) if no description is available
15459 or the description would have been an empty string.
15460 .sp
15461 The special entry with the name set to \fBauto\fP selects the default audio
15462 output driver and the default device.
15463 .sp
15464 The property can be watched with the property observation mechanism in
15465 the client API and in Lua scripts. (Technically, change notification is
15466 enabled the first time this property is read.)
15467 .TP
15468 .B \fBaudio\-device\fP (RW)
15469 Set the audio device. This directly reads/writes the \fB\-\-audio\-device\fP
15470 option, but on write accesses, the audio output will be scheduled for
15471 reloading.
15472 .sp
15473 Writing this property while no audio output is active will not automatically
15474 enable audio. (This is also true in the case when audio was disabled due to
15475 reinitialization failure after a previous write access to \fBaudio\-device\fP\&.)
15476 .sp
15477 This property also doesn\(aqt tell you which audio device is actually in use.
15478 .sp
15479 How these details are handled may change in the future.
15480 .TP
15481 .B \fBcurrent\-vo\fP
15482 Current video output driver (name as used with \fB\-\-vo\fP).
15483 .TP
15484 .B \fBcurrent\-ao\fP
15485 Current audio output driver (name as used with \fB\-\-ao\fP).
15486 .TP
15487 .B \fBshared\-script\-properties\fP (RW)
15488 This is a key/value map of arbitrary strings shared between scripts for
15489 general use. The player itself does not use any data in it (although some
15490 builtin scripts may). The property is not preserved across player restarts.
15491 .sp
15492 This is very primitive, inefficient, and annoying to use. It\(aqs a makeshift
15493 solution which could go away any time (for example, when a better solution
15494 becomes available). This is also why this property has an annoying name. You
15495 should avoid using it, unless you absolutely have to.
15496 .sp
15497 Lua scripting has helpers starting with \fButils.shared_script_property_\fP\&.
15498 They are undocumented because you should not use this property. If you still
15499 think you must, you should use the helpers instead of the property directly.
15500 .sp
15501 You are supposed to use the \fBchange\-list\fP command to modify the contents.
15502 Reading, modifying, and writing the property manually could data loss if two
15503 scripts update different keys at the same time due to lack of
15504 synchronization. The Lua helpers take care of this.
15505 .sp
15506 (There is no way to ensure synchronization if two scripts try to update the
15507 same key at the same time.)
15508 .TP
15509 .B \fBworking\-directory\fP
15510 The working directory of the mpv process. Can be useful for JSON IPC users,
15511 because the command line player usually works with relative paths.
15512 .TP
15513 .B \fBprotocol\-list\fP
15514 List of protocol prefixes potentially recognized by the player. They are
15515 returned without trailing \fB://\fP suffix (which is still always required).
15516 In some cases, the protocol will not actually be supported (consider
15517 \fBhttps\fP if ffmpeg is not compiled with TLS support).
15518 .TP
15519 .B \fBdecoder\-list\fP
15520 List of decoders supported. This lists decoders which can be passed to
15521 \fB\-\-vd\fP and \fB\-\-ad\fP\&.
15522 .INDENT 7.0
15523 .TP
15524 .B \fBcodec\fP
15525 Canonical codec name, which identifies the format the decoder can
15526 handle.
15527 .TP
15528 .B \fBdriver\fP
15529 The name of the decoder itself. Often, this is the same as \fBcodec\fP\&.
15530 Sometimes it can be different. It is used to distinguish multiple
15531 decoders for the same codec.
15532 .TP
15533 .B \fBdescription\fP
15534 Human readable description of the decoder and codec.
15535 .UNINDENT
15536 .sp
15537 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
15538 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
15539 the following contents:
15540 .INDENT 7.0
15541 .INDENT 3.5
15542 .sp
15543 .nf
15544 .ft C
15545 MPV_FORMAT_NODE_ARRAY
15546 MPV_FORMAT_NODE_MAP (for each decoder entry)
15547 "codec" MPV_FORMAT_STRING
15548 "driver" MPV_FORMAT_STRING
15549 "description" MPV_FORMAT_STRING
15550 .ft P
15551 .fi
15552 .UNINDENT
15553 .UNINDENT
15554 .TP
15555 .B \fBencoder\-list\fP
15556 List of libavcodec encoders. This has the same format as \fBdecoder\-list\fP\&.
15557 The encoder names (\fBdriver\fP entries) can be passed to \fB\-\-ovc\fP and
15558 \fB\-\-oac\fP (without the \fBlavc:\fP prefix required by \fB\-\-vd\fP and \fB\-\-ad\fP).
15559 .TP
15560 .B \fBdemuxer\-lavf\-list\fP
15561 List of available libavformat demuxers\(aq names. This can be used to check
15562 for support for a specific format or use with \fB\-\-demuxer\-lavf\-format\fP\&.
15563 .TP
15564 .B \fBinput\-key\-list\fP
15565 List of \fI\%Key names\fP, same as output by \fB\-\-input\-keylist\fP\&.
15566 .TP
15567 .B \fBmpv\-version\fP
15568 The mpv version/copyright string. Depending on how the binary was built, it
15569 might contain either a release version, or just a git hash.
15570 .TP
15571 .B \fBmpv\-configuration\fP
15572 The configuration arguments which were passed to the build system
15573 (typically the way \fB\&./waf configure ...\fP was invoked).
15574 .TP
15575 .B \fBffmpeg\-version\fP
15576 The contents of the \fBav_version_info()\fP API call. This is a string which
15577 identifies the build in some way, either through a release version number,
15578 or a git hash. This applies to Libav as well (the property is still named
15579 the same.) This property is unavailable if mpv is linked against older
15580 FFmpeg and Libav versions.
15581 .TP
15582 .B \fBlibass\-version\fP
15583 The value of \fBass_library_version()\fP\&. This is an integer, encoded in a
15584 somewhat weird form (apparently "hex BCD"), indicating the release version
15585 of the libass library linked to mpv.
15586 .TP
15587 .B \fBoptions/<name>\fP (RW)
15588 The value of option \fB\-\-<name>\fP\&. Most options can be changed at runtime by
15589 writing to this property. Note that many options require reloading the file
15590 for changes to take effect. If there is an equivalent property, prefer
15591 setting the property instead.
15592 .sp
15593 There shouldn\(aqt be any reason to access \fBoptions/<name>\fP instead of
15594 \fB<name>\fP, except in situations in which the properties have different
15595 behavior or conflicting semantics.
15596 .TP
15597 .B \fBfile\-local\-options/<name>\fP (RW)
15598 Similar to \fBoptions/<name>\fP, but when setting an option through this
15599 property, the option is reset to its old value once the current file has
15600 stopped playing. Trying to write an option while no file is playing (or
15601 is being loaded) results in an error.
15602 .sp
15603 (Note that if an option is marked as file\-local, even \fBoptions/\fP will
15604 access the local value, and the \fBold\fP value, which will be restored on
15605 end of playback, cannot be read or written until end of playback.)
15606 .TP
15607 .B \fBoption\-info/<name>\fP
15608 Additional per\-option information.
15609 .sp
15610 This has a number of sub\-properties. Replace \fB<name>\fP with the name of
15611 a top\-level option. No guarantee of stability is given to any of these
15612 sub\-properties \- they may change radically in the feature.
15613 .INDENT 7.0
15614 .TP
15615 .B \fBoption\-info/<name>/name\fP
15616 The name of the option.
15617 .TP
15618 .B \fBoption\-info/<name>/type\fP
15619 The name of the option type, like \fBString\fP or \fBInteger\fP\&. For many
15620 complex types, this isn\(aqt very accurate.
15621 .TP
15622 .B \fBoption\-info/<name>/set\-from\-commandline\fP
15623 Whether the option was set from the mpv command line. What this is set
15624 to if the option is e.g. changed at runtime is left undefined (meaning
15625 it could change in the future).
15626 .TP
15627 .B \fBoption\-info/<name>/set\-locally\fP
15628 Whether the option was set per\-file. This is the case with
15629 automatically loaded profiles, file\-dir configs, and other cases. It
15630 means the option value will be restored to the value before playback
15631 start when playback ends.
15632 .TP
15633 .B \fBoption\-info/<name>/default\-value\fP
15634 The default value of the option. May not always be available.
15635 .TP
15636 .B \fBoption\-info/<name>/min\fP, \fBoption\-info/<name>/max\fP
15637 Integer minimum and maximum values allowed for the option. Only
15638 available if the options are numeric, and the minimum/maximum has been
15639 set internally. It\(aqs also possible that only one of these is set.
15640 .TP
15641 .B \fBoption\-info/<name>/choices\fP
15642 If the option is a choice option, the possible choices. Choices that
15643 are integers may or may not be included (they can be implied by \fBmin\fP
15644 and \fBmax\fP). Note that options which behave like choice options, but
15645 are not actual choice options internally, may not have this info
15646 available.
15647 .UNINDENT
15648 .TP
15649 .B \fBproperty\-list\fP
15650 The list of top\-level properties.
15651 .TP
15652 .B \fBprofile\-list\fP
15653 The list of profiles and their contents. This is highly
15654 implementation\-specific, and may change any time. Currently, it returns an
15655 array of options for each profile. Each option has a name and a value, with
15656 the value currently always being a string. Note that the options array is
15657 not a map, as order matters and duplicate entries are possible. Recursive
15658 profiles are not expanded, and show up as special \fBprofile\fP options.
15659 .TP
15660 .B \fBcommand\-list\fP
15661 The list of input commands. This returns an array of maps, where each map
15662 node represents a command. This map currently only has a single entry:
15663 \fBname\fP for the name of the command. (This property is supposed to be a
15664 replacement for \fB\-\-input\-cmdlist\fP\&. The option dumps some more
15665 information, but it\(aqs a valid feature request to extend this property if
15666 needed.)
15667 .TP
15668 .B \fBinput\-bindings\fP
15669 The list of current input key bindings. This returns an array of maps,
15670 where each map node represents a binding for a single key/command. This map
15671 has the following entries:
15672 .INDENT 7.0
15673 .TP
15674 .B \fBkey\fP
15675 The key name. This is normalized and may look slightly different from
15676 how it was specified in the source (e.g. in input.conf).
15677 .TP
15678 .B \fBcmd\fP
15679 The command mapped to the key. (Currently, this is exactly the same
15680 string as specified in the source, other than stripping whitespace and
15681 comments. It\(aqs possible that it will be normalized in the future.)
15682 .TP
15683 .B \fBis_weak\fP
15684 If set to true, any existing and active user bindings will take priority.
15685 .TP
15686 .B \fBowner\fP
15687 If this entry exists, the name of the script (or similar) which added
15688 this binding.
15689 .TP
15690 .B \fBsection\fP
15691 Name of the section this binding is part of. This is a rarely used
15692 mechanism. This entry may be removed or change meaning in the future.
15693 .TP
15694 .B \fBpriority\fP
15695 A number. Bindings with a higher value are preferred over bindings
15696 with a lower value. If the value is negative, this binding is inactive
15697 and will not be triggered by input. Note that mpv does not use this
15698 value internally, and matching of bindings may work slightly differently
15699 in some cases. In addition, this value is dynamic and can change around
15700 at runtime.
15701 .TP
15702 .B \fBcomment\fP
15703 If available, the comment following the command on the same line. (For
15704 example, the input.conf entry \fBf cycle bla # toggle bla\fP would
15705 result in an entry with \fBcomment = "toggle bla", cmd = "cycle bla"\fP\&.)
15706 .UNINDENT
15707 .sp
15708 This property is read\-only, and change notification is not supported.
15709 Currently, there is no mechanism to change key bindings at runtime, other
15710 than scripts adding or removing their own bindings.
15711 .UNINDENT
15712 .SS Inconsistencies between options and properties
15713 .sp
15714 You can access (almost) all options as properties, though there are some
15715 caveats with some properties (due to historical reasons):
15716 .INDENT 0.0
15717 .TP
15718 .B \fBvid\fP, \fBaid\fP, \fBsid\fP
15719 While playback is active, these result the actually active tracks. For
15720 example, if you set \fBaid=5\fP, and the currently played file contains no
15721 audio track with ID 5, the \fBaid\fP property will return \fBno\fP\&.
15722 .sp
15723 Before mpv 0.31.0, you could set existing tracks at runtime only.
15724 .TP
15725 .B \fBdisplay\-fps\fP
15726 This inconsistent behavior is deprecated. Post\-deprecation, the reported
15727 value and the option value are cleanly separated (\fBoverride\-display\-fps\fP
15728 for the option value).
15729 .TP
15730 .B \fBvf\fP, \fBaf\fP
15731 If you set the properties during playback, and the filter chain fails to
15732 reinitialize, the option will be set, but the runtime filter chain does not
15733 change. On the other hand, the next video to be played will fail, because
15734 the initial filter chain cannot be created.
15735 .sp
15736 This behavior changed in mpv 0.31.0. Before this, the new value was rejected
15737 \fIiff\fP video (for \fBvf\fP) or audio (for \fBaf\fP) was active. If playback was
15738 not active, the behavior was the same as the current behavior.
15739 .TP
15740 .B \fBplaylist\fP
15741 The property is read\-only and returns the current internal playlist. The
15742 option is for loading playlist during command line parsing. For client API
15743 uses, you should use the \fBloadlist\fP command instead.
15744 .TP
15745 .B \fBprofile\fP, \fBinclude\fP
15746 These are write\-only, and will perform actions as they are written to,
15747 exactly as if they were used on the mpv CLI commandline. Their only use is
15748 when using libmpv before \fBmpv_initialize()\fP, which in turn is probably
15749 only useful in encoding mode. Normal libmpv users should use other
15750 mechanisms, such as the \fBapply\-profile\fP command, and the
15751 \fBmpv_load_config_file\fP API function. Avoid these properties.
15752 .UNINDENT
15753 .SS Property Expansion
15754 .sp
15755 All string arguments to input commands as well as certain options (like
15756 \fB\-\-term\-playing\-msg\fP) are subject to property expansion. Note that property
15757 expansion does not work in places where e.g. numeric parameters are expected.
15758 (For example, the \fBadd\fP command does not do property expansion. The \fBset\fP
15759 command is an exception and not a general rule.)
15760 .INDENT 0.0
15761 .INDENT 3.5
15762 .IP "Example for input.conf"
15763 .INDENT 0.0
15764 .TP
15765 .B \fBi show\-text "Filename: ${filename}"\fP
15766 shows the filename of the current file when pressing the \fBi\fP key
15767 .UNINDENT
15768 .UNINDENT
15769 .UNINDENT
15770 .sp
15771 Within \fBinput.conf\fP, property expansion can be inhibited by putting the
15772 \fBraw\fP prefix in front of commands.
15773 .sp
15774 The following expansions are supported:
15775 .INDENT 0.0
15776 .TP
15777 .B \fB${NAME}\fP
15778 Expands to the value of the property \fBNAME\fP\&. If retrieving the property
15779 fails, expand to an error string. (Use \fB${NAME:}\fP with a trailing
15780 \fB:\fP to expand to an empty string instead.)
15781 If \fBNAME\fP is prefixed with \fB=\fP, expand to the raw value of the property
15782 (see section below).
15783 .TP
15784 .B \fB${NAME:STR}\fP
15785 Expands to the value of the property \fBNAME\fP, or \fBSTR\fP if the
15786 property cannot be retrieved. \fBSTR\fP is expanded recursively.
15787 .TP
15788 .B \fB${?NAME:STR}\fP
15789 Expands to \fBSTR\fP (recursively) if the property \fBNAME\fP is available.
15790 .TP
15791 .B \fB${!NAME:STR}\fP
15792 Expands to \fBSTR\fP (recursively) if the property \fBNAME\fP cannot be
15793 retrieved.
15794 .TP
15795 .B \fB${?NAME==VALUE:STR}\fP
15796 Expands to \fBSTR\fP (recursively) if the property \fBNAME\fP expands to a
15797 string equal to \fBVALUE\fP\&. You can prefix \fBNAME\fP with \fB=\fP in order to
15798 compare the raw value of a property (see section below). If the property
15799 is unavailable, or other errors happen when retrieving it, the value is
15800 never considered equal.
15801 Note that \fBVALUE\fP can\(aqt contain any of the characters \fB:\fP or \fB}\fP\&.
15802 Also, it is possible that escaping with \fB"\fP or \fB%\fP might be added in
15803 the future, should the need arise.
15804 .TP
15805 .B \fB${!NAME==VALUE:STR}\fP
15806 Same as with the \fB?\fP variant, but \fBSTR\fP is expanded if the value is
15807 not equal. (Using the same semantics as with \fB?\fP\&.)
15808 .TP
15809 .B \fB$$\fP
15810 Expands to \fB$\fP\&.
15811 .TP
15812 .B \fB$}\fP
15813 Expands to \fB}\fP\&. (To produce this character inside recursive
15814 expansion.)
15815 .TP
15816 .B \fB$>\fP
15817 Disable property expansion and special handling of \fB$\fP for the rest
15818 of the string.
15819 .UNINDENT
15820 .sp
15821 In places where property expansion is allowed, C\-style escapes are often
15822 accepted as well. Example:
15823 .INDENT 0.0
15824 .INDENT 3.5
15825 .INDENT 0.0
15826 .IP \(bu 2
15827 \fB\en\fP becomes a newline character
15828 .IP \(bu 2
15829 \fB\e\e\fP expands to \fB\e\fP
15830 .UNINDENT
15831 .UNINDENT
15832 .UNINDENT
15833 .SS Raw and Formatted Properties
15834 .sp
15835 Normally, properties are formatted as human\-readable text, meant to be
15836 displayed on OSD or on the terminal. It is possible to retrieve an unformatted
15837 (raw) value from a property by prefixing its name with \fB=\fP\&. These raw values
15838 can be parsed by other programs and follow the same conventions as the options
15839 associated with the properties.
15840 .INDENT 0.0
15841 .INDENT 3.5
15842 .IP "Examples"
15843 .INDENT 0.0
15844 .IP \(bu 2
15845 \fB${time\-pos}\fP expands to \fB00:14:23\fP (if playback position is at 14
15846 minutes 23 seconds)
15847 .IP \(bu 2
15848 \fB${=time\-pos}\fP expands to \fB863.4\fP (same time, plus 400 milliseconds \-
15849 milliseconds are normally not shown in the formatted case)
15850 .UNINDENT
15851 .UNINDENT
15852 .UNINDENT
15853 .sp
15854 Sometimes, the difference in amount of information carried by raw and formatted
15855 property values can be rather big. In some cases, raw values have more
15856 information, like higher precision than seconds with \fBtime\-pos\fP\&. Sometimes
15857 it is the other way around, e.g. \fBaid\fP shows track title and language in the
15858 formatted case, but only the track number if it is raw.
15859 .SH ON SCREEN CONTROLLER
15860 .sp
15861 The On Screen Controller (short: OSC) is a minimal GUI integrated with mpv to
15862 offer basic mouse\-controllability. It is intended to make interaction easier
15863 for new users and to enable precise and direct seeking.
15864 .sp
15865 The OSC is enabled by default if mpv was compiled with Lua support. It can be
15866 disabled entirely using the \fB\-\-osc=no\fP option.
15867 .SS Using the OSC
15868 .sp
15869 By default, the OSC will show up whenever the mouse is moved inside the
15870 player window and will hide if the mouse is not moved outside the OSC for
15871 0.5 seconds or if the mouse leaves the window.
15872 .SS The Interface
15873 .INDENT 0.0
15874 .INDENT 3.5
15875 .sp
15876 .nf
15877 .ft C
15878 +\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+
15879 | pl prev | pl next | title | cache |
15880 +\-\-\-\-\-\-+\-\-+\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-+
15881 | play | skip | skip | time | seekbar | time | audio | sub | vol | fs |
15882 | | back | frwd | elapsed | | left | | | | |
15883 +\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-+
15884 .ft P
15885 .fi
15886 .UNINDENT
15887 .UNINDENT
15888 .INDENT 0.0
15889 .TP
15890 .B pl prev
15891 .TS
15892 center;
15893 |l|l|.
15894 _
15895 T{
15896 left\-click
15897 T} T{
15898 play previous file in playlist
15899 T}
15900 _
15901 T{
15902 right\-click
15903 T} T{
15904 show playlist
15905 T}
15906 _
15907 T{
15908 shift+L\-click
15909 T} T{
15910 show playlist
15911 T}
15912 _
15913 .TE
15914 .TP
15915 .B pl next
15916 .TS
15917 center;
15918 |l|l|.
15919 _
15920 T{
15921 left\-click
15922 T} T{
15923 play next file in playlist
15924 T}
15925 _
15926 T{
15927 right\-click
15928 T} T{
15929 show playlist
15930 T}
15931 _
15932 T{
15933 shift+L\-click
15934 T} T{
15935 show playlist
15936 T}
15937 _
15938 .TE
15939 .TP
15940 .B title
15941 .nf
15942 Displays current media\-title, filename, or custom title
15943 .fi
15944 .sp
15945 .TS
15946 center;
15947 |l|l|.
15948 _
15949 T{
15950 left\-click
15951 T} T{
15952 show playlist position and length and full title
15953 T}
15954 _
15955 T{
15956 right\-click
15957 T} T{
15958 show filename
15959 T}
15960 _
15961 .TE
15962 .TP
15963 .B cache
15964 .nf
15965 Shows current cache fill status
15966 .fi
15967 .sp
15968 .TP
15969 .B play
15970 .TS
15971 center;
15972 |l|l|.
15973 _
15974 T{
15975 left\-click
15976 T} T{
15977 toggle play/pause
15978 T}
15979 _
15980 .TE
15981 .TP
15982 .B skip back
15983 .TS
15984 center;
15985 |l|l|.
15986 _
15987 T{
15988 left\-click
15989 T} T{
15990 go to beginning of chapter / previous chapter
15991 T}
15992 _
15993 T{
15994 right\-click
15995 T} T{
15996 show chapters
15997 T}
15998 _
15999 T{
16000 shift+L\-click
16001 T} T{
16002 show chapters
16003 T}
16004 _
16005 .TE
16006 .TP
16007 .B skip frwd
16008 .TS
16009 center;
16010 |l|l|.
16011 _
16012 T{
16013 left\-click
16014 T} T{
16015 go to next chapter
16016 T}
16017 _
16018 T{
16019 right\-click
16020 T} T{
16021 show chapters
16022 T}
16023 _
16024 T{
16025 shift+L\-click
16026 T} T{
16027 show chapters
16028 T}
16029 _
16030 .TE
16031 .TP
16032 .B time elapsed
16033 .nf
16034 Shows current playback position timestamp
16035 .fi
16036 .sp
16037 .TS
16038 center;
16039 |l|l|.
16040 _
16041 T{
16042 left\-click
16043 T} T{
16044 toggle displaying timecodes with milliseconds
16045 T}
16046 _
16047 .TE
16048 .TP
16049 .B seekbar
16050 .nf
16051 Indicates current playback position and position of chapters
16052 .fi
16053 .sp
16054 .TS
16055 center;
16056 |l|l|.
16057 _
16058 T{
16059 left\-click
16060 T} T{
16061 seek to position
16062 T}
16063 _
16064 .TE
16065 .TP
16066 .B time left
16067 .nf
16068 Shows remaining playback time timestamp
16069 .fi
16070 .sp
16071 .TS
16072 center;
16073 |l|l|.
16074 _
16075 T{
16076 left\-click
16077 T} T{
16078 toggle between total and remaining time
16079 T}
16080 _
16081 .TE
16082 .TP
16083 .B audio and sub
16084 .nf
16085 Displays selected track and amount of available tracks
16086 .fi
16087 .sp
16088 .TS
16089 center;
16090 |l|l|.
16091 _
16092 T{
16093 left\-click
16094 T} T{
16095 cycle audio/sub tracks forward
16096 T}
16097 _
16098 T{
16099 right\-click
16100 T} T{
16101 cycle audio/sub tracks backwards
16102 T}
16103 _
16104 T{
16105 shift+L\-click
16106 T} T{
16107 show available audio/sub tracks
16108 T}
16109 _
16110 .TE
16111 .TP
16112 .B vol
16113 .TS
16114 center;
16115 |l|l|.
16116 _
16117 T{
16118 left\-click
16119 T} T{
16120 toggle mute
16121 T}
16122 _
16123 T{
16124 mouse wheel
16125 T} T{
16126 volume up/down
16127 T}
16128 _
16129 .TE
16130 .TP
16131 .B fs
16132 .TS
16133 center;
16134 |l|l|.
16135 _
16136 T{
16137 left\-click
16138 T} T{
16139 toggle fullscreen
16140 T}
16141 _
16142 .TE
16143 .UNINDENT
16144 .SS Key Bindings
16145 .sp
16146 These key bindings are active by default if nothing else is already bound to
16147 these keys. In case of collision, the function needs to be bound to a
16148 different key. See the \fI\%Script Commands\fP section.
16149 .TS
16150 center;
16151 |l|l|.
16152 _
16153 T{
16154 del
16155 T} T{
16156 Cycles visibility between never / auto (mouse\-move) / always
16157 T}
16158 _
16159 .TE
16160 .SS Configuration
16161 .sp
16162 The OSC offers limited configuration through a config file
16163 \fBscript\-opts/osc.conf\fP placed in mpv\(aqs user dir and through the
16164 \fB\-\-script\-opts\fP command\-line option. Options provided through the command\-line
16165 will override those from the config file.
16166 .SS Config Syntax
16167 .sp
16168 The config file must exactly follow the following syntax:
16169 .INDENT 0.0
16170 .INDENT 3.5
16171 .sp
16172 .nf
16173 .ft C
16174 # this is a comment
16175 optionA=value1
16176 optionB=value2
16177 .ft P
16178 .fi
16179 .UNINDENT
16180 .UNINDENT
16181 .sp
16182 \fB#\fP can only be used at the beginning of a line and there may be no
16183 spaces around the \fB=\fP or anywhere else.
16184 .SS Command\-line Syntax
16185 .sp
16186 To avoid collisions with other scripts, all options need to be prefixed with
16187 \fBosc\-\fP\&.
16188 .sp
16189 Example:
16190 .INDENT 0.0
16191 .INDENT 3.5
16192 .sp
16193 .nf
16194 .ft C
16195 \-\-script\-opts=osc\-optionA=value1,osc\-optionB=value2
16196 .ft P
16197 .fi
16198 .UNINDENT
16199 .UNINDENT
16200 .SS Configurable Options
16201 .INDENT 0.0
16202 .TP
16203 .B \fBlayout\fP
16204 Default: bottombar
16205 .sp
16206 The layout for the OSC. Currently available are: box, slimbox,
16207 bottombar and topbar. Default pre\-0.21.0 was \(aqbox\(aq.
16208 .TP
16209 .B \fBseekbarstyle\fP
16210 Default: bar
16211 .sp
16212 Sets the style of the playback position marker and overall shape
16213 of the seekbar: \fBbar\fP, \fBdiamond\fP or \fBknob\fP\&.
16214 .TP
16215 .B \fBseekbarhandlesize\fP
16216 Default: 0.6
16217 .sp
16218 Size ratio of the seek handle if \fBseekbarstyle\fP is set to \fBdimaond\fP
16219 or \fBknob\fP\&. This is relative to the full height of the seekbar.
16220 .TP
16221 .B \fBseekbarkeyframes\fP
16222 Default: yes
16223 .sp
16224 Controls the mode used to seek when dragging the seekbar (default: true). If
16225 set to true, default seeking mode is used (usually keyframes, but player
16226 defaults and heuristics can change it to exact). If set to false, exact
16227 seeking on mouse drags will be used instead. Keyframes are preferred, but
16228 exact seeks may be useful in cases where keyframes cannot be found. Note
16229 that using exact seeks can potentially make mouse dragging much slower.
16230 .TP
16231 .B \fBseekrangestyle\fP
16232 Default: inverted
16233 .sp
16234 Display seekable ranges on the seekbar. \fBbar\fP shows them on the full
16235 height of the bar, \fBline\fP as a thick line and \fBinverted\fP as a thin
16236 line that is inverted over playback position markers. \fBnone\fP will hide
16237 them. Additionally, \fBslider\fP will show a permanent handle inside the seekbar
16238 with cached ranges marked inside. Note that these will look differently
16239 based on the seekbarstyle option. Also, \fBslider\fP does not work with
16240 \fBseekbarstyle\fP set to \fBbar\fP\&.
16241 .TP
16242 .B \fBseekrangeseparate\fP
16243 Default: yes
16244 .sp
16245 Controls whether to show line\-style seekable ranges on top of the
16246 seekbar or separately if \fBseekbarstyle\fP is set to \fBbar\fP\&.
16247 .TP
16248 .B \fBseekrangealpha\fP
16249 Default: 200
16250 .sp
16251 Alpha of the seekable ranges, 0 (opaque) to 255 (fully transparent).
16252 .TP
16253 .B \fBdeadzonesize\fP
16254 Default: 0.5
16255 .sp
16256 Size of the deadzone. The deadzone is an area that makes the mouse act
16257 like leaving the window. Movement there won\(aqt make the OSC show up and
16258 it will hide immediately if the mouse enters it. The deadzone starts
16259 at the window border opposite to the OSC and the size controls how much
16260 of the window it will span. Values between 0.0 and 1.0, where 0 means the
16261 OSC will always popup with mouse movement in the window, and 1 means the
16262 OSC will only show up when the mouse hovers it. Default pre\-0.21.0 was 0.
16263 .TP
16264 .B \fBminmousemove\fP
16265 Default: 0
16266 .sp
16267 Minimum amount of pixels the mouse has to move between ticks to make
16268 the OSC show up. Default pre\-0.21.0 was 3.
16269 .TP
16270 .B \fBshowwindowed\fP
16271 Default: yes
16272 .sp
16273 Enable the OSC when windowed
16274 .TP
16275 .B \fBshowfullscreen\fP
16276 Default: yes
16277 .sp
16278 Enable the OSC when fullscreen
16279 .TP
16280 .B \fBscalewindowed\fP
16281 Default: 1.0
16282 .sp
16283 Scale factor of the OSC when windowed.
16284 .TP
16285 .B \fBscalefullscreen\fP
16286 Default: 1.0
16287 .sp
16288 Scale factor of the OSC when fullscreen
16289 .TP
16290 .B \fBscaleforcedwindow\fP
16291 Default: 2.0
16292 .sp
16293 Scale factor of the OSC when rendered on a forced (dummy) window
16294 .TP
16295 .B \fBvidscale\fP
16296 Default: yes
16297 .sp
16298 Scale the OSC with the video
16299 \fBno\fP tries to keep the OSC size constant as much as the window size allows
16300 .TP
16301 .B \fBvalign\fP
16302 Default: 0.8
16303 .sp
16304 Vertical alignment, \-1 (top) to 1 (bottom)
16305 .TP
16306 .B \fBhalign\fP
16307 Default: 0.0
16308 .sp
16309 Horizontal alignment, \-1 (left) to 1 (right)
16310 .TP
16311 .B \fBbarmargin\fP
16312 Default: 0
16313 .sp
16314 Margin from bottom (bottombar) or top (topbar), in pixels
16315 .TP
16316 .B \fBboxalpha\fP
16317 Default: 80
16318 .sp
16319 Alpha of the background box, 0 (opaque) to 255 (fully transparent)
16320 .TP
16321 .B \fBhidetimeout\fP
16322 Default: 500
16323 .sp
16324 Duration in ms until the OSC hides if no mouse movement, must not be
16325 negative
16326 .TP
16327 .B \fBfadeduration\fP
16328 Default: 200
16329 .sp
16330 Duration of fade out in ms, 0 = no fade
16331 .TP
16332 .B \fBtitle\fP
16333 Default: ${media\-title}
16334 .sp
16335 String that supports property expansion that will be displayed as
16336 OSC title.
16337 ASS tags are escaped, and newlines and trailing slashes are stripped.
16338 .TP
16339 .B \fBtooltipborder\fP
16340 Default: 1
16341 .sp
16342 Size of the tooltip outline when using bottombar or topbar layouts
16343 .TP
16344 .B \fBtimetotal\fP
16345 Default: no
16346 .sp
16347 Show total time instead of time remaining
16348 .TP
16349 .B \fBtimems\fP
16350 Default: no
16351 .sp
16352 Display timecodes with milliseconds
16353 .TP
16354 .B \fBvisibility\fP
16355 Default: auto (auto hide/show on mouse move)
16356 .sp
16357 Also supports \fBnever\fP and \fBalways\fP
16358 .TP
16359 .B \fBboxmaxchars\fP
16360 Default: 80
16361 .sp
16362 Max chars for the osc title at the box layout. mpv does not measure the
16363 text width on screen and so it needs to limit it by number of chars. The
16364 default is conservative to allow wide fonts to be used without overflow.
16365 However, with many common fonts a bigger number can be used. YMMV.
16366 .TP
16367 .B \fBboxvideo\fP
16368 Default: no
16369 .sp
16370 Whether to overlay the osc over the video (\fBno\fP), or to box the video
16371 within the areas not covered by the osc (\fByes\fP). If this option is set,
16372 the osc may overwrite the \fB\-\-video\-margin\-ratio\-*\fP options, even if the
16373 user has set them. (It will not overwrite them if all of them are set to
16374 default values.) Additionally, \fBvisibility\fP must be set to \fBalways\fP\&.
16375 Otherwise, this option does nothing.
16376 .sp
16377 Currently, this is supported for the \fBbottombar\fP and \fBtopbar\fP layout
16378 only. The other layouts do not change if this option is set. Separately,
16379 if window controls are present (see below), they will be affected
16380 regardless of which osc layout is in use.
16381 .sp
16382 The border is static and appears even if the OSC is configured to appear
16383 only on mouse interaction. If the OSC is invisible, the border is simply
16384 filled with the background color (black by default).
16385 .sp
16386 This currently still makes the OSC overlap with subtitles (if the
16387 \fB\-\-sub\-use\-margins\fP option is set to \fByes\fP, the default). This may be
16388 fixed later.
16389 .sp
16390 This does not work correctly with video outputs like \fB\-\-vo=xv\fP, which
16391 render OSD into the unscaled video.
16392 .TP
16393 .B \fBwindowcontrols\fP
16394 Default: auto (Show window controls if there is no window border)
16395 .sp
16396 Whether to show window management controls over the video, and if so,
16397 which side of the window to place them. This may be desirable when the
16398 window has no decorations, either because they have been explicitly
16399 disabled (\fBborder=no\fP) or because the current platform doesn\(aqt support
16400 them (eg: gnome\-shell with wayland).
16401 .sp
16402 The set of window controls is fixed, offering \fBminimize\fP, \fBmaximize\fP,
16403 and \fBquit\fP\&. Not all platforms implement \fBminimize\fP and \fBmaximize\fP,
16404 but \fBquit\fP will always work.
16405 .TP
16406 .B \fBwindowcontrols_alignment\fP
16407 Default: right
16408 .sp
16409 If window controls are shown, indicates which side should they be aligned
16410 to.
16411 .sp
16412 Supports \fBleft\fP and \fBright\fP which will place the controls on those
16413 respective sides.
16414 .TP
16415 .B \fBgreenandgrumpy\fP
16416 Default: no
16417 .sp
16418 Set to \fByes\fP to reduce festivity (i.e. disable santa hat in December.)
16419 .UNINDENT
16420 .SS Script Commands
16421 .sp
16422 The OSC script listens to certain script commands. These commands can bound
16423 in \fBinput.conf\fP, or sent by other scripts.
16424 .INDENT 0.0
16425 .TP
16426 .B \fBosc\-message\fP
16427 Show a message on screen using the OSC. First argument is the message,
16428 second the duration in seconds.
16429 .TP
16430 .B \fBosc\-visibility\fP
16431 Controls visibility mode \fBnever\fP / \fBauto\fP (on mouse move) / \fBalways\fP
16432 and also \fBcycle\fP to cycle between the modes
16433 .UNINDENT
16434 .sp
16435 Example
16436 .sp
16437 You could put this into \fBinput.conf\fP to hide the OSC with the \fBa\fP key and
16438 to set auto mode (the default) with \fBb\fP:
16439 .INDENT 0.0
16440 .INDENT 3.5
16441 .sp
16442 .nf
16443 .ft C
16444 a script\-message osc\-visibility never
16445 b script\-message osc\-visibility auto
16446 .ft P
16447 .fi
16448 .UNINDENT
16449 .UNINDENT
16450 .INDENT 0.0
16451 .TP
16452 .B \fBosc\-playlist\fP, \fBosc\-chapterlist\fP, \fBosc\-tracklist\fP
16453 Shows a limited view of the respective type of list using the OSC. First
16454 argument is duration in seconds.
16455 .UNINDENT
16456 .SH STATS
16457 .sp
16458 This builtin script displays information and statistics for the currently
16459 played file. It is enabled by default if mpv was compiled with Lua support.
16460 It can be disabled entirely using the \fB\-\-load\-stats\-overlay=no\fP option.
16461 .SS Usage
16462 .sp
16463 The following key bindings are active by default unless something else is
16464 already bound to them:
16465 .TS
16466 center;
16467 |l|l|.
16468 _
16469 T{
16470 i
16471 T} T{
16472 Show stats for a fixed duration
16473 T}
16474 _
16475 T{
16476 I
16477 T} T{
16478 Toggle stats (shown until toggled again)
16479 T}
16480 _
16481 .TE
16482 .sp
16483 While the stats are visible on screen the following key bindings are active,
16484 regardless of existing bindings. They allow you to switch between \fIpages\fP of
16485 stats:
16486 .TS
16487 center;
16488 |l|l|.
16489 _
16490 T{
16491 1
16492 T} T{
16493 Show usual stats
16494 T}
16495 _
16496 T{
16497 2
16498 T} T{
16499 Show frame timings (scroll)
16500 T}
16501 _
16502 T{
16503 3
16504 T} T{
16505 Input cache stats
16506 T}
16507 _
16508 T{
16509 4
16510 T} T{
16511 Internal stuff (scroll)
16512 T}
16513 _
16514 .TE
16515 .sp
16516 On pages which support scroll, these key bindings are also active:
16517 .TS
16518 center;
16519 |l|l|.
16520 _
16521 T{
16522 UP
16523 T} T{
16524 Scroll one line up
16525 T}
16526 _
16527 T{
16528 DOWN
16529 T} T{
16530 Scroll one line down
16531 T}
16532 _
16533 .TE
16534 .SS Font
16535 .sp
16536 For optimal visual experience, a font with support for many font weights and
16537 monospaced digits is recommended. By default, the open source font
16538 \fI\%Source Sans Pro\fP is used.
16539 .SS Configuration
16540 .sp
16541 This script can be customized through a config file \fBscript\-opts/stats.conf\fP
16542 placed in mpv\(aqs user directory and through the \fB\-\-script\-opts\fP command\-line
16543 option. The configuration syntax is described in \fI\%ON SCREEN CONTROLLER\fP\&.
16544 .SS Configurable Options
16545 .INDENT 0.0
16546 .TP
16547 .B \fBkey_oneshot\fP
16548 Default: i
16549 .TP
16550 .B \fBkey_toggle\fP
16551 Default: I
16552 .sp
16553 Key bindings to display stats.
16554 .TP
16555 .B \fBkey_page_1\fP
16556 Default: 1
16557 .TP
16558 .B \fBkey_page_2\fP
16559 Default: 2
16560 .TP
16561 .B \fBkey_page_3\fP
16562 Default: 3
16563 .TP
16564 .B \fBkey_page_4\fP
16565 Default: 4
16566 .sp
16567 Key bindings for page switching while stats are displayed.
16568 .TP
16569 .B \fBkey_scroll_up\fP
16570 Default: UP
16571 .TP
16572 .B \fBkey_scroll_down\fP
16573 Default: DOWN
16574 .TP
16575 .B \fBscroll_lines\fP
16576 Default: 1
16577 .sp
16578 Scroll key bindings and number of lines to scroll on pages which support it.
16579 .TP
16580 .B \fBduration\fP
16581 Default: 4
16582 .sp
16583 How long the stats are shown in seconds (oneshot).
16584 .TP
16585 .B \fBredraw_delay\fP
16586 Default: 1
16587 .sp
16588 How long it takes to refresh the displayed stats in seconds (toggling).
16589 .TP
16590 .B \fBpersistent_overlay\fP
16591 Default: no
16592 .sp
16593 When \fIno\fP, other scripts printing text to the screen can overwrite the
16594 displayed stats. When \fIyes\fP, displayed stats are persistently shown for the
16595 respective duration. This can result in overlapping text when multiple
16596 scripts decide to print text at the same time.
16597 .TP
16598 .B \fBplot_perfdata\fP
16599 Default: yes
16600 .sp
16601 Show graphs for performance data (page 2).
16602 .TP
16603 .B \fBplot_vsync_ratio\fP
16604 Default: yes
16605 .TP
16606 .B \fBplot_vsync_jitter\fP
16607 Default: yes
16608 .sp
16609 Show graphs for vsync and jitter values (page 1). Only when toggled.
16610 .TP
16611 .B \fBflush_graph_data\fP
16612 Default: yes
16613 .sp
16614 Clear data buffers used for drawing graphs when toggling.
16615 .TP
16616 .B \fBfont\fP
16617 Default: Source Sans Pro
16618 .sp
16619 Font name. Should support as many font weights as possible for optimal
16620 visual experience.
16621 .TP
16622 .B \fBfont_mono\fP
16623 Default: Source Sans Pro
16624 .sp
16625 Font name for parts where monospaced characters are necessary to align
16626 text. Currently, monospaced digits are sufficient.
16627 .TP
16628 .B \fBfont_size\fP
16629 Default: 8
16630 .sp
16631 Font size used to render text.
16632 .TP
16633 .B \fBfont_color\fP
16634 Default: FFFFFF
16635 .sp
16636 Font color.
16637 .TP
16638 .B \fBborder_size\fP
16639 Default: 0.8
16640 .sp
16641 Size of border drawn around the font.
16642 .TP
16643 .B \fBborder_color\fP
16644 Default: 262626
16645 .sp
16646 Color of drawn border.
16647 .TP
16648 .B \fBalpha\fP
16649 Default: 11
16650 .sp
16651 Transparency for drawn text.
16652 .TP
16653 .B \fBplot_bg_border_color\fP
16654 Default: 0000FF
16655 .sp
16656 Border color used for drawing graphs.
16657 .TP
16658 .B \fBplot_bg_color\fP
16659 Default: 262626
16660 .sp
16661 Background color used for drawing graphs.
16662 .TP
16663 .B \fBplot_color\fP
16664 Default: FFFFFF
16665 .sp
16666 Color used for drawing graphs.
16667 .UNINDENT
16668 .sp
16669 Note: colors are given as hexadecimal values and use ASS tag order: BBGGRR
16670 (blue green red).
16671 .SS Different key bindings
16672 .sp
16673 A different key binding can be defined with the aforementioned options
16674 \fBkey_oneshot\fP and \fBkey_toggle\fP but also with commands in \fBinput.conf\fP,
16675 for example:
16676 .INDENT 0.0
16677 .INDENT 3.5
16678 .sp
16679 .nf
16680 .ft C
16681 e script\-binding stats/display\-stats
16682 E script\-binding stats/display\-stats\-toggle
16683 .ft P
16684 .fi
16685 .UNINDENT
16686 .UNINDENT
16687 .sp
16688 Using \fBinput.conf\fP, it is also possible to directly display a certain page:
16689 .INDENT 0.0
16690 .INDENT 3.5
16691 .sp
16692 .nf
16693 .ft C
16694 i script\-binding stats/display\-page\-1
16695 e script\-binding stats/display\-page\-2
16696 .ft P
16697 .fi
16698 .UNINDENT
16699 .UNINDENT
16700 .SS Internal stuff page
16701 .sp
16702 Most entries shown on this page have rather vague meaning. Likely none of this
16703 is useful for you. Don\(aqt attempt to use it. Forget its existence.
16704 .sp
16705 Selecting this for the first time will start collecting some internal
16706 performance data. That means performance will be slightly lower than normal for
16707 the rest of the time the player is running (even if the stats page is closed).
16708 Note that the stats page itself uses a lot of CPU and even GPU resources, and
16709 may have a heavy impact on performance.
16710 .sp
16711 The displayed information is accumulated over the redraw delay (shown as
16712 \fBpoll\-time\fP field).
16713 .sp
16714 This adds entries for each Lua script. If there are too many scripts running,
16715 parts of the list will simply be out of the screen, but it can be scrolled.
16716 .sp
16717 If the underlying platform does not support pthread per thread times, the
16718 displayed times will be 0 or something random (I suspect that at time of this
16719 writing, only Linux provides the correct via pthread APIs for per thread times).
16720 .sp
16721 Most entries are added lazily and only during data collection, which is why
16722 entries may pop up randomly after some time. It\(aqs also why the memory usage
16723 entries for scripts that have been inactive since the start of data collection
16724 are missing.
16725 .sp
16726 Memory usage is approximate and does not reflect internal fragmentation.
16727 .sp
16728 JS scripts memory reporting is disabled by default because collecting the data
16729 at the JS side has an overhead. It can be enabled by exporting the env var
16730 \fBMPV_LEAK_REPORT=1\fP before starting mpv, and will increase JS memory usage.
16731 .sp
16732 If entries have \fB/time\fP and \fB/cpu\fP variants, the former gives the real time
16733 (monotonic clock), while the latter the thread CPU time (only if the
16734 corresponding pthread API works and is supported).
16735 .SH CONSOLE
16736 .sp
16737 The console is a REPL for mpv input commands. It is displayed on the video
16738 window. It also shows log messages. It can be disabled entirely using the
16739 \fB\-\-load\-osd\-console=no\fP option.
16740 .SS Keybindings
16741 .INDENT 0.0
16742 .TP
16743 .B \(ga
16744 Show the console.
16745 .TP
16746 .B ESC
16747 Hide the console.
16748 .TP
16749 .B ENTER
16750 Run the typed command.
16751 .TP
16752 .B Shift+ENTER
16753 Type a literal newline character.
16754 .TP
16755 .B Ctrl+LEFT and Ctrl+RIGHT
16756 Move cursor to previous/next word.
16757 .TP
16758 .B UP and DOWN
16759 Navigate command history.
16760 .TP
16761 .B PGUP
16762 Go to the first command in the history.
16763 .TP
16764 .B PGDN
16765 Stop navigating command history.
16766 .TP
16767 .B INSERT
16768 Toggle insert mode.
16769 .TP
16770 .B Shift+INSERT
16771 Paste text (uses the primary selection on X11).
16772 .TP
16773 .B TAB
16774 Complete the command or property name at the cursor.
16775 .TP
16776 .B Ctrl+C
16777 Clear current line.
16778 .TP
16779 .B Ctrl+K
16780 Delete text from the cursor to the end of the line.
16781 .TP
16782 .B Ctrl+L
16783 Clear all log messages from the console.
16784 .TP
16785 .B Ctrl+U
16786 Delete text from the cursor to the beginning of the line.
16787 .TP
16788 .B Ctrl+V
16789 Paste text (uses the clipboard on X11).
16790 .TP
16791 .B Ctrl+W
16792 Delete text from the cursor to the beginning of the current word.
16793 .UNINDENT
16794 .SS Commands
16795 .INDENT 0.0
16796 .TP
16797 .B \fBscript\-message\-to console type <text> [<cursor_pos>]\fP
16798 Show the console and pre\-fill it with the provided text, optionally
16799 specifying the initial cursor position as a positive integer starting from
16800 1.
16801 .INDENT 7.0
16802 .INDENT 3.5
16803 .IP "Example for input.conf"
16804 .sp
16805 \fB% script\-message\-to console type "seek absolute\-percent" 6\fP
16806 .UNINDENT
16807 .UNINDENT
16808 .UNINDENT
16809 .SS Known issues
16810 .INDENT 0.0
16811 .IP \(bu 2
16812 Pasting text is slow on Windows
16813 .IP \(bu 2
16814 Non\-ASCII keyboard input has restrictions
16815 .IP \(bu 2
16816 The cursor keys move between Unicode code\-points, not grapheme clusters
16817 .UNINDENT
16818 .SS Configuration
16819 .sp
16820 This script can be customized through a config file \fBscript\-opts/console.conf\fP
16821 placed in mpv\(aqs user directory and through the \fB\-\-script\-opts\fP command\-line
16822 option. The configuration syntax is described in \fI\%ON SCREEN CONTROLLER\fP\&.
16823 .sp
16824 Key bindings can be changed in a standard way, see for example stats.lua
16825 documentation.
16826 .SS Configurable Options
16827 .INDENT 0.0
16828 .TP
16829 .B \fBscale\fP
16830 Default: 1
16831 .sp
16832 All drawing is scaled by this value, including the text borders and the
16833 cursor.
16834 .sp
16835 If the VO backend in use has HiDPI scale reporting implemented, the option
16836 value is scaled with the reported HiDPI scale.
16837 .TP
16838 .B \fBfont\fP
16839 Default: unset (picks a hardcoded font depending on detected platform)
16840 .sp
16841 Set the font used for the REPL and the console. This probably doesn\(aqt
16842 have to be a monospaced font.
16843 .TP
16844 .B \fBfont_size\fP
16845 Default: 16
16846 .sp
16847 Set the font size used for the REPL and the console. This will be
16848 multiplied by "scale."
16849 .UNINDENT
16850 .SH LUA SCRIPTING
16851 .sp
16852 mpv can load Lua scripts. (See \fI\%Script location\fP\&.)
16853 .sp
16854 mpv provides the built\-in module \fBmp\fP, which contains functions to send
16855 commands to the mpv core and to retrieve information about playback state, user
16856 settings, file information, and so on.
16857 .sp
16858 These scripts can be used to control mpv in a similar way to slave mode.
16859 Technically, the Lua code uses the client API internally.
16860 .SS Example
16861 .sp
16862 A script which leaves fullscreen mode when the player is paused:
16863 .INDENT 0.0
16864 .INDENT 3.5
16865 .sp
16866 .nf
16867 .ft C
16868 function on_pause_change(name, value)
16869 if value == true then
16870 mp.set_property("fullscreen", "no")
16871 end
16872 end
16873 mp.observe_property("pause", "bool", on_pause_change)
16874 .ft P
16875 .fi
16876 .UNINDENT
16877 .UNINDENT
16878 .SS Script location
16879 .sp
16880 Scripts can be passed to the \fB\-\-script\fP option, and are automatically loaded
16881 from the \fBscripts\fP subdirectory of the mpv configuration directory (usually
16882 \fB~/.config/mpv/scripts/\fP).
16883 .sp
16884 A script can be a single file. The file extension is used to select the
16885 scripting backend to use for it. For Lua, it is \fB\&.lua\fP\&. If the extension is
16886 not recognized, an error is printed. (If an error happens, the extension is
16887 either mistyped, or the backend was not compiled into your mpv binary.)
16888 .sp
16889 Entries with \fB\&.disable\fP extension are always ignored.
16890 .sp
16891 If a script is a directory (either if a directory is passed to \fB\-\-script\fP,
16892 or any sub\-directories in the script directory, such as for example
16893 \fB~/.config/mpv/scripts/something/\fP), then the directory represents a single
16894 script. The player will try to load a file named \fBmain.x\fP, where \fBx\fP is
16895 replaced with the file extension. For example, if \fBmain.lua\fP exists, it is
16896 loaded with the Lua scripting backend.
16897 .sp
16898 You must not put any other files or directories that start with \fBmain.\fP into
16899 the script\(aqs top level directory. If the script directory contains for example
16900 both \fBmain.lua\fP and \fBmain.js\fP, only one of them will be loaded (and which
16901 one depends on mpv internals that may change any time). Likewise, if there is
16902 for example \fBmain.foo\fP, your script will break as soon as mpv adds a backend
16903 that uses the \fB\&.foo\fP file extension.
16904 .sp
16905 mpv also appends the top level directory of the script to the start of Lua\(aqs
16906 package path so you can import scripts from there too. Be aware that this will
16907 shadow Lua libraries that use the same package path. (Single file scripts do not
16908 include mpv specific directory the Lua package path. This was silently changed
16909 in mpv 0.32.0.)
16910 .sp
16911 Using a script directory is the recommended way to package a script that
16912 consists of multiple source files, or requires other files (you can use
16913 \fBmp.get_script_directory()\fP to get the location and e.g. load data files).
16914 .sp
16915 Making a script a git repository, basically a repository which contains a
16916 \fBmain.lua\(ga\fP file in the root directory, makes scripts easily updateable
16917 (without the dangers of auto\-updates). Another suggestion is to use git
16918 submodules to share common files or libraries.
16919 .SS Details on the script initialization and lifecycle
16920 .sp
16921 Your script will be loaded by the player at program start from the \fBscripts\fP
16922 configuration subdirectory, or from a path specified with the \fB\-\-script\fP
16923 option. Some scripts are loaded internally (like \fB\-\-osc\fP). Each script runs in
16924 its own thread. Your script is first run "as is", and once that is done, the event loop
16925 is entered. This event loop will dispatch events received by mpv and call your
16926 own event handlers which you have registered with \fBmp.register_event\fP, or
16927 timers added with \fBmp.add_timeout\fP or similar. Note that since the
16928 script starts execution concurrently with player initialization, some properties
16929 may not be populated with meaningful values until the relevant subsystems have
16930 initialized.
16931 .sp
16932 When the player quits, all scripts will be asked to terminate. This happens via
16933 a \fBshutdown\fP event, which by default will make the event loop return. If your
16934 script got into an endless loop, mpv will probably behave fine during playback,
16935 but it won\(aqt terminate when quitting, because it\(aqs waiting on your script.
16936 .sp
16937 Internally, the C code will call the Lua function \fBmp_event_loop\fP after
16938 loading a Lua script. This function is normally defined by the default prelude
16939 loaded before your script (see \fBplayer/lua/defaults.lua\fP in the mpv sources).
16940 The event loop will wait for events and dispatch events registered with
16941 \fBmp.register_event\fP\&. It will also handle timers added with \fBmp.add_timeout\fP
16942 and similar (by waiting with a timeout).
16943 .sp
16944 Since mpv 0.6.0, the player will wait until the script is fully loaded before
16945 continuing normal operation. The player considers a script as fully loaded as
16946 soon as it starts waiting for mpv events (or it exits). In practice this means
16947 the player will more or less hang until the script returns from the main chunk
16948 (and \fBmp_event_loop\fP is called), or the script calls \fBmp_event_loop\fP or
16949 \fBmp.dispatch_events\fP directly. This is done to make it possible for a script
16950 to fully setup event handlers etc. before playback actually starts. In older
16951 mpv versions, this happened asynchronously. With mpv 0.29.0, this changes
16952 slightly, and it merely waits for scripts to be loaded in this manner before
16953 starting playback as part of the player initialization phase. Scripts run though
16954 initialization in parallel. This might change again.
16955 .SS mp functions
16956 .sp
16957 The \fBmp\fP module is preloaded, although it can be loaded manually with
16958 \fBrequire \(aqmp\(aq\fP\&. It provides the core client API.
16959 .INDENT 0.0
16960 .TP
16961 .B \fBmp.command(string)\fP
16962 Run the given command. This is similar to the commands used in input.conf.
16963 See \fI\%List of Input Commands\fP\&.
16964 .sp
16965 By default, this will show something on the OSD (depending on the command),
16966 as if it was used in \fBinput.conf\fP\&. See \fI\%Input Command Prefixes\fP how
16967 to influence OSD usage per command.
16968 .sp
16969 Returns \fBtrue\fP on success, or \fBnil, error\fP on error.
16970 .TP
16971 .B \fBmp.commandv(arg1, arg2, ...)\fP
16972 Similar to \fBmp.command\fP, but pass each command argument as separate
16973 parameter. This has the advantage that you don\(aqt have to care about
16974 quoting and escaping in some cases.
16975 .sp
16976 Example:
16977 .INDENT 7.0
16978 .INDENT 3.5
16979 .sp
16980 .nf
16981 .ft C
16982 mp.command("loadfile " .. filename .. " append")
16983 mp.commandv("loadfile", filename, "append")
16984 .ft P
16985 .fi
16986 .UNINDENT
16987 .UNINDENT
16988 .sp
16989 These two commands are equivalent, except that the first version breaks
16990 if the filename contains spaces or certain special characters.
16991 .sp
16992 Note that properties are \fInot\fP expanded. You can use either \fBmp.command\fP,
16993 the \fBexpand\-properties\fP prefix, or the \fBmp.get_property\fP family of
16994 functions.
16995 .sp
16996 Unlike \fBmp.command\fP, this will not use OSD by default either (except
16997 for some OSD\-specific commands).
16998 .TP
16999 .B \fBmp.command_native(table [,def])\fP
17000 Similar to \fBmp.commandv\fP, but pass the argument list as table. This has
17001 the advantage that in at least some cases, arguments can be passed as
17002 native types. It also allows you to use named argument.
17003 .sp
17004 If the table is an array, each array item is like an argument in
17005 \fBmp.commandv()\fP (but can be a native type instead of a string).
17006 .sp
17007 If the table contains string keys, it\(aqs interpreted as command with named
17008 arguments. This requires at least an entry with the key \fBname\fP to be
17009 present, which must be a string, and contains the command name. The special
17010 entry \fB_flags\fP is optional, and if present, must be an array of
17011 \fI\%Input Command Prefixes\fP to apply. All other entries are interpreted as
17012 arguments.
17013 .sp
17014 Returns a result table on success (usually empty), or \fBdef, error\fP on
17015 error. \fBdef\fP is the second parameter provided to the function, and is
17016 nil if it\(aqs missing.
17017 .TP
17018 .B \fBmp.command_native_async(table [,fn])\fP
17019 Like \fBmp.command_native()\fP, but the command is ran asynchronously (as far
17020 as possible), and upon completion, fn is called. fn has three arguments:
17021 \fBfn(success, result, error)\fP:
17022 .INDENT 7.0
17023 .INDENT 3.5
17024 .INDENT 0.0
17025 .INDENT 3.5
17026 .INDENT 0.0
17027 .TP
17028 .B \fBsuccess\fP
17029 Always a Boolean and is true if the command was successful,
17030 otherwise false.
17031 .UNINDENT
17032 .UNINDENT
17033 .UNINDENT
17034 .INDENT 0.0
17035 .TP
17036 .B \fBresult\fP
17037 The result value (can be nil) in case of success, nil otherwise (as
17038 returned by \fBmp.command_native()\fP).
17039 .TP
17040 .B \fBerror\fP
17041 The error string in case of an error, nil otherwise.
17042 .UNINDENT
17043 .UNINDENT
17044 .UNINDENT
17045 .sp
17046 Returns a table with undefined contents, which can be used as argument for
17047 \fBmp.abort_async_command\fP\&.
17048 .sp
17049 If starting the command failed for some reason, \fBnil, error\fP is returned,
17050 and \fBfn\fP is called indicating failure, using the same error value.
17051 .TP
17052 .B \fBmp.abort_async_command(t)\fP
17053 Abort a \fBmp.command_native_async\fP call. The argument is the return value
17054 of that command (which starts asynchronous execution of the command).
17055 Whether this works and how long it takes depends on the command and the
17056 situation. The abort call itself is asynchronous. Does not return anything.
17057 .TP
17058 .B \fBmp.get_property(name [,def])\fP
17059 Return the value of the given property as string. These are the same
17060 properties as used in input.conf. See \fI\%Properties\fP for a list of
17061 properties. The returned string is formatted similar to \fB${=name}\fP
17062 (see \fI\%Property Expansion\fP).
17063 .sp
17064 Returns the string on success, or \fBdef, error\fP on error. \fBdef\fP is the
17065 second parameter provided to the function, and is nil if it\(aqs missing.
17066 .TP
17067 .B \fBmp.get_property_osd(name [,def])\fP
17068 Similar to \fBmp.get_property\fP, but return the property value formatted for
17069 OSD. This is the same string as printed with \fB${name}\fP when used in
17070 input.conf.
17071 .sp
17072 Returns the string on success, or \fBdef, error\fP on error. \fBdef\fP is the
17073 second parameter provided to the function, and is an empty string if it\(aqs
17074 missing. Unlike \fBget_property()\fP, assigning the return value to a variable
17075 will always result in a string.
17076 .TP
17077 .B \fBmp.get_property_bool(name [,def])\fP
17078 Similar to \fBmp.get_property\fP, but return the property value as Boolean.
17079 .sp
17080 Returns a Boolean on success, or \fBdef, error\fP on error.
17081 .TP
17082 .B \fBmp.get_property_number(name [,def])\fP
17083 Similar to \fBmp.get_property\fP, but return the property value as number.
17084 .sp
17085 Note that while Lua does not distinguish between integers and floats,
17086 mpv internals do. This function simply request a double float from mpv,
17087 and mpv will usually convert integer property values to float.
17088 .sp
17089 Returns a number on success, or \fBdef, error\fP on error.
17090 .TP
17091 .B \fBmp.get_property_native(name [,def])\fP
17092 Similar to \fBmp.get_property\fP, but return the property value using the best
17093 Lua type for the property. Most time, this will return a string, Boolean,
17094 or number. Some properties (for example \fBchapter\-list\fP) are returned as
17095 tables.
17096 .sp
17097 Returns a value on success, or \fBdef, error\fP on error. Note that \fBnil\fP
17098 might be a possible, valid value too in some corner cases.
17099 .TP
17100 .B \fBmp.set_property(name, value)\fP
17101 Set the given property to the given string value. See \fBmp.get_property\fP
17102 and \fI\%Properties\fP for more information about properties.
17103 .sp
17104 Returns true on success, or \fBnil, error\fP on error.
17105 .TP
17106 .B \fBmp.set_property_bool(name, value)\fP
17107 Similar to \fBmp.set_property\fP, but set the given property to the given
17108 Boolean value.
17109 .TP
17110 .B \fBmp.set_property_number(name, value)\fP
17111 Similar to \fBmp.set_property\fP, but set the given property to the given
17112 numeric value.
17113 .sp
17114 Note that while Lua does not distinguish between integers and floats,
17115 mpv internals do. This function will test whether the number can be
17116 represented as integer, and if so, it will pass an integer value to mpv,
17117 otherwise a double float.
17118 .TP
17119 .B \fBmp.set_property_native(name, value)\fP
17120 Similar to \fBmp.set_property\fP, but set the given property using its native
17121 type.
17122 .sp
17123 Since there are several data types which cannot represented natively in
17124 Lua, this might not always work as expected. For example, while the Lua
17125 wrapper can do some guesswork to decide whether a Lua table is an array
17126 or a map, this would fail with empty tables. Also, there are not many
17127 properties for which it makes sense to use this, instead of
17128 \fBset_property\fP, \fBset_property_bool\fP, \fBset_property_number\fP\&.
17129 For these reasons, this function should probably be avoided for now, except
17130 for properties that use tables natively.
17131 .TP
17132 .B \fBmp.get_time()\fP
17133 Return the current mpv internal time in seconds as a number. This is
17134 basically the system time, with an arbitrary offset.
17135 .TP
17136 .B \fBmp.add_key_binding(key, name|fn [,fn [,flags]])\fP
17137 Register callback to be run on a key binding. The binding will be mapped to
17138 the given \fBkey\fP, which is a string describing the physical key. This uses
17139 the same key names as in input.conf, and also allows combinations
17140 (e.g. \fBctrl+a\fP). If the key is empty or \fBnil\fP, no physical key is
17141 registered, but the user still can create own bindings (see below).
17142 .sp
17143 After calling this function, key presses will cause the function \fBfn\fP to
17144 be called (unless the user remapped the key with another binding).
17145 .sp
17146 The \fBname\fP argument should be a short symbolic string. It allows the user
17147 to remap the key binding via input.conf using the \fBscript\-message\fP
17148 command, and the name of the key binding (see below for
17149 an example). The name should be unique across other bindings in the same
17150 script \- if not, the previous binding with the same name will be
17151 overwritten. You can omit the name, in which case a random name is generated
17152 internally. (Omitting works as follows: either pass \fBnil\fP for \fBname\fP,
17153 or pass the \fBfn\fP argument in place of the name. The latter is not
17154 recommended and is handled for compatibility only.)
17155 .sp
17156 The last argument is used for optional flags. This is a table, which can
17157 have the following entries:
17158 .INDENT 7.0
17159 .INDENT 3.5
17160 .INDENT 0.0
17161 .TP
17162 .B \fBrepeatable\fP
17163 If set to \fBtrue\fP, enables key repeat for this specific binding.
17164 .TP
17165 .B \fBcomplex\fP
17166 If set to \fBtrue\fP, then \fBfn\fP is called on both key up and down
17167 events (as well as key repeat, if enabled), with the first
17168 argument being a table. This table has the following entries (and
17169 may contain undocumented ones):
17170 .INDENT 7.0
17171 .INDENT 3.5
17172 .INDENT 0.0
17173 .TP
17174 .B \fBevent\fP
17175 Set to one of the strings \fBdown\fP, \fBrepeat\fP, \fBup\fP or
17176 \fBpress\fP (the latter if key up/down can\(aqt be tracked).
17177 .TP
17178 .B \fBis_mouse\fP
17179 Boolean Whether the event was caused by a mouse button.
17180 .TP
17181 .B \fBkey_name\fP
17182 The name of they key that triggered this, or \fBnil\fP if
17183 invoked artificially. If the key name is unknown, it\(aqs an
17184 empty string.
17185 .TP
17186 .B \fBkey_text\fP
17187 Text if triggered by a text key, otherwise \fBnil\fP\&. See
17188 description of \fBscript\-binding\fP command for details (this
17189 field is equivalent to the 5th argument).
17190 .UNINDENT
17191 .UNINDENT
17192 .UNINDENT
17193 .UNINDENT
17194 .UNINDENT
17195 .UNINDENT
17196 .sp
17197 Internally, key bindings are dispatched via the \fBscript\-message\-to\fP or
17198 \fBscript\-binding\fP input commands and \fBmp.register_script_message\fP\&.
17199 .sp
17200 Trying to map multiple commands to a key will essentially prefer a random
17201 binding, while the other bindings are not called. It is guaranteed that
17202 user defined bindings in the central input.conf are preferred over bindings
17203 added with this function (but see \fBmp.add_forced_key_binding\fP).
17204 .sp
17205 Example:
17206 .INDENT 7.0
17207 .INDENT 3.5
17208 .sp
17209 .nf
17210 .ft C
17211 function something_handler()
17212 print("the key was pressed")
17213 end
17214 mp.add_key_binding("x", "something", something_handler)
17215 .ft P
17216 .fi
17217 .UNINDENT
17218 .UNINDENT
17219 .sp
17220 This will print the message \fBthe key was pressed\fP when \fBx\fP was pressed.
17221 .sp
17222 The user can remap these key bindings. Then the user has to put the
17223 following into their input.conf to remap the command to the \fBy\fP key:
17224 .INDENT 7.0
17225 .INDENT 3.5
17226 .sp
17227 .nf
17228 .ft C
17229 y script\-binding something
17230 .ft P
17231 .fi
17232 .UNINDENT
17233 .UNINDENT
17234 .sp
17235 This will print the message when the key \fBy\fP is pressed. (\fBx\fP will
17236 still work, unless the user remaps it.)
17237 .sp
17238 You can also explicitly send a message to a named script only. Assume the
17239 above script was using the filename \fBfooscript.lua\fP:
17240 .INDENT 7.0
17241 .INDENT 3.5
17242 .sp
17243 .nf
17244 .ft C
17245 y script\-binding fooscript/something
17246 .ft P
17247 .fi
17248 .UNINDENT
17249 .UNINDENT
17250 .TP
17251 .B \fBmp.add_forced_key_binding(...)\fP
17252 This works almost the same as \fBmp.add_key_binding\fP, but registers the
17253 key binding in a way that will overwrite the user\(aqs custom bindings in their
17254 input.conf. (\fBmp.add_key_binding\fP overwrites default key bindings only,
17255 but not those by the user\(aqs input.conf.)
17256 .TP
17257 .B \fBmp.remove_key_binding(name)\fP
17258 Remove a key binding added with \fBmp.add_key_binding\fP or
17259 \fBmp.add_forced_key_binding\fP\&. Use the same name as you used when adding
17260 the bindings. It\(aqs not possible to remove bindings for which you omitted
17261 the name.
17262 .TP
17263 .B \fBmp.register_event(name, fn)\fP
17264 Call a specific function when an event happens. The event name is a string,
17265 and the function fn is a Lua function value.
17266 .sp
17267 Some events have associated data. This is put into a Lua table and passed
17268 as argument to fn. The Lua table by default contains a \fBname\fP field,
17269 which is a string containing the event name. If the event has an error
17270 associated, the \fBerror\fP field is set to a string describing the error,
17271 on success it\(aqs not set.
17272 .sp
17273 If multiple functions are registered for the same event, they are run in
17274 registration order, which the first registered function running before all
17275 the other ones.
17276 .sp
17277 Returns true if such an event exists, false otherwise.
17278 .sp
17279 See \fI\%Events\fP and \fI\%List of events\fP for details.
17280 .TP
17281 .B \fBmp.unregister_event(fn)\fP
17282 Undo \fBmp.register_event(..., fn)\fP\&. This removes all event handlers that
17283 are equal to the \fBfn\fP parameter. This uses normal Lua \fB==\fP comparison,
17284 so be careful when dealing with closures.
17285 .TP
17286 .B \fBmp.observe_property(name, type, fn)\fP
17287 Watch a property for changes. If the property \fBname\fP is changed, then
17288 the function \fBfn(name)\fP will be called. \fBtype\fP can be \fBnil\fP, or be
17289 set to one of \fBnone\fP, \fBnative\fP, \fBbool\fP, \fBstring\fP, or \fBnumber\fP\&.
17290 \fBnone\fP is the same as \fBnil\fP\&. For all other values, the new value of
17291 the property will be passed as second argument to \fBfn\fP, using
17292 \fBmp.get_property_<type>\fP to retrieve it. This means if \fBtype\fP is for
17293 example \fBstring\fP, \fBfn\fP is roughly called as in
17294 \fBfn(name, mp.get_property_string(name))\fP\&.
17295 .sp
17296 If possible, change events are coalesced. If a property is changed a bunch
17297 of times in a row, only the last change triggers the change function. (The
17298 exact behavior depends on timing and other things.)
17299 .sp
17300 If a property is unavailable, or on error, the value argument to \fBfn\fP is
17301 \fBnil\fP\&. (The \fBobserve_property()\fP call always succeeds, even if a
17302 property does not exist.)
17303 .sp
17304 In some cases the function is not called even if the property changes.
17305 This depends on the property, and it\(aqs a valid feature request to ask for
17306 better update handling of a specific property.
17307 .sp
17308 If the \fBtype\fP is \fBnone\fP or \fBnil\fP, sporadic property change events are
17309 possible. This means the change function \fBfn\fP can be called even if the
17310 property doesn\(aqt actually change.
17311 .sp
17312 You always get an initial change notification. This is meant to initialize
17313 the user\(aqs state to the current value of the property.
17314 .TP
17315 .B \fBmp.unobserve_property(fn)\fP
17316 Undo \fBmp.observe_property(..., fn)\fP\&. This removes all property handlers
17317 that are equal to the \fBfn\fP parameter. This uses normal Lua \fB==\fP
17318 comparison, so be careful when dealing with closures.
17319 .TP
17320 .B \fBmp.add_timeout(seconds, fn)\fP
17321 Call the given function fn when the given number of seconds has elapsed.
17322 Note that the number of seconds can be fractional. For now, the timer\(aqs
17323 resolution may be as low as 50 ms, although this will be improved in the
17324 future.
17325 .sp
17326 This is a one\-shot timer: it will be removed when it\(aqs fired.
17327 .sp
17328 Returns a timer object. See \fBmp.add_periodic_timer\fP for details.
17329 .TP
17330 .B \fBmp.add_periodic_timer(seconds, fn)\fP
17331 Call the given function periodically. This is like \fBmp.add_timeout\fP, but
17332 the timer is re\-added after the function fn is run.
17333 .INDENT 7.0
17334 .TP
17335 .B Returns a timer object. The timer object provides the following methods:
17336 .INDENT 7.0
17337 .TP
17338 .B \fBstop()\fP
17339 Disable the timer. Does nothing if the timer is already disabled.
17340 This will remember the current elapsed time when stopping, so that
17341 \fBresume()\fP essentially unpauses the timer.
17342 .TP
17343 .B \fBkill()\fP
17344 Disable the timer. Resets the elapsed time. \fBresume()\fP will
17345 restart the timer.
17346 .TP
17347 .B \fBresume()\fP
17348 Restart the timer. If the timer was disabled with \fBstop()\fP, this
17349 will resume at the time it was stopped. If the timer was disabled
17350 with \fBkill()\fP, or if it\(aqs a previously fired one\-shot timer (added
17351 with \fBadd_timeout()\fP), this starts the timer from the beginning,
17352 using the initially configured timeout.
17353 .TP
17354 .B \fBis_enabled()\fP
17355 Whether the timer is currently enabled or was previously disabled
17356 (e.g. by \fBstop()\fP or \fBkill()\fP).
17357 .TP
17358 .B \fBtimeout\fP (RW)
17359 This field contains the current timeout period. This value is not
17360 updated as time progresses. It\(aqs only used to calculate when the
17361 timer should fire next when the timer expires.
17362 .sp
17363 If you write this, you can call \fBt:kill() ; t:resume()\fP to reset
17364 the current timeout to the new one. (\fBt:stop()\fP won\(aqt use the
17365 new timeout.)
17366 .TP
17367 .B \fBoneshot\fP (RW)
17368 Whether the timer is periodic (\fBfalse\fP) or fires just once
17369 (\fBtrue\fP). This value is used when the timer expires (but before
17370 the timer callback function fn is run).
17371 .UNINDENT
17372 .UNINDENT
17373 .sp
17374 Note that these are methods, and you have to call them using \fB:\fP instead
17375 of \fB\&.\fP (Refer to \fI\%http://www.lua.org/manual/5.2/manual.html#3.4.9\fP .)
17376 .sp
17377 Example:
17378 .INDENT 7.0
17379 .INDENT 3.5
17380 .sp
17381 .nf
17382 .ft C
17383 seconds = 0
17384 timer = mp.add_periodic_timer(1, function()
17385 print("called every second")
17386 # stop it after 10 seconds
17387 seconds = seconds + 1
17388 if seconds >= 10 then
17389 timer:kill()
17390 end
17391 end)
17392 .ft P
17393 .fi
17394 .UNINDENT
17395 .UNINDENT
17396 .TP
17397 .B \fBmp.get_opt(key)\fP
17398 Return a setting from the \fB\-\-script\-opts\fP option. It\(aqs up to the user and
17399 the script how this mechanism is used. Currently, all scripts can access
17400 this equally, so you should be careful about collisions.
17401 .TP
17402 .B \fBmp.get_script_name()\fP
17403 Return the name of the current script. The name is usually made of the
17404 filename of the script, with directory and file extension removed. If
17405 there are several scripts which would have the same name, it\(aqs made unique
17406 by appending a number.
17407 .INDENT 7.0
17408 .INDENT 3.5
17409 .IP "Example"
17410 .sp
17411 The script \fB/path/to/fooscript.lua\fP becomes \fBfooscript\fP\&.
17412 .UNINDENT
17413 .UNINDENT
17414 .TP
17415 .B \fBmp.get_script_directory()\fP
17416 Return the directory if this is a script packaged as directory (see
17417 \fI\%Script location\fP for a description). Return nothing if this is a single
17418 file script.
17419 .TP
17420 .B \fBmp.osd_message(text [,duration])\fP
17421 Show an OSD message on the screen. \fBduration\fP is in seconds, and is
17422 optional (uses \fB\-\-osd\-duration\fP by default).
17423 .UNINDENT
17424 .SS Advanced mp functions
17425 .sp
17426 These also live in the \fBmp\fP module, but are documented separately as they
17427 are useful only in special situations.
17428 .INDENT 0.0
17429 .TP
17430 .B \fBmp.suspend()\fP
17431 This function has been deprecated in mpv 0.21.0 and does nothing starting
17432 with mpv 0.23.0 (no replacement).
17433 .TP
17434 .B \fBmp.resume()\fP
17435 This function has been deprecated in mpv 0.21.0 and does nothing starting
17436 with mpv 0.23.0 (no replacement).
17437 .TP
17438 .B \fBmp.resume_all()\fP
17439 This function has been deprecated in mpv 0.21.0 and does nothing starting
17440 with mpv 0.23.0 (no replacement).
17441 .TP
17442 .B \fBmp.get_wakeup_pipe()\fP
17443 Calls \fBmpv_get_wakeup_pipe()\fP and returns the read end of the wakeup
17444 pipe. This is deprecated, but still works. (See \fBclient.h\fP for details.)
17445 .TP
17446 .B \fBmp.get_next_timeout()\fP
17447 Return the relative time in seconds when the next timer (\fBmp.add_timeout\fP
17448 and similar) expires. If there is no timer, return \fBnil\fP\&.
17449 .TP
17450 .B \fBmp.dispatch_events([allow_wait])\fP
17451 This can be used to run custom event loops. If you want to have direct
17452 control what the Lua script does (instead of being called by the default
17453 event loop), you can set the global variable \fBmp_event_loop\fP to your
17454 own function running the event loop. From your event loop, you should call
17455 \fBmp.dispatch_events()\fP to dequeue and dispatch mpv events.
17456 .sp
17457 If the \fBallow_wait\fP parameter is set to \fBtrue\fP, the function will block
17458 until the next event is received or the next timer expires. Otherwise (and
17459 this is the default behavior), it returns as soon as the event loop is
17460 emptied. It\(aqs strongly recommended to use \fBmp.get_next_timeout()\fP and
17461 \fBmp.get_wakeup_pipe()\fP if you\(aqre interested in properly working
17462 notification of new events and working timers.
17463 .TP
17464 .B \fBmp.register_idle(fn)\fP
17465 Register an event loop idle handler. Idle handlers are called before the
17466 script goes to sleep after handling all new events. This can be used for
17467 example to delay processing of property change events: if you\(aqre observing
17468 multiple properties at once, you might not want to act on each property
17469 change, but only when all change notifications have been received.
17470 .TP
17471 .B \fBmp.unregister_idle(fn)\fP
17472 Undo \fBmp.register_idle(fn)\fP\&. This removes all idle handlers that
17473 are equal to the \fBfn\fP parameter. This uses normal Lua \fB==\fP comparison,
17474 so be careful when dealing with closures.
17475 .TP
17476 .B \fBmp.enable_messages(level)\fP
17477 Set the minimum log level of which mpv message output to receive. These
17478 messages are normally printed to the terminal. By calling this function,
17479 you can set the minimum log level of messages which should be received with
17480 the \fBlog\-message\fP event. See the description of this event for details.
17481 The level is a string, see \fBmsg.log\fP for allowed log levels.
17482 .TP
17483 .B \fBmp.register_script_message(name, fn)\fP
17484 This is a helper to dispatch \fBscript\-message\fP or \fBscript\-message\-to\fP
17485 invocations to Lua functions. \fBfn\fP is called if \fBscript\-message\fP or
17486 \fBscript\-message\-to\fP (with this script as destination) is run
17487 with \fBname\fP as first parameter. The other parameters are passed to \fBfn\fP\&.
17488 If a message with the given name is already registered, it\(aqs overwritten.
17489 .sp
17490 Used by \fBmp.add_key_binding\fP, so be careful about name collisions.
17491 .TP
17492 .B \fBmp.unregister_script_message(name)\fP
17493 Undo a previous registration with \fBmp.register_script_message\fP\&. Does
17494 nothing if the \fBname\fP wasn\(aqt registered.
17495 .TP
17496 .B \fBmp.create_osd_overlay(format)\fP
17497 Create an OSD overlay. This is a very thin wrapper around the \fBosd\-overlay\fP
17498 command. The function returns a table, which mostly contains fields that
17499 will be passed to \fBosd\-overlay\fP\&. The \fBformat\fP parameter is used to
17500 initialize the \fBformat\fP field. The \fBdata\fP field contains the text to
17501 be used as overlay. For details, see the \fBosd\-overlay\fP command.
17502 .sp
17503 In addition, it provides the following methods:
17504 .INDENT 7.0
17505 .TP
17506 .B \fBupdate()\fP
17507 Commit the OSD overlay to the screen, or in other words, run the
17508 \fBosd\-overlay\fP command with the current fields of the overlay table.
17509 Returns the result of the \fBosd\-overlay\fP command itself.
17510 .TP
17511 .B \fBremove()\fP
17512 Remove the overlay from the screen. A \fBupdate()\fP call will add it
17513 again.
17514 .UNINDENT
17515 .sp
17516 Example:
17517 .INDENT 7.0
17518 .INDENT 3.5
17519 .sp
17520 .nf
17521 .ft C
17522 ov = mp.create_osd_overlay("ass\-events")
17523 ov.data = "{\e\ean5}{\e\eb1}hello world!"
17524 ov:update()
17525 .ft P
17526 .fi
17527 .UNINDENT
17528 .UNINDENT
17529 .sp
17530 The advantage of using this wrapper (as opposed to running \fBosd\-overlay\fP
17531 directly) is that the \fBid\fP field is allocated automatically.
17532 .TP
17533 .B \fBmp.get_osd_size()\fP
17534 Returns a tuple of \fBosd_width, osd_height, osd_par\fP\&. The first two give
17535 the size of the OSD in pixels (for video ouputs like \fB\-\-vo=xv\fP, this may
17536 be "scaled" pixels). The third is the display pixel aspect ratio.
17537 .sp
17538 May return invalid/nonsense values if OSD is not initialized yet.
17539 .UNINDENT
17540 .SS mp.msg functions
17541 .sp
17542 This module allows outputting messages to the terminal, and can be loaded
17543 with \fBrequire \(aqmp.msg\(aq\fP\&.
17544 .INDENT 0.0
17545 .TP
17546 .B \fBmsg.log(level, ...)\fP
17547 The level parameter is the message priority. It\(aqs a string and one of
17548 \fBfatal\fP, \fBerror\fP, \fBwarn\fP, \fBinfo\fP, \fBv\fP, \fBdebug\fP, \fBtrace\fP\&. The
17549 user\(aqs settings will determine which of these messages will be
17550 visible. Normally, all messages are visible, except \fBv\fP, \fBdebug\fP and
17551 \fBtrace\fP\&.
17552 .sp
17553 The parameters after that are all converted to strings. Spaces are inserted
17554 to separate multiple parameters.
17555 .sp
17556 You don\(aqt need to add newlines.
17557 .TP
17558 .B \fBmsg.fatal(...)\fP, \fBmsg.error(...)\fP, \fBmsg.warn(...)\fP, \fBmsg.info(...)\fP, \fBmsg.verbose(...)\fP, \fBmsg.debug(...)\fP, \fBmsg.trace(...)\fP
17559 All of these are shortcuts and equivalent to the corresponding
17560 \fBmsg.log(level, ...)\fP call.
17561 .UNINDENT
17562 .SS mp.options functions
17563 .sp
17564 mpv comes with a built\-in module to manage options from config\-files and the
17565 command\-line. All you have to do is to supply a table with default options to
17566 the read_options function. The function will overwrite the default values
17567 with values found in the config\-file and the command\-line (in that order).
17568 .INDENT 0.0
17569 .TP
17570 .B \fBoptions.read_options(table [, identifier [, on_update]])\fP
17571 A \fBtable\fP with key\-value pairs. The type of the default values is
17572 important for converting the values read from the config file or
17573 command\-line back. Do not use \fBnil\fP as a default value!
17574 .sp
17575 The \fBidentifier\fP is used to identify the config\-file and the command\-line
17576 options. These needs to unique to avoid collisions with other scripts.
17577 Defaults to \fBmp.get_script_name()\fP if the parameter is \fBnil\fP or missing.
17578 .sp
17579 The \fBon_update\fP parameter enables run\-time updates of all matching option
17580 values via the \fBscript\-opts\fP option/property. If any of the matching
17581 options changes, the values in the \fBtable\fP (which was originally passed to
17582 the function) are changed, and \fBon_update(list)\fP is called. \fBlist\fP is
17583 a table where each updated option has a \fBlist[option_name] = true\fP entry.
17584 There is no initial \fBon_update()\fP call. This never re\-reads the config file.
17585 \fBscript\-opts\fP is always applied on the original config file, ignoring
17586 previous \fBscript\-opts\fP values (for example, if an option is removed from
17587 \fBscript\-opts\fP at runtime, the option will have the value in the config
17588 file). \fBtable\fP entries are only written for option values whose values
17589 effectively change (this is important if the script changes \fBtable\fP
17590 entries independently).
17591 .UNINDENT
17592 .sp
17593 Example implementation:
17594 .INDENT 0.0
17595 .INDENT 3.5
17596 .sp
17597 .nf
17598 .ft C
17599 require \(aqmp.options\(aq
17600 local options = {
17601 optionA = "defaultvalueA",
17602 optionB = \-0.5,
17603 optionC = true,
17604 }
17605 read_options(options, "myscript")
17606 print(options.optionA)
17607 .ft P
17608 .fi
17609 .UNINDENT
17610 .UNINDENT
17611 .sp
17612 The config file will be stored in \fBscript\-opts/identifier.conf\fP in mpv\(aqs user
17613 folder. Comment lines can be started with # and stray spaces are not removed.
17614 Boolean values will be represented with yes/no.
17615 .sp
17616 Example config:
17617 .INDENT 0.0
17618 .INDENT 3.5
17619 .sp
17620 .nf
17621 .ft C
17622 # comment
17623 optionA=Hello World
17624 optionB=9999
17625 optionC=no
17626 .ft P
17627 .fi
17628 .UNINDENT
17629 .UNINDENT
17630 .sp
17631 Command\-line options are read from the \fB\-\-script\-opts\fP parameter. To avoid
17632 collisions, all keys have to be prefixed with \fBidentifier\-\fP\&.
17633 .sp
17634 Example command\-line:
17635 .INDENT 0.0
17636 .INDENT 3.5
17637 .sp
17638 .nf
17639 .ft C
17640 \-\-script\-opts=myscript\-optionA=TEST,myscript\-optionB=0,myscript\-optionC=yes
17641 .ft P
17642 .fi
17643 .UNINDENT
17644 .UNINDENT
17645 .SS mp.utils functions
17646 .sp
17647 This built\-in module provides generic helper functions for Lua, and have
17648 strictly speaking nothing to do with mpv or video/audio playback. They are
17649 provided for convenience. Most compensate for Lua\(aqs scarce standard library.
17650 .sp
17651 Be warned that any of these functions might disappear any time. They are not
17652 strictly part of the guaranteed API.
17653 .INDENT 0.0
17654 .TP
17655 .B \fButils.getcwd()\fP
17656 Returns the directory that mpv was launched from. On error, \fBnil, error\fP
17657 is returned.
17658 .TP
17659 .B \fButils.readdir(path [, filter])\fP
17660 Enumerate all entries at the given path on the filesystem, and return them
17661 as array. Each entry is a directory entry (without the path).
17662 The list is unsorted (in whatever order the operating system returns it).
17663 .sp
17664 If the \fBfilter\fP argument is given, it must be one of the following
17665 strings:
17666 .INDENT 7.0
17667 .INDENT 3.5
17668 .INDENT 0.0
17669 .TP
17670 .B \fBfiles\fP
17671 List regular files only. This excludes directories, special files
17672 (like UNIX device files or FIFOs), and dead symlinks. It includes
17673 UNIX symlinks to regular files.
17674 .TP
17675 .B \fBdirs\fP
17676 List directories only, or symlinks to directories. \fB\&.\fP and \fB\&..\fP
17677 are not included.
17678 .TP
17679 .B \fBnormal\fP
17680 Include the results of both \fBfiles\fP and \fBdirs\fP\&. (This is the
17681 default.)
17682 .TP
17683 .B \fBall\fP
17684 List all entries, even device files, dead symlinks, FIFOs, and the
17685 \fB\&.\fP and \fB\&..\fP entries.
17686 .UNINDENT
17687 .UNINDENT
17688 .UNINDENT
17689 .sp
17690 On error, \fBnil, error\fP is returned.
17691 .TP
17692 .B \fButils.file_info(path)\fP
17693 Stats the given path for information and returns a table with the
17694 following entries:
17695 .INDENT 7.0
17696 .INDENT 3.5
17697 .INDENT 0.0
17698 .TP
17699 .B \fBmode\fP
17700 protection bits (on Windows, always 755 (octal) for directories
17701 and 644 (octal) for files)
17702 .TP
17703 .B \fBsize\fP
17704 size in bytes
17705 .TP
17706 .B \fBatime\fP
17707 time of last access
17708 .TP
17709 .B \fBmtime\fP
17710 time of last modification
17711 .TP
17712 .B \fBctime\fP
17713 time of last metadata change (Linux) / time of creation (Windows)
17714 .TP
17715 .B \fBis_file\fP
17716 Whether \fBpath\fP is a regular file (boolean)
17717 .TP
17718 .B \fBis_dir\fP
17719 Whether \fBpath\fP is a directory (boolean)
17720 .UNINDENT
17721 .UNINDENT
17722 .UNINDENT
17723 .sp
17724 \fBmode\fP and \fBsize\fP are integers.
17725 Timestamps (\fBatime\fP, \fBmtime\fP and \fBctime\fP) are integer seconds since
17726 the Unix epoch (Unix time).
17727 The booleans \fBis_file\fP and \fBis_dir\fP are provided as a convenience;
17728 they can be and are derived from \fBmode\fP\&.
17729 .sp
17730 On error (eg. path does not exist), \fBnil, error\fP is returned.
17731 .TP
17732 .B \fButils.split_path(path)\fP
17733 Split a path into directory component and filename component, and return
17734 them. The first return value is always the directory. The second return
17735 value is the trailing part of the path, the directory entry.
17736 .TP
17737 .B \fButils.join_path(p1, p2)\fP
17738 Return the concatenation of the 2 paths. Tries to be clever. For example,
17739 if \fBp2\fP is an absolute path, \fBp2\fP is returned without change.
17740 .TP
17741 .B \fButils.subprocess(t)\fP
17742 Runs an external process and waits until it exits. Returns process status
17743 and the captured output. This is a legacy wrapper around calling the
17744 \fBsubprocess\fP command with \fBmp.command_native\fP\&. It does the following
17745 things:
17746 .INDENT 7.0
17747 .IP \(bu 2
17748 copy the table \fBt\fP
17749 .IP \(bu 2
17750 rename \fBcancellable\fP field to \fBplayback_only\fP
17751 .IP \(bu 2
17752 rename \fBmax_size\fP to \fBcapture_size\fP
17753 .IP \(bu 2
17754 set \fBcapture_stdout\fP field to \fBtrue\fP if unset
17755 .IP \(bu 2
17756 set \fBname\fP field to \fBsubprocess\fP
17757 .IP \(bu 2
17758 call \fBmp.command_native(copied_t)\fP
17759 .IP \(bu 2
17760 if the command failed, create a dummy result table
17761 .IP \(bu 2
17762 copy \fBerror_string\fP to \fBerror\fP field if the string is non\-empty
17763 .IP \(bu 2
17764 return the result table
17765 .UNINDENT
17766 .sp
17767 It is recommended to use \fBmp.command_native\fP or \fBmp.command_native_async\fP
17768 directly, instead of calling this legacy wrapper. It is for compatibility
17769 only.
17770 .sp
17771 See the \fBsubprocess\fP documentation for semantics and further parameters.
17772 .TP
17773 .B \fButils.subprocess_detached(t)\fP
17774 Runs an external process and detaches it from mpv\(aqs control.
17775 .sp
17776 The parameter \fBt\fP is a table. The function reads the following entries:
17777 .INDENT 7.0
17778 .INDENT 3.5
17779 .INDENT 0.0
17780 .TP
17781 .B \fBargs\fP
17782 Array of strings of the same semantics as the \fBargs\fP used in the
17783 \fBsubprocess\fP function.
17784 .UNINDENT
17785 .UNINDENT
17786 .UNINDENT
17787 .sp
17788 The function returns \fBnil\fP\&.
17789 .sp
17790 This is a legacy wrapper around calling the \fBrun\fP command with
17791 \fBmp.commandv\fP and other functions.
17792 .TP
17793 .B \fButils.getpid()\fP
17794 Returns the process ID of the running mpv process. This can be used to identify
17795 the calling mpv when launching (detached) subprocesses.
17796 .TP
17797 .B \fButils.get_env_list()\fP
17798 Returns the C environment as a list of strings. (Do not confuse this with
17799 the Lua "environment", which is an unrelated concept.)
17800 .TP
17801 .B \fButils.parse_json(str [, trail])\fP
17802 Parses the given string argument as JSON, and returns it as a Lua table. On
17803 error, returns \fBnil, error\fP\&. (Currently, \fBerror\fP is just a string
17804 reading \fBerror\fP, because there is no fine\-grained error reporting of any
17805 kind.)
17806 .sp
17807 The returned value uses similar conventions as \fBmp.get_property_native()\fP
17808 to distinguish empty objects and arrays.
17809 .sp
17810 If the \fBtrail\fP parameter is \fBtrue\fP (or any value equal to \fBtrue\fP),
17811 then trailing non\-whitespace text is tolerated by the function, and the
17812 trailing text is returned as 3rd return value. (The 3rd return value is
17813 always there, but with \fBtrail\fP set, no error is raised.)
17814 .TP
17815 .B \fButils.format_json(v)\fP
17816 Format the given Lua table (or value) as a JSON string and return it. On
17817 error, returns \fBnil, error\fP\&. (Errors usually only happen on value types
17818 incompatible with JSON.)
17819 .sp
17820 The argument value uses similar conventions as \fBmp.set_property_native()\fP
17821 to distinguish empty objects and arrays.
17822 .TP
17823 .B \fButils.to_string(v)\fP
17824 Turn the given value into a string. Formats tables and their contents. This
17825 doesn\(aqt do anything special; it is only needed because Lua is terrible.
17826 .UNINDENT
17827 .SS Events
17828 .sp
17829 Events are notifications from player core to scripts. You can register an
17830 event handler with \fBmp.register_event\fP\&.
17831 .sp
17832 Note that all scripts (and other parts of the player) receive events equally,
17833 and there\(aqs no such thing as blocking other scripts from receiving events.
17834 .sp
17835 Example:
17836 .INDENT 0.0
17837 .INDENT 3.5
17838 .sp
17839 .nf
17840 .ft C
17841 function my_fn(event)
17842 print("start of playback!")
17843 end
17844
17845 mp.register_event("file\-loaded", my_fn)
17846 .ft P
17847 .fi
17848 .UNINDENT
17849 .UNINDENT
17850 .sp
17851 For the existing event types, see \fI\%List of events\fP\&.
17852 .SS Extras
17853 .sp
17854 This documents experimental features, or features that are "too special" to
17855 guarantee a stable interface.
17856 .INDENT 0.0
17857 .TP
17858 .B \fBmp.add_hook(type, priority, fn)\fP
17859 Add a hook callback for \fBtype\fP (a string identifying a certain kind of
17860 hook). These hooks allow the player to call script functions and wait for
17861 their result (normally, the Lua scripting interface is asynchronous from
17862 the point of view of the player core). \fBpriority\fP is an arbitrary integer
17863 that allows ordering among hooks of the same kind. Using the value 50 is
17864 recommended as neutral default value.
17865 .sp
17866 \fBfn(hook)\fP is the function that will be called during execution of the
17867 hook. The parameter passed to it (\fBhook\fP) is a Lua object that can control
17868 further aspects about the currently invoked hook. It provides the following
17869 methods:
17870 .INDENT 7.0
17871 .INDENT 3.5
17872 .INDENT 0.0
17873 .TP
17874 .B \fBdefer()\fP
17875 Returning from the hook function should not automatically continue
17876 the hook. Instead, the API user wants to call \fBhook:cont()\fP on its
17877 own at a later point in time (before or after the function has
17878 returned).
17879 .TP
17880 .B \fBcont()\fP
17881 Continue the hook. Doesn\(aqt need to be called unless \fBdefer()\fP was
17882 called.
17883 .UNINDENT
17884 .UNINDENT
17885 .UNINDENT
17886 .sp
17887 See \fI\%Hooks\fP for currently existing hooks and what they do \- only the hook
17888 list is interesting; handling hook execution is done by the Lua script
17889 function automatically.
17890 .UNINDENT
17891 .SH JAVASCRIPT
17892 .sp
17893 JavaScript support in mpv is near identical to its Lua support. Use this section
17894 as reference on differences and availability of APIs, but otherwise you should
17895 refer to the Lua documentation for API details and general scripting in mpv.
17896 .SS Example
17897 .sp
17898 JavaScript code which leaves fullscreen mode when the player is paused:
17899 .INDENT 0.0
17900 .INDENT 3.5
17901 .sp
17902 .nf
17903 .ft C
17904 function on_pause_change(name, value) {
17905 if (value == true)
17906 mp.set_property("fullscreen", "no");
17907 }
17908 mp.observe_property("pause", "bool", on_pause_change);
17909 .ft P
17910 .fi
17911 .UNINDENT
17912 .UNINDENT
17913 .SS Similarities with Lua
17914 .sp
17915 mpv tries to load a script file as JavaScript if it has a \fB\&.js\fP extension, but
17916 otherwise, the documented Lua options, script directories, loading, etc apply to
17917 JavaScript files too.
17918 .sp
17919 Script initialization and lifecycle is the same as with Lua, and most of the Lua
17920 functions at the modules \fBmp\fP, \fBmp.utils\fP, \fBmp.msg\fP and \fBmp.options\fP are
17921 available to JavaScript with identical APIs \- including running commands,
17922 getting/setting properties, registering events/key\-bindings/hooks, etc.
17923 .SS Differences from Lua
17924 .sp
17925 No need to load modules. \fBmp\fP, \fBmp.utils\fP, \fBmp.msg\fP and \fBmp.options\fP
17926 are preloaded, and you can use e.g. \fBvar cwd = mp.utils.getcwd();\fP without
17927 prior setup.
17928 .sp
17929 Errors are slightly different. Where the Lua APIs return \fBnil\fP for error,
17930 the JavaScript ones return \fBundefined\fP\&. Where Lua returns \fBsomething, error\fP
17931 JavaScript returns only \fBsomething\fP \- and makes \fBerror\fP available via
17932 \fBmp.last_error()\fP\&. Note that only some of the functions have this additional
17933 \fBerror\fP value \- typically the same ones which have it in Lua.
17934 .sp
17935 Standard APIs are preferred. For instance \fBsetTimeout\fP and \fBJSON.stringify\fP
17936 are available, but \fBmp.add_timeout\fP and \fBmp.utils.format_json\fP are not.
17937 .sp
17938 No standard library. This means that interaction with anything outside of mpv is
17939 limited to the available APIs, typically via \fBmp.utils\fP\&. However, some file
17940 functions were added, and CommonJS \fBrequire\fP is available too \- where the
17941 loaded modules have the same privileges as normal scripts.
17942 .SS Language features \- ECMAScript 5
17943 .sp
17944 The scripting backend which mpv currently uses is MuJS \- a compatible minimal
17945 ES5 interpreter. As such, \fBString.substring\fP is implemented for instance,
17946 while the common but non\-standard \fBString.substr\fP is not. Please consult the
17947 MuJS pages on language features and platform support \- \fI\%http://mujs.com\fP .
17948 .SS Unsupported Lua APIs and their JS alternatives
17949 .sp
17950 \fBmp.add_timeout(seconds, fn)\fP JS: \fBid = setTimeout(fn, ms)\fP
17951 .sp
17952 \fBmp.add_periodic_timer(seconds, fn)\fP JS: \fBid = setInterval(fn, ms)\fP
17953 .sp
17954 \fButils.parse_json(str [, trail])\fP JS: \fBJSON.parse(str)\fP
17955 .sp
17956 \fButils.format_json(v)\fP JS: \fBJSON.stringify(v)\fP
17957 .sp
17958 \fButils.to_string(v)\fP see \fBdump\fP below.
17959 .sp
17960 \fBmp.suspend()\fP JS: none (deprecated).
17961 .sp
17962 \fBmp.resume()\fP JS: none (deprecated).
17963 .sp
17964 \fBmp.resume_all()\fP JS: none (deprecated).
17965 .sp
17966 \fBmp.get_next_timeout()\fP see event loop below.
17967 .sp
17968 \fBmp.dispatch_events([allow_wait])\fP see event loop below.
17969 .SS Scripting APIs \- identical to Lua
17970 .sp
17971 (LE) \- Last\-Error, indicates that \fBmp.last_error()\fP can be used after the
17972 call to test for success (empty string) or failure (non empty reason string).
17973 Where the Lua APIs use \fBnil\fP to indicate error, JS APIs use \fBundefined\fP\&.
17974 .sp
17975 \fBmp.command(string)\fP (LE)
17976 .sp
17977 \fBmp.commandv(arg1, arg2, ...)\fP (LE)
17978 .sp
17979 \fBmp.command_native(table [,def])\fP (LE)
17980 .sp
17981 \fBid = mp.command_native_async(table [,fn])\fP (LE) Notes: \fBid\fP is true\-thy on
17982 success, \fBfn\fP is called always a\-sync, \fBerror\fP is empty string on success.
17983 .sp
17984 \fBmp.abort_async_command(id)\fP
17985 .sp
17986 \fBmp.get_property(name [,def])\fP (LE)
17987 .sp
17988 \fBmp.get_property_osd(name [,def])\fP (LE)
17989 .sp
17990 \fBmp.get_property_bool(name [,def])\fP (LE)
17991 .sp
17992 \fBmp.get_property_number(name [,def])\fP (LE)
17993 .sp
17994 \fBmp.get_property_native(name [,def])\fP (LE)
17995 .sp
17996 \fBmp.set_property(name, value)\fP (LE)
17997 .sp
17998 \fBmp.set_property_bool(name, value)\fP (LE)
17999 .sp
18000 \fBmp.set_property_number(name, value)\fP (LE)
18001 .sp
18002 \fBmp.set_property_native(name, value)\fP (LE)
18003 .sp
18004 \fBmp.get_time()\fP
18005 .sp
18006 \fBmp.add_key_binding(key, name|fn [,fn [,flags]])\fP
18007 .sp
18008 \fBmp.add_forced_key_binding(...)\fP
18009 .sp
18010 \fBmp.remove_key_binding(name)\fP
18011 .sp
18012 \fBmp.register_event(name, fn)\fP
18013 .sp
18014 \fBmp.unregister_event(fn)\fP
18015 .sp
18016 \fBmp.observe_property(name, type, fn)\fP
18017 .sp
18018 \fBmp.unobserve_property(fn)\fP
18019 .sp
18020 \fBmp.get_opt(key)\fP
18021 .sp
18022 \fBmp.get_script_name()\fP
18023 .sp
18024 \fBmp.get_script_directory()\fP
18025 .sp
18026 \fBmp.osd_message(text [,duration])\fP
18027 .sp
18028 \fBmp.get_wakeup_pipe()\fP
18029 .sp
18030 \fBmp.register_idle(fn)\fP
18031 .sp
18032 \fBmp.unregister_idle(fn)\fP
18033 .sp
18034 \fBmp.enable_messages(level)\fP
18035 .sp
18036 \fBmp.register_script_message(name, fn)\fP
18037 .sp
18038 \fBmp.unregister_script_message(name)\fP
18039 .sp
18040 \fBmp.create_osd_overlay(format)\fP
18041 .sp
18042 \fBmp.get_osd_size()\fP (returned object has properties: width, height, aspect)
18043 .sp
18044 \fBmp.msg.log(level, ...)\fP
18045 .sp
18046 \fBmp.msg.fatal(...)\fP
18047 .sp
18048 \fBmp.msg.error(...)\fP
18049 .sp
18050 \fBmp.msg.warn(...)\fP
18051 .sp
18052 \fBmp.msg.info(...)\fP
18053 .sp
18054 \fBmp.msg.verbose(...)\fP
18055 .sp
18056 \fBmp.msg.debug(...)\fP
18057 .sp
18058 \fBmp.msg.trace(...)\fP
18059 .sp
18060 \fBmp.utils.getcwd()\fP (LE)
18061 .sp
18062 \fBmp.utils.readdir(path [, filter])\fP (LE)
18063 .sp
18064 \fBmp.utils.file_info(path)\fP (LE)
18065 .sp
18066 \fBmp.utils.split_path(path)\fP
18067 .sp
18068 \fBmp.utils.join_path(p1, p2)\fP
18069 .sp
18070 \fBmp.utils.subprocess(t)\fP
18071 .sp
18072 \fBmp.utils.subprocess_detached(t)\fP
18073 .sp
18074 \fBmp.utils.get_env_list()\fP
18075 .sp
18076 \fBmp.utils.getpid()\fP (LE)
18077 .sp
18078 \fBmp.add_hook(type, priority, fn(hook))\fP
18079 .sp
18080 \fBmp.options.read_options(obj [, identifier [, on_update]])\fP (types:
18081 string/boolean/number)
18082 .SS Additional utilities
18083 .INDENT 0.0
18084 .TP
18085 .B \fBmp.last_error()\fP
18086 If used after an API call which updates last error, returns an empty string
18087 if the API call succeeded, or a non\-empty error reason string otherwise.
18088 .TP
18089 .B \fBError.stack\fP (string)
18090 When using \fBtry { ... } catch(e) { ... }\fP, then \fBe.stack\fP is the stack
18091 trace of the error \- if it was created using the \fBError(...)\fP constructor.
18092 .TP
18093 .B \fBprint\fP (global)
18094 A convenient alias to \fBmp.msg.info\fP\&.
18095 .TP
18096 .B \fBdump\fP (global)
18097 Like \fBprint\fP but also expands objects and arrays recursively.
18098 .TP
18099 .B \fBmp.utils.getenv(name)\fP
18100 Returns the value of the host environment variable \fBname\fP, or
18101 \fBundefined\fP if the variable is not defined.
18102 .TP
18103 .B \fBmp.utils.get_user_path(path)\fP
18104 Expands (mpv) meta paths like \fB~/x\fP, \fB~~/y\fP, \fB~~desktop/z\fP etc.
18105 \fBread_file\fP, \fBwrite_file\fP and \fBrequire\fP already use this internaly.
18106 .TP
18107 .B \fBmp.utils.read_file(fname [,max])\fP
18108 Returns the content of file \fBfname\fP as string. If \fBmax\fP is provided and
18109 not negative, limit the read to \fBmax\fP bytes.
18110 .TP
18111 .B \fBmp.utils.write_file(fname, str)\fP
18112 (Over)write file \fBfname\fP with text content \fBstr\fP\&. \fBfname\fP must be
18113 prefixed with \fBfile://\fP as simple protection against accidental arguments
18114 switch, e.g. \fBmp.utils.write_file("file://~/abc.txt", "hello world")\fP\&.
18115 .UNINDENT
18116 .sp
18117 Note: \fBread_file\fP and \fBwrite_file\fP throw on errors, allow text content only.
18118 .INDENT 0.0
18119 .TP
18120 .B \fBmp.get_time_ms()\fP
18121 Same as \fBmp.get_time()\fP but in ms instead of seconds.
18122 .TP
18123 .B \fBmp.get_script_file()\fP
18124 Returns the file name of the current script.
18125 .TP
18126 .B \fBexit()\fP (global)
18127 Make the script exit at the end of the current event loop iteration.
18128 Note: please remove added key bindings before calling \fBexit()\fP\&.
18129 .TP
18130 .B \fBmp.utils.compile_js(fname, content_str)\fP
18131 Compiles the JS code \fBcontent_str\fP as file name \fBfname\fP (without loading
18132 anything from the filesystem), and returns it as a function. Very similar
18133 to a \fBFunction\fP constructor, but shows at stack traces as \fBfname\fP\&.
18134 .TP
18135 .B \fBmp.module_paths\fP
18136 Global modules search paths array for the \fBrequire\fP function (see below).
18137 .UNINDENT
18138 .SS Timers (global)
18139 .sp
18140 The standard HTML/node.js timers are available:
18141 .sp
18142 \fBid = setTimeout(fn [,duration [,arg1 [,arg2...]]])\fP
18143 .sp
18144 \fBid = setTimeout(code_string [,duration])\fP
18145 .sp
18146 \fBclearTimeout(id)\fP
18147 .sp
18148 \fBid = setInterval(fn [,duration [,arg1 [,arg2...]]])\fP
18149 .sp
18150 \fBid = setInterval(code_string [,duration])\fP
18151 .sp
18152 \fBclearInterval(id)\fP
18153 .sp
18154 \fBsetTimeout\fP and \fBsetInterval\fP return id, and later call \fBfn\fP (or execute
18155 \fBcode_string\fP) after \fBduration\fP ms. Interval also repeat every \fBduration\fP\&.
18156 .sp
18157 \fBduration\fP has a minimum and default value of 0, \fBcode_string\fP is
18158 a plain string which is evaluated as JS code, and \fB[,arg1 [,arg2..]]\fP are used
18159 as arguments (if provided) when calling back \fBfn\fP\&.
18160 .sp
18161 The \fBclear...(id)\fP functions cancel timer \fBid\fP, and are irreversible.
18162 .sp
18163 Note: timers always call back asynchronously, e.g. \fBsetTimeout(fn)\fP will never
18164 call \fBfn\fP before returning. \fBfn\fP will be called either at the end of this
18165 event loop iteration or at a later event loop iteration. This is true also for
18166 intervals \- which also never call back twice at the same event loop iteration.
18167 .sp
18168 Additionally, timers are processed after the event queue is empty, so it\(aqs valid
18169 to use \fBsetTimeout(fn)\fP as a one\-time idle observer.
18170 .SS CommonJS modules and \fBrequire(id)\fP
18171 .sp
18172 CommonJS Modules are a standard system where scripts can export common functions
18173 for use by other scripts. Specifically, a module is a script which adds
18174 properties (functions, etc) to its pre\-existing \fBexports\fP object, which
18175 another script can access with \fBrequire(module\-id)\fP\&. This runs the module and
18176 returns its \fBexports\fP object. Further calls to \fBrequire\fP for the same module
18177 will return its cached \fBexports\fP object without running the module again.
18178 .sp
18179 Modules and \fBrequire\fP are supported, standard compliant, and generally similar
18180 to node.js. However, most node.js modules won\(aqt run due to missing modules such
18181 as \fBfs\fP, \fBprocess\fP, etc, but some node.js modules with minimal dependencies
18182 do work. In general, this is for mpv modules and not a node.js replacement.
18183 .sp
18184 A \fB\&.js\fP file extension is always added to \fBid\fP, e.g. \fBrequire("./foo")\fP
18185 will load the file \fB\&./foo.js\fP and return its \fBexports\fP object.
18186 .sp
18187 An id which starts with \fB\&./\fP or \fB\&../\fP is relative to the script or module
18188 which \fBrequire\fP it. Otherwise it\(aqs considered a top\-level id (CommonJS term).
18189 .sp
18190 Top\-level id is evaluated as absolute filesystem path if possible, e.g. \fB/x/y\fP
18191 or \fB~/x\fP\&. Otherwise it\(aqs considered a global module id and searched according
18192 to \fBmp.module_paths\fP in normal array order, e.g. \fBrequire("x")\fP tries to
18193 load \fBx.js\fP at one of the array paths, and id \fBfoo/x\fP tries to load \fBx.js\fP
18194 inside dir \fBfoo\fP at one of the paths.
18195 .sp
18196 The \fBmp.module_paths\fP array is empty by default except for scripts which are
18197 loaded as a directory where it contains one item \- \fB<directory>/modules/\fP .
18198 The array may be updated from a script (or using custom init \- see below) which
18199 will affect future calls to \fBrequire\fP for global module id\(aqs which are not
18200 already loaded/cached.
18201 .sp
18202 No \fBglobal\fP variable, but a module\(aqs \fBthis\fP at its top lexical scope is the
18203 global object \- also in strict mode. If you have a module which needs \fBglobal\fP
18204 as the global object, you could do \fBthis.global = this;\fP before \fBrequire\fP\&.
18205 .sp
18206 Functions and variables declared at a module don\(aqt pollute the global object.
18207 .SS Custom initialization
18208 .sp
18209 After mpv initializes the JavaScript environment for a script but before it
18210 loads the script \- it tries to run the file \fB\&.init.js\fP at the root of the mpv
18211 configuration directory. Code at this file can update the environment further
18212 for all scripts. E.g. if it contains \fBmp.module_paths.push("/foo")\fP then
18213 \fBrequire\fP at all scripts will search global module id\(aqs also at \fB/foo\fP\&.
18214 .SS The event loop
18215 .sp
18216 The event loop poll/dispatch mpv events as long as the queue is not empty, then
18217 processes the timers, then waits for the next event, and repeats this forever.
18218 .sp
18219 You could put this code at your script to replace the built\-in event loop, and
18220 also print every event which mpv sends to your script:
18221 .INDENT 0.0
18222 .INDENT 3.5
18223 .sp
18224 .nf
18225 .ft C
18226 function mp_event_loop() {
18227 var wait = 0;
18228 do {
18229 var e = mp.wait_event(wait);
18230 dump(e); // there could be a lot of prints...
18231 if (e.event != "none") {
18232 mp.dispatch_event(e);
18233 wait = 0;
18234 } else {
18235 wait = mp.process_timers() / 1000;
18236 if (wait != 0) {
18237 mp.notify_idle_observers();
18238 wait = mp.peek_timers_wait() / 1000;
18239 }
18240 }
18241 } while (mp.keep_running);
18242 }
18243 .ft P
18244 .fi
18245 .UNINDENT
18246 .UNINDENT
18247 .sp
18248 \fBmp_event_loop\fP is a name which mpv tries to call after the script loads.
18249 The internal implementation is similar to this (without \fBdump\fP though..).
18250 .sp
18251 \fBe = mp.wait_event(wait)\fP returns when the next mpv event arrives, or after
18252 \fBwait\fP seconds if positive and no mpv events arrived. \fBwait\fP value of 0
18253 returns immediately (with \fBe.event == "none"\fP if the queue is empty).
18254 .sp
18255 \fBmp.dispatch_event(e)\fP calls back the handlers registered for \fBe.event\fP,
18256 if there are such (event handlers, property observers, script messages, etc).
18257 .sp
18258 \fBmp.process_timers()\fP calls back the already\-added, non\-canceled due timers,
18259 and returns the duration in ms till the next due timer (possibly 0), or \-1 if
18260 there are no pending timers. Must not be called recursively.
18261 .sp
18262 \fBmp.notify_idle_observers()\fP calls back the idle observers, which we do when
18263 we\(aqre about to sleep (wait != 0), but the observers may add timers or take
18264 non\-negligible duration to complete, so we re\-calculate \fBwait\fP afterwards.
18265 .sp
18266 \fBmp.peek_timers_wait()\fP returns the same values as \fBmp.process_timers()\fP
18267 but without doing anything. Invalid result if called from a timer callback.
18268 .sp
18269 Note: \fBexit()\fP is also registered for the \fBshutdown\fP event, and its
18270 implementation is a simple \fBmp.keep_running = false\fP\&.
18271 .SH JSON IPC
18272 .sp
18273 mpv can be controlled by external programs using the JSON\-based IPC protocol.
18274 It can be enabled by specifying the path to a unix socket or a named pipe using
18275 the option \fB\-\-input\-ipc\-server\fP\&. Clients can connect to this socket and send
18276 commands to the player or receive events from it.
18277 .sp
18278 \fBWARNING:\fP
18279 .INDENT 0.0
18280 .INDENT 3.5
18281 This is not intended to be a secure network protocol. It is explicitly
18282 insecure: there is no authentication, no encryption, and the commands
18283 themselves are insecure too. For example, the \fBrun\fP command is exposed,
18284 which can run arbitrary system commands. The use\-case is controlling the
18285 player locally. This is not different from the MPlayer slave protocol.
18286 .UNINDENT
18287 .UNINDENT
18288 .SS Socat example
18289 .sp
18290 You can use the \fBsocat\fP tool to send commands (and receive replies) from the
18291 shell. Assuming mpv was started with:
18292 .INDENT 0.0
18293 .INDENT 3.5
18294 .sp
18295 .nf
18296 .ft C
18297 mpv file.mkv \-\-input\-ipc\-server=/tmp/mpvsocket
18298 .ft P
18299 .fi
18300 .UNINDENT
18301 .UNINDENT
18302 .sp
18303 Then you can control it using socat:
18304 .INDENT 0.0
18305 .INDENT 3.5
18306 .sp
18307 .nf
18308 .ft C
18309 > echo \(aq{ "command": ["get_property", "playback\-time"] }\(aq | socat \- /tmp/mpvsocket
18310 {"data":190.482000,"error":"success"}
18311 .ft P
18312 .fi
18313 .UNINDENT
18314 .UNINDENT
18315 .sp
18316 In this case, socat copies data between stdin/stdout and the mpv socket
18317 connection.
18318 .sp
18319 See the \fB\-\-idle\fP option how to make mpv start without exiting immediately or
18320 playing a file.
18321 .sp
18322 It\(aqs also possible to send input.conf style text\-only commands:
18323 .INDENT 0.0
18324 .INDENT 3.5
18325 .sp
18326 .nf
18327 .ft C
18328 > echo \(aqshow\-text ${playback\-time}\(aq | socat \- /tmp/mpvsocket
18329 .ft P
18330 .fi
18331 .UNINDENT
18332 .UNINDENT
18333 .sp
18334 But you won\(aqt get a reply over the socket. (This particular command shows the
18335 playback time on the player\(aqs OSD.)
18336 .SS Command Prompt example
18337 .sp
18338 Unfortunately, it\(aqs not as easy to test the IPC protocol on Windows, since
18339 Windows ports of socat (in Cygwin and MSYS2) don\(aqt understand named pipes. In
18340 the absence of a simple tool to send and receive from bidirectional pipes, the
18341 \fBecho\fP command can be used to send commands, but not receive replies from the
18342 command prompt.
18343 .sp
18344 Assuming mpv was started with:
18345 .INDENT 0.0
18346 .INDENT 3.5
18347 .sp
18348 .nf
18349 .ft C
18350 mpv file.mkv \-\-input\-ipc\-server=\e\e.\epipe\empvsocket
18351 .ft P
18352 .fi
18353 .UNINDENT
18354 .UNINDENT
18355 .sp
18356 You can send commands from a command prompt:
18357 .INDENT 0.0
18358 .INDENT 3.5
18359 .sp
18360 .nf
18361 .ft C
18362 echo show\-text ${playback\-time} >\e\e.\epipe\empvsocket
18363 .ft P
18364 .fi
18365 .UNINDENT
18366 .UNINDENT
18367 .sp
18368 To be able to simultaneously read and write from the IPC pipe, like on Linux,
18369 it\(aqs necessary to write an external program that uses overlapped file I/O (or
18370 some wrapper like .NET\(aqs NamedPipeClientStream.)
18371 .sp
18372 You can open the pipe in PuTTY as "serial" device. This is not very
18373 comfortable, but gives a way to test interactively without having to write code.
18374 .SS Protocol
18375 .sp
18376 The protocol uses UTF\-8\-only JSON as defined by RFC\-8259. Unlike standard JSON,
18377 "u" escape sequences are not allowed to construct surrogate pairs. To avoid
18378 getting conflicts, encode all text characters including and above codepoint
18379 U+0020 as UTF\-8. mpv might output broken UTF\-8 in corner cases (see "UTF\-8"
18380 section below).
18381 .sp
18382 Clients can execute commands on the player by sending JSON messages of the
18383 following form:
18384 .INDENT 0.0
18385 .INDENT 3.5
18386 .sp
18387 .nf
18388 .ft C
18389 { "command": ["command_name", "param1", "param2", ...] }
18390 .ft P
18391 .fi
18392 .UNINDENT
18393 .UNINDENT
18394 .sp
18395 where \fBcommand_name\fP is the name of the command to be executed, followed by a
18396 list of parameters. Parameters must be formatted as native JSON values
18397 (integers, strings, booleans, ...). Every message \fBmust\fP be terminated with
18398 \fB\en\fP\&. Additionally, \fB\en\fP must not appear anywhere inside the message. In
18399 practice this means that messages should be minified before being sent to mpv.
18400 .sp
18401 mpv will then send back a reply indicating whether the command was run
18402 correctly, and an additional field holding the command\-specific return data (it
18403 can also be null).
18404 .INDENT 0.0
18405 .INDENT 3.5
18406 .sp
18407 .nf
18408 .ft C
18409 { "error": "success", "data": null }
18410 .ft P
18411 .fi
18412 .UNINDENT
18413 .UNINDENT
18414 .sp
18415 mpv will also send events to clients with JSON messages of the following form:
18416 .INDENT 0.0
18417 .INDENT 3.5
18418 .sp
18419 .nf
18420 .ft C
18421 { "event": "event_name" }
18422 .ft P
18423 .fi
18424 .UNINDENT
18425 .UNINDENT
18426 .sp
18427 where \fBevent_name\fP is the name of the event. Additional event\-specific fields
18428 can also be present. See \fI\%List of events\fP for a list of all supported events.
18429 .sp
18430 Because events can occur at any time, it may be difficult at times to determine
18431 which response goes with which command. Commands may optionally include a
18432 \fBrequest_id\fP which, if provided in the command request, will be copied
18433 verbatim into the response. mpv does not intrepret the \fBrequest_id\fP in any
18434 way; it is solely for the use of the requester. The only requirement is that
18435 the \fBrequest_id\fP field must be an integer (a number without fractional parts
18436 in the range \fB\-2^63..2^63\-1\fP). Using other types is deprecated and will
18437 currently show a warning. In the future, this will raise an error.
18438 .sp
18439 For example, this request:
18440 .INDENT 0.0
18441 .INDENT 3.5
18442 .sp
18443 .nf
18444 .ft C
18445 { "command": ["get_property", "time\-pos"], "request_id": 100 }
18446 .ft P
18447 .fi
18448 .UNINDENT
18449 .UNINDENT
18450 .sp
18451 Would generate this response:
18452 .INDENT 0.0
18453 .INDENT 3.5
18454 .sp
18455 .nf
18456 .ft C
18457 { "error": "success", "data": 1.468135, "request_id": 100 }
18458 .ft P
18459 .fi
18460 .UNINDENT
18461 .UNINDENT
18462 .sp
18463 If you don\(aqt specify a \fBrequest_id\fP, command replies will set it to 0.
18464 .sp
18465 All commands, replies, and events are separated from each other with a line
18466 break character (\fB\en\fP).
18467 .sp
18468 If the first character (after skipping whitespace) is not \fB{\fP, the command
18469 will be interpreted as non\-JSON text command, as they are used in input.conf
18470 (or \fBmpv_command_string()\fP in the client API). Additionally, lines starting
18471 with \fB#\fP and empty lines are ignored.
18472 .sp
18473 Currently, embedded 0 bytes terminate the current line, but you should not
18474 rely on this.
18475 .SS Data flow
18476 .sp
18477 Currently, the mpv\-side IPC implementation does not service the socket while a
18478 command is executed and the reply is written. It is for example not possible
18479 that other events, that happened during the execution of the command, are
18480 written to the socket before the reply is written.
18481 .sp
18482 This might change in the future. The only guarantee is that replies to IPC
18483 messages are sent in sequence.
18484 .sp
18485 Also, since socket I/O is inherently asynchronous, it is possible that you read
18486 unrelated event messages from the socket, before you read the reply to the
18487 previous command you sent. In this case, these events were queued by the mpv
18488 side before it read and started processing your command message.
18489 .sp
18490 If the mpv\-side IPC implementation switches away from blocking writes and
18491 blocking command execution, it may attempt to send events at any time.
18492 .sp
18493 You can also use asynchronous commands, which can return in any order, and
18494 which do not block IPC protocol interaction at all while the command is
18495 executed in the background.
18496 .SS Asynchronous commands
18497 .sp
18498 Command can be run asynchronously. This behaves exactly as with normal command
18499 execution, except that execution is not blocking. Other commands can be sent
18500 while it\(aqs executing, and command completion can be arbitrarily reordered.
18501 .sp
18502 The \fBasync\fP field controls this. If present, it must be a boolean. If missing,
18503 \fBfalse\fP is assumed.
18504 .sp
18505 For example, this initiates an asynchronous command:
18506 .INDENT 0.0
18507 .INDENT 3.5
18508 .sp
18509 .nf
18510 .ft C
18511 { "command": ["screenshot"], "request_id": 123, "async": true }
18512 .ft P
18513 .fi
18514 .UNINDENT
18515 .UNINDENT
18516 .sp
18517 And this is the completion:
18518 .INDENT 0.0
18519 .INDENT 3.5
18520 .sp
18521 .nf
18522 .ft C
18523 {"request_id":123,"error":"success","data":null}
18524 .ft P
18525 .fi
18526 .UNINDENT
18527 .UNINDENT
18528 .sp
18529 By design, you will not get a confirmation that the command was started. If a
18530 command is long running, sending the message will lead to any reply until much
18531 later when the command finishes.
18532 .sp
18533 Some commands execute synchronously, but these will behave like asynchronous
18534 commands that finished execution immediately.
18535 .sp
18536 Cancellation of asynchronous commands is available in the libmpv API, but has
18537 not yet been implemented in the IPC protocol.
18538 .SS Commands with named arguments
18539 .sp
18540 If the \fBcommand\fP field is a JSON object, named arguments are expected. This
18541 is described in the C API \fBmpv_command_node()\fP documentation (the
18542 \fBMPV_FORMAT_NODE_MAP\fP case). In some cases, this may make commands more
18543 readable, while some obscure commands basically require using named arguments.
18544 .sp
18545 Currently, only "proper" commands (as listed by \fI\%List of Input Commands\fP)
18546 support named arguments.
18547 .SS Commands
18548 .sp
18549 In addition to the commands described in \fI\%List of Input Commands\fP, a few
18550 extra commands can also be used as part of the protocol:
18551 .INDENT 0.0
18552 .TP
18553 .B \fBclient_name\fP
18554 Return the name of the client as string. This is the string \fBipc\-N\fP with
18555 N being an integer number.
18556 .TP
18557 .B \fBget_time_us\fP
18558 Return the current mpv internal time in microseconds as a number. This is
18559 basically the system time, with an arbitrary offset.
18560 .TP
18561 .B \fBget_property\fP
18562 Return the value of the given property. The value will be sent in the data
18563 field of the replay message.
18564 .sp
18565 Example:
18566 .INDENT 7.0
18567 .INDENT 3.5
18568 .sp
18569 .nf
18570 .ft C
18571 { "command": ["get_property", "volume"] }
18572 { "data": 50.0, "error": "success" }
18573 .ft P
18574 .fi
18575 .UNINDENT
18576 .UNINDENT
18577 .TP
18578 .B \fBget_property_string\fP
18579 Like \fBget_property\fP, but the resulting data will always be a string.
18580 .sp
18581 Example:
18582 .INDENT 7.0
18583 .INDENT 3.5
18584 .sp
18585 .nf
18586 .ft C
18587 { "command": ["get_property_string", "volume"] }
18588 { "data": "50.000000", "error": "success" }
18589 .ft P
18590 .fi
18591 .UNINDENT
18592 .UNINDENT
18593 .TP
18594 .B \fBset_property\fP
18595 Set the given property to the given value. See \fI\%Properties\fP for more
18596 information about properties.
18597 .sp
18598 Example:
18599 .INDENT 7.0
18600 .INDENT 3.5
18601 .sp
18602 .nf
18603 .ft C
18604 { "command": ["set_property", "pause", true] }
18605 { "error": "success" }
18606 .ft P
18607 .fi
18608 .UNINDENT
18609 .UNINDENT
18610 .TP
18611 .B \fBset_property_string\fP
18612 Alias for \fBset_property\fP\&. Both commands accept native values and strings.
18613 .TP
18614 .B \fBobserve_property\fP
18615 Watch a property for changes. If the given property is changed, then an
18616 event of type \fBproperty\-change\fP will be generated
18617 .sp
18618 Example:
18619 .INDENT 7.0
18620 .INDENT 3.5
18621 .sp
18622 .nf
18623 .ft C
18624 { "command": ["observe_property", 1, "volume"] }
18625 { "error": "success" }
18626 { "event": "property\-change", "id": 1, "data": 52.0, "name": "volume" }
18627 .ft P
18628 .fi
18629 .UNINDENT
18630 .UNINDENT
18631 .sp
18632 \fBWARNING:\fP
18633 .INDENT 7.0
18634 .INDENT 3.5
18635 If the connection is closed, the IPC client is destroyed internally,
18636 and the observed properties are unregistered. This happens for example
18637 when sending commands to a socket with separate \fBsocat\fP invocations.
18638 This can make it seem like property observation does not work. You must
18639 keep the IPC connection open to make it work.
18640 .UNINDENT
18641 .UNINDENT
18642 .TP
18643 .B \fBobserve_property_string\fP
18644 Like \fBobserve_property\fP, but the resulting data will always be a string.
18645 .sp
18646 Example:
18647 .INDENT 7.0
18648 .INDENT 3.5
18649 .sp
18650 .nf
18651 .ft C
18652 { "command": ["observe_property_string", 1, "volume"] }
18653 { "error": "success" }
18654 { "event": "property\-change", "id": 1, "data": "52.000000", "name": "volume" }
18655 .ft P
18656 .fi
18657 .UNINDENT
18658 .UNINDENT
18659 .TP
18660 .B \fBunobserve_property\fP
18661 Undo \fBobserve_property\fP or \fBobserve_property_string\fP\&. This requires the
18662 numeric id passed to the observed command as argument.
18663 .sp
18664 Example:
18665 .INDENT 7.0
18666 .INDENT 3.5
18667 .sp
18668 .nf
18669 .ft C
18670 { "command": ["unobserve_property", 1] }
18671 { "error": "success" }
18672 .ft P
18673 .fi
18674 .UNINDENT
18675 .UNINDENT
18676 .TP
18677 .B \fBrequest_log_messages\fP
18678 Enable output of mpv log messages. They will be received as events. The
18679 parameter to this command is the log\-level (see \fBmpv_request_log_messages\fP
18680 C API function).
18681 .sp
18682 Log message output is meant for humans only (mostly for debugging).
18683 Attempting to retrieve information by parsing these messages will just
18684 lead to breakages with future mpv releases. Instead, make a feature request,
18685 and ask for a proper event that returns the information you need.
18686 .TP
18687 .B \fBenable_event\fP, \fBdisable_event\fP
18688 Enables or disables the named event. Mirrors the \fBmpv_request_event\fP C
18689 API function. If the string \fBall\fP is used instead of an event name, all
18690 events are enabled or disabled.
18691 .sp
18692 By default, most events are enabled, and there is not much use for this
18693 command.
18694 .TP
18695 .B \fBget_version\fP
18696 Returns the client API version the C API of the remote mpv instance
18697 provides.
18698 .sp
18699 See also: \fBDOCS/client\-api\-changes.rst\fP\&.
18700 .UNINDENT
18701 .SS UTF\-8
18702 .sp
18703 Normally, all strings are in UTF\-8. Sometimes it can happen that strings are
18704 in some broken encoding (often happens with file tags and such, and filenames
18705 on many Unixes are not required to be in UTF\-8 either). This means that mpv
18706 sometimes sends invalid JSON. If that is a problem for the client application\(aqs
18707 parser, it should filter the raw data for invalid UTF\-8 sequences and perform
18708 the desired replacement, before feeding the data to its JSON parser.
18709 .sp
18710 mpv will not attempt to construct invalid UTF\-8 with broken "u" escape
18711 sequences. This includes surrogate pairs.
18712 .SS JSON extensions
18713 .sp
18714 The following non\-standard extensions are supported:
18715 .INDENT 0.0
18716 .INDENT 3.5
18717 .INDENT 0.0
18718 .IP \(bu 2
18719 a list or object item can have a trailing ","
18720 .IP \(bu 2
18721 object syntax accepts "=" in addition of ":"
18722 .IP \(bu 2
18723 object keys can be unquoted, if they start with a character in "A\-Za\-z_"
18724 and contain only characters in "A\-Za\-z0\-9_"
18725 .IP \(bu 2
18726 byte escapes with "xAB" are allowed (with AB being a 2 digit hex number)
18727 .UNINDENT
18728 .UNINDENT
18729 .UNINDENT
18730 .sp
18731 Example:
18732 .INDENT 0.0
18733 .INDENT 3.5
18734 .sp
18735 .nf
18736 .ft C
18737 { objkey = "value\ex0A" }
18738 .ft P
18739 .fi
18740 .UNINDENT
18741 .UNINDENT
18742 .sp
18743 Is equivalent to:
18744 .INDENT 0.0
18745 .INDENT 3.5
18746 .sp
18747 .nf
18748 .ft C
18749 { "objkey": "value\en" }
18750 .ft P
18751 .fi
18752 .UNINDENT
18753 .UNINDENT
18754 .SS Alternative ways of starting clients
18755 .sp
18756 You can create an anonymous IPC connection without having to set
18757 \fB\-\-input\-ipc\-server\fP\&. This is achieved through a mpv pseudo scripting backend
18758 that starts processes.
18759 .sp
18760 You can put \fB\&.run\fP file extension in the mpv scripts directory in its config
18761 directory (see the \fI\%FILES\fP section for details), or load them through other
18762 means (see \fI\%Script location\fP). These scripts are simply executed with the OS
18763 native mechanism (as if you ran them in the shell). They must have a proper
18764 shebang and have the executable bit set.
18765 .sp
18766 When executed, a socket (the IPC connection) is passed to them through file
18767 descriptor inheritance. The file descriptor is indicated as the special command
18768 line argument \fB\-\-mpv\-ipc\-fd=N\fP, where \fBN\fP is the numeric file descriptor.
18769 .sp
18770 The rest is the same as with a normal \fB\-\-input\-ipc\-server\fP IPC connection. mpv
18771 does not attempt to observe or other interact with the started script process.
18772 .sp
18773 This does not work in Windows yet.
18774 .SH CHANGELOG
18775 .sp
18776 There is no real changelog, but you can look at the following things:
18777 .INDENT 0.0
18778 .IP \(bu 2
18779 The release changelog, which should contain most user\-visible changes,
18780 including new features and bug fixes:
18781 .sp
18782 \fI\%https://github.com/mpv\-player/mpv/releases\fP
18783 .IP \(bu 2
18784 The git log, which is the "real" changelog
18785 .IP \(bu 2
18786 The file \fI\%https://github.com/mpv\-player/mpv/blob/master/DOCS/interface\-changes.rst\fP
18787 documents changes to the command and user interface, such as options and
18788 properties. (It usually documents breaking changes only, additions and
18789 enhancements are often not listed.)
18790 .IP \(bu 2
18791 C API changes are listed in
18792 \fI\%https://github.com/mpv\-player/mpv/blob/master/DOCS/client\-api\-changes.rst\fP
18793 .IP \(bu 2
18794 The file \fBmplayer\-changes.rst\fP in the \fBDOCS\fP sub directory on the git
18795 repository, which used to be in place of this section. It documents some
18796 changes that happened since mplayer2 forked off MPlayer. (Not updated
18797 anymore.)
18798 .UNINDENT
18799 .SH EMBEDDING INTO OTHER PROGRAMS (LIBMPV)
18800 .sp
18801 mpv can be embedded into other programs as video/audio playback backend. The
18802 recommended way to do so is using libmpv. See \fBlibmpv/client.h\fP in the mpv
18803 source code repository. This provides a C API. Bindings for other languages
18804 might be available (see wiki).
18805 .sp
18806 Since libmpv merely allows access to underlying mechanisms that can control
18807 mpv, further documentation is spread over a few places:
18808 .INDENT 0.0
18809 .IP \(bu 2
18810 \fI\%https://github.com/mpv\-player/mpv/blob/master/libmpv/client.h\fP
18811 .IP \(bu 2
18812 \fI\%http://mpv.io/manual/master/#options\fP
18813 .IP \(bu 2
18814 \fI\%http://mpv.io/manual/master/#list\-of\-input\-commands\fP
18815 .IP \(bu 2
18816 \fI\%http://mpv.io/manual/master/#properties\fP
18817 .IP \(bu 2
18818 \fI\%https://github.com/mpv\-player/mpv\-examples/tree/master/libmpv\fP
18819 .UNINDENT
18820 .SH C PLUGINS
18821 .sp
18822 You can write C plugins for mpv. These use the libmpv API, although they do not
18823 use the libmpv library itself.
18824 .sp
18825 Currently, they must be explicitly enabled at build time with
18826 \fB\-\-enable\-cplugins\fP\&. They are available on Linux/BSD platforms only.
18827 .SS C plugins location
18828 .sp
18829 C plugins are put into the mpv scripts directory in its config directory
18830 (see the \fI\%FILES\fP section for details). They must have a \fB\&.so\fP file extension.
18831 They can also be explicitly loaded with the \fB\-\-script\fP option.
18832 .SS API
18833 .sp
18834 A C plugin must export the following function:
18835 .INDENT 0.0
18836 .INDENT 3.5
18837 .sp
18838 .nf
18839 .ft C
18840 int mpv_open_cplugin(mpv_handle *handle)
18841 .ft P
18842 .fi
18843 .UNINDENT
18844 .UNINDENT
18845 .sp
18846 The plugin function will be called on loading time. This function does not
18847 return as long as your plugin is loaded (it runs in its own thread). The
18848 \fBhandle\fP will be deallocated as soon as the plugin function returns.
18849 .sp
18850 The return value is interpreted as error status. A value of \fB0\fP is
18851 interpreted as success, while \fB\-1\fP signals an error. In the latter case,
18852 the player prints an uninformative error message that loading failed.
18853 .sp
18854 Return values other than \fB0\fP and \fB\-1\fP are reserved, and trigger undefined
18855 behavior.
18856 .sp
18857 Within the plugin function, you can call libmpv API functions. The \fBhandle\fP
18858 is created by \fBmpv_create_client()\fP (or actually an internal equivalent),
18859 and belongs to you. You can call \fBmpv_wait_event()\fP to wait for things
18860 happening, and so on.
18861 .sp
18862 Note that the player might block until your plugin calls \fBmpv_wait_event()\fP
18863 for the first time. This gives you a chance to install initial hooks etc.
18864 before playback begins.
18865 .sp
18866 The details are quite similar to Lua scripts.
18867 .SS Linkage to libmpv
18868 .sp
18869 The current implementation requires that your plugins are \fBnot\fP linked against
18870 libmpv. What your plugins uses are not symbols from a libmpv binary, but
18871 symbols from the mpv host binary.
18872 .SS Examples
18873 .sp
18874 See:
18875 .INDENT 0.0
18876 .IP \(bu 2
18877 \fI\%https://github.com/mpv\-player/mpv\-examples/tree/master/cplugins\fP
18878 .UNINDENT
18879 .SH ENVIRONMENT VARIABLES
18880 .sp
18881 There are a number of environment variables that can be used to control the
18882 behavior of mpv.
18883 .INDENT 0.0
18884 .TP
18885 .B \fBHOME\fP, \fBXDG_CONFIG_HOME\fP
18886 Used to determine mpv config directory. If \fBXDG_CONFIG_HOME\fP is not set,
18887 \fB$HOME/.config/mpv\fP is used.
18888 .sp
18889 \fB$HOME/.mpv\fP is always added to the list of config search paths with a
18890 lower priority.
18891 .TP
18892 .B \fBMPV_HOME\fP
18893 Directory where mpv looks for user settings. Overrides \fBHOME\fP, and mpv
18894 will try to load the config file as \fB$MPV_HOME/mpv.conf\fP\&.
18895 .TP
18896 .B \fBMPV_VERBOSE\fP (see also \fB\-v\fP and \fB\-\-msg\-level\fP)
18897 Set the initial verbosity level across all message modules (default: 0).
18898 This is an integer, and the resulting verbosity corresponds to the number
18899 of \fB\-\-v\fP options passed to the command line.
18900 .TP
18901 .B \fBMPV_LEAK_REPORT\fP
18902 If set to \fB1\fP, enable internal talloc leak reporting. If set to another
18903 value, disable leak reporting. If unset, use the default, which normally is
18904 \fB0\fP\&. If mpv was built with \fB\-\-enable\-ta\-leak\-report\fP, the default is
18905 \fB1\fP\&. If leak reporting was disabled at compile time (\fBNDEBUG\fP in
18906 custom \fBCFLAGS\fP), this environment variable is ignored.
18907 .TP
18908 .B \fBLADSPA_PATH\fP
18909 Specifies the search path for LADSPA plugins. If it is unset, fully
18910 qualified path names must be used.
18911 .TP
18912 .B \fBDISPLAY\fP
18913 Standard X11 display name to use.
18914 .TP
18915 .B FFmpeg/Libav:
18916 This library accesses various environment variables. However, they are not
18917 centrally documented, and documenting them is not our job. Therefore, this
18918 list is incomplete.
18919 .sp
18920 Notable environment variables:
18921 .INDENT 7.0
18922 .TP
18923 .B \fBhttp_proxy\fP
18924 URL to proxy for \fBhttp://\fP and \fBhttps://\fP URLs.
18925 .TP
18926 .B \fBno_proxy\fP
18927 List of domain patterns for which no proxy should be used.
18928 List entries are separated by \fB,\fP\&. Patterns can include \fB*\fP\&.
18929 .UNINDENT
18930 .TP
18931 .B libdvdcss:
18932 .INDENT 7.0
18933 .TP
18934 .B \fBDVDCSS_CACHE\fP
18935 Specify a directory in which to store title key values. This will
18936 speed up descrambling of DVDs which are in the cache. The
18937 \fBDVDCSS_CACHE\fP directory is created if it does not exist, and a
18938 subdirectory is created named after the DVD\(aqs title or manufacturing
18939 date. If \fBDVDCSS_CACHE\fP is not set or is empty, libdvdcss will use
18940 the default value which is \fB${HOME}/.dvdcss/\fP under Unix and
18941 the roaming application data directory (\fB%APPDATA%\fP) under
18942 Windows. The special value "off" disables caching.
18943 .TP
18944 .B \fBDVDCSS_METHOD\fP
18945 Sets the authentication and decryption method that libdvdcss will use
18946 to read scrambled discs. Can be one of \fBtitle\fP, \fBkey\fP or \fBdisc\fP\&.
18947 .INDENT 7.0
18948 .TP
18949 .B key
18950 is the default method. libdvdcss will use a set of calculated
18951 player keys to try to get the disc key. This can fail if the drive
18952 does not recognize any of the player keys.
18953 .TP
18954 .B disc
18955 is a fallback method when key has failed. Instead of using player
18956 keys, libdvdcss will crack the disc key using a brute force
18957 algorithm. This process is CPU intensive and requires 64 MB of
18958 memory to store temporary data.
18959 .TP
18960 .B title
18961 is the fallback when all other methods have failed. It does not
18962 rely on a key exchange with the DVD drive, but rather uses a crypto
18963 attack to guess the title key. On rare cases this may fail because
18964 there is not enough encrypted data on the disc to perform a
18965 statistical attack, but on the other hand it is the only way to
18966 decrypt a DVD stored on a hard disc, or a DVD with the wrong region
18967 on an RPC2 drive.
18968 .UNINDENT
18969 .TP
18970 .B \fBDVDCSS_RAW_DEVICE\fP
18971 Specify the raw device to use. Exact usage will depend on your
18972 operating system, the Linux utility to set up raw devices is raw(8)
18973 for instance. Please note that on most operating systems, using a raw
18974 device requires highly aligned buffers: Linux requires a 2048 bytes
18975 alignment (which is the size of a DVD sector).
18976 .TP
18977 .B \fBDVDCSS_VERBOSE\fP
18978 Sets the libdvdcss verbosity level.
18979 .INDENT 7.0
18980 .TP
18981 .B 0
18982 Outputs no messages at all.
18983 .TP
18984 .B 1
18985 Outputs error messages to stderr.
18986 .TP
18987 .B 2
18988 Outputs error messages and debug messages to stderr.
18989 .UNINDENT
18990 .TP
18991 .B \fBDVDREAD_NOKEYS\fP
18992 Skip retrieving all keys on startup. Currently disabled.
18993 .TP
18994 .B \fBHOME\fP
18995 FIXME: Document this.
18996 .UNINDENT
18997 .UNINDENT
18998 .SH EXIT CODES
18999 .sp
19000 Normally \fBmpv\fP returns 0 as exit code after finishing playback successfully.
19001 If errors happen, the following exit codes can be returned:
19002 .INDENT 0.0
19003 .INDENT 3.5
19004 .INDENT 0.0
19005 .TP
19006 .B 1
19007 Error initializing mpv. This is also returned if unknown options are
19008 passed to mpv.
19009 .TP
19010 .B 2
19011 The file passed to mpv couldn\(aqt be played. This is somewhat fuzzy:
19012 currently, playback of a file is considered to be successful if
19013 initialization was mostly successful, even if playback fails
19014 immediately after initialization.
19015 .TP
19016 .B 3
19017 There were some files that could be played, and some files which
19018 couldn\(aqt (using the definition of success from above).
19019 .TP
19020 .B 4
19021 Quit due to a signal, Ctrl+c in a VO window (by default), or from the
19022 default quit key bindings in encoding mode.
19023 .UNINDENT
19024 .UNINDENT
19025 .UNINDENT
19026 .sp
19027 Note that quitting the player manually will always lead to exit code 0,
19028 overriding the exit code that would be returned normally. Also, the \fBquit\fP
19029 input command can take an exit code: in this case, that exit code is returned.
19030 .SH FILES
19031 .sp
19032 For Windows\-specifics, see \fI\%FILES ON WINDOWS\fP section.
19033 .INDENT 0.0
19034 .TP
19035 .B \fB/usr/local/etc/mpv/mpv.conf\fP
19036 mpv system\-wide settings (depends on \fB\-\-prefix\fP passed to configure \- mpv
19037 in default configuration will use \fB/usr/local/etc/mpv/\fP as config
19038 directory, while most Linux distributions will set it to \fB/etc/mpv/\fP).
19039 .TP
19040 .B \fB~/.config/mpv\fP
19041 The standard configuration directory. This can be overridden by environment
19042 variables, in ascending order:
19043 .INDENT 7.0
19044 .TP
19045 .B 1
19046 If \fB$XDG_CONFIG_HOME\fP is set, then the derived configuration directory
19047 will be \fB$XDG_CONFIG_HOME/mpv\fP\&.
19048 .TP
19049 .B 2
19050 If \fB$MPV_HOME\fP is set, then the derived configuration directory will be
19051 \fB$MPV_HOME\fP\&.
19052 .UNINDENT
19053 .sp
19054 If this directory, nor the original configuration directory (see below) do
19055 not exist, mpv tries to create this directory automatically.
19056 .TP
19057 .B \fB~/.mpv/\fP
19058 The original (pre 0.5.0) configuration directory. It will continue to be
19059 read if present.
19060 .sp
19061 If both this directory and the standard configuration directory are
19062 present, configuration will be read from both with the standard
19063 configuration directory content taking precedence. However, you should
19064 fully migrate to the standard directory and a warning will be shown in
19065 this situation.
19066 .TP
19067 .B \fB~/.config/mpv/mpv.conf\fP
19068 mpv user settings (see \fI\%CONFIGURATION FILES\fP section)
19069 .TP
19070 .B \fB~/.config/mpv/input.conf\fP
19071 key bindings (see \fI\%INPUT.CONF\fP section)
19072 .TP
19073 .B \fB~/.config/mpv/fonts.conf\fP
19074 Fontconfig fonts.conf that is customized for mpv. You should include system
19075 fonts.conf in this file or mpv would not know about fonts that you already
19076 have in the system.
19077 .sp
19078 Only available when libass is built with fontconfig.
19079 .TP
19080 .B \fB~/.config/mpv/subfont.ttf\fP
19081 fallback subtitle font
19082 .TP
19083 .B \fB~/.config/mpv/fonts/\fP
19084 Font files in this directory are used by mpv/libass for subtitles. Useful
19085 if you do not want to install fonts to your system. Note that files in this
19086 directory are loaded into memory before being used by mpv. If you have a
19087 lot of fonts, consider using fonts.conf (see above) to include additional
19088 fonts, which is more memory\-efficient.
19089 .TP
19090 .B \fB~/.config/mpv/scripts/\fP
19091 All files in this directory are loaded as if they were passed to the
19092 \fB\-\-script\fP option. They are loaded in alphabetical order.
19093 .sp
19094 The \fB\-\-load\-scripts=no\fP option disables loading these files.
19095 .sp
19096 See \fI\%Script location\fP for details.
19097 .TP
19098 .B \fB~/.config/mpv/watch_later/\fP
19099 Contains temporary config files needed for resuming playback of files with
19100 the watch later feature. See for example the \fBQ\fP key binding, or the
19101 \fBquit\-watch\-later\fP input command.
19102 .sp
19103 Each file is a small config file which is loaded if the corresponding media
19104 file is loaded. It contains the playback position and some (not necessarily
19105 all) settings that were changed during playback. The filenames are hashed
19106 from the full paths of the media files. It\(aqs in general not possible to
19107 extract the media filename from this hash. However, you can set the
19108 \fB\-\-write\-filename\-in\-watch\-later\-config\fP option, and the player will
19109 add the media filename to the contents of the resume config file.
19110 .TP
19111 .B \fB~/.config/mpv/script\-opts/osc.conf\fP
19112 This is loaded by the OSC script. See the \fI\%ON SCREEN CONTROLLER\fP docs
19113 for details.
19114 .sp
19115 Other files in this directory are specific to the corresponding scripts
19116 as well, and the mpv core doesn\(aqt touch them.
19117 .UNINDENT
19118 .SH FILES ON WINDOWS
19119 .sp
19120 On win32 (if compiled with MinGW, but not Cygwin), the default config file
19121 locations are different. They are generally located under \fB%APPDATA%/mpv/\fP\&.
19122 For example, the path to mpv.conf is \fB%APPDATA%/mpv/mpv.conf\fP, which maps to
19123 a system and user\-specific path, for example
19124 .INDENT 0.0
19125 .INDENT 3.5
19126 \fBC:\eusers\eUSERNAME\eAppData\eRoaming\empv\empv.conf\fP
19127 .UNINDENT
19128 .UNINDENT
19129 .sp
19130 You can find the exact path by running \fBecho %APPDATA%\empv\empv.conf\fP in cmd.exe.
19131 .sp
19132 Other config files (such as \fBinput.conf\fP) are in the same directory. See the
19133 \fI\%FILES\fP section above.
19134 .sp
19135 The environment variable \fB$MPV_HOME\fP completely overrides these, like on
19136 UNIX.
19137 .sp
19138 If a directory named \fBportable_config\fP next to the mpv.exe exists, all
19139 config will be loaded from this directory only. Watch later config files are
19140 written to this directory as well. (This exists on Windows only and is redundant
19141 with \fB$MPV_HOME\fP\&. However, since Windows is very scripting unfriendly, a
19142 wrapper script just setting \fB$MPV_HOME\fP, like you could do it on other
19143 systems, won\(aqt work. \fBportable_config\fP is provided for convenience to get
19144 around this restriction.)
19145 .sp
19146 Config files located in the same directory as \fBmpv.exe\fP are loaded with
19147 lower priority. Some config files are loaded only once, which means that
19148 e.g. of 2 \fBinput.conf\fP files located in two config directories, only the
19149 one from the directory with higher priority will be loaded.
19150 .sp
19151 A third config directory with the lowest priority is the directory named \fBmpv\fP
19152 in the same directory as \fBmpv.exe\fP\&. This used to be the directory with the
19153 highest priority, but is now discouraged to use and might be removed in the
19154 future.
19155 .sp
19156 Note that mpv likes to mix \fB/\fP and \fB\e\fP path separators for simplicity.
19157 kernel32.dll accepts this, but cmd.exe does not.
19158 .SH COPYRIGHT
19159 GPLv2+
19160 .\" Generated by docutils manpage writer.
19161 .
|
