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 u
179 Switch between applying no style overrides to SSA/ASS subtitles, and
180 overriding them almost completely with the normal subtitle style. See
181 \fB\-\-sub\-ass\-override\fP for more info.
182 .TP
183 .B V
184 Toggle subtitle VSFilter aspect compatibility mode. See
185 \fB\-\-sub\-ass\-vsfilter\-aspect\-compat\fP for more info.
186 .TP
187 .B r and R
188 Move subtitles up/down. The \fBt\fP key does the same as \fBR\fP currently, but
189 use is discouraged.
190 .TP
191 .B s
192 Take a screenshot.
193 .TP
194 .B S
195 Take a screenshot, without subtitles. (Whether this works depends on VO
196 driver support.)
197 .TP
198 .B Ctrl s
199 Take a screenshot, as the window shows it (with subtitles, OSD, and scaled
200 video).
201 .TP
202 .B PGUP and PGDWN
203 Seek to the beginning of the previous/next chapter. In most cases,
204 "previous" will actually go to the beginning of the current chapter; see
205 \fB\-\-chapter\-seek\-threshold\fP\&.
206 .TP
207 .B Shift+PGUP and Shift+PGDWN
208 Seek backward or forward by 10 minutes. (This used to be mapped to
209 PGUP/PGDWN without Shift.)
210 .TP
211 .B d
212 Activate/deactivate deinterlacer.
213 .TP
214 .B A
215 Cycle aspect ratio override.
216 .TP
217 .B Ctrl h
218 Toggle hardware video decoding on/off.
219 .TP
220 .B Alt+LEFT, Alt+RIGHT, Alt+UP, Alt+DOWN
221 Move the video rectangle (panning).
222 .TP
223 .B Alt + and Alt \-
224 Combining \fBAlt\fP with the \fB+\fP or \fB\-\fP keys changes video zoom.
225 .TP
226 .B Alt+BACKSPACE
227 Reset the pan/zoom settings.
228 .TP
229 .B F8
230 Show the playlist and the current position in it (useful only if a UI window
231 is used, broken on the terminal).
232 .TP
233 .B F9
234 Show the list of audio and subtitle streams (useful only if a UI window is
235 used, broken on the terminal).
236 .TP
237 .B i and I
238 Show/toggle an overlay displaying statistics about the currently playing
239 file such as codec, framerate, number of dropped frames and so on. See
240 \fI\%STATS\fP for more information.
241 .UNINDENT
242 .sp
243 (The following keys are valid only when using a video output that supports the
244 corresponding adjustment.)
245 .INDENT 0.0
246 .TP
247 .B 1 and 2
248 Adjust contrast.
249 .TP
250 .B 3 and 4
251 Adjust brightness.
252 .TP
253 .B 5 and 6
254 Adjust gamma.
255 .TP
256 .B 7 and 8
257 Adjust saturation.
258 .TP
259 .B Alt+0 (and command+0 on OSX)
260 Resize video window to half its original size.
261 .TP
262 .B Alt+1 (and command+1 on OSX)
263 Resize video window to its original size.
264 .TP
265 .B Alt+2 (and command+2 on OSX)
266 Resize video window to double its original size.
267 .TP
268 .B command + f (OSX only)
269 Toggle fullscreen (see also \fB\-\-fs\fP).
270 .UNINDENT
271 .sp
272 (The following keys are valid if you have a keyboard with multimedia keys.)
273 .INDENT 0.0
274 .TP
275 .B PAUSE
276 Pause.
277 .TP
278 .B STOP
279 Stop playing and quit.
280 .TP
281 .B PREVIOUS and NEXT
282 Seek backward/forward 1 minute.
283 .UNINDENT
284 .sp
285 If you miss some older key bindings, look at \fBetc/restore\-old\-bindings.conf\fP
286 in the mpv git repository.
287 .SS Mouse Control
288 .INDENT 0.0
289 .TP
290 .B button 3 and button 4
291 Seek backward/forward 1 minute.
292 .TP
293 .B button 5 and button 6
294 Decrease/increase volume.
295 .UNINDENT
296 .SH USAGE
297 .sp
298 Command line arguments starting with \fB\-\fP are interpreted as options,
299 everything else as filenames or URLs. All options except \fIflag\fP options (or
300 choice options which include \fByes\fP) require a parameter in the form
301 \fB\-\-option=value\fP\&.
302 .sp
303 One exception is the lone \fB\-\fP (without anything else), which means media data
304 will be read from stdin. Also, \fB\-\-\fP (without anything else) will make the
305 player interpret all following arguments as filenames, even if they start with
306 \fB\-\fP\&. (To play a file named \fB\-\fP, you need to use \fB\&./\-\fP\&.)
307 .sp
308 Every \fIflag\fP option has a \fIno\-flag\fP counterpart, e.g. the opposite of the
309 \fB\-\-fs\fP option is \fB\-\-no\-fs\fP\&. \fB\-\-fs=yes\fP is same as \fB\-\-fs\fP, \fB\-\-fs=no\fP
310 is the same as \fB\-\-no\-fs\fP\&.
311 .sp
312 If an option is marked as \fI(XXX only)\fP, it will only work in combination with
313 the \fIXXX\fP option or if \fIXXX\fP is compiled in.
314 .SS Legacy option syntax
315 .sp
316 The \fB\-\-option=value\fP syntax is not strictly enforced, and the alternative
317 legacy syntax \fB\-option value\fP and \fB\-\-option value\fP will also work. This is
318 mostly for compatibility with MPlayer. Using these should be avoided. Their
319 semantics can change any time in the future.
320 .sp
321 For example, the alternative syntax will consider an argument following the
322 option a filename. \fBmpv \-fs no\fP will attempt to play a file named \fBno\fP,
323 because \fB\-\-fs\fP is a flag option that requires no parameter. If an option
324 changes and its parameter becomes optional, then a command line using the
325 alternative syntax will break.
326 .sp
327 Currently, the parser makes no difference whether an option starts with \fB\-\-\fP
328 or a single \fB\-\fP\&. This might also change in the future, and \fB\-\-option value\fP
329 might always interpret \fBvalue\fP as filename in order to reduce ambiguities.
330 .SS Escaping spaces and other special characters
331 .sp
332 Keep in mind that the shell will partially parse and mangle the arguments you
333 pass to mpv. For example, you might need to quote or escape options and
334 filenames:
335 .INDENT 0.0
336 .INDENT 3.5
337 \fBmpv "filename with spaces.mkv" \-\-title="window title"\fP
338 .UNINDENT
339 .UNINDENT
340 .sp
341 It gets more complicated if the suboption parser is involved. The suboption
342 parser puts several options into a single string, and passes them to a
343 component at once, instead of using multiple options on the level of the
344 command line.
345 .sp
346 The suboption parser can quote strings with \fB"\fP and \fB[...]\fP\&.
347 Additionally, there is a special form of quoting with \fB%n%\fP described below.
348 .sp
349 For example, assume the hypothetical \fBfoo\fP filter can take multiple options:
350 .INDENT 0.0
351 .INDENT 3.5
352 \fBmpv test.mkv \-\-vf=foo:option1=value1:option2:option3=value3,bar\fP
353 .UNINDENT
354 .UNINDENT
355 .sp
356 This passes \fBoption1\fP and \fBoption3\fP to the \fBfoo\fP filter, with \fBoption2\fP
357 as flag (implicitly \fBoption2=yes\fP), and adds a \fBbar\fP filter after that. If
358 an option contains spaces or characters like \fB,\fP or \fB:\fP, you need to quote
359 them:
360 .INDENT 0.0
361 .INDENT 3.5
362 \fBmpv \(aq\-\-vf=foo:option1="option value with spaces",bar\(aq\fP
363 .UNINDENT
364 .UNINDENT
365 .sp
366 Shells may actually strip some quotes from the string passed to the commandline,
367 so the example quotes the string twice, ensuring that mpv receives the \fB"\fP
368 quotes.
369 .sp
370 The \fB[...]\fP form of quotes wraps everything between \fB[\fP and \fB]\fP\&. It\(aqs
371 useful with shells that don\(aqt interpret these characters in the middle of
372 an argument (like bash). These quotes are balanced (since mpv 0.9.0): the \fB[\fP
373 and \fB]\fP nest, and the quote terminates on the last \fB]\fP that has no matching
374 \fB[\fP within the string. (For example, \fB[a[b]c]\fP results in \fBa[b]c\fP\&.)
375 .sp
376 The fixed\-length quoting syntax is intended for use with external
377 scripts and programs.
378 .sp
379 It is started with \fB%\fP and has the following format:
380 .INDENT 0.0
381 .INDENT 3.5
382 .sp
383 .nf
384 .ft C
385 %n%string_of_length_n
386 .ft P
387 .fi
388 .UNINDENT
389 .UNINDENT
390 .INDENT 0.0
391 .INDENT 3.5
392 .IP "Examples"
393 .sp
394 \fBmpv \(aq\-\-vf=foo:option1=%11%quoted text\(aq test.avi\fP
395 .sp
396 Or in a script:
397 .sp
398 \fBmpv \-\-vf=foo:option1=%\(gaexpr length "$NAME"\(ga%"$NAME" test.avi\fP
399 .UNINDENT
400 .UNINDENT
401 .sp
402 Suboptions passed to the client API are also subject to escaping. Using
403 \fBmpv_set_option_string()\fP is exactly like passing \fB\-\-name=data\fP to the
404 command line (but without shell processing of the string). Some options
405 support passing values in a more structured way instead of flat strings, and
406 can avoid the suboption parsing mess. For example, \fB\-\-vf\fP supports
407 \fBMPV_FORMAT_NODE\fP, which lets you pass suboptions as a nested data structure
408 of maps and arrays.
409 .SS Paths
410 .sp
411 Some care must be taken when passing arbitrary paths and filenames to mpv. For
412 example, paths starting with \fB\-\fP will be interpreted as options. Likewise,
413 if a path contains the sequence \fB://\fP, the string before that might be
414 interpreted as protocol prefix, even though \fB://\fP can be part of a legal
415 UNIX path. To avoid problems with arbitrary paths, you should be sure that
416 absolute paths passed to mpv start with \fB/\fP, and prefix relative paths with
417 \fB\&./\fP\&.
418 .sp
419 Using the \fBfile://\fP pseudo\-protocol is discouraged, because it involves
420 strange URL unescaping rules.
421 .sp
422 The name \fB\-\fP itself is interpreted as stdin, and will cause mpv to disable
423 console controls. (Which makes it suitable for playing data piped to stdin.)
424 .sp
425 The special argument \fB\-\-\fP can be used to stop mpv from interpreting the
426 following arguments as options.
427 .sp
428 When using the client API, you should strictly avoid using \fBmpv_command_string\fP
429 for invoking the \fBloadfile\fP command, and instead prefer e.g. \fBmpv_command\fP
430 to avoid the need for filename escaping.
431 .sp
432 For paths passed to suboptions, the situation is further complicated by the
433 need to escape special characters. To work this around, the path can be
434 additionally wrapped in the fixed\-length syntax, e.g. \fB%n%string_of_length_n\fP
435 (see above).
436 .sp
437 Some mpv options interpret paths starting with \fB~\fP\&. Currently, the prefix
438 \fB~~/\fP expands to the mpv configuration directory (usually \fB~/.config/mpv/\fP).
439 \fB~/\fP expands to the user\(aqs home directory. (The trailing \fB/\fP is always
440 required.) There are the following paths as well:
441 .TS
442 center;
443 |l|l|.
444 _
445 T{
446 Name
447 T} T{
448 Meaning
449 T}
450 _
451 T{
452 \fB~~home/\fP
453 T} T{
454 same as \fB~~/\fP
455 T}
456 _
457 T{
458 \fB~~global/\fP
459 T} T{
460 the global config path, if available (not on win32)
461 T}
462 _
463 T{
464 \fB~~osxbundle/\fP
465 T} T{
466 the OSX bundle resource path (OSX only)
467 T}
468 _
469 T{
470 \fB~~desktop/\fP
471 T} T{
472 the path to the desktop (win32, OSX)
473 T}
474 _
475 .TE
476 .SS Per\-File Options
477 .sp
478 When playing multiple files, any option given on the command line usually
479 affects all files. Example:
480 .INDENT 0.0
481 .INDENT 3.5
482 .sp
483 .nf
484 .ft C
485 mpv \-\-a file1.mkv \-\-b file2.mkv \-\-c
486 .ft P
487 .fi
488 .UNINDENT
489 .UNINDENT
490 .TS
491 center;
492 |l|l|.
493 _
494 T{
495 File
496 T} T{
497 Active options
498 T}
499 _
500 T{
501 file1.mkv
502 T} T{
503 \fB\-\-a \-\-b \-\-c\fP
504 T}
505 _
506 T{
507 file2.mkv
508 T} T{
509 \fB\-\-a \-\-b \-\-c\fP
510 T}
511 _
512 .TE
513 .sp
514 (This is different from MPlayer and mplayer2.)
515 .sp
516 Also, if any option is changed at runtime (via input commands), they are not
517 reset when a new file is played.
518 .sp
519 Sometimes, it is useful to change options per\-file. This can be achieved by
520 adding the special per\-file markers \fB\-\-{\fP and \fB\-\-}\fP\&. (Note that you must
521 escape these on some shells.) Example:
522 .INDENT 0.0
523 .INDENT 3.5
524 .sp
525 .nf
526 .ft C
527 mpv \-\-a file1.mkv \-\-b \-\-\e{ \-\-c file2.mkv \-\-d file3.mkv \-\-e \-\-\e} file4.mkv \-\-f
528 .ft P
529 .fi
530 .UNINDENT
531 .UNINDENT
532 .TS
533 center;
534 |l|l|.
535 _
536 T{
537 File
538 T} T{
539 Active options
540 T}
541 _
542 T{
543 file1.mkv
544 T} T{
545 \fB\-\-a \-\-b \-\-f\fP
546 T}
547 _
548 T{
549 file2.mkv
550 T} T{
551 \fB\-\-a \-\-b \-\-f \-\-c \-\-d \-\-e\fP
552 T}
553 _
554 T{
555 file3.mkv
556 T} T{
557 \fB\-\-a \-\-b \-\-f \-\-c \-\-d \-\-e\fP
558 T}
559 _
560 T{
561 file4.mkv
562 T} T{
563 \fB\-\-a \-\-b \-\-f\fP
564 T}
565 _
566 .TE
567 .sp
568 Additionally, any file\-local option changed at runtime is reset when the current
569 file stops playing. If option \fB\-\-c\fP is changed during playback of
570 \fBfile2.mkv\fP, it is reset when advancing to \fBfile3.mkv\fP\&. This only affects
571 file\-local options. The option \fB\-\-a\fP is never reset here.
572 .SS List Options
573 .sp
574 Some options which store lists of option values can have action suffixes. For
575 example, you can set a \fB,\fP\-separated list of filters with \fB\-\-vf\fP, but the
576 option also allows you to append filters with \fB\-\-vf\-append\fP\&.
577 .sp
578 Options for filenames do not use \fB,\fP as separator, but \fB:\fP (Unix) or \fB;\fP
579 (Windows).
580 .TS
581 center;
582 |l|l|.
583 _
584 T{
585 Suffix
586 T} T{
587 Meaning
588 T}
589 _
590 T{
591 \-add
592 T} T{
593 Append 1 or more items (may become alias for \-append)
594 T}
595 _
596 T{
597 \-append
598 T} T{
599 Append single item (avoids need for escaping)
600 T}
601 _
602 T{
603 \-clr
604 T} T{
605 Clear the option
606 T}
607 _
608 T{
609 \-del
610 T} T{
611 Delete an existing item by integer index
612 T}
613 _
614 T{
615 \-pre
616 T} T{
617 Prepend 1 or more items
618 T}
619 _
620 T{
621 \-set
622 T} T{
623 Set a list of items
624 T}
625 _
626 T{
627 \-toggle
628 T} T{
629 Append an item, or remove if if it already exists
630 T}
631 _
632 .TE
633 .sp
634 Although some operations allow specifying multiple \fB,\fP\-separated items, using
635 this is strongly discouraged and deprecated, except for \fB\-set\fP\&.
636 .sp
637 Without suffix, the action taken is normally \fB\-set\fP\&.
638 .sp
639 Some options (like \fB\-\-sub\-file\fP, \fB\-\-audio\-file\fP, \fB\-\-glsl\-shader\fP) are
640 aliases for the proper option with \fB\-append\fP action. For example,
641 \fB\-\-sub\-file\fP is an alias for \fB\-\-sub\-files\-append\fP\&.
642 .sp
643 Some options only support a subset of the above.
644 .sp
645 Options of this type can be changed at runtime using the \fBchange\-list\fP
646 command, which takes the suffix as separate operation parameter.
647 .SS Playing DVDs
648 .sp
649 DVDs can be played with the \fBdvd://[title]\fP syntax. The optional
650 title specifier is a number which selects between separate video
651 streams on the DVD. If no title is given (\fBdvd://\fP) then the longest
652 title is selected automatically by the library. This is usually what
653 you want. mpv does not support DVD menus.
654 .sp
655 DVDs which have been copied on to a hard drive or other mounted
656 filesystem (by e.g. the \fBdvdbackup\fP tool) are accommodated by
657 specifying the path to the local copy: \fB\-\-dvd\-device=PATH\fP\&.
658 Alternatively, running \fBmpv PATH\fP should auto\-detect a DVD directory
659 tree and play the longest title.
660 .sp
661 \fBNOTE:\fP
662 .INDENT 0.0
663 .INDENT 3.5
664 DVD subtitles
665 .sp
666 DVDs use image\-based subtitles. Image subtitles are implemented as
667 a bitmap video stream which can be superimposed over the main
668 movie. mpv\(aqs subtitle styling and positioning options and keyboard
669 shortcuts generally do not work with image\-based subtitles.
670 Exceptions include options like \fB\-\-stretch\-dvd\-subs\fP and
671 \fB\-\-stretch\-image\-subs\-to\-screen\fP\&.
672 .UNINDENT
673 .UNINDENT
674 .SH CONFIGURATION FILES
675 .SS Location and Syntax
676 .sp
677 You can put all of the options in configuration files which will be read every
678 time mpv is run. The system\-wide configuration file \(aqmpv.conf\(aq is in your
679 configuration directory (e.g. \fB/etc/mpv\fP or \fB/usr/local/etc/mpv\fP), the
680 user\-specific one is \fB~/.config/mpv/mpv.conf\fP\&. For details and platform
681 specifics (in particular Windows paths) see the \fI\%FILES\fP section.
682 .sp
683 User\-specific options override system\-wide options and options given on the
684 command line override either. The syntax of the configuration files is
685 \fBoption=value\fP\&. Everything after a \fI#\fP is considered a comment. Options
686 that work without values can be enabled by setting them to \fIyes\fP and disabled by
687 setting them to \fIno\fP\&. Even suboptions can be specified in this way.
688 .INDENT 0.0
689 .INDENT 3.5
690 .IP "Example configuration file"
691 .INDENT 0.0
692 .INDENT 3.5
693 .sp
694 .nf
695 .ft C
696 # Use GPU\-accelerated video output by default.
697 vo=gpu
698 # Use quotes for text that can contain spaces:
699 status\-msg="Time: ${time\-pos}"
700 .ft P
701 .fi
702 .UNINDENT
703 .UNINDENT
704 .UNINDENT
705 .UNINDENT
706 .SS Escaping spaces and special characters
707 .sp
708 This is done like with command line options. The shell is not involved here,
709 but option values still need to be quoted as a whole if it contains certain
710 characters like spaces. A config entry can be quoted with \fB"\fP,
711 as well as with the fixed\-length syntax (\fB%n%\fP) mentioned before. This is like
712 passing the exact contents of the quoted string as command line option. C\-style
713 escapes are currently _not_ interpreted on this level, although some options do
714 this manually. (This is a mess and should probably be changed at some point.)
715 .SS Putting Command Line Options into the Configuration File
716 .sp
717 Almost all command line options can be put into the configuration file. Here
718 is a small guide:
719 .TS
720 center;
721 |l|l|.
722 _
723 T{
724 Option
725 T} T{
726 Configuration file entry
727 T}
728 _
729 T{
730 \fB\-\-flag\fP
731 T} T{
732 \fBflag\fP
733 T}
734 _
735 T{
736 \fB\-opt val\fP
737 T} T{
738 \fBopt=val\fP
739 T}
740 _
741 T{
742 \fB\-\-opt=val\fP
743 T} T{
744 \fBopt=val\fP
745 T}
746 _
747 T{
748 \fB\-opt "has spaces"\fP
749 T} T{
750 \fBopt="has spaces"\fP
751 T}
752 _
753 .TE
754 .SS File\-specific Configuration Files
755 .sp
756 You can also write file\-specific configuration files. If you wish to have a
757 configuration file for a file called \(aqvideo.avi\(aq, create a file named
758 \(aqvideo.avi.conf\(aq with the file\-specific options in it and put it in
759 \fB~/.config/mpv/\fP\&. You can also put the configuration file in the same directory
760 as the file to be played. Both require you to set the \fB\-\-use\-filedir\-conf\fP
761 option (either on the command line or in your global config file). If a
762 file\-specific configuration file is found in the same directory, no
763 file\-specific configuration is loaded from \fB~/.config/mpv\fP\&. In addition, the
764 \fB\-\-use\-filedir\-conf\fP option enables directory\-specific configuration files.
765 For this, mpv first tries to load a mpv.conf from the same directory
766 as the file played and then tries to load any file\-specific configuration.
767 .SS Profiles
768 .sp
769 To ease working with different configurations, profiles can be defined in the
770 configuration files. A profile starts with its name in square brackets,
771 e.g. \fB[my\-profile]\fP\&. All following options will be part of the profile. A
772 description (shown by \fB\-\-profile=help\fP) can be defined with the
773 \fBprofile\-desc\fP option. To end the profile, start another one or use the
774 profile name \fBdefault\fP to continue with normal options.
775 .sp
776 You can list profiles with \fB\-\-profile=help\fP, and show the contents of a
777 profile with \fB\-\-show\-profile=<name>\fP (replace \fB<name>\fP with the profile
778 name). You can apply profiles on start with the \fB\-\-profile=<name>\fP option,
779 or at runtime with the \fBapply\-profile <name>\fP command.
780 .INDENT 0.0
781 .INDENT 3.5
782 .IP "Example mpv config file with profiles"
783 .INDENT 0.0
784 .INDENT 3.5
785 .sp
786 .nf
787 .ft C
788 # normal top\-level option
789 fullscreen=yes
790
791 # a profile that can be enabled with \-\-profile=big\-cache
792 [big\-cache]
793 cache=yes
794 demuxer\-max\-bytes=123400KiB
795 demuxer\-readahead\-secs=20
796
797 [slow]
798 profile\-desc="some profile name"
799 # reference a builtin profile
800 profile=gpu\-hq
801
802 [fast]
803 vo=vdpau
804
805 # using a profile again extends it
806 [slow]
807 framedrop=no
808 # you can also include other profiles
809 profile=big\-cache
810 .ft P
811 .fi
812 .UNINDENT
813 .UNINDENT
814 .UNINDENT
815 .UNINDENT
816 .SS Auto profiles
817 .sp
818 Some profiles are loaded automatically. The following example demonstrates this:
819 .INDENT 0.0
820 .INDENT 3.5
821 .IP "Auto profile loading"
822 .INDENT 0.0
823 .INDENT 3.5
824 .sp
825 .nf
826 .ft C
827 [protocol.dvd]
828 profile\-desc="profile for dvd:// streams"
829 alang=en
830
831 [extension.flv]
832 profile\-desc="profile for .flv files"
833 vf=flip
834 .ft P
835 .fi
836 .UNINDENT
837 .UNINDENT
838 .UNINDENT
839 .UNINDENT
840 .sp
841 The profile name follows the schema \fBtype.name\fP, where type can be
842 \fBprotocol\fP for the input/output protocol in use (see \fB\-\-list\-protocols\fP),
843 and \fBextension\fP for the extension of the path of the currently played file
844 (\fInot\fP the file format).
845 .sp
846 This feature is very limited, and there are no other auto profiles.
847 .SH TAKING SCREENSHOTS
848 .sp
849 Screenshots of the currently played file can be taken using the \(aqscreenshot\(aq
850 input mode command, which is by default bound to the \fBs\fP key. Files named
851 \fBmpv\-shotNNNN.jpg\fP will be saved in the working directory, using the first
852 available number \- no files will be overwritten. In pseudo\-GUI mode, the
853 screenshot will be saved somewhere else. See \fI\%PSEUDO GUI MODE\fP\&.
854 .sp
855 A screenshot will usually contain the unscaled video contents at the end of the
856 video filter chain and subtitles. By default, \fBS\fP takes screenshots without
857 subtitles, while \fBs\fP includes subtitles.
858 .sp
859 Unlike with MPlayer, the \fBscreenshot\fP video filter is not required. This
860 filter was never required in mpv, and has been removed.
861 .SH TERMINAL STATUS LINE
862 .sp
863 During playback, mpv shows the playback status on the terminal. It looks like
864 something like this:
865 .INDENT 0.0
866 .INDENT 3.5
867 \fBAV: 00:03:12 / 00:24:25 (13%) A\-V: \-0.000\fP
868 .UNINDENT
869 .UNINDENT
870 .sp
871 The status line can be overridden with the \fB\-\-term\-status\-msg\fP option.
872 .sp
873 The following is a list of things that can show up in the status line. Input
874 properties, that can be used to get the same information manually, are also
875 listed.
876 .INDENT 0.0
877 .IP \(bu 2
878 \fBAV:\fP or \fBV:\fP (video only) or \fBA:\fP (audio only)
879 .IP \(bu 2
880 The current time position in \fBHH:MM:SS\fP format (\fBplayback\-time\fP property)
881 .IP \(bu 2
882 The total file duration (absent if unknown) (\fBlength\fP property)
883 .IP \(bu 2
884 Playback speed, e.g. \(ga\(ga x2.0\(ga\(ga. Only visible if the speed is not normal. This
885 is the user\-requested speed, and not the actual speed (usually they should
886 be the same, unless playback is too slow). (\fBspeed\fP property.)
887 .IP \(bu 2
888 Playback percentage, e.g. \fB(13%)\fP\&. How much of the file has been played.
889 Normally calculated out of playback position and duration, but can fallback
890 to other methods (like byte position) if these are not available.
891 (\fBpercent\-pos\fP property.)
892 .IP \(bu 2
893 The audio/video sync as \fBA\-V: 0.000\fP\&. This is the difference between
894 audio and video time. Normally it should be 0 or close to 0. If it\(aqs growing,
895 it might indicate a playback problem. (\fBavsync\fP property.)
896 .IP \(bu 2
897 Total A/V sync change, e.g. \fBct: \-0.417\fP\&. Normally invisible. Can show up
898 if there is audio "missing", or not enough frames can be dropped. Usually
899 this will indicate a problem. (\fBtotal\-avsync\-change\fP property.)
900 .IP \(bu 2
901 Encoding state in \fB{...}\fP, only shown in encoding mode.
902 .IP \(bu 2
903 Display sync state. If display sync is active (\fBdisplay\-sync\-active\fP
904 property), this shows \fBDS: 2.500/13\fP, where the first number is average
905 number of vsyncs per video frame (e.g. 2.5 when playing 24Hz videos on 60Hz
906 screens), which might jitter if the ratio doesn\(aqt round off, or there are
907 mistimed frames (\fBvsync\-ratio\fP), and the second number of estimated number
908 of vsyncs which took too long (\fBvo\-delayed\-frame\-count\fP property). The
909 latter is a heuristic, as it\(aqs generally not possible to determine this with
910 certainty.
911 .IP \(bu 2
912 Dropped frames, e.g. \fBDropped: 4\fP\&. Shows up only if the count is not 0. Can
913 grow if the video framerate is higher than that of the display, or if video
914 rendering is too slow. May also be incremented on "hiccups" and when the video
915 frame couldn\(aqt be displayed on time. (\fBvo\-drop\-frame\-count\fP property.)
916 If the decoder drops frames, the number of decoder\-dropped frames is appended
917 to the display as well, e.g.: \fBDropped: 4/34\fP\&. This happens only if
918 decoder frame dropping is enabled with the \fB\-\-framedrop\fP options.
919 (\fBdrop\-frame\-count\fP property.)
920 .IP \(bu 2
921 Cache state, e.g. \fBCache: 2s/134KB\fP\&. Visible if the stream cache is enabled.
922 The first value shows the amount of video buffered in the demuxer in seconds,
923 the second value shows the estimated size of the buffered amount in kilobytes.
924 (\fBdemuxer\-cache\-duration\fP and \fBdemuxer\-cache\-state\fP properties.)
925 .UNINDENT
926 .SH LOW LATENCY PLAYBACK
927 .sp
928 mpv is optimized for normal video playback, meaning it actually tries to buffer
929 as much data as it seems to make sense. This will increase latency. Reducing
930 latency is possible only by specifically disabling features which increase
931 latency.
932 .sp
933 The builtin \fBlow\-latency\fP profile tries to apply some of the options which can
934 reduce latency. You can use \fB\-\-profile=low\-latency\fP to apply all of them. You
935 can list the contents with \fB\-\-show\-profile=low\-latency\fP (some of the options
936 are quite obscure, and may change every mpv release).
937 .sp
938 Be aware that some of the options can reduce playback quality.
939 .sp
940 Most latency is actually caused by inconvenient timing behavior. You can disable
941 this with \fB\-\-untimed\fP, but it will likely break, unless the stream has no
942 audio, and the input feeds data to the player at a constant rate.
943 .sp
944 Another common problem is with MJPEG streams. These do not signal the correct
945 framerate. Using \fB\-\-untimed\fP or \fB\-\-no\-correct\-pts \-\-fps=60\fP might help.
946 .sp
947 For livestreams, data can build up due to pausing the stream, due to slightly
948 lower playback rate, or "buffering" pauses. If the demuxer cache is enabled,
949 these can be skipped manually. The experimental \fBdrop\-buffers\fP command can
950 be used to discard any buffered data, though it\(aqs very disruptive.
951 .sp
952 In some cases, manually tuning TCP buffer sizes and such can help to reduce
953 latency.
954 .sp
955 Additional options that can be tried:
956 .INDENT 0.0
957 .IP \(bu 2
958 \fB\-\-opengl\-glfinish=yes\fP, can reduce buffering in the graphics driver
959 .IP \(bu 2
960 \fB\-\-opengl\-swapinterval=0\fP, same
961 .IP \(bu 2
962 \fB\-\-vo=xv\fP, same
963 .IP \(bu 2
964 without audio \fB\-\-framedrop=no \-\-speed=1.01\fP may help for live sources
965 (results can be mixed)
966 .UNINDENT
967 .SH PROTOCOLS
968 .sp
969 \fBhttp://...\fP, \fBhttps://\fP, ...
970 .INDENT 0.0
971 .INDENT 3.5
972 Many network protocols are supported, but the protocol prefix must always
973 be specified. mpv will never attempt to guess whether a filename is
974 actually a network address. A protocol prefix is always required.
975 .sp
976 Note that not all prefixes are documented here. Undocumented prefixes are
977 either aliases to documented protocols, or are just redirections to
978 protocols implemented and documented in FFmpeg.
979 .sp
980 \fBdata:\fP is supported in FFmpeg (not in Libav), but needs to be in the
981 format \fBdata://\fP\&. This is done to avoid ambiguity with filenames. You
982 can also prefix it with \fBlavf://\fP or \fBffmpeg://\fP\&.
983 .UNINDENT
984 .UNINDENT
985 .sp
986 \fBytdl://...\fP
987 .INDENT 0.0
988 .INDENT 3.5
989 By default, the youtube\-dl hook script (enabled by default for mpv CLI)
990 only looks at http URLs. Prefixing an URL with \fBytdl://\fP forces it to
991 be always processed by the script. This can also be used to invoke special
992 youtube\-dl functionality like playing a video by ID or invoking search.
993 .sp
994 Keep in mind that you can\(aqt pass youtube\-dl command line options by this,
995 and you have to use \fB\-\-ytdl\-raw\-options\fP instead.
996 .UNINDENT
997 .UNINDENT
998 .sp
999 \fB\-\fP
1000 .INDENT 0.0
1001 .INDENT 3.5
1002 Play data from stdin.
1003 .UNINDENT
1004 .UNINDENT
1005 .sp
1006 \fBsmb://PATH\fP
1007 .INDENT 0.0
1008 .INDENT 3.5
1009 Play a path from Samba share.
1010 .UNINDENT
1011 .UNINDENT
1012 .sp
1013 \fBbd://[title][/device]\fP \fB\-\-bluray\-device=PATH\fP
1014 .INDENT 0.0
1015 .INDENT 3.5
1016 Play a Blu\-ray disc. Since libbluray 1.0.1, you can read from ISO files
1017 by passing them to \fB\-\-bluray\-device\fP\&.
1018 .sp
1019 \fBtitle\fP can be: \fBlongest\fP or \fBfirst\fP (selects the default
1020 playlist); \fBmpls/<number>\fP (selects <number>.mpls playlist);
1021 \fB<number>\fP (select playlist with the same index). mpv will list
1022 the available playlists on loading.
1023 .sp
1024 \fBbluray://\fP is an alias.
1025 .UNINDENT
1026 .UNINDENT
1027 .sp
1028 \fBdvd://[title|[starttitle]\-endtitle][/device]\fP \fB\-\-dvd\-device=PATH\fP
1029 .INDENT 0.0
1030 .INDENT 3.5
1031 Play a DVD. DVD menus are not supported. If no title is given, the longest
1032 title is auto\-selected.
1033 .sp
1034 \fBdvdnav://\fP is an old alias for \fBdvd://\fP and does exactly the same
1035 thing.
1036 .UNINDENT
1037 .UNINDENT
1038 .sp
1039 \fBdvdread://...:\fP
1040 .INDENT 0.0
1041 .INDENT 3.5
1042 Play a DVD using the old libdvdread code. This is what MPlayer and
1043 older mpv versions used for \fBdvd://\fP\&. Use is discouraged. It\(aqs
1044 provided only for compatibility and for transition, and to work
1045 around outstanding dvdnav bugs (see "DVD library choices" above).
1046 .UNINDENT
1047 .UNINDENT
1048 .sp
1049 \fBtv://[channel][/input_id]\fP \fB\-\-tv\-...\fP
1050 .INDENT 0.0
1051 .INDENT 3.5
1052 Analogue TV via V4L. Also useful for webcams. (Linux only.)
1053 .UNINDENT
1054 .UNINDENT
1055 .sp
1056 \fBpvr://\fP \fB\-\-pvr\-...\fP
1057 .INDENT 0.0
1058 .INDENT 3.5
1059 PVR. (Linux only.)
1060 .UNINDENT
1061 .UNINDENT
1062 .sp
1063 \fBdvb://[cardnumber@]channel\fP \fB\-\-dvbin\-...\fP
1064 .INDENT 0.0
1065 .INDENT 3.5
1066 Digital TV via DVB. (Linux only.)
1067 .UNINDENT
1068 .UNINDENT
1069 .sp
1070 \fBmf://[filemask|@listfile]\fP \fB\-\-mf\-...\fP
1071 .INDENT 0.0
1072 .INDENT 3.5
1073 Play a series of images as video.
1074 .UNINDENT
1075 .UNINDENT
1076 .sp
1077 \fBcdda://[device]\fP \fB\-\-cdrom\-device=PATH\fP \fB\-\-cdda\-...\fP
1078 .INDENT 0.0
1079 .INDENT 3.5
1080 Play CD.
1081 .UNINDENT
1082 .UNINDENT
1083 .sp
1084 \fBlavf://...\fP
1085 .INDENT 0.0
1086 .INDENT 3.5
1087 Access any FFmpeg/Libav libavformat protocol. Basically, this passed the
1088 string after the \fB//\fP directly to libavformat.
1089 .UNINDENT
1090 .UNINDENT
1091 .sp
1092 \fBav://type:options\fP
1093 .INDENT 0.0
1094 .INDENT 3.5
1095 This is intended for using libavdevice inputs. \fBtype\fP is the libavdevice
1096 demuxer name, and \fBoptions\fP is the (pseudo\-)filename passed to the
1097 demuxer.
1098 .sp
1099 For example, \fBmpv av://lavfi:mandelbrot\fP makes use of the libavfilter
1100 wrapper included in libavdevice, and will use the \fBmandelbrot\fP source
1101 filter to generate input data.
1102 .sp
1103 \fBavdevice://\fP is an alias.
1104 .UNINDENT
1105 .UNINDENT
1106 .sp
1107 \fBfile://PATH\fP
1108 .INDENT 0.0
1109 .INDENT 3.5
1110 A local path as URL. Might be useful in some special use\-cases. Note that
1111 \fBPATH\fP itself should start with a third \fB/\fP to make the path an
1112 absolute path.
1113 .UNINDENT
1114 .UNINDENT
1115 .sp
1116 \fBappending://PATH\fP
1117 .INDENT 0.0
1118 .INDENT 3.5
1119 Play a local file, but assume it\(aqs being appended to. This is useful for
1120 example for files that are currently being downloaded to disk. This will
1121 block playback, and stop playback only if no new data was appended after
1122 a timeout of about 2 seconds.
1123 .sp
1124 Using this is still a bit of a bad idea, because there is no way to detect
1125 if a file is actually being appended, or if it\(aqs still written. If you\(aqre
1126 trying to play the output of some program, consider using a pipe
1127 (\fBsomething | mpv \-\fP). If it really has to be a file on disk, use tail to
1128 make it wait forever, e.g. \fBtail \-f \-c +0 file.mkv | mpv \-\fP\&.
1129 .UNINDENT
1130 .UNINDENT
1131 .sp
1132 \fBfd://123\fP
1133 .INDENT 0.0
1134 .INDENT 3.5
1135 Read data from the given file descriptor (for example 123). This is similar
1136 to piping data to stdin via \fB\-\fP, but can use an arbitrary file descriptor.
1137 mpv may modify some file descriptor properties when the stream layer "opens"
1138 it.
1139 .UNINDENT
1140 .UNINDENT
1141 .sp
1142 \fBfdclose://123\fP
1143 .INDENT 0.0
1144 .INDENT 3.5
1145 Like \fBfd://\fP, but the file descriptor is closed after use. When using this
1146 you need to ensure that the same fd URL will only be used once.
1147 .UNINDENT
1148 .UNINDENT
1149 .sp
1150 \fBedl://[edl specification as in edl\-mpv.rst]\fP
1151 .INDENT 0.0
1152 .INDENT 3.5
1153 Stitch together parts of multiple files and play them.
1154 .UNINDENT
1155 .UNINDENT
1156 .sp
1157 \fBnull://\fP
1158 .INDENT 0.0
1159 .INDENT 3.5
1160 Simulate an empty file. If opened for writing, it will discard all data.
1161 The \fBnull\fP demuxer will specifically pass autoprobing if this protocol
1162 is used (while it\(aqs not automatically invoked for empty files).
1163 .UNINDENT
1164 .UNINDENT
1165 .sp
1166 \fBmemory://data\fP
1167 .INDENT 0.0
1168 .INDENT 3.5
1169 Use the \fBdata\fP part as source data.
1170 .UNINDENT
1171 .UNINDENT
1172 .sp
1173 \fBhex://data\fP
1174 .INDENT 0.0
1175 .INDENT 3.5
1176 Like \fBmemory://\fP, but the string is interpreted as hexdump.
1177 .UNINDENT
1178 .UNINDENT
1179 .SH PSEUDO GUI MODE
1180 .sp
1181 mpv has no official GUI, other than the OSC (\fI\%ON SCREEN CONTROLLER\fP), which
1182 is not a full GUI and is not meant to be. However, to compensate for the lack
1183 of expected GUI behavior, mpv will in some cases start with some settings
1184 changed to behave slightly more like a GUI mode.
1185 .sp
1186 Currently this happens only in the following cases:
1187 .INDENT 0.0
1188 .IP \(bu 2
1189 if started using the \fBmpv.desktop\fP file on Linux (e.g. started from menus
1190 or file associations provided by desktop environments)
1191 .IP \(bu 2
1192 if started from explorer.exe on Windows (technically, if it was started on
1193 Windows, and all of the stdout/stderr/stdin handles are unset)
1194 .IP \(bu 2
1195 started out of the bundle on OSX
1196 .IP \(bu 2
1197 if you manually use \fB\-\-player\-operation\-mode=pseudo\-gui\fP on the command line
1198 .UNINDENT
1199 .sp
1200 This mode applies options from the builtin profile \fBbuiltin\-pseudo\-gui\fP, but
1201 only if these haven\(aqt been set in the user\(aqs config file or on the command line.
1202 Also, for compatibility with the old pseudo\-gui behavior, the options in the
1203 \fBpseudo\-gui\fP profile are applied unconditionally. In addition, the profile
1204 makes sure to enable the pseudo\-GUI mode, so that \fB\-\-profile=pseudo\-gui\fP
1205 works like in older mpv releases. The profiles are currently defined as follows:
1206 .INDENT 0.0
1207 .INDENT 3.5
1208 .sp
1209 .nf
1210 .ft C
1211 [builtin\-pseudo\-gui]
1212 terminal=no
1213 force\-window=yes
1214 idle=once
1215 screenshot\-directory=~~desktop/
1216 [pseudo\-gui]
1217 player\-operation\-mode=pseudo\-gui
1218 .ft P
1219 .fi
1220 .UNINDENT
1221 .UNINDENT
1222 .sp
1223 \fBWARNING:\fP
1224 .INDENT 0.0
1225 .INDENT 3.5
1226 Currently, you can extend the \fBpseudo\-gui\fP profile in the config file the
1227 normal way. This is deprecated. In future mpv releases, the behavior might
1228 change, and not apply your additional settings, and/or use a different
1229 profile name.
1230 .UNINDENT
1231 .UNINDENT
1232 .SH OPTIONS
1233 .SS Track Selection
1234 .INDENT 0.0
1235 .TP
1236 .B \fB\-\-alang=<languagecode[,languagecode,...]>\fP
1237 Specify a priority list of audio languages to use. Different container
1238 formats employ different language codes. DVDs use ISO 639\-1 two\-letter
1239 language codes, Matroska, MPEG\-TS and NUT use ISO 639\-2 three\-letter
1240 language codes, while OGM uses a free\-form identifier. See also \fB\-\-aid\fP\&.
1241 .INDENT 7.0
1242 .INDENT 3.5
1243 .IP "Examples"
1244 .INDENT 0.0
1245 .IP \(bu 2
1246 \fBmpv dvd://1 \-\-alang=hu,en\fP chooses the Hungarian language track
1247 on a DVD and falls back on English if Hungarian is not available.
1248 .IP \(bu 2
1249 \fBmpv \-\-alang=jpn example.mkv\fP plays a Matroska file with Japanese
1250 audio.
1251 .UNINDENT
1252 .UNINDENT
1253 .UNINDENT
1254 .TP
1255 .B \fB\-\-slang=<languagecode[,languagecode,...]>\fP
1256 Specify a priority list of subtitle languages to use. Different container
1257 formats employ different language codes. DVDs use ISO 639\-1 two letter
1258 language codes, Matroska uses ISO 639\-2 three letter language codes while
1259 OGM uses a free\-form identifier. See also \fB\-\-sid\fP\&.
1260 .INDENT 7.0
1261 .INDENT 3.5
1262 .IP "Examples"
1263 .INDENT 0.0
1264 .IP \(bu 2
1265 \fBmpv dvd://1 \-\-slang=hu,en\fP chooses the Hungarian subtitle track on
1266 a DVD and falls back on English if Hungarian is not available.
1267 .IP \(bu 2
1268 \fBmpv \-\-slang=jpn example.mkv\fP plays a Matroska file with Japanese
1269 subtitles.
1270 .UNINDENT
1271 .UNINDENT
1272 .UNINDENT
1273 .TP
1274 .B \fB\-\-vlang=<...>\fP
1275 Equivalent to \fB\-\-alang\fP and \fB\-\-slang\fP, for video tracks.
1276 .TP
1277 .B \fB\-\-aid=<ID|auto|no>\fP
1278 Select audio track. \fBauto\fP selects the default, \fBno\fP disables audio.
1279 See also \fB\-\-alang\fP\&. mpv normally prints available audio tracks on the
1280 terminal when starting playback of a file.
1281 .sp
1282 \fB\-\-audio\fP is an alias for \fB\-\-aid\fP\&.
1283 .sp
1284 \fB\-\-aid=no\fP or \fB\-\-audio=no\fP or \fB\-\-no\-audio\fP disables audio playback.
1285 (The latter variant does not work with the client API.)
1286 .TP
1287 .B \fB\-\-sid=<ID|auto|no>\fP
1288 Display the subtitle stream specified by \fB<ID>\fP\&. \fBauto\fP selects
1289 the default, \fBno\fP disables subtitles.
1290 .sp
1291 \fB\-\-sub\fP is an alias for \fB\-\-sid\fP\&.
1292 .sp
1293 \fB\-\-sid=no\fP or \fB\-\-sub=no\fP or \fB\-\-no\-sub\fP disables subtitle decoding.
1294 (The latter variant does not work with the client API.)
1295 .TP
1296 .B \fB\-\-vid=<ID|auto|no>\fP
1297 Select video channel. \fBauto\fP selects the default, \fBno\fP disables video.
1298 .sp
1299 \fB\-\-video\fP is an alias for \fB\-\-vid\fP\&.
1300 .sp
1301 \fB\-\-vid=no\fP or \fB\-\-video=no\fP or \fB\-\-no\-video\fP disables video playback.
1302 (The latter variant does not work with the client API.)
1303 .sp
1304 If video is disabled, mpv will try to download the audio only if media is
1305 streamed with youtube\-dl, because it saves bandwidth. This is done by
1306 setting the ytdl_format to "bestaudio/best" in the ytdl_hook.lua script.
1307 .TP
1308 .B \fB\-\-edition=<ID|auto>\fP
1309 (Matroska files only)
1310 Specify the edition (set of chapters) to use, where 0 is the first. If set
1311 to \fBauto\fP (the default), mpv will choose the first edition declared as a
1312 default, or if there is no default, the first edition defined.
1313 .TP
1314 .B \fB\-\-track\-auto\-selection=<yes|no>\fP
1315 Enable the default track auto\-selection (default: yes). Enabling this will
1316 make the player select streams according to \fB\-\-aid\fP, \fB\-\-alang\fP, and
1317 others. If it is disabled, no tracks are selected. In addition, the player
1318 will not exit if no tracks are selected, and wait instead (this wait mode
1319 is similar to pausing, but the pause option is not set).
1320 .sp
1321 This is useful with \fB\-\-lavfi\-complex\fP: you can start playback in this
1322 mode, and then set select tracks at runtime by setting the filter graph.
1323 Note that if \fB\-\-lavfi\-complex\fP is set before playback is started, the
1324 referenced tracks are always selected.
1325 .UNINDENT
1326 .SS Playback Control
1327 .INDENT 0.0
1328 .TP
1329 .B \fB\-\-start=<relative time>\fP
1330 Seek to given time position.
1331 .sp
1332 The general format for times is \fB[+|\-][[hh:]mm:]ss[.ms]\fP\&. If the time is
1333 prefixed with \fB\-\fP, the time is considered relative from the end of the
1334 file (as signaled by the demuxer/the file). A \fB+\fP is usually ignored (but
1335 see below).
1336 .sp
1337 The following alternative time specifications are recognized:
1338 .sp
1339 \fBpp%\fP seeks to percent position pp (0\-100).
1340 .sp
1341 \fB#c\fP seeks to chapter number c. (Chapters start from 1.)
1342 .sp
1343 \fBnone\fP resets any previously set option (useful for libmpv).
1344 .sp
1345 If \fB\-\-rebase\-start\-time=no\fP is given, then prefixing times with \fB+\fP
1346 makes the time relative to the start of the file. A timestamp without
1347 prefix is considered an absolute time, i.e. should seek to a frame with a
1348 timestamp as the file contains it. As a bug, but also a hidden feature,
1349 putting 1 or more spaces before the \fB+\fP or \fB\-\fP always interprets the
1350 time as absolute, which can be used to seek to negative timestamps (useful
1351 for debugging at most).
1352 .INDENT 7.0
1353 .INDENT 3.5
1354 .IP "Examples"
1355 .INDENT 0.0
1356 .TP
1357 .B \fB\-\-start=+56\fP, \fB\-\-start=00:56\fP
1358 Seeks to the start time + 56 seconds.
1359 .TP
1360 .B \fB\-\-start=\-56\fP, \fB\-\-start=\-00:56\fP
1361 Seeks to the end time \- 56 seconds.
1362 .TP
1363 .B \fB\-\-start=01:10:00\fP
1364 Seeks to 1 hour 10 min.
1365 .TP
1366 .B \fB\-\-start=50%\fP
1367 Seeks to the middle of the file.
1368 .TP
1369 .B \fB\-\-start=30 \-\-end=40\fP
1370 Seeks to 30 seconds, plays 10 seconds, and exits.
1371 .TP
1372 .B \fB\-\-start=\-3:20 \-\-length=10\fP
1373 Seeks to 3 minutes and 20 seconds before the end of the file, plays
1374 10 seconds, and exits.
1375 .TP
1376 .B \fB\-\-start=\(aq#2\(aq \-\-end=\(aq#4\(aq\fP
1377 Plays chapters 2 and 3, and exits.
1378 .UNINDENT
1379 .UNINDENT
1380 .UNINDENT
1381 .TP
1382 .B \fB\-\-end=<relative time>\fP
1383 Stop at given time. Use \fB\-\-length\fP if the time should be relative
1384 to \fB\-\-start\fP\&. See \fB\-\-start\fP for valid option values and examples.
1385 .TP
1386 .B \fB\-\-length=<relative time>\fP
1387 Stop after a given time relative to the start time.
1388 See \fB\-\-start\fP for valid option values and examples.
1389 .sp
1390 If both \fB\-\-end\fP and \fB\-\-length\fP are provided, playback will stop when it
1391 reaches either of the two endpoints.
1392 .sp
1393 Obscurity note: this does not work correctly if \fB\-\-rebase\-start\-time=no\fP,
1394 and the specified time is not an "absolute" time, as defined in the
1395 \fB\-\-start\fP option description.
1396 .TP
1397 .B \fB\-\-rebase\-start\-time=<yes|no>\fP
1398 Whether to move the file start time to \fB00:00:00\fP (default: yes). This
1399 is less awkward for files which start at a random timestamp, such as
1400 transport streams. On the other hand, if there are timestamp resets, the
1401 resulting behavior can be rather weird. For this reason, and in case you
1402 are actually interested in the real timestamps, this behavior can be
1403 disabled with \fBno\fP\&.
1404 .TP
1405 .B \fB\-\-speed=<0.01\-100>\fP
1406 Slow down or speed up playback by the factor given as parameter.
1407 .sp
1408 If \fB\-\-audio\-pitch\-correction\fP (on by default) is used, playing with a
1409 speed higher than normal automatically inserts the \fBscaletempo\fP audio
1410 filter.
1411 .TP
1412 .B \fB\-\-pause\fP
1413 Start the player in paused state.
1414 .TP
1415 .B \fB\-\-shuffle\fP
1416 Play files in random order.
1417 .TP
1418 .B \fB\-\-playlist\-start=<auto|index>\fP
1419 Set which file on the internal playlist to start playback with. The index
1420 is an integer, with 0 meaning the first file. The value \fBauto\fP means that
1421 the selection of the entry to play is left to the playback resume mechanism
1422 (default). If an entry with the given index doesn\(aqt exist, the behavior is
1423 unspecified and might change in future mpv versions. The same applies if
1424 the playlist contains further playlists (don\(aqt expect any reasonable
1425 behavior). Passing a playlist file to mpv should work with this option,
1426 though. E.g. \fBmpv playlist.m3u \-\-playlist\-start=123\fP will work as expected,
1427 as long as \fBplaylist.m3u\fP does not link to further playlists.
1428 .sp
1429 The value \fBno\fP is a deprecated alias for \fBauto\fP\&.
1430 .TP
1431 .B \fB\-\-playlist=<filename>\fP
1432 Play files according to a playlist file (Supports some common formats. If
1433 no format is detected, it will be treated as list of files, separated by
1434 newline characters. Note that XML playlist formats are not supported.)
1435 .sp
1436 You can play playlists directly and without this option, however, this
1437 option disables any security mechanisms that might be in place. You may
1438 also need this option to load plaintext files as playlist.
1439 .sp
1440 \fBWARNING:\fP
1441 .INDENT 7.0
1442 .INDENT 3.5
1443 The way mpv uses playlist files via \fB\-\-playlist\fP is not safe against
1444 maliciously constructed files. Such files may trigger harmful actions.
1445 This has been the case for all mpv and MPlayer versions, but
1446 unfortunately this fact was not well documented earlier, and some people
1447 have even misguidedly recommended use of \fB\-\-playlist\fP with untrusted
1448 sources. Do NOT use \fB\-\-playlist\fP with random internet sources or files
1449 you do not trust!
1450 .sp
1451 Playlist can contain entries using other protocols, such as local files,
1452 or (most severely), special protocols like \fBavdevice://\fP, which are
1453 inherently unsafe.
1454 .UNINDENT
1455 .UNINDENT
1456 .TP
1457 .B \fB\-\-chapter\-merge\-threshold=<number>\fP
1458 Threshold for merging almost consecutive ordered chapter parts in
1459 milliseconds (default: 100). Some Matroska files with ordered chapters
1460 have inaccurate chapter end timestamps, causing a small gap between the
1461 end of one chapter and the start of the next one when they should match.
1462 If the end of one playback part is less than the given threshold away from
1463 the start of the next one then keep playing video normally over the
1464 chapter change instead of doing a seek.
1465 .TP
1466 .B \fB\-\-chapter\-seek\-threshold=<seconds>\fP
1467 Distance in seconds from the beginning of a chapter within which a backward
1468 chapter seek will go to the previous chapter (default: 5.0). Past this
1469 threshold, a backward chapter seek will go to the beginning of the current
1470 chapter instead. A negative value means always go back to the previous
1471 chapter.
1472 .TP
1473 .B \fB\-\-hr\-seek=<no|absolute|yes>\fP
1474 Select when to use precise seeks that are not limited to keyframes. Such
1475 seeks require decoding video from the previous keyframe up to the target
1476 position and so can take some time depending on decoding performance. For
1477 some video formats, precise seeks are disabled. This option selects the
1478 default choice to use for seeks; it is possible to explicitly override that
1479 default in the definition of key bindings and in input commands.
1480 .INDENT 7.0
1481 .TP
1482 .B no
1483 Never use precise seeks.
1484 .TP
1485 .B absolute
1486 Use precise seeks if the seek is to an absolute position in the
1487 file, such as a chapter seek, but not for relative seeks like
1488 the default behavior of arrow keys (default).
1489 .TP
1490 .B yes
1491 Use precise seeks whenever possible.
1492 .TP
1493 .B always
1494 Same as \fByes\fP (for compatibility).
1495 .UNINDENT
1496 .TP
1497 .B \fB\-\-hr\-seek\-demuxer\-offset=<seconds>\fP
1498 This option exists to work around failures to do precise seeks (as in
1499 \fB\-\-hr\-seek\fP) caused by bugs or limitations in the demuxers for some file
1500 formats. Some demuxers fail to seek to a keyframe before the given target
1501 position, going to a later position instead. The value of this option is
1502 subtracted from the time stamp given to the demuxer. Thus, if you set this
1503 option to 1.5 and try to do a precise seek to 60 seconds, the demuxer is
1504 told to seek to time 58.5, which hopefully reduces the chance that it
1505 erroneously goes to some time later than 60 seconds. The downside of
1506 setting this option is that precise seeks become slower, as video between
1507 the earlier demuxer position and the real target may be unnecessarily
1508 decoded.
1509 .TP
1510 .B \fB\-\-hr\-seek\-framedrop=<yes|no>\fP
1511 Allow the video decoder to drop frames during seek, if these frames are
1512 before the seek target. If this is enabled, precise seeking can be faster,
1513 but if you\(aqre using video filters which modify timestamps or add new
1514 frames, it can lead to precise seeking skipping the target frame. This
1515 e.g. can break frame backstepping when deinterlacing is enabled.
1516 .sp
1517 Default: \fByes\fP
1518 .TP
1519 .B \fB\-\-index=<mode>\fP
1520 Controls how to seek in files. Note that if the index is missing from a
1521 file, it will be built on the fly by default, so you don\(aqt need to change
1522 this. But it might help with some broken files.
1523 .INDENT 7.0
1524 .TP
1525 .B default
1526 use an index if the file has one, or build it if missing
1527 .TP
1528 .B recreate
1529 don\(aqt read or use the file\(aqs index
1530 .UNINDENT
1531 .sp
1532 \fBNOTE:\fP
1533 .INDENT 7.0
1534 .INDENT 3.5
1535 This option only works if the underlying media supports seeking
1536 (i.e. not with stdin, pipe, etc).
1537 .UNINDENT
1538 .UNINDENT
1539 .TP
1540 .B \fB\-\-load\-unsafe\-playlists\fP
1541 Load URLs from playlists which are considered unsafe (default: no). This
1542 includes special protocols and anything that doesn\(aqt refer to normal files.
1543 Local files and HTTP links on the other hand are always considered safe.
1544 .sp
1545 In addition, if a playlist is loaded while this is set, the added playlist
1546 entries are not marked as originating from network or potentially unsafe
1547 location. (Instead, the behavior is as if the playlist entries were provided
1548 directly to mpv command line or \fBloadfile\fP command.)
1549 .sp
1550 Note that \fB\-\-playlist\fP always loads all entries, so you use that instead
1551 if you really have the need for this functionality.
1552 .TP
1553 .B \fB\-\-access\-references=<yes|no>\fP
1554 Follow any references in the file being opened (default: yes). Disabling
1555 this is helpful if the file is automatically scanned (e.g. thumbnail
1556 generation). If the thumbnail scanner for example encounters a playlist
1557 file, which contains network URLs, and the scanner should not open these,
1558 enabling this option will prevent it. This option also disables ordered
1559 chapters, mov reference files, opening of archives, and a number of other
1560 features.
1561 .sp
1562 On older FFmpeg versions, this will not work in some cases. Some FFmpeg
1563 demuxers might not respect this option.
1564 .sp
1565 This option does not prevent opening of paired subtitle files and such. Use
1566 \fB\-\-autoload\-files=no\fP to prevent this.
1567 .sp
1568 This option does not always work if you open non\-files (for example using
1569 \fBdvd://directory\fP would open a whole bunch of files in the given
1570 directory). Prefixing the filename with \fB\&./\fP if it doesn\(aqt start with
1571 a \fB/\fP will avoid this.
1572 .TP
1573 .B \fB\-\-loop\-playlist=<N|inf|force|no>\fP, \fB\-\-loop\-playlist\fP
1574 Loops playback \fBN\fP times. A value of \fB1\fP plays it one time (default),
1575 \fB2\fP two times, etc. \fBinf\fP means forever. \fBno\fP is the same as \fB1\fP and
1576 disables looping. If several files are specified on command line, the
1577 entire playlist is looped. \fB\-\-loop\-playlist\fP is the same as
1578 \fB\-\-loop\-playlist=inf\fP\&.
1579 .sp
1580 The \fBforce\fP mode is like \fBinf\fP, but does not skip playlist entries
1581 which have been marked as failing. This means the player might waste CPU
1582 time trying to loop a file that doesn\(aqt exist. But it might be useful for
1583 playing webradios under very bad network conditions.
1584 .TP
1585 .B \fB\-\-loop\-file=<N|inf|no>\fP, \fB\-\-loop=<N|inf|no>\fP
1586 Loop a single file N times. \fBinf\fP means forever, \fBno\fP means normal
1587 playback. For compatibility, \fB\-\-loop\-file\fP and \fB\-\-loop\-file=yes\fP are
1588 also accepted, and are the same as \fB\-\-loop\-file=inf\fP\&.
1589 .sp
1590 The difference to \fB\-\-loop\-playlist\fP is that this doesn\(aqt loop the playlist,
1591 just the file itself. If the playlist contains only a single file, the
1592 difference between the two option is that this option performs a seek on
1593 loop, instead of reloading the file.
1594 .sp
1595 \fB\-\-loop\fP is an alias for this option.
1596 .TP
1597 .B \fB\-\-ab\-loop\-a=<time>\fP, \fB\-\-ab\-loop\-b=<time>\fP
1598 Set loop points. If playback passes the \fBb\fP timestamp, it will seek to
1599 the \fBa\fP timestamp. Seeking past the \fBb\fP point doesn\(aqt loop (this is
1600 intentional).
1601 .sp
1602 If \fBa\fP is after \fBb\fP, the behavior is as if the points were given in
1603 the right order, and the player will seek to \fBb\fP after crossing through
1604 \fBa\fP\&. This is different from old behavior, where looping was disabled (and
1605 as a bug, looped back to \fBa\fP on the end of the file).
1606 .sp
1607 If either options are set to \fBno\fP (or unset), looping is disabled. This
1608 is different from old behavior, where an unset \fBa\fP implied the start of
1609 the file, and an unset \fBb\fP the end of the file.
1610 .sp
1611 The loop\-points can be adjusted at runtime with the corresponding
1612 properties. See also \fBab\-loop\fP command.
1613 .TP
1614 .B \fB\-\-ordered\-chapters\fP, \fB\-\-no\-ordered\-chapters\fP
1615 Enabled by default.
1616 Disable support for Matroska ordered chapters. mpv will not load or
1617 search for video segments from other files, and will also ignore any
1618 chapter order specified for the main file.
1619 .TP
1620 .B \fB\-\-ordered\-chapters\-files=<playlist\-file>\fP
1621 Loads the given file as playlist, and tries to use the files contained in
1622 it as reference files when opening a Matroska file that uses ordered
1623 chapters. This overrides the normal mechanism for loading referenced
1624 files by scanning the same directory the main file is located in.
1625 .sp
1626 Useful for loading ordered chapter files that are not located on the local
1627 filesystem, or if the referenced files are in different directories.
1628 .sp
1629 Note: a playlist can be as simple as a text file containing filenames
1630 separated by newlines.
1631 .TP
1632 .B \fB\-\-chapters\-file=<filename>\fP
1633 Load chapters from this file, instead of using the chapter metadata found
1634 in the main file.
1635 .sp
1636 This accepts a media file (like mkv) or even a pseudo\-format like ffmetadata
1637 and uses its chapters to replace the current file\(aqs chapters. This doesn\(aqt
1638 work with OGM or XML chapters directly.
1639 .TP
1640 .B \fB\-\-sstep=<sec>\fP
1641 Skip <sec> seconds after every frame.
1642 .sp
1643 \fBNOTE:\fP
1644 .INDENT 7.0
1645 .INDENT 3.5
1646 Without \fB\-\-hr\-seek\fP, skipping will snap to keyframes.
1647 .UNINDENT
1648 .UNINDENT
1649 .TP
1650 .B \fB\-\-stop\-playback\-on\-init\-failure=<yes|no>\fP
1651 Stop playback if either audio or video fails to initialize (default: no).
1652 With \fBno\fP, playback will continue in video\-only or audio\-only mode if one
1653 of them fails. This doesn\(aqt affect playback of audio\-only or video\-only
1654 files.
1655 .TP
1656 .B \fB\-\-play\-dir=<forward|+|backward|\->\fP
1657 Control the playback direction (default: forward). Setting \fBbackward\fP
1658 will attempt to play the file in reverse direction, with decreasing
1659 playback time. If this is set on playback starts, playback will start from
1660 the end of the file. If this is changed at during playback, a hr\-seek will
1661 be issued to change the direction.
1662 .sp
1663 \fB+\fP and \fB\-\fP are aliases for \fBforward\fP and \fBbackward\fP\&.
1664 .sp
1665 The rest of this option description pertains to the \fBbackward\fP mode.
1666 .sp
1667 \fBNOTE:\fP
1668 .INDENT 7.0
1669 .INDENT 3.5
1670 Backward playback is extremely fragile. It may not always work, is much
1671 slower than forward playback, and breaks certain other features. How
1672 well it works depends mainly on the file being played. Generally, it
1673 will show good results (or results at all) only if the stars align.
1674 .UNINDENT
1675 .UNINDENT
1676 .sp
1677 mpv, as well as most media formats, were designed for forward playback
1678 only. Backward playback is bolted on top of mpv, and tries to make a medium
1679 effort to make backward playback work. Depending on your use\-case, another
1680 tool may work much better.
1681 .sp
1682 Backward playback is not exactly a 1st class feature. Implementation
1683 tradeoffs were made, that are bad for backward playback, but in turn do not
1684 cause disadvantages for normal playback. Various possible optimizations are
1685 not implemented in order to keep the complexity down. Normally, a media
1686 player is highly pipelined (future data is prepared in separate threads, so
1687 it is available in realtime when the next stage needs it), but backward
1688 playback will essentially stall the pipeline at various random points.
1689 .sp
1690 For example, for intra\-only codecs are trivially backward playable, and
1691 tools built around them may make efficient use of them (consider video
1692 editors or camera viewers). mpv won\(aqt be efficient in this case, because it
1693 uses its generic backward playback algorithm, that on top of it is not very
1694 optimized.
1695 .sp
1696 If you just want to quickly go backward through the video and just show
1697 "keyframes", just use forward playback, and hold down the left cursor key
1698 (which on CLI with default config sends many small relative seek commands).
1699 .sp
1700 The implementation consists of mostly 3 parts:
1701 .INDENT 7.0
1702 .IP \(bu 2
1703 Backward demuxing. This relies on the demuxer cache, so the demuxer cache
1704 should (or must, didn\(aqt test it) be enabled, and its size will affect
1705 performance. If the cache is too small or too large, quadratic runtime
1706 behavior may result.
1707 .IP \(bu 2
1708 Backward decoding. The decoder library used (libavcodec) does not support
1709 this. It is emulated by feeding bits of data in forward, putting the
1710 result in a queue, returning the queue data to the VO in reverse, and
1711 then starting over at an earlier position. This can require buffering an
1712 extreme amount of decoded data, and also completely breaks pipelining.
1713 .IP \(bu 2
1714 Backward output. This is relatively simple, because the decoder returns
1715 the frames in the needed order. However, this may cause various problems
1716 because filters see audio and video going backward.
1717 .UNINDENT
1718 .sp
1719 Known problems:
1720 .INDENT 7.0
1721 .IP \(bu 2
1722 It\(aqs fragile. If anything doesn\(aqt work, random non\-useful behavior may
1723 occur. In simple cases, the player will just play nonsense and artifacts.
1724 In other cases, it may get stuck or heat the CPU. (Exceeding memory usage
1725 significantly beyond the user\-set limits would be a bug, though.)
1726 .IP \(bu 2
1727 Performance and resource usage isn\(aqt good. In part this is inherent to
1728 backward playback of normal media formats, and in parts due to
1729 implementation choices and tradeoffs.
1730 .IP \(bu 2
1731 This is extremely reliant on good demuxer behavior. Although backward
1732 demuxing requires no special demuxer support, it is required that the
1733 demuxer performs seeks reliably, fulfills some specific requirements
1734 about packet metadata, and has deterministic behavior.
1735 .IP \(bu 2
1736 Starting playback exactly from the end may or may not work, depending on
1737 seeking behavior and file duration detection.
1738 .IP \(bu 2
1739 Some container formats, audio, and video codecs are not supported due to
1740 their behavior. There is no list, and the player usually does not detect
1741 them. Certain live streams (including TV captures) may exhibit problems
1742 in particular, as well as some lossy audio codecs. h264 intra\-refresh is
1743 known not to work due to problems with libavcodec. WAV and some other raw
1744 audio formats tend to have problems \- there are hacks for dealing with
1745 them, which may or may not work.
1746 .IP \(bu 2
1747 Backward demuxing of subtitles is not supported. Subtitle display still
1748 works for some external text subtitle formats. (These are fully read into
1749 memory, and only backward display is needed.) Text subtitles that are
1750 cached in the subtitle renderer also have a chance to be displayed
1751 correctly.
1752 .IP \(bu 2
1753 Some features dealing with playback of broken or hard to deal with files
1754 will not work fully (such as timestamp correction).
1755 .IP \(bu 2
1756 If demuxer low level seeks (i.e. seeking the actual demuxer instead of
1757 just within the demuxer cache) are performed by backward playback, the
1758 created seek ranges may not join, because not enough overlap is achieved.
1759 .IP \(bu 2
1760 Trying to use this with hardware video decoding will probably exhaust all
1761 your GPU memory and then crash a thing or two. Or it will fail because
1762 \fB\-\-hwdec\-extra\-frames\fP will certainly be set too low.
1763 .IP \(bu 2
1764 Stream recording is broken. \fB\-\-stream\-record\fP may keep working if you
1765 backward play within a cached region only.
1766 .IP \(bu 2
1767 Relative seeks may behave weird. Small seeks backward (towards smaller
1768 time, i.e. \fBseek \-1\fP) may not really seek properly, and audio will
1769 remain muted for a while. Using hr\-seek is recommended, which should have
1770 none of these problems.
1771 .IP \(bu 2
1772 Some things are just weird. For example, while seek commands manipulate
1773 playback time in the expected way (provided they work correctly), the
1774 framestep commands are transposed. Backstepping will perform very
1775 expensive work to step forward by 1 frame.
1776 .UNINDENT
1777 .sp
1778 Tuning:
1779 .INDENT 7.0
1780 .IP \(bu 2
1781 Remove all \fB\-\-vf\fP/\fB\-\-af\fP filters you have set. Disable hardware
1782 decoding. Disable idiotic nonsense like SPDIF passthrough.
1783 .IP \(bu 2
1784 Increasing \fB\-\-video\-reversal\-buffer\fP might help if reversal queue
1785 overflow is reported, which may happen in high bitrate video, or video
1786 with large GOP. Hardware decoding mostly ignores this, and you need to
1787 increase \fB\-\-hwdec\-extra\-frames\fP instead (until you get playback without
1788 logged errors).
1789 .IP \(bu 2
1790 The demuxer cache is essential for backward demuxing. Make sure to set
1791 \fB\-\-demuxer\-seekable\-cache\fP (or just use \fB\-\-cache\fP). The cache size
1792 might matter. If it\(aqs too small, a queue overflow will be logged, and
1793 backward playback cannot continue, or it performs too many low level
1794 seeks. If it\(aqs too large, implementation tradeoffs may cause general
1795 performance issues. Use \fB\-\-demuxer\-max\-bytes\fP to potentially increase
1796 the amount of packets the demuxer layer can queue for reverse demuxing
1797 (basically it\(aqs the \fB\-\-video\-reversal\-buffer\fP equivalent for the
1798 demuxer layer).
1799 .IP \(bu 2
1800 \fB\-\-demuxer\-backward\-playback\-step\fP also factors into how many seeks may
1801 be performed, and whether backward demuxing could break due to queue
1802 overflow. If it\(aqs set too high, the backstep operation needs to search
1803 through more packets all the time, even if the cache is large enough.
1804 .IP \(bu 2
1805 Setting \fB\-\-demuxer\-cache\-wait\fP may be useful to cache the entire file
1806 into the demuxer cache. Set \fB\-\-demuxer\-max\-bytes\fP to a large size to
1807 make sure it can read the entire cache; \fB\-\-demuxer\-max\-back\-bytes\fP
1808 should also be set to a large size to prevent that tries to trim the
1809 cache.
1810 .IP \(bu 2
1811 If audio artifacts are audible, even though the AO does not underrun,
1812 increasing \fB\-\-audio\-backward\-overlap\fP might help in some cases.
1813 .UNINDENT
1814 .TP
1815 .B \fB\-\-video\-reversal\-buffer=<bytesize>\fP, \fB\-\-audio\-reversal\-buffer=<bytesize>\fP
1816 For backward decoding. Backward decoding decodes forward in steps, and then
1817 reverses the decoder output. These options control the approximate maximum
1818 amount of bytes that can be buffered. The main use of this is to avoid
1819 unbounded resource usage; during normal backward playback, it\(aqs not supposed
1820 to hit the limit, and if it does, it will drop frames and complain about it.
1821 .sp
1822 Use this option if you get reversal queue overflow errors during backward
1823 playback. Increase the size until the warning disappears. Usually, the video
1824 buffer will overflow first, especially if it\(aqs high resolution video.
1825 .sp
1826 This does not work correctly if video hardware decoding is used. The video
1827 frame size will not include the referenced GPU and driver memory. Some
1828 hardware decoders may also be limited by \fB\-\-hwdec\-extra\-frames\fP\&.
1829 .sp
1830 How large the queue size needs to be depends entirely on the way the media
1831 was encoded. Audio typically requires a very small buffer, while video can
1832 require excessively large buffers.
1833 .sp
1834 (Technically, this allows the last frame to exceed the limit. Also, this
1835 does not account for other buffered frames, such as inside the decoder or
1836 the video output.)
1837 .sp
1838 This does not affect demuxer cache behavior at all.
1839 .sp
1840 See \fB\-\-list\-options\fP for defaults and value range. \fB<bytesize>\fP options
1841 accept suffixes such as \fBKiB\fP and \fBMiB\fP\&.
1842 .TP
1843 .B \fB\-\-video\-backward\-overlap=<auto|number>\fP, \fB\-\-audio\-backward\-overlap=<auto|number>\fP
1844 Number of overlapping keyframe ranges to use for backward decoding (default:
1845 auto) ("keyframe" to be understood as in the mpv/ffmpeg specific meaning).
1846 Backward decoding works by forward decoding in small steps. Some codecs
1847 cannot restart decoding from any packet (even if it\(aqs marked as seek point),
1848 which becomes noticeable with backward decoding (in theory this is a problem
1849 with seeking too, but \fB\-\-hr\-seek\-demuxer\-offset\fP can fix it for seeking).
1850 In particular, MDCT based audio codecs are affected.
1851 .sp
1852 The solution is to feed a previous packet to the decoder each time, and then
1853 discard the output. This option controls how many packets to feed. The
1854 \fBauto\fP choice is currently hardcoded to 0 for video, and uses 1 for lossy
1855 audio, 0 for lossless audio. For some specific lossy audio codecs, this is
1856 set to 2.
1857 .sp
1858 \fB\-\-video\-backward\-overlap\fP can potentially handle intra\-refresh video,
1859 depending on the exact conditions. You may have to use the
1860 \fB\-\-vd\-lavc\-show\-all\fP option as well.
1861 .TP
1862 .B \fB\-\-video\-backward\-batch=<number>\fP, \fB\-\-audio\-backward\-batch=<number>\fP
1863 Number of keyframe ranges to decode at once when backward decoding (default:
1864 1 for video, 10 for audio). Another pointless tuning parameter nobody should
1865 use. This should affect performance only. In theory, setting a number higher
1866 than 1 for audio will reduce overhead due to less frequent backstep
1867 operations and less redundant decoding work due to fewer decoded overlap
1868 frames (see \fB\-\-audio\-backward\-overlap\fP). On the other hand, it requires
1869 a larger reversal buffer, and could make playback less smooth due to
1870 breaking pipelining (e.g. by decoding a lot, and then doing nothing for a
1871 while).
1872 .sp
1873 It probably never makes sense to set \fB\-\-video\-backward\-batch\fP\&. But in
1874 theory, it could help with intra\-only video codecs by reducing backstep
1875 operations.
1876 .TP
1877 .B \fB\-\-demuxer\-backward\-playback\-step=<seconds>\fP
1878 Number of seconds the demuxer should seek back to get new packets during
1879 backward playback (default: 60). This is useful for tuning backward
1880 playback, see \fB\-\-play\-dir\fP for details.
1881 .sp
1882 Setting this to a very low value or 0 may make the player think seeking is
1883 broken, or may make it perform multiple seeks.
1884 .sp
1885 Setting this to a high value may lead to quadratic runtime behavior.
1886 .UNINDENT
1887 .SS Program Behavior
1888 .INDENT 0.0
1889 .TP
1890 .B \fB\-\-help\fP, \fB\-\-h\fP
1891 Show short summary of options.
1892 .sp
1893 You can also pass a string to this option, which will list all top\-level
1894 options which contain the string in the name, e.g. \fB\-\-h=scale\fP for all
1895 options that contain the word \fBscale\fP\&. The special string \fB*\fP lists
1896 all top\-level options.
1897 .TP
1898 .B \fB\-v\fP
1899 Increment verbosity level, one level for each \fB\-v\fP found on the command
1900 line.
1901 .TP
1902 .B \fB\-\-version, \-V\fP
1903 Print version string and exit.
1904 .TP
1905 .B \fB\-\-no\-config\fP
1906 Do not load default configuration files. This prevents loading of both the
1907 user\-level and system\-wide \fBmpv.conf\fP and \fBinput.conf\fP files. Other
1908 configuration files are blocked as well, such as resume playback files.
1909 .sp
1910 \fBNOTE:\fP
1911 .INDENT 7.0
1912 .INDENT 3.5
1913 Files explicitly requested by command line options, like
1914 \fB\-\-include\fP or \fB\-\-use\-filedir\-conf\fP, will still be loaded.
1915 .UNINDENT
1916 .UNINDENT
1917 .sp
1918 See also: \fB\-\-config\-dir\fP\&.
1919 .TP
1920 .B \fB\-\-list\-options\fP
1921 Prints all available options.
1922 .TP
1923 .B \fB\-\-list\-properties\fP
1924 Print a list of the available properties.
1925 .TP
1926 .B \fB\-\-list\-protocols\fP
1927 Print a list of the supported protocols.
1928 .TP
1929 .B \fB\-\-log\-file=<path>\fP
1930 Opens the given path for writing, and print log messages to it. Existing
1931 files will be truncated. The log level is at least \fB\-v \-v\fP, but
1932 can be raised via \fB\-\-msg\-level\fP (the option cannot lower it below the
1933 forced minimum log level).
1934 .TP
1935 .B \fB\-\-config\-dir=<path>\fP
1936 Force a different configuration directory. If this is set, the given
1937 directory is used to load configuration files, and all other configuration
1938 directories are ignored. This means the global mpv configuration directory
1939 as well as per\-user directories are ignored, and overrides through
1940 environment variables (\fBMPV_HOME\fP) are also ignored.
1941 .sp
1942 Note that the \fB\-\-no\-config\fP option takes precedence over this option.
1943 .TP
1944 .B \fB\-\-save\-position\-on\-quit\fP
1945 Always save the current playback position on quit. When this file is
1946 played again later, the player will seek to the old playback position on
1947 start. This does not happen if playback of a file is stopped in any other
1948 way than quitting. For example, going to the next file in the playlist
1949 will not save the position, and start playback at beginning the next time
1950 the file is played.
1951 .sp
1952 This behavior is disabled by default, but is always available when quitting
1953 the player with Shift+Q.
1954 .TP
1955 .B \fB\-\-watch\-later\-directory=<path>\fP
1956 The directory in which to store the "watch later" temporary files.
1957 .sp
1958 The default is a subdirectory named "watch_later" underneath the
1959 config directory (usually \fB~/.config/mpv/\fP).
1960 .TP
1961 .B \fB\-\-dump\-stats=<filename>\fP
1962 Write certain statistics to the given file. The file is truncated on
1963 opening. The file will contain raw samples, each with a timestamp. To
1964 make this file into a readable, the script \fBTOOLS/stats\-conv.py\fP can be
1965 used (which currently displays it as a graph).
1966 .sp
1967 This option is useful for debugging only.
1968 .TP
1969 .B \fB\-\-idle=<no|yes|once>\fP
1970 Makes mpv wait idly instead of quitting when there is no file to play.
1971 Mostly useful in input mode, where mpv can be controlled through input
1972 commands. (Default: \fBno\fP)
1973 .sp
1974 \fBonce\fP will only idle at start and let the player close once the
1975 first playlist has finished playing back.
1976 .TP
1977 .B \fB\-\-include=<configuration\-file>\fP
1978 Specify configuration file to be parsed after the default ones.
1979 .TP
1980 .B \fB\-\-load\-scripts=<yes|no>\fP
1981 If set to \fBno\fP, don\(aqt auto\-load scripts from the \fBscripts\fP
1982 configuration subdirectory (usually \fB~/.config/mpv/scripts/\fP).
1983 (Default: \fByes\fP)
1984 .TP
1985 .B \fB\-\-script=<filename>\fP, \fB\-\-scripts=file1.lua:file2.lua:...\fP
1986 Load a Lua script. The second option allows you to load multiple scripts by
1987 separating them with the path separator (\fB:\fP on Unix, \fB;\fP on Windows).
1988 .TP
1989 .B \fB\-\-script\-opts=key1=value1,key2=value2,...\fP
1990 Set options for scripts. A script can query an option by key. If an
1991 option is used and what semantics the option value has depends entirely on
1992 the loaded scripts. Values not claimed by any scripts are ignored.
1993 .TP
1994 .B \fB\-\-merge\-files\fP
1995 Pretend that all files passed to mpv are concatenated into a single, big
1996 file. This uses timeline/EDL support internally.
1997 .TP
1998 .B \fB\-\-no\-resume\-playback\fP
1999 Do not restore playback position from the \fBwatch_later\fP configuration
2000 subdirectory (usually \fB~/.config/mpv/watch_later/\fP).
2001 See \fBquit\-watch\-later\fP input command.
2002 .TP
2003 .B \fB\-\-profile=<profile1,profile2,...>\fP
2004 Use the given profile(s), \fB\-\-profile=help\fP displays a list of the
2005 defined profiles.
2006 .TP
2007 .B \fB\-\-reset\-on\-next\-file=<all|option1,option2,...>\fP
2008 Normally, mpv will try to keep all settings when playing the next file on
2009 the playlist, even if they were changed by the user during playback. (This
2010 behavior is the opposite of MPlayer\(aqs, which tries to reset all settings
2011 when starting next file.)
2012 .sp
2013 Default: Do not reset anything.
2014 .sp
2015 This can be changed with this option. It accepts a list of options, and
2016 mpv will reset the value of these options on playback start to the initial
2017 value. The initial value is either the default value, or as set by the
2018 config file or command line.
2019 .sp
2020 In some cases, this might not work as expected. For example, \fB\-\-volume\fP
2021 will only be reset if it is explicitly set in the config file or the
2022 command line.
2023 .sp
2024 The special name \fBall\fP resets as many options as possible.
2025 .INDENT 7.0
2026 .INDENT 3.5
2027 .IP "Examples"
2028 .INDENT 0.0
2029 .IP \(bu 2
2030 \fB\-\-reset\-on\-next\-file=pause\fP
2031 Reset pause mode when switching to the next file.
2032 .IP \(bu 2
2033 \fB\-\-reset\-on\-next\-file=fullscreen,speed\fP
2034 Reset fullscreen and playback speed settings if they were changed
2035 during playback.
2036 .IP \(bu 2
2037 \fB\-\-reset\-on\-next\-file=all\fP
2038 Try to reset all settings that were changed during playback.
2039 .UNINDENT
2040 .UNINDENT
2041 .UNINDENT
2042 .TP
2043 .B \fB\-\-write\-filename\-in\-watch\-later\-config\fP
2044 Prepend the watch later config files with the name of the file they refer
2045 to. This is simply written as comment on the top of the file.
2046 .sp
2047 \fBWARNING:\fP
2048 .INDENT 7.0
2049 .INDENT 3.5
2050 This option may expose privacy\-sensitive information and is thus
2051 disabled by default.
2052 .UNINDENT
2053 .UNINDENT
2054 .TP
2055 .B \fB\-\-ignore\-path\-in\-watch\-later\-config\fP
2056 Ignore path (i.e. use filename only) when using watch later feature.
2057 (Default: disabled)
2058 .TP
2059 .B \fB\-\-show\-profile=<profile>\fP
2060 Show the description and content of a profile.
2061 .TP
2062 .B \fB\-\-use\-filedir\-conf\fP
2063 Look for a file\-specific configuration file in the same directory as the
2064 file that is being played. See \fI\%File\-specific Configuration Files\fP\&.
2065 .sp
2066 \fBWARNING:\fP
2067 .INDENT 7.0
2068 .INDENT 3.5
2069 May be dangerous if playing from untrusted media.
2070 .UNINDENT
2071 .UNINDENT
2072 .TP
2073 .B \fB\-\-ytdl\fP, \fB\-\-no\-ytdl\fP
2074 Enable the youtube\-dl hook\-script. It will look at the input URL, and will
2075 play the video located on the website. This works with many streaming sites,
2076 not just the one that the script is named after. This requires a recent
2077 version of youtube\-dl to be installed on the system. (Enabled by default.)
2078 .sp
2079 If the script can\(aqt do anything with an URL, it will do nothing.
2080 .sp
2081 The \fBtry_ytdl_first\fP script option accepts a boolean \(aqyes\(aq or \(aqno\(aq, and if
2082 \(aqyes\(aq will try parsing the URL with youtube\-dl first, instead of the default
2083 where it\(aqs only after mpv failed to open it. This mostly depends on whether
2084 most of your URLs need youtube\-dl parsing.
2085 .sp
2086 The \fBexclude\fP script option accepts a \fB|\fP\-separated list of URL patterns
2087 which mpv should not use with youtube\-dl. The patterns are matched after
2088 the \fBhttp(s)://\fP part of the URL.
2089 .sp
2090 \fB^\fP matches the beginning of the URL, \fB$\fP matches its end, and you
2091 should use \fB%\fP before any of the characters \fB^$()%|,.[]*+\-?\fP to match
2092 that character.
2093 .INDENT 7.0
2094 .INDENT 3.5
2095 .IP "Examples"
2096 .INDENT 0.0
2097 .IP \(bu 2
2098 \fB\-\-script\-opts=ytdl_hook\-exclude=\(aq^youtube%.com\(aq\fP
2099 will exclude any URL that starts with \fBhttp://youtube.com\fP or
2100 \fBhttps://youtube.com\fP\&.
2101 .IP \(bu 2
2102 \fB\-\-script\-opts=ytdl_hook\-exclude=\(aq%.mkv$|%.mp4$\(aq\fP
2103 will exclude any URL that ends with \fB\&.mkv\fP or \fB\&.mp4\fP\&.
2104 .UNINDENT
2105 .UNINDENT
2106 .UNINDENT
2107 .sp
2108 See more lua patterns here: \fI\%https://www.lua.org/manual/5.1/manual.html#5.4.1\fP
2109 .sp
2110 The \fBuse_manifests\fP script option makes mpv use the master manifest URL for
2111 formats like HLS and DASH, if available, allowing for video/audio selection
2112 in runtime. It\(aqs disabled ("no") by default for performance reasons.
2113 .TP
2114 .B \fB\-\-ytdl\-format=<best|worst|mp4|webm|...>\fP
2115 Video format/quality that is directly passed to youtube\-dl. The possible
2116 values are specific to the website and the video, for a given url the
2117 available formats can be found with the command
2118 \fByoutube\-dl \-\-list\-formats URL\fP\&. See youtube\-dl\(aqs documentation for
2119 available aliases.
2120 (Default: youtube\-dl\(aqs default, currently \fBbestvideo+bestaudio/best\fP)
2121 .TP
2122 .B \fB\-\-ytdl\-raw\-options=<key>=<value>[,<key>=<value>[,...]]\fP
2123 Pass arbitrary options to youtube\-dl. Parameter and argument should be
2124 passed as a key\-value pair. Options without argument must include \fB=\fP\&.
2125 .sp
2126 There is no sanity checking so it\(aqs possible to break things (i.e.
2127 passing invalid parameters to youtube\-dl).
2128 .sp
2129 A proxy URL can be passed for youtube\-dl to use it in parsing the website.
2130 This is useful for geo\-restricted URLs. After youtube\-dl parsing, some
2131 URLs also require a proxy for playback, so this can pass that proxy
2132 information to mpv. Take note that SOCKS proxies aren\(aqt supported and
2133 https URLs also bypass the proxy. This is a limitation in FFmpeg.
2134 .INDENT 7.0
2135 .INDENT 3.5
2136 .IP "Example"
2137 .INDENT 0.0
2138 .IP \(bu 2
2139 \fB\-\-ytdl\-raw\-options=username=user,password=pass\fP
2140 .IP \(bu 2
2141 \fB\-\-ytdl\-raw\-options=force\-ipv6=\fP
2142 .IP \(bu 2
2143 \fB\-\-ytdl\-raw\-options=proxy=[http://127.0.0.1:3128]\fP
2144 .IP \(bu 2
2145 \fB\-\-ytdl\-raw\-options\-append=proxy=http://127.0.0.1:3128\fP
2146 .UNINDENT
2147 .UNINDENT
2148 .UNINDENT
2149 .TP
2150 .B \fB\-\-load\-stats\-overlay=<yes|no>\fP
2151 Enable the builtin script that shows useful playback information on a key
2152 binding (default: yes). By default, the \fBi\fP key is used (\fBI\fP to make
2153 the overlay permanent).
2154 .TP
2155 .B \fB\-\-player\-operation\-mode=<cplayer|pseudo\-gui>\fP
2156 For enabling "pseudo GUI mode", which means that the defaults for some
2157 options are changed. This option should not normally be used directly, but
2158 only by mpv internally, or mpv\-provided scripts, config files, or .desktop
2159 files.
2160 .UNINDENT
2161 .SS Video
2162 .INDENT 0.0
2163 .TP
2164 .B \fB\-\-vo=<driver>\fP
2165 Specify the video output backend to be used. See \fI\%VIDEO OUTPUT DRIVERS\fP for
2166 details and descriptions of available drivers.
2167 .TP
2168 .B \fB\-\-vd=<...>\fP
2169 Specify a priority list of video decoders to be used, according to their
2170 family and name. See \fB\-\-ad\fP for further details. Both of these options
2171 use the same syntax and semantics; the only difference is that they
2172 operate on different codec lists.
2173 .sp
2174 \fBNOTE:\fP
2175 .INDENT 7.0
2176 .INDENT 3.5
2177 See \fB\-\-vd=help\fP for a full list of available decoders.
2178 .UNINDENT
2179 .UNINDENT
2180 .TP
2181 .B \fB\-\-vf=<filter1[=parameter1:parameter2:...],filter2,...>\fP
2182 Specify a list of video filters to apply to the video stream. See
2183 \fI\%VIDEO FILTERS\fP for details and descriptions of the available filters.
2184 The option variants \fB\-\-vf\-add\fP, \fB\-\-vf\-pre\fP, \fB\-\-vf\-del\fP and
2185 \fB\-\-vf\-clr\fP exist to modify a previously specified list, but you
2186 should not need these for typical use.
2187 .TP
2188 .B \fB\-\-untimed\fP
2189 Do not sleep when outputting video frames. Useful for benchmarks when used
2190 with \fB\-\-no\-audio.\fP
2191 .TP
2192 .B \fB\-\-framedrop=<mode>\fP
2193 Skip displaying some frames to maintain A/V sync on slow systems, or
2194 playing high framerate video on video outputs that have an upper framerate
2195 limit.
2196 .sp
2197 The argument selects the drop methods, and can be one of the following:
2198 .INDENT 7.0
2199 .TP
2200 .B <no>
2201 Disable any framedropping.
2202 .TP
2203 .B <vo>
2204 Drop late frames on video output (default). This still decodes and
2205 filters all frames, but doesn\(aqt render them on the VO. It tries to query
2206 the display FPS (X11 only, not correct on multi\-monitor systems), or
2207 assumes infinite display FPS if that fails. Drops are indicated in
2208 the terminal status line as \fBDropped:\fP field. If the decoder is too slow,
2209 in theory all frames would have to be dropped (because all frames are
2210 too late) \- to avoid this, frame dropping stops if the effective
2211 framerate is below 10 FPS.
2212 .TP
2213 .B <decoder>
2214 Old, decoder\-based framedrop mode. (This is the same as \fB\-\-framedrop=yes\fP
2215 in mpv 0.5.x and before.) This tells the decoder to skip frames (unless
2216 they are needed to decode future frames). May help with slow systems,
2217 but can produce unwatchable choppy output, or even freeze the display
2218 completely. Not recommended.
2219 The \fB\-\-vd\-lavc\-framedrop\fP option controls what frames to drop.
2220 .TP
2221 .B <decoder+vo>
2222 Enable both modes. Not recommended.
2223 .UNINDENT
2224 .sp
2225 \fBNOTE:\fP
2226 .INDENT 7.0
2227 .INDENT 3.5
2228 \fB\-\-vo=vdpau\fP has its own code for the \fBvo\fP framedrop mode. Slight
2229 differences to other VOs are possible.
2230 .UNINDENT
2231 .UNINDENT
2232 .TP
2233 .B \fB\-\-video\-latency\-hacks=<yes|no>\fP
2234 Enable some things which tend to reduce video latency by 1 or 2 frames
2235 (default: no). Note that this option might be removed without notice once
2236 the player\(aqs timing code does not inherently need to do these things
2237 anymore.
2238 .sp
2239 This does:
2240 .INDENT 7.0
2241 .IP \(bu 2
2242 Use the demuxer reported FPS for frame dropping. This avoids that the
2243 player needs to decode 1 frame in advance, lowering total latency in
2244 effect. This also means that if the demuxer reported FPS is wrong, or
2245 the video filter chain changes FPS (e.g. deinterlacing), then it could
2246 drop too many or not enough frames.
2247 .IP \(bu 2
2248 Disable waiting for the first video frame. Normally the player waits for
2249 the first video frame to be fully rendered before starting playback
2250 properly. Some VOs will lazily initialize stuff when rendering the first
2251 frame, so if this is not done, there is some likeliness that the VO has
2252 to drop some frames if rendering the first frame takes longer than needed.
2253 .UNINDENT
2254 .TP
2255 .B \fB\-\-display\-fps=<fps>\fP
2256 Set the display FPS used with the \fB\-\-video\-sync=display\-*\fP modes. By
2257 default, a detected value is used. Keep in mind that setting an incorrect
2258 value (even if slightly incorrect) can ruin video playback. On multi\-monitor
2259 systems, there is a chance that the detected value is from the wrong
2260 monitor.
2261 .sp
2262 Set this option only if you have reason to believe the automatically
2263 determined value is wrong.
2264 .TP
2265 .B \fB\-\-hwdec=<api>\fP
2266 Specify the hardware video decoding API that should be used if possible.
2267 Whether hardware decoding is actually done depends on the video codec. If
2268 hardware decoding is not possible, mpv will fall back on software decoding.
2269 .sp
2270 \fB<api>\fP can be one of the following:
2271 .INDENT 7.0
2272 .TP
2273 .B no
2274 always use software decoding (default)
2275 .TP
2276 .B auto
2277 enable best hw decoder (see below)
2278 .TP
2279 .B yes
2280 exactly the same as \fBauto\fP
2281 .TP
2282 .B auto\-copy
2283 enable best hw decoder with copy\-back (see below)
2284 .TP
2285 .B vdpau
2286 requires \fB\-\-vo=gpu\fP with \fB\-\-gpu\-context=x11\fP,
2287 or \fB\-\-vo=vdpau\fP (Linux only)
2288 .TP
2289 .B vdpau\-copy
2290 copies video back into system RAM (Linux with some GPUs only)
2291 .TP
2292 .B vaapi
2293 requires \fB\-\-vo=gpu\fP or \fB\-\-vo=vaapi\fP (Linux only)
2294 .TP
2295 .B vaapi\-copy
2296 copies video back into system RAM (Linux with some GPUs only)
2297 .TP
2298 .B videotoolbox
2299 requires \fB\-\-vo=gpu\fP (OS X 10.8 and up),
2300 or \fB\-\-vo=opengl\-cb\fP (iOS 9.0 and up)
2301 .TP
2302 .B videotoolbox\-copy
2303 copies video back into system RAM (OS X 10.8 or iOS 9.0 and up)
2304 .TP
2305 .B dxva2
2306 requires \fB\-\-vo=gpu\fP with \fB\-\-gpu\-context=d3d11\fP,
2307 \fB\-\-gpu\-context=angle\fP or \fB\-\-gpu\-context=dxinterop\fP
2308 (Windows only)
2309 .TP
2310 .B dxva2\-copy
2311 copies video back to system RAM (Windows only)
2312 .TP
2313 .B d3d11va
2314 requires \fB\-\-vo=gpu\fP with \fB\-\-gpu\-context=d3d11\fP or
2315 \fB\-\-gpu\-context=angle\fP (Windows 8+ only)
2316 .TP
2317 .B d3d11va\-copy
2318 copies video back to system RAM (Windows 8+ only)
2319 .TP
2320 .B mediacodec
2321 requires \fB\-\-vo=mediacodec_embed\fP (Android only)
2322 .TP
2323 .B mediacodec\-copy
2324 copies video back to system RAM (Android only)
2325 .TP
2326 .B mmal
2327 requires \fB\-\-vo=gpu\fP (Raspberry Pi only \- default if available)
2328 .TP
2329 .B mmal\-copy
2330 copies video back to system RAM (Raspberry Pi only)
2331 .TP
2332 .B cuda
2333 requires \fB\-\-vo=gpu\fP (Any platform CUDA is available)
2334 .TP
2335 .B cuda\-copy
2336 copies video back to system RAM (Any platform CUDA is available)
2337 .TP
2338 .B nvdec
2339 requires \fB\-\-vo=gpu\fP (Any platform CUDA is available)
2340 .TP
2341 .B nvdec\-copy
2342 copies video back to system RAM (Any platform CUDA is available)
2343 .TP
2344 .B crystalhd
2345 copies video back to system RAM (Any platform supported by hardware)
2346 .TP
2347 .B rkmpp
2348 requires \fB\-\-vo=gpu\fP (some RockChip devices only)
2349 .UNINDENT
2350 .sp
2351 \fBauto\fP tries to automatically enable hardware decoding using the first
2352 available method. This still depends what VO you are using. For example,
2353 if you are not using \fB\-\-vo=gpu\fP or \fB\-\-vo=vdpau\fP, vdpau decoding will
2354 never be enabled. Also note that if the first found method doesn\(aqt actually
2355 work, it will always fall back to software decoding, instead of trying the
2356 next method (might matter on some Linux systems).
2357 .sp
2358 \fBauto\-copy\fP selects only modes that copy the video data back to system
2359 memory after decoding. This selects modes like \fBvaapi\-copy\fP (and so on).
2360 If none of these work, hardware decoding is disabled. This mode is always
2361 guaranteed to incur no additional loss compared to software decoding, and
2362 will allow CPU processing with video filters.
2363 .sp
2364 The \fBvaapi\fP mode, if used with \fB\-\-vo=gpu\fP, requires Mesa 11 and most
2365 likely works with Intel GPUs only. It also requires the opengl EGL backend.
2366 .sp
2367 The \fBcuda\fP and \fBcuda\-copy\fP modes provides deinterlacing in the decoder
2368 which is useful as there is no other deinterlacing mechanism in the gpu
2369 output path. To use this deinterlacing you must pass the option:
2370 \fBvd\-lavc\-o=deint=[weave|bob|adaptive]\fP\&.
2371 Pass \fBweave\fP (or leave the option unset) to not attempt any
2372 deinterlacing. \fBcuda\fP should always be preferred unless the \fBgpu\fP
2373 vo is not being used or filters are required.
2374 .sp
2375 \fBnvdec\fP is a newer implementation of CUVID/CUDA decoding, which uses the
2376 FFmpeg decoders for file parsing. Experimental, is known not to correctly
2377 check whether decoding is supported by the hardware at all. Deinterlacing
2378 is not supported. Since this uses FFmpeg\(aqs codec parsers, it is expected
2379 that this generally causes fewer issues than \fBcuda\fP\&.
2380 .sp
2381 Most video filters will not work with hardware decoding as they are
2382 primarily implemented on the CPU. Some exceptions are \fBvdpaupp\fP,
2383 \fBvdpaurb\fP and \fBvavpp\fP\&. See \fI\%VIDEO FILTERS\fP for more details.
2384 .sp
2385 The \fB\&...\-copy\fP modes (e.g. \fBdxva2\-copy\fP) allow you to use hardware
2386 decoding with any VO, backend or filter. Because these copy the decoded
2387 video back to system RAM, they\(aqre likely less efficient than the direct
2388 modes (like e.g. \fBdxva2\fP), and probably not more efficient than software
2389 decoding except for some codecs (e.g. HEVC).
2390 .sp
2391 \fBNOTE:\fP
2392 .INDENT 7.0
2393 .INDENT 3.5
2394 When using this switch, hardware decoding is still only done for some
2395 codecs. See \fB\-\-hwdec\-codecs\fP to enable hardware decoding for more
2396 codecs.
2397 .UNINDENT
2398 .UNINDENT
2399 .sp
2400 \fBNOTE:\fP
2401 .INDENT 7.0
2402 .INDENT 3.5
2403 Most non\-copy methods only work with the OpenGL GPU backend. Currently,
2404 only the \fBnvdec\fP and \fBcuda\fP methods work with Vulkan.
2405 .UNINDENT
2406 .UNINDENT
2407 .INDENT 7.0
2408 .INDENT 3.5
2409 .IP "Quality reduction with hardware decoding"
2410 .sp
2411 In theory, hardware decoding does not reduce video quality (at least
2412 for the codecs h264 and HEVC). However, due to restrictions in video
2413 output APIs, as well as bugs in the actual hardware decoders, there can
2414 be some loss, or even blatantly incorrect results.
2415 .sp
2416 In some cases, RGB conversion is forced, which means the RGB conversion
2417 is performed by the hardware decoding API, instead of the shaders
2418 used by \fB\-\-vo=gpu\fP\&. This means certain colorspaces may not display
2419 correctly, and certain filtering (such as debanding) cannot be applied
2420 in an ideal way. This will also usually force the use of low quality
2421 chroma scalers instead of the one specified by \fB\-\-cscale\fP\&. In other
2422 cases, hardware decoding can also reduce the bit depth of the decoded
2423 image, which can introduce banding or precision loss for 10\-bit files.
2424 .sp
2425 \fBvdpau\fP is usually safe, except for 10 bit video. If deinterlacing
2426 enabled (or the \fBvdpaupp\fP video filter is active in general), it
2427 forces RGB conversion. The latter currently does not treat certain
2428 colorspaces like BT.2020 correctly.
2429 .sp
2430 \fBvaapi\fP and \fBd3d11va\fP are safe. Enabling deinterlacing (or simply
2431 their respective post\-processing filters) will possibly at least reduce
2432 color quality by converting the output to a 8 bit format.
2433 .sp
2434 \fBdxva2\fP is not safe. It appears to always use BT.601 for forced RGB
2435 conversion, but actual behavior depends on the GPU drivers. Some drivers
2436 appear to convert to limited range RGB, which gives a faded appearance.
2437 In addition to driver\-specific behavior, global system settings might
2438 affect this additionally. This can give incorrect results even with
2439 completely ordinary video sources.
2440 .sp
2441 \fBrpi\fP always uses the hardware overlay renderer, even with
2442 \fB\-\-vo=gpu\fP\&.
2443 .sp
2444 \fBcuda\fP should be safe, but it has been reported to corrupt the
2445 timestamps causing glitched, flashing frames on some files. It can also
2446 sometimes cause massive framedrops for unknown reasons. Caution is
2447 advised.
2448 .sp
2449 \fBcrystalhd\fP is not safe. It always converts to 4:2:2 YUV, which
2450 may be lossy, depending on how chroma sub\-sampling is done during
2451 conversion. It also discards the top left pixel of each frame for
2452 some reason.
2453 .sp
2454 All other methods, in particular the copy\-back methods (like
2455 \fBdxva2\-copy\fP etc.) should hopefully be safe, although they can still
2456 cause random decoding issues. At the very least, they shouldn\(aqt affect
2457 the colors of the image.
2458 .sp
2459 In particular, \fBauto\-copy\fP will only select "safe" modes
2460 (although potentially slower than other methods), but there\(aqs still no
2461 guarantee the chosen hardware decoder will actually work correctly.
2462 .sp
2463 In general, it\(aqs very strongly advised to avoid hardware decoding
2464 unless \fBabsolutely\fP necessary, i.e. if your CPU is insufficient to
2465 decode the file in questions. If you run into any weird decoding issues,
2466 frame glitches or discoloration, and you have \fB\-\-hwdec\fP turned on,
2467 the first thing you should try is disabling it.
2468 .UNINDENT
2469 .UNINDENT
2470 .TP
2471 .B \fB\-\-gpu\-hwdec\-interop=<auto|all|no|name>\fP
2472 This option is for troubleshooting hwdec interop issues. Since it\(aqs a
2473 debugging option, its semantics may change at any time.
2474 .sp
2475 This is useful for the \fBgpu\fP and \fBopengl\-cb\fP VOs for selecting which
2476 hwdec interop context to use exactly. Effectively it also can be used
2477 to block loading of certain backends.
2478 .sp
2479 If set to \fBauto\fP (default), the behavior depends on the VO: for \fBgpu\fP,
2480 it does nothing, and the interop context is loaded on demand (when the
2481 decoder probes for \fB\-\-hwdec\fP support). For \fBopengl\-cb\fP, which has
2482 has no on\-demand loading, this is equivalent to \fBall\fP\&.
2483 .sp
2484 The empty string is equivalent to \fBauto\fP\&.
2485 .sp
2486 If set to \fBall\fP, it attempts to load all interop contexts at GL context
2487 creation time.
2488 .sp
2489 Other than that, a specific backend can be set, and the list of them can
2490 be queried with \fBhelp\fP (mpv CLI only).
2491 .sp
2492 Runtime changes to this are ignored (the current option value is used
2493 whenever the renderer is created).
2494 .sp
2495 The old aliases \fB\-\-opengl\-hwdec\-interop\fP and \fB\-\-hwdec\-preload\fP are
2496 barely related to this anymore, but will be somewhat compatible in some
2497 cases.
2498 .TP
2499 .B \fB\-\-hwdec\-extra\-frames=<N>\fP
2500 Number of GPU frames hardware decoding should preallocate (default: see
2501 \fB\-\-list\-options\fP output). If this is too low, frame allocation may fail
2502 during decoding, and video frames might get dropped and/or corrupted.
2503 Setting it too high simply wastes GPU memory and has no advantages.
2504 .sp
2505 This value is used only for hardware decoding APIs which require
2506 preallocating surfaces (known examples include \fBd3d11va\fP and \fBvaapi\fP).
2507 For other APIs, frames are allocated as needed. The details depend on the
2508 libavcodec implementations of the hardware decoders.
2509 .sp
2510 The required number of surfaces depends on dynamic runtime situations. The
2511 default is a fixed value that is thought to be sufficient for most uses. But
2512 in certain situations, it may not be enough.
2513 .TP
2514 .B \fB\-\-hwdec\-image\-format=<name>\fP
2515 Set the internal pixel format used by hardware decoding via \fB\-\-hwdec\fP
2516 (default \fBno\fP). The special value \fBno\fP selects an implementation
2517 specific standard format. Most decoder implementations support only one
2518 format, and will fail to initialize if the format is not supported.
2519 .sp
2520 Some implementations might support multiple formats. In particular,
2521 videotoolbox is known to require \fBuyvy422\fP for good performance on some
2522 older hardware. d3d11va can always use \fByuv420p\fP, which uses an opaque
2523 format, with likely no advantages.
2524 .TP
2525 .B \fB\-\-cuda\-decode\-device=<auto|0..>\fP
2526 Choose the GPU device used for decoding when using the \fBcuda\fP or
2527 \fBnvdec\fP hwdecs with the OpenGL GPU backend.
2528 .sp
2529 By default, the device that is being used to provide \fBgpu\fP output will
2530 also be used for decoding (and in the vast majority of cases, only one
2531 GPU will be present).
2532 .sp
2533 Note that when using the \fBcuda\-copy\fP or \fBnvdec\-copy\fP hwdec, a
2534 different option must be passed: \fB\-\-vd\-lavc\-o=gpu=<0..>\fP\&.
2535 .sp
2536 Note that this option is not available with the Vulkan GPU backend. With
2537 Vulkan, decoding must always happen on the display device.
2538 .TP
2539 .B \fB\-\-vaapi\-device=<device file>\fP
2540 Choose the DRM device for \fBvaapi\-copy\fP\&. This should be the path to a
2541 DRM device file. (Default: \fB/dev/dri/renderD128\fP)
2542 .TP
2543 .B \fB\-\-panscan=<0.0\-1.0>\fP
2544 Enables pan\-and\-scan functionality (cropping the sides of e.g. a 16:9
2545 video to make it fit a 4:3 display without black bands). The range
2546 controls how much of the image is cropped. May not work with all video
2547 output drivers.
2548 .sp
2549 This option has no effect if \fB\-\-video\-unscaled\fP option is used.
2550 .TP
2551 .B \fB\-\-video\-aspect\-override=<ratio|no>\fP
2552 Override video aspect ratio, in case aspect information is incorrect or
2553 missing in the file being played.
2554 .sp
2555 These values have special meaning:
2556 .INDENT 7.0
2557 .TP
2558 .B 0
2559 disable aspect ratio handling, pretend the video has square pixels
2560 .TP
2561 .B no
2562 same as \fB0\fP
2563 .TP
2564 .B \-1
2565 use the video stream or container aspect (default)
2566 .UNINDENT
2567 .sp
2568 But note that handling of these special values might change in the future.
2569 .INDENT 7.0
2570 .INDENT 3.5
2571 .IP "Examples"
2572 .INDENT 0.0
2573 .IP \(bu 2
2574 \fB\-\-video\-aspect\-override=4:3\fP or \fB\-\-video\-aspect\-override=1.3333\fP
2575 .IP \(bu 2
2576 \fB\-\-video\-aspect\-override=16:9\fP or \fB\-\-video\-aspect\-override=1.7777\fP
2577 .IP \(bu 2
2578 \fB\-\-no\-video\-aspect\-override\fP or \fB\-\-video\-aspect\-override=no\fP
2579 .UNINDENT
2580 .UNINDENT
2581 .UNINDENT
2582 .TP
2583 .B \fB\-\-video\-aspect\-method=<bitstream|container>\fP
2584 This sets the default video aspect determination method (if the aspect is
2585 _not_ overridden by the user with \fB\-\-video\-aspect\-override\fP or others).
2586 .INDENT 7.0
2587 .TP
2588 .B container
2589 Strictly prefer the container aspect ratio. This is apparently
2590 the default behavior with VLC, at least with Matroska. Note that
2591 if the container has no aspect ratio set, the behavior is the
2592 same as with bitstream.
2593 .TP
2594 .B bitstream
2595 Strictly prefer the bitstream aspect ratio, unless the bitstream
2596 aspect ratio is not set. This is apparently the default behavior
2597 with XBMC/kodi, at least with Matroska.
2598 .UNINDENT
2599 .sp
2600 The current default for mpv is \fBcontainer\fP\&.
2601 .sp
2602 Normally you should not set this. Try the various choices if you encounter
2603 video that has the wrong aspect ratio in mpv, but seems to be correct in
2604 other players.
2605 .TP
2606 .B \fB\-\-video\-unscaled=<no|yes|downscale\-big>\fP
2607 Disable scaling of the video. If the window is larger than the video,
2608 black bars are added. Otherwise, the video is cropped, unless the option
2609 is set to \fBdownscale\-big\fP, in which case the video is fit to window. The
2610 video still can be influenced by the other \fB\-\-video\-...\fP options. This
2611 option disables the effect of \fB\-\-panscan\fP\&.
2612 .sp
2613 Note that the scaler algorithm may still be used, even if the video isn\(aqt
2614 scaled. For example, this can influence chroma conversion. The video will
2615 also still be scaled in one dimension if the source uses non\-square pixels
2616 (e.g. anamorphic widescreen DVDs).
2617 .sp
2618 This option is disabled if the \fB\-\-no\-keepaspect\fP option is used.
2619 .TP
2620 .B \fB\-\-video\-pan\-x=<value>\fP, \fB\-\-video\-pan\-y=<value>\fP
2621 Moves the displayed video rectangle by the given value in the X or Y
2622 direction. The unit is in fractions of the size of the scaled video (the
2623 full size, even if parts of the video are not visible due to panscan or
2624 other options).
2625 .sp
2626 For example, displaying a 1280x720 video fullscreen on a 1680x1050 screen
2627 with \fB\-\-video\-pan\-x=\-0.1\fP would move the video 168 pixels to the left
2628 (making 128 pixels of the source video invisible).
2629 .sp
2630 This option is disabled if the \fB\-\-no\-keepaspect\fP option is used.
2631 .TP
2632 .B \fB\-\-video\-rotate=<0\-359|no>\fP
2633 Rotate the video clockwise, in degrees. Currently supports 90° steps only.
2634 If \fBno\fP is given, the video is never rotated, even if the file has
2635 rotation metadata. (The rotation value is added to the rotation metadata,
2636 which means the value \fB0\fP would rotate the video according to the
2637 rotation metadata.)
2638 .TP
2639 .B \fB\-\-video\-zoom=<value>\fP
2640 Adjust the video display scale factor by the given value. The parameter is
2641 given log 2. For example, \fB\-\-video\-zoom=0\fP is unscaled,
2642 \fB\-\-video\-zoom=1\fP is twice the size, \fB\-\-video\-zoom=\-2\fP is one fourth of
2643 the size, and so on.
2644 .sp
2645 This option is disabled if the \fB\-\-no\-keepaspect\fP option is used.
2646 .TP
2647 .B \fB\-\-video\-align\-x=<\-1\-1>\fP, \fB\-\-video\-align\-y=<\-1\-1>\fP
2648 Moves the video rectangle within the black borders, which are usually added
2649 to pad the video to screen if video and screen aspect ratios are different.
2650 \fB\-\-video\-align\-y=\-1\fP would move the video to the top of the screen
2651 (leaving a border only on the bottom), a value of \fB0\fP centers it
2652 (default), and a value of \fB1\fP would put the video at the bottom of the
2653 screen.
2654 .sp
2655 If video and screen aspect match perfectly, these options do nothing.
2656 .sp
2657 This option is disabled if the \fB\-\-no\-keepaspect\fP option is used.
2658 .TP
2659 .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
2660 Set extra video margins on each border (default: 0). Each value is a ratio
2661 of the window size, using a range 0.0\-1.0. For example, setting the option
2662 \fB\-\-video\-margin\-ratio\-right=0.2\fP at a window size of 1000 pixels will add
2663 a 200 pixels border on the right side of the window.
2664 .sp
2665 The video is "boxed" by these margins. The window size is not changed. In
2666 particular it does not enlarge the window, and the margins will cause the
2667 video to be downscaled by default. This may or may not change in the future.
2668 .sp
2669 The margins are applied after 90° video rotation, but before any other video
2670 transformations.
2671 .sp
2672 This option is disabled if the \fB\-\-no\-keepaspect\fP option is used.
2673 .sp
2674 Subtitles still may use the margins, depending on \fB\-\-sub\-use\-margins\fP and
2675 similar options.
2676 .sp
2677 These options were created for the OSC. Some odd decisions, such as making
2678 the margin values a ratio (instead of pixels), were made for the sake of
2679 the OSC. It\(aqs possible that these options may be replaced by ones that are
2680 more generally useful. The behavior of these options may change to fit
2681 OSC requirements better, too.
2682 .TP
2683 .B \fB\-\-correct\-pts\fP, \fB\-\-no\-correct\-pts\fP
2684 \fB\-\-no\-correct\-pts\fP switches mpv to a mode where video timing is
2685 determined using a fixed framerate value (either using the \fB\-\-fps\fP
2686 option, or using file information). Sometimes, files with very broken
2687 timestamps can be played somewhat well in this mode. Note that video
2688 filters, subtitle rendering, seeking (including hr\-seeks and backstepping),
2689 and audio synchronization can be completely broken in this mode.
2690 .TP
2691 .B \fB\-\-fps=<float>\fP
2692 Override video framerate. Useful if the original value is wrong or missing.
2693 .sp
2694 \fBNOTE:\fP
2695 .INDENT 7.0
2696 .INDENT 3.5
2697 Works in \fB\-\-no\-correct\-pts\fP mode only.
2698 .UNINDENT
2699 .UNINDENT
2700 .TP
2701 .B \fB\-\-deinterlace=<yes|no>\fP
2702 Enable or disable interlacing (default: no).
2703 Interlaced video shows ugly comb\-like artifacts, which are visible on
2704 fast movement. Enabling this typically inserts the yadif video filter in
2705 order to deinterlace the video, or lets the video output apply deinterlacing
2706 if supported.
2707 .sp
2708 This behaves exactly like the \fBdeinterlace\fP input property (usually
2709 mapped to \fBd\fP).
2710 .sp
2711 Keep in mind that this \fBwill\fP conflict with manually inserted
2712 deinterlacing filters, unless you take care. (Since mpv 0.27.0, even the
2713 hardware deinterlace filters will conflict. Also since that version,
2714 \fB\-\-deinterlace=auto\fP was removed, which used to mean that the default
2715 interlacing option of possibly inserted video filters was used.)
2716 .sp
2717 Note that this will make video look worse if it\(aqs not actually interlaced.
2718 .TP
2719 .B \fB\-\-frames=<number>\fP
2720 Play/convert only first \fB<number>\fP video frames, then quit.
2721 .sp
2722 \fB\-\-frames=0\fP loads the file, but immediately quits before initializing
2723 playback. (Might be useful for scripts which just want to determine some
2724 file properties.)
2725 .sp
2726 For audio\-only playback, any value greater than 0 will quit playback
2727 immediately after initialization. The value 0 works as with video.
2728 .TP
2729 .B \fB\-\-video\-output\-levels=<outputlevels>\fP
2730 RGB color levels used with YUV to RGB conversion. Normally, output devices
2731 such as PC monitors use full range color levels. However, some TVs and
2732 video monitors expect studio RGB levels. Providing full range output to a
2733 device expecting studio level input results in crushed blacks and whites,
2734 the reverse in dim gray blacks and dim whites.
2735 .sp
2736 Not all VOs support this option. Some will silently ignore it.
2737 .sp
2738 Available color ranges are:
2739 .INDENT 7.0
2740 .TP
2741 .B auto
2742 automatic selection (equals to full range) (default)
2743 .TP
2744 .B limited
2745 limited range (16\-235 per component), studio levels
2746 .TP
2747 .B full
2748 full range (0\-255 per component), PC levels
2749 .UNINDENT
2750 .sp
2751 \fBNOTE:\fP
2752 .INDENT 7.0
2753 .INDENT 3.5
2754 It is advisable to use your graphics driver\(aqs color range option
2755 instead, if available.
2756 .UNINDENT
2757 .UNINDENT
2758 .TP
2759 .B \fB\-\-hwdec\-codecs=<codec1,codec2,...|all>\fP
2760 Allow hardware decoding for a given list of codecs only. The special value
2761 \fBall\fP always allows all codecs.
2762 .sp
2763 You can get the list of allowed codecs with \fBmpv \-\-vd=help\fP\&. Remove the
2764 prefix, e.g. instead of \fBlavc:h264\fP use \fBh264\fP\&.
2765 .sp
2766 By default, this is set to \fBh264,vc1,hevc,vp9\fP\&. Note that
2767 the hardware acceleration special codecs like \fBh264_vdpau\fP are not
2768 relevant anymore, and in fact have been removed from Libav in this form.
2769 .sp
2770 This is usually only needed with broken GPUs, where a codec is reported
2771 as supported, but decoding causes more problems than it solves.
2772 .INDENT 7.0
2773 .INDENT 3.5
2774 .IP "Example"
2775 .INDENT 0.0
2776 .TP
2777 .B \fBmpv \-\-hwdec=vdpau \-\-vo=vdpau \-\-hwdec\-codecs=h264,mpeg2video\fP
2778 Enable vdpau decoding for h264 and mpeg2 only.
2779 .UNINDENT
2780 .UNINDENT
2781 .UNINDENT
2782 .TP
2783 .B \fB\-\-vd\-lavc\-check\-hw\-profile=<yes|no>\fP
2784 Check hardware decoder profile (default: yes). If \fBno\fP is set, the
2785 highest profile of the hardware decoder is unconditionally selected, and
2786 decoding is forced even if the profile of the video is higher than that.
2787 The result is most likely broken decoding, but may also help if the
2788 detected or reported profiles are somehow incorrect.
2789 .TP
2790 .B \fB\-\-vd\-lavc\-software\-fallback=<yes|no|N>\fP
2791 Fallback to software decoding if the hardware\-accelerated decoder fails
2792 (default: 3). If this is a number, then fallback will be triggered if
2793 N frames fail to decode in a row. 1 is equivalent to \fByes\fP\&.
2794 .TP
2795 .B \fB\-\-vd\-lavc\-dr=<yes|no>\fP
2796 Enable direct rendering (default: yes). If this is set to \fByes\fP, the
2797 video will be decoded directly to GPU video memory (or staging buffers).
2798 This can speed up video upload, and may help with large resolutions or
2799 slow hardware. This works only with the following VOs:
2800 .INDENT 7.0
2801 .INDENT 3.5
2802 .INDENT 0.0
2803 .IP \(bu 2
2804 \fBgpu\fP: requires at least OpenGL 4.4 or Vulkan.
2805 .UNINDENT
2806 .UNINDENT
2807 .UNINDENT
2808 .sp
2809 (In particular, this can\(aqt be made work with \fBopengl\-cb\fP, but the libmpv
2810 render API has optional support.)
2811 .sp
2812 Using video filters of any kind that write to the image data (or output
2813 newly allocated frames) will silently disable the DR code path.
2814 .TP
2815 .B \fB\-\-vd\-lavc\-bitexact\fP
2816 Only use bit\-exact algorithms in all decoding steps (for codec testing).
2817 .TP
2818 .B \fB\-\-vd\-lavc\-fast\fP (MPEG\-2, MPEG\-4, and H.264 only)
2819 Enable optimizations which do not comply with the format specification and
2820 potentially cause problems, like simpler dequantization, simpler motion
2821 compensation, assuming use of the default quantization matrix, assuming YUV
2822 4:2:0 and skipping a few checks to detect damaged bitstreams.
2823 .TP
2824 .B \fB\-\-vd\-lavc\-o=<key>=<value>[,<key>=<value>[,...]]\fP
2825 Pass AVOptions to libavcodec decoder. Note, a patch to make the \fBo=\fP
2826 unneeded and pass all unknown options through the AVOption system is
2827 welcome. A full list of AVOptions can be found in the FFmpeg manual.
2828 .sp
2829 Some options which used to be direct options can be set with this
2830 mechanism, like \fBbug\fP, \fBgray\fP, \fBidct\fP, \fBec\fP, \fBvismv\fP,
2831 \fBskip_top\fP (was \fBst\fP), \fBskip_bottom\fP (was \fBsb\fP), \fBdebug\fP\&.
2832 .INDENT 7.0
2833 .INDENT 3.5
2834 .IP "Example"
2835 .sp
2836 \fB\-\-vd\-lavc\-o=debug=pict\fP
2837 .UNINDENT
2838 .UNINDENT
2839 .TP
2840 .B \fB\-\-vd\-lavc\-show\-all=<yes|no>\fP
2841 Show even broken/corrupt frames (default: no). If this option is set to
2842 no, libavcodec won\(aqt output frames that were either decoded before an
2843 initial keyframe was decoded, or frames that are recognized as corrupted.
2844 .TP
2845 .B \fB\-\-vd\-lavc\-skiploopfilter=<skipvalue> (H.264 only)\fP
2846 Skips the loop filter (AKA deblocking) during H.264 decoding. Since
2847 the filtered frame is supposed to be used as reference for decoding
2848 dependent frames, this has a worse effect on quality than not doing
2849 deblocking on e.g. MPEG\-2 video. But at least for high bitrate HDTV,
2850 this provides a big speedup with little visible quality loss.
2851 .sp
2852 \fB<skipvalue>\fP can be one of the following:
2853 .INDENT 7.0
2854 .TP
2855 .B none
2856 Never skip.
2857 .TP
2858 .B default
2859 Skip useless processing steps (e.g. 0 size packets in AVI).
2860 .TP
2861 .B nonref
2862 Skip frames that are not referenced (i.e. not used for
2863 decoding other frames, the error cannot "build up").
2864 .TP
2865 .B bidir
2866 Skip B\-Frames.
2867 .TP
2868 .B nonkey
2869 Skip all frames except keyframes.
2870 .TP
2871 .B all
2872 Skip all frames.
2873 .UNINDENT
2874 .TP
2875 .B \fB\-\-vd\-lavc\-skipidct=<skipvalue> (MPEG\-1/2 only)\fP
2876 Skips the IDCT step. This degrades quality a lot in almost all cases
2877 (see skiploopfilter for available skip values).
2878 .TP
2879 .B \fB\-\-vd\-lavc\-skipframe=<skipvalue>\fP
2880 Skips decoding of frames completely. Big speedup, but jerky motion and
2881 sometimes bad artifacts (see skiploopfilter for available skip values).
2882 .TP
2883 .B \fB\-\-vd\-lavc\-framedrop=<skipvalue>\fP
2884 Set framedropping mode used with \fB\-\-framedrop\fP (see skiploopfilter for
2885 available skip values).
2886 .TP
2887 .B \fB\-\-vd\-lavc\-threads=<N>\fP
2888 Number of threads to use for decoding. Whether threading is actually
2889 supported depends on codec (default: 0). 0 means autodetect number of cores
2890 on the machine and use that, up to the maximum of 16. You can set more than
2891 16 threads manually.
2892 .TP
2893 .B \fB\-\-vd\-lavc\-assume\-old\-x264=<yes|no>\fP
2894 Assume the video was encoded by an old, buggy x264 version (default: no).
2895 Normally, this is autodetected by libavcodec. But if the bitstream contains
2896 no x264 version info (or it was somehow skipped), and the stream was in fact
2897 encoded by an old x264 version (build 150 or earlier), and if the stream
2898 uses \fB4:4:4\fP chroma, then libavcodec will by default show corrupted video.
2899 This option sets the libavcodec \fBx264_build\fP option to \fB150\fP, which
2900 means that if the stream contains no version info, or was not encoded by
2901 x264 at all, it assumes it was encoded by the old version. Enabling this
2902 option is pretty safe if you want your broken files to work, but in theory
2903 this can break on streams not encoded by x264, or if a stream encoded by a
2904 newer x264 version contains no version info.
2905 .TP
2906 .B \fB\-\-swapchain\-depth=<N>\fP
2907 Allow up to N in\-flight frames. This essentially controls the frame
2908 latency. Increasing the swapchain depth can improve pipelining and prevent
2909 missed vsyncs, but increases visible latency. This option only mandates an
2910 upper limit, the implementation can use a lower latency than requested
2911 internally. A setting of 1 means that the VO will wait for every frame to
2912 become visible before starting to render the next frame. (Default: 3)
2913 .UNINDENT
2914 .SS Audio
2915 .INDENT 0.0
2916 .TP
2917 .B \fB\-\-audio\-pitch\-correction=<yes|no>\fP
2918 If this is enabled (default), playing with a speed different from normal
2919 automatically inserts the \fBscaletempo\fP audio filter. For details, see
2920 audio filter section.
2921 .TP
2922 .B \fB\-\-audio\-device=<name>\fP
2923 Use the given audio device. This consists of the audio output name, e.g.
2924 \fBalsa\fP, followed by \fB/\fP, followed by the audio output specific device
2925 name. The default value for this option is \fBauto\fP, which tries every audio
2926 output in preference order with the default device.
2927 .sp
2928 You can list audio devices with \fB\-\-audio\-device=help\fP\&. This outputs the
2929 device name in quotes, followed by a description. The device name is what
2930 you have to pass to the \fB\-\-audio\-device\fP option. The list of audio devices
2931 can be retrieved by API by using the \fBaudio\-device\-list\fP property.
2932 .sp
2933 While the option normally takes one of the strings as indicated by the
2934 methods above, you can also force the device for most AOs by building it
2935 manually. For example \fBname/foobar\fP forces the AO \fBname\fP to use the
2936 device \fBfoobar\fP\&. However, the \fB\-\-ao\fP option will strictly force a
2937 specific AO. To avoid confusion, don\(aqt use \fB\-\-ao\fP and \fB\-\-audio\-device\fP
2938 together.
2939 .INDENT 7.0
2940 .INDENT 3.5
2941 .IP "Example for ALSA"
2942 .sp
2943 MPlayer and mplayer2 required you to replace any \(aq,\(aq with \(aq.\(aq and
2944 any \(aq:\(aq with \(aq=\(aq in the ALSA device name. For example, to use the
2945 device named \fBdmix:default\fP, you had to do:
2946 .INDENT 0.0
2947 .INDENT 3.5
2948 \fB\-ao alsa:device=dmix=default\fP
2949 .UNINDENT
2950 .UNINDENT
2951 .sp
2952 In mpv you could instead use:
2953 .INDENT 0.0
2954 .INDENT 3.5
2955 \fB\-\-audio\-device=alsa/dmix:default\fP
2956 .UNINDENT
2957 .UNINDENT
2958 .UNINDENT
2959 .UNINDENT
2960 .TP
2961 .B \fB\-\-audio\-exclusive=<yes|no>\fP
2962 Enable exclusive output mode. In this mode, the system is usually locked
2963 out, and only mpv will be able to output audio.
2964 .sp
2965 This only works for some audio outputs, such as \fBwasapi\fP and
2966 \fBcoreaudio\fP\&. Other audio outputs silently ignore this options. They either
2967 have no concept of exclusive mode, or the mpv side of the implementation is
2968 missing.
2969 .TP
2970 .B \fB\-\-audio\-fallback\-to\-null=<yes|no>\fP
2971 If no audio device can be opened, behave as if \fB\-\-ao=null\fP was given. This
2972 is useful in combination with \fB\-\-audio\-device\fP: instead of causing an
2973 error if the selected device does not exist, the client API user (or a
2974 Lua script) could let playback continue normally, and check the
2975 \fBcurrent\-ao\fP and \fBaudio\-device\-list\fP properties to make high\-level
2976 decisions about how to continue.
2977 .TP
2978 .B \fB\-\-ao=<driver>\fP
2979 Specify the audio output drivers to be used. See \fI\%AUDIO OUTPUT DRIVERS\fP for
2980 details and descriptions of available drivers.
2981 .TP
2982 .B \fB\-\-af=<filter1[=parameter1:parameter2:...],filter2,...>\fP
2983 Specify a list of audio filters to apply to the audio stream. See
2984 \fI\%AUDIO FILTERS\fP for details and descriptions of the available filters.
2985 The option variants \fB\-\-af\-add\fP, \fB\-\-af\-pre\fP, \fB\-\-af\-del\fP and
2986 \fB\-\-af\-clr\fP exist to modify a previously specified list, but you
2987 should not need these for typical use.
2988 .TP
2989 .B \fB\-\-audio\-spdif=<codecs>\fP
2990 List of codecs for which compressed audio passthrough should be used. This
2991 works for both classic S/PDIF and HDMI.
2992 .sp
2993 Possible codecs are \fBac3\fP, \fBdts\fP, \fBdts\-hd\fP, \fBeac3\fP, \fBtruehd\fP\&.
2994 Multiple codecs can be specified by separating them with \fB,\fP\&. \fBdts\fP
2995 refers to low bitrate DTS core, while \fBdts\-hd\fP refers to DTS MA (receiver
2996 and OS support varies). If both \fBdts\fP and \fBdts\-hd\fP are specified, it
2997 behaves equivalent to specifying \fBdts\-hd\fP only.
2998 .sp
2999 In earlier mpv versions you could use \fB\-\-ad\fP to force the spdif wrapper.
3000 This does not work anymore.
3001 .INDENT 7.0
3002 .INDENT 3.5
3003 .IP "Warning"
3004 .sp
3005 There is not much reason to use this. HDMI supports uncompressed
3006 multichannel PCM, and mpv supports lossless DTS\-HD decoding via
3007 FFmpeg\(aqs new DCA decoder (based on libdcadec).
3008 .UNINDENT
3009 .UNINDENT
3010 .TP
3011 .B \fB\-\-ad=<decoder1,decoder2,...[\-]>\fP
3012 Specify a priority list of audio decoders to be used, according to their
3013 decoder name. When determining which decoder to use, the first decoder that
3014 matches the audio format is selected. If that is unavailable, the next
3015 decoder is used. Finally, it tries all other decoders that are not
3016 explicitly selected or rejected by the option.
3017 .sp
3018 \fB\-\fP at the end of the list suppresses fallback on other available
3019 decoders not on the \fB\-\-ad\fP list. \fB+\fP in front of an entry forces the
3020 decoder. Both of these should not normally be used, because they break
3021 normal decoder auto\-selection! Both of these methods are deprecated.
3022 .INDENT 7.0
3023 .INDENT 3.5
3024 .IP "Examples"
3025 .INDENT 0.0
3026 .TP
3027 .B \fB\-\-ad=mp3float\fP
3028 Prefer the FFmpeg/Libav \fBmp3float\fP decoder over all other MP3
3029 decoders.
3030 .TP
3031 .B \fB\-\-ad=help\fP
3032 List all available decoders.
3033 .UNINDENT
3034 .UNINDENT
3035 .UNINDENT
3036 .INDENT 7.0
3037 .INDENT 3.5
3038 .IP "Warning"
3039 .sp
3040 Enabling compressed audio passthrough (AC3 and DTS via SPDIF/HDMI) with
3041 this option is not possible. Use \fB\-\-audio\-spdif\fP instead.
3042 .UNINDENT
3043 .UNINDENT
3044 .TP
3045 .B \fB\-\-volume=<value>\fP
3046 Set the startup volume. 0 means silence, 100 means no volume reduction or
3047 amplification. Negative values can be passed for compatibility, but are
3048 treated as 0.
3049 .sp
3050 Since mpv 0.18.1, this always controls the internal mixer (aka "softvol").
3051 .TP
3052 .B \fB\-\-replaygain=<no|track|album>\fP
3053 Adjust volume gain according to replaygain values stored in the file
3054 metadata. With \fB\-\-replaygain=no\fP (the default), perform no adjustment.
3055 With \fB\-\-replaygain=track\fP, apply track gain. With \fB\-\-replaygain=album\fP,
3056 apply album gain if present and fall back to track gain otherwise.
3057 .TP
3058 .B \fB\-\-replaygain\-preamp=<db>\fP
3059 Pre\-amplification gain in dB to apply to the selected replaygain gain
3060 (default: 0).
3061 .TP
3062 .B \fB\-\-replaygain\-clip=<yes|no>\fP
3063 Prevent clipping caused by replaygain by automatically lowering the
3064 gain (default). Use \fB\-\-replaygain\-clip=no\fP to disable this.
3065 .TP
3066 .B \fB\-\-replaygain\-fallback=<db>\fP
3067 Gain in dB to apply if the file has no replay gain tags. This option
3068 is always applied if the replaygain logic is somehow inactive. If this
3069 is applied, no other replaygain options are applied.
3070 .TP
3071 .B \fB\-\-audio\-delay=<sec>\fP
3072 Audio delay in seconds (positive or negative float value). Positive values
3073 delay the audio, and negative values delay the video.
3074 .TP
3075 .B \fB\-\-mute=<yes|no|auto>\fP
3076 Set startup audio mute status (default: no).
3077 .sp
3078 \fBauto\fP is a deprecated possible value that is equivalent to \fBno\fP\&.
3079 .sp
3080 See also: \fB\-\-volume\fP\&.
3081 .TP
3082 .B \fB\-\-softvol=<no|yes|auto>\fP
3083 Deprecated/unfunctional. Before mpv 0.18.1, this used to control whether
3084 to use the volume controls of the audio output driver or the internal mpv
3085 volume filter.
3086 .sp
3087 The current behavior is that softvol is always enabled, i.e. as if this
3088 option is set to \fByes\fP\&. The other behaviors are not available anymore,
3089 although \fBauto\fP almost matches current behavior in most cases.
3090 .sp
3091 The \fBno\fP behavior is still partially available through the \fBao\-volume\fP
3092 and \fBao\-mute\fP properties. But there are no options to reset these.
3093 .TP
3094 .B \fB\-\-audio\-demuxer=<[+]name>\fP
3095 Use this audio demuxer type when using \fB\-\-audio\-file\fP\&. Use a \(aq+\(aq before
3096 the name to force it; this will skip some checks. Give the demuxer name as
3097 printed by \fB\-\-audio\-demuxer=help\fP\&.
3098 .TP
3099 .B \fB\-\-ad\-lavc\-ac3drc=<level>\fP
3100 Select the Dynamic Range Compression level for AC\-3 audio streams.
3101 \fB<level>\fP is a float value ranging from 0 to 1, where 0 means no
3102 compression (which is the default) and 1 means full compression (make loud
3103 passages more silent and vice versa). Values up to 6 are also accepted, but
3104 are purely experimental. This option only shows an effect if the AC\-3 stream
3105 contains the required range compression information.
3106 .sp
3107 The standard mandates that DRC is enabled by default, but mpv (and some
3108 other players) ignore this for the sake of better audio quality.
3109 .TP
3110 .B \fB\-\-ad\-lavc\-downmix=<yes|no>\fP
3111 Whether to request audio channel downmixing from the decoder (default: yes).
3112 Some decoders, like AC\-3, AAC and DTS, can remix audio on decoding. The
3113 requested number of output channels is set with the \fB\-\-audio\-channels\fP option.
3114 Useful for playing surround audio on a stereo system.
3115 .TP
3116 .B \fB\-\-ad\-lavc\-threads=<0\-16>\fP
3117 Number of threads to use for decoding. Whether threading is actually
3118 supported depends on codec. As of this writing, it\(aqs supported for some
3119 lossless codecs only. 0 means autodetect number of cores on the
3120 machine and use that, up to the maximum of 16 (default: 1).
3121 .TP
3122 .B \fB\-\-ad\-lavc\-o=<key>=<value>[,<key>=<value>[,...]]\fP
3123 Pass AVOptions to libavcodec decoder. Note, a patch to make the o=
3124 unneeded and pass all unknown options through the AVOption system is
3125 welcome. A full list of AVOptions can be found in the FFmpeg manual.
3126 .TP
3127 .B \fB\-\-ad\-spdif\-dtshd=<yes|no>\fP, \fB\-\-dtshd\fP, \fB\-\-no\-dtshd\fP
3128 If DTS is passed through, use DTS\-HD.
3129 .INDENT 7.0
3130 .INDENT 3.5
3131 .IP "Warning"
3132 .sp
3133 This and enabling passthrough via \fB\-\-ad\fP are deprecated in favor of
3134 using \fB\-\-audio\-spdif=dts\-hd\fP\&.
3135 .UNINDENT
3136 .UNINDENT
3137 .TP
3138 .B \fB\-\-audio\-channels=<auto\-safe|auto|layouts>\fP
3139 Control which audio channels are output (e.g. surround vs. stereo). There
3140 are the following possibilities:
3141 .INDENT 7.0
3142 .IP \(bu 2
3143 .INDENT 2.0
3144 .TP
3145 .B \fB\-\-audio\-channels=auto\-safe\fP
3146 Use the system\(aqs preferred channel layout. If there is none (such
3147 as when accessing a hardware device instead of the system mixer),
3148 force stereo. Some audio outputs might simply accept any layout and
3149 do downmixing on their own.
3150 .sp
3151 This is the default.
3152 .UNINDENT
3153 .IP \(bu 2
3154 .INDENT 2.0
3155 .TP
3156 .B \fB\-\-audio\-channels=auto\fP
3157 Send the audio device whatever it accepts, preferring the audio\(aqs
3158 original channel layout. Can cause issues with HDMI (see the warning
3159 below).
3160 .UNINDENT
3161 .IP \(bu 2
3162 .INDENT 2.0
3163 .TP
3164 .B \fB\-\-audio\-channels=layout1,layout2,...\fP
3165 List of \fB,\fP\-separated channel layouts which should be allowed.
3166 Technically, this only adjusts the filter chain output to the best
3167 matching layout in the list, and passes the result to the audio API.
3168 It\(aqs possible that the audio API will select a different channel
3169 layout.
3170 .sp
3171 Using this mode is recommended for direct hardware output, especially
3172 over HDMI (see HDMI warning below).
3173 .UNINDENT
3174 .IP \(bu 2
3175 .INDENT 2.0
3176 .TP
3177 .B \fB\-\-audio\-channels=stereo\fP
3178 Force a plain stereo downmix. This is a special\-case of the previous
3179 item. (See paragraphs below for implications.)
3180 .UNINDENT
3181 .UNINDENT
3182 .sp
3183 If a list of layouts is given, each item can be either an explicit channel
3184 layout name (like \fB5.1\fP), or a channel number. Channel numbers refer to
3185 default layouts, e.g. 2 channels refer to stereo, 6 refers to 5.1.
3186 .sp
3187 See \fB\-\-audio\-channels=help\fP output for defined default layouts. This also
3188 lists speaker names, which can be used to express arbitrary channel
3189 layouts (e.g. \fBfl\-fr\-lfe\fP is 2.1).
3190 .sp
3191 If the list of channel layouts has only 1 item, the decoder is asked to
3192 produce according output. This sometimes triggers decoder\-downmix, which
3193 might be different from the normal mpv downmix. (Only some decoders support
3194 remixing audio, like AC\-3, AAC or DTS. You can use \fB\-\-ad\-lavc\-downmix=no\fP
3195 to make the decoder always output its native layout.) One consequence is
3196 that \fB\-\-audio\-channels=stereo\fP triggers decoder downmix, while \fBauto\fP
3197 or \fBauto\-safe\fP never will, even if they end up selecting stereo. This
3198 happens because the decision whether to use decoder downmix happens long
3199 before the audio device is opened.
3200 .sp
3201 If the channel layout of the media file (i.e. the decoder) and the AO\(aqs
3202 channel layout don\(aqt match, mpv will attempt to insert a conversion filter.
3203 You may need to change the channel layout of the system mixer to achieve
3204 your desired output as mpv does not have control over it. Another
3205 work\-around for this on some AOs is to use \fB\-\-audio\-exclusive=yes\fP to
3206 circumvent the system mixer entirely.
3207 .INDENT 7.0
3208 .INDENT 3.5
3209 .IP "Warning"
3210 .sp
3211 Using \fBauto\fP can cause issues when using audio over HDMI. The OS will
3212 typically report all channel layouts that _can_ go over HDMI, even if
3213 the receiver does not support them. If a receiver gets an unsupported
3214 channel layout, random things can happen, such as dropping the
3215 additional channels, or adding noise.
3216 .sp
3217 You are recommended to set an explicit whitelist of the layouts you
3218 want. For example, most A/V receivers connected via HDMI and that can
3219 do 7.1 would be served by: \fB\-\-audio\-channels=7.1,5.1,stereo\fP
3220 .UNINDENT
3221 .UNINDENT
3222 .TP
3223 .B \fB\-\-audio\-display=<no|attachment>\fP
3224 Setting this option to \fBattachment\fP (default) will display image
3225 attachments (e.g. album cover art) when playing audio files. It will
3226 display the first image found, and additional images are available as
3227 video tracks.
3228 .sp
3229 Setting this option to \fBno\fP disables display of video entirely when
3230 playing audio files.
3231 .sp
3232 This option has no influence on files with normal video tracks.
3233 .TP
3234 .B \fB\-\-audio\-files=<files>\fP
3235 Play audio from an external file while viewing a video.
3236 .sp
3237 This is a list option. See \fI\%List Options\fP for details.
3238 .TP
3239 .B \fB\-\-audio\-file=<file>\fP
3240 CLI/config file only alias for \fB\-\-audio\-files\-append\fP\&. Each use of this
3241 option will add a new audio track. The details are similar to how
3242 \fB\-\-sub\-file\fP works.
3243 .TP
3244 .B \fB\-\-audio\-format=<format>\fP
3245 Select the sample format used for output from the audio filter layer to
3246 the sound card. The values that \fB<format>\fP can adopt are listed below in
3247 the description of the \fBformat\fP audio filter.
3248 .TP
3249 .B \fB\-\-audio\-samplerate=<Hz>\fP
3250 Select the output sample rate to be used (of course sound cards have
3251 limits on this). If the sample frequency selected is different from that
3252 of the current media, the lavrresample audio filter will be inserted into
3253 the audio filter layer to compensate for the difference.
3254 .TP
3255 .B \fB\-\-gapless\-audio=<no|yes|weak>\fP
3256 Try to play consecutive audio files with no silence or disruption at the
3257 point of file change. Default: \fBweak\fP\&.
3258 .INDENT 7.0
3259 .TP
3260 .B no
3261 Disable gapless audio.
3262 .TP
3263 .B yes
3264 The audio device is opened using parameters chosen for the first
3265 file played and is then kept open for gapless playback. This
3266 means that if the first file for example has a low sample rate, then
3267 the following files may get resampled to the same low sample rate,
3268 resulting in reduced sound quality. If you play files with different
3269 parameters, consider using options such as \fB\-\-audio\-samplerate\fP
3270 and \fB\-\-audio\-format\fP to explicitly select what the shared output
3271 format will be.
3272 .TP
3273 .B weak
3274 Normally, the audio device is kept open (using the format it was
3275 first initialized with). If the audio format the decoder output
3276 changes, the audio device is closed and reopened. This means that
3277 you will normally get gapless audio with files that were encoded
3278 using the same settings, but might not be gapless in other cases.
3279 The exact conditions under which the audio device is kept open is
3280 an implementation detail, and can change from version to version.
3281 Currently, the device is kept even if the sample format changes,
3282 but the sample formats are convertible.
3283 If video is still going on when there is still audio, trying to use
3284 gapless is also explicitly given up.
3285 .UNINDENT
3286 .sp
3287 \fBNOTE:\fP
3288 .INDENT 7.0
3289 .INDENT 3.5
3290 This feature is implemented in a simple manner and relies on audio
3291 output device buffering to continue playback while moving from one file
3292 to another. If playback of the new file starts slowly, for example
3293 because it is played from a remote network location or because you have
3294 specified cache settings that require time for the initial cache fill,
3295 then the buffered audio may run out before playback of the new file
3296 can start.
3297 .UNINDENT
3298 .UNINDENT
3299 .TP
3300 .B \fB\-\-initial\-audio\-sync\fP, \fB\-\-no\-initial\-audio\-sync\fP
3301 When starting a video file or after events such as seeking, mpv will by
3302 default modify the audio stream to make it start from the same timestamp
3303 as video, by either inserting silence at the start or cutting away the
3304 first samples. Disabling this option makes the player behave like older
3305 mpv versions did: video and audio are both started immediately even if
3306 their start timestamps differ, and then video timing is gradually adjusted
3307 if necessary to reach correct synchronization later.
3308 .TP
3309 .B \fB\-\-volume\-max=<100.0\-1000.0>\fP, \fB\-\-softvol\-max=<...>\fP
3310 Set the maximum amplification level in percent (default: 130). A value of
3311 130 will allow you to adjust the volume up to about double the normal level.
3312 .sp
3313 \fB\-\-softvol\-max\fP is a deprecated alias and should not be used.
3314 .TP
3315 .B \fB\-\-audio\-file\-auto=<no|exact|fuzzy|all>\fP, \fB\-\-no\-audio\-file\-auto\fP
3316 Load additional audio files matching the video filename. The parameter
3317 specifies how external audio files are matched.
3318 .INDENT 7.0
3319 .TP
3320 .B no
3321 Don\(aqt automatically load external audio files (default).
3322 .TP
3323 .B exact
3324 Load the media filename with audio file extension.
3325 .TP
3326 .B fuzzy
3327 Load all audio files containing media filename.
3328 .TP
3329 .B all
3330 Load all audio files in the current and \fB\-\-audio\-file\-paths\fP
3331 directories.
3332 .UNINDENT
3333 .TP
3334 .B \fB\-\-audio\-file\-paths=<path1:path2:...>\fP
3335 Equivalent to \fB\-\-sub\-file\-paths\fP option, but for auto\-loaded audio files.
3336 .TP
3337 .B \fB\-\-audio\-client\-name=<name>\fP
3338 The application name the player reports to the audio API. Can be useful
3339 if you want to force a different audio profile (e.g. with PulseAudio),
3340 or to set your own application name when using libmpv.
3341 .TP
3342 .B \fB\-\-audio\-buffer=<seconds>\fP
3343 Set the audio output minimum buffer. The audio device might actually create
3344 a larger buffer if it pleases. If the device creates a smaller buffer,
3345 additional audio is buffered in an additional software buffer.
3346 .sp
3347 Making this larger will make soft\-volume and other filters react slower,
3348 introduce additional issues on playback speed change, and block the
3349 player on audio format changes. A smaller buffer might lead to audio
3350 dropouts.
3351 .sp
3352 This option should be used for testing only. If a non\-default value helps
3353 significantly, the mpv developers should be contacted.
3354 .sp
3355 Default: 0.2 (200 ms).
3356 .TP
3357 .B \fB\-\-audio\-stream\-silence=<yes|no>\fP
3358 Cash\-grab consumer audio hardware (such as A/V receivers) often ignore
3359 initial audio sent over HDMI. This can happen every time audio over HDMI
3360 is stopped and resumed. In order to compensate for this, you can enable
3361 this option to not to stop and restart audio on seeks, and fill the gaps
3362 with silence. Likewise, when pausing playback, audio is not stopped, and
3363 silence is played while paused. Note that if no audio track is selected,
3364 the audio device will still be closed immediately.
3365 .sp
3366 Not all AOs support this.
3367 .TP
3368 .B \fB\-\-audio\-wait\-open=<secs>\fP
3369 This makes sense for use with \fB\-\-audio\-stream\-silence=yes\fP\&. If this option
3370 is given, the player will wait for the given amount of seconds after opening
3371 the audio device before sending actual audio data to it. Useful if your
3372 expensive hardware discards the first 1 or 2 seconds of audio data sent to
3373 it. If \fB\-\-audio\-stream\-silence=yes\fP is not set, this option will likely
3374 just waste time.
3375 .UNINDENT
3376 .SS Subtitles
3377 .sp
3378 \fBNOTE:\fP
3379 .INDENT 0.0
3380 .INDENT 3.5
3381 Changing styling and position does not work with all subtitles. Image\-based
3382 subtitles (DVD, Bluray/PGS, DVB) cannot changed for fundamental reasons.
3383 Subtitles in ASS format are normally not changed intentionally, but
3384 overriding them can be controlled with \fB\-\-sub\-ass\-override\fP\&.
3385 .sp
3386 Previously some options working on text subtitles were called
3387 \fB\-\-sub\-text\-*\fP, they are now named \fB\-\-sub\-*\fP, and those specifically
3388 for ASS have been renamed from \fB\-\-ass\-*\fP to \fB\-\-sub\-ass\-*\fP\&.
3389 They are now all in this section.
3390 .UNINDENT
3391 .UNINDENT
3392 .INDENT 0.0
3393 .TP
3394 .B \fB\-\-sub\-demuxer=<[+]name>\fP
3395 Force subtitle demuxer type for \fB\-\-sub\-file\fP\&. Give the demuxer name as
3396 printed by \fB\-\-sub\-demuxer=help\fP\&.
3397 .TP
3398 .B \fB\-\-sub\-delay=<sec>\fP
3399 Delays subtitles by \fB<sec>\fP seconds. Can be negative.
3400 .TP
3401 .B \fB\-\-sub\-files=<file\-list>\fP, \fB\-\-sub\-file=<filename>\fP
3402 Add a subtitle file to the list of external subtitles.
3403 .sp
3404 If you use \fB\-\-sub\-file\fP only once, this subtitle file is displayed by
3405 default.
3406 .sp
3407 If \fB\-\-sub\-file\fP is used multiple times, the subtitle to use can be
3408 switched at runtime by cycling subtitle tracks. It\(aqs possible to show
3409 two subtitles at once: use \fB\-\-sid\fP to select the first subtitle index,
3410 and \fB\-\-secondary\-sid\fP to select the second index. (The index is printed
3411 on the terminal output after the \fB\-\-sid=\fP in the list of streams.)
3412 .sp
3413 \fB\-\-sub\-files\fP is a list option (see \fI\%List Options\fP for details), and
3414 can take multiple file names separated by \fB:\fP (Unix) or \fB;\fP (Windows),
3415 while \fB\-\-sub\-file\fP takes a single filename, but can be used multiple
3416 times to add multiple files. Technically, \fB\-\-sub\-file\fP is a CLI/config
3417 file only alias for \fB\-\-sub\-files\-append\fP\&.
3418 .TP
3419 .B \fB\-\-secondary\-sid=<ID|auto|no>\fP
3420 Select a secondary subtitle stream. This is similar to \fB\-\-sid\fP\&. If a
3421 secondary subtitle is selected, it will be rendered as toptitle (i.e. on
3422 the top of the screen) alongside the normal subtitle, and provides a way
3423 to render two subtitles at once.
3424 .sp
3425 There are some caveats associated with this feature. For example, bitmap
3426 subtitles will always be rendered in their usual position, so selecting a
3427 bitmap subtitle as secondary subtitle will result in overlapping subtitles.
3428 Secondary subtitles are never shown on the terminal if video is disabled.
3429 .sp
3430 \fBNOTE:\fP
3431 .INDENT 7.0
3432 .INDENT 3.5
3433 Styling and interpretation of any formatting tags is disabled for the
3434 secondary subtitle. Internally, the same mechanism as \fB\-\-no\-sub\-ass\fP
3435 is used to strip the styling.
3436 .UNINDENT
3437 .UNINDENT
3438 .sp
3439 \fBNOTE:\fP
3440 .INDENT 7.0
3441 .INDENT 3.5
3442 If the main subtitle stream contains formatting tags which display the
3443 subtitle at the top of the screen, it will overlap with the secondary
3444 subtitle. To prevent this, you could use \fB\-\-no\-sub\-ass\fP to disable
3445 styling in the main subtitle stream.
3446 .UNINDENT
3447 .UNINDENT
3448 .TP
3449 .B \fB\-\-sub\-scale=<0\-100>\fP
3450 Factor for the text subtitle font size (default: 1).
3451 .sp
3452 \fBNOTE:\fP
3453 .INDENT 7.0
3454 .INDENT 3.5
3455 This affects ASS subtitles as well, and may lead to incorrect subtitle
3456 rendering. Use with care, or use \fB\-\-sub\-font\-size\fP instead.
3457 .UNINDENT
3458 .UNINDENT
3459 .TP
3460 .B \fB\-\-sub\-scale\-by\-window=<yes|no>\fP
3461 Whether to scale subtitles with the window size (default: yes). If this is
3462 disabled, changing the window size won\(aqt change the subtitle font size.
3463 .sp
3464 Like \fB\-\-sub\-scale\fP, this can break ASS subtitles.
3465 .TP
3466 .B \fB\-\-sub\-scale\-with\-window=<yes|no>\fP
3467 Make the subtitle font size relative to the window, instead of the video.
3468 This is useful if you always want the same font size, even if the video
3469 doesn\(aqt cover the window fully, e.g. because screen aspect and window
3470 aspect mismatch (and the player adds black bars).
3471 .sp
3472 Default: yes.
3473 .sp
3474 This option is misnamed. The difference to the confusingly similar sounding
3475 option \fB\-\-sub\-scale\-by\-window\fP is that \fB\-\-sub\-scale\-with\-window\fP still
3476 scales with the approximate window size, while the other option disables
3477 this scaling.
3478 .sp
3479 Affects plain text subtitles only (or ASS if \fB\-\-sub\-ass\-override\fP is set
3480 high enough).
3481 .TP
3482 .B \fB\-\-sub\-ass\-scale\-with\-window=<yes|no>\fP
3483 Like \fB\-\-sub\-scale\-with\-window\fP, but affects subtitles in ASS format only.
3484 Like \fB\-\-sub\-scale\fP, this can break ASS subtitles.
3485 .sp
3486 Default: no.
3487 .TP
3488 .B \fB\-\-embeddedfonts=<yes|no>\fP
3489 Use fonts embedded in Matroska container files and ASS scripts (default:
3490 yes). These fonts can be used for SSA/ASS subtitle rendering.
3491 .TP
3492 .B \fB\-\-sub\-pos=<0\-100>\fP
3493 Specify the position of subtitles on the screen. The value is the vertical
3494 position of the subtitle in % of the screen height.
3495 .sp
3496 \fBNOTE:\fP
3497 .INDENT 7.0
3498 .INDENT 3.5
3499 This affects ASS subtitles as well, and may lead to incorrect subtitle
3500 rendering. Use with care, or use \fB\-\-sub\-margin\-y\fP instead.
3501 .UNINDENT
3502 .UNINDENT
3503 .TP
3504 .B \fB\-\-sub\-speed=<0.1\-10.0>\fP
3505 Multiply the subtitle event timestamps with the given value. Can be used
3506 to fix the playback speed for frame\-based subtitle formats. Affects text
3507 subtitles only.
3508 .INDENT 7.0
3509 .INDENT 3.5
3510 .IP "Example"
3511 .sp
3512 \fB\-\-sub\-speed=25/23.976\fP plays frame based subtitles which have been
3513 loaded assuming a framerate of 23.976 at 25 FPS.
3514 .UNINDENT
3515 .UNINDENT
3516 .TP
3517 .B \fB\-\-sub\-ass\-force\-style=<[Style.]Param=Value[,...]>\fP
3518 Override some style or script info parameters.
3519 .INDENT 7.0
3520 .INDENT 3.5
3521 .IP "Examples"
3522 .INDENT 0.0
3523 .IP \(bu 2
3524 \fB\-\-sub\-ass\-force\-style=FontName=Arial,Default.Bold=1\fP
3525 .IP \(bu 2
3526 \fB\-\-sub\-ass\-force\-style=PlayResY=768\fP
3527 .UNINDENT
3528 .UNINDENT
3529 .UNINDENT
3530 .sp
3531 \fBNOTE:\fP
3532 .INDENT 7.0
3533 .INDENT 3.5
3534 Using this option may lead to incorrect subtitle rendering.
3535 .UNINDENT
3536 .UNINDENT
3537 .TP
3538 .B \fB\-\-sub\-ass\-hinting=<none|light|normal|native>\fP
3539 Set font hinting type. <type> can be:
3540 .INDENT 7.0
3541 .TP
3542 .B none
3543 no hinting (default)
3544 .TP
3545 .B light
3546 FreeType autohinter, light mode
3547 .TP
3548 .B normal
3549 FreeType autohinter, normal mode
3550 .TP
3551 .B native
3552 font native hinter
3553 .UNINDENT
3554 .INDENT 7.0
3555 .INDENT 3.5
3556 .IP "Warning"
3557 .sp
3558 Enabling hinting can lead to mispositioned text (in situations it\(aqs
3559 supposed to match up video background), or reduce the smoothness
3560 of animations with some badly authored ASS scripts. It is recommended
3561 to not use this option, unless really needed.
3562 .UNINDENT
3563 .UNINDENT
3564 .TP
3565 .B \fB\-\-sub\-ass\-line\-spacing=<value>\fP
3566 Set line spacing value for SSA/ASS renderer.
3567 .TP
3568 .B \fB\-\-sub\-ass\-shaper=<simple|complex>\fP
3569 Set the text layout engine used by libass.
3570 .INDENT 7.0
3571 .TP
3572 .B simple
3573 uses Fribidi only, fast, doesn\(aqt render some languages correctly
3574 .TP
3575 .B complex
3576 uses HarfBuzz, slower, wider language support
3577 .UNINDENT
3578 .sp
3579 \fBcomplex\fP is the default. If libass hasn\(aqt been compiled against HarfBuzz,
3580 libass silently reverts to \fBsimple\fP\&.
3581 .TP
3582 .B \fB\-\-sub\-ass\-styles=<filename>\fP
3583 Load all SSA/ASS styles found in the specified file and use them for
3584 rendering text subtitles. The syntax of the file is exactly like the \fB[V4
3585 Styles]\fP / \fB[V4+ Styles]\fP section of SSA/ASS.
3586 .sp
3587 \fBNOTE:\fP
3588 .INDENT 7.0
3589 .INDENT 3.5
3590 Using this option may lead to incorrect subtitle rendering.
3591 .UNINDENT
3592 .UNINDENT
3593 .TP
3594 .B \fB\-\-sub\-ass\-override=<yes|no|force|scale|strip>\fP
3595 Control whether user style overrides should be applied. Note that all of
3596 these overrides try to be somewhat smart about figuring out whether or not
3597 a subtitle is considered a "sign".
3598 .INDENT 7.0
3599 .TP
3600 .B no
3601 Render subtitles as specified by the subtitle scripts, without
3602 overrides.
3603 .TP
3604 .B yes
3605 Apply all the \fB\-\-sub\-ass\-*\fP style override options. Changing the
3606 default for any of these options can lead to incorrect subtitle
3607 rendering (default).
3608 .TP
3609 .B force
3610 Like \fByes\fP, but also force all \fB\-\-sub\-*\fP options. Can break
3611 rendering easily.
3612 .TP
3613 .B scale
3614 Like \fByes\fP, but also apply \fB\-\-sub\-scale\fP\&.
3615 .TP
3616 .B strip
3617 Radically strip all ASS tags and styles from the subtitle. This
3618 is equivalent to the old \fB\-\-no\-ass\fP / \fB\-\-no\-sub\-ass\fP options.
3619 .UNINDENT
3620 .sp
3621 This also controls some bitmap subtitle overrides, as well as HTML tags in
3622 formats like SRT, despite the name of the option.
3623 .TP
3624 .B \fB\-\-sub\-ass\-force\-margins\fP
3625 Enables placing toptitles and subtitles in black borders when they are
3626 available, if the subtitles are in the ASS format.
3627 .sp
3628 Default: no.
3629 .TP
3630 .B \fB\-\-sub\-use\-margins\fP
3631 Enables placing toptitles and subtitles in black borders when they are
3632 available, if the subtitles are in a plain text format (or ASS if
3633 \fB\-\-sub\-ass\-override\fP is set high enough).
3634 .sp
3635 Default: yes.
3636 .sp
3637 Renamed from \fB\-\-sub\-ass\-use\-margins\fP\&. To place ASS subtitles in the borders
3638 too (like the old option did), also add \fB\-\-sub\-ass\-force\-margins\fP\&.
3639 .TP
3640 .B \fB\-\-sub\-ass\-vsfilter\-aspect\-compat=<yes|no>\fP
3641 Stretch SSA/ASS subtitles when playing anamorphic videos for compatibility
3642 with traditional VSFilter behavior. This switch has no effect when the
3643 video is stored with square pixels.
3644 .sp
3645 The renderer historically most commonly used for the SSA/ASS subtitle
3646 formats, VSFilter, had questionable behavior that resulted in subtitles
3647 being stretched too if the video was stored in anamorphic format that
3648 required scaling for display. This behavior is usually undesirable and
3649 newer VSFilter versions may behave differently. However, many existing
3650 scripts compensate for the stretching by modifying things in the opposite
3651 direction. Thus, if such scripts are displayed "correctly", they will not
3652 appear as intended. This switch enables emulation of the old VSFilter
3653 behavior (undesirable but expected by many existing scripts).
3654 .sp
3655 Enabled by default.
3656 .TP
3657 .B \fB\-\-sub\-ass\-vsfilter\-blur\-compat=<yes|no>\fP
3658 Scale \fB\eblur\fP tags by video resolution instead of script resolution
3659 (enabled by default). This is bug in VSFilter, which according to some,
3660 can\(aqt be fixed anymore in the name of compatibility.
3661 .sp
3662 Note that this uses the actual video resolution for calculating the
3663 offset scale factor, not what the video filter chain or the video output
3664 use.
3665 .TP
3666 .B \fB\-\-sub\-ass\-vsfilter\-color\-compat=<basic|full|force\-601|no>\fP
3667 Mangle colors like (xy\-)vsfilter do (default: basic). Historically, VSFilter
3668 was not color space aware. This was no problem as long as the color space
3669 used for SD video (BT.601) was used. But when everything switched to HD
3670 (BT.709), VSFilter was still converting RGB colors to BT.601, rendered
3671 them into the video frame, and handled the frame to the video output, which
3672 would use BT.709 for conversion to RGB. The result were mangled subtitle
3673 colors. Later on, bad hacks were added on top of the ASS format to control
3674 how colors are to be mangled.
3675 .INDENT 7.0
3676 .TP
3677 .B basic
3678 Handle only BT.601\->BT.709 mangling, if the subtitles seem to
3679 indicate that this is required (default).
3680 .TP
3681 .B full
3682 Handle the full \fBYCbCr Matrix\fP header with all video color spaces
3683 supported by libass and mpv. This might lead to bad breakages in
3684 corner cases and is not strictly needed for compatibility
3685 (hopefully), which is why this is not default.
3686 .TP
3687 .B force\-601
3688 Force BT.601\->BT.709 mangling, regardless of subtitle headers
3689 or video color space.
3690 .TP
3691 .B no
3692 Disable color mangling completely. All colors are RGB.
3693 .UNINDENT
3694 .sp
3695 Choosing anything other than \fBno\fP will make the subtitle color depend on
3696 the video color space, and it\(aqs for example in theory not possible to reuse
3697 a subtitle script with another video file. The \fB\-\-sub\-ass\-override\fP
3698 option doesn\(aqt affect how this option is interpreted.
3699 .TP
3700 .B \fB\-\-stretch\-dvd\-subs=<yes|no>\fP
3701 Stretch DVD subtitles when playing anamorphic videos for better looking
3702 fonts on badly mastered DVDs. This switch has no effect when the
3703 video is stored with square pixels \- which for DVD input cannot be the case
3704 though.
3705 .sp
3706 Many studios tend to use bitmap fonts designed for square pixels when
3707 authoring DVDs, causing the fonts to look stretched on playback on DVD
3708 players. This option fixes them, however at the price of possibly
3709 misaligning some subtitles (e.g. sign translations).
3710 .sp
3711 Disabled by default.
3712 .TP
3713 .B \fB\-\-stretch\-image\-subs\-to\-screen=<yes|no>\fP
3714 Stretch DVD and other image subtitles to the screen, ignoring the video
3715 margins. This has a similar effect as \fB\-\-sub\-use\-margins\fP for text
3716 subtitles, except that the text itself will be stretched, not only just
3717 repositioned. (At least in general it is unavoidable, as an image bitmap
3718 can in theory consist of a single bitmap covering the whole screen, and
3719 the player won\(aqt know where exactly the text parts are located.)
3720 .sp
3721 This option does not display subtitles correctly. Use with care.
3722 .sp
3723 Disabled by default.
3724 .TP
3725 .B \fB\-\-image\-subs\-video\-resolution=<yes|no>\fP
3726 Override the image subtitle resolution with the video resolution
3727 (default: no). Normally, the subtitle canvas is fit into the video canvas
3728 (e.g. letterboxed). Setting this option uses the video size as subtitle
3729 canvas size. Can be useful to test broken subtitles, which often happen
3730 when the video was trancoded, while attempting to keep the old subtitles.
3731 .TP
3732 .B \fB\-\-sub\-ass\fP, \fB\-\-no\-sub\-ass\fP
3733 Render ASS subtitles natively (enabled by default).
3734 .sp
3735 \fBNOTE:\fP
3736 .INDENT 7.0
3737 .INDENT 3.5
3738 This has been deprecated by \fB\-\-sub\-ass\-override=strip\fP\&. You also
3739 may need \fB\-\-embeddedfonts=no\fP to get the same behavior. Also,
3740 using \fB\-\-sub\-ass\-override=style\fP should give better results
3741 without breaking subtitles too much.
3742 .UNINDENT
3743 .UNINDENT
3744 .sp
3745 If \fB\-\-no\-sub\-ass\fP is specified, all tags and style declarations are
3746 stripped and ignored on display. The subtitle renderer uses the font style
3747 as specified by the \fB\-\-sub\-\fP options instead.
3748 .sp
3749 \fBNOTE:\fP
3750 .INDENT 7.0
3751 .INDENT 3.5
3752 Using \fB\-\-no\-sub\-ass\fP may lead to incorrect or completely broken
3753 rendering of ASS/SSA subtitles. It can sometimes be useful to forcibly
3754 override the styling of ASS subtitles, but should be avoided in general.
3755 .UNINDENT
3756 .UNINDENT
3757 .TP
3758 .B \fB\-\-sub\-auto=<no|exact|fuzzy|all>\fP, \fB\-\-no\-sub\-auto\fP
3759 Load additional subtitle files matching the video filename. The parameter
3760 specifies how external subtitle files are matched. \fBexact\fP is enabled by
3761 default.
3762 .INDENT 7.0
3763 .TP
3764 .B no
3765 Don\(aqt automatically load external subtitle files.
3766 .TP
3767 .B exact
3768 Load the media filename with subtitle file extension (default).
3769 .TP
3770 .B fuzzy
3771 Load all subs containing media filename.
3772 .TP
3773 .B all
3774 Load all subs in the current and \fB\-\-sub\-file\-paths\fP directories.
3775 .UNINDENT
3776 .TP
3777 .B \fB\-\-sub\-codepage=<codepage>\fP
3778 You can use this option to specify the subtitle codepage. uchardet will be
3779 used to guess the charset. (If mpv was not compiled with uchardet, then
3780 \fButf\-8\fP is the effective default.)
3781 .sp
3782 The default value for this option is \fBauto\fP, which enables autodetection.
3783 .sp
3784 The following steps are taken to determine the final codepage, in order:
3785 .INDENT 7.0
3786 .IP \(bu 2
3787 if the specific codepage has a \fB+\fP, use that codepage
3788 .IP \(bu 2
3789 if the data looks like UTF\-8, assume it is UTF\-8
3790 .IP \(bu 2
3791 if \fB\-\-sub\-codepage\fP is set to a specific codepage, use that
3792 .IP \(bu 2
3793 run uchardet, and if successful, use that
3794 .IP \(bu 2
3795 otherwise, use \fBUTF\-8\-BROKEN\fP
3796 .UNINDENT
3797 .INDENT 7.0
3798 .INDENT 3.5
3799 .IP "Examples"
3800 .INDENT 0.0
3801 .IP \(bu 2
3802 \fB\-\-sub\-codepage=latin2\fP Use Latin 2 if input is not UTF\-8.
3803 .IP \(bu 2
3804 \fB\-\-sub\-codepage=+cp1250\fP Always force recoding to cp1250.
3805 .UNINDENT
3806 .UNINDENT
3807 .UNINDENT
3808 .sp
3809 The pseudo codepage \fBUTF\-8\-BROKEN\fP is used internally. If it\(aqs set,
3810 subtitles are interpreted as UTF\-8 with "Latin 1" as fallback for bytes
3811 which are not valid UTF\-8 sequences. iconv is never involved in this mode.
3812 .sp
3813 This option changed in mpv 0.23.0. Support for the old syntax was fully
3814 removed in mpv 0.24.0.
3815 .TP
3816 .B \fB\-\-sub\-fix\-timing=<yes|no>\fP
3817 Adjust subtitle timing is to remove minor gaps or overlaps between
3818 subtitles (if the difference is smaller than 210 ms, the gap or overlap
3819 is removed).
3820 .TP
3821 .B \fB\-\-sub\-forced\-only\fP
3822 Display only forced subtitles for the DVD subtitle stream selected by e.g.
3823 \fB\-\-slang\fP\&.
3824 .TP
3825 .B \fB\-\-sub\-fps=<rate>\fP
3826 Specify the framerate of the subtitle file (default: video fps). Affects
3827 text subtitles only.
3828 .sp
3829 \fBNOTE:\fP
3830 .INDENT 7.0
3831 .INDENT 3.5
3832 \fB<rate>\fP > video fps speeds the subtitles up for frame\-based
3833 subtitle files and slows them down for time\-based ones.
3834 .UNINDENT
3835 .UNINDENT
3836 .sp
3837 See also: \fB\-\-sub\-speed\fP\&.
3838 .TP
3839 .B \fB\-\-sub\-gauss=<0.0\-3.0>\fP
3840 Apply Gaussian blur to image subtitles (default: 0). This can help to make
3841 pixelated DVD/Vobsubs look nicer. A value other than 0 also switches to
3842 software subtitle scaling. Might be slow.
3843 .sp
3844 \fBNOTE:\fP
3845 .INDENT 7.0
3846 .INDENT 3.5
3847 Never applied to text subtitles.
3848 .UNINDENT
3849 .UNINDENT
3850 .TP
3851 .B \fB\-\-sub\-gray\fP
3852 Convert image subtitles to grayscale. Can help to make yellow DVD/Vobsubs
3853 look nicer.
3854 .sp
3855 \fBNOTE:\fP
3856 .INDENT 7.0
3857 .INDENT 3.5
3858 Never applied to text subtitles.
3859 .UNINDENT
3860 .UNINDENT
3861 .TP
3862 .B \fB\-\-sub\-paths=<path1:path2:...>\fP
3863 Deprecated, use \fB\-\-sub\-file\-paths\fP\&.
3864 .TP
3865 .B \fB\-\-sub\-file\-paths=<path\-list>\fP
3866 Specify extra directories to search for subtitles matching the video.
3867 Multiple directories can be separated by ":" (";" on Windows).
3868 Paths can be relative or absolute. Relative paths are interpreted relative
3869 to video file directory.
3870 If the file is a URL, only absolute paths and \fBsub\fP configuration
3871 subdirectory will be scanned.
3872 .INDENT 7.0
3873 .INDENT 3.5
3874 .IP "Example"
3875 .sp
3876 Assuming that \fB/path/to/video/video.avi\fP is played and
3877 \fB\-\-sub\-file\-paths=sub:subtitles\fP is specified, mpv
3878 searches for subtitle files in these directories:
3879 .INDENT 0.0
3880 .IP \(bu 2
3881 \fB/path/to/video/\fP
3882 .IP \(bu 2
3883 \fB/path/to/video/sub/\fP
3884 .IP \(bu 2
3885 \fB/path/to/video/subtitles/\fP
3886 .IP \(bu 2
3887 the \fBsub\fP configuration subdirectory (usually \fB~/.config/mpv/sub/\fP)
3888 .UNINDENT
3889 .UNINDENT
3890 .UNINDENT
3891 .sp
3892 This is a list option. See \fI\%List Options\fP for details.
3893 .TP
3894 .B \fB\-\-sub\-visibility\fP, \fB\-\-no\-sub\-visibility\fP
3895 Can be used to disable display of subtitles, but still select and decode
3896 them.
3897 .TP
3898 .B \fB\-\-sub\-clear\-on\-seek\fP
3899 (Obscure, rarely useful.) Can be used to play broken mkv files with
3900 duplicate ReadOrder fields. ReadOrder is the first field in a
3901 Matroska\-style ASS subtitle packets. It should be unique, and libass
3902 uses it for fast elimination of duplicates. This option disables caching
3903 of subtitles across seeks, so after a seek libass can\(aqt eliminate subtitle
3904 packets with the same ReadOrder as earlier packets.
3905 .TP
3906 .B \fB\-\-teletext\-page=<1\-999>\fP
3907 This works for \fBdvb_teletext\fP subtitle streams, and if FFmpeg has been
3908 compiled with support for it.
3909 .TP
3910 .B \fB\-\-sub\-font=<name>\fP
3911 Specify font to use for subtitles that do not themselves
3912 specify a particular font. The default is \fBsans\-serif\fP\&.
3913 .INDENT 7.0
3914 .INDENT 3.5
3915 .IP "Examples"
3916 .INDENT 0.0
3917 .IP \(bu 2
3918 \fB\-\-sub\-font=\(aqBitstream Vera Sans\(aq\fP
3919 .IP \(bu 2
3920 \fB\-\-sub\-font=\(aqComic Sans MS\(aq\fP
3921 .UNINDENT
3922 .UNINDENT
3923 .UNINDENT
3924 .sp
3925 \fBNOTE:\fP
3926 .INDENT 7.0
3927 .INDENT 3.5
3928 The \fB\-\-sub\-font\fP option (and many other style related \fB\-\-sub\-\fP
3929 options) are ignored when ASS\-subtitles are rendered, unless the
3930 \fB\-\-no\-sub\-ass\fP option is specified.
3931 .sp
3932 This used to support fontconfig patterns. Starting with libass 0.13.0,
3933 this stopped working.
3934 .UNINDENT
3935 .UNINDENT
3936 .TP
3937 .B \fB\-\-sub\-font\-size=<size>\fP
3938 Specify the sub font size. The unit is the size in scaled pixels at a
3939 window height of 720. The actual pixel size is scaled with the window
3940 height: if the window height is larger or smaller than 720, the actual size
3941 of the text increases or decreases as well.
3942 .sp
3943 Default: 55.
3944 .TP
3945 .B \fB\-\-sub\-back\-color=<color>\fP
3946 See \fB\-\-sub\-color\fP\&. Color used for sub text background. You can use
3947 \fB\-\-sub\-shadow\-offset\fP to change its size relative to the text.
3948 .TP
3949 .B \fB\-\-sub\-blur=<0..20.0>\fP
3950 Gaussian blur factor. 0 means no blur applied (default).
3951 .TP
3952 .B \fB\-\-sub\-bold=<yes|no>\fP
3953 Format text on bold.
3954 .TP
3955 .B \fB\-\-sub\-italic=<yes|no>\fP
3956 Format text on italic.
3957 .TP
3958 .B \fB\-\-sub\-border\-color=<color>\fP
3959 See \fB\-\-sub\-color\fP\&. Color used for the sub font border.
3960 .sp
3961 \fBNOTE:\fP
3962 .INDENT 7.0
3963 .INDENT 3.5
3964 ignored when \fB\-\-sub\-back\-color\fP is
3965 specified (or more exactly: when that option is not set to completely
3966 transparent).
3967 .UNINDENT
3968 .UNINDENT
3969 .TP
3970 .B \fB\-\-sub\-border\-size=<size>\fP
3971 Size of the sub font border in scaled pixels (see \fB\-\-sub\-font\-size\fP
3972 for details). A value of 0 disables borders.
3973 .sp
3974 Default: 3.
3975 .TP
3976 .B \fB\-\-sub\-color=<color>\fP
3977 Specify the color used for unstyled text subtitles.
3978 .sp
3979 The color is specified in the form \fBr/g/b\fP, where each color component
3980 is specified as number in the range 0.0 to 1.0. It\(aqs also possible to
3981 specify the transparency by using \fBr/g/b/a\fP, where the alpha value 0
3982 means fully transparent, and 1.0 means opaque. If the alpha component is
3983 not given, the color is 100% opaque.
3984 .sp
3985 Passing a single number to the option sets the sub to gray, and the form
3986 \fBgray/a\fP lets you specify alpha additionally.
3987 .INDENT 7.0
3988 .INDENT 3.5
3989 .IP "Examples"
3990 .INDENT 0.0
3991 .IP \(bu 2
3992 \fB\-\-sub\-color=1.0/0.0/0.0\fP set sub to opaque red
3993 .IP \(bu 2
3994 \fB\-\-sub\-color=1.0/0.0/0.0/0.75\fP set sub to opaque red with 75% alpha
3995 .IP \(bu 2
3996 \fB\-\-sub\-color=0.5/0.75\fP set sub to 50% gray with 75% alpha
3997 .UNINDENT
3998 .UNINDENT
3999 .UNINDENT
4000 .sp
4001 Alternatively, the color can be specified as a RGB hex triplet in the form
4002 \fB#RRGGBB\fP, where each 2\-digit group expresses a color value in the
4003 range 0 (\fB00\fP) to 255 (\fBFF\fP). For example, \fB#FF0000\fP is red.
4004 This is similar to web colors. Alpha is given with \fB#AARRGGBB\fP\&.
4005 .INDENT 7.0
4006 .INDENT 3.5
4007 .IP "Examples"
4008 .INDENT 0.0
4009 .IP \(bu 2
4010 \fB\-\-sub\-color=\(aq#FF0000\(aq\fP set sub to opaque red
4011 .IP \(bu 2
4012 \fB\-\-sub\-color=\(aq#C0808080\(aq\fP set sub to 50% gray with 75% alpha
4013 .UNINDENT
4014 .UNINDENT
4015 .UNINDENT
4016 .TP
4017 .B \fB\-\-sub\-margin\-x=<size>\fP
4018 Left and right screen margin for the subs in scaled pixels (see
4019 \fB\-\-sub\-font\-size\fP for details).
4020 .sp
4021 This option specifies the distance of the sub to the left, as well as at
4022 which distance from the right border long sub text will be broken.
4023 .sp
4024 Default: 25.
4025 .TP
4026 .B \fB\-\-sub\-margin\-y=<size>\fP
4027 Top and bottom screen margin for the subs in scaled pixels (see
4028 \fB\-\-sub\-font\-size\fP for details).
4029 .sp
4030 This option specifies the vertical margins of unstyled text subtitles.
4031 If you just want to raise the vertical subtitle position, use \fB\-\-sub\-pos\fP\&.
4032 .sp
4033 Default: 22.
4034 .TP
4035 .B \fB\-\-sub\-align\-x=<left|center|right>\fP
4036 Control to which corner of the screen text subtitles should be
4037 aligned to (default: \fBcenter\fP).
4038 .sp
4039 Never applied to ASS subtitles, except in \fB\-\-no\-sub\-ass\fP mode. Likewise,
4040 this does not apply to image subtitles.
4041 .TP
4042 .B \fB\-\-sub\-align\-y=<top|center|bottom>\fP
4043 Vertical position (default: \fBbottom\fP).
4044 Details see \fB\-\-sub\-align\-x\fP\&.
4045 .TP
4046 .B \fB\-\-sub\-justify=<auto|left|center|right>\fP
4047 Control how multi line subs are justified irrespective of where they
4048 are aligned (default: \fBauto\fP which justifies as defined by
4049 \fB\-\-sub\-align\-y\fP).
4050 Left justification is recommended to make the subs easier to read
4051 as it is easier for the eyes.
4052 .TP
4053 .B \fB\-\-sub\-ass\-justify=<yes|no>\fP
4054 Applies justification as defined by \fB\-\-sub\-justify\fP on ASS subtitles
4055 if \fB\-\-sub\-ass\-override\fP is not set to \fBno\fP\&.
4056 Default: \fBno\fP\&.
4057 .TP
4058 .B \fB\-\-sub\-shadow\-color=<color>\fP
4059 See \fB\-\-sub\-color\fP\&. Color used for sub text shadow.
4060 .TP
4061 .B \fB\-\-sub\-shadow\-offset=<size>\fP
4062 Displacement of the sub text shadow in scaled pixels (see
4063 \fB\-\-sub\-font\-size\fP for details). A value of 0 disables shadows.
4064 .sp
4065 Default: 0.
4066 .TP
4067 .B \fB\-\-sub\-spacing=<size>\fP
4068 Horizontal sub font spacing in scaled pixels (see \fB\-\-sub\-font\-size\fP
4069 for details). This value is added to the normal letter spacing. Negative
4070 values are allowed.
4071 .sp
4072 Default: 0.
4073 .TP
4074 .B \fB\-\-sub\-filter\-sdh=<yes|no>\fP
4075 Applies filter removing subtitle additions for the deaf or hard\-of\-hearing (SDH).
4076 This is intended for English, but may in part work for other languages too.
4077 The intention is that it can be always enabled so may not remove
4078 all parts added.
4079 It removes speaker labels (like MAN:), upper case text in parentheses and
4080 any text in brackets.
4081 .sp
4082 Default: \fBno\fP\&.
4083 .TP
4084 .B \fB\-\-sub\-filter\-sdh\-harder=<yes|no>\fP
4085 Do harder SDH filtering (if enabled by \fB\-\-sub\-filter\-sdh\fP).
4086 Will also remove speaker labels and text within parentheses using both
4087 lower and upper case letters.
4088 .sp
4089 Default: \fBno\fP\&.
4090 .TP
4091 .B \fB\-\-sub\-create\-cc\-track=<yes|no>\fP
4092 For every video stream, create a closed captions track (default: no). The
4093 only purpose is to make the track available for selection at the start of
4094 playback, instead of creating it lazily. This applies only to
4095 \fBATSC A53 Part 4 Closed Captions\fP (displayed by mpv as subtitle tracks
4096 using the codec \fBeia_608\fP). The CC track is marked "default" and selected
4097 according to the normal subtitle track selection rules. You can then use
4098 \fB\-\-sid\fP to explicitly select the correct track too.
4099 .sp
4100 If the video stream contains no closed captions, or if no video is being
4101 decoded, the CC track will remain empty and will not show any text.
4102 .TP
4103 .B \fB\-\-sub\-font\-provider=<auto|none|fontconfig>\fP
4104 Which libass font provider backend to use (default: auto). \fBauto\fP will
4105 attempt to use the native font provider: fontconfig on Linux, CoreText on
4106 OSX, DirectWrite on Windows. \fBfontconfig\fP forces fontconfig, if libass
4107 was built with support (if not, it behaves like \fBnone\fP).
4108 .sp
4109 The \fBnone\fP font provider effectively disables system fonts. It will still
4110 attempt to use embedded fonts (unless \fB\-\-embeddedfonts=no\fP is set; this is
4111 the same behavior as with all other font providers), \fBsubfont.ttf\fP if
4112 provided, and fonts in the \fBfonts\fP sub\-directory if provided. (The
4113 fallback is more strict than that of other font providers, and if a font
4114 name does not match, it may prefer not to render any text that uses the
4115 missing font.)
4116 .UNINDENT
4117 .SS Window
4118 .INDENT 0.0
4119 .TP
4120 .B \fB\-\-title=<string>\fP
4121 Set the window title. This is used for the video window, and if possible,
4122 also sets the audio stream title.
4123 .sp
4124 Properties are expanded. (See \fI\%Property Expansion\fP\&.)
4125 .sp
4126 \fBWARNING:\fP
4127 .INDENT 7.0
4128 .INDENT 3.5
4129 There is a danger of this causing significant CPU usage, depending on
4130 the properties used. Changing the window title is often a slow
4131 operation, and if the title changes every frame, playback can be ruined.
4132 .UNINDENT
4133 .UNINDENT
4134 .TP
4135 .B \fB\-\-screen=<default|0\-32>\fP
4136 In multi\-monitor configurations (i.e. a single desktop that spans across
4137 multiple displays), this option tells mpv which screen to display the
4138 video on.
4139 .INDENT 7.0
4140 .INDENT 3.5
4141 .IP "Note (X11)"
4142 .sp
4143 This option does not work properly with all window managers. In these
4144 cases, you can try to use \fB\-\-geometry\fP to position the window
4145 explicitly. It\(aqs also possible that the window manager provides native
4146 features to control which screens application windows should use.
4147 .UNINDENT
4148 .UNINDENT
4149 .sp
4150 See also \fB\-\-fs\-screen\fP\&.
4151 .TP
4152 .B \fB\-\-fullscreen\fP, \fB\-\-fs\fP
4153 Fullscreen playback.
4154 .TP
4155 .B \fB\-\-fs\-screen=<all|current|0\-32>\fP
4156 In multi\-monitor configurations (i.e. a single desktop that spans across
4157 multiple displays), this option tells mpv which screen to go fullscreen to.
4158 If \fBdefault\fP is provided mpv will fallback on using the behavior
4159 depending on what the user provided with the \fBscreen\fP option.
4160 .INDENT 7.0
4161 .INDENT 3.5
4162 .IP "Note (X11)"
4163 .sp
4164 This option works properly only with window managers which
4165 understand the EWMH \fB_NET_WM_FULLSCREEN_MONITORS\fP hint.
4166 .UNINDENT
4167 .UNINDENT
4168 .INDENT 7.0
4169 .INDENT 3.5
4170 .IP "Note (OS X)"
4171 .sp
4172 \fBall\fP does not work on OS X and will behave like \fBcurrent\fP\&.
4173 .UNINDENT
4174 .UNINDENT
4175 .sp
4176 See also \fB\-\-screen\fP\&.
4177 .TP
4178 .B \fB\-\-keep\-open=<yes|no|always>\fP
4179 Do not terminate when playing or seeking beyond the end of the file, and
4180 there is not next file to be played (and \fB\-\-loop\fP is not used).
4181 Instead, pause the player. When trying to seek beyond end of the file, the
4182 player will attempt to seek to the last frame.
4183 .sp
4184 Normally, this will act like \fBset pause yes\fP on EOF, unless the
4185 \fB\-\-keep\-open\-pause=no\fP option is set.
4186 .sp
4187 The following arguments can be given:
4188 .INDENT 7.0
4189 .TP
4190 .B no
4191 If the current file ends, go to the next file or terminate.
4192 (Default.)
4193 .TP
4194 .B yes
4195 Don\(aqt terminate if the current file is the last playlist entry.
4196 Equivalent to \fB\-\-keep\-open\fP without arguments.
4197 .TP
4198 .B always
4199 Like \fByes\fP, but also applies to files before the last playlist
4200 entry. This means playback will never automatically advance to
4201 the next file.
4202 .UNINDENT
4203 .sp
4204 \fBNOTE:\fP
4205 .INDENT 7.0
4206 .INDENT 3.5
4207 This option is not respected when using \fB\-\-frames\fP\&. Explicitly
4208 skipping to the next file if the binding uses \fBforce\fP will terminate
4209 playback as well.
4210 .sp
4211 Also, if errors or unusual circumstances happen, the player can quit
4212 anyway.
4213 .UNINDENT
4214 .UNINDENT
4215 .sp
4216 Since mpv 0.6.0, this doesn\(aqt pause if there is a next file in the playlist,
4217 or the playlist is looped. Approximately, this will pause when the player
4218 would normally exit, but in practice there are corner cases in which this
4219 is not the case (e.g. \fBmpv \-\-keep\-open file.mkv /dev/null\fP will play
4220 file.mkv normally, then fail to open \fB/dev/null\fP, then exit). (In
4221 mpv 0.8.0, \fBalways\fP was introduced, which restores the old behavior.)
4222 .TP
4223 .B \fB\-\-keep\-open\-pause=<yes|no>\fP
4224 If set to \fBno\fP, instead of pausing when \fB\-\-keep\-open\fP is active, just
4225 stop at end of file and continue playing forward when you seek backwards
4226 until end where it stops again. Default: \fByes\fP\&.
4227 .TP
4228 .B \fB\-\-image\-display\-duration=<seconds|inf>\fP
4229 If the current file is an image, play the image for the given amount of
4230 seconds (default: 1). \fBinf\fP means the file is kept open forever (until
4231 the user stops playback manually).
4232 .sp
4233 Unlike \fB\-\-keep\-open\fP, the player is not paused, but simply continues
4234 playback until the time has elapsed. (It should not use any resources
4235 during "playback".)
4236 .sp
4237 This affects image files, which are defined as having only 1 video frame
4238 and no audio. The player may recognize certain non\-images as images, for
4239 example if \fB\-\-length\fP is used to reduce the length to 1 frame, or if
4240 you seek to the last frame.
4241 .sp
4242 This option does not affect the framerate used for \fBmf://\fP or
4243 \fB\-\-merge\-files\fP\&. For that, use \fB\-\-mf\-fps\fP instead.
4244 .sp
4245 Setting \fB\-\-image\-display\-duration\fP hides the OSC and does not track
4246 playback time on the command\-line output, and also does not duplicate
4247 the image frame when encoding. To force the player into "dumb mode"
4248 and actually count out seconds, or to duplicate the image when
4249 encoding, you need to use \fB\-\-demuxer=lavf \-\-demuxer\-lavf\-o=loop=1\fP,
4250 and use \fB\-\-length\fP or \fB\-\-frames\fP to stop after a particular time.
4251 .TP
4252 .B \fB\-\-force\-window=<yes|no|immediate>\fP
4253 Create a video output window even if there is no video. This can be useful
4254 when pretending that mpv is a GUI application. Currently, the window
4255 always has the size 640x480, and is subject to \fB\-\-geometry\fP,
4256 \fB\-\-autofit\fP, and similar options.
4257 .sp
4258 \fBWARNING:\fP
4259 .INDENT 7.0
4260 .INDENT 3.5
4261 The window is created only after initialization (to make sure default
4262 window placement still works if the video size is different from the
4263 \fB\-\-force\-window\fP default window size). This can be a problem if
4264 initialization doesn\(aqt work perfectly, such as when opening URLs with
4265 bad network connection, or opening broken video files. The \fBimmediate\fP
4266 mode can be used to create the window always on program start, but this
4267 may cause other issues.
4268 .UNINDENT
4269 .UNINDENT
4270 .TP
4271 .B \fB\-\-taskbar\-progress\fP, \fB\-\-no\-taskbar\-progress\fP
4272 (Windows only)
4273 Enable/disable playback progress rendering in taskbar (Windows 7 and above).
4274 .sp
4275 Enabled by default.
4276 .TP
4277 .B \fB\-\-snap\-window\fP
4278 (Windows only) Snap the player window to screen edges.
4279 .TP
4280 .B \fB\-\-ontop\fP
4281 Makes the player window stay on top of other windows.
4282 .sp
4283 On Windows, if combined with fullscreen mode, this causes mpv to be
4284 treated as exclusive fullscreen window that bypasses the Desktop Window
4285 Manager.
4286 .TP
4287 .B \fB\-\-ontop\-level=<window|system|level>\fP
4288 (OS X only)
4289 Sets the level of an ontop window (default: window).
4290 .INDENT 7.0
4291 .TP
4292 .B window
4293 On top of all other windows.
4294 .TP
4295 .B system
4296 On top of system elements like Taskbar, Menubar and Dock.
4297 .TP
4298 .B level
4299 A level as integer.
4300 .UNINDENT
4301 .TP
4302 .B \fB\-\-border\fP, \fB\-\-no\-border\fP
4303 Play video with window border and decorations. Since this is on by
4304 default, use \fB\-\-no\-border\fP to disable the standard window decorations.
4305 .TP
4306 .B \fB\-\-fit\-border\fP, \fB\-\-no\-fit\-border\fP
4307 (Windows only) Fit the whole window with border and decorations on the
4308 screen. Since this is on by default, use \fB\-\-no\-fit\-border\fP to make mpv
4309 try to only fit client area with video on the screen. This behavior only
4310 applied to window/video with size exceeding size of the screen.
4311 .TP
4312 .B \fB\-\-on\-all\-workspaces\fP
4313 (X11 only)
4314 Show the video window on all virtual desktops.
4315 .TP
4316 .B \fB\-\-geometry=<[W[xH]][+\-x+\-y]>\fP, \fB\-\-geometry=<x:y>\fP
4317 Adjust the initial window position or size. \fBW\fP and \fBH\fP set the window
4318 size in pixels. \fBx\fP and \fBy\fP set the window position, measured in pixels
4319 from the top\-left corner of the screen to the top\-left corner of the image
4320 being displayed. If a percentage sign (\fB%\fP) is given after the argument,
4321 it turns the value into a percentage of the screen size in that direction.
4322 Positions are specified similar to the standard X11 \fB\-\-geometry\fP option
4323 format, in which e.g. +10\-50 means "place 10 pixels from the left border and
4324 50 pixels from the lower border" and "\-\-20+\-10" means "place 20 pixels
4325 beyond the right and 10 pixels beyond the top border".
4326 .sp
4327 If an external window is specified using the \fB\-\-wid\fP option, this
4328 option is ignored.
4329 .sp
4330 The coordinates are relative to the screen given with \fB\-\-screen\fP for the
4331 video output drivers that fully support \fB\-\-screen\fP\&.
4332 .sp
4333 \fBNOTE:\fP
4334 .INDENT 7.0
4335 .INDENT 3.5
4336 Generally only supported by GUI VOs. Ignored for encoding.
4337 .UNINDENT
4338 .UNINDENT
4339 .\" admonition: Note (OS X)
4340 .\"
4341 .\" On Mac OS X the origin of the screen coordinate system is located on the
4342 .\" bottom-left corner. For instance, ``0:0`` will place the window at the
4343 .\" bottom-left of the screen.
4344 .
4345 .INDENT 7.0
4346 .INDENT 3.5
4347 .IP "Note (X11)"
4348 .sp
4349 This option does not work properly with all window managers.
4350 .UNINDENT
4351 .UNINDENT
4352 .INDENT 7.0
4353 .INDENT 3.5
4354 .IP "Examples"
4355 .INDENT 0.0
4356 .TP
4357 .B \fB50:40\fP
4358 Places the window at x=50, y=40.
4359 .TP
4360 .B \fB50%:50%\fP
4361 Places the window in the middle of the screen.
4362 .TP
4363 .B \fB100%:100%\fP
4364 Places the window at the bottom right corner of the screen.
4365 .TP
4366 .B \fB50%\fP
4367 Sets the window width to half the screen width. Window height is set
4368 so that the window has the video aspect ratio.
4369 .TP
4370 .B \fB50%x50%\fP
4371 Forces the window width and height to half the screen width and
4372 height. Will show black borders to compensate for the video aspect
4373 ratio (with most VOs and without \fB\-\-no\-keepaspect\fP).
4374 .TP
4375 .B \fB50%+10+10\fP
4376 Sets the window to half the screen widths, and positions it 10
4377 pixels below/left of the top left corner of the screen.
4378 .UNINDENT
4379 .UNINDENT
4380 .UNINDENT
4381 .sp
4382 See also \fB\-\-autofit\fP and \fB\-\-autofit\-larger\fP for fitting the window into
4383 a given size without changing aspect ratio.
4384 .TP
4385 .B \fB\-\-autofit=<[W[xH]]>\fP
4386 Set the initial window size to a maximum size specified by \fBWxH\fP, without
4387 changing the window\(aqs aspect ratio. The size is measured in pixels, or if
4388 a number is followed by a percentage sign (\fB%\fP), in percents of the
4389 screen size.
4390 .sp
4391 This option never changes the aspect ratio of the window. If the aspect
4392 ratio mismatches, the window\(aqs size is reduced until it fits into the
4393 specified size.
4394 .sp
4395 Window position is not taken into account, nor is it modified by this
4396 option (the window manager still may place the window differently depending
4397 on size). Use \fB\-\-geometry\fP to change the window position. Its effects
4398 are applied after this option.
4399 .sp
4400 See \fB\-\-geometry\fP for details how this is handled with multi\-monitor
4401 setups.
4402 .sp
4403 Use \fB\-\-autofit\-larger\fP instead if you just want to limit the maximum size
4404 of the window, rather than always forcing a window size.
4405 .sp
4406 Use \fB\-\-geometry\fP if you want to force both window width and height to a
4407 specific size.
4408 .sp
4409 \fBNOTE:\fP
4410 .INDENT 7.0
4411 .INDENT 3.5
4412 Generally only supported by GUI VOs. Ignored for encoding.
4413 .UNINDENT
4414 .UNINDENT
4415 .INDENT 7.0
4416 .INDENT 3.5
4417 .IP "Examples"
4418 .INDENT 0.0
4419 .TP
4420 .B \fB70%\fP
4421 Make the window width 70% of the screen size, keeping aspect ratio.
4422 .TP
4423 .B \fB1000\fP
4424 Set the window width to 1000 pixels, keeping aspect ratio.
4425 .TP
4426 .B \fB70%x60%\fP
4427 Make the window as large as possible, without being wider than 70%
4428 of the screen width, or higher than 60% of the screen height.
4429 .UNINDENT
4430 .UNINDENT
4431 .UNINDENT
4432 .TP
4433 .B \fB\-\-autofit\-larger=<[W[xH]]>\fP
4434 This option behaves exactly like \fB\-\-autofit\fP, except the window size is
4435 only changed if the window would be larger than the specified size.
4436 .INDENT 7.0
4437 .INDENT 3.5
4438 .IP "Example"
4439 .INDENT 0.0
4440 .TP
4441 .B \fB90%x80%\fP
4442 If the video is larger than 90% of the screen width or 80% of the
4443 screen height, make the window smaller until either its width is 90%
4444 of the screen, or its height is 80% of the screen.
4445 .UNINDENT
4446 .UNINDENT
4447 .UNINDENT
4448 .TP
4449 .B \fB\-\-autofit\-smaller=<[W[xH]]>\fP
4450 This option behaves exactly like \fB\-\-autofit\fP, except that it sets the
4451 minimum size of the window (just as \fB\-\-autofit\-larger\fP sets the maximum).
4452 .INDENT 7.0
4453 .INDENT 3.5
4454 .IP "Example"
4455 .INDENT 0.0
4456 .TP
4457 .B \fB500x500\fP
4458 Make the window at least 500 pixels wide and 500 pixels high
4459 (depending on the video aspect ratio, the width or height will be
4460 larger than 500 in order to keep the aspect ratio the same).
4461 .UNINDENT
4462 .UNINDENT
4463 .UNINDENT
4464 .TP
4465 .B \fB\-\-window\-scale=<factor>\fP
4466 Resize the video window to a multiple (or fraction) of the video size. This
4467 option is applied before \fB\-\-autofit\fP and other options are applied (so
4468 they override this option).
4469 .sp
4470 For example, \fB\-\-window\-scale=0.5\fP would show the window at half the
4471 video size.
4472 .TP
4473 .B \fB\-\-cursor\-autohide=<number|no|always>\fP
4474 Make mouse cursor automatically hide after given number of milliseconds.
4475 \fBno\fP will disable cursor autohide. \fBalways\fP means the cursor will stay
4476 hidden.
4477 .TP
4478 .B \fB\-\-cursor\-autohide\-fs\-only\fP
4479 If this option is given, the cursor is always visible in windowed mode. In
4480 fullscreen mode, the cursor is shown or hidden according to
4481 \fB\-\-cursor\-autohide\fP\&.
4482 .TP
4483 .B \fB\-\-no\-fixed\-vo\fP, \fB\-\-fixed\-vo\fP
4484 \fB\-\-no\-fixed\-vo\fP enforces closing and reopening the video window for
4485 multiple files (one (un)initialization for each file).
4486 .TP
4487 .B \fB\-\-force\-rgba\-osd\-rendering\fP
4488 Change how some video outputs render the OSD and text subtitles. This
4489 does not change appearance of the subtitles and only has performance
4490 implications. For VOs which support native ASS rendering (like \fBgpu\fP,
4491 \fBvdpau\fP, \fBdirect3d\fP), this can be slightly faster or slower,
4492 depending on GPU drivers and hardware. For other VOs, this just makes
4493 rendering slower.
4494 .TP
4495 .B \fB\-\-force\-window\-position\fP
4496 Forcefully move mpv\(aqs video output window to default location whenever
4497 there is a change in video parameters, video stream or file. This used to
4498 be the default behavior. Currently only affects X11 VOs.
4499 .TP
4500 .B \fB\-\-no\-keepaspect\fP, \fB\-\-keepaspect\fP
4501 \fB\-\-no\-keepaspect\fP will always stretch the video to window size, and will
4502 disable the window manager hints that force the window aspect ratio.
4503 (Ignored in fullscreen mode.)
4504 .TP
4505 .B \fB\-\-no\-keepaspect\-window\fP, \fB\-\-keepaspect\-window\fP
4506 \fB\-\-keepaspect\-window\fP (the default) will lock the window size to the
4507 video aspect. \fB\-\-no\-keepaspect\-window\fP disables this behavior, and will
4508 instead add black bars if window aspect and video aspect mismatch. Whether
4509 this actually works depends on the VO backend.
4510 (Ignored in fullscreen mode.)
4511 .TP
4512 .B \fB\-\-monitoraspect=<ratio>\fP
4513 Set the aspect ratio of your monitor or TV screen. A value of 0 disables a
4514 previous setting (e.g. in the config file). Overrides the
4515 \fB\-\-monitorpixelaspect\fP setting if enabled.
4516 .sp
4517 See also \fB\-\-monitorpixelaspect\fP and \fB\-\-video\-aspect\-override\fP\&.
4518 .INDENT 7.0
4519 .INDENT 3.5
4520 .IP "Examples"
4521 .INDENT 0.0
4522 .IP \(bu 2
4523 \fB\-\-monitoraspect=4:3\fP or \fB\-\-monitoraspect=1.3333\fP
4524 .IP \(bu 2
4525 \fB\-\-monitoraspect=16:9\fP or \fB\-\-monitoraspect=1.7777\fP
4526 .UNINDENT
4527 .UNINDENT
4528 .UNINDENT
4529 .TP
4530 .B \fB\-\-hidpi\-window\-scale\fP, \fB\-\-no\-hidpi\-window\-scale\fP
4531 (OS X and X11 only)
4532 Scale the window size according to the backing scale factor (default: yes).
4533 On regular HiDPI resolutions the window opens with double the size but appears
4534 as having the same size as on none\-HiDPI resolutions. This is the default OS X
4535 behavior.
4536 .TP
4537 .B \fB\-\-native\-fs\fP, \fB\-\-no\-native\-fs\fP
4538 (OS X only)
4539 Uses the native fullscreen mechanism of the OS (default: yes).
4540 .TP
4541 .B \fB\-\-monitorpixelaspect=<ratio>\fP
4542 Set the aspect of a single pixel of your monitor or TV screen (default:
4543 1). A value of 1 means square pixels (correct for (almost?) all LCDs). See
4544 also \fB\-\-monitoraspect\fP and \fB\-\-video\-aspect\-override\fP\&.
4545 .TP
4546 .B \fB\-\-stop\-screensaver\fP, \fB\-\-no\-stop\-screensaver\fP
4547 Turns off the screensaver (or screen blanker and similar mechanisms) at
4548 startup and turns it on again on exit (default: yes). The screensaver is
4549 always re\-enabled when the player is paused.
4550 .sp
4551 This is not supported on all video outputs or platforms. Sometimes it is
4552 implemented, but does not work (especially with Linux "desktops").
4553 .TP
4554 .B \fB\-\-wid=<ID>\fP
4555 This tells mpv to attach to an existing window. If a VO is selected that
4556 supports this option, it will use that window for video output. mpv will
4557 scale the video to the size of this window, and will add black bars to
4558 compensate if the aspect ratio of the video is different.
4559 .sp
4560 On X11, the ID is interpreted as a \fBWindow\fP on X11. Unlike
4561 MPlayer/mplayer2, mpv always creates its own window, and sets the wid
4562 window as parent. The window will always be resized to cover the parent
4563 window fully. The value \fB0\fP is interpreted specially, and mpv will
4564 draw directly on the root window.
4565 .sp
4566 On win32, the ID is interpreted as \fBHWND\fP\&. Pass it as value cast to
4567 \fBintptr_t\fP\&. mpv will create its own window, and set the wid window as
4568 parent, like with X11.
4569 .sp
4570 On OSX/Cocoa, the ID is interpreted as \fBNSView*\fP\&. Pass it as value cast
4571 to \fBintptr_t\fP\&. mpv will create its own sub\-view. Because OSX does not
4572 support window embedding of foreign processes, this works only with libmpv,
4573 and will crash when used from the command line.
4574 .sp
4575 On Android, the ID is interpreted as \fBandroid.view.Surface\fP\&. Pass it as a
4576 value cast to \fBintptr_t\fP\&. Use with \fB\-\-vo=mediacodec_embed\fP and
4577 \fB\-\-hwdec=mediacodec\fP for direct rendering using MediaCodec, or with
4578 \fB\-\-vo=gpu \-\-gpu\-context=android\fP (with or without \fB\-\-hwdec=mediacodec\-copy\fP).
4579 .TP
4580 .B \fB\-\-no\-window\-dragging\fP
4581 Don\(aqt move the window when clicking on it and moving the mouse pointer.
4582 .TP
4583 .B \fB\-\-x11\-name\fP
4584 Set the window class name for X11\-based video output methods.
4585 .TP
4586 .B \fB\-\-x11\-netwm=<yes|no|auto>\fP
4587 (X11 only)
4588 Control the use of NetWM protocol features.
4589 .sp
4590 This may or may not help with broken window managers. This provides some
4591 functionality that was implemented by the now removed \fB\-\-fstype\fP option.
4592 Actually, it is not known to the developers to which degree this option
4593 was needed, so feedback is welcome.
4594 .sp
4595 Specifically, \fByes\fP will force use of NetWM fullscreen support, even if
4596 not advertised by the WM. This can be useful for WMs that are broken on
4597 purpose, like XMonad. (XMonad supposedly doesn\(aqt advertise fullscreen
4598 support, because Flash uses it. Apparently, applications which want to
4599 use fullscreen anyway are supposed to either ignore the NetWM support hints,
4600 or provide a workaround. Shame on XMonad for deliberately breaking X
4601 protocols (as if X isn\(aqt bad enough already).
4602 .sp
4603 By default, NetWM support is autodetected (\fBauto\fP).
4604 .sp
4605 This option might be removed in the future.
4606 .TP
4607 .B \fB\-\-x11\-bypass\-compositor=<yes|no|fs\-only|never>\fP
4608 If set to \fByes\fP, then ask the compositor to unredirect the mpv window
4609 (default: \fBfs\-only\fP). This uses the \fB_NET_WM_BYPASS_COMPOSITOR\fP hint.
4610 .sp
4611 \fBfs\-only\fP asks the window manager to disable the compositor only in
4612 fullscreen mode.
4613 .sp
4614 \fBno\fP sets \fB_NET_WM_BYPASS_COMPOSITOR\fP to 0, which is the default value
4615 as declared by the EWMH specification, i.e. no change is done.
4616 .sp
4617 \fBnever\fP asks the window manager to never disable the compositor.
4618 .UNINDENT
4619 .SS Disc Devices
4620 .INDENT 0.0
4621 .TP
4622 .B \fB\-\-cdrom\-device=<path>\fP
4623 Specify the CD\-ROM device (default: \fB/dev/cdrom\fP).
4624 .TP
4625 .B \fB\-\-dvd\-device=<path>\fP
4626 Specify the DVD device or .iso filename (default: \fB/dev/dvd\fP). You can
4627 also specify a directory that contains files previously copied directly
4628 from a DVD (with e.g. vobcopy).
4629 .INDENT 7.0
4630 .INDENT 3.5
4631 .IP "Example"
4632 .sp
4633 \fBmpv dvd:// \-\-dvd\-device=/path/to/dvd/\fP
4634 .UNINDENT
4635 .UNINDENT
4636 .TP
4637 .B \fB\-\-bluray\-device=<path>\fP
4638 (Blu\-ray only)
4639 Specify the Blu\-ray disc location. Must be a directory with Blu\-ray
4640 structure.
4641 .INDENT 7.0
4642 .INDENT 3.5
4643 .IP "Example"
4644 .sp
4645 \fBmpv bd:// \-\-bluray\-device=/path/to/bd/\fP
4646 .UNINDENT
4647 .UNINDENT
4648 .TP
4649 .B \fB\-\-cdda\-...\fP
4650 These options can be used to tune the CD Audio reading feature of mpv.
4651 .TP
4652 .B \fB\-\-cdda\-speed=<value>\fP
4653 Set CD spin speed.
4654 .TP
4655 .B \fB\-\-cdda\-paranoia=<0\-2>\fP
4656 Set paranoia level. Values other than 0 seem to break playback of
4657 anything but the first track.
4658 .INDENT 7.0
4659 .TP
4660 .B 0
4661 disable checking (default)
4662 .TP
4663 .B 1
4664 overlap checking only
4665 .TP
4666 .B 2
4667 full data correction and verification
4668 .UNINDENT
4669 .TP
4670 .B \fB\-\-cdda\-sector\-size=<value>\fP
4671 Set atomic read size.
4672 .TP
4673 .B \fB\-\-cdda\-overlap=<value>\fP
4674 Force minimum overlap search during verification to <value> sectors.
4675 .TP
4676 .B \fB\-\-cdda\-toc\-bias\fP
4677 Assume that the beginning offset of track 1 as reported in the TOC
4678 will be addressed as LBA 0. Some discs need this for getting track
4679 boundaries correctly.
4680 .TP
4681 .B \fB\-\-cdda\-toc\-offset=<value>\fP
4682 Add \fB<value>\fP sectors to the values reported when addressing tracks.
4683 May be negative.
4684 .TP
4685 .B \fB\-\-cdda\-skip=<yes|no>\fP
4686 (Never) accept imperfect data reconstruction.
4687 .TP
4688 .B \fB\-\-cdda\-cdtext=<yes|no>\fP
4689 Print CD text. This is disabled by default, because it ruins performance
4690 with CD\-ROM drives for unknown reasons.
4691 .TP
4692 .B \fB\-\-dvd\-speed=<speed>\fP
4693 Try to limit DVD speed (default: 0, no change). DVD base speed is 1385
4694 kB/s, so an 8x drive can read at speeds up to 11080 kB/s. Slower speeds
4695 make the drive more quiet. For watching DVDs, 2700 kB/s should be quiet and
4696 fast enough. mpv resets the speed to the drive default value on close.
4697 Values of at least 100 mean speed in kB/s. Values less than 100 mean
4698 multiples of 1385 kB/s, i.e. \fB\-\-dvd\-speed=8\fP selects 11080 kB/s.
4699 .sp
4700 \fBNOTE:\fP
4701 .INDENT 7.0
4702 .INDENT 3.5
4703 You need write access to the DVD device to change the speed.
4704 .UNINDENT
4705 .UNINDENT
4706 .TP
4707 .B \fB\-\-dvd\-angle=<ID>\fP
4708 Some DVDs contain scenes that can be viewed from multiple angles.
4709 This option tells mpv which angle to use (default: 1).
4710 .UNINDENT
4711 .SS Equalizer
4712 .INDENT 0.0
4713 .TP
4714 .B \fB\-\-brightness=<\-100\-100>\fP
4715 Adjust the brightness of the video signal (default: 0). Not supported by
4716 all video output drivers.
4717 .TP
4718 .B \fB\-\-contrast=<\-100\-100>\fP
4719 Adjust the contrast of the video signal (default: 0). Not supported by all
4720 video output drivers.
4721 .TP
4722 .B \fB\-\-saturation=<\-100\-100>\fP
4723 Adjust the saturation of the video signal (default: 0). You can get
4724 grayscale output with this option. Not supported by all video output
4725 drivers.
4726 .TP
4727 .B \fB\-\-gamma=<\-100\-100>\fP
4728 Adjust the gamma of the video signal (default: 0). Not supported by all
4729 video output drivers.
4730 .TP
4731 .B \fB\-\-hue=<\-100\-100>\fP
4732 Adjust the hue of the video signal (default: 0). You can get a colored
4733 negative of the image with this option. Not supported by all video output
4734 drivers.
4735 .UNINDENT
4736 .SS Demuxer
4737 .INDENT 0.0
4738 .TP
4739 .B \fB\-\-demuxer=<[+]name>\fP
4740 Force demuxer type. Use a \(aq+\(aq before the name to force it; this will skip
4741 some checks. Give the demuxer name as printed by \fB\-\-demuxer=help\fP\&.
4742 .TP
4743 .B \fB\-\-demuxer\-lavf\-analyzeduration=<value>\fP
4744 Maximum length in seconds to analyze the stream properties.
4745 .TP
4746 .B \fB\-\-demuxer\-lavf\-probe\-info=<yes|no|auto|nostreams>\fP
4747 Whether to probe stream information (default: auto). Technically, this
4748 controls whether libavformat\(aqs \fBavformat_find_stream_info()\fP function
4749 is called. Usually it\(aqs safer to call it, but it can also make startup
4750 slower.
4751 .sp
4752 The \fBauto\fP choice (the default) tries to skip this for a few know\-safe
4753 whitelisted formats, while calling it for everything else.
4754 .sp
4755 The \fBnostreams\fP choice only calls it if and only if the file seems to
4756 contain no streams after opening (helpful in cases when calling the function
4757 is needed to detect streams at all, such as with FLV files).
4758 .TP
4759 .B \fB\-\-demuxer\-lavf\-probescore=<1\-100>\fP
4760 Minimum required libavformat probe score. Lower values will require
4761 less data to be loaded (makes streams start faster), but makes file
4762 format detection less reliable. Can be used to force auto\-detected
4763 libavformat demuxers, even if libavformat considers the detection not
4764 reliable enough. (Default: 26.)
4765 .TP
4766 .B \fB\-\-demuxer\-lavf\-allow\-mimetype=<yes|no>\fP
4767 Allow deriving the format from the HTTP MIME type (default: yes). Set
4768 this to no in case playing things from HTTP mysteriously fails, even
4769 though the same files work from local disk.
4770 .sp
4771 This is default in order to reduce latency when opening HTTP streams.
4772 .TP
4773 .B \fB\-\-demuxer\-lavf\-format=<name>\fP
4774 Force a specific libavformat demuxer.
4775 .TP
4776 .B \fB\-\-demuxer\-lavf\-hacks=<yes|no>\fP
4777 By default, some formats will be handled differently from other formats
4778 by explicitly checking for them. Most of these compensate for weird or
4779 imperfect behavior from libavformat demuxers. Passing \fBno\fP disables
4780 these. For debugging and testing only.
4781 .TP
4782 .B \fB\-\-demuxer\-lavf\-o=<key>=<value>[,<key>=<value>[,...]]\fP
4783 Pass AVOptions to libavformat demuxer.
4784 .sp
4785 Note, a patch to make the \fIo=\fP unneeded and pass all unknown options
4786 through the AVOption system is welcome. A full list of AVOptions can
4787 be found in the FFmpeg manual. Note that some options may conflict
4788 with mpv options.
4789 .INDENT 7.0
4790 .INDENT 3.5
4791 .IP "Example"
4792 .sp
4793 \fB\-\-demuxer\-lavf\-o=fflags=+ignidx\fP
4794 .UNINDENT
4795 .UNINDENT
4796 .TP
4797 .B \fB\-\-demuxer\-lavf\-probesize=<value>\fP
4798 Maximum amount of data to probe during the detection phase. In the
4799 case of MPEG\-TS this value identifies the maximum number of TS packets
4800 to scan.
4801 .TP
4802 .B \fB\-\-demuxer\-lavf\-buffersize=<value>\fP
4803 Size of the stream read buffer allocated for libavformat in bytes
4804 (default: 32768). Lowering the size could lower latency. Note that
4805 libavformat might reallocate the buffer internally, or not fully use all
4806 of it.
4807 .TP
4808 .B \fB\-\-demuxer\-lavf\-linearize\-timestamps=<yes|no|auto>\fP
4809 Attempt to linearize timestamp resets in demuxed streams (default: auto).
4810 This was tested only for single audio streams. It\(aqs unknown whether it
4811 works correctly for video (but likely won\(aqt). Note that the implementation
4812 is slightly incorrect either way, and will introduce a discontinuity by
4813 about 1 codec frame size.
4814 .sp
4815 The \fBauto\fP mode enables this for OGG audio stream. This covers the common
4816 and annoying case of OGG web radio streams. Some of these will reset
4817 timestamps to 0 every time a new song begins. This breaks the mpv seekable
4818 cache, which can\(aqt deal with timestamp resets. Note that FFmpeg/libavformat\(aqs
4819 seeking API can\(aqt deal with this either; it\(aqs likely that if this option
4820 breaks this even more, while if it\(aqs disabled, you can at least seek within
4821 the first song in the stream. Well, you won\(aqt get anything useful either
4822 way if the seek is outside of mpv\(aqs cache.
4823 .TP
4824 .B \fB\-\-demuxer\-mkv\-subtitle\-preroll=<yes|index|no>\fP, \fB\-\-mkv\-subtitle\-preroll\fP
4825 Try harder to show embedded soft subtitles when seeking somewhere. Normally,
4826 it can happen that the subtitle at the seek target is not shown due to how
4827 some container file formats are designed. The subtitles appear only if
4828 seeking before or exactly to the position a subtitle first appears. To
4829 make this worse, subtitles are often timed to appear a very small amount
4830 before the associated video frame, so that seeking to the video frame
4831 typically does not demux the subtitle at that position.
4832 .sp
4833 Enabling this option makes the demuxer start reading data a bit before the
4834 seek target, so that subtitles appear correctly. Note that this makes
4835 seeking slower, and is not guaranteed to always work. It only works if the
4836 subtitle is close enough to the seek target.
4837 .sp
4838 Works with the internal Matroska demuxer only. Always enabled for absolute
4839 and hr\-seeks, and this option changes behavior with relative or imprecise
4840 seeks only.
4841 .sp
4842 You can use the \fB\-\-demuxer\-mkv\-subtitle\-preroll\-secs\fP option to specify
4843 how much data the demuxer should pre\-read at most in order to find subtitle
4844 packets that may overlap. Setting this to 0 will effectively disable this
4845 preroll mechanism. Setting a very large value can make seeking very slow,
4846 and an extremely large value would completely reread the entire file from
4847 start to seek target on every seek \- seeking can become slower towards the
4848 end of the file. The details are messy, and the value is actually rounded
4849 down to the cluster with the previous video keyframe.
4850 .sp
4851 Some files, especially files muxed with newer mkvmerge versions, have
4852 information embedded that can be used to determine what subtitle packets
4853 overlap with a seek target. In these cases, mpv will reduce the amount
4854 of data read to a minimum. (Although it will still read \fIall\fP data between
4855 the cluster that contains the first wanted subtitle packet, and the seek
4856 target.) If the \fBindex\fP choice (which is the default) is specified, then
4857 prerolling will be done only if this information is actually available. If
4858 this method is used, the maximum amount of data to skip can be additionally
4859 controlled by \fB\-\-demuxer\-mkv\-subtitle\-preroll\-secs\-index\fP (it still uses
4860 the value of the option without \fB\-index\fP if that is higher).
4861 .sp
4862 See also \fB\-\-hr\-seek\-demuxer\-offset\fP option. This option can achieve a
4863 similar effect, but only if hr\-seek is active. It works with any demuxer,
4864 but makes seeking much slower, as it has to decode audio and video data
4865 instead of just skipping over it.
4866 .sp
4867 \fB\-\-mkv\-subtitle\-preroll\fP is a deprecated alias.
4868 .TP
4869 .B \fB\-\-demuxer\-mkv\-subtitle\-preroll\-secs=<value>\fP
4870 See \fB\-\-demuxer\-mkv\-subtitle\-preroll\fP\&.
4871 .TP
4872 .B \fB\-\-demuxer\-mkv\-subtitle\-preroll\-secs\-index=<value>\fP
4873 See \fB\-\-demuxer\-mkv\-subtitle\-preroll\fP\&.
4874 .TP
4875 .B \fB\-\-demuxer\-mkv\-probe\-video\-duration=<yes|no|full>\fP
4876 When opening the file, seek to the end of it, and check what timestamp the
4877 last video packet has, and report that as file duration. This is strictly
4878 for compatibility with Haali only. In this mode, it\(aqs possible that opening
4879 will be slower (especially when playing over http), or that behavior with
4880 broken files is much worse. So don\(aqt use this option.
4881 .sp
4882 The \fByes\fP mode merely uses the index and reads a small number of blocks
4883 from the end of the file. The \fBfull\fP mode actually traverses the entire
4884 file and can make a reliable estimate even without an index present (such
4885 as partial files).
4886 .TP
4887 .B \fB\-\-demuxer\-rawaudio\-channels=<value>\fP
4888 Number of channels (or channel layout) if \fB\-\-demuxer=rawaudio\fP is used
4889 (default: stereo).
4890 .TP
4891 .B \fB\-\-demuxer\-rawaudio\-format=<value>\fP
4892 Sample format for \fB\-\-demuxer=rawaudio\fP (default: s16le).
4893 Use \fB\-\-demuxer\-rawaudio\-format=help\fP to get a list of all formats.
4894 .TP
4895 .B \fB\-\-demuxer\-rawaudio\-rate=<value>\fP
4896 Sample rate for \fB\-\-demuxer=rawaudio\fP (default: 44 kHz).
4897 .TP
4898 .B \fB\-\-demuxer\-rawvideo\-fps=<value>\fP
4899 Rate in frames per second for \fB\-\-demuxer=rawvideo\fP (default: 25.0).
4900 .TP
4901 .B \fB\-\-demuxer\-rawvideo\-w=<value>\fP, \fB\-\-demuxer\-rawvideo\-h=<value>\fP
4902 Image dimension in pixels for \fB\-\-demuxer=rawvideo\fP\&.
4903 .INDENT 7.0
4904 .INDENT 3.5
4905 .IP "Example"
4906 .sp
4907 Play a raw YUV sample:
4908 .INDENT 0.0
4909 .INDENT 3.5
4910 .sp
4911 .nf
4912 .ft C
4913 mpv sample\-720x576.yuv \-\-demuxer=rawvideo \e
4914 \-\-demuxer\-rawvideo\-w=720 \-\-demuxer\-rawvideo\-h=576
4915 .ft P
4916 .fi
4917 .UNINDENT
4918 .UNINDENT
4919 .UNINDENT
4920 .UNINDENT
4921 .TP
4922 .B \fB\-\-demuxer\-rawvideo\-format=<value>\fP
4923 Color space (fourcc) in hex or string for \fB\-\-demuxer=rawvideo\fP
4924 (default: \fBYV12\fP).
4925 .TP
4926 .B \fB\-\-demuxer\-rawvideo\-mp\-format=<value>\fP
4927 Color space by internal video format for \fB\-\-demuxer=rawvideo\fP\&. Use
4928 \fB\-\-demuxer\-rawvideo\-mp\-format=help\fP for a list of possible formats.
4929 .TP
4930 .B \fB\-\-demuxer\-rawvideo\-codec=<value>\fP
4931 Set the video codec instead of selecting the rawvideo codec when using
4932 \fB\-\-demuxer=rawvideo\fP\&. This uses the same values as codec names in
4933 \fB\-\-vd\fP (but it does not accept decoder names).
4934 .TP
4935 .B \fB\-\-demuxer\-rawvideo\-size=<value>\fP
4936 Frame size in bytes when using \fB\-\-demuxer=rawvideo\fP\&.
4937 .TP
4938 .B \fB\-\-demuxer\-cue\-codepage=<codepage>\fP
4939 Specify the CUE sheet codepage. (See \fB\-\-sub\-codepage\fP for details.)
4940 .TP
4941 .B \fB\-\-demuxer\-max\-bytes=<bytesize>\fP
4942 This controls how much the demuxer is allowed to buffer ahead. The demuxer
4943 will normally try to read ahead as much as necessary, or as much is
4944 requested with \fB\-\-demuxer\-readahead\-secs\fP\&. The option can be used to
4945 restrict the maximum readahead. This limits excessive readahead in case of
4946 broken files or desynced playback. The demuxer will stop reading additional
4947 packets as soon as one of the limits is reached. (The limits still can be
4948 slightly overstepped due to technical reasons.)
4949 .sp
4950 Set these limits higher if you get a packet queue overflow warning, and
4951 you think normal playback would be possible with a larger packet queue.
4952 .sp
4953 See \fB\-\-list\-options\fP for defaults and value range. \fB<bytesize>\fP options
4954 accept suffixes such as \fBKiB\fP and \fBMiB\fP\&.
4955 .TP
4956 .B \fB\-\-demuxer\-max\-back\-bytes=<bytesize>\fP
4957 This controls how much past data the demuxer is allowed to preserve. This
4958 is useful only if the \fB\-\-demuxer\-seekable\-cache\fP option is enabled.
4959 Unlike the forward cache, there is no control how many seconds are actually
4960 cached \- it will simply use as much memory this option allows. Setting this
4961 option to 0 will strictly disable any back buffer, but this will lead to
4962 the situation that the forward seek range starts after the current playback
4963 position (as it removes past packets that are seek points).
4964 .sp
4965 If the end of the file is reached, the remaining unused forward buffer space
4966 is "donated" to the backbuffer (unless the backbuffer size is set to 0).
4967 This still limits the total cache usage to the sum of the forward and
4968 backward cache, and effectively makes better use of the total allowed memory
4969 budget. (The opposite does not happen: free backward buffer is never
4970 "donated" to the forward buffer.)
4971 .sp
4972 Keep in mind that other buffers in the player (like decoders) will cause the
4973 demuxer to cache "future" frames in the back buffer, which can skew the
4974 impression about how much data the backbuffer contains.
4975 .sp
4976 See \fB\-\-list\-options\fP for defaults and value range.
4977 .TP
4978 .B \fB\-\-demuxer\-seekable\-cache=<yes|no|auto>\fP
4979 This controls whether seeking can use the demuxer cache (default: auto). If
4980 enabled, short seek offsets will not trigger a low level demuxer seek
4981 (which means for example that slow network round trips or FFmpeg seek bugs
4982 can be avoided). If a seek cannot happen within the cached range, a low
4983 level seek will be triggered. Seeking outside of the cache will start a new
4984 cached range, but can discard the old cache range if the demuxer exhibits
4985 certain unsupported behavior.
4986 .sp
4987 Keep in mind that some events can flush the cache or force a low level
4988 seek anyway, such as switching tracks, or attempting to seek before the
4989 start or after the end of the file.
4990 .sp
4991 The special value \fBauto\fP means \fByes\fP in the same situation as
4992 \fB\-\-cache\-secs\fP is used (i.e. when the stream appears to be a network
4993 stream or the stream cache is enabled).
4994 .TP
4995 .B \fB\-\-demuxer\-thread=<yes|no>\fP
4996 Run the demuxer in a separate thread, and let it prefetch a certain amount
4997 of packets (default: yes). Having this enabled leads to smoother playback,
4998 enables features like prefetching, and prevents that stuck network freezes
4999 the player. On the other hand, it can add overhead, or the background
5000 prefetching can hog CPU resources.
5001 .sp
5002 Disabling this option is not recommended. Use it for debugging only.
5003 .TP
5004 .B \fB\-\-demuxer\-termination\-timeout=<seconds>\fP
5005 Number of seconds the player should wait to shutdown the demuxer (default:
5006 0.1). The player will wait up to this much time before it closes the
5007 stream layer forcefully. Forceful closing usually means the network I/O is
5008 given no chance to close its connections gracefully (of course the OS can
5009 still close TCP connections properly), and might result in annoying messages
5010 being logged, and in some cases, confused remote servers.
5011 .sp
5012 This timeout is usually only applied when loading has finished properly. If
5013 loading is aborted by the user, or in some corner cases like removing
5014 external tracks sourced from network during playback, forceful closing is
5015 always used.
5016 .TP
5017 .B \fB\-\-demuxer\-readahead\-secs=<seconds>\fP
5018 If \fB\-\-demuxer\-thread\fP is enabled, this controls how much the demuxer
5019 should buffer ahead in seconds (default: 1). As long as no packet has
5020 a timestamp difference higher than the readahead amount relative to the
5021 last packet returned to the decoder, the demuxer keeps reading.
5022 .sp
5023 Note that the \fB\-\-cache\-secs\fP option will override this value if a cache
5024 is enabled, and the value is larger.
5025 .sp
5026 (This value tends to be fuzzy, because many file formats don\(aqt store linear
5027 timestamps.)
5028 .TP
5029 .B \fB\-\-prefetch\-playlist=<yes|no>\fP
5030 Prefetch next playlist entry while playback of the current entry is ending
5031 (default: no). This merely opens the URL of the next playlist entry as soon
5032 as the current URL is fully read.
5033 .sp
5034 This does \fBnot\fP work with URLs resolved by the \fByoutube\-dl\fP wrapper,
5035 and it won\(aqt.
5036 .sp
5037 This does not affect HLS (\fB\&.m3u8\fP URLs) \- HLS prefetching depends on the
5038 demuxer cache settings and is on by default.
5039 .sp
5040 This can give subtly wrong results if per\-file options are used, or if
5041 options are changed in the time window between prefetching start and next
5042 file played.
5043 .sp
5044 This can occasionally make wrong prefetching decisions. For example, it
5045 can\(aqt predict whether you go backwards in the playlist, and assumes you
5046 won\(aqt edit the playlist.
5047 .sp
5048 Highly experimental.
5049 .TP
5050 .B \fB\-\-force\-seekable=<yes|no>\fP
5051 If the player thinks that the media is not seekable (e.g. playing from a
5052 pipe, or it\(aqs an http stream with a server that doesn\(aqt support range
5053 requests), seeking will be disabled. This option can forcibly enable it.
5054 For seeks within the cache, there\(aqs a good chance of success.
5055 .TP
5056 .B \fB\-\-demuxer\-cache\-wait=<yes|no>\fP
5057 Before starting playback, read data until either the end of the file was
5058 reached, or the demuxer cache has reached maximum capacity. Only once this
5059 is done, playback starts. This intentionally happens before the initial
5060 seek triggered with \fB\-\-start\fP\&. This does not change any runtime behavior
5061 after the initial caching. This option is useless if the file cannot be
5062 cached completely.
5063 .UNINDENT
5064 .SS Input
5065 .INDENT 0.0
5066 .TP
5067 .B \fB\-\-native\-keyrepeat\fP
5068 Use system settings for keyrepeat delay and rate, instead of
5069 \fB\-\-input\-ar\-delay\fP and \fB\-\-input\-ar\-rate\fP\&. (Whether this applies
5070 depends on the VO backend and how it handles keyboard input. Does not
5071 apply to terminal input.)
5072 .TP
5073 .B \fB\-\-input\-ar\-delay\fP
5074 Delay in milliseconds before we start to autorepeat a key (0 to disable).
5075 .TP
5076 .B \fB\-\-input\-ar\-rate\fP
5077 Number of key presses to generate per second on autorepeat.
5078 .TP
5079 .B \fB\-\-input\-conf=<filename>\fP
5080 Specify input configuration file other than the default location in the mpv
5081 configuration directory (usually \fB~/.config/mpv/input.conf\fP).
5082 .TP
5083 .B \fB\-\-no\-input\-default\-bindings\fP
5084 Disable mpv default (built\-in) key bindings.
5085 .TP
5086 .B \fB\-\-input\-cmdlist\fP
5087 Prints all commands that can be bound to keys.
5088 .TP
5089 .B \fB\-\-input\-doubleclick\-time=<milliseconds>\fP
5090 Time in milliseconds to recognize two consecutive button presses as a
5091 double\-click (default: 300).
5092 .TP
5093 .B \fB\-\-input\-keylist\fP
5094 Prints all keys that can be bound to commands.
5095 .TP
5096 .B \fB\-\-input\-key\-fifo\-size=<2\-65000>\fP
5097 Specify the size of the FIFO that buffers key events (default: 7). If it
5098 is too small, some events may be lost. The main disadvantage of setting it
5099 to a very large value is that if you hold down a key triggering some
5100 particularly slow command then the player may be unresponsive while it
5101 processes all the queued commands.
5102 .TP
5103 .B \fB\-\-input\-test\fP
5104 Input test mode. Instead of executing commands on key presses, mpv
5105 will show the keys and the bound commands on the OSD. Has to be used
5106 with a dummy video, and the normal ways to quit the player will not
5107 work (key bindings that normally quit will be shown on OSD only, just
5108 like any other binding). See \fI\%INPUT.CONF\fP\&.
5109 .TP
5110 .B \fB\-\-input\-file=<filename>\fP
5111 Read commands from the given file. Mostly useful with a FIFO. Since
5112 mpv 0.7.0 also understands JSON commands (see \fI\%JSON IPC\fP), but you can\(aqt
5113 get replies or events. Use \fB\-\-input\-ipc\-server\fP for something
5114 bi\-directional. On MS Windows, JSON commands are not available.
5115 .sp
5116 This can also specify a direct file descriptor with \fBfd://N\fP (UNIX only).
5117 In this case, JSON replies will be written if the FD is writable.
5118 .sp
5119 \fBNOTE:\fP
5120 .INDENT 7.0
5121 .INDENT 3.5
5122 When the given file is a FIFO mpv opens both ends, so you can do several
5123 \fIecho "seek 10" > mp_pipe\fP and the pipe will stay valid.
5124 .UNINDENT
5125 .UNINDENT
5126 .TP
5127 .B \fB\-\-input\-terminal\fP, \fB\-\-no\-input\-terminal\fP
5128 \fB\-\-no\-input\-terminal\fP prevents the player from reading key events from
5129 standard input. Useful when reading data from standard input. This is
5130 automatically enabled when \fB\-\fP is found on the command line. There are
5131 situations where you have to set it manually, e.g. if you open
5132 \fB/dev/stdin\fP (or the equivalent on your system), use stdin in a playlist
5133 or intend to read from stdin later on via the loadfile or loadlist input
5134 commands.
5135 .TP
5136 .B \fB\-\-input\-ipc\-server=<filename>\fP
5137 Enable the IPC support and create the listening socket at the given path.
5138 .sp
5139 On Linux and Unix, the given path is a regular filesystem path. On Windows,
5140 named pipes are used, so the path refers to the pipe namespace
5141 (\fB\e\e.\epipe\e<name>\fP). If the \fB\e\e.\epipe\e\fP prefix is missing, mpv will add
5142 it automatically before creating the pipe, so
5143 \fB\-\-input\-ipc\-server=/tmp/mpv\-socket\fP and
5144 \fB\-\-input\-ipc\-server=\e\e.\epipe\etmp\empv\-socket\fP are equivalent for IPC on
5145 Windows.
5146 .sp
5147 See \fI\%JSON IPC\fP for details.
5148 .TP
5149 .B \fB\-\-input\-appleremote=<yes|no>\fP
5150 (OS X only)
5151 Enable/disable Apple Remote support. Enabled by default (except for libmpv).
5152 .TP
5153 .B \fB\-\-input\-gamepad=<yes|no>\fP
5154 Enable/disable SDL2 Gamepad support. Enabled by default (except for libmpv).
5155 .TP
5156 .B \fB\-\-input\-cursor\fP, \fB\-\-no\-input\-cursor\fP
5157 Permit mpv to receive pointer events reported by the video output
5158 driver. Necessary to use the OSC, or to select the buttons in DVD menus.
5159 Support depends on the VO in use.
5160 .TP
5161 .B \fB\-\-input\-media\-keys=<yes|no>\fP
5162 (OS X and Windows only)
5163 Enable/disable media keys support. Enabled by default (except for libmpv).
5164 .TP
5165 .B \fB\-\-input\-right\-alt\-gr\fP, \fB\-\-no\-input\-right\-alt\-gr\fP
5166 (Cocoa and Windows only)
5167 Use the right Alt key as Alt Gr to produce special characters. If disabled,
5168 count the right Alt as an Alt modifier key. Enabled by default.
5169 .TP
5170 .B \fB\-\-input\-vo\-keyboard=<yes|no>\fP
5171 Disable all keyboard input on for VOs which can\(aqt participate in proper
5172 keyboard input dispatching. May not affect all VOs. Generally useful for
5173 embedding only.
5174 .sp
5175 On X11, a sub\-window with input enabled grabs all keyboard input as long
5176 as it is 1. a child of a focused window, and 2. the mouse is inside of
5177 the sub\-window. It can steal away all keyboard input from the
5178 application embedding the mpv window, and on the other hand, the mpv
5179 window will receive no input if the mouse is outside of the mpv window,
5180 even though mpv has focus. Modern toolkits work around this weird X11
5181 behavior, but naively embedding foreign windows breaks it.
5182 .sp
5183 The only way to handle this reasonably is using the XEmbed protocol, which
5184 was designed to solve these problems. GTK provides \fBGtkSocket\fP, which
5185 supports XEmbed. Qt doesn\(aqt seem to provide anything working in newer
5186 versions.
5187 .sp
5188 If the embedder supports XEmbed, input should work with default settings
5189 and with this option disabled. Note that \fBinput\-default\-bindings\fP is
5190 disabled by default in libmpv as well \- it should be enabled if you want
5191 the mpv default key bindings.
5192 .sp
5193 (This option was renamed from \fB\-\-input\-x11\-keyboard\fP\&.)
5194 .UNINDENT
5195 .SS OSD
5196 .INDENT 0.0
5197 .TP
5198 .B \fB\-\-osc\fP, \fB\-\-no\-osc\fP
5199 Whether to load the on\-screen\-controller (default: yes).
5200 .TP
5201 .B \fB\-\-no\-osd\-bar\fP, \fB\-\-osd\-bar\fP
5202 Disable display of the OSD bar.
5203 .sp
5204 You can configure this on a per\-command basis in input.conf using \fBosd\-\fP
5205 prefixes, see \fBInput Command Prefixes\fP\&. If you want to disable the OSD
5206 completely, use \fB\-\-osd\-level=0\fP\&.
5207 .TP
5208 .B \fB\-\-osd\-on\-seek=<no,bar,msg,msg\-bar>\fP
5209 Set what is displayed on the OSD during seeks. The default is \fBbar\fP\&.
5210 .sp
5211 You can configure this on a per\-command basis in input.conf using \fBosd\-\fP
5212 prefixes, see \fBInput Command Prefixes\fP\&.
5213 .TP
5214 .B \fB\-\-osd\-duration=<time>\fP
5215 Set the duration of the OSD messages in ms (default: 1000).
5216 .TP
5217 .B \fB\-\-osd\-font=<name>\fP
5218 Specify font to use for OSD. The default is \fBsans\-serif\fP\&.
5219 .INDENT 7.0
5220 .INDENT 3.5
5221 .IP "Examples"
5222 .INDENT 0.0
5223 .IP \(bu 2
5224 \fB\-\-osd\-font=\(aqBitstream Vera Sans\(aq\fP
5225 .IP \(bu 2
5226 \fB\-\-osd\-font=\(aqComic Sans MS\(aq\fP
5227 .UNINDENT
5228 .UNINDENT
5229 .UNINDENT
5230 .TP
5231 .B \fB\-\-osd\-font\-size=<size>\fP
5232 Specify the OSD font size. See \fB\-\-sub\-font\-size\fP for details.
5233 .sp
5234 Default: 55.
5235 .TP
5236 .B \fB\-\-osd\-msg1=<string>\fP
5237 Show this string as message on OSD with OSD level 1 (visible by default).
5238 The message will be visible by default, and as long as no other message
5239 covers it, and the OSD level isn\(aqt changed (see \fB\-\-osd\-level\fP).
5240 Expands properties; see \fI\%Property Expansion\fP\&.
5241 .TP
5242 .B \fB\-\-osd\-msg2=<string>\fP
5243 Similar to \fB\-\-osd\-msg1\fP, but for OSD level 2. If this is an empty string
5244 (default), then the playback time is shown.
5245 .TP
5246 .B \fB\-\-osd\-msg3=<string>\fP
5247 Similar to \fB\-\-osd\-msg1\fP, but for OSD level 3. If this is an empty string
5248 (default), then the playback time, duration, and some more information is
5249 shown.
5250 .sp
5251 This is used for the \fBshow\-progress\fP command (by default mapped to \fBP\fP),
5252 and when seeking if enabled with \fB\-\-osd\-on\-seek\fP or by \fBosd\-\fP prefixes
5253 in input.conf (see \fBInput Command Prefixes\fP).
5254 .sp
5255 \fB\-\-osd\-status\-msg\fP is a legacy equivalent (but with a minor difference).
5256 .TP
5257 .B \fB\-\-osd\-status\-msg=<string>\fP
5258 Show a custom string during playback instead of the standard status text.
5259 This overrides the status text used for \fB\-\-osd\-level=3\fP, when using the
5260 \fBshow\-progress\fP command (by default mapped to \fBP\fP), and when seeking if
5261 enabled with \fB\-\-osd\-on\-seek\fP or \fBosd\-\fP prefixes in input.conf (see
5262 \fBInput Command Prefixes\fP). Expands properties. See \fI\%Property Expansion\fP\&.
5263 .sp
5264 This option has been replaced with \fB\-\-osd\-msg3\fP\&. The only difference is
5265 that this option implicitly includes \fB${osd\-sym\-cc}\fP\&. This option is
5266 ignored if \fB\-\-osd\-msg3\fP is not empty.
5267 .TP
5268 .B \fB\-\-osd\-playing\-msg=<string>\fP
5269 Show a message on OSD when playback starts. The string is expanded for
5270 properties, e.g. \fB\-\-osd\-playing\-msg=\(aqfile: ${filename}\(aq\fP will show the
5271 message \fBfile:\fP followed by a space and the currently played filename.
5272 .sp
5273 See \fI\%Property Expansion\fP\&.
5274 .TP
5275 .B \fB\-\-osd\-bar\-align\-x=<\-1\-1>\fP
5276 Position of the OSD bar. \-1 is far left, 0 is centered, 1 is far right.
5277 Fractional values (like 0.5) are allowed.
5278 .TP
5279 .B \fB\-\-osd\-bar\-align\-y=<\-1\-1>\fP
5280 Position of the OSD bar. \-1 is top, 0 is centered, 1 is bottom.
5281 Fractional values (like 0.5) are allowed.
5282 .TP
5283 .B \fB\-\-osd\-bar\-w=<1\-100>\fP
5284 Width of the OSD bar, in percentage of the screen width (default: 75).
5285 A value of 50 means the bar is half the screen wide.
5286 .TP
5287 .B \fB\-\-osd\-bar\-h=<0.1\-50>\fP
5288 Height of the OSD bar, in percentage of the screen height (default: 3.125).
5289 .TP
5290 .B \fB\-\-osd\-back\-color=<color>\fP
5291 See \fB\-\-osd\-color\fP\&. Color used for OSD text background.
5292 .TP
5293 .B \fB\-\-osd\-blur=<0..20.0>\fP
5294 Gaussian blur factor. 0 means no blur applied (default).
5295 .TP
5296 .B \fB\-\-osd\-bold=<yes|no>\fP
5297 Format text on bold.
5298 .TP
5299 .B \fB\-\-osd\-italic=<yes|no>\fP
5300 Format text on italic.
5301 .TP
5302 .B \fB\-\-osd\-border\-color=<color>\fP
5303 See \fB\-\-osd\-color\fP\&. Color used for the OSD font border.
5304 .sp
5305 \fBNOTE:\fP
5306 .INDENT 7.0
5307 .INDENT 3.5
5308 ignored when \fB\-\-osd\-back\-color\fP is
5309 specified (or more exactly: when that option is not set to completely
5310 transparent).
5311 .UNINDENT
5312 .UNINDENT
5313 .TP
5314 .B \fB\-\-osd\-border\-size=<size>\fP
5315 Size of the OSD font border in scaled pixels (see \fB\-\-sub\-font\-size\fP
5316 for details). A value of 0 disables borders.
5317 .sp
5318 Default: 3.
5319 .TP
5320 .B \fB\-\-osd\-color=<color>\fP
5321 Specify the color used for OSD.
5322 See \fB\-\-sub\-color\fP for details.
5323 .TP
5324 .B \fB\-\-osd\-fractions\fP
5325 Show OSD times with fractions of seconds (in millisecond precision). Useful
5326 to see the exact timestamp of a video frame.
5327 .TP
5328 .B \fB\-\-osd\-level=<0\-3>\fP
5329 Specifies which mode the OSD should start in.
5330 .INDENT 7.0
5331 .TP
5332 .B 0
5333 OSD completely disabled (subtitles only)
5334 .TP
5335 .B 1
5336 enabled (shows up only on user interaction)
5337 .TP
5338 .B 2
5339 enabled + current time visible by default
5340 .TP
5341 .B 3
5342 enabled + \fB\-\-osd\-status\-msg\fP (current time and status by default)
5343 .UNINDENT
5344 .TP
5345 .B \fB\-\-osd\-margin\-x=<size>\fP
5346 Left and right screen margin for the OSD in scaled pixels (see
5347 \fB\-\-sub\-font\-size\fP for details).
5348 .sp
5349 This option specifies the distance of the OSD to the left, as well as at
5350 which distance from the right border long OSD text will be broken.
5351 .sp
5352 Default: 25.
5353 .TP
5354 .B \fB\-\-osd\-margin\-y=<size>\fP
5355 Top and bottom screen margin for the OSD in scaled pixels (see
5356 \fB\-\-sub\-font\-size\fP for details).
5357 .sp
5358 This option specifies the vertical margins of the OSD.
5359 .sp
5360 Default: 22.
5361 .TP
5362 .B \fB\-\-osd\-align\-x=<left|center|right>\fP
5363 Control to which corner of the screen OSD should be
5364 aligned to (default: \fBleft\fP).
5365 .TP
5366 .B \fB\-\-osd\-align\-y=<top|center|bottom>\fP
5367 Vertical position (default: \fBtop\fP).
5368 Details see \fB\-\-osd\-align\-x\fP\&.
5369 .TP
5370 .B \fB\-\-osd\-scale=<factor>\fP
5371 OSD font size multiplier, multiplied with \fB\-\-osd\-font\-size\fP value.
5372 .TP
5373 .B \fB\-\-osd\-scale\-by\-window=<yes|no>\fP
5374 Whether to scale the OSD with the window size (default: yes). If this is
5375 disabled, \fB\-\-osd\-font\-size\fP and other OSD options that use scaled pixels
5376 are always in actual pixels. The effect is that changing the window size
5377 won\(aqt change the OSD font size.
5378 .TP
5379 .B \fB\-\-osd\-shadow\-color=<color>\fP
5380 See \fB\-\-sub\-color\fP\&. Color used for OSD shadow.
5381 .TP
5382 .B \fB\-\-osd\-shadow\-offset=<size>\fP
5383 Displacement of the OSD shadow in scaled pixels (see
5384 \fB\-\-sub\-font\-size\fP for details). A value of 0 disables shadows.
5385 .sp
5386 Default: 0.
5387 .TP
5388 .B \fB\-\-osd\-spacing=<size>\fP
5389 Horizontal OSD/sub font spacing in scaled pixels (see \fB\-\-sub\-font\-size\fP
5390 for details). This value is added to the normal letter spacing. Negative
5391 values are allowed.
5392 .sp
5393 Default: 0.
5394 .TP
5395 .B \fB\-\-video\-osd=<yes|no>\fP
5396 Enabled OSD rendering on the video window (default: yes). This can be used
5397 in situations where terminal OSD is preferred. If you just want to disable
5398 all OSD rendering, use \fB\-\-osd\-level=0\fP\&.
5399 .sp
5400 It does not affect subtitles or overlays created by scripts (in particular,
5401 the OSC needs to be disabled with \fB\-\-no\-osc\fP).
5402 .sp
5403 This option is somewhat experimental and could be replaced by another
5404 mechanism in the future.
5405 .TP
5406 .B \fB\-\-osd\-font\-provider=<...>\fP
5407 See \fB\-\-sub\-font\-provider\fP for details and accepted values. Note that
5408 unlike subtitles, OSD never uses embedded fonts from media files.
5409 .UNINDENT
5410 .SS Screenshot
5411 .INDENT 0.0
5412 .TP
5413 .B \fB\-\-screenshot\-format=<type>\fP
5414 Set the image file type used for saving screenshots.
5415 .sp
5416 Available choices:
5417 .INDENT 7.0
5418 .TP
5419 .B png
5420 PNG
5421 .TP
5422 .B jpg
5423 JPEG (default)
5424 .TP
5425 .B jpeg
5426 JPEG (alias for jpg)
5427 .TP
5428 .B webp
5429 WebP
5430 .UNINDENT
5431 .TP
5432 .B \fB\-\-screenshot\-tag\-colorspace=<yes|no>\fP
5433 Tag screenshots with the appropriate colorspace.
5434 .sp
5435 Note that not all formats are supported.
5436 .sp
5437 Default: \fBno\fP\&.
5438 .TP
5439 .B \fB\-\-screenshot\-high\-bit\-depth=<yes|no>\fP
5440 If possible, write screenshots with a bit depth similar to the source
5441 video (default: yes). This is interesting in particular for PNG, as this
5442 sometimes triggers writing 16 bit PNGs with huge file sizes. This will also
5443 include an unused alpha channel in the resulting files if 16 bit is used.
5444 .TP
5445 .B \fB\-\-screenshot\-template=<template>\fP
5446 Specify the filename template used to save screenshots. The template
5447 specifies the filename without file extension, and can contain format
5448 specifiers, which will be substituted when taking a screenshot.
5449 By default, the template is \fBmpv\-shot%n\fP, which results in filenames like
5450 \fBmpv\-shot0012.png\fP for example.
5451 .sp
5452 The template can start with a relative or absolute path, in order to
5453 specify a directory location where screenshots should be saved.
5454 .sp
5455 If the final screenshot filename points to an already existing file, the
5456 file will not be overwritten. The screenshot will either not be saved, or if
5457 the template contains \fB%n\fP, saved using different, newly generated
5458 filename.
5459 .sp
5460 Allowed format specifiers:
5461 .INDENT 7.0
5462 .TP
5463 .B \fB%[#][0X]n\fP
5464 A sequence number, padded with zeros to length X (default: 04). E.g.
5465 passing the format \fB%04n\fP will yield \fB0012\fP on the 12th screenshot.
5466 The number is incremented every time a screenshot is taken or if the
5467 file already exists. The length \fBX\fP must be in the range 0\-9. With
5468 the optional # sign, mpv will use the lowest available number. For
5469 example, if you take three screenshots\-\-0001, 0002, 0003\-\-and delete
5470 the first two, the next two screenshots will not be 0004 and 0005, but
5471 0001 and 0002 again.
5472 .TP
5473 .B \fB%f\fP
5474 Filename of the currently played video.
5475 .TP
5476 .B \fB%F\fP
5477 Same as \fB%f\fP, but strip the file extension, including the dot.
5478 .TP
5479 .B \fB%x\fP
5480 Directory path of the currently played video. If the video is not on
5481 the filesystem (but e.g. \fBhttp://\fP), this expand to an empty string.
5482 .TP
5483 .B \fB%X{fallback}\fP
5484 Same as \fB%x\fP, but if the video file is not on the filesystem, return
5485 the fallback string inside the \fB{...}\fP\&.
5486 .TP
5487 .B \fB%p\fP
5488 Current playback time, in the same format as used in the OSD. The
5489 result is a string of the form "HH:MM:SS". For example, if the video is
5490 at the time position 5 minutes and 34 seconds, \fB%p\fP will be replaced
5491 with "00:05:34".
5492 .TP
5493 .B \fB%P\fP
5494 Similar to \fB%p\fP, but extended with the playback time in milliseconds.
5495 It is formatted as "HH:MM:SS.mmm", with "mmm" being the millisecond
5496 part of the playback time.
5497 .sp
5498 \fBNOTE:\fP
5499 .INDENT 7.0
5500 .INDENT 3.5
5501 This is a simple way for getting unique per\-frame timestamps. (Frame
5502 numbers would be more intuitive, but are not easily implementable
5503 because container formats usually use time stamps for identifying
5504 frames.)
5505 .UNINDENT
5506 .UNINDENT
5507 .TP
5508 .B \fB%wX\fP
5509 Specify the current playback time using the format string \fBX\fP\&.
5510 \fB%p\fP is like \fB%wH:%wM:%wS\fP, and \fB%P\fP is like \fB%wH:%wM:%wS.%wT\fP\&.
5511 .INDENT 7.0
5512 .TP
5513 .B Valid format specifiers:
5514 .INDENT 7.0
5515 .TP
5516 .B \fB%wH\fP
5517 hour (padded with 0 to two digits)
5518 .TP
5519 .B \fB%wh\fP
5520 hour (not padded)
5521 .TP
5522 .B \fB%wM\fP
5523 minutes (00\-59)
5524 .TP
5525 .B \fB%wm\fP
5526 total minutes (includes hours, unlike \fB%wM\fP)
5527 .TP
5528 .B \fB%wS\fP
5529 seconds (00\-59)
5530 .TP
5531 .B \fB%ws\fP
5532 total seconds (includes hours and minutes)
5533 .TP
5534 .B \fB%wf\fP
5535 like \fB%ws\fP, but as float
5536 .TP
5537 .B \fB%wT\fP
5538 milliseconds (000\-999)
5539 .UNINDENT
5540 .UNINDENT
5541 .TP
5542 .B \fB%tX\fP
5543 Specify the current local date/time using the format \fBX\fP\&. This format
5544 specifier uses the UNIX \fBstrftime()\fP function internally, and inserts
5545 the result of passing "%X" to \fBstrftime\fP\&. For example, \fB%tm\fP will
5546 insert the number of the current month as number. You have to use
5547 multiple \fB%tX\fP specifiers to build a full date/time string.
5548 .TP
5549 .B \fB%{prop[:fallback text]}\fP
5550 Insert the value of the input property \(aqprop\(aq. E.g. \fB%{filename}\fP is
5551 the same as \fB%f\fP\&. If the property does not exist or is not available,
5552 an error text is inserted, unless a fallback is specified.
5553 .TP
5554 .B \fB%%\fP
5555 Replaced with the \fB%\fP character itself.
5556 .UNINDENT
5557 .TP
5558 .B \fB\-\-screenshot\-directory=<path>\fP
5559 Store screenshots in this directory. This path is joined with the filename
5560 generated by \fB\-\-screenshot\-template\fP\&. If the template filename is already
5561 absolute, the directory is ignored.
5562 .sp
5563 If the directory does not exist, it is created on the first screenshot. If
5564 it is not a directory, an error is generated when trying to write a
5565 screenshot.
5566 .sp
5567 This option is not set by default, and thus will write screenshots to the
5568 directory from which mpv was started. In pseudo\-gui mode
5569 (see \fI\%PSEUDO GUI MODE\fP), this is set to the desktop.
5570 .TP
5571 .B \fB\-\-screenshot\-jpeg\-quality=<0\-100>\fP
5572 Set the JPEG quality level. Higher means better quality. The default is 90.
5573 .TP
5574 .B \fB\-\-screenshot\-jpeg\-source\-chroma=<yes|no>\fP
5575 Write JPEG files with the same chroma subsampling as the video
5576 (default: yes). If disabled, the libjpeg default is used.
5577 .TP
5578 .B \fB\-\-screenshot\-png\-compression=<0\-9>\fP
5579 Set the PNG compression level. Higher means better compression. This will
5580 affect the file size of the written screenshot file and the time it takes
5581 to write a screenshot. Too high compression might occupy enough CPU time to
5582 interrupt playback. The default is 7.
5583 .TP
5584 .B \fB\-\-screenshot\-png\-filter=<0\-5>\fP
5585 Set the filter applied prior to PNG compression. 0 is none, 1 is "sub", 2 is
5586 "up", 3 is "average", 4 is "Paeth", and 5 is "mixed". This affects the level
5587 of compression that can be achieved. For most images, "mixed" achieves the
5588 best compression ratio, hence it is the default.
5589 .TP
5590 .B \fB\-\-screenshot\-webp\-lossless=<yes|no>\fP
5591 Write lossless WebP files. \fB\-\-screenshot\-webp\-quality\fP is ignored if this
5592 is set. The default is no.
5593 .TP
5594 .B \fB\-\-screenshot\-webp\-quality=<0\-100>\fP
5595 Set the WebP quality level. Higher means better quality. The default is 75.
5596 .TP
5597 .B \fB\-\-screenshot\-webp\-compression=<0\-6>\fP
5598 Set the WebP compression level. Higher means better compression, but takes
5599 more CPU time. Note that this also affects the screenshot quality when used
5600 with lossy WebP files. The default is 4.
5601 .UNINDENT
5602 .SS Software Scaler
5603 .INDENT 0.0
5604 .TP
5605 .B \fB\-\-sws\-scaler=<name>\fP
5606 Specify the software scaler algorithm to be used with \fB\-\-vf=scale\fP\&. This
5607 also affects video output drivers which lack hardware acceleration,
5608 e.g. \fBx11\fP\&. See also \fB\-\-vf=scale\fP\&.
5609 .sp
5610 To get a list of available scalers, run \fB\-\-sws\-scaler=help\fP\&.
5611 .sp
5612 Default: \fBbicubic\fP\&.
5613 .TP
5614 .B \fB\-\-sws\-lgb=<0\-100>\fP
5615 Software scaler Gaussian blur filter (luma). See \fB\-\-sws\-scaler\fP\&.
5616 .TP
5617 .B \fB\-\-sws\-cgb=<0\-100>\fP
5618 Software scaler Gaussian blur filter (chroma). See \fB\-\-sws\-scaler\fP\&.
5619 .TP
5620 .B \fB\-\-sws\-ls=<\-100\-100>\fP
5621 Software scaler sharpen filter (luma). See \fB\-\-sws\-scaler\fP\&.
5622 .TP
5623 .B \fB\-\-sws\-cs=<\-100\-100>\fP
5624 Software scaler sharpen filter (chroma). See \fB\-\-sws\-scaler\fP\&.
5625 .TP
5626 .B \fB\-\-sws\-chs=<h>\fP
5627 Software scaler chroma horizontal shifting. See \fB\-\-sws\-scaler\fP\&.
5628 .TP
5629 .B \fB\-\-sws\-cvs=<v>\fP
5630 Software scaler chroma vertical shifting. See \fB\-\-sws\-scaler\fP\&.
5631 .TP
5632 .B \fB\-\-sws\-allow\-zimg=<yes|no>\fP
5633 Allow using zimg (if the component using the internal swscale wrapper
5634 explicitly allows so). In this case, zimg \fImay\fP be used, if the internal
5635 zimg wrapper supports the input and output formats. It will silently
5636 fall back to libswscale if one of these conditions does not apply.
5637 .sp
5638 If zimg is used, the other \fB\-\-sws\-\fP options are ignored, and the
5639 \fB\-\-zimg\-\fP options are used instead.
5640 .sp
5641 If the internal component using the swscale wrapper hooks up logging
5642 correctly, a verbose priority log message will indicate whether zimg is
5643 being used.
5644 .sp
5645 Currently, barely anything uses this.
5646 .TP
5647 .B \fB\-\-zimg\-\-scaler=<point|bilinear|bicubic|spline16|lanczos>\fP
5648 Zimg luma scaler to use (default: bilinear).
5649 .TP
5650 .B \fB\-\-zimg\-fast=<yes|no>\fP
5651 Allow optimizations that help with performance, but reduce quality (default:
5652 yes). Currently, this may simplify gamma conversion operations.
5653 .UNINDENT
5654 .SS Audio Resampler
5655 .sp
5656 This controls the default options of any resampling done by mpv (but not within
5657 libavfilter, within the system audio API resampler, or any other places).
5658 .sp
5659 It also sets the defaults for the \fBlavrresample\fP audio filter.
5660 .INDENT 0.0
5661 .TP
5662 .B \fB\-\-audio\-resample\-filter\-size=<length>\fP
5663 Length of the filter with respect to the lower sampling rate. (default:
5664 16)
5665 .TP
5666 .B \fB\-\-audio\-resample\-phase\-shift=<count>\fP
5667 Log2 of the number of polyphase entries. (..., 10\->1024, 11\->2048,
5668 12\->4096, ...) (default: 10\->1024)
5669 .TP
5670 .B \fB\-\-audio\-resample\-cutoff=<cutoff>\fP
5671 Cutoff frequency (0.0\-1.0), default set depending upon filter length.
5672 .TP
5673 .B \fB\-\-audio\-resample\-linear=<yes|no>\fP
5674 If set then filters will be linearly interpolated between polyphase
5675 entries. (default: no)
5676 .TP
5677 .B \fB\-\-audio\-normalize\-downmix=<yes|no>\fP
5678 Enable/disable normalization if surround audio is downmixed to stereo
5679 (default: no). If this is disabled, downmix can cause clipping. If it\(aqs
5680 enabled, the output might be too quiet. It depends on the source audio.
5681 .sp
5682 Technically, this changes the \fBnormalize\fP suboption of the
5683 \fBlavrresample\fP audio filter, which performs the downmixing.
5684 .sp
5685 If downmix happens outside of mpv for some reason, or in the decoder
5686 (decoder downmixing), or in the audio output (system mixer), this has no
5687 effect.
5688 .TP
5689 .B \fB\-\-audio\-resample\-max\-output\-size=<length>\fP
5690 Limit maximum size of audio frames filtered at once, in ms (default: 40).
5691 The output size size is limited in order to make resample speed changes
5692 react faster. This is necessary especially if decoders or filters output
5693 very large frame sizes (like some lossless codecs or some DRC filters).
5694 This option does not affect the resampling algorithm in any way.
5695 .sp
5696 For testing/debugging only. Can be removed or changed any time.
5697 .TP
5698 .B \fB\-\-audio\-swresample\-o=<string>\fP
5699 Set AVOptions on the SwrContext or AVAudioResampleContext. These should
5700 be documented by FFmpeg or Libav.
5701 .UNINDENT
5702 .SS Terminal
5703 .INDENT 0.0
5704 .TP
5705 .B \fB\-\-quiet\fP
5706 Make console output less verbose; in particular, prevents the status line
5707 (i.e. AV: 3.4 (00:00:03.37) / 5320.6 ...) from being displayed.
5708 Particularly useful on slow terminals or broken ones which do not properly
5709 handle carriage return (i.e. \fB\er\fP).
5710 .sp
5711 See also: \fB\-\-really\-quiet\fP and \fB\-\-msg\-level\fP\&.
5712 .TP
5713 .B \fB\-\-really\-quiet\fP
5714 Display even less output and status messages than with \fB\-\-quiet\fP\&.
5715 .TP
5716 .B \fB\-\-no\-terminal\fP, \fB\-\-terminal\fP
5717 Disable any use of the terminal and stdin/stdout/stderr. This completely
5718 silences any message output.
5719 .sp
5720 Unlike \fB\-\-really\-quiet\fP, this disables input and terminal initialization
5721 as well.
5722 .TP
5723 .B \fB\-\-no\-msg\-color\fP
5724 Disable colorful console output on terminals.
5725 .TP
5726 .B \fB\-\-msg\-level=<module1=level1,module2=level2,...>\fP
5727 Control verbosity directly for each module. The \fBall\fP module changes the
5728 verbosity of all the modules. The verbosity changes from this option are
5729 applied in order from left to right, and each item can override a previous
5730 one.
5731 .sp
5732 Run mpv with \fB\-\-msg\-level=all=trace\fP to see all messages mpv outputs. You
5733 can use the module names printed in the output (prefixed to each line in
5734 \fB[...]\fP) to limit the output to interesting modules.
5735 .sp
5736 This also affects \fB\-\-log\-file\fP, and in certain cases libmpv API logging.
5737 .sp
5738 \fBNOTE:\fP
5739 .INDENT 7.0
5740 .INDENT 3.5
5741 Some messages are printed before the command line is parsed and are
5742 therefore not affected by \fB\-\-msg\-level\fP\&. To control these messages,
5743 you have to use the \fBMPV_VERBOSE\fP environment variable; see
5744 \fI\%ENVIRONMENT VARIABLES\fP for details.
5745 .UNINDENT
5746 .UNINDENT
5747 .sp
5748 Available levels:
5749 .INDENT 7.0
5750 .INDENT 3.5
5751 .INDENT 0.0
5752 .TP
5753 .B no
5754 complete silence
5755 .TP
5756 .B fatal
5757 fatal messages only
5758 .TP
5759 .B error
5760 error messages
5761 .TP
5762 .B warn
5763 warning messages
5764 .TP
5765 .B info
5766 informational messages
5767 .TP
5768 .B status
5769 status messages (default)
5770 .TP
5771 .B v
5772 verbose messages
5773 .TP
5774 .B debug
5775 debug messages
5776 .TP
5777 .B trace
5778 very noisy debug messages
5779 .UNINDENT
5780 .UNINDENT
5781 .UNINDENT
5782 .INDENT 7.0
5783 .INDENT 3.5
5784 .IP "Example"
5785 .INDENT 0.0
5786 .INDENT 3.5
5787 .sp
5788 .nf
5789 .ft C
5790 mpv \-\-msg\-level=ao/sndio=no
5791 .ft P
5792 .fi
5793 .UNINDENT
5794 .UNINDENT
5795 .sp
5796 Completely silences the output of ao_sndio, which uses the log
5797 prefix \fB[ao/sndio]\fP\&.
5798 .INDENT 0.0
5799 .INDENT 3.5
5800 .sp
5801 .nf
5802 .ft C
5803 mpv \-\-msg\-level=all=warn,ao/alsa=error
5804 .ft P
5805 .fi
5806 .UNINDENT
5807 .UNINDENT
5808 .sp
5809 Only show warnings or worse, and let the ao_alsa output show errors
5810 only.
5811 .UNINDENT
5812 .UNINDENT
5813 .TP
5814 .B \fB\-\-term\-osd=<auto|no|force>\fP
5815 Control whether OSD messages are shown on the console when no video output
5816 is available (default: auto).
5817 .INDENT 7.0
5818 .TP
5819 .B auto
5820 use terminal OSD if no video output active
5821 .TP
5822 .B no
5823 disable terminal OSD
5824 .TP
5825 .B force
5826 use terminal OSD even if video output active
5827 .UNINDENT
5828 .sp
5829 The \fBauto\fP mode also enables terminal OSD if \fB\-\-video\-osd=no\fP was set.
5830 .TP
5831 .B \fB\-\-term\-osd\-bar\fP, \fB\-\-no\-term\-osd\-bar\fP
5832 Enable printing a progress bar under the status line on the terminal.
5833 (Disabled by default.)
5834 .TP
5835 .B \fB\-\-term\-osd\-bar\-chars=<string>\fP
5836 Customize the \fB\-\-term\-osd\-bar\fP feature. The string is expected to
5837 consist of 5 characters (start, left space, position indicator,
5838 right space, end). You can use Unicode characters, but note that double\-
5839 width characters will not be treated correctly.
5840 .sp
5841 Default: \fB[\-+\-]\fP\&.
5842 .TP
5843 .B \fB\-\-term\-playing\-msg=<string>\fP
5844 Print out a string after starting playback. The string is expanded for
5845 properties, e.g. \fB\-\-term\-playing\-msg=\(aqfile: ${filename}\(aq\fP will print the string
5846 \fBfile:\fP followed by a space and the currently played filename.
5847 .sp
5848 See \fI\%Property Expansion\fP\&.
5849 .TP
5850 .B \fB\-\-term\-status\-msg=<string>\fP
5851 Print out a custom string during playback instead of the standard status
5852 line. Expands properties. See \fI\%Property Expansion\fP\&.
5853 .TP
5854 .B \fB\-\-msg\-module\fP
5855 Prepend module name to each console message.
5856 .TP
5857 .B \fB\-\-msg\-time\fP
5858 Prepend timing information to each console message.
5859 .UNINDENT
5860 .SS Cache
5861 .INDENT 0.0
5862 .TP
5863 .B \fB\-\-cache=<yes|no|auto>\fP
5864 Decide whether to use network cache settings (default: auto).
5865 .sp
5866 If enabled, use up to \fB\-\-cache\-secs\fP for the cache size (but still limited
5867 to \fB\-\-demuxer\-max\-bytes\fP). \fB\-\-demuxer\-seekable\-cache=auto\fP behaves as if
5868 it was set to \fByes\fP\&. If disabled, \fB\-\-cache\-pause\fP and related are
5869 implicitly disabled.
5870 .sp
5871 The \fBauto\fP choice enables this depending on whether the stream is thought
5872 to involve network accesses or other slow media (this is an imperfect
5873 heuristic).
5874 .sp
5875 Before mpv 0.30.0, this used to accept a number, which specified the size
5876 of the cache in kilobytes. Use e.g. \fB\-\-cache \-\-demuxer\-max\-bytes=123k\fP
5877 instead.
5878 .TP
5879 .B \fB\-\-no\-cache\fP
5880 Turn off input stream caching. See \fB\-\-cache\fP\&.
5881 .TP
5882 .B \fB\-\-cache\-secs=<seconds>\fP
5883 How many seconds of audio/video to prefetch if the cache is active. This
5884 overrides the \fB\-\-demuxer\-readahead\-secs\fP option if and only if the cache
5885 is enabled and the value is larger. The default value is set to something
5886 very high, so the actually achieved readahead will usually be limited by
5887 the value of the \fB\-\-demuxer\-max\-bytes\fP option. Setting this option is
5888 usually only useful for limiting readahead.
5889 .TP
5890 .B \fB\-\-cache\-on\-disk=<yes|no>\fP
5891 Write packet data to a temporary file, instead of keeping them in memory.
5892 This makes sense only with \fB\-\-cache\fP\&. If the normal cache is disabled,
5893 this option is ignored.
5894 .sp
5895 You need to set \fB\-\-cache\-dir\fP to use this.
5896 .sp
5897 The cache file is append\-only. Even if the player appears to prune data, the
5898 file space freed by it is not reused. The cache file is deleted when
5899 playback is closed.
5900 .sp
5901 Note that packet metadata is still kept in memory. \fB\-\-demuxer\-max\-bytes\fP
5902 and related options are applied to metadata \fIonly\fP\&. The size of this
5903 metadata varies, but 50 MB per hour of media is typical. The cache
5904 statistics will report this metadats size, instead of the size of the cache
5905 file. If the metadata hits the size limits, the metadata is pruned (but not
5906 the cache file).
5907 .sp
5908 When the media is closed, the cache file is deleted. A cache file is
5909 generally worthless after the media is closed, and it\(aqs hard to retrieve
5910 any media data from it (it\(aqs not supported by design).
5911 .sp
5912 If the option is enabled at runtime, the cache file is created, but old data
5913 will remain in the memory cache. If the option is disabled at runtime, old
5914 data remains in the disk cache, and the cache file is not closed until the
5915 media is closed. If the option is disabled and enabled again, it will
5916 continue to use the cache file that was opened first.
5917 .TP
5918 .B \fB\-\-cache\-dir=<path>\fP
5919 Directory where to create temporary files (default: none).
5920 .sp
5921 Currently, this is used for \fB\-\-cache\-on\-disk\fP only.
5922 .TP
5923 .B \fB\-\-cache\-pause=<yes|no>\fP
5924 Whether the player should automatically pause when the cache runs out of
5925 data and stalls decoding/playback (default: yes). If enabled, it will
5926 pause and unpause once more data is available, aka "buffering".
5927 .TP
5928 .B \fB\-\-cache\-pause\-wait=<seconds>\fP
5929 Number of seconds the packet cache should have buffered before starting
5930 playback again if "buffering" was entered (default: 1). This can be used
5931 to control how long the player rebuffers if \fB\-\-cache\-pause\fP is enabled,
5932 and the demuxer underruns. If the given time is higher than the maximum
5933 set with \fB\-\-cache\-secs\fP or \fB\-\-demuxer\-readahead\-secs\fP, or prefetching
5934 ends before that for some other reason (like file end or maximum configured
5935 cache size reached), playback resumes earlier.
5936 .TP
5937 .B \fB\-\-cache\-pause\-initial=<yes|no>\fP
5938 Enter "buffering" mode before starting playback (default: no). This can be
5939 used to ensure playback starts smoothly, in exchange for waiting some time
5940 to prefetch network data (as controlled by \fB\-\-cache\-pause\-wait\fP). For
5941 example, some common behavior is that playback starts, but network caches
5942 immediately underrun when trying to decode more data as playback progresses.
5943 .sp
5944 Another thing that can happen is that the network prefetching is so CPU
5945 demanding (due to demuxing in the background) that playback drops frames
5946 at first. In these cases, it helps enabling this option, and setting
5947 \fB\-\-cache\-secs\fP and \fB\-\-cache\-pause\-wait\fP to roughly the same value.
5948 .sp
5949 This option also triggers when playback is restarted after seeking.
5950 .TP
5951 .B \fB\-\-cache\-unlink\-files=<immediate|whendone|no>\fP
5952 Whether or when to unlink cache files (default: immediate). This affects
5953 cache files which are inherently temporary, and which make no sense to
5954 remain on disk after the player terminates. This is a debugging option.
5955 .INDENT 7.0
5956 .TP
5957 .B \fBimmediate\fP
5958 Unlink cache file after they were created. The cache files won\(aqt be
5959 visible anymore, even though they\(aqre in use. This ensures they are
5960 guaranteed to be removed from disk when the player terminates, even if
5961 it crashes.
5962 .TP
5963 .B \fBwhendone\fP
5964 Delete cache files after they are closed.
5965 .TP
5966 .B \fBno\fP
5967 Don\(aqt delete cache files. They will consume disk space without having a
5968 use.
5969 .UNINDENT
5970 .sp
5971 Currently, this is used for \fB\-\-cache\-on\-disk\fP only.
5972 .UNINDENT
5973 .SS Network
5974 .INDENT 0.0
5975 .TP
5976 .B \fB\-\-user\-agent=<string>\fP
5977 Use \fB<string>\fP as user agent for HTTP streaming.
5978 .TP
5979 .B \fB\-\-cookies\fP, \fB\-\-no\-cookies\fP
5980 Support cookies when making HTTP requests. Disabled by default.
5981 .TP
5982 .B \fB\-\-cookies\-file=<filename>\fP
5983 Read HTTP cookies from <filename>. The file is assumed to be in Netscape
5984 format.
5985 .TP
5986 .B \fB\-\-http\-header\-fields=<field1,field2>\fP
5987 Set custom HTTP fields when accessing HTTP stream.
5988 .INDENT 7.0
5989 .INDENT 3.5
5990 .IP "Example"
5991 .INDENT 0.0
5992 .INDENT 3.5
5993 .sp
5994 .nf
5995 .ft C
5996 mpv \-\-http\-header\-fields=\(aqField1: value1\(aq,\(aqField2: value2\(aq \e
5997 http://localhost:1234
5998 .ft P
5999 .fi
6000 .UNINDENT
6001 .UNINDENT
6002 .sp
6003 Will generate HTTP request:
6004 .INDENT 0.0
6005 .INDENT 3.5
6006 .sp
6007 .nf
6008 .ft C
6009 GET / HTTP/1.0
6010 Host: localhost:1234
6011 User\-Agent: MPlayer
6012 Icy\-MetaData: 1
6013 Field1: value1
6014 Field2: value2
6015 Connection: close
6016 .ft P
6017 .fi
6018 .UNINDENT
6019 .UNINDENT
6020 .UNINDENT
6021 .UNINDENT
6022 .TP
6023 .B \fB\-\-http\-proxy=<proxy>\fP
6024 URL of the HTTP/HTTPS proxy. If this is set, the \fBhttp_proxy\fP environment
6025 is ignored. The \fBno_proxy\fP environment variable is still respected. This
6026 option is silently ignored if it does not start with \fBhttp://\fP\&. Proxies
6027 are not used for https URLs. Setting this option does not try to make the
6028 ytdl script use the proxy.
6029 .TP
6030 .B \fB\-\-tls\-ca\-file=<filename>\fP
6031 Certificate authority database file for use with TLS. (Silently fails with
6032 older FFmpeg or Libav versions.)
6033 .TP
6034 .B \fB\-\-tls\-verify\fP
6035 Verify peer certificates when using TLS (e.g. with \fBhttps://...\fP).
6036 (Silently fails with older FFmpeg or Libav versions.)
6037 .TP
6038 .B \fB\-\-tls\-cert\-file\fP
6039 A file containing a certificate to use in the handshake with the
6040 peer.
6041 .TP
6042 .B \fB\-\-tls\-key\-file\fP
6043 A file containing the private key for the certificate.
6044 .TP
6045 .B \fB\-\-referrer=<string>\fP
6046 Specify a referrer path or URL for HTTP requests.
6047 .TP
6048 .B \fB\-\-network\-timeout=<seconds>\fP
6049 Specify the network timeout in seconds. This affects at least HTTP. The
6050 special value 0 (default) uses the FFmpeg/Libav defaults. If a protocol
6051 is used which does not support timeouts, this option is silently ignored.
6052 .sp
6053 \fBWARNING:\fP
6054 .INDENT 7.0
6055 .INDENT 3.5
6056 This breaks the RTSP protocol, because of inconsistent FFmpeg API
6057 regarding its internal timeout option. Not only does the RTSP timeout
6058 option accept different units (seconds instead of microseconds, causing
6059 mpv to pass it huge values), it will also overflow FFmpeg internal
6060 calculations. The worst is that merely setting the option will put RTSP
6061 into listening mode, which breaks any client uses. Do not use this
6062 option with RTSP URLs.
6063 .UNINDENT
6064 .UNINDENT
6065 .TP
6066 .B \fB\-\-rtsp\-transport=<lavf|udp|tcp|http>\fP
6067 Select RTSP transport method (default: tcp). This selects the underlying
6068 network transport when playing \fBrtsp://...\fP URLs. The value \fBlavf\fP
6069 leaves the decision to libavformat.
6070 .TP
6071 .B \fB\-\-hls\-bitrate=<no|min|max|<rate>>\fP
6072 If HLS streams are played, this option controls what streams are selected
6073 by default. The option allows the following parameters:
6074 .INDENT 7.0
6075 .TP
6076 .B no
6077 Don\(aqt do anything special. Typically, this will simply pick the
6078 first audio/video streams it can find.
6079 .TP
6080 .B min
6081 Pick the streams with the lowest bitrate.
6082 .TP
6083 .B max
6084 Same, but highest bitrate. (Default.)
6085 .UNINDENT
6086 .sp
6087 Additionally, if the option is a number, the stream with the highest rate
6088 equal or below the option value is selected.
6089 .sp
6090 The bitrate as used is sent by the server, and there\(aqs no guarantee it\(aqs
6091 actually meaningful.
6092 .UNINDENT
6093 .SS DVB
6094 .INDENT 0.0
6095 .TP
6096 .B \fB\-\-dvbin\-prog=<string>\fP
6097 This defines the program to tune to. Usually, you may specify this
6098 by using a stream URI like \fB"dvb://ZDF HD"\fP, but you can tune to a
6099 different channel by writing to this property at runtime.
6100 Also see \fBdvbin\-channel\-switch\-offset\fP for more useful channel
6101 switching functionality.
6102 .TP
6103 .B \fB\-\-dvbin\-card=<0\-15>\fP
6104 Specifies using card number 0\-15 (default: 0).
6105 .TP
6106 .B \fB\-\-dvbin\-file=<filename>\fP
6107 Instructs mpv to read the channels list from \fB<filename>\fP\&. The default is
6108 in the mpv configuration directory (usually \fB~/.config/mpv\fP) with the
6109 filename \fBchannels.conf.{sat,ter,cbl,atsc}\fP (based on your card type) or
6110 \fBchannels.conf\fP as a last resort.
6111 For DVB\-S/2 cards, a VDR 1.7.x format channel list is recommended
6112 as it allows tuning to DVB\-S2 channels, enabling subtitles and
6113 decoding the PMT (which largely improves the demuxing).
6114 Classic mplayer format channel lists are still supported (without
6115 these improvements), and for other card types, only limited VDR
6116 format channel list support is implemented (patches welcome).
6117 For channels with dynamic PID switching or incomplete
6118 \fBchannels.conf\fP, \fB\-\-dvbin\-full\-transponder\fP or the magic PID
6119 \fB8192\fP are recommended.
6120 .TP
6121 .B \fB\-\-dvbin\-timeout=<1\-30>\fP
6122 Maximum number of seconds to wait when trying to tune a frequency before
6123 giving up (default: 30).
6124 .TP
6125 .B \fB\-\-dvbin\-full\-transponder=<yes|no>\fP
6126 Apply no filters on program PIDs, only tune to frequency and pass full
6127 transponder to demuxer.
6128 The player frontend selects the streams from the full TS in this case,
6129 so the program which is shown initially may not match the chosen channel.
6130 Switching between the programs is possible by cycling the \fBprogram\fP
6131 property.
6132 This is useful to record multiple programs on a single transponder,
6133 or to work around issues in the \fBchannels.conf\fP\&.
6134 It is also recommended to use this for channels which switch PIDs
6135 on\-the\-fly, e.g. for regional news.
6136 .sp
6137 Default: \fBno\fP
6138 .TP
6139 .B \fB\-\-dvbin\-channel\-switch\-offset=<integer>\fP
6140 This value is not meant for setting via configuration, but used in channel
6141 switching. An \fBinput.conf\fP can \fBcycle\fP this value \fBup\fP and \fBdown\fP
6142 to perform channel switching. This number effectively gives the offset
6143 to the initially tuned to channel in the channel list.
6144 .sp
6145 An example \fBinput.conf\fP could contain:
6146 \fBH cycle dvbin\-channel\-switch\-offset up\fP, \fBK cycle dvbin\-channel\-switch\-offset down\fP
6147 .UNINDENT
6148 .SS ALSA audio output options
6149 .INDENT 0.0
6150 .TP
6151 .B \fB\-\-alsa\-device=<device>\fP
6152 Deprecated, use \fB\-\-audio\-device\fP (requires \fBalsa/\fP prefix).
6153 .TP
6154 .B \fB\-\-alsa\-resample=yes\fP
6155 Enable ALSA resampling plugin. (This is disabled by default, because
6156 some drivers report incorrect audio delay in some cases.)
6157 .TP
6158 .B \fB\-\-alsa\-mixer\-device=<device>\fP
6159 Set the mixer device used with \fBao\-volume\fP (default: \fBdefault\fP).
6160 .TP
6161 .B \fB\-\-alsa\-mixer\-name=<name>\fP
6162 Set the name of the mixer element (default: \fBMaster\fP). This is for
6163 example \fBPCM\fP or \fBMaster\fP\&.
6164 .TP
6165 .B \fB\-\-alsa\-mixer\-index=<number>\fP
6166 Set the index of the mixer channel (default: 0). Consider the output of
6167 "\fBamixer scontrols\fP", then the index is the number that follows the
6168 name of the element.
6169 .TP
6170 .B \fB\-\-alsa\-non\-interleaved\fP
6171 Allow output of non\-interleaved formats (if the audio decoder uses
6172 this format). Currently disabled by default, because some popular
6173 ALSA plugins are utterly broken with non\-interleaved formats.
6174 .TP
6175 .B \fB\-\-alsa\-ignore\-chmap\fP
6176 Don\(aqt read or set the channel map of the ALSA device \- only request the
6177 required number of channels, and then pass the audio as\-is to it. This
6178 option most likely should not be used. It can be useful for debugging,
6179 or for static setups with a specially engineered ALSA configuration (in
6180 this case you should always force the same layout with \fB\-\-audio\-channels\fP,
6181 or it will work only for files which use the layout implicit to your
6182 ALSA device).
6183 .TP
6184 .B \fB\-\-alsa\-buffer\-time=<microseconds>\fP
6185 Set the requested buffer time in microseconds. A value of 0 skips requesting
6186 anything from the ALSA API. This and the \fB\-\-alsa\-periods\fP option uses the
6187 ALSA \fBnear\fP functions to set the requested parameters. If doing so results
6188 in an empty configuration set, setting these parameters is skipped.
6189 .sp
6190 Both options control the buffer size. A low buffer size can lead to higher
6191 CPU usage and audio dropouts, while a high buffer size can lead to higher
6192 latency in volume changes and other filtering.
6193 .TP
6194 .B \fB\-\-alsa\-periods=<number>\fP
6195 Number of periods requested from the ALSA API. See \fB\-\-alsa\-buffer\-time\fP
6196 for further remarks.
6197 .UNINDENT
6198 .SS GPU renderer options
6199 .sp
6200 The following video options are currently all specific to \fB\-\-vo=gpu\fP and
6201 \fB\-\-vo=opengl\-cb\fP only, which are the only VOs that implement them.
6202 .INDENT 0.0
6203 .TP
6204 .B \fB\-\-scale=<filter>\fP
6205 The filter function to use when upscaling video.
6206 .INDENT 7.0
6207 .TP
6208 .B \fBbilinear\fP
6209 Bilinear hardware texture filtering (fastest, very low quality). This
6210 is the default for compatibility reasons.
6211 .TP
6212 .B \fBspline36\fP
6213 Mid quality and speed. This is the default when using \fBgpu\-hq\fP\&.
6214 .TP
6215 .B \fBlanczos\fP
6216 Lanczos scaling. Provides mid quality and speed. Generally worse than
6217 \fBspline36\fP, but it results in a slightly sharper image which is good
6218 for some content types. The number of taps can be controlled with
6219 \fBscale\-radius\fP, but is best left unchanged.
6220 .sp
6221 (This filter is an alias for \fBsinc\fP\-windowed \fBsinc\fP)
6222 .TP
6223 .B \fBewa_lanczos\fP
6224 Elliptic weighted average Lanczos scaling. Also known as Jinc.
6225 Relatively slow, but very good quality. The radius can be controlled
6226 with \fBscale\-radius\fP\&. Increasing the radius makes the filter sharper
6227 but adds more ringing.
6228 .sp
6229 (This filter is an alias for \fBjinc\fP\-windowed \fBjinc\fP)
6230 .TP
6231 .B \fBewa_lanczossharp\fP
6232 A slightly sharpened version of ewa_lanczos, preconfigured to use an
6233 ideal radius and parameter. If your hardware can run it, this is
6234 probably what you should use by default.
6235 .TP
6236 .B \fBmitchell\fP
6237 Mitchell\-Netravali. The \fBB\fP and \fBC\fP parameters can be set with
6238 \fB\-\-scale\-param1\fP and \fB\-\-scale\-param2\fP\&. This filter is very good at
6239 downscaling (see \fB\-\-dscale\fP).
6240 .TP
6241 .B \fBoversample\fP
6242 A version of nearest neighbour that (naively) oversamples pixels, so
6243 that pixels overlapping edges get linearly interpolated instead of
6244 rounded. This essentially removes the small imperfections and judder
6245 artifacts caused by nearest\-neighbour interpolation, in exchange for
6246 adding some blur. This filter is good at temporal interpolation, and
6247 also known as "smoothmotion" (see \fB\-\-tscale\fP).
6248 .TP
6249 .B \fBlinear\fP
6250 A \fB\-\-tscale\fP filter.
6251 .UNINDENT
6252 .sp
6253 There are some more filters, but most are not as useful. For a complete
6254 list, pass \fBhelp\fP as value, e.g.:
6255 .INDENT 7.0
6256 .INDENT 3.5
6257 .sp
6258 .nf
6259 .ft C
6260 mpv \-\-scale=help
6261 .ft P
6262 .fi
6263 .UNINDENT
6264 .UNINDENT
6265 .TP
6266 .B \fB\-\-cscale=<filter>\fP
6267 As \fB\-\-scale\fP, but for interpolating chroma information. If the image is
6268 not subsampled, this option is ignored entirely.
6269 .TP
6270 .B \fB\-\-dscale=<filter>\fP
6271 Like \fB\-\-scale\fP, but apply these filters on downscaling instead. If this
6272 option is unset, the filter implied by \fB\-\-scale\fP will be applied.
6273 .TP
6274 .B \fB\-\-tscale=<filter>\fP
6275 The filter used for interpolating the temporal axis (frames). This is only
6276 used if \fB\-\-interpolation\fP is enabled. The only valid choices for
6277 \fB\-\-tscale\fP are separable convolution filters (use \fB\-\-tscale=help\fP to
6278 get a list). The default is \fBmitchell\fP\&.
6279 .sp
6280 Common \fB\-\-tscale\fP choices include \fBoversample\fP, \fBlinear\fP,
6281 \fBcatmull_rom\fP, \fBmitchell\fP, \fBgaussian\fP, or \fBbicubic\fP\&. These are
6282 listed in increasing order of smoothness/blurriness, with \fBbicubic\fP
6283 being the smoothest/blurriest and \fBoversample\fP being the sharpest/least
6284 smooth.
6285 .TP
6286 .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
6287 Set filter parameters. By default, these are set to the special string
6288 \fBdefault\fP, which maps to a scaler\-specific default value. Ignored if the
6289 filter is not tunable. Currently, this affects the following filter
6290 parameters:
6291 .INDENT 7.0
6292 .TP
6293 .B bcspline
6294 Spline parameters (\fBB\fP and \fBC\fP). Defaults to 0.5 for both.
6295 .TP
6296 .B gaussian
6297 Scale parameter (\fBt\fP). Increasing this makes the result blurrier.
6298 Defaults to 1.
6299 .TP
6300 .B oversample
6301 Minimum distance to an edge before interpolation is used. Setting this
6302 to 0 will always interpolate edges, whereas setting it to 0.5 will
6303 never interpolate, thus behaving as if the regular nearest neighbour
6304 algorithm was used. Defaults to 0.0.
6305 .UNINDENT
6306 .TP
6307 .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
6308 Kernel/window scaling factor (also known as a blur factor). Decreasing this
6309 makes the result sharper, increasing it makes it blurrier (default 0). If
6310 set to 0, the kernel\(aqs preferred blur factor is used. Note that setting
6311 this too low (eg. 0.5) leads to bad results. It\(aqs generally recommended to
6312 stick to values between 0.8 and 1.2.
6313 .TP
6314 .B \fB\-\-scale\-clamp=<0.0\-1.0>\fP, \fB\-\-cscale\-clamp\fP, \fB\-\-dscale\-clamp\fP, \fB\-\-tscale\-clamp\fP
6315 Specifies a weight bias to multiply into negative coefficients. Specifying
6316 \fB\-\-scale\-clamp=1\fP has the effect of removing negative weights completely,
6317 thus effectively clamping the value range to [0\-1]. Values between 0.0 and
6318 1.0 can be specified to apply only a moderate diminishment of negative
6319 weights. This is especially useful for \fB\-\-tscale\fP, where it reduces
6320 excessive ringing artifacts in the temporal domain (which typically
6321 manifest themselves as short flashes or fringes of black, mostly around
6322 moving edges) in exchange for potentially adding more blur. The default for
6323 \fB\-\-tscale\-clamp\fP is 1.0, the others default to 0.0.
6324 .TP
6325 .B \fB\-\-scale\-cutoff=<value>\fP, \fB\-\-cscale\-cutoff=<value>\fP, \fB\-\-dscale\-cutoff=<value>\fP
6326 Cut off the filter kernel prematurely once the value range drops below
6327 this threshold. Doing so allows more aggressive pruning of skippable
6328 coefficients by disregarding parts of the LUT which are effectively zeroed
6329 out by the window function. Only affects polar (EWA) filters. The default
6330 is 0.001 for each, which is perceptually transparent but provides a 10%\-20%
6331 speedup, depending on the exact radius and filter kernel chosen.
6332 .TP
6333 .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
6334 Kernel/window taper factor. Increasing this flattens the filter function.
6335 Value range is 0 to 1. A value of 0 (the default) means no flattening, a
6336 value of 1 makes the filter completely flat (equivalent to a box function).
6337 Values in between mean that some portion will be flat and the actual filter
6338 function will be squeezed into the space in between.
6339 .TP
6340 .B \fB\-\-scale\-radius=<value>\fP, \fB\-\-cscale\-radius=<value>\fP, \fB\-\-dscale\-radius=<value>\fP, \fB\-\-tscale\-radius=<value>\fP
6341 Set radius for tunable filters, must be a float number between 0.5 and
6342 16.0. Defaults to the filter\(aqs preferred radius if not specified. Doesn\(aqt
6343 work for every scaler and VO combination.
6344 .sp
6345 Note that depending on filter implementation details and video scaling
6346 ratio, the radius that actually being used might be different (most likely
6347 being increased a bit).
6348 .TP
6349 .B \fB\-\-scale\-antiring=<value>\fP, \fB\-\-cscale\-antiring=<value>\fP, \fB\-\-dscale\-antiring=<value>\fP, \fB\-\-tscale\-antiring=<value>\fP
6350 Set the antiringing strength. This tries to eliminate ringing, but can
6351 introduce other artifacts in the process. Must be a float number between
6352 0.0 and 1.0. The default value of 0.0 disables antiringing entirely.
6353 .sp
6354 Note that this doesn\(aqt affect the special filters \fBbilinear\fP and
6355 \fBbicubic_fast\fP, nor does it affect any polar (EWA) scalers.
6356 .TP
6357 .B \fB\-\-scale\-window=<window>\fP, \fB\-\-cscale\-window=<window>\fP, \fB\-\-dscale\-window=<window>\fP, \fB\-\-tscale\-window=<window>\fP
6358 (Advanced users only) Choose a custom windowing function for the kernel.
6359 Defaults to the filter\(aqs preferred window if unset. Use
6360 \fB\-\-scale\-window=help\fP to get a list of supported windowing functions.
6361 .TP
6362 .B \fB\-\-scale\-wparam=<window>\fP, \fB\-\-cscale\-wparam=<window>\fP, \fB\-\-cscale\-wparam=<window>\fP, \fB\-\-tscale\-wparam=<window>\fP
6363 (Advanced users only) Configure the parameter for the window function given
6364 by \fB\-\-scale\-window\fP etc. By default, these are set to the special string
6365 \fBdefault\fP, which maps to a window\-specific default value. Ignored if the
6366 window is not tunable. Currently, this affects the following window
6367 parameters:
6368 .INDENT 7.0
6369 .TP
6370 .B kaiser
6371 Window parameter (alpha). Defaults to 6.33.
6372 .TP
6373 .B blackman
6374 Window parameter (alpha). Defaults to 0.16.
6375 .TP
6376 .B gaussian
6377 Scale parameter (t). Increasing this makes the window wider. Defaults
6378 to 1.
6379 .UNINDENT
6380 .TP
6381 .B \fB\-\-scaler\-lut\-size=<4..10>\fP
6382 Set the size of the lookup texture for scaler kernels (default: 6). The
6383 actual size of the texture is \fB2^N\fP for an option value of \fBN\fP\&. So the
6384 lookup texture with the default setting uses 64 samples.
6385 .sp
6386 All weights are linearly interpolated from those samples, so increasing
6387 the size of lookup table might improve the accuracy of scaler.
6388 .TP
6389 .B \fB\-\-scaler\-resizes\-only\fP
6390 Disable the scaler if the video image is not resized. In that case,
6391 \fBbilinear\fP is used instead of whatever is set with \fB\-\-scale\fP\&. Bilinear
6392 will reproduce the source image perfectly if no scaling is performed.
6393 Enabled by default. Note that this option never affects \fB\-\-cscale\fP\&.
6394 .TP
6395 .B \fB\-\-correct\-downscaling\fP
6396 When using convolution based filters, extend the filter size when
6397 downscaling. Increases quality, but reduces performance while downscaling.
6398 .sp
6399 This will perform slightly sub\-optimally for anamorphic video (but still
6400 better than without it) since it will extend the size to match only the
6401 milder of the scale factors between the axes.
6402 .TP
6403 .B \fB\-\-linear\-downscaling\fP
6404 Scale in linear light when downscaling. It should only be used with a
6405 \fB\-\-fbo\-format\fP that has at least 16 bit precision. This option
6406 has no effect on HDR content.
6407 .TP
6408 .B \fB\-\-linear\-upscaling\fP
6409 Scale in linear light when upscaling. Like \fB\-\-linear\-downscaling\fP, it
6410 should only be used with a \fB\-\-fbo\-format\fP that has at least 16 bits
6411 precisions. This is not usually recommended except for testing/specific
6412 purposes. Users are advised to either enable \fB\-\-sigmoid\-upscaling\fP or
6413 keep both options disabled (i.e. scaling in gamma light).
6414 .TP
6415 .B \fB\-\-sigmoid\-upscaling\fP
6416 When upscaling, use a sigmoidal color transform to avoid emphasizing
6417 ringing artifacts. This is incompatible with and replaces
6418 \fB\-\-linear\-upscaling\fP\&. (Note that sigmoidization also requires
6419 linearization, so the \fBLINEAR\fP rendering step fires in both cases)
6420 .TP
6421 .B \fB\-\-sigmoid\-center\fP
6422 The center of the sigmoid curve used for \fB\-\-sigmoid\-upscaling\fP, must be a
6423 float between 0.0 and 1.0. Defaults to 0.75 if not specified.
6424 .TP
6425 .B \fB\-\-sigmoid\-slope\fP
6426 The slope of the sigmoid curve used for \fB\-\-sigmoid\-upscaling\fP, must be a
6427 float between 1.0 and 20.0. Defaults to 6.5 if not specified.
6428 .TP
6429 .B \fB\-\-interpolation\fP
6430 Reduce stuttering caused by mismatches in the video fps and display refresh
6431 rate (also known as judder).
6432 .sp
6433 \fBWARNING:\fP
6434 .INDENT 7.0
6435 .INDENT 3.5
6436 This requires setting the \fB\-\-video\-sync\fP option to one
6437 of the \fBdisplay\-\fP modes, or it will be silently disabled.
6438 This was not required before mpv 0.14.0.
6439 .UNINDENT
6440 .UNINDENT
6441 .sp
6442 This essentially attempts to interpolate the missing frames by convoluting
6443 the video along the temporal axis. The filter used can be controlled using
6444 the \fB\-\-tscale\fP setting.
6445 .TP
6446 .B \fB\-\-interpolation\-threshold=<0..1,\-1>\fP
6447 Threshold below which frame ratio interpolation gets disabled (default:
6448 \fB0.0001\fP). This is calculated as \fBabs(disphz/vfps \- 1) < threshold\fP,
6449 where \fBvfps\fP is the speed\-adjusted video FPS, and \fBdisphz\fP the
6450 display refresh rate. (The speed\-adjusted video FPS is roughly equal to
6451 the normal video FPS, but with slowdown and speedup applied. This matters
6452 if you use \fB\-\-video\-sync=display\-resample\fP to make video run synchronously
6453 to the display FPS, or if you change the \fBspeed\fP property.)
6454 .sp
6455 The default is intended to almost always enable interpolation if the
6456 playback rate is even slightly different from the display refresh rate. But
6457 note that if you use e.g. \fB\-\-video\-sync=display\-vdrop\fP, small deviations
6458 in the rate can disable interpolation and introduce a discontinuity every
6459 other minute.
6460 .sp
6461 Set this to \fB\-1\fP to disable this logic.
6462 .TP
6463 .B \fB\-\-opengl\-pbo\fP
6464 Enable use of PBOs. On some drivers this can be faster, especially if the
6465 source video size is huge (e.g. so called "4K" video). On other drivers it
6466 might be slower or cause latency issues.
6467 .TP
6468 .B \fB\-\-dither\-depth=<N|no|auto>\fP
6469 Set dither target depth to N. Default: no.
6470 .INDENT 7.0
6471 .TP
6472 .B no
6473 Disable any dithering done by mpv.
6474 .TP
6475 .B auto
6476 Automatic selection. If output bit depth cannot be detected, 8 bits per
6477 component are assumed.
6478 .TP
6479 .B 8
6480 Dither to 8 bit output.
6481 .UNINDENT
6482 .sp
6483 Note that the depth of the connected video display device cannot be
6484 detected. Often, LCD panels will do dithering on their own, which conflicts
6485 with this option and leads to ugly output.
6486 .TP
6487 .B \fB\-\-dither\-size\-fruit=<2\-8>\fP
6488 Set the size of the dither matrix (default: 6). The actual size of the
6489 matrix is \fB(2^N) x (2^N)\fP for an option value of \fBN\fP, so a value of 6
6490 gives a size of 64x64. The matrix is generated at startup time, and a large
6491 matrix can take rather long to compute (seconds).
6492 .sp
6493 Used in \fB\-\-dither=fruit\fP mode only.
6494 .TP
6495 .B \fB\-\-dither=<fruit|ordered|error\-diffusion|no>\fP
6496 Select dithering algorithm (default: fruit). (Normally, the
6497 \fB\-\-dither\-depth\fP option controls whether dithering is enabled.)
6498 .sp
6499 The \fBerror\-diffusion\fP option requires compute shader support. It also
6500 requires large amount of shared memory to run, the size of which depends on
6501 both the kernel (see \fB\-\-error\-diffusion\fP option below) and the height of
6502 video window. It will fallback to \fBfruit\fP dithering if there is no enough
6503 shared memory to run the shader.
6504 .TP
6505 .B \fB\-\-temporal\-dither\fP
6506 Enable temporal dithering. (Only active if dithering is enabled in
6507 general.) This changes between 8 different dithering patterns on each frame
6508 by changing the orientation of the tiled dithering matrix. Unfortunately,
6509 this can lead to flicker on LCD displays, since these have a high reaction
6510 time.
6511 .TP
6512 .B \fB\-\-temporal\-dither\-period=<1\-128>\fP
6513 Determines how often the dithering pattern is updated when
6514 \fB\-\-temporal\-dither\fP is in use. 1 (the default) will update on every video
6515 frame, 2 on every other frame, etc.
6516 .TP
6517 .B \fB\-\-error\-diffusion=<kernel>\fP
6518 The error diffusion kernel to use when \fB\-\-dither=error\-diffusion\fP is set.
6519 .INDENT 7.0
6520 .TP
6521 .B \fBsimple\fP
6522 Propagate error to only two adjacent pixels. Fastest but low quality.
6523 .TP
6524 .B \fBsierra\-lite\fP
6525 Fast with reasonable quality. This is the default.
6526 .TP
6527 .B \fBfloyd\-steinberg\fP
6528 Most notable error diffusion kernel.
6529 .TP
6530 .B \fBatkinson\fP
6531 Looks different from other kernels because only fraction of errors will
6532 be propagated during dithering. A typical use case of this kernel is
6533 saving dithered screenshot (in window mode). This kernel produces
6534 slightly smaller file, with still reasonable dithering quality.
6535 .UNINDENT
6536 .sp
6537 There are other kernels (use \fB\-\-error\-diffusion=help\fP to list) but most of
6538 them are much slower and demanding even larger amount of shared memory.
6539 Among these kernels, \fBburkes\fP achieves a good balance between performance
6540 and quality, and probably is the one you want to try first.
6541 .TP
6542 .B \fB\-\-gpu\-debug\fP
6543 Enables GPU debugging. What this means depends on the API type. For OpenGL,
6544 it calls \fBglGetError()\fP, and requests a debug context. For Vulkan, it
6545 enables validation layers.
6546 .TP
6547 .B \fB\-\-opengl\-swapinterval=<n>\fP
6548 Interval in displayed frames between two buffer swaps. 1 is equivalent to
6549 enable VSYNC, 0 to disable VSYNC. Defaults to 1 if not specified.
6550 .sp
6551 Note that this depends on proper OpenGL vsync support. On some platforms
6552 and drivers, this only works reliably when in fullscreen mode. It may also
6553 require driver\-specific hacks if using multiple monitors, to ensure mpv
6554 syncs to the right one. Compositing window managers can also lead to bad
6555 results, as can missing or incorrect display FPS information (see
6556 \fB\-\-display\-fps\fP).
6557 .TP
6558 .B \fB\-\-vulkan\-swap\-mode=<mode>\fP
6559 Controls the presentation mode of the vulkan swapchain. This is similar
6560 to the \fB\-\-opengl\-swapinterval\fP option.
6561 .INDENT 7.0
6562 .TP
6563 .B auto
6564 Use the preferred swapchain mode for the vulkan context. (Default)
6565 .TP
6566 .B fifo
6567 Non\-tearing, vsync blocked. Similar to "VSync on".
6568 .TP
6569 .B fifo\-relaxed
6570 Tearing, vsync blocked. Late frames will tear instead of stuttering.
6571 .TP
6572 .B mailbox
6573 Non\-tearing, not vsync blocked. Similar to "triple buffering".
6574 .TP
6575 .B immediate
6576 Tearing, not vsync blocked. Similar to "VSync off".
6577 .UNINDENT
6578 .TP
6579 .B \fB\-\-vulkan\-queue\-count=<1..8>\fP
6580 Controls the number of VkQueues used for rendering (limited by how many
6581 your device supports). In theory, using more queues could enable some
6582 parallelism between frames (when using a \fB\-\-swapchain\-depth\fP higher than
6583 1), but it can also slow things down on hardware where there\(aqs no true
6584 parallelism between queues. (Default: 1)
6585 .TP
6586 .B \fB\-\-vulkan\-async\-transfer\fP
6587 Enables the use of async transfer queues on supported vulkan devices. Using
6588 them allows transfer operations like texture uploads and blits to happen
6589 concurrently with the actual rendering, thus improving overall throughput
6590 and power consumption. Enabled by default, and should be relatively safe.
6591 .TP
6592 .B \fB\-\-vulkan\-async\-compute\fP
6593 Enables the use of async compute queues on supported vulkan devices. Using
6594 this, in theory, allows out\-of\-order scheduling of compute shaders with
6595 graphics shaders, thus enabling the hardware to do more effective work while
6596 waiting for pipeline bubbles and memory operations. Not beneficial on all
6597 GPUs. It\(aqs worth noting that if async compute is enabled, and the device
6598 supports more compute queues than graphics queues (bound by the restrictions
6599 set by \fB\-\-vulkan\-queue\-count\fP), mpv will internally try and prefer the
6600 use of compute shaders over fragment shaders wherever possible. Not enabled
6601 by default, since it seems to cause issues with some drivers.
6602 .TP
6603 .B \fB\-\-d3d11\-warp=<yes|no|auto>\fP
6604 Use WARP (Windows Advanced Rasterization Platform) with the D3D11 GPU
6605 backend (default: auto). This is a high performance software renderer. By
6606 default, it is only used when the system has no hardware adapters that
6607 support D3D11. While the extended GPU features will work with WARP, they
6608 can be very slow.
6609 .TP
6610 .B \fB\-\-d3d11\-feature\-level=<12_1|12_0|11_1|11_0|10_1|10_0|9_3|9_2|9_1>\fP
6611 Select a specific feature level when using the D3D11 GPU backend. By
6612 default, the highest available feature level is used. This option can be
6613 used to select a lower feature level, which is mainly useful for debugging.
6614 Most extended GPU features will not work at 9_x feature levels.
6615 .TP
6616 .B \fB\-\-d3d11\-flip=<yes|no>\fP
6617 Enable flip\-model presentation, which avoids unnecessarily copying the
6618 backbuffer by sharing surfaces with the DWM (default: yes). This may cause
6619 performance issues with older drivers. If flip\-model presentation is not
6620 supported (for example, on Windows 7 without the platform update), mpv will
6621 automatically fall back to the older bitblt presentation model.
6622 .TP
6623 .B \fB\-\-d3d11\-sync\-interval=<0..4>\fP
6624 Schedule each frame to be presented for this number of VBlank intervals.
6625 (default: 1) Setting to 1 will enable VSync, setting to 0 will disable it.
6626 .TP
6627 .B \fB\-\-d3d11\-adapter=<adapter name|help>\fP
6628 Select a specific D3D11 adapter to utilize for D3D11 rendering.
6629 Will pick the default adapter if unset. Alternatives are listed
6630 when the name "help" is given.
6631 .sp
6632 Checks for matches based on the start of the string, case
6633 insensitive. Thus, if the description of the adapter starts with
6634 the vendor name, that can be utilized as the selection parameter.
6635 .sp
6636 Hardware decoders utilizing the D3D11 rendering abstraction\(aqs helper
6637 functionality to receive a device, such as D3D11VA or DXVA2\(aqs DXGI
6638 mode, will be affected by this choice.
6639 .TP
6640 .B \fB\-\-d3d11\-output\-format=<auto|rgba8|bgra8|rgb10_a2|rgba16f>\fP
6641 Select a specific D3D11 output format to utilize for D3D11 rendering.
6642 "auto" is the default, which will pick either rgba8 or rgb10_a2 depending
6643 on the configured desktop bit depth. rgba16f and bgra8 are left out of
6644 the autodetection logic, and are available for manual testing.
6645 .sp
6646 \fBNOTE:\fP
6647 .INDENT 7.0
6648 .INDENT 3.5
6649 Desktop bit depth querying is only available from an API available
6650 from Windows 10. Thus on older systems it will only automatically
6651 utilize the rgba8 output format.
6652 .UNINDENT
6653 .UNINDENT
6654 .TP
6655 .B \fB\-\-d3d11va\-zero\-copy=<yes|no>\fP
6656 By default, when using hardware decoding with \fB\-\-gpu\-api=d3d11\fP, the
6657 video image will be copied (GPU\-to\-GPU) from the decoder surface to a
6658 shader resource. Set this option to avoid that copy by sampling directly
6659 from the decoder image. This may increase performance and reduce power
6660 usage, but can cause the image to be sampled incorrectly on the bottom and
6661 right edges due to padding, and may invoke driver bugs, since Direct3D 11
6662 technically does not allow sampling from a decoder surface (though most
6663 drivers support it.)
6664 .sp
6665 Currently only relevant for \fB\-\-gpu\-api=d3d11\fP\&.
6666 .TP
6667 .B \fB\-\-wayland\-frame\-wait\-offset=<\-100..3000>\fP
6668 Control the amount of offset (in microseconds) to add to wayland\(aqs frame wait
6669 (default 1000). The wayland context assumes that if frame callback or presentation
6670 feedback isn\(aqt received within a certain amount of time then the video is being
6671 rendered offscreen. The time it waits is equal to how long it takes your monitor
6672 to display a frame (i.e. 1/refresh rate) plus the offset. In general, staying
6673 close to your monitor\(aqs refresh rate is preferred, but with a small offset in
6674 case a frame takes a little long to display.
6675 .TP
6676 .B \fB\-\-wayland\-disable\-vsync=<yes|no>\fP
6677 Disable vsync for the wayland contexts (default: no). Useful for benchmarking
6678 the wayland context when combined with \fBvideo\-sync=display\-desync\fP,
6679 \fB\-\-no\-audio\fP, and \fB\-\-untimed=yes\fP\&. Only works with \fB\-\-gpu\-context=wayland\fP
6680 and \fB\-\-gpu\-context=waylandvk\fP\&.
6681 .TP
6682 .B \fB\-\-spirv\-compiler=<compiler>\fP
6683 Controls which compiler is used to translate GLSL to SPIR\-V. This is
6684 (currently) only relevant for \fB\-\-gpu\-api=vulkan\fP and \fI\-\-gpu\-api=d3d11\fP\&.
6685 The possible choices are currently only:
6686 .INDENT 7.0
6687 .TP
6688 .B auto
6689 Use the first available compiler. (Default)
6690 .TP
6691 .B shaderc
6692 Use libshaderc, which is an API wrapper around glslang. This is
6693 generally the most preferred, if available.
6694 .UNINDENT
6695 .sp
6696 \fBNOTE:\fP
6697 .INDENT 7.0
6698 .INDENT 3.5
6699 This option is deprecated, since there is only one reasonable value.
6700 It may be removed in the future.
6701 .UNINDENT
6702 .UNINDENT
6703 .TP
6704 .B \fB\-\-glsl\-shaders=<file\-list>\fP
6705 Custom GLSL hooks. These are a flexible way to add custom fragment shaders,
6706 which can be injected at almost arbitrary points in the rendering pipeline,
6707 and access all previous intermediate textures. Each use of the option will
6708 add another file to the internal list of shaders (see \fI\%List Options\fP).
6709 .INDENT 7.0
6710 .INDENT 3.5
6711 .IP "Warning"
6712 .sp
6713 The syntax is not stable yet and may change any time.
6714 .UNINDENT
6715 .UNINDENT
6716 .sp
6717 The general syntax of a user shader looks like this:
6718 .INDENT 7.0
6719 .INDENT 3.5
6720 .sp
6721 .nf
6722 .ft C
6723 //!METADATA ARGS...
6724 //!METADATA ARGS...
6725
6726 vec4 hook() {
6727 ...
6728 return something;
6729 }
6730
6731 //!METADATA ARGS...
6732 //!METADATA ARGS...
6733
6734 \&...
6735 .ft P
6736 .fi
6737 .UNINDENT
6738 .UNINDENT
6739 .sp
6740 Each section of metadata, along with the non\-metadata lines after it,
6741 defines a single block. There are currently two types of blocks, HOOKs and
6742 TEXTUREs.
6743 .sp
6744 A \fBTEXTURE\fP block can set the following options:
6745 .INDENT 7.0
6746 .TP
6747 .B TEXTURE <name> (required)
6748 The name of this texture. Hooks can then bind the texture under this
6749 name using BIND. This must be the first option of the texture block.
6750 .TP
6751 .B SIZE <width> [<height>] [<depth>] (required)
6752 The dimensions of the texture. The height and depth are optional. The
6753 type of texture (1D, 2D or 3D) depends on the number of components
6754 specified.
6755 .TP
6756 .B FORMAT <name> (required)
6757 The texture format for the samples. Supported texture formats are listed
6758 in debug logging when the \fBgpu\fP VO is initialized (look for
6759 \fBTexture formats:\fP). Usually, this follows OpenGL naming conventions.
6760 For example, \fBrgb16\fP provides 3 channels with normalized 16 bit
6761 components. One oddity are float formats: for example, \fBrgba16f\fP has
6762 16 bit internal precision, but the texture data is provided as 32 bit
6763 floats, and the driver converts the data on texture upload.
6764 .sp
6765 Although format names follow a common naming convention, not all of them
6766 are available on all hardware, drivers, GL versions, and so on.
6767 .TP
6768 .B FILTER <LINEAR|NEAREST>
6769 The min/magnification filter used when sampling from this texture.
6770 .TP
6771 .B BORDER <CLAMP|REPEAT|MIRROR>
6772 The border wrapping mode used when sampling from this texture.
6773 .UNINDENT
6774 .sp
6775 Following the metadata is a string of bytes in hexadecimal notation that
6776 define the raw texture data, corresponding to the format specified by
6777 \fIFORMAT\fP, on a single line with no extra whitespace.
6778 .sp
6779 A \fBHOOK\fP block can set the following options:
6780 .INDENT 7.0
6781 .TP
6782 .B HOOK <name> (required)
6783 The texture which to hook into. May occur multiple times within a
6784 metadata block, up to a predetermined limit. See below for a list of
6785 hookable textures.
6786 .TP
6787 .B DESC <title>
6788 User\-friendly description of the pass. This is the name used when
6789 representing this shader in the list of passes for property
6790 \fIvo\-passes\fP\&.
6791 .TP
6792 .B BIND <name>
6793 Loads a texture (either coming from mpv or from a \fBTEXTURE\fP block)
6794 and makes it available to the pass. When binding textures from mpv,
6795 this will also set up macros to facilitate accessing it properly. See
6796 below for a list. By default, no textures are bound. The special name
6797 HOOKED can be used to refer to the texture that triggered this pass.
6798 .TP
6799 .B SAVE <name>
6800 Gives the name of the texture to save the result of this pass into. By
6801 default, this is set to the special name HOOKED which has the effect of
6802 overwriting the hooked texture.
6803 .TP
6804 .B WIDTH <szexpr>, HEIGHT <szexpr>
6805 Specifies the size of the resulting texture for this pass. \fBszexpr\fP
6806 refers to an expression in RPN (reverse polish notation), using the
6807 operators + \- * / > < !, floating point literals, and references to
6808 sizes of existing texture (such as MAIN.width or CHROMA.height),
6809 OUTPUT, or NATIVE_CROPPED (size of an input texture cropped after
6810 pan\-and\-scan, video\-align\-x/y, video\-pan\-x/y, etc. and possibly
6811 prescaled). By default, these are set to HOOKED.w and HOOKED.h,
6812 espectively.
6813 .TP
6814 .B WHEN <szexpr>
6815 Specifies a condition that needs to be true (non\-zero) for the shader
6816 stage to be evaluated. If it fails, it will silently be omitted. (Note
6817 that a shader stage like this which has a dependency on an optional
6818 hook point can still cause that hook point to be saved, which has some
6819 minor overhead)
6820 .TP
6821 .B OFFSET <ox oy | ALIGN>
6822 Indicates a pixel shift (offset) introduced by this pass. These pixel
6823 offsets will be accumulated and corrected during the next scaling pass
6824 (\fBcscale\fP or \fBscale\fP). The default values are 0 0 which correspond
6825 to no shift. Note that offsets are ignored when not overwriting the
6826 hooked texture.
6827 .sp
6828 A special value of \fBALIGN\fP will attempt to fix existing offset of
6829 HOOKED by align it with reference. It requires HOOKED to be resizable
6830 (see below). It works transparently with fragment shader. For compute
6831 shader, the predefined \fBtexmap\fP macro is required to handle coordinate
6832 mapping.
6833 .TP
6834 .B COMPONENTS <n>
6835 Specifies how many components of this pass\(aqs output are relevant and
6836 should be stored in the texture, up to 4 (rgba). By default, this value
6837 is equal to the number of components in HOOKED.
6838 .TP
6839 .B COMPUTE <bw> <bh> [<tw> <th>]
6840 Specifies that this shader should be treated as a compute shader, with
6841 the block size bw and bh. The compute shader will be dispatched with
6842 however many blocks are necessary to completely tile over the output.
6843 Within each block, there will bw tw*th threads, forming a single work
6844 group. In other words: tw and th specify the work group size, which can
6845 be different from the block size. So for example, a compute shader with
6846 bw, bh = 32 and tw, th = 8 running on a 500x500 texture would dispatch
6847 16x16 blocks (rounded up), each with 8x8 threads.
6848 .sp
6849 Compute shaders in mpv are treated a bit different from fragment
6850 shaders. Instead of defining a \fBvec4 hook\fP that produces an output
6851 sample, you directly define \fBvoid hook\fP which writes to a fixed
6852 writeonly image unit named \fBout_image\fP (this is bound by mpv) using
6853 \fIimageStore\fP\&. To help translate texture coordinates in the absence of
6854 vertices, mpv provides a special function \fBNAME_map(id)\fP to map from
6855 the texel space of the output image to the texture coordinates for all
6856 bound textures. In particular, \fBNAME_pos\fP is equivalent to
6857 \fBNAME_map(gl_GlobalInvocationID)\fP, although using this only really
6858 makes sense if (tw,th) == (bw,bh).
6859 .UNINDENT
6860 .sp
6861 Each bound mpv texture (via \fBBIND\fP) will make available the following
6862 definitions to that shader pass, where NAME is the name of the bound
6863 texture:
6864 .INDENT 7.0
6865 .TP
6866 .B vec4 NAME_tex(vec2 pos)
6867 The sampling function to use to access the texture at a certain spot
6868 (in texture coordinate space, range [0,1]). This takes care of any
6869 necessary normalization conversions.
6870 .TP
6871 .B vec4 NAME_texOff(vec2 offset)
6872 Sample the texture at a certain offset in pixels. This works like
6873 NAME_tex but additionally takes care of necessary rotations, so that
6874 sampling at e.g. vec2(\-1,0) is always one pixel to the left.
6875 .TP
6876 .B vec2 NAME_pos
6877 The local texture coordinate of that texture, range [0,1].
6878 .TP
6879 .B vec2 NAME_size
6880 The (rotated) size in pixels of the texture.
6881 .TP
6882 .B mat2 NAME_rot
6883 The rotation matrix associated with this texture. (Rotates pixel space
6884 to texture coordinates)
6885 .TP
6886 .B vec2 NAME_pt
6887 The (unrotated) size of a single pixel, range [0,1].
6888 .TP
6889 .B float NAME_mul
6890 The coefficient that needs to be multiplied into the texture contents
6891 in order to normalize it to the range [0,1].
6892 .TP
6893 .B sampler NAME_raw
6894 The raw bound texture itself. The use of this should be avoided unless
6895 absolutely necessary.
6896 .UNINDENT
6897 .sp
6898 Normally, users should use either NAME_tex or NAME_texOff to read from the
6899 texture. For some shaders however , it can be better for performance to do
6900 custom sampling from NAME_raw, in which case care needs to be taken to
6901 respect NAME_mul and NAME_rot.
6902 .sp
6903 In addition to these parameters, the following uniforms are also globally
6904 available:
6905 .INDENT 7.0
6906 .TP
6907 .B float random
6908 A random number in the range [0\-1], different per frame.
6909 .TP
6910 .B int frame
6911 A simple count of frames rendered, increases by one per frame and never
6912 resets (regardless of seeks).
6913 .TP
6914 .B vec2 input_size
6915 The size in pixels of the input image (possibly cropped and prescaled).
6916 .TP
6917 .B vec2 target_size
6918 The size in pixels of the visible part of the scaled (and possibly
6919 cropped) image.
6920 .TP
6921 .B vec2 tex_offset
6922 Texture offset introduced by user shaders or options like panscan, video\-align\-x/y, video\-pan\-x/y.
6923 .UNINDENT
6924 .sp
6925 Internally, vo_gpu may generate any number of the following textures.
6926 Whenever a texture is rendered and saved by vo_gpu, all of the passes
6927 that have hooked into it will run, in the order they were added by the
6928 user. This is a list of the legal hook points:
6929 .INDENT 7.0
6930 .TP
6931 .B RGB, LUMA, CHROMA, ALPHA, XYZ (resizable)
6932 Source planes (raw). Which of these fire depends on the image format of
6933 the source.
6934 .TP
6935 .B CHROMA_SCALED, ALPHA_SCALED (fixed)
6936 Source planes (upscaled). These only fire on subsampled content.
6937 .TP
6938 .B NATIVE (resizable)
6939 The combined image, in the source colorspace, before conversion to RGB.
6940 .TP
6941 .B MAINPRESUB (resizable)
6942 The image, after conversion to RGB, but before
6943 \fB\-\-blend\-subtitles=video\fP is applied.
6944 .TP
6945 .B MAIN (resizable)
6946 The main image, after conversion to RGB but before upscaling.
6947 .TP
6948 .B LINEAR (fixed)
6949 Linear light image, before scaling. This only fires when
6950 \fB\-\-linear\-upscaling\fP, \fB\-\-linear\-downscaling\fP or
6951 \fB\-\-sigmoid\-upscaling\fP is in effect.
6952 .TP
6953 .B SIGMOID (fixed)
6954 Sigmoidized light, before scaling. This only fires when
6955 \fB\-\-sigmoid\-upscaling\fP is in effect.
6956 .TP
6957 .B PREKERNEL (fixed)
6958 The image immediately before the scaler kernel runs.
6959 .TP
6960 .B POSTKERNEL (fixed)
6961 The image immediately after the scaler kernel runs.
6962 .TP
6963 .B SCALED (fixed)
6964 The final upscaled image, before color management.
6965 .TP
6966 .B OUTPUT (fixed)
6967 The final output image, after color management but before dithering and
6968 drawing to screen.
6969 .UNINDENT
6970 .sp
6971 Only the textures labelled with \fBresizable\fP may be transformed by the
6972 pass. When overwriting a texture marked \fBfixed\fP, the WIDTH, HEIGHT and
6973 OFFSET must be left at their default values.
6974 .TP
6975 .B \fB\-\-glsl\-shader=<file>\fP
6976 CLI/config file only alias for \fB\-\-glsl\-shaders\-append\fP\&.
6977 .TP
6978 .B \fB\-\-deband\fP
6979 Enable the debanding algorithm. This greatly reduces the amount of visible
6980 banding, blocking and other quantization artifacts, at the expense of
6981 very slightly blurring some of the finest details. In practice, it\(aqs
6982 virtually always an improvement \- the only reason to disable it would be
6983 for performance.
6984 .TP
6985 .B \fB\-\-deband\-iterations=<1..16>\fP
6986 The number of debanding steps to perform per sample. Each step reduces a
6987 bit more banding, but takes time to compute. Note that the strength of each
6988 step falls off very quickly, so high numbers (>4) are practically useless.
6989 (Default 1)
6990 .TP
6991 .B \fB\-\-deband\-threshold=<0..4096>\fP
6992 The debanding filter\(aqs cut\-off threshold. Higher numbers increase the
6993 debanding strength dramatically but progressively diminish image details.
6994 (Default 64)
6995 .TP
6996 .B \fB\-\-deband\-range=<1..64>\fP
6997 The debanding filter\(aqs initial radius. The radius increases linearly for
6998 each iteration. A higher radius will find more gradients, but a lower
6999 radius will smooth more aggressively. (Default 16)
7000 .sp
7001 If you increase the \fB\-\-deband\-iterations\fP, you should probably decrease
7002 this to compensate.
7003 .TP
7004 .B \fB\-\-deband\-grain=<0..4096>\fP
7005 Add some extra noise to the image. This significantly helps cover up
7006 remaining quantization artifacts. Higher numbers add more noise. (Default
7007 48)
7008 .TP
7009 .B \fB\-\-sharpen=<value>\fP
7010 If set to a value other than 0, enable an unsharp masking filter. Positive
7011 values will sharpen the image (but add more ringing and aliasing). Negative
7012 values will blur the image. If your GPU is powerful enough, consider
7013 alternatives like the \fBewa_lanczossharp\fP scale filter, or the
7014 \fB\-\-scale\-blur\fP option.
7015 .TP
7016 .B \fB\-\-opengl\-glfinish\fP
7017 Call \fBglFinish()\fP before swapping buffers (default: disabled). Slower,
7018 but might improve results when doing framedropping. Can completely ruin
7019 performance. The details depend entirely on the OpenGL driver.
7020 .TP
7021 .B \fB\-\-opengl\-waitvsync\fP
7022 Call \fBglXWaitVideoSyncSGI\fP after each buffer swap (default: disabled).
7023 This may or may not help with video timing accuracy and frame drop. It\(aqs
7024 possible that this makes video output slower, or has no effect at all.
7025 .sp
7026 X11/GLX only.
7027 .TP
7028 .B \fB\-\-opengl\-dwmflush=<no|windowed|yes|auto>\fP
7029 Calls \fBDwmFlush\fP after swapping buffers on Windows (default: auto). It
7030 also sets \fBSwapInterval(0)\fP to ignore the OpenGL timing. Values are: no
7031 (disabled), windowed (only in windowed mode), yes (also in full screen).
7032 .sp
7033 The value \fBauto\fP will try to determine whether the compositor is active,
7034 and calls \fBDwmFlush\fP only if it seems to be.
7035 .sp
7036 This may help to get more consistent frame intervals, especially with
7037 high\-fps clips \- which might also reduce dropped frames. Typically, a value
7038 of \fBwindowed\fP should be enough, since full screen may bypass the DWM.
7039 .sp
7040 Windows only.
7041 .TP
7042 .B \fB\-\-angle\-d3d11\-feature\-level=<11_0|10_1|10_0|9_3>\fP
7043 Selects a specific feature level when using the ANGLE backend with D3D11.
7044 By default, the highest available feature level is used. This option can be
7045 used to select a lower feature level, which is mainly useful for debugging.
7046 Note that OpenGL ES 3.0 is only supported at feature level 10_1 or higher.
7047 Most extended OpenGL features will not work at lower feature levels
7048 (similar to \fB\-\-gpu\-dumb\-mode\fP).
7049 .sp
7050 Windows with ANGLE only.
7051 .TP
7052 .B \fB\-\-angle\-d3d11\-warp=<yes|no|auto>\fP
7053 Use WARP (Windows Advanced Rasterization Platform) when using the ANGLE
7054 backend with D3D11 (default: auto). This is a high performance software
7055 renderer. By default, it is used when the Direct3D hardware does not
7056 support Direct3D 11 feature level 9_3. While the extended OpenGL features
7057 will work with WARP, they can be very slow.
7058 .sp
7059 Windows with ANGLE only.
7060 .TP
7061 .B \fB\-\-angle\-egl\-windowing=<yes|no|auto>\fP
7062 Use ANGLE\(aqs built in EGL windowing functions to create a swap chain
7063 (default: auto). If this is set to \fBno\fP and the D3D11 renderer is in use,
7064 ANGLE\(aqs built in swap chain will not be used and a custom swap chain that
7065 is optimized for video rendering will be created instead. If set to
7066 \fBauto\fP, a custom swap chain will be used for D3D11 and the built in swap
7067 chain will be used for D3D9. This option is mainly for debugging purposes,
7068 in case the custom swap chain has poor performance or does not work.
7069 .sp
7070 If set to \fByes\fP, the \fB\-\-angle\-max\-frame\-latency\fP,
7071 \fB\-\-angle\-swapchain\-length\fP and \fB\-\-angle\-flip\fP options will have no
7072 effect.
7073 .sp
7074 Windows with ANGLE only.
7075 .TP
7076 .B \fB\-\-angle\-flip=<yes|no>\fP
7077 Enable flip\-model presentation, which avoids unnecessarily copying the
7078 backbuffer by sharing surfaces with the DWM (default: yes). This may cause
7079 performance issues with older drivers. If flip\-model presentation is not
7080 supported (for example, on Windows 7 without the platform update), mpv will
7081 automatically fall back to the older bitblt presentation model.
7082 .sp
7083 If set to \fBno\fP, the \fB\-\-angle\-swapchain\-length\fP option will have no
7084 effect.
7085 .sp
7086 Windows with ANGLE only.
7087 .TP
7088 .B \fB\-\-angle\-renderer=<d3d9|d3d11|auto>\fP
7089 Forces a specific renderer when using the ANGLE backend (default: auto). In
7090 auto mode this will pick D3D11 for systems that support Direct3D 11 feature
7091 level 9_3 or higher, and D3D9 otherwise. This option is mainly for
7092 debugging purposes. Normally there is no reason to force a specific
7093 renderer, though \fB\-\-angle\-renderer=d3d9\fP may give slightly better
7094 performance on old hardware. Note that the D3D9 renderer only supports
7095 OpenGL ES 2.0, so most extended OpenGL features will not work if this
7096 renderer is selected (similar to \fB\-\-gpu\-dumb\-mode\fP).
7097 .sp
7098 Windows with ANGLE only.
7099 .TP
7100 .B \fB\-\-cocoa\-force\-dedicated\-gpu=<yes|no>\fP
7101 Deactivates the automatic graphics switching and forces the dedicated GPU.
7102 (default: no)
7103 .sp
7104 OS X only.
7105 .TP
7106 .B \fB\-\-cocoa\-cb\-sw\-renderer=<yes|no|auto>\fP
7107 Use the Apple Software Renderer when using cocoa\-cb (default: auto). If set
7108 to \fBno\fP the software renderer is never used and instead fails when a the
7109 usual pixel format could not be created, \fByes\fP will always only use the
7110 software renderer, and \fBauto\fP only falls back to the software renderer
7111 when the usual pixel format couldn\(aqt be created.
7112 .sp
7113 OS X only.
7114 .TP
7115 .B \fB\-\-cocoa\-cb\-10bit\-context=<yes|no>\fP
7116 Creates a 10bit capable pixel format for the context creation (default: yes).
7117 Instead of 8bit integer framebuffer a 16bit half\-float framebuffer is
7118 requested.
7119 .sp
7120 OS X only.
7121 .TP
7122 .B \fB\-\-macos\-title\-bar\-appearance=<appearance>\fP
7123 Sets the appearance of the title bar (default: auto). Not all combinations
7124 of appearances and \fB\-\-macos\-title\-bar\-material\fP materials make sense or
7125 are unique. Appearances that are not supported by you current macOS version
7126 fall back to the default value.
7127 macOS and cocoa\-cb only
7128 .sp
7129 \fB<appearance>\fP can be one of the following:
7130 .INDENT 7.0
7131 .TP
7132 .B auto
7133 Detects the system settings and sets the title
7134 bar appearance appropriately. On macOS 10.14 it
7135 also detects run time changes.
7136 .TP
7137 .B aqua
7138 The standard macOS Light appearance.
7139 .TP
7140 .B darkAqua
7141 The standard macOS Dark appearance. (macOS 10.14+)
7142 .TP
7143 .B vibrantLight
7144 Light vibrancy appearance with.
7145 .TP
7146 .B vibrantDark
7147 Dark vibrancy appearance with.
7148 .TP
7149 .B aquaHighContrast
7150 Light Accessibility appearance. (macOS 10.14+)
7151 .TP
7152 .B darkAquaHighContrast
7153 Dark Accessibility appearance. (macOS 10.14+)
7154 .TP
7155 .B vibrantLightHighContrast
7156 Light vibrancy Accessibility appearance.
7157 (macOS 10.14+)
7158 .TP
7159 .B vibrantDarkHighContrast
7160 Dark vibrancy Accessibility appearance.
7161 (macOS 10.14+)
7162 .UNINDENT
7163 .TP
7164 .B \fB\-\-macos\-title\-bar\-material=<material>\fP
7165 Sets the material of the title bar (default: titlebar). All deprecated
7166 materials should not be used on macOS 10.14+ because their functionality
7167 is not guaranteed. Not all combinations of materials and
7168 \fB\-\-macos\-title\-bar\-appearance\fP appearances make sense or are unique.
7169 Materials that are not supported by you current macOS version fall back to
7170 the default value.
7171 macOS and cocoa\-cb only
7172 .sp
7173 \fB<material>\fP can be one of the following:
7174 .INDENT 7.0
7175 .TP
7176 .B titlebar
7177 The standard macOS titel bar material.
7178 .TP
7179 .B selection
7180 The standard macOS selection material.
7181 .TP
7182 .B menu
7183 The standard macOS menu material. (macOS 10.11+)
7184 .TP
7185 .B popover
7186 The standard macOS popover material. (macOS 10.11+)
7187 .TP
7188 .B sidebar
7189 The standard macOS sidebar material. (macOS 10.11+)
7190 .TP
7191 .B headerView
7192 The standard macOS header view material.
7193 (macOS 10.14+)
7194 .TP
7195 .B sheet
7196 The standard macOS sheet material. (macOS 10.14+)
7197 .TP
7198 .B windowBackground
7199 The standard macOS window background material.
7200 (macOS 10.14+)
7201 .TP
7202 .B hudWindow
7203 The standard macOS hudWindow material. (macOS 10.14+)
7204 .TP
7205 .B fullScreen
7206 The standard macOS full screen material.
7207 (macOS 10.14+)
7208 .TP
7209 .B toolTip
7210 The standard macOS tool tip material. (macOS 10.14+)
7211 .TP
7212 .B contentBackground
7213 The standard macOS content background material.
7214 (macOS 10.14+)
7215 .TP
7216 .B underWindowBackground
7217 The standard macOS under window background material.
7218 (macOS 10.14+)
7219 .TP
7220 .B underPageBackground
7221 The standard macOS under page background material.
7222 (deprecated in macOS 10.14+)
7223 .TP
7224 .B dark
7225 The standard macOS dark material.
7226 (deprecated in macOS 10.14+)
7227 .TP
7228 .B light
7229 The standard macOS light material.
7230 (macOS 10.14+)
7231 .TP
7232 .B mediumLight
7233 The standard macOS mediumLight material.
7234 (macOS 10.11+, deprecated in macOS 10.14+)
7235 .TP
7236 .B ultraDark
7237 The standard macOS ultraDark material.
7238 (macOS 10.11+ deprecated in macOS 10.14+)
7239 .UNINDENT
7240 .TP
7241 .B \fB\-\-macos\-title\-bar\-color=<color>\fP
7242 Sets the color of the title bar (default: completely transparent). Is
7243 influenced by \fB\-\-macos\-title\-bar\-appearance\fP and
7244 \fB\-\-macos\-title\-bar\-material\fP\&.
7245 See \fB\-\-sub\-color\fP for color syntax.
7246 .TP
7247 .B \fB\-\-macos\-fs\-animation\-duration=<default|0\-1000>\fP
7248 Sets the fullscreen resize animation duration in ms (default: default).
7249 The default value is slightly less than the system\(aqs animation duration
7250 (500ms) to prevent some problems when the end of an async animation happens
7251 at the same time as the end of the system wide fullscreen animation. Setting
7252 anything higher than 500ms will only prematurely cancel the resize animation
7253 after the system wide animation ended. The upper limit is still set at
7254 1000ms since it\(aqs possible that Apple or the user changes the system
7255 defaults. Anything higher than 1000ms though seems too long and shouldn\(aqt be
7256 set anyway.
7257 OS X and cocoa\-cb only
7258 .TP
7259 .B \fB\-\-android\-surface\-size=<WxH>\fP
7260 Set dimensions of the rendering surface used by the Android gpu context.
7261 Needs to be set by the embedding application if the dimensions change during
7262 runtime (i.e. if the device is rotated), via the surfaceChanged callback.
7263 .sp
7264 Android with \fB\-\-gpu\-context=android\fP only.
7265 .TP
7266 .B \fB\-\-gpu\-sw\fP
7267 Continue even if a software renderer is detected.
7268 .TP
7269 .B \fB\-\-gpu\-context=<sys>\fP
7270 The value \fBauto\fP (the default) selects the GPU context. You can also pass
7271 \fBhelp\fP to get a complete list of compiled in backends (sorted by
7272 autoprobe order).
7273 .INDENT 7.0
7274 .TP
7275 .B auto
7276 auto\-select (default)
7277 .TP
7278 .B cocoa
7279 Cocoa/OS X (deprecated, use \-\-vo=opengl\-cb instead)
7280 .TP
7281 .B win
7282 Win32/WGL
7283 .TP
7284 .B winvk
7285 VK_KHR_win32_surface
7286 .TP
7287 .B angle
7288 Direct3D11 through the OpenGL ES translation layer ANGLE. This supports
7289 almost everything the \fBwin\fP backend does (if the ANGLE build is new
7290 enough).
7291 .TP
7292 .B dxinterop (experimental)
7293 Win32, using WGL for rendering and Direct3D 9Ex for presentation. Works
7294 on Nvidia and AMD. Newer Intel chips with the latest drivers may also
7295 work.
7296 .TP
7297 .B d3d11
7298 Win32, with native Direct3D 11 rendering.
7299 .TP
7300 .B x11
7301 X11/GLX
7302 .TP
7303 .B x11vk
7304 VK_KHR_xlib_surface
7305 .TP
7306 .B wayland
7307 Wayland/EGL
7308 .TP
7309 .B waylandvk
7310 VK_KHR_wayland_surface
7311 .TP
7312 .B drm
7313 DRM/EGL
7314 .TP
7315 .B x11egl
7316 X11/EGL
7317 .TP
7318 .B android
7319 Android/EGL. Requires \fB\-\-wid\fP be set to an \fBandroid.view.Surface\fP\&.
7320 .TP
7321 .B vdpauglx
7322 Use vdpau presentation with GLX as backing. Experimental use only.
7323 Using this will have no advantage (other than additional bugs or
7324 performance problems), and is for doing experiments only. Will not
7325 be used automatically.
7326 .UNINDENT
7327 .TP
7328 .B \fB\-\-gpu\-api=<type>\fP
7329 Controls which type of graphics APIs will be accepted:
7330 .INDENT 7.0
7331 .TP
7332 .B auto
7333 Use any available API (default)
7334 .TP
7335 .B opengl
7336 Allow only OpenGL (requires OpenGL 2.1+ or GLES 2.0+)
7337 .TP
7338 .B vulkan
7339 Allow only Vulkan (requires a valid/working \fB\-\-spirv\-compiler\fP)
7340 .TP
7341 .B d3d11
7342 Allow only \fB\-\-gpu\-context=d3d11\fP
7343 .UNINDENT
7344 .TP
7345 .B \fB\-\-opengl\-es=<mode>\fP
7346 Controls which type of OpenGL context will be accepted:
7347 .INDENT 7.0
7348 .TP
7349 .B auto
7350 Allow all types of OpenGL (default)
7351 .TP
7352 .B yes
7353 Only allow GLES
7354 .TP
7355 .B no
7356 Only allow desktop/core GL
7357 .UNINDENT
7358 .TP
7359 .B \fB\-\-opengl\-restrict=<version>\fP
7360 Restricts all OpenGL versions above a certain version. Versions are encoded
7361 in hundreds, i.e. OpenGL 4.5 \-> 450. As an example, \-\-opengl\-restrict=300
7362 would restrict OpenGL 3.0 and higher, effectively only allowing 2.x
7363 contexts. Note that this only imposes a limit on context creation APIs, the
7364 actual OpenGL context may still have a higher OpenGL version. (Default: 0)
7365 .TP
7366 .B \fB\-\-fbo\-format=<fmt>\fP
7367 Selects the internal format of textures used for FBOs. The format can
7368 influence performance and quality of the video output. \fBfmt\fP can be one
7369 of: rgb8, rgb10, rgb10_a2, rgb16, rgb16f, rgb32f, rgba12, rgba16, rgba16f,
7370 rgba16hf, rgba32f.
7371 .sp
7372 Default: \fBauto\fP, which first attempts to utilize 16bit float
7373 (rgba16f, rgba16hf), and falls back to rgba16 if those are not available.
7374 Finally, attempts to utilize rgb10_a2 or rgba8 if all of the previous formats
7375 are not available.
7376 .TP
7377 .B \fB\-\-gamma\-factor=<0.1..2.0>\fP
7378 Set an additional raw gamma factor (default: 1.0). If gamma is adjusted in
7379 other ways (like with the \fB\-\-gamma\fP option or key bindings and the
7380 \fBgamma\fP property), the value is multiplied with the other gamma value.
7381 .sp
7382 Recommended values based on the environmental brightness:
7383 .INDENT 7.0
7384 .TP
7385 .B 1.0
7386 Pitch black or dimly lit room (default)
7387 .TP
7388 .B 1.1
7389 Moderately lit room, home
7390 .TP
7391 .B 1.2
7392 Brightly illuminated room, office
7393 .UNINDENT
7394 .sp
7395 NOTE: This is based around the assumptions of typical movie content, which
7396 contains an implicit end\-to\-end of about 0.8 from scene to display. For
7397 bright environments it can be useful to cancel that out.
7398 .TP
7399 .B \fB\-\-gamma\-auto\fP
7400 Automatically corrects the gamma value depending on ambient lighting
7401 conditions (adding a gamma boost for bright rooms).
7402 .sp
7403 With ambient illuminance of 16 lux, mpv will pick the 1.0 gamma value (no
7404 boost), and slightly increase the boost up until 1.2 for 256 lux.
7405 .sp
7406 NOTE: Only implemented on OS X.
7407 .TP
7408 .B \fB\-\-target\-prim=<value>\fP
7409 Specifies the primaries of the display. Video colors will be adapted to
7410 this colorspace when ICC color management is not being used. Valid values
7411 are:
7412 .INDENT 7.0
7413 .TP
7414 .B auto
7415 Disable any adaptation, except for atypical color spaces. Specifically,
7416 wide/unusual gamuts get automatically adapted to BT.709, while standard
7417 gamut (i.e. BT.601 and BT.709) content is not touched. (default)
7418 .TP
7419 .B bt.470m
7420 ITU\-R BT.470 M
7421 .TP
7422 .B bt.601\-525
7423 ITU\-R BT.601 (525\-line SD systems, eg. NTSC), SMPTE 170M/240M
7424 .TP
7425 .B bt.601\-625
7426 ITU\-R BT.601 (625\-line SD systems, eg. PAL/SECAM), ITU\-R BT.470 B/G
7427 .TP
7428 .B bt.709
7429 ITU\-R BT.709 (HD), IEC 61966\-2\-4 (sRGB), SMPTE RP177 Annex B
7430 .TP
7431 .B bt.2020
7432 ITU\-R BT.2020 (UHD)
7433 .TP
7434 .B apple
7435 Apple RGB
7436 .TP
7437 .B adobe
7438 Adobe RGB (1998)
7439 .TP
7440 .B prophoto
7441 ProPhoto RGB (ROMM)
7442 .TP
7443 .B cie1931
7444 CIE 1931 RGB (not to be confused with CIE XYZ)
7445 .TP
7446 .B dci\-p3
7447 DCI\-P3 (Digital Cinema Colorspace), SMPTE RP431\-2
7448 .TP
7449 .B v\-gamut
7450 Panasonic V\-Gamut (VARICAM) primaries
7451 .TP
7452 .B s\-gamut
7453 Sony S\-Gamut (S\-Log) primaries
7454 .UNINDENT
7455 .TP
7456 .B \fB\-\-target\-trc=<value>\fP
7457 Specifies the transfer characteristics (gamma) of the display. Video colors
7458 will be adjusted to this curve when ICC color management is not being used.
7459 Valid values are:
7460 .INDENT 7.0
7461 .TP
7462 .B auto
7463 Disable any adaptation, except for atypical transfers. Specifically,
7464 HDR or linear light source material gets automatically converted to
7465 gamma 2.2, while SDR content is not touched. (default)
7466 .TP
7467 .B bt.1886
7468 ITU\-R BT.1886 curve (assuming infinite contrast)
7469 .TP
7470 .B srgb
7471 IEC 61966\-2\-4 (sRGB)
7472 .TP
7473 .B linear
7474 Linear light output
7475 .TP
7476 .B gamma1.8
7477 Pure power curve (gamma 1.8), also used for Apple RGB
7478 .TP
7479 .B gamma2.0
7480 Pure power curve (gamma 2.0)
7481 .TP
7482 .B gamma2.2
7483 Pure power curve (gamma 2.2)
7484 .TP
7485 .B gamma2.4
7486 Pure power curve (gamma 2.4)
7487 .TP
7488 .B gamma2.6
7489 Pure power curve (gamma 2.6)
7490 .TP
7491 .B gamma2.8
7492 Pure power curve (gamma 2.8), also used for BT.470\-BG
7493 .TP
7494 .B prophoto
7495 ProPhoto RGB (ROMM)
7496 .TP
7497 .B pq
7498 ITU\-R BT.2100 PQ (Perceptual quantizer) curve, aka SMPTE ST2084
7499 .TP
7500 .B hlg
7501 ITU\-R BT.2100 HLG (Hybrid Log\-gamma) curve, aka ARIB STD\-B67
7502 .TP
7503 .B v\-log
7504 Panasonic V\-Log (VARICAM) curve
7505 .TP
7506 .B s\-log1
7507 Sony S\-Log1 curve
7508 .TP
7509 .B s\-log2
7510 Sony S\-Log2 curve
7511 .UNINDENT
7512 .sp
7513 \fBNOTE:\fP
7514 .INDENT 7.0
7515 .INDENT 3.5
7516 When using HDR output formats, mpv will encode to the specified
7517 curve but it will not set any HDMI flags or other signalling that might
7518 be required for the target device to correctly display the HDR signal.
7519 The user should independently guarantee this before using these signal
7520 formats for display.
7521 .UNINDENT
7522 .UNINDENT
7523 .TP
7524 .B \fB\-\-target\-peak=<auto|nits>\fP
7525 Specifies the measured peak brightness of the output display, in cd/m^2
7526 (AKA nits). The interpretation of this brightness depends on the configured
7527 \fB\-\-target\-trc\fP\&. In all cases, it imposes a limit on the signal values
7528 that will be sent to the display. If the source exceeds this brightness
7529 level, a tone mapping filter will be inserted. For HLG, it has the
7530 additional effect of parametrizing the inverse OOTF, in order to get
7531 colorimetrically consistent results with the mastering display. For SDR, or
7532 when using an ICC (profile (\fB\-\-icc\-profile\fP), setting this to a value
7533 above 100 essentially causes the display to be treated as if it were an HDR
7534 display in disguise. (See the note below)
7535 .sp
7536 In \fBauto\fP mode (the default), the chosen peak is an appropriate value
7537 based on the TRC in use. For SDR curves, it uses 100. For HDR curves, it
7538 uses 100 * the transfer function\(aqs nominal peak.
7539 .sp
7540 \fBNOTE:\fP
7541 .INDENT 7.0
7542 .INDENT 3.5
7543 When using an SDR transfer function, this is normally not needed, and
7544 setting it may lead to very unexpected results. The one time it \fIis\fP
7545 useful is if you want to calibrate a HDR display using traditional
7546 transfer functions and calibration equipment. In such cases, you can
7547 set your HDR display to a high brightness such as 800 cd/m^2, and then
7548 calibrate it to a standard curve like gamma2.8. Setting this value to
7549 800 would then instruct mpv to essentially treat it as an HDR display
7550 with the given peak. This may be a good alternative in environments
7551 where PQ or HLG input to the display is not possible, and makes it
7552 possible to use HDR displays with mpv regardless of operating system
7553 support for HDMI HDR metadata.
7554 .sp
7555 In such a configuration, we highly recommend setting \fB\-\-tone\-mapping\fP
7556 to \fBmobius\fP or even \fBclip\fP\&.
7557 .UNINDENT
7558 .UNINDENT
7559 .TP
7560 .B \fB\-\-tone\-mapping=<value>\fP
7561 Specifies the algorithm used for tone\-mapping images onto the target
7562 display. This is relevant for both HDR\->SDR conversion as well as gamut
7563 reduction (e.g. playing back BT.2020 content on a standard gamut display).
7564 Valid values are:
7565 .INDENT 7.0
7566 .TP
7567 .B clip
7568 Hard\-clip any out\-of\-range values. Use this when you care about
7569 perfect color accuracy for in\-range values at the cost of completely
7570 distorting out\-of\-range values. Not generally recommended.
7571 .TP
7572 .B mobius
7573 Generalization of Reinhard to a Möbius transform with linear section.
7574 Smoothly maps out\-of\-range values while retaining contrast and colors
7575 for in\-range material as much as possible. Use this when you care about
7576 color accuracy more than detail preservation. This is somewhere in
7577 between \fBclip\fP and \fBreinhard\fP, depending on the value of
7578 \fB\-\-tone\-mapping\-param\fP\&.
7579 .TP
7580 .B reinhard
7581 Reinhard tone mapping algorithm. Very simple continuous curve.
7582 Preserves overall image brightness but uses nonlinear contrast, which
7583 results in flattening of details and degradation in color accuracy.
7584 .TP
7585 .B hable
7586 Similar to \fBreinhard\fP but preserves both dark and bright details
7587 better (slightly sigmoidal), at the cost of slightly darkening /
7588 desaturating everything. Developed by John Hable for use in video
7589 games. Use this when you care about detail preservation more than
7590 color/brightness accuracy. This is roughly equivalent to
7591 \fB\-\-tone\-mapping=reinhard \-\-tone\-mapping\-param=0.24\fP\&. If possible,
7592 you should also enable \fB\-\-hdr\-compute\-peak\fP for the best results.
7593 (Default)
7594 .TP
7595 .B gamma
7596 Fits a logarithmic transfer between the tone curves.
7597 .TP
7598 .B linear
7599 Linearly stretches the entire reference gamut to (a linear multiple of)
7600 the display.
7601 .UNINDENT
7602 .TP
7603 .B \fB\-\-tone\-mapping\-param=<value>\fP
7604 Set tone mapping parameters. By default, this is set to the special string
7605 \fBdefault\fP, which maps to an algorithm\-specific default value. Ignored if
7606 the tone mapping algorithm is not tunable. This affects the following tone
7607 mapping algorithms:
7608 .INDENT 7.0
7609 .TP
7610 .B clip
7611 Specifies an extra linear coefficient to multiply into the signal
7612 before clipping. Defaults to 1.0.
7613 .TP
7614 .B mobius
7615 Specifies the transition point from linear to mobius transform. Every
7616 value below this point is guaranteed to be mapped 1:1. The higher the
7617 value, the more accurate the result will be, at the cost of losing
7618 bright details. Defaults to 0.3, which due to the steep initial slope
7619 still preserves in\-range colors fairly accurately.
7620 .TP
7621 .B reinhard
7622 Specifies the local contrast coefficient at the display peak. Defaults
7623 to 0.5, which means that in\-gamut values will be about half as bright
7624 as when clipping.
7625 .TP
7626 .B gamma
7627 Specifies the exponent of the function. Defaults to 1.8.
7628 .TP
7629 .B linear
7630 Specifies the scale factor to use while stretching. Defaults to 1.0.
7631 .UNINDENT
7632 .TP
7633 .B \fB\-\-tone\-mapping\-max\-boost=<1.0..10.0>\fP
7634 Upper limit for how much the tone mapping algorithm is allowed to boost
7635 the average brightness by over\-exposing the image. The default value of 1.0
7636 allows no additional brightness boost. A value of 2.0 would allow
7637 over\-exposing by a factor of 2, and so on. Raising this setting can help
7638 reveal details that would otherwise be hidden in dark scenes, but raising
7639 it too high will make dark scenes appear unnaturally bright.
7640 .TP
7641 .B \fB\-\-hdr\-compute\-peak=<auto|yes|no>\fP
7642 Compute the HDR peak and frame average brightness per\-frame instead of
7643 relying on tagged metadata. These values are averaged over local regions as
7644 well as over several frames to prevent the value from jittering around too
7645 much. This option basically gives you dynamic, per\-scene tone mapping.
7646 Requires compute shaders, which is a fairly recent OpenGL feature, and will
7647 probably also perform horribly on some drivers, so enable at your own risk.
7648 The special value \fBauto\fP (default) will enable HDR peak computation
7649 automatically if compute shaders and SSBOs are supported.
7650 .TP
7651 .B \fB\-\-hdr\-peak\-decay\-rate=<1.0..1000.0>\fP
7652 The decay rate used for the HDR peak detection algorithm (default: 100.0).
7653 This is only relevant when \fB\-\-hdr\-compute\-peak\fP is enabled. Higher values
7654 make the peak decay more slowly, leading to more stable values at the cost
7655 of more "eye adaptation"\-like effects (although this is mitigated somewhat
7656 by \fB\-\-hdr\-scene\-threshold\fP). A value of 1.0 (the lowest possible) disables
7657 all averaging, meaning each frame\(aqs value is used directly as measured,
7658 but doing this is not recommended for "noisy" sources since it may lead
7659 to excessive flicker. (In signal theory terms, this controls the time
7660 constant "tau" of an IIR low pass filter)
7661 .TP
7662 .B \fB\-\-hdr\-scene\-threshold\-low=<0.0..100.0>\fP, \fB\-\-hdr\-scene\-threshold\-high=<0.0..100.0>\fP
7663 The lower and upper thresholds (in dB) for a brightness difference
7664 to be considered a scene change (default: 5.5 low, 10.0 high). This is only
7665 relevant when \fB\-\-hdr\-compute\-peak\fP is enabled. Normally, small
7666 fluctuations in the frame brightness are compensated for by the peak
7667 averaging mechanism, but for large jumps in the brightness this can result
7668 in the frame remaining too bright or too dark for up to several seconds,
7669 depending on the value of \fB\-\-hdr\-peak\-decay\-rate\fP\&. To counteract this,
7670 when the brightness between the running average and the current frame
7671 exceeds the low threshold, mpv will make the averaging filter more
7672 aggressive, up to the limit of the high threshold (at which point the
7673 filter becomes instant).
7674 .TP
7675 .B \fB\-\-tone\-mapping\-desaturate=<0.0..1.0>\fP
7676 Apply desaturation for highlights (default: 0.75). The parameter controls
7677 the strength of the desaturation curve. A value of 0.0 completely disables
7678 it, while a value of 1.0 means that overly bright colors will tend towards
7679 white. (This is not always the case, especially not for highlights that are
7680 near primary colors)
7681 .sp
7682 Values in between apply progressively more/less aggressive desaturation.
7683 This setting helps prevent unnaturally oversaturated colors for
7684 super\-highlights, by (smoothly) turning them into less saturated (per
7685 channel tone mapped) colors instead. This makes images feel more natural,
7686 at the cost of chromatic distortions for out\-of\-range colors. The default
7687 value of 0.75 provides a good balance. Setting this to 0.0 preserves the
7688 chromatic accuracy of the tone mapping process.
7689 .TP
7690 .B \fB\-\-tone\-mapping\-desaturate\-exponent=<0.0..20.0>\fP
7691 This setting controls the exponent of the desaturation curve, which
7692 controls how bright a color needs to be in order to start being
7693 desaturated. The default of 1.5 provides a reasonable balance. Decreasing
7694 this exponent makes the curve more aggressive.
7695 .TP
7696 .B \fB\-\-gamut\-warning\fP
7697 If enabled, mpv will mark all clipped/out\-of\-gamut pixels that exceed a
7698 given threshold (currently hard\-coded to 101%). The affected pixels will be
7699 inverted to make them stand out. Note: This option applies after the
7700 effects of all of mpv\(aqs color space transformation / tone mapping options,
7701 so it\(aqs a good idea to combine this with \fB\-\-tone\-mapping=clip\fP and use
7702 \fB\-\-target\-prim\fP to set the gamut to simulate. For example,
7703 \fB\-\-target\-prim=bt.709\fP would make mpv highlight all pixels that exceed the
7704 gamut of a standard gamut (sRGB) display. This option also does not work
7705 well with ICC profiles, since the 3DLUTs are always generated against the
7706 source color space and have chromatically\-accurate clipping built in.
7707 .TP
7708 .B \fB\-\-use\-embedded\-icc\-profile\fP
7709 Load the embedded ICC profile contained in media files such as PNG images.
7710 (Default: yes). Note that this option only works when also using a display
7711 ICC profile (\fB\-\-icc\-profile\fP or \fB\-\-icc\-profile\-auto\fP), and also
7712 requires LittleCMS 2 support.
7713 .TP
7714 .B \fB\-\-icc\-profile=<file>\fP
7715 Load an ICC profile and use it to transform video RGB to screen output.
7716 Needs LittleCMS 2 support compiled in. This option overrides the
7717 \fB\-\-target\-prim\fP, \fB\-\-target\-trc\fP and \fB\-\-icc\-profile\-auto\fP options.
7718 .TP
7719 .B \fB\-\-icc\-profile\-auto\fP
7720 Automatically select the ICC display profile currently specified by the
7721 display settings of the operating system.
7722 .sp
7723 NOTE: On Windows, the default profile must be an ICC profile. WCS profiles
7724 are not supported.
7725 .sp
7726 Applications using libmpv with the render API need to provide the ICC
7727 profile via \fBMPV_RENDER_PARAM_ICC_PROFILE\fP\&.
7728 .TP
7729 .B \fB\-\-icc\-cache\-dir=<dirname>\fP
7730 Store and load the 3D LUTs created from the ICC profile in this directory.
7731 This can be used to speed up loading, since LittleCMS 2 can take a while to
7732 create a 3D LUT. Note that these files contain uncompressed LUTs. Their
7733 size depends on the \fB\-\-icc\-3dlut\-size\fP, and can be very big.
7734 .sp
7735 NOTE: This is not cleaned automatically, so old, unused cache files may
7736 stick around indefinitely.
7737 .TP
7738 .B \fB\-\-icc\-intent=<value>\fP
7739 Specifies the ICC intent used for the color transformation (when using
7740 \fB\-\-icc\-profile\fP).
7741 .INDENT 7.0
7742 .TP
7743 .B 0
7744 perceptual
7745 .TP
7746 .B 1
7747 relative colorimetric (default)
7748 .TP
7749 .B 2
7750 saturation
7751 .TP
7752 .B 3
7753 absolute colorimetric
7754 .UNINDENT
7755 .TP
7756 .B \fB\-\-icc\-3dlut\-size=<r>x<g>x<b>\fP
7757 Size of the 3D LUT generated from the ICC profile in each dimension.
7758 Default is 64x64x64. Sizes may range from 2 to 512.
7759 .TP
7760 .B \fB\-\-icc\-contrast=<0\-1000000|inf>\fP
7761 Specifies an upper limit on the target device\(aqs contrast ratio. This is
7762 detected automatically from the profile if possible, but for some profiles
7763 it might be missing, causing the contrast to be assumed as infinite. As a
7764 result, video may appear darker than intended. This only affects BT.1886
7765 content. The default of 0 means no limit if the detected contrast is less
7766 than 100000, and limits to 1000 otherwise. Use \fB\-\-icc\-contrast=inf\fP to
7767 preserve the infinite contrast (most likely when using OLED displays).
7768 .TP
7769 .B \fB\-\-blend\-subtitles=<yes|video|no>\fP
7770 Blend subtitles directly onto upscaled video frames, before interpolation
7771 and/or color management (default: no). Enabling this causes subtitles to be
7772 affected by \fB\-\-icc\-profile\fP, \fB\-\-target\-prim\fP, \fB\-\-target\-trc\fP,
7773 \fB\-\-interpolation\fP, \fB\-\-gamma\-factor\fP and \fB\-\-glsl\-shaders\fP\&. It also
7774 increases subtitle performance when using \fB\-\-interpolation\fP\&.
7775 .sp
7776 The downside of enabling this is that it restricts subtitles to the visible
7777 portion of the video, so you can\(aqt have subtitles exist in the black
7778 margins below a video (for example).
7779 .sp
7780 If \fBvideo\fP is selected, the behavior is similar to \fByes\fP, but subs are
7781 drawn at the video\(aqs native resolution, and scaled along with the video.
7782 .sp
7783 \fBWARNING:\fP
7784 .INDENT 7.0
7785 .INDENT 3.5
7786 This changes the way subtitle colors are handled. Normally,
7787 subtitle colors are assumed to be in sRGB and color managed as
7788 such. Enabling this makes them treated as being in the video\(aqs
7789 color space instead. This is good if you want things like
7790 softsubbed ASS signs to match the video colors, but may cause
7791 SRT subtitles or similar to look slightly off.
7792 .UNINDENT
7793 .UNINDENT
7794 .TP
7795 .B \fB\-\-alpha=<blend\-tiles|blend|yes|no>\fP
7796 Decides what to do if the input has an alpha component.
7797 .INDENT 7.0
7798 .TP
7799 .B blend\-tiles
7800 Blend the frame against a 16x16 gray/white tiles background (default).
7801 .TP
7802 .B blend
7803 Blend the frame against the background color (\fB\-\-background\fP, normally
7804 black).
7805 .TP
7806 .B yes
7807 Try to create a framebuffer with alpha component. This only makes sense
7808 if the video contains alpha information (which is extremely rare). May
7809 not be supported on all platforms. If alpha framebuffers are
7810 unavailable, it silently falls back on a normal framebuffer. Note that
7811 if you set the \fB\-\-fbo\-format\fP option to a non\-default value, a
7812 format with alpha must be specified, or this won\(aqt work.
7813 This does not work on X11 with EGL and Mesa (freedesktop bug 67676).
7814 .TP
7815 .B no
7816 Ignore alpha component.
7817 .UNINDENT
7818 .TP
7819 .B \fB\-\-opengl\-rectangle\-textures\fP
7820 Force use of rectangle textures (default: no). Normally this shouldn\(aqt have
7821 any advantages over normal textures. Note that hardware decoding overrides
7822 this flag. Could be removed any time.
7823 .TP
7824 .B \fB\-\-background=<color>\fP
7825 Color used to draw parts of the mpv window not covered by video. See
7826 \fB\-\-osd\-color\fP option how colors are defined.
7827 .TP
7828 .B \fB\-\-gpu\-tex\-pad\-x\fP, \fB\-\-gpu\-tex\-pad\-y\fP
7829 Enlarge the video source textures by this many pixels. For debugging only
7830 (normally textures are sized exactly, but due to hardware decoding interop
7831 we may have to deal with additional padding, which can be tested with these
7832 options). Could be removed any time.
7833 .TP
7834 .B \fB\-\-opengl\-early\-flush=<yes|no|auto>\fP
7835 Call \fBglFlush()\fP after rendering a frame and before attempting to display
7836 it (default: auto). Can fix stuttering in some cases, in other cases
7837 probably causes it. The \fBauto\fP mode will call \fBglFlush()\fP only if
7838 the renderer is going to wait for a while after rendering, instead of
7839 flipping GL front and backbuffers immediately (i.e. it doesn\(aqt call it
7840 in display\-sync mode).
7841 .sp
7842 On OSX this is always deactivated because it only causes performance
7843 problems and other regressions.
7844 .TP
7845 .B \fB\-\-gpu\-dumb\-mode=<yes|no|auto>\fP
7846 This mode is extremely restricted, and will disable most extended
7847 features. That includes high quality scalers and custom shaders!
7848 .sp
7849 It is intended for hardware that does not support FBOs (including GLES,
7850 which supports it insufficiently), or to get some more performance out of
7851 bad or old hardware.
7852 .sp
7853 This mode is forced automatically if needed, and this option is mostly
7854 useful for debugging. The default of \fBauto\fP will enable it automatically
7855 if nothing uses features which require FBOs.
7856 .sp
7857 This option might be silently removed in the future.
7858 .TP
7859 .B \fB\-\-gpu\-shader\-cache\-dir=<dirname>\fP
7860 Store and load compiled GLSL shaders in this directory. Normally, shader
7861 compilation is very fast, so this is usually not needed. It mostly matters
7862 for GPU APIs that require internally recompiling shaders to other languages,
7863 for example anything based on ANGLE or Vulkan. Enabling this can improve
7864 startup performance on these platforms.
7865 .sp
7866 NOTE: This is not cleaned automatically, so old, unused cache files may
7867 stick around indefinitely.
7868 .UNINDENT
7869 .SS Miscellaneous
7870 .INDENT 0.0
7871 .TP
7872 .B \fB\-\-display\-tags=tag1,tags2,...\fP
7873 Set the list of tags that should be displayed on the terminal. Tags that
7874 are in the list, but are not present in the played file, will not be shown.
7875 If a value ends with \fB*\fP, all tags are matched by prefix (though there
7876 is no general globbing). Just passing \fB*\fP essentially filtering.
7877 .sp
7878 The default includes a common list of tags, call mpv with \fB\-\-list\-options\fP
7879 to see it.
7880 .TP
7881 .B \fB\-\-mc=<seconds/frame>\fP
7882 Maximum A\-V sync correction per frame (in seconds)
7883 .TP
7884 .B \fB\-\-autosync=<factor>\fP
7885 Gradually adjusts the A/V sync based on audio delay measurements.
7886 Specifying \fB\-\-autosync=0\fP, the default, will cause frame timing to be
7887 based entirely on audio delay measurements. Specifying \fB\-\-autosync=1\fP
7888 will do the same, but will subtly change the A/V correction algorithm. An
7889 uneven video framerate in a video which plays fine with \fB\-\-no\-audio\fP can
7890 often be helped by setting this to an integer value greater than 1. The
7891 higher the value, the closer the timing will be to \fB\-\-no\-audio\fP\&. Try
7892 \fB\-\-autosync=30\fP to smooth out problems with sound drivers which do not
7893 implement a perfect audio delay measurement. With this value, if large A/V
7894 sync offsets occur, they will only take about 1 or 2 seconds to settle
7895 out. This delay in reaction time to sudden A/V offsets should be the only
7896 side effect of turning this option on, for all sound drivers.
7897 .TP
7898 .B \fB\-\-video\-timing\-offset=<seconds>\fP
7899 Control how long before video display target time the frame should be
7900 rendered (default: 0.050). If a video frame should be displayed at a
7901 certain time, the VO will start rendering the frame earlier, and then will
7902 perform a blocking wait until the display time, and only then "swap" the
7903 frame to display. The rendering cannot start before the previous frame is
7904 displayed, so this value is implicitly limited by the video framerate. With
7905 normal video frame rates, the default value will ensure that rendering is
7906 always immediately started after the previous frame was displayed. On the
7907 other hand, setting a too high value can reduce responsiveness with low
7908 FPS value.
7909 .sp
7910 For client API users using the render API (or the deprecated \fBopengl\-cb\fP
7911 API), this option is interesting, because you can stop the render API
7912 from limiting your FPS (see \fBmpv_render_context_render()\fP documentation).
7913 .sp
7914 This applies only to audio timing modes (e.g. \fB\-\-video\-sync=audio\fP). In
7915 other modes (\fB\-\-video\-sync=display\-...\fP), video timing relies on vsync
7916 blocking, and this option is not used.
7917 .TP
7918 .B \fB\-\-video\-sync=<audio|...>\fP
7919 How the player synchronizes audio and video.
7920 .sp
7921 If you use this option, you usually want to set it to \fBdisplay\-resample\fP
7922 to enable a timing mode that tries to not skip or repeat frames when for
7923 example playing 24fps video on a 24Hz screen.
7924 .sp
7925 The modes starting with \fBdisplay\-\fP try to output video frames completely
7926 synchronously to the display, using the detected display vertical refresh
7927 rate as a hint how fast frames will be displayed on average. These modes
7928 change video speed slightly to match the display. See \fB\-\-video\-sync\-...\fP
7929 options for fine tuning. The robustness of this mode is further reduced by
7930 making a some idealized assumptions, which may not always apply in reality.
7931 Behavior can depend on the VO and the system\(aqs video and audio drivers.
7932 Media files must use constant framerate. Section\-wise VFR might work as well
7933 with some container formats (but not e.g. mkv).
7934 .sp
7935 Under some circumstances, the player automatically reverts to \fBaudio\fP mode
7936 for some time or permanently. This can happen on very low framerate video,
7937 or if the framerate cannot be detected.
7938 .sp
7939 Also in display\-sync modes it can happen that interruptions to video
7940 playback (such as toggling fullscreen mode, or simply resizing the window)
7941 will skip the video frames that should have been displayed, while \fBaudio\fP
7942 mode will display them after the renderer has resumed (typically resulting
7943 in a short A/V desync and the video "catching up").
7944 .sp
7945 Before mpv 0.30.0, there was a fallback to \fBaudio\fP mode on severe A/V
7946 desync. This was changed for the sake of not sporadically stopping. Now,
7947 \fBdisplay\-desync\fP does what it promises and may desync with audio by an
7948 arbitrary amount, until it is manually fixed with a seek.
7949 .sp
7950 These modes also require a vsync blocked presentation mode. For OpenGL, this
7951 translates to \fB\-\-opengl\-swapinterval=1\fP\&. For Vulkan, it translates to
7952 \fB\-\-vulkan\-swap\-mode=fifo\fP (or \fBfifo\-relaxed\fP).
7953 .sp
7954 The modes with \fBdesync\fP in their names do not attempt to keep audio/video
7955 in sync. They will slowly (or quickly) desync, until e.g. the next seek
7956 happens. These modes are meant for testing, not serious use.
7957 .INDENT 7.0
7958 .TP
7959 .B audio
7960 Time video frames to audio. This is the most robust
7961 mode, because the player doesn\(aqt have to assume anything
7962 about how the display behaves. The disadvantage is that
7963 it can lead to occasional frame drops or repeats. If
7964 audio is disabled, this uses the system clock. This is
7965 the default mode.
7966 .TP
7967 .B display\-resample
7968 Resample audio to match the video. This mode will also
7969 try to adjust audio speed to compensate for other drift.
7970 (This means it will play the audio at a different speed
7971 every once in a while to reduce the A/V difference.)
7972 .TP
7973 .B display\-resample\-vdrop
7974 Resample audio to match the video. Drop video
7975 frames to compensate for drift.
7976 .TP
7977 .B display\-resample\-desync
7978 Like the previous mode, but no A/V compensation.
7979 .TP
7980 .B display\-vdrop
7981 Drop or repeat video frames to compensate desyncing
7982 video. (Although it should have the same effects as
7983 \fBaudio\fP, the implementation is very different.)
7984 .TP
7985 .B display\-adrop
7986 Drop or repeat audio data to compensate desyncing
7987 video. See \fB\-\-video\-sync\-adrop\-size\fP\&. This mode will
7988 cause severe audio artifacts if the real monitor
7989 refresh rate is too different from the reported or
7990 forced rate.
7991 .TP
7992 .B display\-desync
7993 Sync video to display, and let audio play on its own.
7994 .TP
7995 .B desync
7996 Sync video according to system clock, and let audio play
7997 on its own.
7998 .UNINDENT
7999 .TP
8000 .B \fB\-\-video\-sync\-max\-video\-change=<value>\fP
8001 Maximum speed difference in percent that is applied to video with
8002 \fB\-\-video\-sync=display\-...\fP (default: 1). Display sync mode will be
8003 disabled if the monitor and video refresh way do not match within the
8004 given range. It tries multiples as well: playing 30 fps video on a 60 Hz
8005 screen will duplicate every second frame. Playing 24 fps video on a 60 Hz
8006 screen will play video in a 2\-3\-2\-3\-... pattern.
8007 .sp
8008 The default settings are not loose enough to speed up 23.976 fps video to
8009 25 fps. We consider the pitch change too extreme to allow this behavior
8010 by default. Set this option to a value of \fB5\fP to enable it.
8011 .sp
8012 Note that in the \fB\-\-video\-sync=display\-resample\fP mode, audio speed will
8013 additionally be changed by a small amount if necessary for A/V sync. See
8014 \fB\-\-video\-sync\-max\-audio\-change\fP\&.
8015 .TP
8016 .B \fB\-\-video\-sync\-max\-audio\-change=<value>\fP
8017 Maximum \fIadditional\fP speed difference in percent that is applied to audio
8018 with \fB\-\-video\-sync=display\-...\fP (default: 0.125). Normally, the player
8019 plays the audio at the speed of the video. But if the difference between
8020 audio and video position is too high, e.g. due to drift or other timing
8021 errors, it will attempt to speed up or slow down audio by this additional
8022 factor. Too low values could lead to video frame dropping or repeating if
8023 the A/V desync cannot be compensated, too high values could lead to chaotic
8024 frame dropping due to the audio "overshooting" and skipping multiple video
8025 frames before the sync logic can react.
8026 .TP
8027 .B \fB\-\-video\-sync\-adrop\-size=<value>\fP
8028 For the \fB\-\-video\-sync=display\-adrop\fP mode. This mode duplicates/drops
8029 audio data to keep audio in sync with video. To avoid audio artifacts on
8030 jitter (which would add/remove samples all the time), this is done in
8031 relatively large, fixed units, controlled by this option. The unit is
8032 seconds.
8033 .TP
8034 .B \fB\-\-mf\-fps=<value>\fP
8035 Framerate used when decoding from multiple PNG or JPEG files with \fBmf://\fP
8036 (default: 1).
8037 .TP
8038 .B \fB\-\-mf\-type=<value>\fP
8039 Input file type for \fBmf://\fP (available: jpeg, png, tga, sgi). By default,
8040 this is guessed from the file extension.
8041 .TP
8042 .B \fB\-\-stream\-dump=<destination\-filename>\fP
8043 Instead of playing a file, read its byte stream and write it to the given
8044 destination file. The destination is overwritten. Can be useful to test
8045 network\-related behavior.
8046 .TP
8047 .B \fB\-\-stream\-lavf\-o=opt1=value1,opt2=value2,...\fP
8048 Set AVOptions on streams opened with libavformat. Unknown or misspelled
8049 options are silently ignored. (They are mentioned in the terminal output
8050 in verbose mode, i.e. \fB\-\-v\fP\&. In general we can\(aqt print errors, because
8051 other options such as e.g. user agent are not available with all protocols,
8052 and printing errors for unknown options would end up being too noisy.)
8053 .TP
8054 .B \fB\-\-vo\-mmcss\-profile=<name>\fP
8055 (Windows only.)
8056 Set the MMCSS profile for the video renderer thread (default: \fBPlayback\fP).
8057 .TP
8058 .B \fB\-\-priority=<prio>\fP
8059 (Windows only.)
8060 Set process priority for mpv according to the predefined priorities
8061 available under Windows.
8062 .sp
8063 Possible values of \fB<prio>\fP:
8064 idle|belownormal|normal|abovenormal|high|realtime
8065 .sp
8066 \fBWARNING:\fP
8067 .INDENT 7.0
8068 .INDENT 3.5
8069 Using realtime priority can cause system lockup.
8070 .UNINDENT
8071 .UNINDENT
8072 .TP
8073 .B \fB\-\-force\-media\-title=<string>\fP
8074 Force the contents of the \fBmedia\-title\fP property to this value. Useful
8075 for scripts which want to set a title, without overriding the user\(aqs
8076 setting in \fB\-\-title\fP\&.
8077 .TP
8078 .B \fB\-\-external\-files=<file\-list>\fP
8079 Load a file and add all of its tracks. This is useful to play different
8080 files together (for example audio from one file, video from another), or
8081 for advanced \fB\-\-lavfi\-complex\fP used (like playing two video files at
8082 the same time).
8083 .sp
8084 Unlike \fB\-\-sub\-files\fP and \fB\-\-audio\-files\fP, this includes all tracks, and
8085 does not cause default stream selection over the "proper" file. This makes
8086 it slightly less intrusive. (In mpv 0.28.0 and before, this was not quite
8087 strictly enforced.)
8088 .sp
8089 This is a list option. See \fI\%List Options\fP for details.
8090 .TP
8091 .B \fB\-\-external\-file=<file>\fP
8092 CLI/config file only alias for \fB\-\-external\-files\-append\fP\&. Each use of this
8093 option will add a new external files.
8094 .TP
8095 .B \fB\-\-autoload\-files=<yes|no>\fP
8096 Automatically load/select external files (default: yes).
8097 .sp
8098 If set to \fBno\fP, then do not automatically load external files as specified
8099 by \fB\-\-sub\-auto\fP and \fB\-\-audio\-file\-auto\fP\&. If external files are forcibly
8100 added (like with \fB\-\-sub\-files\fP), they will not be auto\-selected.
8101 .sp
8102 This does not affect playlist expansion, redirection, or other loading of
8103 referenced files like with ordered chapters.
8104 .TP
8105 .B \fB\-\-record\-file=<file>\fP
8106 Deprecated, use \fB\-\-stream\-record\fP, or the \fBdump\-cache\fP command.
8107 .sp
8108 Record the current stream to the given target file. The target file will
8109 always be overwritten without asking.
8110 .sp
8111 This was deprecated because it isn\(aqt very nice to use. For one, seeking
8112 while this is enabled will be directly reflected in the output, which was
8113 not useful and annoying.
8114 .TP
8115 .B \fB\-\-stream\-record=<file>\fP
8116 Write received/read data from the demuxer to the given output file. The
8117 output file will always be overwritten without asking. The output format
8118 is determined by the extension of the output file.
8119 .sp
8120 Switching streams or seeking during recording might result in recording
8121 being stopped and/or broken files. Use with care.
8122 .sp
8123 Seeking outside of the demuxer cache will result in "skips" in the output
8124 file, but seeking within the demuxer cache should not affect recording. One
8125 exception is when you seek back far enough to exceed the forward buffering
8126 size, in which case the cache stops actively reading. This will return in
8127 dropped data if it\(aqs a live stream.
8128 .sp
8129 If this is set at runtime, the old file is closed, and the new file is
8130 opened. Note that this will write only data that is appended at the end of
8131 the cache, and the already cached data cannot be written. You can try the
8132 \fBdump\-cache\fP command as an alternative.
8133 .sp
8134 External files (\fB\-\-audio\-file\fP etc.) are ignored by this, it works on the
8135 "main" file only. Using this with files using ordered chapters or EDL files
8136 will also not work correctly in general.
8137 .sp
8138 There are some glitches with this because it uses FFmpeg\(aqs libavformat for
8139 writing the output file. For example, it\(aqs typical that it will only work if
8140 the output format is the same as the input format. This is the case even if
8141 it works with the \fBffmpeg\fP tool. One reason for this is that \fBffmpeg\fP
8142 and its libraries contain certain hacks and workarounds for these issues,
8143 that are unavailable to outside users.
8144 .sp
8145 This replaces \fB\-\-record\-file\fP\&. It is similar to the ancient/removed
8146 \fB\-\-stream\-capture\fP/\fB\-capture\fP options, and provides better behavior in
8147 most cases (i.e. actually works).
8148 .TP
8149 .B \fB\-\-lavfi\-complex=<string>\fP
8150 Set a "complex" libavfilter filter, which means a single filter graph can
8151 take input from multiple source audio and video tracks. The graph can result
8152 in a single audio or video output (or both).
8153 .sp
8154 Currently, the filter graph labels are used to select the participating
8155 input tracks and audio/video output. The following rules apply:
8156 .INDENT 7.0
8157 .IP \(bu 2
8158 A label of the form \fBaidN\fP selects audio track N as input (e.g.
8159 \fBaid1\fP).
8160 .IP \(bu 2
8161 A label of the form \fBvidN\fP selects video track N as input.
8162 .IP \(bu 2
8163 A label named \fBao\fP will be connected to the audio output.
8164 .IP \(bu 2
8165 A label named \fBvo\fP will be connected to the video output.
8166 .UNINDENT
8167 .sp
8168 Each label can be used only once. If you want to use e.g. an audio stream
8169 for multiple filters, you need to use the \fBasplit\fP filter. Multiple
8170 video or audio outputs are not possible, but you can use filters to merge
8171 them into one.
8172 .sp
8173 It\(aqs not possible to change the tracks connected to the filter at runtime,
8174 unless you explicitly change the \fBlavfi\-complex\fP property and set new
8175 track assignments. When the graph is changed, the track selection is changed
8176 according to the used labels as well.
8177 .sp
8178 Other tracks, as long as they\(aqre not connected to the filter, and the
8179 corresponding output is not connected to the filter, can still be freely
8180 changed with the normal methods.
8181 .sp
8182 Note that the normal filter chains (\fB\-\-af\fP, \fB\-\-vf\fP) are applied between
8183 the complex graphs (e.g. \fBao\fP label) and the actual output.
8184 .INDENT 7.0
8185 .INDENT 3.5
8186 .IP "Examples"
8187 .INDENT 0.0
8188 .IP \(bu 2
8189 \fB\-\-lavfi\-complex=\(aq[aid1] [aid2] amix [ao]\(aq\fP
8190 Play audio track 1 and 2 at the same time.
8191 .IP \(bu 2
8192 \fB\-\-lavfi\-complex=\(aq[vid1] [vid2] vstack [vo]\(aq\fP
8193 Stack video track 1 and 2 and play them at the same time. Note that
8194 both tracks need to have the same width, or filter initialization
8195 will fail (you can add \fBscale\fP filters before the \fBvstack\fP filter
8196 to fix the size).
8197 To load a video track from another file, you can use
8198 \fB\-\-external\-file=other.mkv\fP\&.
8199 .IP \(bu 2
8200 \fB\-\-lavfi\-complex=\(aq[aid1] asplit [t1] [ao] ; [t1] showvolume [t2] ; [vid1] [t2] overlay [vo]\(aq\fP
8201 Play audio track 1, and overlay the measured volume for each speaker
8202 over video track 1.
8203 .IP \(bu 2
8204 \fBnull:// \-\-lavfi\-complex=\(aqlife [vo]\(aq\fP
8205 A libavfilter source\-only filter (Conways\(aq Life Game).
8206 .UNINDENT
8207 .UNINDENT
8208 .UNINDENT
8209 .sp
8210 See the FFmpeg libavfilter documentation for details on the available
8211 filters.
8212 .UNINDENT
8213 .SH AUDIO OUTPUT DRIVERS
8214 .sp
8215 Audio output drivers are interfaces to different audio output facilities. The
8216 syntax is:
8217 .INDENT 0.0
8218 .TP
8219 .B \fB\-\-ao=<driver1,driver2,...[,]>\fP
8220 Specify a priority list of audio output drivers to be used.
8221 .UNINDENT
8222 .sp
8223 If the list has a trailing \(aq,\(aq, mpv will fall back on drivers not contained
8224 in the list.
8225 .sp
8226 \fBNOTE:\fP
8227 .INDENT 0.0
8228 .INDENT 3.5
8229 See \fB\-\-ao=help\fP for a list of compiled\-in audio output drivers. The
8230 driver \fB\-\-ao=alsa\fP is preferred. \fB\-\-ao=pulse\fP is preferred on systems
8231 where PulseAudio is used. On BSD systems, \fB\-\-ao=oss\fP or \fB\-\-ao=sndio\fP
8232 may work (the latter being experimental).
8233 .UNINDENT
8234 .UNINDENT
8235 .sp
8236 Available audio output drivers are:
8237 .INDENT 0.0
8238 .TP
8239 .B \fBalsa\fP (Linux only)
8240 ALSA audio output driver
8241 .sp
8242 See \fI\%ALSA audio output options\fP for options specific to this AO.
8243 .sp
8244 \fBWARNING:\fP
8245 .INDENT 7.0
8246 .INDENT 3.5
8247 To get multichannel/surround audio, use \fB\-\-audio\-channels=auto\fP\&. The
8248 default for this option is \fBauto\-safe\fP, which makes this audio output
8249 explicitly reject multichannel output, as there is no way to detect
8250 whether a certain channel layout is actually supported.
8251 .sp
8252 You can also try \fI\%using the upmix plugin\fP\&.
8253 This setup enables multichannel audio on the \fBdefault\fP device
8254 with automatic upmixing with shared access, so playing stereo
8255 and multichannel audio at the same time will work as expected.
8256 .UNINDENT
8257 .UNINDENT
8258 .TP
8259 .B \fBoss\fP
8260 OSS audio output driver
8261 .sp
8262 The following global options are supported by this audio output:
8263 .INDENT 7.0
8264 .TP
8265 .B \fB\-\-oss\-mixer\-device\fP
8266 Sets the audio mixer device (default: \fB/dev/mixer\fP).
8267 .TP
8268 .B \fB\-\-oss\-mixer\-channel\fP
8269 Sets the audio mixer channel (default: \fBpcm\fP). Other valid values
8270 include \fBvol, pcm, line\fP\&. For a complete list of options look for
8271 \fBSOUND_DEVICE_NAMES\fP in \fB/usr/include/linux/soundcard.h\fP\&.
8272 .UNINDENT
8273 .TP
8274 .B \fBjack\fP
8275 JACK (Jack Audio Connection Kit) audio output driver.
8276 .sp
8277 The following global options are supported by this audio output:
8278 .INDENT 7.0
8279 .TP
8280 .B \fB\-\-jack\-port=<name>\fP
8281 Connects to the ports with the given name (default: physical ports).
8282 .TP
8283 .B \fB\-\-jack\-name=<client>\fP
8284 Client name that is passed to JACK (default: \fBmpv\fP). Useful
8285 if you want to have certain connections established automatically.
8286 .TP
8287 .B \fB\-\-jack\-autostart=<yes|no>\fP
8288 Automatically start jackd if necessary (default: disabled). Note that
8289 this tends to be unreliable and will flood stdout with server messages.
8290 .TP
8291 .B \fB\-\-jack\-connect=<yes|no>\fP
8292 Automatically create connections to output ports (default: enabled).
8293 When enabled, the maximum number of output channels will be limited to
8294 the number of available output ports.
8295 .TP
8296 .B \fB\-\-jack\-std\-channel\-layout=<waveext|any>\fP
8297 Select the standard channel layout (default: waveext). JACK itself has no
8298 notion of channel layouts (i.e. assigning which speaker a given
8299 channel is supposed to map to) \- it just takes whatever the application
8300 outputs, and reroutes it to whatever the user defines. This means the
8301 user and the application are in charge of dealing with the channel
8302 layout. \fBwaveext\fP uses WAVE_FORMAT_EXTENSIBLE order, which, even
8303 though it was defined by Microsoft, is the standard on many systems.
8304 The value \fBany\fP makes JACK accept whatever comes from the audio
8305 filter chain, regardless of channel layout and without reordering. This
8306 mode is probably not very useful, other than for debugging or when used
8307 with fixed setups.
8308 .UNINDENT
8309 .TP
8310 .B \fBcoreaudio\fP (Mac OS X only)
8311 Native Mac OS X audio output driver using AudioUnits and the CoreAudio
8312 sound server.
8313 .sp
8314 Automatically redirects to \fBcoreaudio_exclusive\fP when playing compressed
8315 formats.
8316 .sp
8317 The following global options are supported by this audio output:
8318 .INDENT 7.0
8319 .TP
8320 .B \fB\-\-coreaudio\-change\-physical\-format=<yes|no>\fP
8321 Change the physical format to one similar to the requested audio format
8322 (default: no). This has the advantage that multichannel audio output
8323 will actually work. The disadvantage is that it will change the
8324 system\-wide audio settings. This is equivalent to changing the \fBFormat\fP
8325 setting in the \fBAudio Devices\fP dialog in the \fBAudio MIDI Setup\fP
8326 utility. Note that this does not affect the selected speaker setup.
8327 .TP
8328 .B \fB\-\-coreaudio\-spdif\-hack=<yes|no>\fP
8329 Try to pass through AC3/DTS data as PCM. This is useful for drivers
8330 which do not report AC3 support. It converts the AC3 data to float,
8331 and assumes the driver will do the inverse conversion, which means
8332 a typical A/V receiver will pick it up as compressed IEC framed AC3
8333 stream, ignoring that it\(aqs marked as PCM. This disables normal AC3
8334 passthrough (even if the device reports it as supported). Use with
8335 extreme care.
8336 .UNINDENT
8337 .TP
8338 .B \fBcoreaudio_exclusive\fP (Mac OS X only)
8339 Native Mac OS X audio output driver using direct device access and
8340 exclusive mode (bypasses the sound server).
8341 .TP
8342 .B \fBopenal\fP
8343 OpenAL audio output driver
8344 .INDENT 7.0
8345 .TP
8346 .B \fB\-\-openal\-num\-buffers=<2\-128>\fP
8347 Specify the number of audio buffers to use. Lower values are better for
8348 lower CPU usage. Default: 4.
8349 .TP
8350 .B \fB\-\-openal\-num\-samples=<256\-32768>\fP
8351 Specify the number of complete samples to use for each buffer. Higher
8352 values are better for lower CPU usage. Default: 8192.
8353 .TP
8354 .B \fB\-\-openal\-direct\-channels=<yes|no>\fP
8355 Enable OpenAL Soft\(aqs direct channel extension when available to avoid
8356 tinting the sound with ambisonics or HRTF.
8357 Channels are dropped when when they are not available as downmixing
8358 will be disabled. Default: no.
8359 .UNINDENT
8360 .TP
8361 .B \fBpulse\fP
8362 PulseAudio audio output driver
8363 .sp
8364 The following global options are supported by this audio output:
8365 .INDENT 7.0
8366 .TP
8367 .B \fB\-\-pulse\-host=<host>\fP
8368 Specify the host to use. An empty <host> string uses a local connection,
8369 "localhost" uses network transfer (most likely not what you want).
8370 .TP
8371 .B \fB\-\-pulse\-buffer=<1\-2000|native>\fP
8372 Set the audio buffer size in milliseconds. A higher value buffers
8373 more data, and has a lower probability of buffer underruns. A smaller
8374 value makes the audio stream react faster, e.g. to playback speed
8375 changes.
8376 .TP
8377 .B \fB\-\-pulse\-latency\-hacks=<yes|no>\fP
8378 Enable hacks to workaround PulseAudio timing bugs (default: no). If
8379 enabled, mpv will do elaborate latency calculations on its own. If
8380 disabled, it will use PulseAudio automatically updated timing
8381 information. Disabling this might help with e.g. networked audio or
8382 some plugins, while enabling it might help in some unknown situations
8383 (it used to be required to get good behavior on old PulseAudio versions).
8384 .sp
8385 If you have stuttering video when using pulse, try to enable this
8386 option. (Or try to update PulseAudio.)
8387 .TP
8388 .B \fB\-\-pulse\-allow\-suspended=<yes|no>\fP
8389 Allow mpv to use PulseAudio even if the sink is suspended (default: no).
8390 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.
8391 .UNINDENT
8392 .TP
8393 .B \fBsdl\fP
8394 SDL 1.2+ audio output driver. Should work on any platform supported by SDL
8395 1.2, but may require the \fBSDL_AUDIODRIVER\fP environment variable to be set
8396 appropriately for your system.
8397 .sp
8398 \fBNOTE:\fP
8399 .INDENT 7.0
8400 .INDENT 3.5
8401 This driver is for compatibility with extremely foreign
8402 environments, such as systems where none of the other drivers
8403 are available.
8404 .UNINDENT
8405 .UNINDENT
8406 .sp
8407 The following global options are supported by this audio output:
8408 .INDENT 7.0
8409 .TP
8410 .B \fB\-\-sdl\-buflen=<length>\fP
8411 Sets the audio buffer length in seconds. Is used only as a hint by the
8412 sound system. Playing a file with \fB\-v\fP will show the requested and
8413 obtained exact buffer size. A value of 0 selects the sound system
8414 default.
8415 .TP
8416 .B \fB\-\-sdl\-bufcnt=<count>\fP
8417 Sets the number of extra audio buffers in mpv. Usually needs not be
8418 changed.
8419 .UNINDENT
8420 .TP
8421 .B \fBnull\fP
8422 Produces no audio output but maintains video playback speed. You can use
8423 \fB\-\-ao=null \-\-ao\-null\-untimed\fP for benchmarking.
8424 .sp
8425 The following global options are supported by this audio output:
8426 .INDENT 7.0
8427 .TP
8428 .B \fB\-\-ao\-null\-untimed\fP
8429 Do not simulate timing of a perfect audio device. This means audio
8430 decoding will go as fast as possible, instead of timing it to the
8431 system clock.
8432 .TP
8433 .B \fB\-\-ao\-null\-buffer\fP
8434 Simulated buffer length in seconds.
8435 .TP
8436 .B \fB\-\-ao\-null\-outburst\fP
8437 Simulated chunk size in samples.
8438 .TP
8439 .B \fB\-\-ao\-null\-speed\fP
8440 Simulated audio playback speed as a multiplier. Usually, a real audio
8441 device will not go exactly as fast as the system clock. It will deviate
8442 just a little, and this option helps to simulate this.
8443 .TP
8444 .B \fB\-\-ao\-null\-latency\fP
8445 Simulated device latency. This is additional to EOF.
8446 .TP
8447 .B \fB\-\-ao\-null\-broken\-eof\fP
8448 Simulate broken audio drivers, which always add the fixed device
8449 latency to the reported audio playback position.
8450 .TP
8451 .B \fB\-\-ao\-null\-broken\-delay\fP
8452 Simulate broken audio drivers, which don\(aqt report latency correctly.
8453 .TP
8454 .B \fB\-\-ao\-null\-channel\-layouts\fP
8455 If not empty, this is a \fB,\fP separated list of channel layouts the
8456 AO allows. This can be used to test channel layout selection.
8457 .TP
8458 .B \fB\-\-ao\-null\-format\fP
8459 Force the audio output format the AO will accept. If unset accepts any.
8460 .UNINDENT
8461 .TP
8462 .B \fBpcm\fP
8463 Raw PCM/WAVE file writer audio output
8464 .sp
8465 The following global options are supported by this audio output:
8466 .INDENT 7.0
8467 .TP
8468 .B \fB\-\-ao\-pcm\-waveheader=<yes|no>\fP
8469 Include or do not include the WAVE header (default: included). When
8470 not included, raw PCM will be generated.
8471 .TP
8472 .B \fB\-\-ao\-pcm\-file=<filename>\fP
8473 Write the sound to \fB<filename>\fP instead of the default
8474 \fBaudiodump.wav\fP\&. If \fBno\-waveheader\fP is specified, the default is
8475 \fBaudiodump.pcm\fP\&.
8476 .TP
8477 .B \fB\-\-ao\-pcm\-append=<yes|no>\fP
8478 Append to the file, instead of overwriting it. Always use this with the
8479 \fBno\-waveheader\fP option \- with \fBwaveheader\fP it\(aqs broken, because
8480 it will write a WAVE header every time the file is opened.
8481 .UNINDENT
8482 .TP
8483 .B \fBrsound\fP
8484 Audio output to an RSound daemon. Use \fB\-\-audio\-device=rsound/<hostname>\fP
8485 to set the host name (with \fB<hostname>\fP replaced, without the \fB< >\fP).
8486 .sp
8487 \fBNOTE:\fP
8488 .INDENT 7.0
8489 .INDENT 3.5
8490 Completely useless, unless you intend to run RSound. Not to be
8491 confused with RoarAudio, which is something completely
8492 different.
8493 .UNINDENT
8494 .UNINDENT
8495 .TP
8496 .B \fBsndio\fP
8497 Audio output to the OpenBSD sndio sound system
8498 .sp
8499 \fBNOTE:\fP
8500 .INDENT 7.0
8501 .INDENT 3.5
8502 Experimental. There are known bugs and issues.
8503 .UNINDENT
8504 .UNINDENT
8505 .sp
8506 (Note: only supports mono, stereo, 4.0, 5.1 and 7.1 channel
8507 layouts.)
8508 .TP
8509 .B \fBwasapi\fP
8510 Audio output to the Windows Audio Session API.
8511 .UNINDENT
8512 .SH VIDEO OUTPUT DRIVERS
8513 .sp
8514 Video output drivers are interfaces to different video output facilities. The
8515 syntax is:
8516 .INDENT 0.0
8517 .TP
8518 .B \fB\-\-vo=<driver1,driver2,...[,]>\fP
8519 Specify a priority list of video output drivers to be used.
8520 .UNINDENT
8521 .sp
8522 If the list has a trailing \fB,\fP, mpv will fall back on drivers not contained
8523 in the list.
8524 .sp
8525 \fBNOTE:\fP
8526 .INDENT 0.0
8527 .INDENT 3.5
8528 See \fB\-\-vo=help\fP for a list of compiled\-in video output drivers.
8529 .sp
8530 The recommended output driver is \fB\-\-vo=gpu\fP, which is the default. All
8531 other drivers are for compatibility or special purposes. If the default
8532 does not work, it will fallback to other drivers (in the same order as
8533 listed by \fB\-\-vo=help\fP).
8534 .UNINDENT
8535 .UNINDENT
8536 .sp
8537 Available video output drivers are:
8538 .INDENT 0.0
8539 .TP
8540 .B \fBxv\fP (X11 only)
8541 Uses the XVideo extension to enable hardware\-accelerated display. This is
8542 the most compatible VO on X, but may be low\-quality, and has issues with
8543 OSD and subtitle display.
8544 .sp
8545 \fBNOTE:\fP
8546 .INDENT 7.0
8547 .INDENT 3.5
8548 This driver is for compatibility with old systems.
8549 .UNINDENT
8550 .UNINDENT
8551 .sp
8552 The following global options are supported by this video output:
8553 .INDENT 7.0
8554 .TP
8555 .B \fB\-\-xv\-adaptor=<number>\fP
8556 Select a specific XVideo adapter (check xvinfo results).
8557 .TP
8558 .B \fB\-\-xv\-port=<number>\fP
8559 Select a specific XVideo port.
8560 .TP
8561 .B \fB\-\-xv\-ck=<cur|use|set>\fP
8562 Select the source from which the color key is taken (default: cur).
8563 .INDENT 7.0
8564 .TP
8565 .B cur
8566 The default takes the color key currently set in Xv.
8567 .TP
8568 .B use
8569 Use but do not set the color key from mpv (use the \fB\-\-colorkey\fP
8570 option to change it).
8571 .TP
8572 .B set
8573 Same as use but also sets the supplied color key.
8574 .UNINDENT
8575 .TP
8576 .B \fB\-\-xv\-ck\-method=<none|man|bg|auto>\fP
8577 Sets the color key drawing method (default: man).
8578 .INDENT 7.0
8579 .TP
8580 .B none
8581 Disables color\-keying.
8582 .TP
8583 .B man
8584 Draw the color key manually (reduces flicker in some cases).
8585 .TP
8586 .B bg
8587 Set the color key as window background.
8588 .TP
8589 .B auto
8590 Let Xv draw the color key.
8591 .UNINDENT
8592 .TP
8593 .B \fB\-\-xv\-colorkey=<number>\fP
8594 Changes the color key to an RGB value of your choice. \fB0x000000\fP is
8595 black and \fB0xffffff\fP is white.
8596 .TP
8597 .B \fB\-\-xv\-buffers=<number>\fP
8598 Number of image buffers to use for the internal ringbuffer (default: 2).
8599 Increasing this will use more memory, but might help with the X server
8600 not responding quickly enough if video FPS is close to or higher than
8601 the display refresh rate.
8602 .UNINDENT
8603 .TP
8604 .B \fBx11\fP (X11 only)
8605 Shared memory video output driver without hardware acceleration that works
8606 whenever X11 is present.
8607 .sp
8608 \fBNOTE:\fP
8609 .INDENT 7.0
8610 .INDENT 3.5
8611 This is a fallback only, and should not be normally used.
8612 .UNINDENT
8613 .UNINDENT
8614 .TP
8615 .B \fBvdpau\fP (X11 only)
8616 Uses the VDPAU interface to display and optionally also decode video.
8617 Hardware decoding is used with \fB\-\-hwdec=vdpau\fP\&.
8618 .sp
8619 \fBNOTE:\fP
8620 .INDENT 7.0
8621 .INDENT 3.5
8622 Earlier versions of mpv (and MPlayer, mplayer2) provided sub\-options
8623 to tune vdpau post\-processing, like \fBdeint\fP, \fBsharpen\fP, \fBdenoise\fP,
8624 \fBchroma\-deint\fP, \fBpullup\fP, \fBhqscaling\fP\&. These sub\-options are
8625 deprecated, and you should use the \fBvdpaupp\fP video filter instead.
8626 .UNINDENT
8627 .UNINDENT
8628 .sp
8629 The following global options are supported by this video output:
8630 .INDENT 7.0
8631 .TP
8632 .B \fB\-\-vo\-vdpau\-sharpen=<\-1\-1>\fP
8633 (Deprecated. See note about \fBvdpaupp\fP\&.)
8634 .sp
8635 For positive values, apply a sharpening algorithm to the video, for
8636 negative values a blurring algorithm (default: 0).
8637 .TP
8638 .B \fB\-\-vo\-vdpau\-denoise=<0\-1>\fP
8639 (Deprecated. See note about \fBvdpaupp\fP\&.)
8640 .sp
8641 Apply a noise reduction algorithm to the video (default: 0; no noise
8642 reduction).
8643 .TP
8644 .B \fB\-\-vo\-vdpau\-deint=<\-4\-4>\fP
8645 (Deprecated. See note about \fBvdpaupp\fP\&.)
8646 .sp
8647 Select deinterlacing mode (default: 0). In older versions (as well as
8648 MPlayer/mplayer2) you could use this option to enable deinterlacing.
8649 This doesn\(aqt work anymore, and deinterlacing is enabled with either
8650 the \fBd\fP key (by default mapped to the command \fBcycle deinterlace\fP),
8651 or the \fB\-\-deinterlace\fP option. Also, to select the default deint mode,
8652 you should use something like \fB\-\-vf\-defaults=vdpaupp:deint\-mode=temporal\fP
8653 instead of this sub\-option.
8654 .INDENT 7.0
8655 .TP
8656 .B 0
8657 Pick the \fBvdpaupp\fP video filter default, which corresponds to 3.
8658 .TP
8659 .B 1
8660 Show only first field.
8661 .TP
8662 .B 2
8663 Bob deinterlacing.
8664 .TP
8665 .B 3
8666 Motion\-adaptive temporal deinterlacing. May lead to A/V desync
8667 with slow video hardware and/or high resolution.
8668 .TP
8669 .B 4
8670 Motion\-adaptive temporal deinterlacing with edge\-guided spatial
8671 interpolation. Needs fast video hardware.
8672 .UNINDENT
8673 .TP
8674 .B \fB\-\-vo\-vdpau\-chroma\-deint\fP
8675 (Deprecated. See note about \fBvdpaupp\fP\&.)
8676 .sp
8677 Makes temporal deinterlacers operate both on luma and chroma (default).
8678 Use no\-chroma\-deint to solely use luma and speed up advanced
8679 deinterlacing. Useful with slow video memory.
8680 .TP
8681 .B \fB\-\-vo\-vdpau\-pullup\fP
8682 (Deprecated. See note about \fBvdpaupp\fP\&.)
8683 .sp
8684 Try to apply inverse telecine, needs motion adaptive temporal
8685 deinterlacing.
8686 .TP
8687 .B \fB\-\-vo\-vdpau\-hqscaling=<0\-9>\fP
8688 (Deprecated. See note about \fBvdpaupp\fP\&.)
8689 .INDENT 7.0
8690 .TP
8691 .B 0
8692 Use default VDPAU scaling (default).
8693 .TP
8694 .B 1\-9
8695 Apply high quality VDPAU scaling (needs capable hardware).
8696 .UNINDENT
8697 .TP
8698 .B \fB\-\-vo\-vdpau\-fps=<number>\fP
8699 Override autodetected display refresh rate value (the value is needed
8700 for framedrop to allow video playback rates higher than display
8701 refresh rate, and for vsync\-aware frame timing adjustments). Default 0
8702 means use autodetected value. A positive value is interpreted as a
8703 refresh rate in Hz and overrides the autodetected value. A negative
8704 value disables all timing adjustment and framedrop logic.
8705 .TP
8706 .B \fB\-\-vo\-vdpau\-composite\-detect\fP
8707 NVIDIA\(aqs current VDPAU implementation behaves somewhat differently
8708 under a compositing window manager and does not give accurate frame
8709 timing information. With this option enabled, the player tries to
8710 detect whether a compositing window manager is active. If one is
8711 detected, the player disables timing adjustments as if the user had
8712 specified \fBfps=\-1\fP (as they would be based on incorrect input). This
8713 means timing is somewhat less accurate than without compositing, but
8714 with the composited mode behavior of the NVIDIA driver, there is no
8715 hard playback speed limit even without the disabled logic. Enabled by
8716 default, use \fB\-\-vo\-vdpau\-composite\-detect=no\fP to disable.
8717 .TP
8718 .B \fB\-\-vo\-vdpau\-queuetime\-windowed=<number>\fP and \fBqueuetime\-fs=<number>\fP
8719 Use VDPAU\(aqs presentation queue functionality to queue future video
8720 frame changes at most this many milliseconds in advance (default: 50).
8721 See below for additional information.
8722 .TP
8723 .B \fB\-\-vo\-vdpau\-output\-surfaces=<2\-15>\fP
8724 Allocate this many output surfaces to display video frames (default:
8725 3). See below for additional information.
8726 .TP
8727 .B \fB\-\-vo\-vdpau\-colorkey=<#RRGGBB|#AARRGGBB>\fP
8728 Set the VDPAU presentation queue background color, which in practice
8729 is the colorkey used if VDPAU operates in overlay mode (default:
8730 \fB#020507\fP, some shade of black). If the alpha component of this value
8731 is 0, the default VDPAU colorkey will be used instead (which is usually
8732 green).
8733 .TP
8734 .B \fB\-\-vo\-vdpau\-force\-yuv\fP
8735 Never accept RGBA input. This means mpv will insert a filter to convert
8736 to a YUV format before the VO. Sometimes useful to force availability
8737 of certain YUV\-only features, like video equalizer or deinterlacing.
8738 .UNINDENT
8739 .sp
8740 Using the VDPAU frame queuing functionality controlled by the queuetime
8741 options makes mpv\(aqs frame flip timing less sensitive to system CPU load and
8742 allows mpv to start decoding the next frame(s) slightly earlier, which can
8743 reduce jitter caused by individual slow\-to\-decode frames. However, the
8744 NVIDIA graphics drivers can make other window behavior such as window moves
8745 choppy if VDPAU is using the blit queue (mainly happens if you have the
8746 composite extension enabled) and this feature is active. If this happens on
8747 your system and it bothers you then you can set the queuetime value to 0 to
8748 disable this feature. The settings to use in windowed and fullscreen mode
8749 are separate because there should be no reason to disable this for
8750 fullscreen mode (as the driver issue should not affect the video itself).
8751 .sp
8752 You can queue more frames ahead by increasing the queuetime values and the
8753 \fBoutput_surfaces\fP count (to ensure enough surfaces to buffer video for a
8754 certain time ahead you need at least as many surfaces as the video has
8755 frames during that time, plus two). This could help make video smoother in
8756 some cases. The main downsides are increased video RAM requirements for
8757 the surfaces and laggier display response to user commands (display
8758 changes only become visible some time after they\(aqre queued). The graphics
8759 driver implementation may also have limits on the length of maximum
8760 queuing time or number of queued surfaces that work well or at all.
8761 .TP
8762 .B \fBdirect3d\fP (Windows only)
8763 Video output driver that uses the Direct3D interface.
8764 .sp
8765 \fBNOTE:\fP
8766 .INDENT 7.0
8767 .INDENT 3.5
8768 This driver is for compatibility with systems that don\(aqt provide
8769 proper OpenGL drivers, and where ANGLE does not perform well.
8770 .UNINDENT
8771 .UNINDENT
8772 .sp
8773 \fBNOTE:\fP
8774 .INDENT 7.0
8775 .INDENT 3.5
8776 Before to 0.21.0, \fBdirect3d_shaders\fP and \fBdirect3d\fP were
8777 different, with \fBdirect3d\fP not using shader by default. Now
8778 both use shaders by default, and \fBdirect3d_shaders\fP is a
8779 deprecated alias. Use the \fB\-\-vo\-direct3d\-prefer\-stretchrect\fP
8780 or the \fB\-\-vo\-direct3d\-disable\-shaders\fP options to get the old
8781 behavior of \fBdirect3d\fP\&.
8782 .UNINDENT
8783 .UNINDENT
8784 .sp
8785 The following global options are supported by this video output:
8786 .INDENT 7.0
8787 .TP
8788 .B \fB\-\-vo\-direct3d\-prefer\-stretchrect\fP
8789 Use \fBIDirect3DDevice9::StretchRect\fP over other methods if possible.
8790 .TP
8791 .B \fB\-\-vo\-direct3d\-disable\-stretchrect\fP
8792 Never render the video using \fBIDirect3DDevice9::StretchRect\fP\&.
8793 .TP
8794 .B \fB\-\-vo\-direct3d\-disable\-textures\fP
8795 Never render the video using D3D texture rendering. Rendering with
8796 textures + shader will still be allowed. Add \fBdisable\-shaders\fP to
8797 completely disable video rendering with textures.
8798 .TP
8799 .B \fB\-\-vo\-direct3d\-disable\-shaders\fP
8800 Never use shaders when rendering video.
8801 .TP
8802 .B \fB\-\-vo\-direct3d\-only\-8bit\fP
8803 Never render YUV video with more than 8 bits per component.
8804 Using this flag will force software conversion to 8\-bit.
8805 .TP
8806 .B \fB\-\-vo\-direct3d\-disable\-texture\-align\fP
8807 Normally texture sizes are always aligned to 16. With this option
8808 enabled, the video texture will always have exactly the same size as
8809 the video itself.
8810 .UNINDENT
8811 .sp
8812 Debug options. These might be incorrect, might be removed in the future,
8813 might crash, might cause slow downs, etc. Contact the developers if you
8814 actually need any of these for performance or proper operation.
8815 .INDENT 7.0
8816 .TP
8817 .B \fB\-\-vo\-direct3d\-force\-power\-of\-2\fP
8818 Always force textures to power of 2, even if the device reports
8819 non\-power\-of\-2 texture sizes as supported.
8820 .TP
8821 .B \fB\-\-vo\-direct3d\-texture\-memory=<mode>\fP
8822 Only affects operation with shaders/texturing enabled, and (E)OSD.
8823 Possible values:
8824 .INDENT 7.0
8825 .TP
8826 .B \fBdefault\fP (default)
8827 Use \fBD3DPOOL_DEFAULT\fP, with a \fBD3DPOOL_SYSTEMMEM\fP texture for
8828 locking. If the driver supports \fBD3DDEVCAPS_TEXTURESYSTEMMEMORY\fP,
8829 \fBD3DPOOL_SYSTEMMEM\fP is used directly.
8830 .TP
8831 .B \fBdefault\-pool\fP
8832 Use \fBD3DPOOL_DEFAULT\fP\&. (Like \fBdefault\fP, but never use a
8833 shadow\-texture.)
8834 .TP
8835 .B \fBdefault\-pool\-shadow\fP
8836 Use \fBD3DPOOL_DEFAULT\fP, with a \fBD3DPOOL_SYSTEMMEM\fP texture for
8837 locking. (Like \fBdefault\fP, but always force the shadow\-texture.)
8838 .TP
8839 .B \fBmanaged\fP
8840 Use \fBD3DPOOL_MANAGED\fP\&.
8841 .TP
8842 .B \fBscratch\fP
8843 Use \fBD3DPOOL_SCRATCH\fP, with a \fBD3DPOOL_SYSTEMMEM\fP texture for
8844 locking.
8845 .UNINDENT
8846 .TP
8847 .B \fB\-\-vo\-direct3d\-swap\-discard\fP
8848 Use \fBD3DSWAPEFFECT_DISCARD\fP, which might be faster.
8849 Might be slower too, as it must(?) clear every frame.
8850 .TP
8851 .B \fB\-\-vo\-direct3d\-exact\-backbuffer\fP
8852 Always resize the backbuffer to window size.
8853 .UNINDENT
8854 .TP
8855 .B \fBgpu\fP
8856 General purpose, customizable, GPU\-accelerated video output driver. It
8857 supports extended scaling methods, dithering, color management, custom
8858 shaders, HDR, and more.
8859 .sp
8860 See \fI\%GPU renderer options\fP for options specific to this VO.
8861 .sp
8862 By default, it tries to use fast and fail\-safe settings. Use the
8863 \fBgpu\-hq\fP profile to use this driver with defaults set to high quality
8864 rendering. The profile can be applied with \fB\-\-profile=gpu\-hq\fP and its
8865 contents can be viewed with \fB\-\-show\-profile=gpu\-hq\fP\&.
8866 .sp
8867 This VO abstracts over several possible graphics APIs and windowing
8868 contexts, which can be influenced using the \fB\-\-gpu\-api\fP and
8869 \fB\-\-gpu\-context\fP options.
8870 .sp
8871 Hardware decoding over OpenGL\-interop is supported to some degree. Note
8872 that in this mode, some corner case might not be gracefully handled, and
8873 color space conversion and chroma upsampling is generally in the hand of
8874 the hardware decoder APIs.
8875 .sp
8876 \fBgpu\fP makes use of FBOs by default. Sometimes you can achieve better
8877 quality or performance by changing the \fB\-\-gpu\-fbo\-format\fP option to
8878 \fBrgb16f\fP, \fBrgb32f\fP or \fBrgb\fP\&. Known problems include Mesa/Intel not
8879 accepting \fBrgb16\fP, Mesa sometimes not being compiled with float texture
8880 support, and some OS X setups being very slow with \fBrgb16\fP but fast
8881 with \fBrgb32f\fP\&. If you have problems, you can also try enabling the
8882 \fB\-\-gpu\-dumb\-mode=yes\fP option.
8883 .TP
8884 .B \fBsdl\fP
8885 SDL 2.0+ Render video output driver, depending on system with or without
8886 hardware acceleration. Should work on all platforms supported by SDL 2.0.
8887 For tuning, refer to your copy of the file \fBSDL_hints.h\fP\&.
8888 .sp
8889 \fBNOTE:\fP
8890 .INDENT 7.0
8891 .INDENT 3.5
8892 This driver is for compatibility with systems that don\(aqt provide
8893 proper graphics drivers.
8894 .UNINDENT
8895 .UNINDENT
8896 .sp
8897 The following global options are supported by this video output:
8898 .INDENT 7.0
8899 .TP
8900 .B \fB\-\-sdl\-sw\fP
8901 Continue even if a software renderer is detected.
8902 .TP
8903 .B \fB\-\-sdl\-switch\-mode\fP
8904 Instruct SDL to switch the monitor video mode when going fullscreen.
8905 .UNINDENT
8906 .TP
8907 .B \fBvaapi\fP
8908 Intel VA API video output driver with support for hardware decoding. Note
8909 that there is absolutely no reason to use this, other than compatibility.
8910 This is low quality, and has issues with OSD.
8911 .sp
8912 \fBNOTE:\fP
8913 .INDENT 7.0
8914 .INDENT 3.5
8915 This driver is for compatibility with crappy systems. You can
8916 use vaapi hardware decoding with \fB\-\-vo=gpu\fP too.
8917 .UNINDENT
8918 .UNINDENT
8919 .sp
8920 The following global options are supported by this video output:
8921 .INDENT 7.0
8922 .TP
8923 .B \fB\-\-vo\-vaapi\-scaling=<algorithm>\fP
8924 .INDENT 7.0
8925 .TP
8926 .B default
8927 Driver default (mpv default as well).
8928 .TP
8929 .B fast
8930 Fast, but low quality.
8931 .TP
8932 .B hq
8933 Unspecified driver dependent high\-quality scaling, slow.
8934 .TP
8935 .B nla
8936 \fBnon\-linear anamorphic scaling\fP
8937 .UNINDENT
8938 .TP
8939 .B \fB\-\-vo\-vaapi\-deint\-mode=<mode>\fP
8940 Select deinterlacing algorithm. Note that by default deinterlacing is
8941 initially always off, and needs to be enabled with the \fBd\fP key
8942 (default key binding for \fBcycle deinterlace\fP).
8943 .sp
8944 This option doesn\(aqt apply if libva supports video post processing (vpp).
8945 In this case, the default for \fBdeint\-mode\fP is \fBno\fP, and enabling
8946 deinterlacing via user interaction using the methods mentioned above
8947 actually inserts the \fBvavpp\fP video filter. If vpp is not actually
8948 supported with the libva backend in use, you can use this option to
8949 forcibly enable VO based deinterlacing.
8950 .INDENT 7.0
8951 .TP
8952 .B no
8953 Don\(aqt allow deinterlacing (default for newer libva).
8954 .TP
8955 .B first\-field
8956 Show only first field.
8957 .TP
8958 .B bob
8959 bob deinterlacing (default for older libva).
8960 .UNINDENT
8961 .TP
8962 .B \fB\-\-vo\-vaapi\-scaled\-osd=<yes|no>\fP
8963 If enabled, then the OSD is rendered at video resolution and scaled to
8964 display resolution. By default, this is disabled, and the OSD is
8965 rendered at display resolution if the driver supports it.
8966 .UNINDENT
8967 .TP
8968 .B \fBnull\fP
8969 Produces no video output. Useful for benchmarking.
8970 .sp
8971 Usually, it\(aqs better to disable video with \fB\-\-no\-video\fP instead.
8972 .sp
8973 The following global options are supported by this video output:
8974 .INDENT 7.0
8975 .TP
8976 .B \fB\-\-vo\-null\-fps=<value>\fP
8977 Simulate display FPS. This artificially limits how many frames the
8978 VO accepts per second.
8979 .UNINDENT
8980 .TP
8981 .B \fBcaca\fP
8982 Color ASCII art video output driver that works on a text console.
8983 .sp
8984 \fBNOTE:\fP
8985 .INDENT 7.0
8986 .INDENT 3.5
8987 This driver is a joke.
8988 .UNINDENT
8989 .UNINDENT
8990 .TP
8991 .B \fBtct\fP
8992 Color Unicode art video output driver that works on a text console.
8993 Depends on support of true color by modern terminals to display the images
8994 at full color range. On Windows it requires an ansi terminal such as mintty.
8995 .INDENT 7.0
8996 .TP
8997 .B \fB\-\-vo\-tct\-algo=<algo>\fP
8998 Select how to write the pixels to the terminal.
8999 .INDENT 7.0
9000 .TP
9001 .B half\-blocks
9002 Uses unicode LOWER HALF BLOCK character to achieve higher vertical
9003 resolution. (Default.)
9004 .TP
9005 .B plain
9006 Uses spaces. Causes vertical resolution to drop twofolds, but in
9007 theory works in more places.
9008 .UNINDENT
9009 .TP
9010 .B \fB\-\-vo\-tct\-width=<width>\fP \fB\-\-vo\-tct\-height=<height>\fP
9011 Assume the terminal has the specified character width and/or height.
9012 These default to 80x25 if the terminal size cannot be determined.
9013 .TP
9014 .B \fB\-\-vo\-tct\-256=<yes|no>\fP (default: no)
9015 Use 256 colors \- for terminals which don\(aqt support true color.
9016 .UNINDENT
9017 .TP
9018 .B \fBimage\fP
9019 Output each frame into an image file in the current directory. Each file
9020 takes the frame number padded with leading zeros as name.
9021 .sp
9022 The following global options are supported by this video output:
9023 .INDENT 7.0
9024 .TP
9025 .B \fB\-\-vo\-image\-format=<format>\fP
9026 Select the image file format.
9027 .INDENT 7.0
9028 .TP
9029 .B jpg
9030 JPEG files, extension .jpg. (Default.)
9031 .TP
9032 .B jpeg
9033 JPEG files, extension .jpeg.
9034 .TP
9035 .B png
9036 PNG files.
9037 .TP
9038 .B webp
9039 WebP files.
9040 .UNINDENT
9041 .TP
9042 .B \fB\-\-vo\-image\-png\-compression=<0\-9>\fP
9043 PNG compression factor (speed vs. file size tradeoff) (default: 7)
9044 .TP
9045 .B \fB\-\-vo\-image\-png\-filter=<0\-5>\fP
9046 Filter applied prior to PNG compression (0 = none; 1 = sub; 2 = up;
9047 3 = average; 4 = Paeth; 5 = mixed) (default: 5)
9048 .TP
9049 .B \fB\-\-vo\-image\-jpeg\-quality=<0\-100>\fP
9050 JPEG quality factor (default: 90)
9051 .TP
9052 .B \fB\-\-vo\-image\-jpeg\-optimize=<0\-100>\fP
9053 JPEG optimization factor (default: 100)
9054 .TP
9055 .B \fB\-\-vo\-image\-webp\-lossless=<yes|no>\fP
9056 Enable writing lossless WebP files (default: no)
9057 .TP
9058 .B \fB\-\-vo\-image\-webp\-quality=<0\-100>\fP
9059 WebP quality (default: 75)
9060 .TP
9061 .B \fB\-\-vo\-image\-webp\-compression=<0\-6>\fP
9062 WebP compression factor (default: 4)
9063 .TP
9064 .B \fB\-\-vo\-image\-outdir=<dirname>\fP
9065 Specify the directory to save the image files to (default: \fB\&./\fP).
9066 .UNINDENT
9067 .TP
9068 .B \fBlibmpv\fP
9069 For use with libmpv direct embedding. As a special case, on OS X it
9070 is used like a normal VO within mpv (cocoa\-cb). Otherwise useless in any
9071 other contexts.
9072 (See \fB<mpv/render.h>\fP\&.)
9073 .sp
9074 This also supports many of the options the \fBgpu\fP VO has, depending on the
9075 backend.
9076 .TP
9077 .B \fBrpi\fP (Raspberry Pi)
9078 Native video output on the Raspberry Pi using the MMAL API.
9079 .sp
9080 This is deprecated. Use \fB\-\-vo=gpu\fP instead, which is the default and
9081 provides the same functionality. The \fBrpi\fP VO will be removed in
9082 mpv 0.23.0. Its functionality was folded into \-\-vo=gpu, which now uses
9083 RPI hardware decoding by treating it as a hardware overlay (without applying
9084 GL filtering). Also to be changed in 0.23.0: the \-\-fs flag will be reset to
9085 "no" by default (like on the other platforms).
9086 .sp
9087 The following deprecated global options are supported by this video output:
9088 .INDENT 7.0
9089 .TP
9090 .B \fB\-\-rpi\-display=<number>\fP
9091 Select the display number on which the video overlay should be shown
9092 (default: 0).
9093 .TP
9094 .B \fB\-\-rpi\-layer=<number>\fP
9095 Select the dispmanx layer on which the video overlay should be shown
9096 (default: \-10). Note that mpv will also use the 2 layers above the
9097 selected layer, to handle the window background and OSD. Actual video
9098 rendering will happen on the layer above the selected layer.
9099 .TP
9100 .B \fB\-\-rpi\-background=<yes|no>\fP
9101 Whether to render a black background behind the video (default: no).
9102 Normally it\(aqs better to kill the console framebuffer instead, which
9103 gives better performance.
9104 .TP
9105 .B \fB\-\-rpi\-osd=<yes|no>\fP
9106 Enabled by default. If disabled with \fBno\fP, no OSD layer is created.
9107 This also means there will be no subtitles rendered.
9108 .UNINDENT
9109 .TP
9110 .B \fBdrm\fP (Direct Rendering Manager)
9111 Video output driver using Kernel Mode Setting / Direct Rendering Manager.
9112 Should be used when one doesn\(aqt want to install full\-blown graphical
9113 environment (e.g. no X). Does not support hardware acceleration (if you
9114 need this, check the \fBdrm\fP backend for \fBgpu\fP VO).
9115 .sp
9116 The following global options are supported by this video output:
9117 .INDENT 7.0
9118 .TP
9119 .B \fB\-\-drm\-connector=[<gpu_number>.]<name>\fP
9120 Select the connector to use (usually this is a monitor.) If \fB<name>\fP
9121 is empty or \fBauto\fP, mpv renders the output on the first available
9122 connector. Use \fB\-\-drm\-connector=help\fP to get a list of available
9123 connectors. When using multiple graphic cards, use the \fB<gpu_number>\fP
9124 argument to disambiguate.
9125 (default: empty)
9126 .TP
9127 .B \fB\-\-drm\-mode=<preferred|highest|N|WxH[@R]>\fP
9128 Mode to use (resolution and frame rate).
9129 Possible values:
9130 .INDENT 7.0
9131 .TP
9132 .B preferred
9133 Use the preferred mode for the screen on the selected
9134 connector. (default)
9135 .TP
9136 .B highest
9137 Use the mode with the highest resolution available on the
9138 selected connector.
9139 .TP
9140 .B N
9141 Select mode by index.
9142 .TP
9143 .B WxH[@R]
9144 Specify mode by width, height, and optionally refresh rate.
9145 In case several modes match, selects the mode that comes
9146 first in the EDID list of modes.
9147 .UNINDENT
9148 .sp
9149 Use \fB\-\-drm\-mode=help\fP to get a list of available modes for all active
9150 connectors.
9151 .TP
9152 .B \fB\-\-drm\-atomic=<no|auto>\fP
9153 Toggle use of atomic modesetting. Mostly useful for debugging.
9154 .INDENT 7.0
9155 .TP
9156 .B no
9157 Use legacy modesetting.
9158 .TP
9159 .B auto
9160 Use atomic modesetting, falling back to legacy modesetting if
9161 not available. (default)
9162 .UNINDENT
9163 .sp
9164 Note: Only affects \fBgpu\-context=drm\fP\&. \fBvo=drm\fP supports legacy
9165 modesetting only.
9166 .TP
9167 .B \fB\-\-drm\-draw\-plane=<primary|overlay|N>\fP
9168 Select the DRM plane to which video and OSD is drawn to, under normal
9169 circumstances. The plane can be specified as \fBprimary\fP, which will
9170 pick the first applicable primary plane; \fBoverlay\fP, which will pick
9171 the first applicable overlay plane; or by index. The index is zero
9172 based, and related to the CRTC.
9173 (default: primary)
9174 .sp
9175 When using this option with the drmprime\-drm hwdec interop, only the OSD
9176 is rendered to this plane.
9177 .TP
9178 .B \fB\-\-drm\-drmprime\-video\-plane=<primary|overlay|N>\fP
9179 Select the DRM plane to use for video with the drmprime\-drm hwdec
9180 interop (used by e.g. the rkmpp hwdec on RockChip SoCs, and v4l2 hwdec:s
9181 on various other SoC:s). The plane is unused otherwise. This option
9182 accepts the same values as \fB\-\-drm\-draw\-plane\fP\&. (default: overlay)
9183 .sp
9184 To be able to successfully play 4K video on various SoCs you might need
9185 to set \fB\-\-drm\-draw\-plane=overlay \-\-drm\-drmprime\-video\-plane=primary\fP
9186 and setting \fB\-\-drm\-draw\-surface\-size=1920x1080\fP, to render the OSD at a
9187 lower resolution (the video when handled by the hwdec will be on the
9188 drmprime\-video plane and at full 4K resolution)
9189 .TP
9190 .B \fB\-\-drm\-format=<xrgb8888|xrgb2101010>\fP
9191 Select the DRM format to use (default: xrgb8888). This allows you to
9192 choose the bit depth of the DRM mode. xrgb8888 is your usual 24 bit per
9193 pixel/8 bits per channel packed RGB format with 8 bits of padding.
9194 xrgb2101010 is a packed 30 bits per pixel/10 bits per channel packed RGB
9195 format with 2 bits of padding.
9196 .sp
9197 There are cases when xrgb2101010 will work with the \fBdrm\fP VO, but not
9198 with the \fBdrm\fP backend for the \fBgpu\fP VO. This is because with the
9199 \fBgpu\fP VO, in addition to requiring support in your DRM driver,
9200 requires support for xrgb2101010 in your EGL driver
9201 .TP
9202 .B \fB\-\-drm\-draw\-surface\-size=<[WxH]>\fP
9203 Sets the size of the surface used on the draw plane. The surface will
9204 then be upscaled to the current screen resolution. This option can be
9205 useful when used together with the drmprime\-drm hwdec interop at high
9206 resolutions, as it allows scaling the draw plane (which in this case
9207 only handles the OSD) down to a size the GPU can handle.
9208 .sp
9209 When used without the drmprime\-drm hwdec interop this option will just
9210 cause the video to get rendered at a different resolution and then
9211 scaled to screen size.
9212 .sp
9213 Note: this option is only available with DRM atomic support.
9214 (default: display resolution)
9215 .UNINDENT
9216 .TP
9217 .B \fBmediacodec_embed\fP (Android)
9218 Renders \fBIMGFMT_MEDIACODEC\fP frames directly to an \fBandroid.view.Surface\fP\&.
9219 Requires \fB\-\-hwdec=mediacodec\fP for hardware decoding, along with
9220 \fB\-\-vo=mediacodec_embed\fP and \fB\-\-wid=(intptr_t)(*android.view.Surface)\fP\&.
9221 .sp
9222 Since this video output driver uses native decoding and rendering routines,
9223 many of mpv\(aqs features (subtitle rendering, OSD/OSC, video filters, etc)
9224 are not available with this driver.
9225 .sp
9226 To use hardware decoding with \fB\-\-vo=gpu\fP instead, use
9227 \fB\-\-hwdec=mediacodec\-copy\fP along with \fB\-\-gpu\-context=android\fP\&.
9228 .TP
9229 .B \fBwlshm\fP (Wayland only)
9230 Shared memory video output driver without hardware acceleration that works
9231 whenever Wayland is present.
9232 .sp
9233 \fBNOTE:\fP
9234 .INDENT 7.0
9235 .INDENT 3.5
9236 This is a fallback only, and should not be normally used.
9237 .UNINDENT
9238 .UNINDENT
9239 .UNINDENT
9240 .SH AUDIO FILTERS
9241 .sp
9242 Audio filters allow you to modify the audio stream and its properties. The
9243 syntax is:
9244 .INDENT 0.0
9245 .TP
9246 .B \fB\-\-af=...\fP
9247 Setup a chain of audio filters. See \fB\-\-vf\fP (\fI\%VIDEO FILTERS\fP) for the
9248 full syntax.
9249 .UNINDENT
9250 .sp
9251 \fBNOTE:\fP
9252 .INDENT 0.0
9253 .INDENT 3.5
9254 To get a full list of available audio filters, see \fB\-\-af=help\fP\&.
9255 .sp
9256 Also, keep in mind that most actual filters are available via the \fBlavfi\fP
9257 wrapper, which gives you access to most of libavfilter\(aqs filters. This
9258 includes all filters that have been ported from MPlayer to libavfilter.
9259 .sp
9260 The \fB\-\-vf\fP description describes how libavfilter can be used and how to
9261 workaround deprecated mpv filters.
9262 .UNINDENT
9263 .UNINDENT
9264 .sp
9265 See \fB\-\-vf\fP group of options for info on how \fB\-\-af\-defaults\fP, \fB\-\-af\-add\fP,
9266 \fB\-\-af\-pre\fP, \fB\-\-af\-del\fP, \fB\-\-af\-clr\fP, and possibly others work.
9267 .sp
9268 Available filters are:
9269 .INDENT 0.0
9270 .TP
9271 .B \fBlavcac3enc[=options]\fP
9272 Encode multi\-channel audio to AC\-3 at runtime using libavcodec. Supports
9273 16\-bit native\-endian input format, maximum 6 channels. The output is
9274 big\-endian when outputting a raw AC\-3 stream, native\-endian when
9275 outputting to S/PDIF. If the input sample rate is not 48 kHz, 44.1 kHz or
9276 32 kHz, it will be resampled to 48 kHz.
9277 .INDENT 7.0
9278 .TP
9279 .B \fBtospdif=<yes|no>\fP
9280 Output raw AC\-3 stream if \fBno\fP, output to S/PDIF for
9281 pass\-through if \fByes\fP (default).
9282 .TP
9283 .B \fBbitrate=<rate>\fP
9284 The bitrate use for the AC\-3 stream. Set it to 384 to get 384 kbps.
9285 .sp
9286 The default is 640. Some receivers might not be able to handle this.
9287 .sp
9288 Valid values: 32, 40, 48, 56, 64, 80, 96, 112, 128,
9289 160, 192, 224, 256, 320, 384, 448, 512, 576, 640.
9290 .sp
9291 The special value \fBauto\fP selects a default bitrate based on the
9292 input channel number:
9293 .INDENT 7.0
9294 .TP
9295 .B 1ch
9296 96
9297 .TP
9298 .B 2ch
9299 192
9300 .TP
9301 .B 3ch
9302 224
9303 .TP
9304 .B 4ch
9305 384
9306 .TP
9307 .B 5ch
9308 448
9309 .TP
9310 .B 6ch
9311 448
9312 .UNINDENT
9313 .TP
9314 .B \fBminch=<n>\fP
9315 If the input channel number is less than \fB<minch>\fP, the filter will
9316 detach itself (default: 3).
9317 .TP
9318 .B \fBencoder=<name>\fP
9319 Select the libavcodec encoder used. Currently, this should be an AC\-3
9320 encoder, and using another codec will fail horribly.
9321 .UNINDENT
9322 .TP
9323 .B \fBformat=format:srate:channels:out\-srate:out\-channels\fP
9324 Does not do any format conversion itself. Rather, it may cause the
9325 filter system to insert necessary conversion filters before or after this
9326 filter if needed. It is primarily useful for controlling the audio format
9327 going into other filters. To specify the format for audio output, see
9328 \fB\-\-audio\-format\fP, \fB\-\-audio\-samplerate\fP, and \fB\-\-audio\-channels\fP\&. This
9329 filter is able to force a particular format, whereas \fB\-\-audio\-*\fP
9330 may be overridden by the ao based on output compatibility.
9331 .sp
9332 All parameters are optional. The first 3 parameters restrict what the filter
9333 accepts as input. They will therefore cause conversion filters to be
9334 inserted before this one. The \fBout\-\fP parameters tell the filters or audio
9335 outputs following this filter how to interpret the data without actually
9336 doing a conversion. Setting these will probably just break things unless you
9337 really know you want this for some reason, such as testing or dealing with
9338 broken media.
9339 .INDENT 7.0
9340 .TP
9341 .B \fB<format>\fP
9342 Force conversion to this format. Use \fB\-\-af=format=format=help\fP to get
9343 a list of valid formats.
9344 .TP
9345 .B \fB<srate>\fP
9346 Force conversion to a specific sample rate. The rate is an integer,
9347 48000 for example.
9348 .TP
9349 .B \fB<channels>\fP
9350 Force mixing to a specific channel layout. See \fB\-\-audio\-channels\fP option
9351 for possible values.
9352 .UNINDENT
9353 .sp
9354 \fB<out\-srate>\fP
9355 .sp
9356 \fB<out\-channels>\fP
9357 .sp
9358 \fINOTE\fP: this filter used to be named \fBforce\fP\&. The old \fBformat\fP filter
9359 used to do conversion itself, unlike this one which lets the filter system
9360 handle the conversion.
9361 .TP
9362 .B \fBscaletempo[=option1:option2:...]\fP
9363 Scales audio tempo without altering pitch, optionally synced to playback
9364 speed (default).
9365 .sp
9366 This works by playing \(aqstride\(aq ms of audio at normal speed then consuming
9367 \(aqstride*scale\(aq ms of input audio. It pieces the strides together by
9368 blending \(aqoverlap\(aq% of stride with audio following the previous stride. It
9369 optionally performs a short statistical analysis on the next \(aqsearch\(aq ms
9370 of audio to determine the best overlap position.
9371 .INDENT 7.0
9372 .TP
9373 .B \fBscale=<amount>\fP
9374 Nominal amount to scale tempo. Scales this amount in addition to
9375 speed. (default: 1.0)
9376 .TP
9377 .B \fBstride=<amount>\fP
9378 Length in milliseconds to output each stride. Too high of a value will
9379 cause noticeable skips at high scale amounts and an echo at low scale
9380 amounts. Very low values will alter pitch. Increasing improves
9381 performance. (default: 60)
9382 .TP
9383 .B \fBoverlap=<percent>\fP
9384 Percentage of stride to overlap. Decreasing improves performance.
9385 (default: .20)
9386 .TP
9387 .B \fBsearch=<amount>\fP
9388 Length in milliseconds to search for best overlap position. Decreasing
9389 improves performance greatly. On slow systems, you will probably want
9390 to set this very low. (default: 14)
9391 .TP
9392 .B \fBspeed=<tempo|pitch|both|none>\fP
9393 Set response to speed change.
9394 .INDENT 7.0
9395 .TP
9396 .B tempo
9397 Scale tempo in sync with speed (default).
9398 .TP
9399 .B pitch
9400 Reverses effect of filter. Scales pitch without altering tempo.
9401 Add this to your \fBinput.conf\fP to step by musical semi\-tones:
9402 .INDENT 7.0
9403 .INDENT 3.5
9404 .sp
9405 .nf
9406 .ft C
9407 [ multiply speed 0.9438743126816935
9408 ] multiply speed 1.059463094352953
9409 .ft P
9410 .fi
9411 .UNINDENT
9412 .UNINDENT
9413 .sp
9414 \fBWARNING:\fP
9415 .INDENT 7.0
9416 .INDENT 3.5
9417 Loses sync with video.
9418 .UNINDENT
9419 .UNINDENT
9420 .TP
9421 .B both
9422 Scale both tempo and pitch.
9423 .TP
9424 .B none
9425 Ignore speed changes.
9426 .UNINDENT
9427 .UNINDENT
9428 .INDENT 7.0
9429 .INDENT 3.5
9430 .IP "Examples"
9431 .INDENT 0.0
9432 .TP
9433 .B \fBmpv \-\-af=scaletempo \-\-speed=1.2 media.ogg\fP
9434 Would play media at 1.2x normal speed, with audio at normal
9435 pitch. Changing playback speed would change audio tempo to match.
9436 .TP
9437 .B \fBmpv \-\-af=scaletempo=scale=1.2:speed=none \-\-speed=1.2 media.ogg\fP
9438 Would play media at 1.2x normal speed, with audio at normal
9439 pitch, but changing playback speed would have no effect on audio
9440 tempo.
9441 .TP
9442 .B \fBmpv \-\-af=scaletempo=stride=30:overlap=.50:search=10 media.ogg\fP
9443 Would tweak the quality and performance parameters.
9444 .TP
9445 .B \fBmpv \-\-af=scaletempo=scale=1.2:speed=pitch audio.ogg\fP
9446 Would play media at 1.2x normal speed, with audio at normal pitch.
9447 Changing playback speed would change pitch, leaving audio tempo at
9448 1.2x.
9449 .UNINDENT
9450 .UNINDENT
9451 .UNINDENT
9452 .TP
9453 .B \fBrubberband\fP
9454 High quality pitch correction with librubberband. This can be used in place
9455 of \fBscaletempo\fP, and will be used to adjust audio pitch when playing
9456 at speed different from normal. It can also be used to adjust audio pitch
9457 without changing playback speed.
9458 .INDENT 7.0
9459 .TP
9460 .B \fB<pitch\-scale>\fP
9461 Sets the pitch scaling factor. Frequencies are multiplied by this value.
9462 .UNINDENT
9463 .sp
9464 This filter has a number of additional sub\-options. You can list them with
9465 \fBmpv \-\-af=rubberband=help\fP\&. This will also show the default values
9466 for each option. The options are not documented here, because they are
9467 merely passed to librubberband. Look at the librubberband documentation
9468 to learn what each option does:
9469 \fI\%http://breakfastquay.com/rubberband/code\-doc/classRubberBand_1_1RubberBandStretcher.html\fP
9470 (The mapping of the mpv rubberband filter sub\-option names and values to
9471 those of librubberband follows a simple pattern: \fB"Option" + Name + Value\fP\&.)
9472 .sp
9473 This filter supports the following \fBaf\-command\fP commands:
9474 .INDENT 7.0
9475 .TP
9476 .B \fBset\-pitch\fP
9477 Set the \fB<pitch\-scale>\fP argument dynamically. This can be used to
9478 change the playback pitch at runtime. Note that speed is controlled
9479 using the standard \fBspeed\fP property, not \fBaf\-command\fP\&.
9480 .TP
9481 .B \fBmultiply\-pitch <factor>\fP
9482 Multiply the current value of \fB<pitch\-scale>\fP dynamically. For
9483 example: 0.5 to go down by an octave, 1.5 to go up by a perfect fifth.
9484 If you want to go up or down by semi\-tones, use 1.059463094352953 and
9485 0.9438743126816935
9486 .UNINDENT
9487 .TP
9488 .B \fBlavfi=graph\fP
9489 Filter audio using FFmpeg\(aqs libavfilter.
9490 .INDENT 7.0
9491 .TP
9492 .B \fB<graph>\fP
9493 Libavfilter graph. See \fBlavfi\fP video filter for details \- the graph
9494 syntax is the same.
9495 .sp
9496 \fBWARNING:\fP
9497 .INDENT 7.0
9498 .INDENT 3.5
9499 Don\(aqt forget to quote libavfilter graphs as described in the lavfi
9500 video filter section.
9501 .UNINDENT
9502 .UNINDENT
9503 .TP
9504 .B \fBo=<string>\fP
9505 AVOptions.
9506 .TP
9507 .B \fBfix\-pts=<yes|no>\fP
9508 Determine PTS based on sample count (default: no). If this is enabled,
9509 the player won\(aqt rely on libavfilter passing through PTS accurately.
9510 Instead, it pass a sample count as PTS to libavfilter, and compute the
9511 PTS used by mpv based on that and the input PTS. This helps with filters
9512 which output a recomputed PTS instead of the original PTS (including
9513 filters which require the PTS to start at 0). mpv normally expects
9514 filters to not touch the PTS (or only to the extent of changing frame
9515 boundaries), so this is not the default, but it will be needed to use
9516 broken filters. In practice, these broken filters will either cause slow
9517 A/V desync over time (with some files), or break playback completely if
9518 you seek or start playback from the middle of a file.
9519 .UNINDENT
9520 .UNINDENT
9521 .SH VIDEO FILTERS
9522 .sp
9523 Video filters allow you to modify the video stream and its properties. All of
9524 the information described in this section applies to audio filters as well
9525 (generally using the prefix \fB\-\-af\fP instead of \fB\-\-vf\fP).
9526 .sp
9527 The exact syntax is:
9528 .INDENT 0.0
9529 .TP
9530 .B \fB\-\-vf=<filter1[=parameter1:parameter2:...],filter2,...>\fP
9531 Setup a chain of video filters. This consists on the filter name, and an
9532 option list of parameters after \fB=\fP\&. The parameters are separated by
9533 \fB:\fP (not \fB,\fP, as that starts a new filter entry).
9534 .sp
9535 Before the filter name, a label can be specified with \fB@name:\fP, where
9536 name is an arbitrary user\-given name, which identifies the filter. This
9537 is only needed if you want to toggle the filter at runtime.
9538 .sp
9539 A \fB!\fP before the filter name means the filter is disabled by default. It
9540 will be skipped on filter creation. This is also useful for runtime filter
9541 toggling.
9542 .sp
9543 See the \fBvf\fP command (and \fBtoggle\fP sub\-command) for further explanations
9544 and examples.
9545 .sp
9546 The general filter entry syntax is:
9547 .INDENT 7.0
9548 .INDENT 3.5
9549 \fB["@"<label\-name>":"] ["!"] <filter\-name> [ "=" <filter\-parameter\-list> ]\fP
9550 .UNINDENT
9551 .UNINDENT
9552 .sp
9553 or for the special "toggle" syntax (see \fBvf\fP command):
9554 .INDENT 7.0
9555 .INDENT 3.5
9556 \fB"@"<label\-name>\fP
9557 .UNINDENT
9558 .UNINDENT
9559 .sp
9560 and the \fBfilter\-parameter\-list\fP:
9561 .INDENT 7.0
9562 .INDENT 3.5
9563 \fB<filter\-parameter> | <filter\-parameter> "," <filter\-parameter\-list>\fP
9564 .UNINDENT
9565 .UNINDENT
9566 .sp
9567 and \fBfilter\-parameter\fP:
9568 .INDENT 7.0
9569 .INDENT 3.5
9570 \fB( <param\-name> "=" <param\-value> ) | <param\-value>\fP
9571 .UNINDENT
9572 .UNINDENT
9573 .sp
9574 \fBparam\-value\fP can further be quoted in \fB[\fP / \fB]\fP in case the value
9575 contains characters like \fB,\fP or \fB=\fP\&. This is used in particular with
9576 the \fBlavfi\fP filter, which uses a very similar syntax as mpv (MPlayer
9577 historically) to specify filters and their parameters.
9578 .UNINDENT
9579 .sp
9580 Filters can be manipulated at run time. You can use \fB@\fP labels as described
9581 above in combination with the \fBvf\fP command (see \fI\%COMMAND INTERFACE\fP) to get
9582 more control over this. Initially disabled filters with \fB!\fP are useful for
9583 this as well.
9584 .sp
9585 You can also set defaults for each filter. The defaults are applied before the
9586 normal filter parameters. This is deprecated and never worked for the
9587 libavfilter bridge.
9588 .INDENT 0.0
9589 .TP
9590 .B \fB\-\-vf\-defaults=<filter1[=parameter1:parameter2:...],filter2,...>\fP
9591 Set defaults for each filter. (Deprecated. \fB\-\-af\-defaults\fP is deprecated
9592 as well.)
9593 .UNINDENT
9594 .sp
9595 \fBNOTE:\fP
9596 .INDENT 0.0
9597 .INDENT 3.5
9598 To get a full list of available video filters, see \fB\-\-vf=help\fP and
9599 \fI\%http://ffmpeg.org/ffmpeg\-filters.html\fP .
9600 .sp
9601 Also, keep in mind that most actual filters are available via the \fBlavfi\fP
9602 wrapper, which gives you access to most of libavfilter\(aqs filters. This
9603 includes all filters that have been ported from MPlayer to libavfilter.
9604 .sp
9605 Most builtin filters are deprecated in some ways, unless they\(aqre only available
9606 in mpv (such as filters which deal with mpv specifics, or which are
9607 implemented in mpv only).
9608 .sp
9609 If a filter is not builtin, the \fBlavfi\-bridge\fP will be automatically
9610 tried. This bridge does not support help output, and does not verify
9611 parameters before the filter is actually used. Although the mpv syntax
9612 is rather similar to libavfilter\(aqs, it\(aqs not the same. (Which means not
9613 everything accepted by vf_lavfi\(aqs \fBgraph\fP option will be accepted by
9614 \fB\-\-vf\fP\&.)
9615 .sp
9616 You can also prefix the filter name with \fBlavfi\-\fP to force the wrapper.
9617 This is helpful if the filter name collides with a deprecated mpv builtin
9618 filter. For example \fB\-\-vf=lavfi\-scale=args\fP would use libavfilter\(aqs
9619 \fBscale\fP filter over mpv\(aqs deprecated builtin one.
9620 .UNINDENT
9621 .UNINDENT
9622 .sp
9623 Video filters are managed in lists. There are a few commands to manage the
9624 filter list.
9625 .INDENT 0.0
9626 .TP
9627 .B \fB\-\-vf\-add=filter\fP
9628 Appends the filter given as arguments to the filter list. (Passing multiple
9629 filters is currently still possible, but deprecated.)
9630 .TP
9631 .B \fB\-\-vf\-pre=filter\fP
9632 Prepends the filters given as arguments to the filter list. (Passing
9633 multiple filters is currently still possible, but deprecated.)
9634 .TP
9635 .B \fB\-\-vf\-del=filter\fP
9636 Deletes the filter. The filter can even given the way it was added (filter
9637 name and its full argument list), by label (prefixed with \fB@\fP), or as
9638 index number. Index numbers start at 0, negative numbers address the end of
9639 the list (\-1 is the last). (Passing multiple filters is currently still
9640 possible, but deprecated.)
9641 .TP
9642 .B \fB\-\-vf\-clr\fP
9643 Completely empties the filter list.
9644 .UNINDENT
9645 .sp
9646 With filters that support it, you can access parameters by their name.
9647 .INDENT 0.0
9648 .TP
9649 .B \fB\-\-vf=<filter>=help\fP
9650 Prints the parameter names and parameter value ranges for a particular
9651 filter.
9652 .UNINDENT
9653 .sp
9654 Available mpv\-only filters are:
9655 .INDENT 0.0
9656 .TP
9657 .B \fBformat=fmt=<value>:colormatrix=<value>:...\fP
9658 Applies video parameter overrides, with optional conversion. By default,
9659 this overrides the video\(aqs parameters without conversion (except for the
9660 \fBfmt\fP parameter), but can be made to perform an appropriate conversion
9661 with \fBconvert=yes\fP for parameters for which conversion is supported.
9662 .INDENT 7.0
9663 .TP
9664 .B \fB<fmt>\fP
9665 Image format name, e.g. rgb15, bgr24, 420p, etc. (default: don\(aqt change).
9666 .sp
9667 This filter always performs conversion to the given format.
9668 .sp
9669 \fBNOTE:\fP
9670 .INDENT 7.0
9671 .INDENT 3.5
9672 For a list of available formats, use \fB\-\-vf=format=fmt=help\fP\&.
9673 .UNINDENT
9674 .UNINDENT
9675 .TP
9676 .B \fB<convert=yes|no>\fP
9677 Force conversion of color parameters (default: no).
9678 .sp
9679 If this is disabled (the default), the only conversion that is possibly
9680 performed is format conversion if \fB<fmt>\fP is set. All other parameters
9681 (like \fB<colormatrix>\fP) are forced without conversion. This mode is
9682 typically useful when files have been incorrectly tagged.
9683 .sp
9684 If this is enabled, libswscale or zimg is used if any of the parameters
9685 mismatch. zimg is used of the input/output image formats are supported
9686 by mpv\(aqs zimg wrapper, and if \fB\-\-sws\-allow\-zimg=yes\fP is used. Both
9687 libraries may not support all kinds of conversions. This typically
9688 results in silent incorrect conversion. zimg has in many cases a better
9689 chance of performing the conversion correctly.
9690 .sp
9691 In both cases, the color parameters are set on the output stage of the
9692 image format conversion (if \fBfmt\fP was set). The difference is that
9693 with \fBconvert=no\fP, the color parameters are not passed on to the
9694 converter.
9695 .sp
9696 If input and output video parameters are the same, conversion is always
9697 skipped.
9698 .INDENT 7.0
9699 .INDENT 3.5
9700 .IP "Examples"
9701 .INDENT 0.0
9702 .TP
9703 .B \fBmpv test.mkv \-\-vf=format:colormatrix=ycgco\fP
9704 Results in incorrect colors (if test.mkv was tagged correctly).
9705 .TP
9706 .B \fBmpv test.mkv \-\-vf=format:colormatrix=ycgco:convert=yes \-\-sws\-allow\-zimg\fP
9707 Results in true conversion to \fBycgco\fP, assuming the renderer
9708 supports it (\fB\-\-vo=gpu\fP normally does). You can add \fB\-\-vo=xv\fP
9709 to force a VO which definitely does not support it, which should
9710 show incorrect colors as confirmation.
9711 .sp
9712 Using \fB\-\-sws\-allow\-zimg=no\fP (or disabling zimg at build time)
9713 will use libswscale, which cannot perform this conversion as
9714 of this writing.
9715 .UNINDENT
9716 .UNINDENT
9717 .UNINDENT
9718 .TP
9719 .B \fB<colormatrix>\fP
9720 Controls the YUV to RGB color space conversion when playing video. There
9721 are various standards. Normally, BT.601 should be used for SD video, and
9722 BT.709 for HD video. (This is done by default.) Using incorrect color space
9723 results in slightly under or over saturated and shifted colors.
9724 .sp
9725 These options are not always supported. Different video outputs provide
9726 varying degrees of support. The \fBgpu\fP and \fBvdpau\fP video output
9727 drivers usually offer full support. The \fBxv\fP output can set the color
9728 space if the system video driver supports it, but not input and output
9729 levels. The \fBscale\fP video filter can configure color space and input
9730 levels, but only if the output format is RGB (if the video output driver
9731 supports RGB output, you can force this with \fB\-vf scale,format=rgba\fP).
9732 .sp
9733 If this option is set to \fBauto\fP (which is the default), the video\(aqs
9734 color space flag will be used. If that flag is unset, the color space
9735 will be selected automatically. This is done using a simple heuristic that
9736 attempts to distinguish SD and HD video. If the video is larger than
9737 1279x576 pixels, BT.709 (HD) will be used; otherwise BT.601 (SD) is
9738 selected.
9739 .sp
9740 Available color spaces are:
9741 .INDENT 7.0
9742 .TP
9743 .B auto
9744 automatic selection (default)
9745 .TP
9746 .B bt.601
9747 ITU\-R BT.601 (SD)
9748 .TP
9749 .B bt.709
9750 ITU\-R BT.709 (HD)
9751 .TP
9752 .B bt.2020\-ncl
9753 ITU\-R BT.2020 non\-constant luminance system
9754 .TP
9755 .B bt.2020\-cl
9756 ITU\-R BT.2020 constant luminance system
9757 .TP
9758 .B smpte\-240m
9759 SMPTE\-240M
9760 .UNINDENT
9761 .TP
9762 .B \fB<colorlevels>\fP
9763 YUV color levels used with YUV to RGB conversion. This option is only
9764 necessary when playing broken files which do not follow standard color
9765 levels or which are flagged wrong. If the video does not specify its
9766 color range, it is assumed to be limited range.
9767 .sp
9768 The same limitations as with \fB<colormatrix>\fP apply.
9769 .sp
9770 Available color ranges are:
9771 .INDENT 7.0
9772 .TP
9773 .B auto
9774 automatic selection (normally limited range) (default)
9775 .TP
9776 .B limited
9777 limited range (16\-235 for luma, 16\-240 for chroma)
9778 .TP
9779 .B full
9780 full range (0\-255 for both luma and chroma)
9781 .UNINDENT
9782 .TP
9783 .B \fB<primaries>\fP
9784 RGB primaries the source file was encoded with. Normally this should be set
9785 in the file header, but when playing broken or mistagged files this can be
9786 used to override the setting.
9787 .sp
9788 This option only affects video output drivers that perform color
9789 management, for example \fBgpu\fP with the \fBtarget\-prim\fP or
9790 \fBicc\-profile\fP suboptions set.
9791 .sp
9792 If this option is set to \fBauto\fP (which is the default), the video\(aqs
9793 primaries flag will be used. If that flag is unset, the color space will
9794 be selected automatically, using the following heuristics: If the
9795 \fB<colormatrix>\fP is set or determined as BT.2020 or BT.709, the
9796 corresponding primaries are used. Otherwise, if the video height is
9797 exactly 576 (PAL), BT.601\-625 is used. If it\(aqs exactly 480 or 486 (NTSC),
9798 BT.601\-525 is used. If the video resolution is anything else, BT.709 is
9799 used.
9800 .sp
9801 Available primaries are:
9802 .INDENT 7.0
9803 .TP
9804 .B auto
9805 automatic selection (default)
9806 .TP
9807 .B bt.601\-525
9808 ITU\-R BT.601 (SD) 525\-line systems (NTSC, SMPTE\-C)
9809 .TP
9810 .B bt.601\-625
9811 ITU\-R BT.601 (SD) 625\-line systems (PAL, SECAM)
9812 .TP
9813 .B bt.709
9814 ITU\-R BT.709 (HD) (same primaries as sRGB)
9815 .TP
9816 .B bt.2020
9817 ITU\-R BT.2020 (UHD)
9818 .TP
9819 .B apple
9820 Apple RGB
9821 .TP
9822 .B adobe
9823 Adobe RGB (1998)
9824 .TP
9825 .B prophoto
9826 ProPhoto RGB (ROMM)
9827 .TP
9828 .B cie1931
9829 CIE 1931 RGB
9830 .TP
9831 .B dci\-p3
9832 DCI\-P3 (Digital Cinema)
9833 .TP
9834 .B v\-gamut
9835 Panasonic V\-Gamut primaries
9836 .UNINDENT
9837 .TP
9838 .B \fB<gamma>\fP
9839 Gamma function the source file was encoded with. Normally this should be set
9840 in the file header, but when playing broken or mistagged files this can be
9841 used to override the setting.
9842 .sp
9843 This option only affects video output drivers that perform color management.
9844 .sp
9845 If this option is set to \fBauto\fP (which is the default), the gamma will
9846 be set to BT.1886 for YCbCr content, sRGB for RGB content and Linear for
9847 XYZ content.
9848 .sp
9849 Available gamma functions are:
9850 .INDENT 7.0
9851 .TP
9852 .B auto
9853 automatic selection (default)
9854 .TP
9855 .B bt.1886
9856 ITU\-R BT.1886 (EOTF corresponding to BT.601/BT.709/BT.2020)
9857 .TP
9858 .B srgb
9859 IEC 61966\-2\-4 (sRGB)
9860 .TP
9861 .B linear
9862 Linear light
9863 .TP
9864 .B gamma1.8
9865 Pure power curve (gamma 1.8)
9866 .TP
9867 .B gamma2.0
9868 Pure power curve (gamma 2.0)
9869 .TP
9870 .B gamma2.2
9871 Pure power curve (gamma 2.2)
9872 .TP
9873 .B gamma2.4
9874 Pure power curve (gamma 2.4)
9875 .TP
9876 .B gamma2.6
9877 Pure power curve (gamma 2.6)
9878 .TP
9879 .B gamma2.8
9880 Pure power curve (gamma 2.8)
9881 .TP
9882 .B prophoto
9883 ProPhoto RGB (ROMM) curve
9884 .TP
9885 .B pq
9886 ITU\-R BT.2100 PQ (Perceptual quantizer) curve
9887 .TP
9888 .B hlg
9889 ITU\-R BT.2100 HLG (Hybrid Log\-gamma) curve
9890 .TP
9891 .B v\-log
9892 Panasonic V\-Log transfer curve
9893 .TP
9894 .B s\-log1
9895 Sony S\-Log1 transfer curve
9896 .TP
9897 .B s\-log2
9898 Sony S\-Log2 transfer curve
9899 .UNINDENT
9900 .TP
9901 .B \fB<sig\-peak>\fP
9902 Reference peak illumination for the video file, relative to the
9903 signal\(aqs reference white level. This is mostly interesting for HDR, but
9904 it can also be used tone map SDR content to simulate a different
9905 exposure. Normally inferred from tags such as MaxCLL or mastering
9906 metadata.
9907 .sp
9908 The default of 0.0 will default to the source\(aqs nominal peak luminance.
9909 .TP
9910 .B \fB<light>\fP
9911 .INDENT 7.0
9912 .INDENT 3.5
9913 Light type of the scene. This is mostly correctly inferred based on the
9914 gamma function, but it can be useful to override this when viewing raw
9915 camera footage (e.g. V\-Log), which is normally scene\-referred instead
9916 of display\-referred.
9917 .sp
9918 Available light types are:
9919 .UNINDENT
9920 .UNINDENT
9921 .INDENT 7.0
9922 .TP
9923 .B auto
9924 Automatic selection (default)
9925 .TP
9926 .B display
9927 Display\-referred light (most content)
9928 .TP
9929 .B hlg
9930 Scene\-referred using the HLG OOTF (e.g. HLG content)
9931 .TP
9932 .B 709\-1886
9933 Scene\-referred using the BT709+BT1886 interaction
9934 .TP
9935 .B gamma1.2
9936 Scene\-referred using a pure power OOTF (gamma=1.2)
9937 .UNINDENT
9938 .TP
9939 .B \fB<stereo\-in>\fP
9940 Set the stereo mode the video is assumed to be encoded in. Use
9941 \fB\-\-vf format:stereo\-in=help\fP to list all available modes. Check with
9942 the \fBstereo3d\fP filter documentation to see what the names mean.
9943 .TP
9944 .B \fB<stereo\-out>\fP
9945 Set the stereo mode the video should be displayed as. Takes the
9946 same values as the \fBstereo\-in\fP option.
9947 .TP
9948 .B \fB<rotate>\fP
9949 Set the rotation the video is assumed to be encoded with in degrees.
9950 The special value \fB\-1\fP uses the input format.
9951 .TP
9952 .B \fB<dw>\fP, \fB<dh>\fP
9953 Set the display size. Note that setting the display size such that
9954 the video is scaled in both directions instead of just changing the
9955 aspect ratio is an implementation detail, and might change later.
9956 .TP
9957 .B \fB<dar>\fP
9958 Set the display aspect ratio of the video frame. This is a float,
9959 but values such as \fB[16:9]\fP can be passed too (\fB[...]\fP for quoting
9960 to prevent the option parser from interpreting the \fB:\fP character).
9961 .UNINDENT
9962 .TP
9963 .B \fBlavfi=graph[:sws\-flags[:o=opts]]\fP
9964 Filter video using FFmpeg\(aqs libavfilter.
9965 .INDENT 7.0
9966 .TP
9967 .B \fB<graph>\fP
9968 The libavfilter graph string. The filter must have a single video input
9969 pad and a single video output pad.
9970 .sp
9971 See \fI\%https://ffmpeg.org/ffmpeg\-filters.html\fP for syntax and available
9972 filters.
9973 .sp
9974 \fBWARNING:\fP
9975 .INDENT 7.0
9976 .INDENT 3.5
9977 If you want to use the full filter syntax with this option, you have
9978 to quote the filter graph in order to prevent mpv\(aqs syntax and the
9979 filter graph syntax from clashing. To prevent a quoting and escaping
9980 mess, consider using \fB\-\-lavfi\-complex\fP if you know which video
9981 track you want to use from the input file. (There is only one video
9982 track for nearly all video files anyway.)
9983 .UNINDENT
9984 .UNINDENT
9985 .INDENT 7.0
9986 .INDENT 3.5
9987 .IP "Examples"
9988 .INDENT 0.0
9989 .TP
9990 .B \fB\-\-vf=lavfi=[gradfun=20:30,vflip]\fP
9991 \fBgradfun\fP filter with nonsense parameters, followed by a
9992 \fBvflip\fP filter. (This demonstrates how libavfilter takes a
9993 graph and not just a single filter.) The filter graph string is
9994 quoted with \fB[\fP and \fB]\fP\&. This requires no additional quoting
9995 or escaping with some shells (like bash), while others (like
9996 zsh) require additional \fB"\fP quotes around the option string.
9997 .TP
9998 .B \fB\(aq\-\-vf=lavfi="gradfun=20:30,vflip"\(aq\fP
9999 Same as before, but uses quoting that should be safe with all
10000 shells. The outer \fB\(aq\fP quotes make sure that the shell does not
10001 remove the \fB"\fP quotes needed by mpv.
10002 .TP
10003 .B \fB\(aq\-\-vf=lavfi=graph="gradfun=radius=30:strength=20,vflip"\(aq\fP
10004 Same as before, but uses named parameters for everything.
10005 .UNINDENT
10006 .UNINDENT
10007 .UNINDENT
10008 .TP
10009 .B \fB<sws\-flags>\fP
10010 If libavfilter inserts filters for pixel format conversion, this
10011 option gives the flags which should be passed to libswscale. This
10012 option is numeric and takes a bit\-wise combination of \fBSWS_\fP flags.
10013 .sp
10014 See \fBhttp://git.videolan.org/?p=ffmpeg.git;a=blob;f=libswscale/swscale.h\fP\&.
10015 .TP
10016 .B \fB<o>\fP
10017 Set AVFilterGraph options. These should be documented by FFmpeg.
10018 .INDENT 7.0
10019 .INDENT 3.5
10020 .IP "Example"
10021 .INDENT 0.0
10022 .TP
10023 .B \fB\(aq\-\-vf=lavfi=yadif:o="threads=2,thread_type=slice"\(aq\fP
10024 forces a specific threading configuration.
10025 .UNINDENT
10026 .UNINDENT
10027 .UNINDENT
10028 .UNINDENT
10029 .TP
10030 .B \fBsub=[=bottom\-margin:top\-margin]\fP
10031 Moves subtitle rendering to an arbitrary point in the filter chain, or force
10032 subtitle rendering in the video filter as opposed to using video output OSD
10033 support.
10034 .INDENT 7.0
10035 .TP
10036 .B \fB<bottom\-margin>\fP
10037 Adds a black band at the bottom of the frame. The SSA/ASS renderer can
10038 place subtitles there (with \fB\-\-sub\-use\-margins\fP).
10039 .TP
10040 .B \fB<top\-margin>\fP
10041 Black band on the top for toptitles (with \fB\-\-sub\-use\-margins\fP).
10042 .UNINDENT
10043 .INDENT 7.0
10044 .INDENT 3.5
10045 .IP "Examples"
10046 .INDENT 0.0
10047 .TP
10048 .B \fB\-\-vf=sub,eq\fP
10049 Moves sub rendering before the eq filter. This will put both
10050 subtitle colors and video under the influence of the video equalizer
10051 settings.
10052 .UNINDENT
10053 .UNINDENT
10054 .UNINDENT
10055 .TP
10056 .B \fBvapoursynth=file:buffered\-frames:concurrent\-frames\fP
10057 Loads a VapourSynth filter script. This is intended for streamed
10058 processing: mpv actually provides a source filter, instead of using a
10059 native VapourSynth video source. The mpv source will answer frame
10060 requests only within a small window of frames (the size of this window
10061 is controlled with the \fBbuffered\-frames\fP parameter), and requests outside
10062 of that will return errors. As such, you can\(aqt use the full power of
10063 VapourSynth, but you can use certain filters.
10064 .sp
10065 \fBWARNING:\fP
10066 .INDENT 7.0
10067 .INDENT 3.5
10068 Do not use this filter, unless you have expert knowledge in VapourSynth,
10069 and know how to fix bugs in the mpv VapourSynth wrapper code.
10070 .UNINDENT
10071 .UNINDENT
10072 .sp
10073 If you just want to play video generated by VapourSynth (i.e. using
10074 a native VapourSynth video source), it\(aqs better to use \fBvspipe\fP and a
10075 pipe or FIFO to feed the video to mpv. The same applies if the filter script
10076 requires random frame access (see \fBbuffered\-frames\fP parameter).
10077 .INDENT 7.0
10078 .TP
10079 .B \fBfile\fP
10080 Filename of the script source. Currently, this is always a python
10081 script (\fB\&.vpy\fP in VapourSynth convention).
10082 .sp
10083 The variable \fBvideo_in\fP is set to the mpv video source, and it is
10084 expected that the script reads video from it. (Otherwise, mpv will
10085 decode no video, and the video packet queue will overflow, eventually
10086 leading to only audio playing, or worse.)
10087 .sp
10088 The filter graph created by the script is also expected to pass through
10089 timestamps using the \fB_DurationNum\fP and \fB_DurationDen\fP frame
10090 properties.
10091 .sp
10092 See the end of the option list for a full list of script variables
10093 defined by mpv.
10094 .INDENT 7.0
10095 .INDENT 3.5
10096 .IP "Example:"
10097 .INDENT 0.0
10098 .INDENT 3.5
10099 .sp
10100 .nf
10101 .ft C
10102 import vapoursynth as vs
10103 core = vs.get_core()
10104 core.std.AddBorders(video_in, 10, 10, 20, 20).set_output()
10105 .ft P
10106 .fi
10107 .UNINDENT
10108 .UNINDENT
10109 .UNINDENT
10110 .UNINDENT
10111 .sp
10112 \fBWARNING:\fP
10113 .INDENT 7.0
10114 .INDENT 3.5
10115 The script will be reloaded on every seek. This is done to reset
10116 the filter properly on discontinuities.
10117 .UNINDENT
10118 .UNINDENT
10119 .TP
10120 .B \fBbuffered\-frames\fP
10121 Maximum number of decoded video frames that should be buffered before
10122 the filter (default: 4). This specifies the maximum number of frames
10123 the script can request in backward direction.
10124 .sp
10125 E.g. if \fBbuffered\-frames=5\fP, and the script just requested frame 15,
10126 it can still request frame 10, but frame 9 is not available anymore.
10127 If it requests frame 30, mpv will decode 15 more frames, and keep only
10128 frames 25\-30.
10129 .sp
10130 The only reason why this buffer exists is to serve the random access
10131 requests the VapourSynth filter can make.
10132 .sp
10133 The VapourSynth API has a \fBgetFrameAsync\fP function, which takes an
10134 absolute frame number. Source filters must respond to all requests. For
10135 example, a source filter can request frame 2432, and then frame 3.
10136 Source filters typically implement this by pre\-indexing the entire
10137 file.
10138 .sp
10139 mpv on the other hand is stream oriented, and does not allow filters to
10140 seek. (And it would not make sense to allow it, because it would ruin
10141 performance.) Filters get frames sequentially in playback direction, and
10142 cannot request them out of order.
10143 .sp
10144 To compensate for this mismatch, mpv allows the filter to access frames
10145 within a certain window. \fBbuffered\-frames\fP controls the size of this
10146 window. Most VapourSynth filters happen to work with this, because mpv
10147 requests frames sequentially increasing from it, and most filters only
10148 require frames "close" to the requested frame.
10149 .sp
10150 If the filter requests a frame that has a higher frame number than the
10151 highest buffered frame, new frames will be decoded until the requested
10152 frame number is reached. Excessive frames will be flushed out in a FIFO
10153 manner (there are only at most \fBbuffered\-frames\fP in this buffer).
10154 .sp
10155 If the filter requests a frame that has a lower frame number than the
10156 lowest buffered frame, the request cannot be satisfied, and an error
10157 is returned to the filter. This kind of error is not supposed to happen
10158 in a "proper" VapourSynth environment. What exactly happens depends on
10159 the filters involved.
10160 .sp
10161 Increasing this buffer will not improve performance. Rather, it will
10162 waste memory, and slow down seeks (when enough frames to fill the buffer
10163 need to be decoded at once). It is only needed to prevent the error
10164 described in the previous paragraph.
10165 .sp
10166 How many frames a filter requires depends on filter implementation
10167 details, and mpv has no way of knowing. A scale filter might need only
10168 1 frame, an interpolation filter may require a small number of frames,
10169 and the \fBReverse\fP filter will require an infinite number of frames.
10170 .sp
10171 If you want reliable operation to the full extend VapourSynth is
10172 capable, use \fBvspipe\fP\&.
10173 .sp
10174 The actual number of buffered frames also depends on the value of the
10175 \fBconcurrent\-frames\fP option. Currently, both option values are
10176 multiplied to get the final buffer size.
10177 .TP
10178 .B \fBconcurrent\-frames\fP
10179 Number of frames that should be requested in parallel. The
10180 level of concurrency depends on the filter and how quickly mpv can
10181 decode video to feed the filter. This value should probably be
10182 proportional to the number of cores on your machine. Most time,
10183 making it higher than the number of cores can actually make it
10184 slower.
10185 .sp
10186 Technically, mpv will call the VapourSynth \fBgetFrameAsync\fP function
10187 in a loop, until there are \fBconcurrent\-frames\fP frames that have not
10188 been returned by the filter yet. This also assumes that the rest of the
10189 mpv filter chain reads the output of the \fBvapoursynth\fP filter quickly
10190 enough. (For example, if you pause the player, filtering will stop very
10191 soon, because the filtered frames are waiting in a queue.)
10192 .sp
10193 Actual concurrency depends on many other factors.
10194 .sp
10195 By default, this uses the special value \fBauto\fP, which sets the option
10196 to the number of detected logical CPU cores.
10197 .UNINDENT
10198 .sp
10199 The following \fB\&.vpy\fP script variables are defined by mpv:
10200 .INDENT 7.0
10201 .TP
10202 .B \fBvideo_in\fP
10203 The mpv video source as vapoursynth clip. Note that this has an
10204 incorrect (very high) length set, which confuses many filters. This is
10205 necessary, because the true number of frames is unknown. You can use the
10206 \fBTrim\fP filter on the clip to reduce the length.
10207 .TP
10208 .B \fBvideo_in_dw\fP, \fBvideo_in_dh\fP
10209 Display size of the video. Can be different from video size if the
10210 video does not use square pixels (e.g. DVD).
10211 .TP
10212 .B \fBcontainer_fps\fP
10213 FPS value as reported by file headers. This value can be wrong or
10214 completely broken (e.g. 0 or NaN). Even if the value is correct,
10215 if another filter changes the real FPS (by dropping or inserting
10216 frames), the value of this variable will not be useful. Note that
10217 the \fB\-\-fps\fP command line option overrides this value.
10218 .sp
10219 Useful for some filters which insist on having a FPS.
10220 .TP
10221 .B \fBdisplay_fps\fP
10222 Refresh rate of the current display. Note that this value can be 0.
10223 .UNINDENT
10224 .TP
10225 .B \fBvavpp\fP
10226 VA\-API video post processing. Requires the system to support VA\-API,
10227 i.e. Linux/BSD only. Works with \fB\-\-vo=vaapi\fP and \fB\-\-vo=gpu\fP only.
10228 Currently deinterlaces. This filter is automatically inserted if
10229 deinterlacing is requested (either using the \fBd\fP key, by default mapped to
10230 the command \fBcycle deinterlace\fP, or the \fB\-\-deinterlace\fP option).
10231 .INDENT 7.0
10232 .TP
10233 .B \fBdeint=<method>\fP
10234 Select the deinterlacing algorithm.
10235 .INDENT 7.0
10236 .TP
10237 .B no
10238 Don\(aqt perform deinterlacing.
10239 .TP
10240 .B auto
10241 Select the best quality deinterlacing algorithm (default). This
10242 goes by the order of the options as documented, with
10243 \fBmotion\-compensated\fP being considered best quality.
10244 .TP
10245 .B first\-field
10246 Show only first field.
10247 .TP
10248 .B bob
10249 bob deinterlacing.
10250 .TP
10251 .B weave, motion\-adaptive, motion\-compensated
10252 Advanced deinterlacing algorithms. Whether these actually work
10253 depends on the GPU hardware, the GPU drivers, driver bugs, and
10254 mpv bugs.
10255 .UNINDENT
10256 .TP
10257 .B \fB<interlaced\-only>\fP
10258 .INDENT 7.0
10259 .TP
10260 .B no
10261 Deinterlace all frames (default).
10262 .TP
10263 .B yes
10264 Only deinterlace frames marked as interlaced.
10265 .UNINDENT
10266 .TP
10267 .B \fBreversal\-bug=<yes|no>\fP
10268 .INDENT 7.0
10269 .TP
10270 .B no
10271 Use the API as it was interpreted by older Mesa drivers. While
10272 this interpretation was more obvious and inuitive, it was
10273 apparently wrong, and not shared by Intel driver developers.
10274 .TP
10275 .B yes
10276 Use Intel interpretation of surface forward and backwards
10277 references (default). This is what Intel drivers and newer Mesa
10278 drivers expect. Matters only for the advanced deinterlacing
10279 algorithms.
10280 .UNINDENT
10281 .UNINDENT
10282 .TP
10283 .B \fBvdpaupp\fP
10284 VDPAU video post processing. Works with \fB\-\-vo=vdpau\fP and \fB\-\-vo=gpu\fP
10285 only. This filter is automatically inserted if deinterlacing is requested
10286 (either using the \fBd\fP key, by default mapped to the command
10287 \fBcycle deinterlace\fP, or the \fB\-\-deinterlace\fP option). When enabling
10288 deinterlacing, it is always preferred over software deinterlacer filters
10289 if the \fBvdpau\fP VO is used, and also if \fBgpu\fP is used and hardware
10290 decoding was activated at least once (i.e. vdpau was loaded).
10291 .INDENT 7.0
10292 .TP
10293 .B \fBsharpen=<\-1\-1>\fP
10294 For positive values, apply a sharpening algorithm to the video, for
10295 negative values a blurring algorithm (default: 0).
10296 .TP
10297 .B \fBdenoise=<0\-1>\fP
10298 Apply a noise reduction algorithm to the video (default: 0; no noise
10299 reduction).
10300 .TP
10301 .B \fBdeint=<yes|no>\fP
10302 Whether deinterlacing is enabled (default: no). If enabled, it will use
10303 the mode selected with \fBdeint\-mode\fP\&.
10304 .TP
10305 .B \fBdeint\-mode=<first\-field|bob|temporal|temporal\-spatial>\fP
10306 Select deinterlacing mode (default: temporal).
10307 .sp
10308 Note that there\(aqs currently a mechanism that allows the \fBvdpau\fP VO to
10309 change the \fBdeint\-mode\fP of auto\-inserted \fBvdpaupp\fP filters. To avoid
10310 confusion, it\(aqs recommended not to use the \fB\-\-vo=vdpau\fP suboptions
10311 related to filtering.
10312 .INDENT 7.0
10313 .TP
10314 .B first\-field
10315 Show only first field.
10316 .TP
10317 .B bob
10318 Bob deinterlacing.
10319 .TP
10320 .B temporal
10321 Motion\-adaptive temporal deinterlacing. May lead to A/V desync
10322 with slow video hardware and/or high resolution.
10323 .TP
10324 .B temporal\-spatial
10325 Motion\-adaptive temporal deinterlacing with edge\-guided spatial
10326 interpolation. Needs fast video hardware.
10327 .UNINDENT
10328 .TP
10329 .B \fBchroma\-deint\fP
10330 Makes temporal deinterlacers operate both on luma and chroma (default).
10331 Use no\-chroma\-deint to solely use luma and speed up advanced
10332 deinterlacing. Useful with slow video memory.
10333 .TP
10334 .B \fBpullup\fP
10335 Try to apply inverse telecine, needs motion adaptive temporal
10336 deinterlacing.
10337 .TP
10338 .B \fBinterlaced\-only=<yes|no>\fP
10339 If \fByes\fP, only deinterlace frames marked as interlaced (default: no).
10340 .TP
10341 .B \fBhqscaling=<0\-9>\fP
10342 .INDENT 7.0
10343 .TP
10344 .B 0
10345 Use default VDPAU scaling (default).
10346 .TP
10347 .B 1\-9
10348 Apply high quality VDPAU scaling (needs capable hardware).
10349 .UNINDENT
10350 .UNINDENT
10351 .TP
10352 .B \fBd3d11vpp\fP
10353 Direct3D 11 video post processing. Currently requires D3D11 hardware
10354 decoding for use.
10355 .INDENT 7.0
10356 .TP
10357 .B \fBdeint=<yes|no>\fP
10358 Whether deinterlacing is enabled (default: no).
10359 .TP
10360 .B \fBinterlaced\-only=<yes|no>\fP
10361 If \fByes\fP, only deinterlace frames marked as interlaced (default: no).
10362 .TP
10363 .B \fBmode=<blend|bob|adaptive|mocomp|ivctc|none>\fP
10364 Tries to select a video processor with the given processing capability.
10365 If a video processor supports multiple capabilities, it is not clear
10366 which algorithm is actually selected. \fBnone\fP always falls back. On
10367 most if not all hardware, this option will probably do nothing, because
10368 a video processor usually supports all modes or none.
10369 .UNINDENT
10370 .TP
10371 .B \fBfingerprint=...\fP
10372 Compute video frame fingerprints and provide them as metadata. Actually, it
10373 currently barely deserved to be called \fBfingerprint\fP, because it does not
10374 compute "proper" fingerprints, only tiny downscaled images (but which can be
10375 used to compute image hashes or for similarity matching).
10376 .sp
10377 The main purpose of this filter is to support the \fBskip\-logo.lua\fP script.
10378 If this script is dropped, or mpv ever gains a way to load user\-defined
10379 filters (other than VapourSynth), this filter will be removed. Due to the
10380 "special" nature of this filter, it will be removed without warning.
10381 .sp
10382 The intended way to read from the filter is using \fBvf\-metadata\fP (also
10383 see \fBclear\-on\-query\fP filter parameter). The property will return a list
10384 of key/value pairs as follows:
10385 .INDENT 7.0
10386 .INDENT 3.5
10387 .sp
10388 .nf
10389 .ft C
10390 fp0.pts = 1.2345
10391 fp0.hex = 1234abcdef...bcde
10392 fp1.pts = 1.4567
10393 fp1.hex = abcdef1234...6789
10394 \&...
10395 fpN.pts = ...
10396 fpN.hex = ...
10397 type = gray\-hex\-16x16
10398 .ft P
10399 .fi
10400 .UNINDENT
10401 .UNINDENT
10402 .sp
10403 Each \fBfp<N>\fP entry is for a frame. The \fBpts\fP entry specifies the
10404 timestamp of the frame (within the filter chain; in simple cases this is
10405 the same as the display timestamp). The \fBhex\fP field is the hex encoded
10406 fingerprint, whose size and meaning depend on the \fBtype\fP filter option.
10407 The \fBtype\fP field has the same value as the option the filter was created
10408 with.
10409 .sp
10410 This returns the frames that were filtered since the last query of the
10411 property. If \fBclear\-on\-query=no\fP was set, a query doesn\(aqt reset the list
10412 of frames. In both cases, a maximum of 10 frames is returned. If there are
10413 more frames, the oldest frames are discarded. Frames are returned in filter
10414 order.
10415 .sp
10416 (This doesn\(aqt return a structured list for the per\-frame details because the
10417 internals of the \fBvf\-metadata\fP mechanism suck. The returned format may
10418 change in the future.)
10419 .sp
10420 This filter uses zimg for speed and profit. However, it will fallback to
10421 libswscale in a number of situations: lesser pixel formats, unaligned data
10422 pointers or strides, or if zimg fails to initialize for unknown reasons. In
10423 these cases, the filter will use more CPU. Also, it will output different
10424 fingerprints, because libswscale cannot perform the full range expansion we
10425 normally request from zimg. As a consequence, the filter may be slower and
10426 not work correctly in random situations.
10427 .INDENT 7.0
10428 .TP
10429 .B \fBtype=...\fP
10430 What fingerprint to compute. Available types are:
10431 .INDENT 7.0
10432 .TP
10433 .B gray\-hex\-8x8
10434 grayscale, 8 bit, 8x8 size
10435 .TP
10436 .B gray\-hex\-16x16
10437 grayscale, 8 bit, 16x16 size (default)
10438 .UNINDENT
10439 .sp
10440 Both types simply remove all colors, downscale the image, concatenate
10441 all pixel values to a byte array, and convert the array to a hex string.
10442 .TP
10443 .B \fBclear\-on\-query=yes|no\fP
10444 Clear the list of frame fingerprints if the \fBvf\-metadata\fP property for
10445 this filter is queried (default: yes). This requires some care by the
10446 user. Some types of accesses might query the filter multiple times,
10447 which leads to lost frames.
10448 .TP
10449 .B \fBprint=yes|no\fP
10450 Print computed fingerprints the the terminal (default: no). This is
10451 mostly for testing and such. Scripts should use \fBvf\-metadata\fP to
10452 read information from this filter instead.
10453 .UNINDENT
10454 .UNINDENT
10455 .SH ENCODING
10456 .sp
10457 You can encode files from one format/codec to another using this facility.
10458 .INDENT 0.0
10459 .TP
10460 .B \fB\-\-o=<filename>\fP
10461 Enables encoding mode and specifies the output file name.
10462 .TP
10463 .B \fB\-\-of=<format>\fP
10464 Specifies the output format (overrides autodetection by the file name
10465 extension of the file specified by \fB\-o\fP). See \fB\-\-of=help\fP for a full
10466 list of supported formats.
10467 .TP
10468 .B \fB\-\-ofopts=<options>\fP
10469 Specifies the output format options for libavformat.
10470 See \fB\-\-ofopts=help\fP for a full list of supported options.
10471 .sp
10472 Options are managed in lists. There are a few commands to manage the
10473 options list.
10474 .INDENT 7.0
10475 .TP
10476 .B \fB\-\-ofopts\-add=<options1[,options2,...]>\fP
10477 Appends the options given as arguments to the options list.
10478 .TP
10479 .B \fB\-\-ofopts=""\fP
10480 Completely empties the options list.
10481 .UNINDENT
10482 .TP
10483 .B \fB\-\-oac=<codec>\fP
10484 Specifies the output audio codec. See \fB\-\-oac=help\fP for a full list of
10485 supported codecs.
10486 .TP
10487 .B \fB\-\-oaoffset=<value>\fP
10488 Shifts audio data by the given time (in seconds) by adding/removing
10489 samples at the start. Deprecated.
10490 .TP
10491 .B \fB\-\-oacopts=<options>\fP
10492 Specifies the output audio codec options for libavcodec.
10493 See \fB\-\-oacopts=help\fP for a full list of supported options.
10494 .INDENT 7.0
10495 .INDENT 3.5
10496 .IP "Example"
10497 .INDENT 0.0
10498 .TP
10499 .B "\fB\-\-oac=libmp3lame \-\-oacopts=b=128000\fP"
10500 selects 128 kbps MP3 encoding.
10501 .UNINDENT
10502 .UNINDENT
10503 .UNINDENT
10504 .sp
10505 Options are managed in lists. There are a few commands to manage the
10506 options list.
10507 .INDENT 7.0
10508 .TP
10509 .B \fB\-\-oacopts\-add=<options1[,options2,...]>\fP
10510 Appends the options given as arguments to the options list.
10511 .TP
10512 .B \fB\-\-oacopts=""\fP
10513 Completely empties the options list.
10514 .UNINDENT
10515 .TP
10516 .B \fB\-\-oafirst\fP
10517 Force the audio stream to become the first stream in the output.
10518 By default, the order is unspecified. Deprecated.
10519 .TP
10520 .B \fB\-\-ovc=<codec>\fP
10521 Specifies the output video codec. See \fB\-\-ovc=help\fP for a full list of
10522 supported codecs.
10523 .TP
10524 .B \fB\-\-ovoffset=<value>\fP
10525 Shifts video data by the given time (in seconds) by shifting the pts
10526 values. Deprecated.
10527 .TP
10528 .B \fB\-\-ovcopts=<options>\fP
10529 Specifies the output video codec options for libavcodec.
10530 See \-\-ovcopts=help for a full list of supported options.
10531 .INDENT 7.0
10532 .INDENT 3.5
10533 .IP "Examples"
10534 .INDENT 0.0
10535 .TP
10536 .B \fB"\-\-ovc=mpeg4 \-\-ovcopts=qscale=5"\fP
10537 selects constant quantizer scale 5 for MPEG\-4 encoding.
10538 .TP
10539 .B \fB"\-\-ovc=libx264 \-\-ovcopts=crf=23"\fP
10540 selects VBR quality factor 23 for H.264 encoding.
10541 .UNINDENT
10542 .UNINDENT
10543 .UNINDENT
10544 .sp
10545 Options are managed in lists. There are a few commands to manage the
10546 options list.
10547 .INDENT 7.0
10548 .TP
10549 .B \fB\-\-ovcopts\-add=<options1[,options2,...]>\fP
10550 Appends the options given as arguments to the options list.
10551 .TP
10552 .B \fB\-\-ovcopts=""\fP
10553 Completely empties the options list.
10554 .UNINDENT
10555 .TP
10556 .B \fB\-\-ovfirst\fP
10557 Force the video stream to become the first stream in the output.
10558 By default, the order is unspecified. Deprecated.
10559 .TP
10560 .B \fB\-\-orawts\fP
10561 Copies input pts to the output video (not supported by some output
10562 container formats, e.g. AVI). In this mode, discontinuities are not fixed
10563 and all pts are passed through as\-is. Never seek backwards or use multiple
10564 input files in this mode!
10565 .TP
10566 .B \fB\-\-no\-ocopy\-metadata\fP
10567 Turns off copying of metadata from input files to output files when
10568 encoding (which is enabled by default).
10569 .TP
10570 .B \fB\-\-oset\-metadata=<metadata\-tag[,metadata\-tag,...]>\fP
10571 Specifies metadata to include in the output file.
10572 Supported keys vary between output formats. For example, Matroska (MKV) and
10573 FLAC allow almost arbitrary keys, while support in MP4 and MP3 is more
10574 limited.
10575 .INDENT 7.0
10576 .INDENT 3.5
10577 .IP "Example"
10578 .INDENT 0.0
10579 .TP
10580 .B "\fB\-\-oset\-metadata=title="Output title",comment="Another tag"\fP"
10581 adds a title and a comment to the output file.
10582 .UNINDENT
10583 .UNINDENT
10584 .UNINDENT
10585 .TP
10586 .B \fB\-\-oremove\-metadata=<metadata\-tag[,metadata\-tag,...]>\fP
10587 Specifies metadata to exclude from the output file when copying from the
10588 input file.
10589 .INDENT 7.0
10590 .INDENT 3.5
10591 .IP "Example"
10592 .INDENT 0.0
10593 .TP
10594 .B "\fB\-\-oremove\-metadata=comment,genre\fP"
10595 excludes copying of the the comment and genre tags to the output
10596 file.
10597 .UNINDENT
10598 .UNINDENT
10599 .UNINDENT
10600 .UNINDENT
10601 .SH COMMAND INTERFACE
10602 .sp
10603 The mpv core can be controlled with commands and properties. A number of ways
10604 to interact with the player use them: key bindings (\fBinput.conf\fP), OSD
10605 (showing information with properties), JSON IPC, the client API (\fBlibmpv\fP),
10606 and the classic slave mode.
10607 .SS input.conf
10608 .sp
10609 The input.conf file consists of a list of key bindings, for example:
10610 .INDENT 0.0
10611 .INDENT 3.5
10612 .sp
10613 .nf
10614 .ft C
10615 s screenshot # take a screenshot with the s key
10616 LEFT seek 15 # map the left\-arrow key to seeking forward by 15 seconds
10617 .ft P
10618 .fi
10619 .UNINDENT
10620 .UNINDENT
10621 .sp
10622 Each line maps a key to an input command. Keys are specified with their literal
10623 value (upper case if combined with \fBShift\fP), or a name for special keys. For
10624 example, \fBa\fP maps to the \fBa\fP key without shift, and \fBA\fP maps to \fBa\fP
10625 with shift.
10626 .sp
10627 The file is located in the mpv configuration directory (normally at
10628 \fB~/.config/mpv/input.conf\fP depending on platform). The default bindings are
10629 defined here:
10630 .INDENT 0.0
10631 .INDENT 3.5
10632 .sp
10633 .nf
10634 .ft C
10635 https://github.com/mpv\-player/mpv/blob/master/etc/input.conf
10636 .ft P
10637 .fi
10638 .UNINDENT
10639 .UNINDENT
10640 .sp
10641 A list of special keys can be obtained with
10642 .INDENT 0.0
10643 .INDENT 3.5
10644 \fBmpv \-\-input\-keylist\fP
10645 .UNINDENT
10646 .UNINDENT
10647 .sp
10648 In general, keys can be combined with \fBShift\fP, \fBCtrl\fP and \fBAlt\fP:
10649 .INDENT 0.0
10650 .INDENT 3.5
10651 .sp
10652 .nf
10653 .ft C
10654 ctrl+q quit
10655 .ft P
10656 .fi
10657 .UNINDENT
10658 .UNINDENT
10659 .sp
10660 \fBmpv\fP can be started in input test mode, which displays key bindings and the
10661 commands they\(aqre bound to on the OSD, instead of executing the commands:
10662 .INDENT 0.0
10663 .INDENT 3.5
10664 .sp
10665 .nf
10666 .ft C
10667 mpv \-\-input\-test \-\-force\-window \-\-idle
10668 .ft P
10669 .fi
10670 .UNINDENT
10671 .UNINDENT
10672 .sp
10673 (Only closing the window will make \fBmpv\fP exit, pressing normal keys will
10674 merely display the binding, even if mapped to quit.)
10675 .SS input.conf syntax
10676 .sp
10677 \fB[Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] <command> ( ; <command> )*\fP
10678 .sp
10679 Note that by default, the right Alt key can be used to create special
10680 characters, and thus does not register as a modifier. The option
10681 \fB\-\-no\-input\-right\-alt\-gr\fP changes this behavior.
10682 .sp
10683 Newlines always start a new binding. \fB#\fP starts a comment (outside of quoted
10684 string arguments). To bind commands to the \fB#\fP key, \fBSHARP\fP can be used.
10685 .sp
10686 \fB<key>\fP is either the literal character the key produces (ASCII or Unicode
10687 character), or a symbolic name (as printed by \fB\-\-input\-keylist\fP).
10688 .sp
10689 \fB<section>\fP (braced with \fB{\fP and \fB}\fP) is the input section for this
10690 command.
10691 .sp
10692 \fB<command>\fP is the command itself. It consists of the command name and
10693 multiple (or none) commands, all separated by whitespace. String arguments
10694 need to be quoted with \fB"\fP\&. Details see \fBFlat command syntax\fP\&.
10695 .sp
10696 You can bind multiple commands to one key. For example:
10697 .nf
10698 a show\-text "command 1" ; show\-text "command 2"
10699 .fi
10700 .sp
10701 .sp
10702 It\(aqs also possible to bind a command to a sequence of keys:
10703 .nf
10704 a\-b\-c show\-text "command run after a, b, c have been pressed"
10705 .fi
10706 .sp
10707 .sp
10708 (This is not shown in the general command syntax.)
10709 .sp
10710 If \fBa\fP or \fBa\-b\fP or \fBb\fP are already bound, this will run the first command
10711 that matches, and the multi\-key command will never be called. Intermediate keys
10712 can be remapped to \fBignore\fP in order to avoid this issue. The maximum number
10713 of (non\-modifier) keys for combinations is currently 4.
10714 .SS Flat command syntax
10715 .sp
10716 This is the syntax used in input.conf, and referred to "input.conf syntax" in
10717 a number of other places.
10718 .sp
10719 \fB<command> ::= [<prefixes>] <command_name> (<argument>)*\fP
10720 \fB<argument> ::= (<string> | " <quoted_string> " )\fP
10721 .sp
10722 \fBcommand_name\fP is an unquoted string with the command name itself. See
10723 \fI\%List of Input Commands\fP for a list.
10724 .sp
10725 Arguments are separated by whitespace. This applies even to string arguments.
10726 For this reason, string arguments should be quoted with \fB"\fP\&. If a string
10727 argument contains spaces or certain special characters, quoting and possibly
10728 escaping is mandatory, or the command cannot be parsed correctly.
10729 .sp
10730 Inside quotes, C\-style escaping can be used. JSON escapes according to RFC 8259,
10731 minus surrogate pair escapes, should be a safe subset that can be used.
10732 .SS Commands specified as arrays
10733 .sp
10734 This applies to certain APIs, such as \fBmp.commandv()\fP or
10735 \fBmp.command_native()\fP (with array parameters) in Lua scripting, or
10736 \fBmpv_command()\fP or \fBmpv_command_node()\fP (with MPV_FORMAT_NODE_ARRAY) in the
10737 C libmpv client API.
10738 .sp
10739 The command as well as all arguments are passed as a single array. Similar to
10740 the \fI\%Flat command syntax\fP, you can first pass prefixes as strings (each as
10741 separate array item), then the command name as string, and then each argument
10742 as string or a native value.
10743 .sp
10744 Since these APIs pass arguments as separate strings or native values, they do
10745 not expect quotes, and do support escaping. Technically, there is the input.conf
10746 parser, which first splits the command string into arguments, and then invokes
10747 argument parsers for each argument. The input.conf parser normally handles
10748 quotes and escaping. The array command APIs mentioned above pass strings
10749 directly to the argument parsers, or can sidestep them by the ability to pass
10750 non\-string values.
10751 .sp
10752 Sometimes commands have string arguments, that in turn are actually parsed by
10753 other components (e.g. filter strings with \fBvf add\fP) \- in these cases, you
10754 you would have to double\-escape in input.conf, but not with the array APIs.
10755 .sp
10756 For complex commands, consider using \fI\%Named arguments\fP instead, which should
10757 give slightly more compatibility. Some commands do not support named arguments
10758 and inherently take an array, though.
10759 .SS Named arguments
10760 .sp
10761 This applies to certain APIs, such as \fBmp.command_native()\fP (with tables that
10762 have string keys) in Lua scripting, or \fBmpv_command_node()\fP (with
10763 MPV_FORMAT_NODE_MAP) in the C libmpv client API.
10764 .sp
10765 Like with array commands, quoting and escaping is inherently not needed in the
10766 normal case.
10767 .sp
10768 The name of each command is defined in each command description in the
10769 \fI\%List of Input Commands\fP\&. \fB\-\-input\-cmdlist\fP also lists them.
10770 .sp
10771 Some commands do not support named arguments (e.g. \fBrun\fP command). You need
10772 to use APIs that pass arguments as arrays.
10773 .sp
10774 Named arguments are not supported in the "flat" input.conf syntax, which means
10775 you cannot use them for key bindings in input.conf at all.
10776 .SS List of Input Commands
10777 .sp
10778 Commands with parameters have the parameter name enclosed in \fB<\fP / \fB>\fP\&.
10779 Don\(aqt add those to the actual command. Optional arguments are enclosed in
10780 \fB[\fP / \fB]\fP\&. If you don\(aqt pass them, they will be set to a default value.
10781 .sp
10782 Remember to quote string arguments in input.conf (see \fI\%Flat command syntax\fP).
10783 .INDENT 0.0
10784 .TP
10785 .B \fBignore\fP
10786 Use this to "block" keys that should be unbound, and do nothing. Useful for
10787 disabling default bindings, without disabling all bindings with
10788 \fB\-\-no\-input\-default\-bindings\fP\&.
10789 .TP
10790 .B \fBseek <target> [<flags>]\fP
10791 Change the playback position. By default, seeks by a relative amount of
10792 seconds.
10793 .sp
10794 The second argument consists of flags controlling the seek mode:
10795 .INDENT 7.0
10796 .TP
10797 .B relative (default)
10798 Seek relative to current position (a negative value seeks backwards).
10799 .TP
10800 .B absolute
10801 Seek to a given time (a negative value starts from the end of the file).
10802 .TP
10803 .B absolute\-percent
10804 Seek to a given percent position.
10805 .TP
10806 .B relative\-percent
10807 Seek relative to current position in percent.
10808 .TP
10809 .B keyframes
10810 Always restart playback at keyframe boundaries (fast).
10811 .TP
10812 .B exact
10813 Always do exact/hr/precise seeks (slow).
10814 .UNINDENT
10815 .sp
10816 Multiple flags can be combined, e.g.: \fBabsolute+keyframes\fP\&.
10817 .sp
10818 By default, \fBkeyframes\fP is used for \fBrelative\fP, \fBrelative\-percent\fP,
10819 and \fBabsolute\-percent\fP seeks, while \fBexact\fP is used for \fBabsolute\fP
10820 seeks.
10821 .sp
10822 Before mpv 0.9, the \fBkeyframes\fP and \fBexact\fP flags had to be passed as
10823 3rd parameter (essentially using a space instead of \fB+\fP). The 3rd
10824 parameter is still parsed, but is considered deprecated.
10825 .TP
10826 .B \fBrevert\-seek [<flags>]\fP
10827 Undoes the \fBseek\fP command, and some other commands that seek (but not
10828 necessarily all of them). Calling this command once will jump to the
10829 playback position before the seek. Calling it a second time undoes the
10830 \fBrevert\-seek\fP command itself. This only works within a single file.
10831 .sp
10832 The first argument is optional, and can change the behavior:
10833 .INDENT 7.0
10834 .TP
10835 .B mark
10836 Mark the current time position. The next normal \fBrevert\-seek\fP command
10837 will seek back to this point, no matter how many seeks happened since
10838 last time.
10839 .UNINDENT
10840 .sp
10841 Using it without any arguments gives you the default behavior.
10842 .TP
10843 .B \fBframe\-step\fP
10844 Play one frame, then pause. Does nothing with audio\-only playback.
10845 .TP
10846 .B \fBframe\-back\-step\fP
10847 Go back by one frame, then pause. Note that this can be very slow (it tries
10848 to be precise, not fast), and sometimes fails to behave as expected. How
10849 well this works depends on whether precise seeking works correctly (e.g.
10850 see the \fB\-\-hr\-seek\-demuxer\-offset\fP option). Video filters or other video
10851 post\-processing that modifies timing of frames (e.g. deinterlacing) should
10852 usually work, but might make backstepping silently behave incorrectly in
10853 corner cases. Using \fB\-\-hr\-seek\-framedrop=no\fP should help, although it
10854 might make precise seeking slower.
10855 .sp
10856 This does not work with audio\-only playback.
10857 .TP
10858 .B \fBset <name> <value>\fP
10859 Set the given property or option to the given value.
10860 .TP
10861 .B \fBadd <name> [<value>]\fP
10862 Add the given value to the property or option. On overflow or underflow,
10863 clamp the property to the maximum. If \fB<value>\fP is omitted, assume \fB1\fP\&.
10864 .TP
10865 .B \fBcycle <name> [<value>]\fP
10866 Cycle the given property or option. The second argument can be \fBup\fP or
10867 \fBdown\fP to set the cycle direction. On overflow, set the property back to
10868 the minimum, on underflow set it to the maximum. If \fBup\fP or \fBdown\fP is
10869 omitted, assume \fBup\fP\&.
10870 .TP
10871 .B \fBmultiply <name> <value>\fP
10872 Similar to \fBadd\fP, but multiplies the property or option with the numeric
10873 value.
10874 .TP
10875 .B \fBscreenshot <flags>\fP
10876 Take a screenshot.
10877 .sp
10878 Multiple flags are available (some can be combined with \fB+\fP):
10879 .INDENT 7.0
10880 .TP
10881 .B <subtitles> (default)
10882 Save the video image, in its original resolution, and with subtitles.
10883 Some video outputs may still include the OSD in the output under certain
10884 circumstances.
10885 .TP
10886 .B <video>
10887 Like \fBsubtitles\fP, but typically without OSD or subtitles. The exact
10888 behavior depends on the selected video output.
10889 .TP
10890 .B <window>
10891 Save the contents of the mpv window. Typically scaled, with OSD and
10892 subtitles. The exact behavior depends on the selected video output, and
10893 if no support is available, this will act like \fBvideo\fP\&.
10894 .TP
10895 .B <each\-frame>
10896 Take a screenshot each frame. Issue this command again to stop taking
10897 screenshots. Note that you should disable frame\-dropping when using
10898 this mode \- or you might receive duplicate images in cases when a
10899 frame was dropped. This flag can be combined with the other flags,
10900 e.g. \fBvideo+each\-frame\fP\&.
10901 .UNINDENT
10902 .sp
10903 Older mpv versions required passing \fBsingle\fP and \fBeach\-frame\fP as
10904 second argument (and did not have flags). This syntax is still understood,
10905 but deprecated and might be removed in the future.
10906 .sp
10907 If you combine this command with another one using \fB;\fP, you can use the
10908 \fBasync\fP flag to make encoding/writing the image file asynchronous. For
10909 normal standalone commands, this is always asynchronous, and the flag has
10910 no effect. (This behavior changed with mpv 0.29.0.)
10911 .TP
10912 .B \fBscreenshot\-to\-file <filename> <flags>\fP
10913 Take a screenshot and save it to a given file. The format of the file will
10914 be guessed by the extension (and \fB\-\-screenshot\-format\fP is ignored \- the
10915 behavior when the extension is missing or unknown is arbitrary).
10916 .sp
10917 The second argument is like the first argument to \fBscreenshot\fP and
10918 supports \fBsubtitles\fP, \fBvideo\fP, \fBwindow\fP\&.
10919 .sp
10920 If the file already exists, it\(aqs overwritten.
10921 .sp
10922 Like all input command parameters, the filename is subject to property
10923 expansion as described in \fI\%Property Expansion\fP\&.
10924 .TP
10925 .B \fBplaylist\-next <flags>\fP
10926 Go to the next entry on the playlist.
10927 .sp
10928 First argument:
10929 .INDENT 7.0
10930 .TP
10931 .B weak (default)
10932 If the last file on the playlist is currently played, do nothing.
10933 .TP
10934 .B force
10935 Terminate playback if there are no more files on the playlist.
10936 .UNINDENT
10937 .TP
10938 .B \fBplaylist\-prev <flags>\fP
10939 Go to the previous entry on the playlist.
10940 .sp
10941 First argument:
10942 .INDENT 7.0
10943 .TP
10944 .B weak (default)
10945 If the first file on the playlist is currently played, do nothing.
10946 .TP
10947 .B force
10948 Terminate playback if the first file is being played.
10949 .UNINDENT
10950 .TP
10951 .B \fBloadfile <url> [<flags> [<options>]]\fP
10952 Load the given file or URL and play it.
10953 .sp
10954 Second argument:
10955 .INDENT 7.0
10956 .TP
10957 .B <replace> (default)
10958 Stop playback of the current file, and play the new file immediately.
10959 .TP
10960 .B <append>
10961 Append the file to the playlist.
10962 .TP
10963 .B <append\-play>
10964 Append the file, and if nothing is currently playing, start playback.
10965 (Always starts with the added file, even if the playlist was not empty
10966 before running this command.)
10967 .UNINDENT
10968 .sp
10969 The third argument is a list of options and values which should be set
10970 while the file is playing. It is of the form \fBopt1=value1,opt2=value2,..\fP\&.
10971 Not all options can be changed this way. Some options require a restart
10972 of the player.
10973 .TP
10974 .B \fBloadlist <url> [<flags>]\fP
10975 Load the given playlist file or URL (like \fB\-\-playlist\fP).
10976 .sp
10977 Second argument:
10978 .INDENT 7.0
10979 .TP
10980 .B <replace> (default)
10981 Stop playback and replace the internal playlist with the new one.
10982 .TP
10983 .B <append>
10984 Append the new playlist at the end of the current internal playlist.
10985 .UNINDENT
10986 .TP
10987 .B \fBplaylist\-clear\fP
10988 Clear the playlist, except the currently played file.
10989 .TP
10990 .B \fBplaylist\-remove <index>\fP
10991 Remove the playlist entry at the given index. Index values start counting
10992 with 0. The special value \fBcurrent\fP removes the current entry. Note that
10993 removing the current entry also stops playback and starts playing the next
10994 entry.
10995 .TP
10996 .B \fBplaylist\-move <index1> <index2>\fP
10997 Move the playlist entry at index1, so that it takes the place of the
10998 entry index2. (Paradoxically, the moved playlist entry will not have
10999 the index value index2 after moving if index1 was lower than index2,
11000 because index2 refers to the target entry, not the index the entry
11001 will have after moving.)
11002 .TP
11003 .B \fBplaylist\-shuffle\fP
11004 Shuffle the playlist. This is similar to what is done on start if the
11005 \fB\-\-shuffle\fP option is used.
11006 .TP
11007 .B \fBrun <command> [<arg1> [<arg2> [...]]]\fP
11008 Run the given command. Unlike in MPlayer/mplayer2 and earlier versions of
11009 mpv (0.2.x and older), this doesn\(aqt call the shell. Instead, the command
11010 is run directly, with each argument passed separately. Each argument is
11011 expanded like in \fI\%Property Expansion\fP\&.
11012 .sp
11013 This command has a variable number of arguments, and cannot be used with
11014 named arguments.
11015 .sp
11016 The program is run in a detached way. mpv doesn\(aqt wait until the command
11017 is completed, but continues playback right after spawning it.
11018 .sp
11019 To get the old behavior, use \fB/bin/sh\fP and \fB\-c\fP as the first two
11020 arguments.
11021 .INDENT 7.0
11022 .INDENT 3.5
11023 .IP "Example"
11024 .sp
11025 \fBrun "/bin/sh" "\-c" "echo ${title} > /tmp/playing"\fP
11026 .sp
11027 This is not a particularly good example, because it doesn\(aqt handle
11028 escaping, and a specially prepared file might allow an attacker to
11029 execute arbitrary shell commands. It is recommended to write a small
11030 shell script, and call that with \fBrun\fP\&.
11031 .UNINDENT
11032 .UNINDENT
11033 .TP
11034 .B \fBsubprocess\fP
11035 Similar to \fBrun\fP, but gives more control about process execution to the
11036 caller, and does does not detach the process.
11037 .sp
11038 You can avoid blocking until the process terminates by running this command
11039 asynchronously. (For example \fBmp.command_native_async()\fP in Lua scripting.)
11040 .sp
11041 This has the following named arguments. The order of them is not guaranteed,
11042 so you should always call them with named arguments, see \fI\%Named arguments\fP\&.
11043 .INDENT 7.0
11044 .TP
11045 .B \fBargs\fP (\fBMPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING]\fP)
11046 Array of strings with the command as first argument, and subsequent
11047 command line arguments following. This is just like the \fBrun\fP command
11048 argument list.
11049 .sp
11050 The first array entry is either an absolute path to the executable, or
11051 a filename with no path components, in which case the \fBPATH\fP
11052 environment variable. On Unix, this is equivalent to \fBposix_spawnp\fP
11053 and \fBexecvp\fP behavior.
11054 .TP
11055 .B \fBplayback_only\fP (\fBMPV_FORMAT_FLAG\fP)
11056 Boolean indicating whether the process should be killed when playback
11057 terminates (optional, default: yes). If enabled, stopping playback
11058 will automatically kill the process, and you can\(aqt start it outside of
11059 playback.
11060 .TP
11061 .B \fBcapture_size\fP (\fBMPV_FORMAT_INT64\fP)
11062 Integer setting the maximum number of stdout plus stderr bytes that can
11063 be captured (optional, default: 64MB). If the number of bytes exceeds
11064 this, capturing is stopped. The limit is per captured stream.
11065 .TP
11066 .B \fBcapture_stdout\fP (\fBMPV_FORMAT_FLAG\fP)
11067 Capture all data the process outputs to stdout and return it once the
11068 process ends (optional, default: no).
11069 .TP
11070 .B \fBcapture_stderr\fP (\fBMPV_FORMAT_FLAG\fP)
11071 Same as \fBcapture_stdout\fP, but for stderr.
11072 .UNINDENT
11073 .sp
11074 The command returns the following result (as \fBMPV_FORMAT_NODE_MAP\fP):
11075 .INDENT 7.0
11076 .TP
11077 .B \fBstatus\fP (\fBMPV_FORMAT_INT64\fP)
11078 The raw exit status of the process. It will be negative on error. The
11079 meaning of negative values is undefined, other than meaning error (and
11080 does not necessarily correspond to OS low level exit status values).
11081 .sp
11082 On Windows, it can happen that a negative return value is returned
11083 even if the process exits gracefully, because the win32 \fBUINT\fP exit
11084 code is assigned to an \fBint\fP variable before being set as \fBint64_t\fP
11085 field in the result map. This might be fixed later.
11086 .TP
11087 .B \fBstdout\fP (\fBMPV_FORMAT_BYTE_ARRAY\fP)
11088 Captured stdout stream, limited to \fBcapture_size\fP\&.
11089 .TP
11090 .B \fBstderr\fP (\fBMPV_FORMAT_BYTE_ARRAY\fP)
11091 Same as \fBstdout\fP, but for stderr.
11092 .TP
11093 .B \fBerror_string\fP (\fBMPV_FORMAT_STRING\fP)
11094 Empty string if the process exited gracefully. The string \fBkilled\fP if
11095 the process was terminated in an unusual way. The string \fBinit\fP if the
11096 process could not be started.
11097 .sp
11098 On Windows, \fBkilled\fP is only returned when the process has been
11099 killed by mpv as a result of \fBplayback_only\fP being set to \fByes\fP\&.
11100 .TP
11101 .B \fBkilled_by_us\fP (\fBMPV_FORMAT_FLAG\fP)
11102 Set to \fByes\fP if the process has been killed by mpv, for example as a
11103 result of \fBplayback_only\fP being set to \fByes\fP, aborting the command
11104 (e.g. by \fBmp.abort_async_command()\fP), or if the player is about to
11105 exit.
11106 .UNINDENT
11107 .sp
11108 Note that the command itself will always return success as long as the
11109 parameters are correct. Whether the process could be spawned or whether
11110 it was somehow killed or returned an error status has to be queried from
11111 the result value.
11112 .sp
11113 This command can be asynchronously aborted via API.
11114 .sp
11115 In all cases, the subprocess will be terminated on player exit. Also see
11116 \fI\%Asynchronous command details\fP\&. Only the \fBrun\fP command can start
11117 processes in a truly detached way.
11118 .INDENT 7.0
11119 .INDENT 3.5
11120 .IP "Warning"
11121 .sp
11122 Don\(aqt forget to set the \fBplayback_only\fP field if you want the command
11123 run while the player is in idle mode, or if you don\(aqt want that end of
11124 playback kills the command.
11125 .UNINDENT
11126 .UNINDENT
11127 .TP
11128 .B \fBquit [<code>]\fP
11129 Exit the player. If an argument is given, it\(aqs used as process exit code.
11130 .TP
11131 .B \fBquit\-watch\-later [<code>]\fP
11132 Exit player, and store current playback position. Playing that file later
11133 will seek to the previous position on start. The (optional) argument is
11134 exactly as in the \fBquit\fP command.
11135 .TP
11136 .B \fBsub\-add <url> [<flags> [<title> [<lang>]]]\fP
11137 Load the given subtitle file or stream. By default, it is selected as
11138 current subtitle after loading.
11139 .sp
11140 The \fBflags\fP argument is one of the following values:
11141 .sp
11142 <select>
11143 .INDENT 7.0
11144 .INDENT 3.5
11145 Select the subtitle immediately (default).
11146 .UNINDENT
11147 .UNINDENT
11148 .sp
11149 <auto>
11150 .INDENT 7.0
11151 .INDENT 3.5
11152 Don\(aqt select the subtitle. (Or in some special situations, let the
11153 default stream selection mechanism decide.)
11154 .UNINDENT
11155 .UNINDENT
11156 .sp
11157 <cached>
11158 .INDENT 7.0
11159 .INDENT 3.5
11160 Select the subtitle. If a subtitle with the same filename was already
11161 added, that one is selected, instead of loading a duplicate entry.
11162 (In this case, title/language are ignored, and if the was changed since
11163 it was loaded, these changes won\(aqt be reflected.)
11164 .UNINDENT
11165 .UNINDENT
11166 .sp
11167 The \fBtitle\fP argument sets the track title in the UI.
11168 .sp
11169 The \fBlang\fP argument sets the track language, and can also influence
11170 stream selection with \fBflags\fP set to \fBauto\fP\&.
11171 .TP
11172 .B \fBsub\-remove [<id>]\fP
11173 Remove the given subtitle track. If the \fBid\fP argument is missing, remove
11174 the current track. (Works on external subtitle files only.)
11175 .TP
11176 .B \fBsub\-reload [<id>]\fP
11177 Reload the given subtitle tracks. If the \fBid\fP argument is missing, reload
11178 the current track. (Works on external subtitle files only.)
11179 .sp
11180 This works by unloading and re\-adding the subtitle track.
11181 .TP
11182 .B \fBsub\-step <skip>\fP
11183 Change subtitle timing such, that the subtitle event after the next
11184 \fB<skip>\fP subtitle events is displayed. \fB<skip>\fP can be negative to step
11185 backwards.
11186 .TP
11187 .B \fBsub\-seek <skip>\fP
11188 Seek to the next (skip set to 1) or the previous (skip set to \-1) subtitle.
11189 This is similar to \fBsub\-step\fP, except that it seeks video and audio
11190 instead of adjusting the subtitle delay.
11191 .sp
11192 For embedded subtitles (like with Matroska), this works only with subtitle
11193 events that have already been displayed, or are within a short prefetch
11194 range.
11195 .TP
11196 .B \fBprint\-text <text>\fP
11197 Print text to stdout. The string can contain properties (see
11198 \fI\%Property Expansion\fP). Take care to put the argument in quotes.
11199 .TP
11200 .B \fBshow\-text <text> [<duration>|\-1 [<level>]]\fP
11201 Show text on the OSD. The string can contain properties, which are expanded
11202 as described in \fI\%Property Expansion\fP\&. This can be used to show playback
11203 time, filename, and so on.
11204 .INDENT 7.0
11205 .TP
11206 .B <duration>
11207 The time in ms to show the message for. By default, it uses the same
11208 value as \fB\-\-osd\-duration\fP\&.
11209 .TP
11210 .B <level>
11211 The minimum OSD level to show the text at (see \fB\-\-osd\-level\fP).
11212 .UNINDENT
11213 .TP
11214 .B \fBexpand\-text <string>\fP
11215 Property\-expand the argument and return the expanded string. This can be
11216 used only through the client API or from a script using
11217 \fBmp.command_native\fP\&. (see \fI\%Property Expansion\fP).
11218 .TP
11219 .B \fBexpand\-path "<string>"\fP
11220 Expand a path\(aqs double\-tilde placeholders into a platform\-specific path.
11221 As \fBexpand\-text\fP, this can only be used through the client API or from
11222 a script using \fBmp.command_native\fP\&.
11223 .INDENT 7.0
11224 .INDENT 3.5
11225 .IP "Example"
11226 .sp
11227 \fBmp.osd_message(mp.command_native({"expand\-path", "~~home/"}))\fP
11228 .sp
11229 This line of Lua would show the location of the user\(aqs mpv
11230 configuration directory on the OSD.
11231 .UNINDENT
11232 .UNINDENT
11233 .TP
11234 .B \fBshow\-progress\fP
11235 Show the progress bar, the elapsed time and the total duration of the file
11236 on the OSD.
11237 .TP
11238 .B \fBwrite\-watch\-later\-config\fP
11239 Write the resume config file that the \fBquit\-watch\-later\fP command writes,
11240 but continue playback normally.
11241 .TP
11242 .B \fBstop\fP
11243 Stop playback and clear playlist. With default settings, this is
11244 essentially like \fBquit\fP\&. Useful for the client API: playback can be
11245 stopped without terminating the player.
11246 .TP
11247 .B \fBmouse <x> <y> [<button> [<mode>]]\fP
11248 Send a mouse event with given coordinate (\fB<x>\fP, \fB<y>\fP).
11249 .sp
11250 Second argument:
11251 .INDENT 7.0
11252 .TP
11253 .B <button>
11254 The button number of clicked mouse button. This should be one of 0\-19.
11255 If \fB<button>\fP is omitted, only the position will be updated.
11256 .UNINDENT
11257 .sp
11258 Third argument:
11259 .INDENT 7.0
11260 .TP
11261 .B <single> (default)
11262 The mouse event represents regular single click.
11263 .TP
11264 .B <double>
11265 The mouse event represents double\-click.
11266 .UNINDENT
11267 .TP
11268 .B \fBkeypress <name>\fP
11269 Send a key event through mpv\(aqs input handler, triggering whatever
11270 behavior is configured to that key. \fBname\fP uses the \fBinput.conf\fP
11271 naming scheme for keys and modifiers. Useful for the client API: key events
11272 can be sent to libmpv to handle internally.
11273 .TP
11274 .B \fBkeydown <name>\fP
11275 Similar to \fBkeypress\fP, but sets the \fBKEYDOWN\fP flag so that if the key is
11276 bound to a repeatable command, it will be run repeatedly with mpv\(aqs key
11277 repeat timing until the \fBkeyup\fP command is called.
11278 .TP
11279 .B \fBkeyup [<name>]\fP
11280 Set the \fBKEYUP\fP flag, stopping any repeated behavior that had been
11281 triggered. \fBname\fP is optional. If \fBname\fP is not given or is an
11282 empty string, \fBKEYUP\fP will be set on all keys. Otherwise, \fBKEYUP\fP will
11283 only be set on the key specified by \fBname\fP\&.
11284 .TP
11285 .B \fBkeybind <name> <command>\fP
11286 Binds a key to an input command. \fBcommand\fP must be a complete command
11287 containing all the desired arguments and flags. Both \fBname\fP and
11288 \fBcommand\fP use the \fBinput.conf\fP naming scheme. This is primarily
11289 useful for the client API.
11290 .TP
11291 .B \fBaudio\-add <url> [<flags> [<title> [<lang>]]]\fP
11292 Load the given audio file. See \fBsub\-add\fP command.
11293 .TP
11294 .B \fBaudio\-remove [<id>]\fP
11295 Remove the given audio track. See \fBsub\-remove\fP command.
11296 .TP
11297 .B \fBaudio\-reload [<id>]\fP
11298 Reload the given audio tracks. See \fBsub\-reload\fP command.
11299 .TP
11300 .B \fBvideo\-add <url> [<flags> [<title> [<lang>]]]\fP
11301 Load the given video file. See \fBsub\-add\fP command.
11302 .TP
11303 .B \fBvideo\-remove [<id>]\fP
11304 Remove the given video track. See \fBsub\-remove\fP command.
11305 .TP
11306 .B \fBvideo\-reload [<id>]\fP
11307 Reload the given video tracks. See \fBsub\-reload\fP command.
11308 .TP
11309 .B \fBrescan\-external\-files [<mode>]\fP
11310 Rescan external files according to the current \fB\-\-sub\-auto\fP and
11311 \fB\-\-audio\-file\-auto\fP settings. This can be used to auto\-load external
11312 files \fIafter\fP the file was loaded.
11313 .sp
11314 The \fBmode\fP argument is one of the following:
11315 .INDENT 7.0
11316 .TP
11317 .B <reselect> (default)
11318 Select the default audio and subtitle streams, which typically selects
11319 external files with the highest preference. (The implementation is not
11320 perfect, and could be improved on request.)
11321 .TP
11322 .B <keep\-selection>
11323 Do not change current track selections.
11324 .UNINDENT
11325 .UNINDENT
11326 .SS Input Commands that are Possibly Subject to Change
11327 .INDENT 0.0
11328 .TP
11329 .B \fBaf <operation> <value>\fP
11330 Change audio filter chain. See \fBvf\fP command.
11331 .TP
11332 .B \fBvf <operation> <value>\fP
11333 Change video filter chain.
11334 .sp
11335 The first argument decides what happens:
11336 .INDENT 7.0
11337 .TP
11338 .B <set>
11339 Overwrite the previous filter chain with the new one.
11340 .TP
11341 .B <add>
11342 Append the new filter chain to the previous one.
11343 .TP
11344 .B <toggle>
11345 Check if the given filter (with the exact parameters) is already
11346 in the video chain. If yes, remove the filter. If no, add the filter.
11347 (If several filters are passed to the command, this is done for
11348 each filter.)
11349 .sp
11350 A special variant is combining this with labels, and using \fB@name\fP
11351 without filter name and parameters as filter entry. This toggles the
11352 enable/disable flag.
11353 .TP
11354 .B <del>
11355 Remove the given filters from the video chain. Unlike in the other
11356 cases, the second parameter is a comma separated list of filter names
11357 or integer indexes. \fB0\fP would denote the first filter. Negative
11358 indexes start from the last filter, and \fB\-1\fP denotes the last
11359 filter.
11360 .TP
11361 .B <clr>
11362 Remove all filters. Note that like the other sub\-commands, this does
11363 not control automatically inserted filters.
11364 .UNINDENT
11365 .sp
11366 The argument is always needed. E.g. in case of \fBclr\fP use \fBvf clr ""\fP\&.
11367 .sp
11368 You can assign labels to filter by prefixing them with \fB@name:\fP (where
11369 \fBname\fP is a user\-chosen arbitrary identifier). Labels can be used to
11370 refer to filters by name in all of the filter chain modification commands.
11371 For \fBadd\fP, using an already used label will replace the existing filter.
11372 .sp
11373 The \fBvf\fP command shows the list of requested filters on the OSD after
11374 changing the filter chain. This is roughly equivalent to
11375 \fBshow\-text ${vf}\fP\&. Note that auto\-inserted filters for format conversion
11376 are not shown on the list, only what was requested by the user.
11377 .sp
11378 Normally, the commands will check whether the video chain is recreated
11379 successfully, and will undo the operation on failure. If the command is run
11380 before video is configured (can happen if the command is run immediately
11381 after opening a file and before a video frame is decoded), this check can\(aqt
11382 be run. Then it can happen that creating the video chain fails.
11383 .INDENT 7.0
11384 .INDENT 3.5
11385 .IP "Example for input.conf"
11386 .INDENT 0.0
11387 .IP \(bu 2
11388 \fBa vf set flip\fP turn video upside\-down on the \fBa\fP key
11389 .IP \(bu 2
11390 \fBb vf set ""\fP remove all video filters on \fBb\fP
11391 .IP \(bu 2
11392 \fBc vf toggle gradfun\fP toggle debanding on \fBc\fP
11393 .UNINDENT
11394 .UNINDENT
11395 .UNINDENT
11396 .INDENT 7.0
11397 .INDENT 3.5
11398 .IP "Example how to toggle disabled filters at runtime"
11399 .INDENT 0.0
11400 .IP \(bu 2
11401 Add something like \fBvf\-add=@deband:!gradfun\fP to \fBmpv.conf\fP\&.
11402 The \fB@deband:\fP is the label, an arbitrary, user\-given name for this
11403 filter entry. The \fB!\fP before the filter name disables the filter by
11404 default. Everything after this is the normal filter name and possibly
11405 filter parameters, like in the normal \fB\-\-vf\fP syntax.
11406 .IP \(bu 2
11407 Add \fBa vf toggle @deband\fP to \fBinput.conf\fP\&. This toggles the
11408 "disabled" flag for the filter with the label \fBdeband\fP when the
11409 \fBa\fP key is hit.
11410 .UNINDENT
11411 .UNINDENT
11412 .UNINDENT
11413 .TP
11414 .B \fBcycle\-values [<"!reverse">] <property> <value1> [<value2> [...]]\fP
11415 Cycle through a list of values. Each invocation of the command will set the
11416 given property to the next value in the list. The command will use the
11417 current value of the property/option, and use it to determine the current
11418 position in the list of values. Once it has found it, it will set the
11419 next value in the list (wrapping around to the first item if needed).
11420 .sp
11421 This command has a variable number of arguments, and cannot be used with
11422 named arguments.
11423 .sp
11424 The special argument \fB!reverse\fP can be used to cycle the value list in
11425 reverse. The only advantage is that you don\(aqt need to reverse the value
11426 list yourself when adding a second key binding for cycling backwards.
11427 .TP
11428 .B \fBenable\-section <name> [<flags>]\fP
11429 Enable all key bindings in the named input section.
11430 .sp
11431 The enabled input sections form a stack. Bindings in sections on the top of
11432 the stack are preferred to lower sections. This command puts the section
11433 on top of the stack. If the section was already on the stack, it is
11434 implicitly removed beforehand. (A section cannot be on the stack more than
11435 once.)
11436 .sp
11437 The \fBflags\fP parameter can be a combination (separated by \fB+\fP) of the
11438 following flags:
11439 .INDENT 7.0
11440 .TP
11441 .B <exclusive>
11442 All sections enabled before the newly enabled section are disabled.
11443 They will be re\-enabled as soon as all exclusive sections above them
11444 are removed. In other words, the new section shadows all previous
11445 sections.
11446 .TP
11447 .B <allow\-hide\-cursor>
11448 This feature can\(aqt be used through the public API.
11449 .TP
11450 .B <allow\-vo\-dragging>
11451 Same.
11452 .UNINDENT
11453 .TP
11454 .B \fBdisable\-section <name>\fP
11455 Disable the named input section. Undoes \fBenable\-section\fP\&.
11456 .TP
11457 .B \fBdefine\-section <name> <contents> [<flags>]\fP
11458 Create a named input section, or replace the contents of an already existing
11459 input section. The \fBcontents\fP parameter uses the same syntax as the
11460 \fBinput.conf\fP file (except that using the section syntax in it is not
11461 allowed), including the need to separate bindings with a newline character.
11462 .sp
11463 If the \fBcontents\fP parameter is an empty string, the section is removed.
11464 .sp
11465 The section with the name \fBdefault\fP is the normal input section.
11466 .sp
11467 In general, input sections have to be enabled with the \fBenable\-section\fP
11468 command, or they are ignored.
11469 .sp
11470 The last parameter has the following meaning:
11471 .INDENT 7.0
11472 .TP
11473 .B <default> (also used if parameter omitted)
11474 Use a key binding defined by this section only if the user hasn\(aqt
11475 already bound this key to a command.
11476 .TP
11477 .B <force>
11478 Always bind a key. (The input section that was made active most recently
11479 wins if there are ambiguities.)
11480 .UNINDENT
11481 .sp
11482 This command can be used to dispatch arbitrary keys to a script or a client
11483 API user. If the input section defines \fBscript\-binding\fP commands, it is
11484 also possible to get separate events on key up/down, and relatively detailed
11485 information about the key state. The special key name \fBunmapped\fP can be
11486 used to match any unmapped key.
11487 .TP
11488 .B \fBoverlay\-add <id> <x> <y> <file> <offset> <fmt> <w> <h> <stride>\fP
11489 Add an OSD overlay sourced from raw data. This might be useful for scripts
11490 and applications controlling mpv, and which want to display things on top
11491 of the video window.
11492 .sp
11493 Overlays are usually displayed in screen resolution, but with some VOs,
11494 the resolution is reduced to that of the video\(aqs. You can read the
11495 \fBosd\-width\fP and \fBosd\-height\fP properties. At least with \fB\-\-vo\-xv\fP and
11496 anamorphic video (such as DVD), \fBosd\-par\fP should be read as well, and the
11497 overlay should be aspect\-compensated.
11498 .sp
11499 This has the following named arguments. The order of them is not guaranteed,
11500 so you should always call them with named arguments, see \fI\%Named arguments\fP\&.
11501 .sp
11502 \fBid\fP is an integer between 0 and 63 identifying the overlay element. The
11503 ID can be used to add multiple overlay parts, update a part by using this
11504 command with an already existing ID, or to remove a part with
11505 \fBoverlay\-remove\fP\&. Using a previously unused ID will add a new overlay,
11506 while reusing an ID will update it.
11507 .sp
11508 \fBx\fP and \fBy\fP specify the position where the OSD should be displayed.
11509 .sp
11510 \fBfile\fP specifies the file the raw image data is read from. It can be
11511 either a numeric UNIX file descriptor prefixed with \fB@\fP (e.g. \fB@4\fP),
11512 or a filename. The file will be mapped into memory with \fBmmap()\fP,
11513 copied, and unmapped before the command returns (changed in mpv 0.18.1).
11514 .sp
11515 It is also possible to pass a raw memory address for use as bitmap memory
11516 by passing a memory address as integer prefixed with an \fB&\fP character.
11517 Passing the wrong thing here will crash the player. This mode might be
11518 useful for use with libmpv. The \fBoffset\fP parameter is simply added to the
11519 memory address (since mpv 0.8.0, ignored before).
11520 .sp
11521 \fBoffset\fP is the byte offset of the first pixel in the source file.
11522 (The current implementation always mmap\(aqs the whole file from position 0 to
11523 the end of the image, so large offsets should be avoided. Before mpv 0.8.0,
11524 the offset was actually passed directly to \fBmmap\fP, but it was changed to
11525 make using it easier.)
11526 .sp
11527 \fBfmt\fP is a string identifying the image format. Currently, only \fBbgra\fP
11528 is defined. This format has 4 bytes per pixels, with 8 bits per component.
11529 The least significant 8 bits are blue, and the most significant 8 bits
11530 are alpha (in little endian, the components are B\-G\-R\-A, with B as first
11531 byte). This uses premultiplied alpha: every color component is already
11532 multiplied with the alpha component. This means the numeric value of each
11533 component is equal to or smaller than the alpha component. (Violating this
11534 rule will lead to different results with different VOs: numeric overflows
11535 resulting from blending broken alpha values is considered something that
11536 shouldn\(aqt happen, and consequently implementations don\(aqt ensure that you
11537 get predictable behavior in this case.)
11538 .sp
11539 \fBw\fP, \fBh\fP, and \fBstride\fP specify the size of the overlay. \fBw\fP is the
11540 visible width of the overlay, while \fBstride\fP gives the width in bytes in
11541 memory. In the simple case, and with the \fBbgra\fP format, \fBstride==4*w\fP\&.
11542 In general, the total amount of memory accessed is \fBstride * h\fP\&.
11543 (Technically, the minimum size would be \fBstride * (h \- 1) + w * 4\fP, but
11544 for simplicity, the player will access all \fBstride * h\fP bytes.)
11545 .sp
11546 \fBNOTE:\fP
11547 .INDENT 7.0
11548 .INDENT 3.5
11549 Before mpv 0.18.1, you had to do manual "double buffering" when updating
11550 an overlay by replacing it with a different memory buffer. Since mpv
11551 0.18.1, the memory is simply copied and doesn\(aqt reference any of the
11552 memory indicated by the command\(aqs arguments after the commend returns.
11553 If you want to use this command before mpv 0.18.1, reads the old docs
11554 to see how to handle this correctly.
11555 .UNINDENT
11556 .UNINDENT
11557 .TP
11558 .B \fBoverlay\-remove <id>\fP
11559 Remove an overlay added with \fBoverlay\-add\fP and the same ID. Does nothing
11560 if no overlay with this ID exists.
11561 .TP
11562 .B \fBscript\-message [<arg1> [<arg2> [...]]]\fP
11563 Send a message to all clients, and pass it the following list of arguments.
11564 What this message means, how many arguments it takes, and what the arguments
11565 mean is fully up to the receiver and the sender. Every client receives the
11566 message, so be careful about name clashes (or use \fBscript\-message\-to\fP).
11567 .sp
11568 This command has a variable number of arguments, and cannot be used with
11569 named arguments.
11570 .TP
11571 .B \fBscript\-message\-to <target> [<arg1> [<arg2> [...]]]\fP
11572 Same as \fBscript\-message\fP, but send it only to the client named
11573 \fB<target>\fP\&. Each client (scripts etc.) has a unique name. For example,
11574 Lua scripts can get their name via \fBmp.get_script_name()\fP\&.
11575 .sp
11576 This command has a variable number of arguments, and cannot be used with
11577 named arguments.
11578 .TP
11579 .B \fBscript\-binding <name>\fP
11580 Invoke a script\-provided key binding. This can be used to remap key
11581 bindings provided by external Lua scripts.
11582 .sp
11583 The argument is the name of the binding.
11584 .sp
11585 It can optionally be prefixed with the name of the script, using \fB/\fP as
11586 separator, e.g. \fBscript\-binding scriptname/bindingname\fP\&.
11587 .sp
11588 For completeness, here is how this command works internally. The details
11589 could change any time. On any matching key event, \fBscript\-message\-to\fP
11590 or \fBscript\-message\fP is called (depending on whether the script name is
11591 included), with the following arguments:
11592 .INDENT 7.0
11593 .IP 1. 3
11594 The string \fBkey\-binding\fP\&.
11595 .IP 2. 3
11596 The name of the binding (as established above).
11597 .IP 3. 3
11598 The key state as string (see below).
11599 .IP 4. 3
11600 The key name (since mpv 0.15.0).
11601 .UNINDENT
11602 .sp
11603 The key state consists of 2 letters:
11604 .INDENT 7.0
11605 .IP 1. 3
11606 One of \fBd\fP (key was pressed down), \fBu\fP (was released), \fBr\fP (key
11607 is still down, and was repeated; only if key repeat is enabled for this
11608 binding), \fBp\fP (key was pressed; happens if up/down can\(aqt be tracked).
11609 .IP 2. 3
11610 Whether the event originates from the mouse, either \fBm\fP (mouse button)
11611 or \fB\-\fP (something else).
11612 .UNINDENT
11613 .TP
11614 .B \fBab\-loop\fP
11615 Cycle through A\-B loop states. The first command will set the \fBA\fP point
11616 (the \fBab\-loop\-a\fP property); the second the \fBB\fP point, and the third
11617 will clear both points.
11618 .TP
11619 .B \fBdrop\-buffers\fP
11620 Drop audio/video/demuxer buffers, and restart from fresh. Might help with
11621 unseekable streams that are going out of sync.
11622 This command might be changed or removed in the future.
11623 .TP
11624 .B \fBscreenshot\-raw [<flags>]\fP
11625 Return a screenshot in memory. This can be used only through the client
11626 API. The MPV_FORMAT_NODE_MAP returned by this command has the \fBw\fP, \fBh\fP,
11627 \fBstride\fP fields set to obvious contents. The \fBformat\fP field is set to
11628 \fBbgr0\fP by default. This format is organized as \fBB8G8R8X8\fP (where \fBB\fP
11629 is the LSB). The contents of the padding \fBX\fP are undefined. The \fBdata\fP
11630 field is of type MPV_FORMAT_BYTE_ARRAY with the actual image data. The image
11631 is freed as soon as the result mpv_node is freed. As usual with client API
11632 semantics, you are not allowed to write to the image data.
11633 .sp
11634 The \fBstride\fP is the number of bytes from a pixel at \fB(x0, y0)\fP to the
11635 pixel at \fB(x0, y0 + 1)\fP\&. This can be larger than \fBw * 4\fP if the image
11636 was cropped, or if there is padding. This number can be negative as well.
11637 You access a pixel with \fBbyte_index = y * stride + x * 4\fP (assuming the
11638 \fBbgr0\fP format).
11639 .sp
11640 The \fBflags\fP argument is like the first argument to \fBscreenshot\fP and
11641 supports \fBsubtitles\fP, \fBvideo\fP, \fBwindow\fP\&.
11642 .TP
11643 .B \fBvf\-command <label> <command> <argument>\fP
11644 Send a command to the filter with the given \fB<label>\fP\&. Use \fBall\fP to send
11645 it to all filters at once. The command and argument string is filter
11646 specific. Currently, this only works with the \fBlavfi\fP filter \- see
11647 the libavfilter documentation for which commands a filter supports.
11648 .sp
11649 Note that the \fB<label>\fP is a mpv filter label, not a libavfilter filter
11650 name.
11651 .TP
11652 .B \fBaf\-command <label> <command> <argument>\fP
11653 Same as \fBvf\-command\fP, but for audio filters.
11654 .TP
11655 .B \fBapply\-profile <name>\fP
11656 Apply the contents of a named profile. This is like using \fBprofile=name\fP
11657 in a config file, except you can map it to a key binding to change it at
11658 runtime.
11659 .sp
11660 There is no such thing as "unapplying" a profile \- applying a profile
11661 merely sets all option values listed within the profile.
11662 .TP
11663 .B \fBload\-script <filename>\fP
11664 Load a script, similar to the \fB\-\-script\fP option. Whether this waits for
11665 the script to finish initialization or not changed multiple times, and the
11666 future behavior is left undefined.
11667 .TP
11668 .B \fBchange\-list <name> <operation> <value>\fP
11669 This command changes list options as described in \fI\%List Options\fP\&. The
11670 \fB<name>\fP parameter is the normal option name, while \fB<operation>\fP is
11671 the suffix or action used on the option.
11672 .sp
11673 Some operations take no value, but the command still requires the value
11674 parameter. In these cases, the value must be an empty string.
11675 .INDENT 7.0
11676 .INDENT 3.5
11677 .IP "Example"
11678 .sp
11679 \fBchange\-list glsl\-shaders append file.glsl\fP
11680 .sp
11681 Add a filename to the \fBglsl\-shaders\fP list. The command line
11682 equivalent is \fB\-\-glsl\-shaders\-append=file.glsl\fP or alternatively
11683 \fB\-\-glsl\-shader=file.glsl\fP\&.
11684 .UNINDENT
11685 .UNINDENT
11686 .TP
11687 .B \fBdump\-cache <start> <end> <filename>\fP
11688 Dump the current cache to the given filename. The \fB<filename>\fP file is
11689 overwritten if it already exists. \fB<start>\fP and \fB<end>\fP give the
11690 time range of what to dump. If no data is cached at the given time range,
11691 nothing may be dumped (creating a file with no packets).
11692 .sp
11693 Dumping a larger part of the cache will freeze the player. No effort was
11694 made to fix this, as this feature was meant mostly for creating small
11695 excerpts.
11696 .sp
11697 See \fB\-\-stream\-record\fP for various caveats that mostly apply to this
11698 command too, as both use the same underlying code for writing the output
11699 file.
11700 .sp
11701 If \fB<filename>\fP is an empty string, an ongoing \fBdump\-cache\fP is stopped.
11702 .sp
11703 If \fB<end>\fP is \fBno\fP, then continuous dumping is enabled. Then, after
11704 dumping the existing parts of the cache, anything read from network is
11705 appended to the cache as well. This behaves similar to \fB\-\-stream\-record\fP
11706 (although it does not conflict with that option, and they can be both active
11707 at the same time).
11708 .sp
11709 If the \fB<end>\fP time is after the cache, the command will _not_ wait and
11710 write newly received data to it.
11711 .sp
11712 The end of the resulting file may be slightly damaged or incomplete at the
11713 end. (Not enough effort was made to ensure that the end lines up properly.)
11714 .sp
11715 Note that this command will finish only once dumping ends. That means it
11716 works similar to the \fBscreenshot\fP command, just that it can block much
11717 longer. If continuous dumping is used, the command will not finish until
11718 playback is stopped, an error happens, another \fBdump\-cache\fP command is
11719 run, or an API like \fBmp.abort_async_command\fP was called to explicitly stop
11720 the command. See \fI\%Synchronous vs. Asynchronous\fP\&.
11721 .sp
11722 \fBNOTE:\fP
11723 .INDENT 7.0
11724 .INDENT 3.5
11725 This was mostly created for network streams. For local files, there may
11726 be much better methods to create excerpts and such. There are tons of
11727 much more user\-friendly Lua scripts, that will reencode parts of a file
11728 by spawning a separate instance of \fBffmpeg\fP\&. With network streams,
11729 this is not that easily possible, as the stream would have to be
11730 downloaded again. Even if \fB\-\-stream\-record\fP is used to record the
11731 stream to the local filesystem, there may be problems, because the
11732 recorded file is still written to.
11733 .UNINDENT
11734 .UNINDENT
11735 .sp
11736 This command is experimental, and all details about it may change in the
11737 future.
11738 .TP
11739 .B \fBab\-loop\-dump\-cache <filename>\fP
11740 Essentially calls \fBdump\-cache\fP with the current AB\-loop points as
11741 arguments. Like \fBdump\-cache\fP, this will overwrite the file at
11742 \fB<filename>\fP\&. Likewise, if the B point is set to \fBno\fP, it will enter
11743 continuous dumping after the existing cache was dumped.
11744 .sp
11745 The author reserves the right to remove this command if enough motivation
11746 is found to move this functionality to a trivial Lua script.
11747 .TP
11748 .B \fBab\-loop\-align\-cache\fP
11749 Re\-adjust the A/B loop points to the start and end within the cache the
11750 \fBab\-loop\-dump\-cache\fP command will (probably) dump. Basically, it aligns
11751 the times on keyframes. The guess might be off especially at the end (due to
11752 granularity issues due to remuxing). If the cache shrinks in the meantime,
11753 the points set by the command will not be the effective parameters either.
11754 .sp
11755 This command has an even more uncertain future than \fBab\-loop\-dump\-cache\fP
11756 and might disappear without replacement if the author decides it\(aqs useless.
11757 .UNINDENT
11758 .sp
11759 Undocumented commands: \fBao\-reload\fP (experimental/internal).
11760 .SS Hooks
11761 .sp
11762 Hooks are synchronous events between player core and a script or similar. This
11763 applies to client API (including the Lua scripting interface). Normally,
11764 events are supposed to be asynchronous, and the hook API provides an awkward
11765 and obscure way to handle events that require stricter coordination. There are
11766 no API stability guarantees made. Not following the protocol exactly can make
11767 the player freeze randomly. Basically, nobody should use this API.
11768 .sp
11769 The C API is described in the header files. The Lua API is described in the
11770 Lua section.
11771 .sp
11772 The following hooks are currently defined:
11773 .INDENT 0.0
11774 .TP
11775 .B \fBon_load\fP
11776 Called when a file is to be opened, before anything is actually done.
11777 For example, you could read and write the \fBstream\-open\-filename\fP
11778 property to redirect an URL to something else (consider support for
11779 streaming sites which rarely give the user a direct media URL), or
11780 you could set per\-file options with by setting the property
11781 \fBfile\-local\-options/<option name>\fP\&. The player will wait until all
11782 hooks are run.
11783 .TP
11784 .B \fBon_load_fail\fP
11785 Called after after a file has been opened, but failed to. This can be
11786 used to provide a fallback in case native demuxers failed to recognize
11787 the file, instead of always running before the native demuxers like
11788 \fBon_load\fP\&. Demux will only be retried if \fBstream\-open\-filename\fP
11789 was changed.
11790 .TP
11791 .B \fBon_preloaded\fP
11792 Called after a file has been opened, and before tracks are selected and
11793 decoders are created. This has some usefulness if an API users wants
11794 to select tracks manually, based on the set of available tracks. It\(aqs
11795 also useful to initialize \fB\-\-lavfi\-complex\fP in a specific way by API,
11796 without having to "probe" the available streams at first.
11797 .sp
11798 Note that this does not yet apply default track selection. Which operations
11799 exactly can be done and not be done, and what information is available and
11800 what is not yet available yet, is all subject to change.
11801 .TP
11802 .B \fBon_unload\fP
11803 Run before closing a file, and before actually uninitializing
11804 everything. It\(aqs not possible to resume playback in this state.
11805 .UNINDENT
11806 .SS Legacy hook API
11807 .sp
11808 \fBWARNING:\fP
11809 .INDENT 0.0
11810 .INDENT 3.5
11811 The legacy API is deprecated and will be removed soon.
11812 .UNINDENT
11813 .UNINDENT
11814 .sp
11815 There are two special commands involved. Also, the client must listen for
11816 client messages (\fBMPV_EVENT_CLIENT_MESSAGE\fP in the C API).
11817 .INDENT 0.0
11818 .TP
11819 .B \fBhook\-add <hook\-name> <id> <priority>\fP
11820 Subscribe to the hook identified by the first argument (basically, the
11821 name of event). The \fBid\fP argument is an arbitrary integer chosen by the
11822 user. \fBpriority\fP is used to sort all hook handlers globally across all
11823 clients. Each client can register multiple hook handlers (even for the
11824 same hook\-name). Once the hook is registered, it cannot be unregistered.
11825 .sp
11826 When a specific event happens, all registered handlers are run serially.
11827 This uses a protocol every client has to follow explicitly. When a hook
11828 handler is run, a client message (\fBMPV_EVENT_CLIENT_MESSAGE\fP) is sent to
11829 the client which registered the hook. This message has the following
11830 arguments:
11831 .INDENT 7.0
11832 .IP 1. 3
11833 the string \fBhook_run\fP
11834 .IP 2. 3
11835 the \fBid\fP argument the hook was registered with as string (this can be
11836 used to correctly handle multiple hooks registered by the same client,
11837 as long as the \fBid\fP argument is unique in the client)
11838 .IP 3. 3
11839 something undefined, used by the hook mechanism to track hook execution
11840 .UNINDENT
11841 .sp
11842 Upon receiving this message, the client can handle the event. While doing
11843 this, the player core will still react to requests, but playback will
11844 typically be stopped.
11845 .sp
11846 When the client is done, it must continue the core\(aqs hook execution by
11847 running the \fBhook\-ack\fP command.
11848 .TP
11849 .B \fBhook\-ack <string>\fP
11850 Run the next hook in the global chain of hooks. The argument is the 3rd
11851 argument of the client message that starts hook execution for the
11852 current client.
11853 .UNINDENT
11854 .SS Input Command Prefixes
11855 .sp
11856 These prefixes are placed between key name and the actual command. Multiple
11857 prefixes can be specified. They are separated by whitespace.
11858 .INDENT 0.0
11859 .TP
11860 .B \fBosd\-auto\fP
11861 Use the default behavior for this command. This is the default for
11862 \fBinput.conf\fP commands. Some libmpv/scripting/IPC APIs do not use this as
11863 default, but use \fBno\-osd\fP instead.
11864 .TP
11865 .B \fBno\-osd\fP
11866 Do not use any OSD for this command.
11867 .TP
11868 .B \fBosd\-bar\fP
11869 If possible, show a bar with this command. Seek commands will show the
11870 progress bar, property changing commands may show the newly set value.
11871 .TP
11872 .B \fBosd\-msg\fP
11873 If possible, show an OSD message with this command. Seek command show
11874 the current playback time, property changing commands show the newly set
11875 value as text.
11876 .TP
11877 .B \fBosd\-msg\-bar\fP
11878 Combine osd\-bar and osd\-msg.
11879 .TP
11880 .B \fBraw\fP
11881 Do not expand properties in string arguments. (Like \fB"${property\-name}"\fP\&.)
11882 This is the default for some libmpv/scripting/IPC APIs.
11883 .TP
11884 .B \fBexpand\-properties\fP
11885 All string arguments are expanded as described in \fI\%Property Expansion\fP\&.
11886 This is the default for \fBinput.conf\fP commands.
11887 .TP
11888 .B \fBrepeatable\fP
11889 For some commands, keeping a key pressed doesn\(aqt run the command repeatedly.
11890 This prefix forces enabling key repeat in any case.
11891 .TP
11892 .B \fBasync\fP
11893 Allow asynchronous execution (if possible). Note that only a few commands
11894 will support this (usually this is explicitly documented). Some commands
11895 are asynchronous by default (or rather, their effects might manifest
11896 after completion of the command). The semantics of this flag might change
11897 in the future. Set it only if you don\(aqt rely on the effects of this command
11898 being fully realized when it returns. See \fI\%Synchronous vs. Asynchronous\fP\&.
11899 .TP
11900 .B \fBsync\fP
11901 Allow synchronous execution (if possible). Normally, all commands are
11902 synchronous by default, but some are asynchronous by default for
11903 compatibility with older behavior.
11904 .UNINDENT
11905 .sp
11906 All of the osd prefixes are still overridden by the global \fB\-\-osd\-level\fP
11907 settings.
11908 .SS Synchronous vs. Asynchronous
11909 .sp
11910 The \fBasync\fP and \fBsync\fP prefix matter only for how the issuer of the command
11911 waits on the completion of the command. Normally it does not affect how the
11912 command behaves by itself. There are the following cases:
11913 .INDENT 0.0
11914 .IP \(bu 2
11915 Normal input.conf commands are always run asynchronously. Slow running
11916 commands are queued up or run in parallel.
11917 .IP \(bu 2
11918 "Multi" input.conf commands (1 key binding, concatenated with \fB;\fP) will be
11919 executed in order, except for commands that are async (either prefixed with
11920 \fBasync\fP, or async by default for some commands). The async commands are
11921 run in a detached manner, possibly in parallel to the remaining sync commands
11922 in the list.
11923 .IP \(bu 2
11924 Normal Lua and libmpv commands (e.g. \fBmpv_command()\fP) are run in a blocking
11925 manner, unless the \fBasync\fP prefix is used, or the command is async by
11926 default. This means in the sync case the caller will block, even if the core
11927 continues playback. Async mode runs the command in a detached manner.
11928 .IP \(bu 2
11929 Async libmpv command API (e.g. \fBmpv_command_async()\fP) never blocks the
11930 caller, and always notify their completion with a message. The \fBsync\fP and
11931 \fBasync\fP prefixes make no difference.
11932 .IP \(bu 2
11933 Lua also provides APIs for running async commands, which behave similar to the
11934 C counterparts.
11935 .IP \(bu 2
11936 In all cases, async mode can still run commands in a synchronous manner, even
11937 in detached mode. This can for example happen in cases when a command does not
11938 have an asynchronous implementation. The async libmpv API still never blocks
11939 the caller in these cases.
11940 .UNINDENT
11941 .sp
11942 Before mpv 0.29.0, the \fBasync\fP prefix was only used by screenshot commands,
11943 and made them run the file saving code in a detached manner. This is the
11944 default now, and \fBasync\fP changes behavior only in the ways mentioned above.
11945 .sp
11946 Currently the following commands have different waiting characteristics with
11947 sync vs. async: sub\-add, audio\-add, sub\-reload, audio\-reload,
11948 rescan\-external\-files, screenshot, screenshot\-to\-file, dump\-cache,
11949 ab\-loop\-dump\-cache.
11950 .SS Asynchronous command details
11951 .sp
11952 On the API level, every asynchronous command is bound to the context which
11953 started it. For example, an asynchronous command started by \fBmpv_command_async\fP
11954 is bound to the \fBmpv_handle\fP passed to the function. Only this \fBmpv_handle\fP
11955 receives the completion notification (\fBMPV_EVENT_COMMAND_REPLY\fP), and only
11956 this handle can abort a still running command directly. If the \fBmpv_handle\fP is
11957 destroyed, any still running async. commands started by it are terminated.
11958 .sp
11959 The scripting APIs and JSON IPC give each script/connection its own implicit
11960 \fBmpv_handle\fP\&.
11961 .sp
11962 If the player is closed, the core may abort all pending async. commands on its
11963 own (like a forced \fBmpv_abort_async_command()\fP call for each pending command
11964 on behalf of the API user). This happens at the same time \fBMPV_EVENT_SHUTDOWN\fP
11965 is sent, and there is no way to prevent this.
11966 .SS Input Sections
11967 .sp
11968 Input sections group a set of bindings, and enable or disable them at once.
11969 In \fBinput.conf\fP, each key binding is assigned to an input section, rather
11970 than actually having explicit text sections.
11971 .sp
11972 See also: \fBenable\-section\fP and \fBdisable\-section\fP commands.
11973 .sp
11974 Predefined bindings:
11975 .INDENT 0.0
11976 .TP
11977 .B \fBdefault\fP
11978 Bindings without input section are implicitly assigned to this section. It
11979 is enabled by default during normal playback.
11980 .TP
11981 .B \fBencode\fP
11982 Section which is active in encoding mode. It is enabled exclusively, so
11983 that bindings in the \fBdefault\fP sections are ignored.
11984 .UNINDENT
11985 .SS Properties
11986 .sp
11987 Properties are used to set mpv options during runtime, or to query arbitrary
11988 information. They can be manipulated with the \fBset\fP/\fBadd\fP/\fBcycle\fP
11989 commands, and retrieved with \fBshow\-text\fP, or anything else that uses property
11990 expansion. (See \fI\%Property Expansion\fP\&.)
11991 .sp
11992 The property name is annotated with RW to indicate whether the property is
11993 generally writable.
11994 .sp
11995 If an option is referenced, the property will normally take/return exactly the
11996 same values as the option. In these cases, properties are merely a way to change
11997 an option at runtime.
11998 .SS Property list
11999 .sp
12000 \fBNOTE:\fP
12001 .INDENT 0.0
12002 .INDENT 3.5
12003 Most options can be set as runtime via properties as well. Just remove the
12004 leading \fB\-\-\fP from the option name. These are not documented. Only
12005 properties which do not exist as option with the same name, or which have
12006 very different behavior from the options are documented below.
12007 .UNINDENT
12008 .UNINDENT
12009 .INDENT 0.0
12010 .TP
12011 .B \fBaudio\-speed\-correction\fP, \fBvideo\-speed\-correction\fP
12012 Factor multiplied with \fBspeed\fP at which the player attempts to play the
12013 file. Usually it\(aqs exactly 1. (Display sync mode will make this useful.)
12014 .sp
12015 OSD formatting will display it in the form of \fB+1.23456%\fP, with the number
12016 being \fB(raw \- 1) * 100\fP for the given raw property value.
12017 .TP
12018 .B \fBdisplay\-sync\-active\fP
12019 Return whether \fB\-\-video\-sync=display\fP is actually active.
12020 .TP
12021 .B \fBfilename\fP
12022 Currently played file, with path stripped. If this is an URL, try to undo
12023 percent encoding as well. (The result is not necessarily correct, but
12024 looks better for display purposes. Use the \fBpath\fP property to get an
12025 unmodified filename.)
12026 .sp
12027 This has a sub\-property:
12028 .INDENT 7.0
12029 .TP
12030 .B \fBfilename/no\-ext\fP
12031 Like the \fBfilename\fP property, but if the text contains a \fB\&.\fP, strip
12032 all text after the last \fB\&.\fP\&. Usually this removes the file extension.
12033 .UNINDENT
12034 .TP
12035 .B \fBfile\-size\fP
12036 Length in bytes of the source file/stream. (This is the same as
12037 \fB${stream\-end}\fP\&. For segmented/multi\-part files, this will return the
12038 size of the main or manifest file, whatever it is.)
12039 .TP
12040 .B \fBestimated\-frame\-count\fP
12041 Total number of frames in current file.
12042 .sp
12043 \fBNOTE:\fP
12044 .INDENT 7.0
12045 .INDENT 3.5
12046 This is only an estimate. (It\(aqs computed from two unreliable
12047 quantities: fps and stream length.)
12048 .UNINDENT
12049 .UNINDENT
12050 .TP
12051 .B \fBestimated\-frame\-number\fP
12052 Number of current frame in current stream.
12053 .sp
12054 \fBNOTE:\fP
12055 .INDENT 7.0
12056 .INDENT 3.5
12057 This is only an estimate. (It\(aqs computed from two unreliable
12058 quantities: fps and possibly rounded timestamps.)
12059 .UNINDENT
12060 .UNINDENT
12061 .TP
12062 .B \fBpath\fP
12063 Full path of the currently played file. Usually this is exactly the same
12064 string you pass on the mpv command line or the \fBloadfile\fP command, even
12065 if it\(aqs a relative path. If you expect an absolute path, you will have to
12066 determine it yourself, for example by using the \fBworking\-directory\fP
12067 property.
12068 .TP
12069 .B \fBstream\-open\-filename\fP
12070 The full path to the currently played media. This is different only from
12071 \fBpath\fP in special cases. In particular, if \fB\-\-ytdl=yes\fP is used, and
12072 the URL is detected by \fByoutube\-dl\fP, then the script will set this
12073 property to the actual media URL. This property should be set only during
12074 the \fBon_load\fP or \fBon_load_fail\fP hooks, otherwise it will have no effect
12075 (or may do something implementation defined in the future). The property is
12076 reset if playback of the current media ends.
12077 .TP
12078 .B \fBmedia\-title\fP
12079 If the currently played file has a \fBtitle\fP tag, use that.
12080 .sp
12081 Otherwise, return the \fBfilename\fP property.
12082 .TP
12083 .B \fBfile\-format\fP
12084 Symbolic name of the file format. In some cases, this is a comma\-separated
12085 list of format names, e.g. mp4 is \fBmov,mp4,m4a,3gp,3g2,mj2\fP (the list
12086 may grow in the future for any format).
12087 .TP
12088 .B \fBcurrent\-demuxer\fP
12089 Name of the current demuxer. (This is useless.)
12090 .sp
12091 (Renamed from \fBdemuxer\fP\&.)
12092 .TP
12093 .B \fBstream\-path\fP
12094 Filename (full path) of the stream layer filename. (This is probably
12095 useless and is almost never different from \fBpath\fP\&.)
12096 .TP
12097 .B \fBstream\-pos\fP
12098 Raw byte position in source stream. Technically, this returns the position
12099 of the most recent packet passed to a decoder.
12100 .TP
12101 .B \fBstream\-end\fP
12102 Raw end position in bytes in source stream.
12103 .TP
12104 .B \fBduration\fP
12105 Duration of the current file in seconds. If the duration is unknown, the
12106 property is unavailable. Note that the file duration is not always exactly
12107 known, so this is an estimate.
12108 .sp
12109 This replaces the \fBlength\fP property, which was deprecated after the
12110 mpv 0.9 release. (The semantics are the same.)
12111 .TP
12112 .B \fBavsync\fP
12113 Last A/V synchronization difference. Unavailable if audio or video is
12114 disabled.
12115 .TP
12116 .B \fBtotal\-avsync\-change\fP
12117 Total A\-V sync correction done. Unavailable if audio or video is
12118 disabled.
12119 .TP
12120 .B \fBdecoder\-frame\-drop\-count\fP
12121 Video frames dropped by decoder, because video is too far behind audio (when
12122 using \fB\-\-framedrop=decoder\fP). Sometimes, this may be incremented in other
12123 situations, e.g. when video packets are damaged, or the decoder doesn\(aqt
12124 follow the usual rules. Unavailable if video is disabled.
12125 .sp
12126 \fBdrop\-frame\-count\fP is a deprecated alias.
12127 .TP
12128 .B \fBframe\-drop\-count\fP
12129 Frames dropped by VO (when using \fB\-\-framedrop=vo\fP).
12130 .sp
12131 \fBvo\-drop\-frame\-count\fP is a deprecated alias.
12132 .TP
12133 .B \fBmistimed\-frame\-count\fP
12134 Number of video frames that were not timed correctly in display\-sync mode
12135 for the sake of keeping A/V sync. This does not include external
12136 circumstances, such as video rendering being too slow or the graphics
12137 driver somehow skipping a vsync. It does not include rounding errors either
12138 (which can happen especially with bad source timestamps). For example,
12139 using the \fBdisplay\-desync\fP mode should never change this value from 0.
12140 .TP
12141 .B \fBvsync\-ratio\fP
12142 For how many vsyncs a frame is displayed on average. This is available if
12143 display\-sync is active only. For 30 FPS video on a 60 Hz screen, this will
12144 be 2. This is the moving average of what actually has been scheduled, so
12145 24 FPS on 60 Hz will never remain exactly on 2.5, but jitter depending on
12146 the last frame displayed.
12147 .TP
12148 .B \fBvo\-delayed\-frame\-count\fP
12149 Estimated number of frames delayed due to external circumstances in
12150 display\-sync mode. Note that in general, mpv has to guess that this is
12151 happening, and the guess can be inaccurate.
12152 .TP
12153 .B \fBpercent\-pos\fP (RW)
12154 Position in current file (0\-100). The advantage over using this instead of
12155 calculating it out of other properties is that it properly falls back to
12156 estimating the playback position from the byte position, if the file
12157 duration is not known.
12158 .TP
12159 .B \fBtime\-pos\fP (RW)
12160 Position in current file in seconds.
12161 .TP
12162 .B \fBtime\-start\fP
12163 Deprecated. Always returns 0. Before mpv 0.14, this used to return the start
12164 time of the file (could affect e.g. transport streams). See
12165 \fB\-\-rebase\-start\-time\fP option.
12166 .TP
12167 .B \fBtime\-remaining\fP
12168 Remaining length of the file in seconds. Note that the file duration is not
12169 always exactly known, so this is an estimate.
12170 .TP
12171 .B \fBaudio\-pts\fP (R)
12172 Current audio playback position in current file in seconds. Unlike time\-pos,
12173 this updates more often than once per frame. For audio\-only files, it is
12174 mostly equivalent to time\-pos, while for video\-only files this property is
12175 not available.
12176 .TP
12177 .B \fBplaytime\-remaining\fP
12178 \fBtime\-remaining\fP scaled by the current \fBspeed\fP\&.
12179 .TP
12180 .B \fBplayback\-time\fP (RW)
12181 Position in current file in seconds. Unlike \fBtime\-pos\fP, the time is
12182 clamped to the range of the file. (Inaccurate file durations etc. could
12183 make it go out of range. Useful on attempts to seek outside of the file,
12184 as the seek target time is considered the current position during seeking.)
12185 .TP
12186 .B \fBchapter\fP (RW)
12187 Current chapter number. The number of the first chapter is 0.
12188 .TP
12189 .B \fBedition\fP (RW)
12190 Current MKV edition number. Setting this property to a different value will
12191 restart playback. The number of the first edition is 0.
12192 .TP
12193 .B \fBchapters\fP
12194 Number of chapters.
12195 .TP
12196 .B \fBeditions\fP
12197 Number of MKV editions.
12198 .TP
12199 .B \fBedition\-list\fP
12200 List of editions, current entry marked. Currently, the raw property value
12201 is useless.
12202 .sp
12203 This has a number of sub\-properties. Replace \fBN\fP with the 0\-based edition
12204 index.
12205 .INDENT 7.0
12206 .TP
12207 .B \fBedition\-list/count\fP
12208 Number of editions. If there are no editions, this can be 0 or 1 (1
12209 if there\(aqs a useless dummy edition).
12210 .TP
12211 .B \fBedition\-list/N/id\fP
12212 Edition ID as integer. Use this to set the \fBedition\fP property.
12213 Currently, this is the same as the edition index.
12214 .TP
12215 .B \fBedition\-list/N/default\fP
12216 \fByes\fP if this is the default edition, \fBno\fP otherwise.
12217 .TP
12218 .B \fBedition\-list/N/title\fP
12219 Edition title as stored in the file. Not always available.
12220 .UNINDENT
12221 .sp
12222 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
12223 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
12224 the following contents:
12225 .INDENT 7.0
12226 .INDENT 3.5
12227 .sp
12228 .nf
12229 .ft C
12230 MPV_FORMAT_NODE_ARRAY
12231 MPV_FORMAT_NODE_MAP (for each edition)
12232 "id" MPV_FORMAT_INT64
12233 "title" MPV_FORMAT_STRING
12234 "default" MPV_FORMAT_FLAG
12235 .ft P
12236 .fi
12237 .UNINDENT
12238 .UNINDENT
12239 .TP
12240 .B \fBmetadata\fP
12241 Metadata key/value pairs.
12242 .sp
12243 If the property is accessed with Lua\(aqs \fBmp.get_property_native\fP, this
12244 returns a table with metadata keys mapping to metadata values. If it is
12245 accessed with the client API, this returns a \fBMPV_FORMAT_NODE_MAP\fP,
12246 with tag keys mapping to tag values.
12247 .sp
12248 For OSD, it returns a formatted list. Trying to retrieve this property as
12249 a raw string doesn\(aqt work.
12250 .sp
12251 This has a number of sub\-properties:
12252 .INDENT 7.0
12253 .TP
12254 .B \fBmetadata/by\-key/<key>\fP
12255 Value of metadata entry \fB<key>\fP\&.
12256 .TP
12257 .B \fBmetadata/list/count\fP
12258 Number of metadata entries.
12259 .TP
12260 .B \fBmetadata/list/N/key\fP
12261 Key name of the Nth metadata entry. (The first entry is \fB0\fP).
12262 .TP
12263 .B \fBmetadata/list/N/value\fP
12264 Value of the Nth metadata entry.
12265 .TP
12266 .B \fBmetadata/<key>\fP
12267 Old version of \fBmetadata/by\-key/<key>\fP\&. Use is discouraged, because
12268 the metadata key string could conflict with other sub\-properties.
12269 .UNINDENT
12270 .sp
12271 The layout of this property might be subject to change. Suggestions are
12272 welcome how exactly this property should work.
12273 .sp
12274 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
12275 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
12276 the following contents:
12277 .INDENT 7.0
12278 .INDENT 3.5
12279 .sp
12280 .nf
12281 .ft C
12282 MPV_FORMAT_NODE_MAP
12283 (key and string value for each metadata entry)
12284 .ft P
12285 .fi
12286 .UNINDENT
12287 .UNINDENT
12288 .TP
12289 .B \fBfiltered\-metadata\fP
12290 Like \fBmetadata\fP, but includes only fields listed in the \fB\-\-display\-tags\fP
12291 option. This is the same set of tags that is printed to the terminal.
12292 .TP
12293 .B \fBchapter\-metadata\fP
12294 Metadata of current chapter. Works similar to \fBmetadata\fP property. It
12295 also allows the same access methods (using sub\-properties).
12296 .sp
12297 Per\-chapter metadata is very rare. Usually, only the chapter name
12298 (\fBtitle\fP) is set.
12299 .sp
12300 For accessing other information, like chapter start, see the
12301 \fBchapter\-list\fP property.
12302 .TP
12303 .B \fBvf\-metadata/<filter\-label>\fP
12304 Metadata added by video filters. Accessed by the filter label,
12305 which, if not explicitly specified using the \fB@filter\-label:\fP syntax,
12306 will be \fB<filter\-name>NN\fP\&.
12307 .sp
12308 Works similar to \fBmetadata\fP property. It allows the same access
12309 methods (using sub\-properties).
12310 .sp
12311 An example of this kind of metadata are the cropping parameters
12312 added by \fB\-\-vf=lavfi=cropdetect\fP\&.
12313 .TP
12314 .B \fBaf\-metadata/<filter\-label>\fP
12315 Equivalent to \fBvf\-metadata/<filter\-label>\fP, but for audio filters.
12316 .TP
12317 .B \fBidle\-active\fP
12318 Return \fByes\fP if no file is loaded, but the player is staying around
12319 because of the \fB\-\-idle\fP option.
12320 .sp
12321 (Renamed from \fBidle\fP\&.)
12322 .TP
12323 .B \fBcore\-idle\fP
12324 Return \fByes\fP if the playback core is paused, otherwise \fBno\fP\&. This can
12325 be different \fBpause\fP in special situations, such as when the player
12326 pauses itself due to low network cache.
12327 .sp
12328 This also returns \fByes\fP if playback is restarting or if nothing is
12329 playing at all. In other words, it\(aqs only \fBno\fP if there\(aqs actually
12330 video playing. (Behavior since mpv 0.7.0.)
12331 .TP
12332 .B \fBcache\-speed\fP (R)
12333 Current I/O read speed between the cache and the lower layer (like network).
12334 This gives the number bytes per seconds over a 1 second window (using
12335 the type \fBMPV_FORMAT_INT64\fP for the client API).
12336 .TP
12337 .B \fBdemuxer\-cache\-duration\fP
12338 Approximate duration of video buffered in the demuxer, in seconds. The
12339 guess is very unreliable, and often the property will not be available
12340 at all, even if data is buffered.
12341 .TP
12342 .B \fBdemuxer\-cache\-time\fP
12343 Approximate time of video buffered in the demuxer, in seconds. Same as
12344 \fBdemuxer\-cache\-duration\fP but returns the last timestamp of buffered
12345 data in demuxer.
12346 .TP
12347 .B \fBdemuxer\-cache\-idle\fP
12348 Returns \fByes\fP if the demuxer is idle, which means the demuxer cache is
12349 filled to the requested amount, and is currently not reading more data.
12350 .TP
12351 .B \fBdemuxer\-cache\-state\fP
12352 Various undocumented or half\-documented things.
12353 .sp
12354 Each entry in \fBseekable\-ranges\fP represents a region in the demuxer cache
12355 that can be seeked to. If there are multiple demuxers active, this only
12356 returns information about the "main" demuxer, but might be changed in
12357 future to return unified information about all demuxers. The ranges are in
12358 arbitrary order. Often, ranges will overlap for a bit, before being joined.
12359 In broken corner cases, ranges may overlap all over the place.
12360 .sp
12361 The end of a seek range is usually smaller than the value returned by the
12362 \fBdemuxer\-cache\-time\fP property, because that property returns the guessed
12363 buffering amount, while the seek ranges represent the buffered data that
12364 can actually be used for cached seeking.
12365 .sp
12366 \fBbof\-cached\fP indicates whether the seek range with the lowest timestamp
12367 points to the beginning of the stream (BOF). This implies you cannot seek
12368 before this position at all. \fBeof\-cached\fP indicates whether the seek range
12369 with the highest timestamp points to the end of the stream (EOF). If both
12370 \fBbof\-cached\fP and \fBeof\-cached\fP are set to \fByes\fP, and there\(aqs only 1
12371 cache range, the entire stream is cached.
12372 .sp
12373 \fBfw\-bytes\fP is the number of bytes of packets buffered in the range
12374 starting from the current decoding position. This is a rough estimate
12375 (may not account correctly for various overhead), and stops at the
12376 demuxer position (it ignores seek ranges after it).
12377 .sp
12378 \fBfile\-cache\-bytes\fP is the number of bytes stored in the file cache. This
12379 includes all overhead, and possibly unused data (like pruned data). This
12380 member is missing if the file cache is not active.
12381 .sp
12382 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
12383 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
12384 the following contents:
12385 .INDENT 7.0
12386 .INDENT 3.5
12387 .sp
12388 .nf
12389 .ft C
12390 MPV_FORMAT_NODE_MAP
12391 "seekable\-ranges" MPV_FORMAT_NODE_ARRAY
12392 MPV_FORMAT_NODE_MAP
12393 "start" MPV_FORMAT_DOUBLE
12394 "end" MPV_FORMAT_DOUBLE
12395 "bof\-cached" MPV_FORMAT_FLAG
12396 "eof\-cached" MPV_FORMAT_FLAG
12397 "fw\-bytes" MPV_FORMAT_INT64
12398 "file\-cache\-bytes" MPV_FORMAT_INT64
12399 .ft P
12400 .fi
12401 .UNINDENT
12402 .UNINDENT
12403 .sp
12404 Other fields (might be changed or removed in the future):
12405 .INDENT 7.0
12406 .TP
12407 .B \fBeof\fP
12408 True if the reader thread has hit the end of the file.
12409 .TP
12410 .B \fBunderrun\fP
12411 True if the reader thread could not satisfy a decoder\(aqs request for a
12412 new packet.
12413 .TP
12414 .B \fBidle\fP
12415 True if the thread is currently not reading.
12416 .TP
12417 .B \fBtotal\-bytes\fP
12418 Sum of packet bytes (plus some overhead estimation) of the entire packet
12419 queue, including cached seekable ranges.
12420 .UNINDENT
12421 .TP
12422 .B \fBdemuxer\-via\-network\fP
12423 Returns \fByes\fP if the stream demuxed via the main demuxer is most likely
12424 played via network. What constitutes "network" is not always clear, might
12425 be used for other types of untrusted streams, could be wrong in certain
12426 cases, and its definition might be changing. Also, external files (like
12427 separate audio files or streams) do not influence the value of this
12428 property (currently).
12429 .TP
12430 .B \fBdemuxer\-start\-time\fP (R)
12431 Returns the start time reported by the demuxer in fractional seconds.
12432 .TP
12433 .B \fBpaused\-for\-cache\fP
12434 Returns \fByes\fP when playback is paused because of waiting for the cache.
12435 .TP
12436 .B \fBcache\-buffering\-state\fP
12437 Return the percentage (0\-100) of the cache fill status until the player
12438 will unpause (related to \fBpaused\-for\-cache\fP).
12439 .TP
12440 .B \fBeof\-reached\fP
12441 Returns \fByes\fP if end of playback was reached, \fBno\fP otherwise. Note
12442 that this is usually interesting only if \fB\-\-keep\-open\fP is enabled,
12443 since otherwise the player will immediately play the next file (or exit
12444 or enter idle mode), and in these cases the \fBeof\-reached\fP property will
12445 logically be cleared immediately after it\(aqs set.
12446 .TP
12447 .B \fBseeking\fP
12448 Returns \fByes\fP if the player is currently seeking, or otherwise trying
12449 to restart playback. (It\(aqs possible that it returns \fByes\fP while a file
12450 is loaded. This is because the same underlying code is used for seeking and
12451 resyncing.)
12452 .TP
12453 .B \fBmixer\-active\fP
12454 Return \fByes\fP if the audio mixer is active, \fBno\fP otherwise.
12455 .sp
12456 This option is relatively useless. Before mpv 0.18.1, it could be used to
12457 infer behavior of the \fBvolume\fP property.
12458 .TP
12459 .B \fBao\-volume\fP (RW)
12460 System volume. This property is available only if mpv audio output is
12461 currently active, and only if the underlying implementation supports volume
12462 control. What this option does depends on the API. For example, on ALSA
12463 this usually changes system\-wide audio, while with PulseAudio this controls
12464 per\-application volume.
12465 .TP
12466 .B \fBao\-mute\fP (RW)
12467 Similar to \fBao\-volume\fP, but controls the mute state. May be unimplemented
12468 even if \fBao\-volume\fP works.
12469 .TP
12470 .B \fBaudio\-codec\fP
12471 Audio codec selected for decoding.
12472 .TP
12473 .B \fBaudio\-codec\-name\fP
12474 Audio codec.
12475 .TP
12476 .B \fBaudio\-params\fP
12477 Audio format as output by the audio decoder.
12478 This has a number of sub\-properties:
12479 .INDENT 7.0
12480 .TP
12481 .B \fBaudio\-params/format\fP
12482 The sample format as string. This uses the same names as used in other
12483 places of mpv.
12484 .TP
12485 .B \fBaudio\-params/samplerate\fP
12486 Samplerate.
12487 .TP
12488 .B \fBaudio\-params/channels\fP
12489 The channel layout as a string. This is similar to what the
12490 \fB\-\-audio\-channels\fP accepts.
12491 .TP
12492 .B \fBaudio\-params/hr\-channels\fP
12493 As \fBchannels\fP, but instead of the possibly cryptic actual layout
12494 sent to the audio device, return a hopefully more human readable form.
12495 (Usually only \fBaudio\-out\-params/hr\-channels\fP makes sense.)
12496 .TP
12497 .B \fBaudio\-params/channel\-count\fP
12498 Number of audio channels. This is redundant to the \fBchannels\fP field
12499 described above.
12500 .UNINDENT
12501 .sp
12502 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
12503 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
12504 the following contents:
12505 .INDENT 7.0
12506 .INDENT 3.5
12507 .sp
12508 .nf
12509 .ft C
12510 MPV_FORMAT_NODE_MAP
12511 "format" MPV_FORMAT_STRING
12512 "samplerate" MPV_FORMAT_INT64
12513 "channels" MPV_FORMAT_STRING
12514 "channel\-count" MPV_FORMAT_INT64
12515 "hr\-channels" MPV_FORMAT_STRING
12516 .ft P
12517 .fi
12518 .UNINDENT
12519 .UNINDENT
12520 .TP
12521 .B \fBaudio\-out\-params\fP
12522 Same as \fBaudio\-params\fP, but the format of the data written to the audio
12523 API.
12524 .TP
12525 .B \fBcolormatrix\fP (R)
12526 Redirects to \fBvideo\-params/colormatrix\fP\&. This parameter (as well as
12527 similar ones) can be overridden with the \fBformat\fP video filter.
12528 .TP
12529 .B \fBcolormatrix\-input\-range\fP (R)
12530 See \fBcolormatrix\fP\&.
12531 .TP
12532 .B \fBcolormatrix\-primaries\fP (R)
12533 See \fBcolormatrix\fP\&.
12534 .TP
12535 .B \fBhwdec\fP (RW)
12536 Reflects the \fB\-\-hwdec\fP option.
12537 .sp
12538 Writing to it may change the currently used hardware decoder, if possible.
12539 (Internally, the player may reinitialize the decoder, and will perform a
12540 seek to refresh the video properly.) You can watch the other hwdec
12541 properties to see whether this was successful.
12542 .sp
12543 Unlike in mpv 0.9.x and before, this does not return the currently active
12544 hardware decoder. Since mpv 0.18.0, \fBhwdec\-current\fP is available for
12545 this purpose.
12546 .TP
12547 .B \fBhwdec\-current\fP
12548 Return the current hardware decoding in use. If decoding is active, return
12549 one of the values used by the \fBhwdec\fP option/property. \fBno\fP indicates
12550 software decoding. If no decoder is loaded, the property is unavailable.
12551 .TP
12552 .B \fBhwdec\-interop\fP
12553 This returns the currently loaded hardware decoding/output interop driver.
12554 This is known only once the VO has opened (and possibly later). With some
12555 VOs (like \fBgpu\fP), this might be never known in advance, but only when
12556 the decoder attempted to create the hw decoder successfully. (Using
12557 \fB\-\-gpu\-hwdec\-interop\fP can load it eagerly.) If there are multiple
12558 drivers loaded, they will be separated by \fB,\fP\&.
12559 .sp
12560 If no VO is active or no interop driver is known, this property is
12561 unavailable.
12562 .sp
12563 This does not necessarily use the same values as \fBhwdec\fP\&. There can be
12564 multiple interop drivers for the same hardware decoder, depending on
12565 platform and VO.
12566 .TP
12567 .B \fBvideo\-format\fP
12568 Video format as string.
12569 .TP
12570 .B \fBvideo\-codec\fP
12571 Video codec selected for decoding.
12572 .TP
12573 .B \fBwidth\fP, \fBheight\fP
12574 Video size. This uses the size of the video as decoded, or if no video
12575 frame has been decoded yet, the (possibly incorrect) container indicated
12576 size.
12577 .TP
12578 .B \fBvideo\-params\fP
12579 Video parameters, as output by the decoder (with overrides like aspect
12580 etc. applied). This has a number of sub\-properties:
12581 .INDENT 7.0
12582 .TP
12583 .B \fBvideo\-params/pixelformat\fP
12584 The pixel format as string. This uses the same names as used in other
12585 places of mpv.
12586 .TP
12587 .B \fBvideo\-params/average\-bpp\fP
12588 Average bits\-per\-pixel as integer. Subsampled planar formats use a
12589 different resolution, which is the reason this value can sometimes be
12590 odd or confusing. Can be unavailable with some formats.
12591 .TP
12592 .B \fBvideo\-params/plane\-depth\fP
12593 Bit depth for each color component as integer. This is only exposed
12594 for planar or single\-component formats, and is unavailable for other
12595 formats.
12596 .TP
12597 .B \fBvideo\-params/w\fP, \fBvideo\-params/h\fP
12598 Video size as integers, with no aspect correction applied.
12599 .TP
12600 .B \fBvideo\-params/dw\fP, \fBvideo\-params/dh\fP
12601 Video size as integers, scaled for correct aspect ratio.
12602 .TP
12603 .B \fBvideo\-params/aspect\fP
12604 Display aspect ratio as float.
12605 .TP
12606 .B \fBvideo\-params/par\fP
12607 Pixel aspect ratio.
12608 .TP
12609 .B \fBvideo\-params/colormatrix\fP
12610 The colormatrix in use as string. (Exact values subject to change.)
12611 .TP
12612 .B \fBvideo\-params/colorlevels\fP
12613 The colorlevels as string. (Exact values subject to change.)
12614 .TP
12615 .B \fBvideo\-params/primaries\fP
12616 The primaries in use as string. (Exact values subject to change.)
12617 .TP
12618 .B \fBvideo\-params/gamma\fP
12619 The gamma function in use as string. (Exact values subject to change.)
12620 .TP
12621 .B \fBvideo\-params/sig\-peak\fP
12622 The video file\(aqs tagged signal peak as float.
12623 .TP
12624 .B \fBvideo\-params/light\fP
12625 The light type in use as a string. (Exact values subject to change.)
12626 .TP
12627 .B \fBvideo\-params/chroma\-location\fP
12628 Chroma location as string. (Exact values subject to change.)
12629 .TP
12630 .B \fBvideo\-params/rotate\fP
12631 Intended display rotation in degrees (clockwise).
12632 .TP
12633 .B \fBvideo\-params/stereo\-in\fP
12634 Source file stereo 3D mode. (See the \fBformat\fP video filter\(aqs
12635 \fBstereo\-in\fP option.)
12636 .UNINDENT
12637 .sp
12638 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
12639 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
12640 the following contents:
12641 .INDENT 7.0
12642 .INDENT 3.5
12643 .sp
12644 .nf
12645 .ft C
12646 MPV_FORMAT_NODE_MAP
12647 "pixelformat" MPV_FORMAT_STRING
12648 "w" MPV_FORMAT_INT64
12649 "h" MPV_FORMAT_INT64
12650 "dw" MPV_FORMAT_INT64
12651 "dh" MPV_FORMAT_INT64
12652 "aspect" MPV_FORMAT_DOUBLE
12653 "par" MPV_FORMAT_DOUBLE
12654 "colormatrix" MPV_FORMAT_STRING
12655 "colorlevels" MPV_FORMAT_STRING
12656 "primaries" MPV_FORMAT_STRING
12657 "gamma" MPV_FORMAT_STRING
12658 "sig\-peak" MPV_FORMAT_DOUBLE
12659 "light" MPV_FORMAT_STRING
12660 "chroma\-location" MPV_FORMAT_STRING
12661 "rotate" MPV_FORMAT_INT64
12662 "stereo\-in" MPV_FORMAT_STRING
12663 .ft P
12664 .fi
12665 .UNINDENT
12666 .UNINDENT
12667 .TP
12668 .B \fBdwidth\fP, \fBdheight\fP
12669 Video display size. This is the video size after filters and aspect scaling
12670 have been applied. The actual video window size can still be different
12671 from this, e.g. if the user resized the video window manually.
12672 .sp
12673 These have the same values as \fBvideo\-out\-params/dw\fP and
12674 \fBvideo\-out\-params/dh\fP\&.
12675 .TP
12676 .B \fBvideo\-dec\-params\fP
12677 Exactly like \fBvideo\-params\fP, but no overrides applied.
12678 .TP
12679 .B \fBvideo\-out\-params\fP
12680 Same as \fBvideo\-params\fP, but after video filters have been applied. If
12681 there are no video filters in use, this will contain the same values as
12682 \fBvideo\-params\fP\&. Note that this is still not necessarily what the video
12683 window uses, since the user can change the window size, and all real VOs
12684 do their own scaling independently from the filter chain.
12685 .sp
12686 Has the same sub\-properties as \fBvideo\-params\fP\&.
12687 .TP
12688 .B \fBvideo\-frame\-info\fP
12689 Approximate information of the current frame. Note that if any of these
12690 are used on OSD, the information might be off by a few frames due to OSD
12691 redrawing and frame display being somewhat disconnected, and you might
12692 have to pause and force a redraw.
12693 .sp
12694 Sub\-properties:
12695 .INDENT 7.0
12696 .INDENT 3.5
12697 .sp
12698 .nf
12699 .ft C
12700 video\-frame\-info/picture\-type
12701 video\-frame\-info/interlaced
12702 video\-frame\-info/tff
12703 video\-frame\-info/repeat
12704 .ft P
12705 .fi
12706 .UNINDENT
12707 .UNINDENT
12708 .TP
12709 .B \fBcontainer\-fps\fP
12710 Container FPS. This can easily contain bogus values. For videos that use
12711 modern container formats or video codecs, this will often be incorrect.
12712 .sp
12713 (Renamed from \fBfps\fP\&.)
12714 .TP
12715 .B \fBestimated\-vf\-fps\fP
12716 Estimated/measured FPS of the video filter chain output. (If no filters
12717 are used, this corresponds to decoder output.) This uses the average of
12718 the 10 past frame durations to calculate the FPS. It will be inaccurate
12719 if frame\-dropping is involved (such as when framedrop is explicitly
12720 enabled, or after precise seeking). Files with imprecise timestamps (such
12721 as Matroska) might lead to unstable results.
12722 .TP
12723 .B \fBwindow\-scale\fP (RW)
12724 Window size multiplier. Setting this will resize the video window to the
12725 values contained in \fBdwidth\fP and \fBdheight\fP multiplied with the value
12726 set with this property. Setting \fB1\fP will resize to original video size
12727 (or to be exact, the size the video filters output). \fB2\fP will set the
12728 double size, \fB0.5\fP halves the size.
12729 .TP
12730 .B \fBwindow\-minimized\fP
12731 Return whether the video window is minimized or not.
12732 .TP
12733 .B \fBdisplay\-names\fP
12734 Names of the displays that the mpv window covers. On X11, these
12735 are the xrandr names (LVDS1, HDMI1, DP1, VGA1, etc.). On Windows, these
12736 are the GDI names (\e.DISPLAY1, \e.DISPLAY2, etc.) and the first display
12737 in the list will be the one that Windows considers associated with the
12738 window (as determined by the MonitorFromWindow API.) On macOS these are the
12739 Display Product Names as used in the System Information and only one display
12740 name is returned since a window can only be on one screen.
12741 .TP
12742 .B \fBdisplay\-fps\fP (RW)
12743 The refresh rate of the current display. Currently, this is the lowest FPS
12744 of any display covered by the video, as retrieved by the underlying system
12745 APIs (e.g. xrandr on X11). It is not the measured FPS. It\(aqs not necessarily
12746 available on all platforms. Note that any of the listed facts may change
12747 any time without a warning.
12748 .TP
12749 .B \fBestimated\-display\-fps\fP
12750 Only available if display\-sync mode (as selected by \fB\-\-video\-sync\fP) is
12751 active. Returns the actual rate at which display refreshes seem to occur,
12752 measured by system time.
12753 .TP
12754 .B \fBvsync\-jitter\fP
12755 Estimated deviation factor of the vsync duration.
12756 .TP
12757 .B \fBvideo\-aspect\fP (RW)
12758 Deprecated. This is tied to \fB\-\-video\-aspect\-override\fP, but always
12759 reports the current video aspect if video is active.
12760 .sp
12761 The read and write components of this option can be split up into
12762 \fBvideo\-params/aspect\fP and \fBvideo\-aspect\-override\fP respectively.
12763 .TP
12764 .B \fBosd\-width\fP, \fBosd\-height\fP
12765 Last known OSD width (can be 0). This is needed if you want to use the
12766 \fBoverlay\-add\fP command. It gives you the actual OSD size, which can be
12767 different from the window size in some cases.
12768 .TP
12769 .B \fBosd\-par\fP
12770 Last known OSD display pixel aspect (can be 0).
12771 .TP
12772 .B \fBsub\-text\fP
12773 Return the current subtitle text regardless of sub visibility.
12774 Formatting is stripped. If the subtitle is not text\-based
12775 (i.e. DVD/BD subtitles), an empty string is returned.
12776 .sp
12777 This property is experimental and might be removed in the future.
12778 .TP
12779 .B \fBsub\-start\fP
12780 Return the current subtitle start time (in seconds). If there\(aqs multiple
12781 current subtitles, returns the first start time. If no current subtitle is
12782 present null is returned instead.
12783 .TP
12784 .B \fBsub\-end\fP
12785 Return the current subtitle start time (in seconds). If there\(aqs multiple
12786 current subtitles, return the last end time. If no current subtitle is
12787 present, or if it\(aqs present but has unknown or incorrect duration, null
12788 is returned instead.
12789 .TP
12790 .B \fBplaylist\-pos\fP (RW)
12791 Current position on playlist. The first entry is on position 0. Writing
12792 to the property will restart playback at the written entry.
12793 .TP
12794 .B \fBplaylist\-pos\-1\fP (RW)
12795 Same as \fBplaylist\-pos\fP, but 1\-based.
12796 .TP
12797 .B \fBplaylist\-count\fP
12798 Number of total playlist entries.
12799 .TP
12800 .B \fBplaylist\fP
12801 Playlist, current entry marked. Currently, the raw property value is
12802 useless.
12803 .sp
12804 This has a number of sub\-properties. Replace \fBN\fP with the 0\-based playlist
12805 entry index.
12806 .INDENT 7.0
12807 .TP
12808 .B \fBplaylist/count\fP
12809 Number of playlist entries (same as \fBplaylist\-count\fP).
12810 .TP
12811 .B \fBplaylist/N/filename\fP
12812 Filename of the Nth entry.
12813 .TP
12814 .B \fBplaylist/N/current\fP, \fBplaylist/N/playing\fP
12815 \fByes\fP if this entry is currently playing (or being loaded).
12816 Unavailable or \fBno\fP otherwise. When changing files, \fBcurrent\fP and
12817 \fBplaying\fP can be different, because the currently playing file hasn\(aqt
12818 been unloaded yet; in this case, \fBcurrent\fP refers to the new
12819 selection. (Since mpv 0.7.0.)
12820 .TP
12821 .B \fBplaylist/N/title\fP
12822 Name of the Nth entry. Only available if the playlist file contains
12823 such fields, and only if mpv\(aqs parser supports it for the given
12824 playlist format.
12825 .UNINDENT
12826 .sp
12827 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
12828 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
12829 the following contents:
12830 .INDENT 7.0
12831 .INDENT 3.5
12832 .sp
12833 .nf
12834 .ft C
12835 MPV_FORMAT_NODE_ARRAY
12836 MPV_FORMAT_NODE_MAP (for each playlist entry)
12837 "filename" MPV_FORMAT_STRING
12838 "current" MPV_FORMAT_FLAG (might be missing; since mpv 0.7.0)
12839 "playing" MPV_FORMAT_FLAG (same)
12840 "title" MPV_FORMAT_STRING (optional)
12841 .ft P
12842 .fi
12843 .UNINDENT
12844 .UNINDENT
12845 .TP
12846 .B \fBtrack\-list\fP
12847 List of audio/video/sub tracks, current entry marked. Currently, the raw
12848 property value is useless.
12849 .sp
12850 This has a number of sub\-properties. Replace \fBN\fP with the 0\-based track
12851 index.
12852 .INDENT 7.0
12853 .TP
12854 .B \fBtrack\-list/count\fP
12855 Total number of tracks.
12856 .TP
12857 .B \fBtrack\-list/N/id\fP
12858 The ID as it\(aqs used for \fB\-sid\fP/\fB\-\-aid\fP/\fB\-\-vid\fP\&. This is unique
12859 within tracks of the same type (sub/audio/video), but otherwise not.
12860 .TP
12861 .B \fBtrack\-list/N/type\fP
12862 String describing the media type. One of \fBaudio\fP, \fBvideo\fP, \fBsub\fP\&.
12863 .TP
12864 .B \fBtrack\-list/N/src\-id\fP
12865 Track ID as used in the source file. Not always available.
12866 .TP
12867 .B \fBtrack\-list/N/title\fP
12868 Track title as it is stored in the file. Not always available.
12869 .TP
12870 .B \fBtrack\-list/N/lang\fP
12871 Track language as identified by the file. Not always available.
12872 .TP
12873 .B \fBtrack\-list/N/albumart\fP
12874 \fByes\fP if this is a video track that consists of a single picture,
12875 \fBno\fP or unavailable otherwise. This is used for video tracks that are
12876 really attached pictures in audio files.
12877 .TP
12878 .B \fBtrack\-list/N/default\fP
12879 \fByes\fP if the track has the default flag set in the file, \fBno\fP
12880 otherwise.
12881 .TP
12882 .B \fBtrack\-list/N/forced\fP
12883 \fByes\fP if the track has the forced flag set in the file, \fBno\fP
12884 otherwise.
12885 .TP
12886 .B \fBtrack\-list/N/codec\fP
12887 The codec name used by this track, for example \fBh264\fP\&. Unavailable
12888 in some rare cases.
12889 .TP
12890 .B \fBtrack\-list/N/external\fP
12891 \fByes\fP if the track is an external file, \fBno\fP otherwise. This is
12892 set for separate subtitle files.
12893 .TP
12894 .B \fBtrack\-list/N/external\-filename\fP
12895 The filename if the track is from an external file, unavailable
12896 otherwise.
12897 .TP
12898 .B \fBtrack\-list/N/selected\fP
12899 \fByes\fP if the track is currently decoded, \fBno\fP otherwise.
12900 .TP
12901 .B \fBtrack\-list/N/ff\-index\fP
12902 The stream index as usually used by the FFmpeg utilities. Note that
12903 this can be potentially wrong if a demuxer other than libavformat
12904 (\fB\-\-demuxer=lavf\fP) is used. For mkv files, the index will usually
12905 match even if the default (builtin) demuxer is used, but there is
12906 no hard guarantee.
12907 .TP
12908 .B \fBtrack\-list/N/decoder\-desc\fP
12909 If this track is being decoded, the human\-readable decoder name,
12910 .TP
12911 .B \fBtrack\-list/N/demux\-w\fP, \fBtrack\-list/N/demux\-h\fP
12912 Video size hint as indicated by the container. (Not always accurate.)
12913 .TP
12914 .B \fBtrack\-list/N/demux\-channel\-count\fP
12915 Number of audio channels as indicated by the container. (Not always
12916 accurate \- in particular, the track could be decoded as a different
12917 number of channels.)
12918 .TP
12919 .B \fBtrack\-list/N/demux\-channels\fP
12920 Channel layout as indicated by the container. (Not always accurate.)
12921 .TP
12922 .B \fBtrack\-list/N/demux\-samplerate\fP
12923 Audio sample rate as indicated by the container. (Not always accurate.)
12924 .TP
12925 .B \fBtrack\-list/N/demux\-fps\fP
12926 Video FPS as indicated by the container. (Not always accurate.)
12927 .TP
12928 .B \fBtrack\-list/N/demux\-bitrate\fP
12929 Audio average bitrate, in bits per second. (Not always accurate.)
12930 .TP
12931 .B \fBtrack\-list/N/demux\-rotation\fP
12932 Video clockwise rotation metadata, in degrees.
12933 .TP
12934 .B \fBtrack\-list/N/demux\-par\fP
12935 Pixel aspect ratio.
12936 .TP
12937 .B \fBtrack\-list/N/audio\-channels\fP (deprecated)
12938 Deprecated alias for \fBtrack\-list/N/demux\-channel\-count\fP\&.
12939 .TP
12940 .B \fBtrack\-list/N/replaygain\-track\-peak\fP, \fBtrack\-list/N/replaygain\-track\-gain\fP
12941 Per\-track replaygain values. Only available for audio tracks with
12942 corresponding information stored in the source file.
12943 .TP
12944 .B \fBtrack\-list/N/replaygain\-album\-peak\fP, \fBtrack\-list/N/replaygain\-album\-gain\fP
12945 Per\-album replaygain values. If the file has per\-track but no per\-album
12946 information, the per\-album values will be copied from the per\-track
12947 values currently. It\(aqs possible that future mpv versions will make
12948 these properties unavailable instead in this case.
12949 .UNINDENT
12950 .sp
12951 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
12952 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
12953 the following contents:
12954 .INDENT 7.0
12955 .INDENT 3.5
12956 .sp
12957 .nf
12958 .ft C
12959 MPV_FORMAT_NODE_ARRAY
12960 MPV_FORMAT_NODE_MAP (for each track)
12961 "id" MPV_FORMAT_INT64
12962 "type" MPV_FORMAT_STRING
12963 "src\-id" MPV_FORMAT_INT64
12964 "title" MPV_FORMAT_STRING
12965 "lang" MPV_FORMAT_STRING
12966 "albumart" MPV_FORMAT_FLAG
12967 "default" MPV_FORMAT_FLAG
12968 "forced" MPV_FORMAT_FLAG
12969 "selected" MPV_FORMAT_FLAG
12970 "external" MPV_FORMAT_FLAG
12971 "external\-filename" MPV_FORMAT_STRING
12972 "codec" MPV_FORMAT_STRING
12973 "ff\-index" MPV_FORMAT_INT64
12974 "decoder\-desc" MPV_FORMAT_STRING
12975 "demux\-w" MPV_FORMAT_INT64
12976 "demux\-h" MPV_FORMAT_INT64
12977 "demux\-channel\-count" MPV_FORMAT_INT64
12978 "demux\-channels" MPV_FORMAT_STRING
12979 "demux\-samplerate" MPV_FORMAT_INT64
12980 "demux\-fps" MPV_FORMAT_DOUBLE
12981 "demux\-bitrate" MPV_FORMAT_INT64
12982 "demux\-rotation" MPV_FORMAT_INT64
12983 "demux\-par" MPV_FORMAT_DOUBLE
12984 "audio\-channels" MPV_FORMAT_INT64
12985 "replaygain\-track\-peak" MPV_FORMAT_DOUBLE
12986 "replaygain\-track\-gain" MPV_FORMAT_DOUBLE
12987 "replaygain\-album\-peak" MPV_FORMAT_DOUBLE
12988 "replaygain\-album\-gain" MPV_FORMAT_DOUBLE
12989 .ft P
12990 .fi
12991 .UNINDENT
12992 .UNINDENT
12993 .TP
12994 .B \fBchapter\-list\fP
12995 List of chapters, current entry marked. Currently, the raw property value
12996 is useless.
12997 .sp
12998 This has a number of sub\-properties. Replace \fBN\fP with the 0\-based chapter
12999 index.
13000 .INDENT 7.0
13001 .TP
13002 .B \fBchapter\-list/count\fP
13003 Number of chapters.
13004 .TP
13005 .B \fBchapter\-list/N/title\fP
13006 Chapter title as stored in the file. Not always available.
13007 .TP
13008 .B \fBchapter\-list/N/time\fP
13009 Chapter start time in seconds as float.
13010 .UNINDENT
13011 .sp
13012 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
13013 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
13014 the following contents:
13015 .INDENT 7.0
13016 .INDENT 3.5
13017 .sp
13018 .nf
13019 .ft C
13020 MPV_FORMAT_NODE_ARRAY
13021 MPV_FORMAT_NODE_MAP (for each chapter)
13022 "title" MPV_FORMAT_STRING
13023 "time" MPV_FORMAT_DOUBLE
13024 .ft P
13025 .fi
13026 .UNINDENT
13027 .UNINDENT
13028 .TP
13029 .B \fBaf\fP, \fBvf\fP (RW)
13030 See \fB\-\-vf\fP/\fB\-\-af\fP and the \fBvf\fP/\fBaf\fP command.
13031 .sp
13032 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
13033 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
13034 the following contents:
13035 .INDENT 7.0
13036 .INDENT 3.5
13037 .sp
13038 .nf
13039 .ft C
13040 MPV_FORMAT_NODE_ARRAY
13041 MPV_FORMAT_NODE_MAP (for each filter entry)
13042 "name" MPV_FORMAT_STRING
13043 "label" MPV_FORMAT_STRING [optional]
13044 "enabled" MPV_FORMAT_FLAG [optional]
13045 "params" MPV_FORMAT_NODE_MAP [optional]
13046 "key" MPV_FORMAT_STRING
13047 "value" MPV_FORMAT_STRING
13048 .ft P
13049 .fi
13050 .UNINDENT
13051 .UNINDENT
13052 .sp
13053 It\(aqs also possible to write the property using this format.
13054 .TP
13055 .B \fBseekable\fP
13056 Return whether it\(aqs generally possible to seek in the current file.
13057 .TP
13058 .B \fBpartially\-seekable\fP
13059 Return \fByes\fP if the current file is considered seekable, but only because
13060 the cache is active. This means small relative seeks may be fine, but larger
13061 seeks may fail anyway. Whether a seek will succeed or not is generally not
13062 known in advance.
13063 .sp
13064 If this property returns true, \fBseekable\fP will also return true.
13065 .TP
13066 .B \fBplayback\-abort\fP
13067 Return whether playback is stopped or is to be stopped. (Useful in obscure
13068 situations like during \fBon_load\fP hook processing, when the user can
13069 stop playback, but the script has to explicitly end processing.)
13070 .TP
13071 .B \fBcursor\-autohide\fP (RW)
13072 See \fB\-\-cursor\-autohide\fP\&. Setting this to a new value will always update
13073 the cursor, and reset the internal timer.
13074 .TP
13075 .B \fBosd\-sym\-cc\fP
13076 Inserts the current OSD symbol as opaque OSD control code (cc). This makes
13077 sense only with the \fBshow\-text\fP command or options which set OSD messages.
13078 The control code is implementation specific and is useless for anything else.
13079 .TP
13080 .B \fBosd\-ass\-cc\fP
13081 \fB${osd\-ass\-cc/0}\fP disables escaping ASS sequences of text in OSD,
13082 \fB${osd\-ass\-cc/1}\fP enables it again. By default, ASS sequences are
13083 escaped to avoid accidental formatting, and this property can disable
13084 this behavior. Note that the properties return an opaque OSD control
13085 code, which only makes sense for the \fBshow\-text\fP command or options
13086 which set OSD messages.
13087 .INDENT 7.0
13088 .INDENT 3.5
13089 .IP "Example"
13090 .INDENT 0.0
13091 .IP \(bu 2
13092 \fB\-\-osd\-status\-msg=\(aqThis is ${osd\-ass\-cc/0}{\e\eb1}bold text\(aq\fP
13093 .IP \(bu 2
13094 \fBshow\-text "This is ${osd\-ass\-cc/0}{\eb1}bold text"\fP
13095 .UNINDENT
13096 .UNINDENT
13097 .UNINDENT
13098 .sp
13099 Any ASS override tags as understood by libass can be used.
13100 .sp
13101 Note that you need to escape the \fB\e\fP character, because the string is
13102 processed for C escape sequences before passing it to the OSD code.
13103 .sp
13104 A list of tags can be found here: \fI\%http://docs.aegisub.org/latest/ASS_Tags/\fP
13105 .TP
13106 .B \fBvo\-configured\fP
13107 Return whether the VO is configured right now. Usually this corresponds to
13108 whether the video window is visible. If the \fB\-\-force\-window\fP option is
13109 used, this is usually always returns \fByes\fP\&.
13110 .TP
13111 .B \fBvo\-passes\fP
13112 Contains introspection about the VO\(aqs active render passes and their
13113 execution times. Not implemented by all VOs.
13114 .sp
13115 This is further subdivided into two frame types, \fBvo\-passes/fresh\fP for
13116 fresh frames (which have to be uploaded, scaled, etc.) and
13117 \fBvo\-passes/redraw\fP for redrawn frames (which only have to be re\-painted).
13118 The number of passes for any given subtype can change from frame to frame,
13119 and should not be relied upon.
13120 .sp
13121 Each frame type has a number of further sub\-properties. Replace \fBTYPE\fP
13122 with the frame type, \fBN\fP with the 0\-based pass index, and \fBM\fP with the
13123 0\-based sample index.
13124 .INDENT 7.0
13125 .TP
13126 .B \fBvo\-passes/TYPE/count\fP
13127 Number of passes.
13128 .TP
13129 .B \fBvo\-passes/TYPE/N/desc\fP
13130 Human\-friendy description of the pass.
13131 .TP
13132 .B \fBvo\-passes/TYPE/N/last\fP
13133 Last measured execution time, in nanoseconds.
13134 .TP
13135 .B \fBvo\-passes/TYPE/N/avg\fP
13136 Average execution time of this pass, in nanoseconds. The exact
13137 timeframe varies, but it should generally be a handful of seconds.
13138 .TP
13139 .B \fBvo\-passes/TYPE/N/peak\fP
13140 The peak execution time (highest value) within this averaging range, in
13141 nanoseconds.
13142 .TP
13143 .B \fBvo\-passes/TYPE/N/count\fP
13144 The number of samples for this pass.
13145 .TP
13146 .B \fBvo\-passes/TYPE/N/samples/M\fP
13147 The raw execution time of a specific sample for this pass, in
13148 nanoseconds.
13149 .UNINDENT
13150 .sp
13151 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
13152 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
13153 the following contents:
13154 .INDENT 7.0
13155 .INDENT 3.5
13156 .sp
13157 .nf
13158 .ft C
13159 MPV_FORMAT_NODE_MAP
13160 "TYPE" MPV_FORMAT_NODE_ARRAY
13161 MPV_FORMAT_NODE_MAP
13162 "desc" MPV_FORMAT_STRING
13163 "last" MPV_FORMAT_INT64
13164 "avg" MPV_FORMAT_INT64
13165 "peak" MPV_FORMAT_INT64
13166 "count" MPV_FORMAT_INT64
13167 "samples" MPV_FORMAT_NODE_ARRAY
13168 MP_FORMAT_INT64
13169 .ft P
13170 .fi
13171 .UNINDENT
13172 .UNINDENT
13173 .sp
13174 Note that directly accessing this structure via subkeys is not supported,
13175 the only access is through aforementioned \fBMPV_FORMAT_NODE\fP\&.
13176 .TP
13177 .B \fBvideo\-bitrate\fP, \fBaudio\-bitrate\fP, \fBsub\-bitrate\fP
13178 Bitrate values calculated on the packet level. This works by dividing the
13179 bit size of all packets between two keyframes by their presentation
13180 timestamp distance. (This uses the timestamps are stored in the file, so
13181 e.g. playback speed does not influence the returned values.) In particular,
13182 the video bitrate will update only per keyframe, and show the "past"
13183 bitrate. To make the property more UI friendly, updates to these properties
13184 are throttled in a certain way.
13185 .sp
13186 The unit is bits per second. OSD formatting turns these values in kilobits
13187 (or megabits, if appropriate), which can be prevented by using the
13188 raw property value, e.g. with \fB${=video\-bitrate}\fP\&.
13189 .sp
13190 Note that the accuracy of these properties is influenced by a few factors.
13191 If the underlying demuxer rewrites the packets on demuxing (done for some
13192 file formats), the bitrate might be slightly off. If timestamps are bad
13193 or jittery (like in Matroska), even constant bitrate streams might show
13194 fluctuating bitrate.
13195 .sp
13196 How exactly these values are calculated might change in the future.
13197 .sp
13198 In earlier versions of mpv, these properties returned a static (but bad)
13199 guess using a completely different method.
13200 .TP
13201 .B \fBpacket\-video\-bitrate\fP, \fBpacket\-audio\-bitrate\fP, \fBpacket\-sub\-bitrate\fP
13202 Old and deprecated properties for \fBvideo\-bitrate\fP, \fBaudio\-bitrate\fP,
13203 \fBsub\-bitrate\fP\&. They behave exactly the same, but return a value in
13204 kilobits. Also, they don\(aqt have any OSD formatting, though the same can be
13205 achieved with e.g. \fB${=video\-bitrate}\fP\&.
13206 .sp
13207 These properties shouldn\(aqt be used anymore.
13208 .TP
13209 .B \fBaudio\-device\-list\fP
13210 Return the list of discovered audio devices. This is mostly for use with
13211 the client API, and reflects what \fB\-\-audio\-device=help\fP with the command
13212 line player returns.
13213 .sp
13214 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
13215 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
13216 the following contents:
13217 .INDENT 7.0
13218 .INDENT 3.5
13219 .sp
13220 .nf
13221 .ft C
13222 MPV_FORMAT_NODE_ARRAY
13223 MPV_FORMAT_NODE_MAP (for each device entry)
13224 "name" MPV_FORMAT_STRING
13225 "description" MPV_FORMAT_STRING
13226 .ft P
13227 .fi
13228 .UNINDENT
13229 .UNINDENT
13230 .sp
13231 The \fBname\fP is what is to be passed to the \fB\-\-audio\-device\fP option (and
13232 often a rather cryptic audio API\-specific ID), while \fBdescription\fP is
13233 human readable free form text. The description is set to the device name
13234 (minus mpv\-specific \fB<driver>/\fP prefix) if no description is available
13235 or the description would have been an empty string.
13236 .sp
13237 The special entry with the name set to \fBauto\fP selects the default audio
13238 output driver and the default device.
13239 .sp
13240 The property can be watched with the property observation mechanism in
13241 the client API and in Lua scripts. (Technically, change notification is
13242 enabled the first time this property is read.)
13243 .TP
13244 .B \fBaudio\-device\fP (RW)
13245 Set the audio device. This directly reads/writes the \fB\-\-audio\-device\fP
13246 option, but on write accesses, the audio output will be scheduled for
13247 reloading.
13248 .sp
13249 Writing this property while no audio output is active will not automatically
13250 enable audio. (This is also true in the case when audio was disabled due to
13251 reinitialization failure after a previous write access to \fBaudio\-device\fP\&.)
13252 .sp
13253 This property also doesn\(aqt tell you which audio device is actually in use.
13254 .sp
13255 How these details are handled may change in the future.
13256 .TP
13257 .B \fBcurrent\-vo\fP
13258 Current video output driver (name as used with \fB\-\-vo\fP).
13259 .TP
13260 .B \fBcurrent\-ao\fP
13261 Current audio output driver (name as used with \fB\-\-ao\fP).
13262 .TP
13263 .B \fBworking\-directory\fP
13264 Return the working directory of the mpv process. Can be useful for JSON IPC
13265 users, because the command line player usually works with relative paths.
13266 .TP
13267 .B \fBprotocol\-list\fP
13268 List of protocol prefixes potentially recognized by the player. They are
13269 returned without trailing \fB://\fP suffix (which is still always required).
13270 In some cases, the protocol will not actually be supported (consider
13271 \fBhttps\fP if ffmpeg is not compiled with TLS support).
13272 .TP
13273 .B \fBdecoder\-list\fP
13274 List of decoders supported. This lists decoders which can be passed to
13275 \fB\-\-vd\fP and \fB\-\-ad\fP\&.
13276 .INDENT 7.0
13277 .TP
13278 .B \fBcodec\fP
13279 Canonical codec name, which identifies the format the decoder can
13280 handle.
13281 .TP
13282 .B \fBdriver\fP
13283 The name of the decoder itself. Often, this is the same as \fBcodec\fP\&.
13284 Sometimes it can be different. It is used to distinguish multiple
13285 decoders for the same codec.
13286 .TP
13287 .B \fBdescription\fP
13288 Human readable description of the decoder and codec.
13289 .UNINDENT
13290 .sp
13291 When querying the property with the client API using \fBMPV_FORMAT_NODE\fP,
13292 or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with
13293 the following contents:
13294 .INDENT 7.0
13295 .INDENT 3.5
13296 .sp
13297 .nf
13298 .ft C
13299 MPV_FORMAT_NODE_ARRAY
13300 MPV_FORMAT_NODE_MAP (for each decoder entry)
13301 "codec" MPV_FORMAT_STRING
13302 "driver" MPV_FORMAT_STRING
13303 "description" MPV_FORMAT_STRING
13304 .ft P
13305 .fi
13306 .UNINDENT
13307 .UNINDENT
13308 .TP
13309 .B \fBencoder\-list\fP
13310 List of libavcodec encoders. This has the same format as \fBdecoder\-list\fP\&.
13311 The encoder names (\fBdriver\fP entries) can be passed to \fB\-\-ovc\fP and
13312 \fB\-\-oac\fP (without the \fBlavc:\fP prefix required by \fB\-\-vd\fP and \fB\-\-ad\fP).
13313 .TP
13314 .B \fBdemuxer\-lavf\-list\fP
13315 List of available libavformat demuxers\(aq names. This can be used to check
13316 for support for a specific format or use with \fB\-\-demuxer\-lavf\-format\fP\&.
13317 .TP
13318 .B \fBmpv\-version\fP
13319 Return the mpv version/copyright string. Depending on how the binary was
13320 built, it might contain either a release version, or just a git hash.
13321 .TP
13322 .B \fBmpv\-configuration\fP
13323 Return the configuration arguments which were passed to the build system
13324 (typically the way \fB\&./waf configure ...\fP was invoked).
13325 .TP
13326 .B \fBffmpeg\-version\fP
13327 Return the contents of the \fBav_version_info()\fP API call. This is a string
13328 which identifies the build in some way, either through a release version
13329 number, or a git hash. This applies to Libav as well (the property is
13330 still named the same.) This property is unavailable if mpv is linked against
13331 older FFmpeg and Libav versions.
13332 .TP
13333 .B \fBoptions/<name>\fP (RW)
13334 Read\-only access to value of option \fB\-\-<name>\fP\&. Most options can be
13335 changed at runtime by writing to this property. Note that many options
13336 require reloading the file for changes to take effect. If there is an
13337 equivalent property, prefer setting the property instead.
13338 .sp
13339 There shouldn\(aqt be any reason to access \fBoptions/<name>\fP instead of
13340 \fB<name>\fP, except in situations in which the properties have different
13341 behavior or conflicting semantics.
13342 .TP
13343 .B \fBfile\-local\-options/<name>\fP
13344 Similar to \fBoptions/<name>\fP, but when setting an option through this
13345 property, the option is reset to its old value once the current file has
13346 stopped playing. Trying to write an option while no file is playing (or
13347 is being loaded) results in an error.
13348 .sp
13349 (Note that if an option is marked as file\-local, even \fBoptions/\fP will
13350 access the local value, and the \fBold\fP value, which will be restored on
13351 end of playback, cannot be read or written until end of playback.)
13352 .TP
13353 .B \fBoption\-info/<name>\fP
13354 Additional per\-option information.
13355 .sp
13356 This has a number of sub\-properties. Replace \fB<name>\fP with the name of
13357 a top\-level option. No guarantee of stability is given to any of these
13358 sub\-properties \- they may change radically in the feature.
13359 .INDENT 7.0
13360 .TP
13361 .B \fBoption\-info/<name>/name\fP
13362 Returns the name of the option.
13363 .TP
13364 .B \fBoption\-info/<name>/type\fP
13365 Return the name of the option type, like \fBString\fP or \fBInteger\fP\&.
13366 For many complex types, this isn\(aqt very accurate.
13367 .TP
13368 .B \fBoption\-info/<name>/set\-from\-commandline\fP
13369 Return \fByes\fP if the option was set from the mpv command line,
13370 \fBno\fP otherwise. What this is set to if the option is e.g. changed
13371 at runtime is left undefined (meaning it could change in the future).
13372 .TP
13373 .B \fBoption\-info/<name>/set\-locally\fP
13374 Return \fByes\fP if the option was set per\-file. This is the case with
13375 automatically loaded profiles, file\-dir configs, and other cases. It
13376 means the option value will be restored to the value before playback
13377 start when playback ends.
13378 .TP
13379 .B \fBoption\-info/<name>/default\-value\fP
13380 The default value of the option. May not always be available.
13381 .TP
13382 .B \fBoption\-info/<name>/min\fP, \fBoption\-info/<name>/max\fP
13383 Integer minimum and maximum values allowed for the option. Only
13384 available if the options are numeric, and the minimum/maximum has been
13385 set internally. It\(aqs also possible that only one of these is set.
13386 .TP
13387 .B \fBoption\-info/<name>/choices\fP
13388 If the option is a choice option, the possible choices. Choices that
13389 are integers may or may not be included (they can be implied by \fBmin\fP
13390 and \fBmax\fP). Note that options which behave like choice options, but
13391 are not actual choice options internally, may not have this info
13392 available.
13393 .UNINDENT
13394 .TP
13395 .B \fBproperty\-list\fP
13396 Return the list of top\-level properties.
13397 .TP
13398 .B \fBprofile\-list\fP
13399 Return the list of profiles and their contents. This is highly
13400 implementation\-specific, and may change any time. Currently, it returns
13401 an array of options for each profile. Each option has a name and a value,
13402 with the value currently always being a string. Note that the options array
13403 is not a map, as order matters and duplicate entries are possible. Recursive
13404 profiles are not expanded, and show up as special \fBprofile\fP options.
13405 .UNINDENT
13406 .SS Inconsistencies between options and properties
13407 .sp
13408 You can access (almost) all options as properties, though there are some
13409 caveats with some properties (due to historical reasons):
13410 .INDENT 0.0
13411 .TP
13412 .B \fBvid\fP, \fBaid\fP, \fBsid\fP
13413 While playback is active, you can set existing tracks only. (The option
13414 allows setting any track ID, and which tracks to enable is chosen at
13415 loading time.)
13416 .sp
13417 Option changes at runtime are affected by this as well.
13418 .TP
13419 .B \fBdisplay\-fps\fP
13420 If a VO is created, this will return either the actual display FPS, or
13421 an invalid value, instead of the option value.
13422 .TP
13423 .B \fBvf\fP, \fBaf\fP
13424 If you set the properties during playback, and the filter chain fails to
13425 reinitialize, the new value will be rejected. Setting the option or
13426 setting the property outside of playback will always succeed/fail in the
13427 same way. Also, there are no \fBvf\-add\fP etc. properties, but you can use
13428 the \fBvf\fP/\fBaf\fP group of commands to achieve the same.
13429 .sp
13430 Option changes at runtime are affected by this as well.
13431 .TP
13432 .B \fBedition\fP
13433 While a file is loaded, the property will always return the effective
13434 edition, and setting the \fBauto\fP value will show somewhat strange behavior
13435 (the property eventually switching to whatever is the default edition).
13436 .TP
13437 .B \fBplaylist\fP
13438 The property is read\-only and returns the current internal playlist. The
13439 option is for loading playlist during command line parsing. For client API
13440 uses, you should use the \fBloadlist\fP command instead.
13441 .TP
13442 .B \fBwindow\-scale\fP
13443 Might verify the set value when setting while a window is created.
13444 .TP
13445 .B \fBaudio\-file\fP, \fBsub\-file\fP, \fBexternal\-file\fP
13446 These options/properties are actually lists of filenames. To make the
13447 command\-line interface easier, each \fB\-\-audio\-file=...\fP option appends
13448 the full string to the internal list. However, when used as properties,
13449 every time you set the property as a string the internal list will be
13450 replaced with a single entry containing the string you set. \fB,\fP or other
13451 separators are never used. You have to use \fBMPV_FORMAT_NODE_ARRAY\fP (or
13452 corresponding API, e.g. \fBmp.set_property_native()\fP with a table in Lua)
13453 to set multiple entries.
13454 .sp
13455 Strictly speaking, option access via API (e.g. \fBmpv_set_option_string()\fP)
13456 has the same problem, and it\(aqs only a difference between CLI/API.
13457 .TP
13458 .B \fBplaylist\-pos\fP, \fBchapter\fP
13459 These properties behave different from the deprecated options with the same
13460 names.
13461 .TP
13462 .B \fBprofile\fP, \fBinclude\fP
13463 These are write\-only, and will perform actions as they are written to,
13464 exactly as if they were used on the mpv CLI commandline. Their only use is
13465 when using libmpv before \fBmpv_initialize()\fP, which in turn is probably
13466 only useful in encoding mode. Normal libmpv users should use other
13467 mechanisms, such as the \fBapply\-profile\fP command, and the
13468 \fBmpv_load_config_file\fP API function. Avoid these properties.
13469 .UNINDENT
13470 .SS Property Expansion
13471 .sp
13472 All string arguments to input commands as well as certain options (like
13473 \fB\-\-term\-playing\-msg\fP) are subject to property expansion. Note that property
13474 expansion does not work in places where e.g. numeric parameters are expected.
13475 (For example, the \fBadd\fP command does not do property expansion. The \fBset\fP
13476 command is an exception and not a general rule.)
13477 .INDENT 0.0
13478 .INDENT 3.5
13479 .IP "Example for input.conf"
13480 .INDENT 0.0
13481 .TP
13482 .B \fBi show\-text "Filename: ${filename}"\fP
13483 shows the filename of the current file when pressing the \fBi\fP key
13484 .UNINDENT
13485 .UNINDENT
13486 .UNINDENT
13487 .sp
13488 Within \fBinput.conf\fP, property expansion can be inhibited by putting the
13489 \fBraw\fP prefix in front of commands.
13490 .sp
13491 The following expansions are supported:
13492 .INDENT 0.0
13493 .TP
13494 .B \fB${NAME}\fP
13495 Expands to the value of the property \fBNAME\fP\&. If retrieving the property
13496 fails, expand to an error string. (Use \fB${NAME:}\fP with a trailing
13497 \fB:\fP to expand to an empty string instead.)
13498 If \fBNAME\fP is prefixed with \fB=\fP, expand to the raw value of the property
13499 (see section below).
13500 .TP
13501 .B \fB${NAME:STR}\fP
13502 Expands to the value of the property \fBNAME\fP, or \fBSTR\fP if the
13503 property cannot be retrieved. \fBSTR\fP is expanded recursively.
13504 .TP
13505 .B \fB${?NAME:STR}\fP
13506 Expands to \fBSTR\fP (recursively) if the property \fBNAME\fP is available.
13507 .TP
13508 .B \fB${!NAME:STR}\fP
13509 Expands to \fBSTR\fP (recursively) if the property \fBNAME\fP cannot be
13510 retrieved.
13511 .TP
13512 .B \fB${?NAME==VALUE:STR}\fP
13513 Expands to \fBSTR\fP (recursively) if the property \fBNAME\fP expands to a
13514 string equal to \fBVALUE\fP\&. You can prefix \fBNAME\fP with \fB=\fP in order to
13515 compare the raw value of a property (see section below). If the property
13516 is unavailable, or other errors happen when retrieving it, the value is
13517 never considered equal.
13518 Note that \fBVALUE\fP can\(aqt contain any of the characters \fB:\fP or \fB}\fP\&.
13519 Also, it is possible that escaping with \fB"\fP or \fB%\fP might be added in
13520 the future, should the need arise.
13521 .TP
13522 .B \fB${!NAME==VALUE:STR}\fP
13523 Same as with the \fB?\fP variant, but \fBSTR\fP is expanded if the value is
13524 not equal. (Using the same semantics as with \fB?\fP\&.)
13525 .TP
13526 .B \fB$$\fP
13527 Expands to \fB$\fP\&.
13528 .TP
13529 .B \fB$}\fP
13530 Expands to \fB}\fP\&. (To produce this character inside recursive
13531 expansion.)
13532 .TP
13533 .B \fB$>\fP
13534 Disable property expansion and special handling of \fB$\fP for the rest
13535 of the string.
13536 .UNINDENT
13537 .sp
13538 In places where property expansion is allowed, C\-style escapes are often
13539 accepted as well. Example:
13540 .INDENT 0.0
13541 .INDENT 3.5
13542 .INDENT 0.0
13543 .IP \(bu 2
13544 \fB\en\fP becomes a newline character
13545 .IP \(bu 2
13546 \fB\e\e\fP expands to \fB\e\fP
13547 .UNINDENT
13548 .UNINDENT
13549 .UNINDENT
13550 .SS Raw and Formatted Properties
13551 .sp
13552 Normally, properties are formatted as human\-readable text, meant to be
13553 displayed on OSD or on the terminal. It is possible to retrieve an unformatted
13554 (raw) value from a property by prefixing its name with \fB=\fP\&. These raw values
13555 can be parsed by other programs and follow the same conventions as the options
13556 associated with the properties.
13557 .INDENT 0.0
13558 .INDENT 3.5
13559 .IP "Examples"
13560 .INDENT 0.0
13561 .IP \(bu 2
13562 \fB${time\-pos}\fP expands to \fB00:14:23\fP (if playback position is at 14
13563 minutes 23 seconds)
13564 .IP \(bu 2
13565 \fB${=time\-pos}\fP expands to \fB863.4\fP (same time, plus 400 milliseconds \-
13566 milliseconds are normally not shown in the formatted case)
13567 .UNINDENT
13568 .UNINDENT
13569 .UNINDENT
13570 .sp
13571 Sometimes, the difference in amount of information carried by raw and formatted
13572 property values can be rather big. In some cases, raw values have more
13573 information, like higher precision than seconds with \fBtime\-pos\fP\&. Sometimes
13574 it is the other way around, e.g. \fBaid\fP shows track title and language in the
13575 formatted case, but only the track number if it is raw.
13576 .SH ON SCREEN CONTROLLER
13577 .sp
13578 The On Screen Controller (short: OSC) is a minimal GUI integrated with mpv to
13579 offer basic mouse\-controllability. It is intended to make interaction easier
13580 for new users and to enable precise and direct seeking.
13581 .sp
13582 The OSC is enabled by default if mpv was compiled with Lua support. It can be
13583 disabled entirely using the \fB\-\-osc=no\fP option.
13584 .SS Using the OSC
13585 .sp
13586 By default, the OSC will show up whenever the mouse is moved inside the
13587 player window and will hide if the mouse is not moved outside the OSC for
13588 0.5 seconds or if the mouse leaves the window.
13589 .SS The Interface
13590 .INDENT 0.0
13591 .INDENT 3.5
13592 .sp
13593 .nf
13594 .ft C
13595 +\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+
13596 | pl prev | pl next | title | cache |
13597 +\-\-\-\-\-\-+\-\-+\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-+
13598 | play | skip | skip | time | seekbar | time | audio | sub | vol | fs |
13599 | | back | frwd | elapsed | | left | | | | |
13600 +\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-+
13601 .ft P
13602 .fi
13603 .UNINDENT
13604 .UNINDENT
13605 .INDENT 0.0
13606 .TP
13607 .B pl prev
13608 .TS
13609 center;
13610 |l|l|.
13611 _
13612 T{
13613 left\-click
13614 T} T{
13615 play previous file in playlist
13616 T}
13617 _
13618 T{
13619 right\-click
13620 T} T{
13621 show playlist
13622 T}
13623 _
13624 T{
13625 shift+L\-click
13626 T} T{
13627 show playlist
13628 T}
13629 _
13630 .TE
13631 .TP
13632 .B pl next
13633 .TS
13634 center;
13635 |l|l|.
13636 _
13637 T{
13638 left\-click
13639 T} T{
13640 play next file in playlist
13641 T}
13642 _
13643 T{
13644 right\-click
13645 T} T{
13646 show playlist
13647 T}
13648 _
13649 T{
13650 shift+L\-click
13651 T} T{
13652 show playlist
13653 T}
13654 _
13655 .TE
13656 .TP
13657 .B title
13658 .nf
13659 Displays current media\-title, filename, or custom title
13660 .fi
13661 .sp
13662 .TS
13663 center;
13664 |l|l|.
13665 _
13666 T{
13667 left\-click
13668 T} T{
13669 show playlist position and length and full title
13670 T}
13671 _
13672 T{
13673 right\-click
13674 T} T{
13675 show filename
13676 T}
13677 _
13678 .TE
13679 .TP
13680 .B cache
13681 .nf
13682 Shows current cache fill status
13683 .fi
13684 .sp
13685 .TP
13686 .B play
13687 .TS
13688 center;
13689 |l|l|.
13690 _
13691 T{
13692 left\-click
13693 T} T{
13694 toggle play/pause
13695 T}
13696 _
13697 .TE
13698 .TP
13699 .B skip back
13700 .TS
13701 center;
13702 |l|l|.
13703 _
13704 T{
13705 left\-click
13706 T} T{
13707 go to beginning of chapter / previous chapter
13708 T}
13709 _
13710 T{
13711 right\-click
13712 T} T{
13713 show chapters
13714 T}
13715 _
13716 T{
13717 shift+L\-click
13718 T} T{
13719 show chapters
13720 T}
13721 _
13722 .TE
13723 .TP
13724 .B skip frwd
13725 .TS
13726 center;
13727 |l|l|.
13728 _
13729 T{
13730 left\-click
13731 T} T{
13732 go to next chapter
13733 T}
13734 _
13735 T{
13736 right\-click
13737 T} T{
13738 show chapters
13739 T}
13740 _
13741 T{
13742 shift+L\-click
13743 T} T{
13744 show chapters
13745 T}
13746 _
13747 .TE
13748 .TP
13749 .B time elapsed
13750 .nf
13751 Shows current playback position timestamp
13752 .fi
13753 .sp
13754 .TS
13755 center;
13756 |l|l|.
13757 _
13758 T{
13759 left\-click
13760 T} T{
13761 toggle displaying timecodes with milliseconds
13762 T}
13763 _
13764 .TE
13765 .TP
13766 .B seekbar
13767 .nf
13768 Indicates current playback position and position of chapters
13769 .fi
13770 .sp
13771 .TS
13772 center;
13773 |l|l|.
13774 _
13775 T{
13776 left\-click
13777 T} T{
13778 seek to position
13779 T}
13780 _
13781 .TE
13782 .TP
13783 .B time left
13784 .nf
13785 Shows remaining playback time timestamp
13786 .fi
13787 .sp
13788 .TS
13789 center;
13790 |l|l|.
13791 _
13792 T{
13793 left\-click
13794 T} T{
13795 toggle between total and remaining time
13796 T}
13797 _
13798 .TE
13799 .TP
13800 .B audio and sub
13801 .nf
13802 Displays selected track and amount of available tracks
13803 .fi
13804 .sp
13805 .TS
13806 center;
13807 |l|l|.
13808 _
13809 T{
13810 left\-click
13811 T} T{
13812 cycle audio/sub tracks forward
13813 T}
13814 _
13815 T{
13816 right\-click
13817 T} T{
13818 cycle audio/sub tracks backwards
13819 T}
13820 _
13821 T{
13822 shift+L\-click
13823 T} T{
13824 show available audio/sub tracks
13825 T}
13826 _
13827 .TE
13828 .TP
13829 .B vol
13830 .TS
13831 center;
13832 |l|l|.
13833 _
13834 T{
13835 left\-click
13836 T} T{
13837 toggle mute
13838 T}
13839 _
13840 T{
13841 mouse wheel
13842 T} T{
13843 volume up/down
13844 T}
13845 _
13846 .TE
13847 .TP
13848 .B fs
13849 .TS
13850 center;
13851 |l|l|.
13852 _
13853 T{
13854 left\-click
13855 T} T{
13856 toggle fullscreen
13857 T}
13858 _
13859 .TE
13860 .UNINDENT
13861 .SS Key Bindings
13862 .sp
13863 These key bindings are active by default if nothing else is already bound to
13864 these keys. In case of collision, the function needs to be bound to a
13865 different key. See the \fI\%Script Commands\fP section.
13866 .TS
13867 center;
13868 |l|l|.
13869 _
13870 T{
13871 del
13872 T} T{
13873 Cycles visibility between never / auto (mouse\-move) / always
13874 T}
13875 _
13876 .TE
13877 .SS Configuration
13878 .sp
13879 The OSC offers limited configuration through a config file
13880 \fBscript\-opts/osc.conf\fP placed in mpv\(aqs user dir and through the
13881 \fB\-\-script\-opts\fP command\-line option. Options provided through the command\-line
13882 will override those from the config file.
13883 .SS Config Syntax
13884 .sp
13885 The config file must exactly follow the following syntax:
13886 .INDENT 0.0
13887 .INDENT 3.5
13888 .sp
13889 .nf
13890 .ft C
13891 # this is a comment
13892 optionA=value1
13893 optionB=value2
13894 .ft P
13895 .fi
13896 .UNINDENT
13897 .UNINDENT
13898 .sp
13899 \fB#\fP can only be used at the beginning of a line and there may be no
13900 spaces around the \fB=\fP or anywhere else.
13901 .SS Command\-line Syntax
13902 .sp
13903 To avoid collisions with other scripts, all options need to be prefixed with
13904 \fBosc\-\fP\&.
13905 .sp
13906 Example:
13907 .INDENT 0.0
13908 .INDENT 3.5
13909 .sp
13910 .nf
13911 .ft C
13912 \-\-script\-opts=osc\-optionA=value1,osc\-optionB=value2
13913 .ft P
13914 .fi
13915 .UNINDENT
13916 .UNINDENT
13917 .SS Configurable Options
13918 .INDENT 0.0
13919 .TP
13920 .B \fBlayout\fP
13921 Default: bottombar
13922 .sp
13923 The layout for the OSC. Currently available are: box, slimbox,
13924 bottombar and topbar. Default pre\-0.21.0 was \(aqbox\(aq.
13925 .TP
13926 .B \fBseekbarstyle\fP
13927 Default: bar
13928 .sp
13929 Sets the style of the playback position marker and overall shape
13930 of the seekbar: \fBbar\fP, \fBdiamond\fP or \fBknob\fP\&.
13931 .TP
13932 .B \fBseekbarhandlesize\fP
13933 Default: 0.6
13934 .sp
13935 Size ratio of the seek handle if \fBseekbarstyle\fP is set to \fBdimaond\fP
13936 or \fBknob\fP\&. This is relative to the full height of the seekbar.
13937 .TP
13938 .B \fBseekbarkeyframes\fP
13939 Default: yes
13940 .sp
13941 Controls the mode used to seek when dragging the seekbar. By default,
13942 keyframes are used. If set to false, exact seeking on mouse drags
13943 will be used instead. Keyframes are preferred, but exact seeks may be
13944 useful in cases where keyframes cannot be found. Note that using exact
13945 seeks can potentially make mouse dragging much slower.
13946 .TP
13947 .B \fBseekrangestyle\fP
13948 Default: inverted
13949 .sp
13950 Display seekable ranges on the seekbar. \fBbar\fP shows them on the full
13951 height of the bar, \fBline\fP as a thick line and \fBinverted\fP as a thin
13952 line that is inverted over playback position markers. \fBnone\fP will hide
13953 them. Additionally, \fBslider\fP will show a permanent handle inside the seekbar
13954 with cached ranges marked inside. Note that these will look differently
13955 based on the seekbarstyle option. Also, \fBslider\fP does not work with
13956 \fBseekbarstyle\fP set to \fBbar\fP\&.
13957 .TP
13958 .B \fBseekrangeseparate\fP
13959 Default: yes
13960 .sp
13961 Controls whether to show line\-style seekable ranges on top of the
13962 seekbar or separately if \fBseekbarstyle\fP is set to \fBbar\fP\&.
13963 .TP
13964 .B \fBseekrangealpha\fP
13965 Default: 200
13966 .sp
13967 Alpha of the seekable ranges, 0 (opaque) to 255 (fully transparent).
13968 .TP
13969 .B \fBdeadzonesize\fP
13970 Default: 0.5
13971 .sp
13972 Size of the deadzone. The deadzone is an area that makes the mouse act
13973 like leaving the window. Movement there won\(aqt make the OSC show up and
13974 it will hide immediately if the mouse enters it. The deadzone starts
13975 at the window border opposite to the OSC and the size controls how much
13976 of the window it will span. Values between 0.0 and 1.0, where 0 means the
13977 OSC will always popup with mouse movement in the window, and 1 means the
13978 OSC will only show up when the mouse hovers it. Default pre\-0.21.0 was 0.
13979 .TP
13980 .B \fBminmousemove\fP
13981 Default: 0
13982 .sp
13983 Minimum amount of pixels the mouse has to move between ticks to make
13984 the OSC show up. Default pre\-0.21.0 was 3.
13985 .TP
13986 .B \fBshowwindowed\fP
13987 Default: yes
13988 .sp
13989 Enable the OSC when windowed
13990 .TP
13991 .B \fBshowfullscreen\fP
13992 Default: yes
13993 .sp
13994 Enable the OSC when fullscreen
13995 .TP
13996 .B \fBscalewindowed\fP
13997 Default: 1.0
13998 .sp
13999 Scale factor of the OSC when windowed.
14000 .TP
14001 .B \fBscalefullscreen\fP
14002 Default: 1.0
14003 .sp
14004 Scale factor of the OSC when fullscreen
14005 .TP
14006 .B \fBscaleforcedwindow\fP
14007 Default: 2.0
14008 .sp
14009 Scale factor of the OSC when rendered on a forced (dummy) window
14010 .TP
14011 .B \fBvidscale\fP
14012 Default: yes
14013 .sp
14014 Scale the OSC with the video
14015 \fBno\fP tries to keep the OSC size constant as much as the window size allows
14016 .TP
14017 .B \fBvalign\fP
14018 Default: 0.8
14019 .sp
14020 Vertical alignment, \-1 (top) to 1 (bottom)
14021 .TP
14022 .B \fBhalign\fP
14023 Default: 0.0
14024 .sp
14025 Horizontal alignment, \-1 (left) to 1 (right)
14026 .TP
14027 .B \fBbarmargin\fP
14028 Default: 0
14029 .sp
14030 Margin from bottom (bottombar) or top (topbar), in pixels
14031 .TP
14032 .B \fBboxalpha\fP
14033 Default: 80
14034 .sp
14035 Alpha of the background box, 0 (opaque) to 255 (fully transparent)
14036 .TP
14037 .B \fBhidetimeout\fP
14038 Default: 500
14039 .sp
14040 Duration in ms until the OSC hides if no mouse movement, must not be
14041 negative
14042 .TP
14043 .B \fBfadeduration\fP
14044 Default: 200
14045 .sp
14046 Duration of fade out in ms, 0 = no fade
14047 .TP
14048 .B \fBtitle\fP
14049 Default: ${media\-title}
14050 .sp
14051 String that supports property expansion that will be displayed as
14052 OSC title.
14053 ASS tags are escaped, and newlines and trailing slashes are stripped.
14054 .TP
14055 .B \fBtooltipborder\fP
14056 Default: 1
14057 .sp
14058 Size of the tooltip outline when using bottombar or topbar layouts
14059 .TP
14060 .B \fBtimetotal\fP
14061 Default: no
14062 .sp
14063 Show total time instead of time remaining
14064 .TP
14065 .B \fBtimems\fP
14066 Default: no
14067 .sp
14068 Display timecodes with milliseconds
14069 .TP
14070 .B \fBvisibility\fP
14071 Default: auto (auto hide/show on mouse move)
14072 .sp
14073 Also supports \fBnever\fP and \fBalways\fP
14074 .TP
14075 .B \fBboxmaxchars\fP
14076 Default: 80
14077 .sp
14078 Max chars for the osc title at the box layout. mpv does not measure the
14079 text width on screen and so it needs to limit it by number of chars. The
14080 default is conservative to allow wide fonts to be used without overflow.
14081 However, with many common fonts a bigger number can be used. YMMV.
14082 .TP
14083 .B \fBboxvideo\fP
14084 Default: no
14085 .sp
14086 Whether to overlay the osc over the video (\fBno\fP), or to box the video
14087 within the areas not covered by the osc (\fByes\fP). If this option is set,
14088 the osc may overwrite the \fB\-\-video\-margin\-ratio\-*\fP options, even if the
14089 user has set them. (It will not overwrite them if all of them are set to
14090 default values.)
14091 .sp
14092 Currently, this is supported for the \fBbottombar\fP layout only. The other
14093 layouts do not change if this option is set.
14094 .sp
14095 The border is static and appears even if the OSC is configured to appear
14096 only on mouse interaction. If the OSC is invisible, the border is simply
14097 filled with the background color (black by default).
14098 .sp
14099 This currently still makes the OSC overlap with subtitles (if the
14100 \fB\-\-sub\-use\-margins\fP option is set to \fByes\fP, the default). This may be
14101 fixed later.
14102 .UNINDENT
14103 .SS Script Commands
14104 .sp
14105 The OSC script listens to certain script commands. These commands can bound
14106 in \fBinput.conf\fP, or sent by other scripts.
14107 .INDENT 0.0
14108 .TP
14109 .B \fBosc\-message\fP
14110 Show a message on screen using the OSC. First argument is the message,
14111 second the duration in seconds.
14112 .TP
14113 .B \fBosc\-visibility\fP
14114 Controls visibility mode \fBnever\fP / \fBauto\fP (on mouse move) / \fBalways\fP
14115 and also \fBcycle\fP to cycle between the modes
14116 .UNINDENT
14117 .sp
14118 Example
14119 .sp
14120 You could put this into \fBinput.conf\fP to hide the OSC with the \fBa\fP key and
14121 to set auto mode (the default) with \fBb\fP:
14122 .INDENT 0.0
14123 .INDENT 3.5
14124 .sp
14125 .nf
14126 .ft C
14127 a script\-message osc\-visibility never
14128 b script\-message osc\-visibility auto
14129 .ft P
14130 .fi
14131 .UNINDENT
14132 .UNINDENT
14133 .INDENT 0.0
14134 .TP
14135 .B \fBosc\-playlist\fP, \fBosc\-chapterlist\fP, \fBosc\-tracklist\fP
14136 Shows a limited view of the respective type of list using the OSC. First
14137 argument is duration in seconds.
14138 .UNINDENT
14139 .SH STATS
14140 .sp
14141 This builtin script displays information and statistics for the currently
14142 played file. It is enabled by default if mpv was compiled with Lua support.
14143 It can be disabled entirely using the \fB\-\-load\-stats\-overlay=no\fP option.
14144 .SS Usage
14145 .sp
14146 The following key bindings are active by default unless something else is
14147 already bound to them:
14148 .TS
14149 center;
14150 |l|l|.
14151 _
14152 T{
14153 i
14154 T} T{
14155 Show stats for a fixed duration
14156 T}
14157 _
14158 T{
14159 I
14160 T} T{
14161 Toggle stats (shown until toggled again)
14162 T}
14163 _
14164 .TE
14165 .sp
14166 While the stats are visible on screen the following key bindings are active,
14167 regardless of existing bindings. They allow you to switch between \fIpages\fP of
14168 stats:
14169 .TS
14170 center;
14171 |l|l|.
14172 _
14173 T{
14174 1
14175 T} T{
14176 Show usual stats
14177 T}
14178 _
14179 T{
14180 2
14181 T} T{
14182 Show frame timings
14183 T}
14184 _
14185 .TE
14186 .SS Font
14187 .sp
14188 For optimal visual experience, a font with support for many font weights and
14189 monospaced digits is recommended. By default, the open source font
14190 \fI\%Source Sans Pro\fP is used.
14191 .SS Configuration
14192 .sp
14193 This script can be customized through a config file \fBscript\-opts/stats.conf\fP
14194 placed in mpv\(aqs user directory and through the \fB\-\-script\-opts\fP command\-line
14195 option. The configuration syntax is described in \fI\%ON SCREEN CONTROLLER\fP\&.
14196 .SS Configurable Options
14197 .INDENT 0.0
14198 .TP
14199 .B \fBkey_oneshot\fP
14200 Default: i
14201 .TP
14202 .B \fBkey_toggle\fP
14203 Default: I
14204 .sp
14205 Key bindings to display stats.
14206 .TP
14207 .B \fBkey_page_1\fP
14208 Default: 1
14209 .TP
14210 .B \fBkey_page_2\fP
14211 Default: 2
14212 .sp
14213 Key bindings for page switching while stats are displayed.
14214 .TP
14215 .B \fBduration\fP
14216 Default: 4
14217 .sp
14218 How long the stats are shown in seconds (oneshot).
14219 .TP
14220 .B \fBredraw_delay\fP
14221 Default: 1
14222 .sp
14223 How long it takes to refresh the displayed stats in seconds (toggling).
14224 .TP
14225 .B \fBpersistent_overlay\fP
14226 Default: no
14227 .sp
14228 When \fIno\fP, other scripts printing text to the screen can overwrite the
14229 displayed stats. When \fIyes\fP, displayed stats are persistently shown for the
14230 respective duration. This can result in overlapping text when multiple
14231 scripts decide to print text at the same time.
14232 .TP
14233 .B \fBplot_perfdata\fP
14234 Default: yes
14235 .sp
14236 Show graphs for performance data (page 2).
14237 .TP
14238 .B \fBplot_vsync_ratio\fP
14239 Default: yes
14240 .TP
14241 .B \fBplot_vsync_jitter\fP
14242 Default: yes
14243 .sp
14244 Show graphs for vsync and jitter values (page 1). Only when toggled.
14245 .TP
14246 .B \fBflush_graph_data\fP
14247 Default: yes
14248 .sp
14249 Clear data buffers used for drawing graphs when toggling.
14250 .TP
14251 .B \fBfont\fP
14252 Default: Source Sans Pro
14253 .sp
14254 Font name. Should support as many font weights as possible for optimal
14255 visual experience.
14256 .TP
14257 .B \fBfont_mono\fP
14258 Default: Source Sans Pro
14259 .sp
14260 Font name for parts where monospaced characters are necessary to align
14261 text. Currently, monospaced digits are sufficient.
14262 .TP
14263 .B \fBfont_size\fP
14264 Default: 8
14265 .sp
14266 Font size used to render text.
14267 .TP
14268 .B \fBfont_color\fP
14269 Default: FFFFFF
14270 .sp
14271 Font color.
14272 .TP
14273 .B \fBborder_size\fP
14274 Default: 0.8
14275 .sp
14276 Size of border drawn around the font.
14277 .TP
14278 .B \fBborder_color\fP
14279 Default: 262626
14280 .sp
14281 Color of drawn border.
14282 .TP
14283 .B \fBalpha\fP
14284 Default: 11
14285 .sp
14286 Transparency for drawn text.
14287 .TP
14288 .B \fBplot_bg_border_color\fP
14289 Default: 0000FF
14290 .sp
14291 Border color used for drawing graphs.
14292 .TP
14293 .B \fBplot_bg_color\fP
14294 Default: 262626
14295 .sp
14296 Background color used for drawing graphs.
14297 .TP
14298 .B \fBplot_color\fP
14299 Default: FFFFFF
14300 .sp
14301 Color used for drawing graphs.
14302 .UNINDENT
14303 .sp
14304 Note: colors are given as hexadecimal values and use ASS tag order: BBGGRR
14305 (blue green red).
14306 .SS Different key bindings
14307 .sp
14308 A different key binding can be defined with the aforementioned options
14309 \fBkey_oneshot\fP and \fBkey_toggle\fP but also with commands in \fBinput.conf\fP,
14310 for example:
14311 .INDENT 0.0
14312 .INDENT 3.5
14313 .sp
14314 .nf
14315 .ft C
14316 e script\-binding stats/display\-stats
14317 E script\-binding stats/display\-stats\-toggle
14318 .ft P
14319 .fi
14320 .UNINDENT
14321 .UNINDENT
14322 .sp
14323 Using \fBinput.conf\fP, it is also possible to directly display a certain page:
14324 .INDENT 0.0
14325 .INDENT 3.5
14326 .sp
14327 .nf
14328 .ft C
14329 i script\-binding stats/display\-page\-1
14330 e script\-binding stats/display\-page\-2
14331 .ft P
14332 .fi
14333 .UNINDENT
14334 .UNINDENT
14335 .SH LUA SCRIPTING
14336 .sp
14337 mpv can load Lua scripts. Scripts passed to the \fB\-\-script\fP option, or found in
14338 the \fBscripts\fP subdirectory of the mpv configuration directory (usually
14339 \fB~/.config/mpv/scripts/\fP) will be loaded on program start. mpv also appends the
14340 \fBscripts\fP subdirectory to the end of Lua\(aqs path so you can import scripts from
14341 there too. Since it\(aqs added to the end, don\(aqt name scripts you want to import
14342 the same as Lua libraries because they will be overshadowed by them.
14343 .sp
14344 mpv provides the built\-in module \fBmp\fP, which contains functions to send
14345 commands to the mpv core and to retrieve information about playback state, user
14346 settings, file information, and so on.
14347 .sp
14348 These scripts can be used to control mpv in a similar way to slave mode.
14349 Technically, the Lua code uses the client API internally.
14350 .SS Example
14351 .sp
14352 A script which leaves fullscreen mode when the player is paused:
14353 .INDENT 0.0
14354 .INDENT 3.5
14355 .sp
14356 .nf
14357 .ft C
14358 function on_pause_change(name, value)
14359 if value == true then
14360 mp.set_property("fullscreen", "no")
14361 end
14362 end
14363 mp.observe_property("pause", "bool", on_pause_change)
14364 .ft P
14365 .fi
14366 .UNINDENT
14367 .UNINDENT
14368 .SS Details on the script initialization and lifecycle
14369 .sp
14370 Your script will be loaded by the player at program start from the \fBscripts\fP
14371 configuration subdirectory, or from a path specified with the \fB\-\-script\fP
14372 option. Some scripts are loaded internally (like \fB\-\-osc\fP). Each script runs in
14373 its own thread. Your script is first run "as is", and once that is done, the event loop
14374 is entered. This event loop will dispatch events received by mpv and call your
14375 own event handlers which you have registered with \fBmp.register_event\fP, or
14376 timers added with \fBmp.add_timeout\fP or similar. Note that since the
14377 script starts execution concurrently with player initialization, some properties
14378 may not be populated with meaningful values until the relevant subsystems have
14379 initialized.
14380 .sp
14381 When the player quits, all scripts will be asked to terminate. This happens via
14382 a \fBshutdown\fP event, which by default will make the event loop return. If your
14383 script got into an endless loop, mpv will probably behave fine during playback,
14384 but it won\(aqt terminate when quitting, because it\(aqs waiting on your script.
14385 .sp
14386 Internally, the C code will call the Lua function \fBmp_event_loop\fP after
14387 loading a Lua script. This function is normally defined by the default prelude
14388 loaded before your script (see \fBplayer/lua/defaults.lua\fP in the mpv sources).
14389 The event loop will wait for events and dispatch events registered with
14390 \fBmp.register_event\fP\&. It will also handle timers added with \fBmp.add_timeout\fP
14391 and similar (by waiting with a timeout).
14392 .sp
14393 Since mpv 0.6.0, the player will wait until the script is fully loaded before
14394 continuing normal operation. The player considers a script as fully loaded as
14395 soon as it starts waiting for mpv events (or it exits). In practice this means
14396 the player will more or less hang until the script returns from the main chunk
14397 (and \fBmp_event_loop\fP is called), or the script calls \fBmp_event_loop\fP or
14398 \fBmp.dispatch_events\fP directly. This is done to make it possible for a script
14399 to fully setup event handlers etc. before playback actually starts. In older
14400 mpv versions, this happened asynchronously. With mpv 0.29.0, this changes
14401 slightly, and it merely waits for scripts to be loaded in this manner before
14402 starting playback as part of the player initialization phase. Scripts run though
14403 initialization in parallel. This might change again.
14404 .SS mp functions
14405 .sp
14406 The \fBmp\fP module is preloaded, although it can be loaded manually with
14407 \fBrequire \(aqmp\(aq\fP\&. It provides the core client API.
14408 .INDENT 0.0
14409 .TP
14410 .B \fBmp.command(string)\fP
14411 Run the given command. This is similar to the commands used in input.conf.
14412 See \fI\%List of Input Commands\fP\&.
14413 .sp
14414 By default, this will show something on the OSD (depending on the command),
14415 as if it was used in \fBinput.conf\fP\&. See \fI\%Input Command Prefixes\fP how
14416 to influence OSD usage per command.
14417 .sp
14418 Returns \fBtrue\fP on success, or \fBnil, error\fP on error.
14419 .TP
14420 .B \fBmp.commandv(arg1, arg2, ...)\fP
14421 Similar to \fBmp.command\fP, but pass each command argument as separate
14422 parameter. This has the advantage that you don\(aqt have to care about
14423 quoting and escaping in some cases.
14424 .sp
14425 Example:
14426 .INDENT 7.0
14427 .INDENT 3.5
14428 .sp
14429 .nf
14430 .ft C
14431 mp.command("loadfile " .. filename .. " append")
14432 mp.commandv("loadfile", filename, "append")
14433 .ft P
14434 .fi
14435 .UNINDENT
14436 .UNINDENT
14437 .sp
14438 These two commands are equivalent, except that the first version breaks
14439 if the filename contains spaces or certain special characters.
14440 .sp
14441 Note that properties are \fInot\fP expanded. You can use either \fBmp.command\fP,
14442 the \fBexpand\-properties\fP prefix, or the \fBmp.get_property\fP family of
14443 functions.
14444 .sp
14445 Unlike \fBmp.command\fP, this will not use OSD by default either (except
14446 for some OSD\-specific commands).
14447 .TP
14448 .B \fBmp.command_native(table [,def])\fP
14449 Similar to \fBmp.commandv\fP, but pass the argument list as table. This has
14450 the advantage that in at least some cases, arguments can be passed as
14451 native types. It also allows you to use named argument.
14452 .sp
14453 If the table is an array, each array item is like an argument in
14454 \fBmp.commandv()\fP (but can be a native type instead of a string).
14455 .sp
14456 If the table contains string keys, it\(aqs interpreted as command with named
14457 arguments. This requires at least an entry with the key \fBname\fP to be
14458 present, which must be a string, and contains the command name. The special
14459 entry \fB_flags\fP is optional, and if present, must be an array of
14460 \fI\%Input Command Prefixes\fP to apply. All other entries are interpreted as
14461 arguments.
14462 .sp
14463 Returns a result table on success (usually empty), or \fBdef, error\fP on
14464 error. \fBdef\fP is the second parameter provided to the function, and is
14465 nil if it\(aqs missing.
14466 .TP
14467 .B \fBmp.command_native_async(table [,fn])\fP
14468 Like \fBmp.command_native()\fP, but the command is ran asynchronously (as far
14469 as possible), and upon completion, fn is called. fn has two arguments:
14470 \fBfn(success, result, error)\fP\&. \fBsuccess\fP is always a Boolean and is true
14471 if the command was successful, otherwise false. The second parameter is
14472 the result value (can be nil) in case of success, nil otherwise (as returned
14473 by \fBmp.command_native()\fP). The third parameter is the error string in case
14474 of an error, nil otherwise.
14475 .sp
14476 Returns a table with undefined contents, which can be used as argument for
14477 \fBmp.abort_async_command\fP\&.
14478 .sp
14479 If starting the command failed for some reason, \fBnil, error\fP is returned,
14480 and \fBfn\fP is called indicating failure, using the same error value.
14481 .TP
14482 .B \fBmp.abort_async_command(t)\fP
14483 Abort a \fBmp.command_native_async\fP call. The argument is the return value
14484 of that command (which starts asynchronous execution of the command).
14485 Whether this works and how long it takes depends on the command and the
14486 situation. The abort call itself is asynchronous. Does not return anything.
14487 .TP
14488 .B \fBmp.get_property(name [,def])\fP
14489 Return the value of the given property as string. These are the same
14490 properties as used in input.conf. See \fI\%Properties\fP for a list of
14491 properties. The returned string is formatted similar to \fB${=name}\fP
14492 (see \fI\%Property Expansion\fP).
14493 .sp
14494 Returns the string on success, or \fBdef, error\fP on error. \fBdef\fP is the
14495 second parameter provided to the function, and is nil if it\(aqs missing.
14496 .TP
14497 .B \fBmp.get_property_osd(name [,def])\fP
14498 Similar to \fBmp.get_property\fP, but return the property value formatted for
14499 OSD. This is the same string as printed with \fB${name}\fP when used in
14500 input.conf.
14501 .sp
14502 Returns the string on success, or \fBdef, error\fP on error. \fBdef\fP is the
14503 second parameter provided to the function, and is an empty string if it\(aqs
14504 missing. Unlike \fBget_property()\fP, assigning the return value to a variable
14505 will always result in a string.
14506 .TP
14507 .B \fBmp.get_property_bool(name [,def])\fP
14508 Similar to \fBmp.get_property\fP, but return the property value as Boolean.
14509 .sp
14510 Returns a Boolean on success, or \fBdef, error\fP on error.
14511 .TP
14512 .B \fBmp.get_property_number(name [,def])\fP
14513 Similar to \fBmp.get_property\fP, but return the property value as number.
14514 .sp
14515 Note that while Lua does not distinguish between integers and floats,
14516 mpv internals do. This function simply request a double float from mpv,
14517 and mpv will usually convert integer property values to float.
14518 .sp
14519 Returns a number on success, or \fBdef, error\fP on error.
14520 .TP
14521 .B \fBmp.get_property_native(name [,def])\fP
14522 Similar to \fBmp.get_property\fP, but return the property value using the best
14523 Lua type for the property. Most time, this will return a string, Boolean,
14524 or number. Some properties (for example \fBchapter\-list\fP) are returned as
14525 tables.
14526 .sp
14527 Returns a value on success, or \fBdef, error\fP on error. Note that \fBnil\fP
14528 might be a possible, valid value too in some corner cases.
14529 .TP
14530 .B \fBmp.set_property(name, value)\fP
14531 Set the given property to the given string value. See \fBmp.get_property\fP
14532 and \fI\%Properties\fP for more information about properties.
14533 .sp
14534 Returns true on success, or \fBnil, error\fP on error.
14535 .TP
14536 .B \fBmp.set_property_bool(name, value)\fP
14537 Similar to \fBmp.set_property\fP, but set the given property to the given
14538 Boolean value.
14539 .TP
14540 .B \fBmp.set_property_number(name, value)\fP
14541 Similar to \fBmp.set_property\fP, but set the given property to the given
14542 numeric value.
14543 .sp
14544 Note that while Lua does not distinguish between integers and floats,
14545 mpv internals do. This function will test whether the number can be
14546 represented as integer, and if so, it will pass an integer value to mpv,
14547 otherwise a double float.
14548 .TP
14549 .B \fBmp.set_property_native(name, value)\fP
14550 Similar to \fBmp.set_property\fP, but set the given property using its native
14551 type.
14552 .sp
14553 Since there are several data types which cannot represented natively in
14554 Lua, this might not always work as expected. For example, while the Lua
14555 wrapper can do some guesswork to decide whether a Lua table is an array
14556 or a map, this would fail with empty tables. Also, there are not many
14557 properties for which it makes sense to use this, instead of
14558 \fBset_property\fP, \fBset_property_bool\fP, \fBset_property_number\fP\&.
14559 For these reasons, this function should probably be avoided for now, except
14560 for properties that use tables natively.
14561 .TP
14562 .B \fBmp.get_time()\fP
14563 Return the current mpv internal time in seconds as a number. This is
14564 basically the system time, with an arbitrary offset.
14565 .TP
14566 .B \fBmp.add_key_binding(key, name|fn [,fn [,flags]])\fP
14567 Register callback to be run on a key binding. The binding will be mapped to
14568 the given \fBkey\fP, which is a string describing the physical key. This uses
14569 the same key names as in input.conf, and also allows combinations
14570 (e.g. \fBctrl+a\fP). If the key is empty or \fBnil\fP, no physical key is
14571 registered, but the user still can create own bindings (see below).
14572 .sp
14573 After calling this function, key presses will cause the function \fBfn\fP to
14574 be called (unless the user remapped the key with another binding).
14575 .sp
14576 The \fBname\fP argument should be a short symbolic string. It allows the user
14577 to remap the key binding via input.conf using the \fBscript\-message\fP
14578 command, and the name of the key binding (see below for
14579 an example). The name should be unique across other bindings in the same
14580 script \- if not, the previous binding with the same name will be
14581 overwritten. You can omit the name, in which case a random name is generated
14582 internally.
14583 .sp
14584 The last argument is used for optional flags. This is a table, which can
14585 have the following entries:
14586 .INDENT 7.0
14587 .INDENT 3.5
14588 .INDENT 0.0
14589 .TP
14590 .B \fBrepeatable\fP
14591 If set to \fBtrue\fP, enables key repeat for this specific binding.
14592 .TP
14593 .B \fBcomplex\fP
14594 If set to \fBtrue\fP, then \fBfn\fP is called on both key up and down
14595 events (as well as key repeat, if enabled), with the first
14596 argument being a table. This table has an \fBevent\fP entry, which
14597 is set to one of the strings \fBdown\fP, \fBrepeat\fP, \fBup\fP or
14598 \fBpress\fP (the latter if key up/down can\(aqt be tracked). It further
14599 has an \fBis_mouse\fP entry, which tells whether the event was caused
14600 by a mouse button.
14601 .UNINDENT
14602 .UNINDENT
14603 .UNINDENT
14604 .sp
14605 Internally, key bindings are dispatched via the \fBscript\-message\-to\fP or
14606 \fBscript\-binding\fP input commands and \fBmp.register_script_message\fP\&.
14607 .sp
14608 Trying to map multiple commands to a key will essentially prefer a random
14609 binding, while the other bindings are not called. It is guaranteed that
14610 user defined bindings in the central input.conf are preferred over bindings
14611 added with this function (but see \fBmp.add_forced_key_binding\fP).
14612 .sp
14613 Example:
14614 .INDENT 7.0
14615 .INDENT 3.5
14616 .sp
14617 .nf
14618 .ft C
14619 function something_handler()
14620 print("the key was pressed")
14621 end
14622 mp.add_key_binding("x", "something", something_handler)
14623 .ft P
14624 .fi
14625 .UNINDENT
14626 .UNINDENT
14627 .sp
14628 This will print the message \fBthe key was pressed\fP when \fBx\fP was pressed.
14629 .sp
14630 The user can remap these key bindings. Then the user has to put the
14631 following into their input.conf to remap the command to the \fBy\fP key:
14632 .INDENT 7.0
14633 .INDENT 3.5
14634 .sp
14635 .nf
14636 .ft C
14637 y script\-binding something
14638 .ft P
14639 .fi
14640 .UNINDENT
14641 .UNINDENT
14642 .sp
14643 This will print the message when the key \fBy\fP is pressed. (\fBx\fP will
14644 still work, unless the user remaps it.)
14645 .sp
14646 You can also explicitly send a message to a named script only. Assume the
14647 above script was using the filename \fBfooscript.lua\fP:
14648 .INDENT 7.0
14649 .INDENT 3.5
14650 .sp
14651 .nf
14652 .ft C
14653 y script\-binding fooscript/something
14654 .ft P
14655 .fi
14656 .UNINDENT
14657 .UNINDENT
14658 .TP
14659 .B \fBmp.add_forced_key_binding(...)\fP
14660 This works almost the same as \fBmp.add_key_binding\fP, but registers the
14661 key binding in a way that will overwrite the user\(aqs custom bindings in their
14662 input.conf. (\fBmp.add_key_binding\fP overwrites default key bindings only,
14663 but not those by the user\(aqs input.conf.)
14664 .TP
14665 .B \fBmp.remove_key_binding(name)\fP
14666 Remove a key binding added with \fBmp.add_key_binding\fP or
14667 \fBmp.add_forced_key_binding\fP\&. Use the same name as you used when adding
14668 the bindings. It\(aqs not possible to remove bindings for which you omitted
14669 the name.
14670 .TP
14671 .B \fBmp.register_event(name, fn)\fP
14672 Call a specific function when an event happens. The event name is a string,
14673 and the function fn is a Lua function value.
14674 .sp
14675 Some events have associated data. This is put into a Lua table and passed
14676 as argument to fn. The Lua table by default contains a \fBname\fP field,
14677 which is a string containing the event name. If the event has an error
14678 associated, the \fBerror\fP field is set to a string describing the error,
14679 on success it\(aqs not set.
14680 .sp
14681 If multiple functions are registered for the same event, they are run in
14682 registration order, which the first registered function running before all
14683 the other ones.
14684 .sp
14685 Returns true if such an event exists, false otherwise.
14686 .sp
14687 See \fI\%Events\fP and \fI\%List of events\fP for details.
14688 .TP
14689 .B \fBmp.unregister_event(fn)\fP
14690 Undo \fBmp.register_event(..., fn)\fP\&. This removes all event handlers that
14691 are equal to the \fBfn\fP parameter. This uses normal Lua \fB==\fP comparison,
14692 so be careful when dealing with closures.
14693 .TP
14694 .B \fBmp.observe_property(name, type, fn)\fP
14695 Watch a property for changes. If the property \fBname\fP is changed, then
14696 the function \fBfn(name)\fP will be called. \fBtype\fP can be \fBnil\fP, or be
14697 set to one of \fBnone\fP, \fBnative\fP, \fBbool\fP, \fBstring\fP, or \fBnumber\fP\&.
14698 \fBnone\fP is the same as \fBnil\fP\&. For all other values, the new value of
14699 the property will be passed as second argument to \fBfn\fP, using
14700 \fBmp.get_property_<type>\fP to retrieve it. This means if \fBtype\fP is for
14701 example \fBstring\fP, \fBfn\fP is roughly called as in
14702 \fBfn(name, mp.get_property_string(name))\fP\&.
14703 .sp
14704 If possible, change events are coalesced. If a property is changed a bunch
14705 of times in a row, only the last change triggers the change function. (The
14706 exact behavior depends on timing and other things.)
14707 .sp
14708 In some cases the function is not called even if the property changes.
14709 This depends on the property, and it\(aqs a valid feature request to ask for
14710 better update handling of a specific property.
14711 .sp
14712 If the \fBtype\fP is \fBnone\fP or \fBnil\fP, sporadic property change events are
14713 possible. This means the change function \fBfn\fP can be called even if the
14714 property doesn\(aqt actually change.
14715 .sp
14716 You always get an initial change notification. This is meant to initialize
14717 the user\(aqs state to the current value of the property.
14718 .TP
14719 .B \fBmp.unobserve_property(fn)\fP
14720 Undo \fBmp.observe_property(..., fn)\fP\&. This removes all property handlers
14721 that are equal to the \fBfn\fP parameter. This uses normal Lua \fB==\fP
14722 comparison, so be careful when dealing with closures.
14723 .TP
14724 .B \fBmp.add_timeout(seconds, fn)\fP
14725 Call the given function fn when the given number of seconds has elapsed.
14726 Note that the number of seconds can be fractional. For now, the timer\(aqs
14727 resolution may be as low as 50 ms, although this will be improved in the
14728 future.
14729 .sp
14730 This is a one\-shot timer: it will be removed when it\(aqs fired.
14731 .sp
14732 Returns a timer object. See \fBmp.add_periodic_timer\fP for details.
14733 .TP
14734 .B \fBmp.add_periodic_timer(seconds, fn)\fP
14735 Call the given function periodically. This is like \fBmp.add_timeout\fP, but
14736 the timer is re\-added after the function fn is run.
14737 .INDENT 7.0
14738 .TP
14739 .B Returns a timer object. The timer object provides the following methods:
14740 .INDENT 7.0
14741 .TP
14742 .B \fBstop()\fP
14743 Disable the timer. Does nothing if the timer is already disabled.
14744 This will remember the current elapsed time when stopping, so that
14745 \fBresume()\fP essentially unpauses the timer.
14746 .TP
14747 .B \fBkill()\fP
14748 Disable the timer. Resets the elapsed time. \fBresume()\fP will
14749 restart the timer.
14750 .TP
14751 .B \fBresume()\fP
14752 Restart the timer. If the timer was disabled with \fBstop()\fP, this
14753 will resume at the time it was stopped. If the timer was disabled
14754 with \fBkill()\fP, or if it\(aqs a previously fired one\-shot timer (added
14755 with \fBadd_timeout()\fP), this starts the timer from the beginning,
14756 using the initially configured timeout.
14757 .TP
14758 .B \fBis_enabled()\fP
14759 Whether the timer is currently enabled or was previously disabled
14760 (e.g. by \fBstop()\fP or \fBkill()\fP).
14761 .TP
14762 .B \fBtimeout\fP (RW)
14763 This field contains the current timeout period. This value is not
14764 updated as time progresses. It\(aqs only used to calculate when the
14765 timer should fire next when the timer expires.
14766 .sp
14767 If you write this, you can call \fBt:kill() ; t:resume()\fP to reset
14768 the current timeout to the new one. (\fBt:stop()\fP won\(aqt use the
14769 new timeout.)
14770 .TP
14771 .B \fBoneshot\fP (RW)
14772 Whether the timer is periodic (\fBfalse\fP) or fires just once
14773 (\fBtrue\fP). This value is used when the timer expires (but before
14774 the timer callback function fn is run).
14775 .UNINDENT
14776 .UNINDENT
14777 .sp
14778 Note that these are methods, and you have to call them using \fB:\fP instead
14779 of \fB\&.\fP (Refer to \fI\%http://www.lua.org/manual/5.2/manual.html#3.4.9\fP .)
14780 .sp
14781 Example:
14782 .INDENT 7.0
14783 .INDENT 3.5
14784 .sp
14785 .nf
14786 .ft C
14787 seconds = 0
14788 timer = mp.add_periodic_timer(1, function()
14789 print("called every second")
14790 # stop it after 10 seconds
14791 seconds = seconds + 1
14792 if seconds >= 10 then
14793 timer:kill()
14794 end
14795 end)
14796 .ft P
14797 .fi
14798 .UNINDENT
14799 .UNINDENT
14800 .TP
14801 .B \fBmp.get_opt(key)\fP
14802 Return a setting from the \fB\-\-script\-opts\fP option. It\(aqs up to the user and
14803 the script how this mechanism is used. Currently, all scripts can access
14804 this equally, so you should be careful about collisions.
14805 .TP
14806 .B \fBmp.get_script_name()\fP
14807 Return the name of the current script. The name is usually made of the
14808 filename of the script, with directory and file extension removed. If
14809 there are several scripts which would have the same name, it\(aqs made unique
14810 by appending a number.
14811 .INDENT 7.0
14812 .INDENT 3.5
14813 .IP "Example"
14814 .sp
14815 The script \fB/path/to/fooscript.lua\fP becomes \fBfooscript\fP\&.
14816 .UNINDENT
14817 .UNINDENT
14818 .TP
14819 .B \fBmp.osd_message(text [,duration])\fP
14820 Show an OSD message on the screen. \fBduration\fP is in seconds, and is
14821 optional (uses \fB\-\-osd\-duration\fP by default).
14822 .UNINDENT
14823 .SS Advanced mp functions
14824 .sp
14825 These also live in the \fBmp\fP module, but are documented separately as they
14826 are useful only in special situations.
14827 .INDENT 0.0
14828 .TP
14829 .B \fBmp.suspend()\fP
14830 This function has been deprecated in mpv 0.21.0 and does nothing starting
14831 with mpv 0.23.0 (no replacement).
14832 .TP
14833 .B \fBmp.resume()\fP
14834 This function has been deprecated in mpv 0.21.0 and does nothing starting
14835 with mpv 0.23.0 (no replacement).
14836 .TP
14837 .B \fBmp.resume_all()\fP
14838 This function has been deprecated in mpv 0.21.0 and does nothing starting
14839 with mpv 0.23.0 (no replacement).
14840 .TP
14841 .B \fBmp.get_wakeup_pipe()\fP
14842 Calls \fBmpv_get_wakeup_pipe()\fP and returns the read end of the wakeup
14843 pipe. This is deprecated, but still works. (See \fBclient.h\fP for details.)
14844 .TP
14845 .B \fBmp.get_next_timeout()\fP
14846 Return the relative time in seconds when the next timer (\fBmp.add_timeout\fP
14847 and similar) expires. If there is no timer, return \fBnil\fP\&.
14848 .TP
14849 .B \fBmp.dispatch_events([allow_wait])\fP
14850 This can be used to run custom event loops. If you want to have direct
14851 control what the Lua script does (instead of being called by the default
14852 event loop), you can set the global variable \fBmp_event_loop\fP to your
14853 own function running the event loop. From your event loop, you should call
14854 \fBmp.dispatch_events()\fP to dequeue and dispatch mpv events.
14855 .sp
14856 If the \fBallow_wait\fP parameter is set to \fBtrue\fP, the function will block
14857 until the next event is received or the next timer expires. Otherwise (and
14858 this is the default behavior), it returns as soon as the event loop is
14859 emptied. It\(aqs strongly recommended to use \fBmp.get_next_timeout()\fP and
14860 \fBmp.get_wakeup_pipe()\fP if you\(aqre interested in properly working
14861 notification of new events and working timers.
14862 .TP
14863 .B \fBmp.register_idle(fn)\fP
14864 Register an event loop idle handler. Idle handlers are called before the
14865 script goes to sleep after handling all new events. This can be used for
14866 example to delay processing of property change events: if you\(aqre observing
14867 multiple properties at once, you might not want to act on each property
14868 change, but only when all change notifications have been received.
14869 .TP
14870 .B \fBmp.unregister_idle(fn)\fP
14871 Undo \fBmp.register_idle(fn)\fP\&. This removes all idle handlers that
14872 are equal to the \fBfn\fP parameter. This uses normal Lua \fB==\fP comparison,
14873 so be careful when dealing with closures.
14874 .TP
14875 .B \fBmp.enable_messages(level)\fP
14876 Set the minimum log level of which mpv message output to receive. These
14877 messages are normally printed to the terminal. By calling this function,
14878 you can set the minimum log level of messages which should be received with
14879 the \fBlog\-message\fP event. See the description of this event for details.
14880 The level is a string, see \fBmsg.log\fP for allowed log levels.
14881 .TP
14882 .B \fBmp.register_script_message(name, fn)\fP
14883 This is a helper to dispatch \fBscript\-message\fP or \fBscript\-message\-to\fP
14884 invocations to Lua functions. \fBfn\fP is called if \fBscript\-message\fP or
14885 \fBscript\-message\-to\fP (with this script as destination) is run
14886 with \fBname\fP as first parameter. The other parameters are passed to \fBfn\fP\&.
14887 If a message with the given name is already registered, it\(aqs overwritten.
14888 .sp
14889 Used by \fBmp.add_key_binding\fP, so be careful about name collisions.
14890 .TP
14891 .B \fBmp.unregister_script_message(name)\fP
14892 Undo a previous registration with \fBmp.register_script_message\fP\&. Does
14893 nothing if the \fBname\fP wasn\(aqt registered.
14894 .UNINDENT
14895 .SS mp.msg functions
14896 .sp
14897 This module allows outputting messages to the terminal, and can be loaded
14898 with \fBrequire \(aqmp.msg\(aq\fP\&.
14899 .INDENT 0.0
14900 .TP
14901 .B \fBmsg.log(level, ...)\fP
14902 The level parameter is the message priority. It\(aqs a string and one of
14903 \fBfatal\fP, \fBerror\fP, \fBwarn\fP, \fBinfo\fP, \fBv\fP, \fBdebug\fP, \fBtrace\fP\&. The
14904 user\(aqs settings will determine which of these messages will be
14905 visible. Normally, all messages are visible, except \fBv\fP, \fBdebug\fP and
14906 \fBtrace\fP\&.
14907 .sp
14908 The parameters after that are all converted to strings. Spaces are inserted
14909 to separate multiple parameters.
14910 .sp
14911 You don\(aqt need to add newlines.
14912 .TP
14913 .B \fBmsg.fatal(...)\fP, \fBmsg.error(...)\fP, \fBmsg.warn(...)\fP, \fBmsg.info(...)\fP, \fBmsg.verbose(...)\fP, \fBmsg.debug(...)\fP, \fBmsg.trace(...)\fP
14914 All of these are shortcuts and equivalent to the corresponding
14915 \fBmsg.log(level, ...)\fP call.
14916 .UNINDENT
14917 .SS mp.options functions
14918 .sp
14919 mpv comes with a built\-in module to manage options from config\-files and the
14920 command\-line. All you have to do is to supply a table with default options to
14921 the read_options function. The function will overwrite the default values
14922 with values found in the config\-file and the command\-line (in that order).
14923 .INDENT 0.0
14924 .TP
14925 .B \fBoptions.read_options(table [, identifier])\fP
14926 A \fBtable\fP with key\-value pairs. The type of the default values is
14927 important for converting the values read from the config file or
14928 command\-line back. Do not use \fBnil\fP as a default value!
14929 .sp
14930 The \fBidentifier\fP is used to identify the config\-file and the command\-line
14931 options. These needs to unique to avoid collisions with other scripts.
14932 Defaults to \fBmp.get_script_name()\fP\&.
14933 .UNINDENT
14934 .sp
14935 Example implementation:
14936 .INDENT 0.0
14937 .INDENT 3.5
14938 .sp
14939 .nf
14940 .ft C
14941 require \(aqmp.options\(aq
14942 local options = {
14943 optionA = "defaultvalueA",
14944 optionB = \-0.5,
14945 optionC = true,
14946 }
14947 read_options(options, "myscript")
14948 print(options.optionA)
14949 .ft P
14950 .fi
14951 .UNINDENT
14952 .UNINDENT
14953 .sp
14954 The config file will be stored in \fBscript\-opts/identifier.conf\fP in mpv\(aqs user
14955 folder. Comment lines can be started with # and stray spaces are not removed.
14956 Boolean values will be represented with yes/no.
14957 .sp
14958 Example config:
14959 .INDENT 0.0
14960 .INDENT 3.5
14961 .sp
14962 .nf
14963 .ft C
14964 # comment
14965 optionA=Hello World
14966 optionB=9999
14967 optionC=no
14968 .ft P
14969 .fi
14970 .UNINDENT
14971 .UNINDENT
14972 .sp
14973 Command\-line options are read from the \fB\-\-script\-opts\fP parameter. To avoid
14974 collisions, all keys have to be prefixed with \fBidentifier\-\fP\&.
14975 .sp
14976 Example command\-line:
14977 .INDENT 0.0
14978 .INDENT 3.5
14979 .sp
14980 .nf
14981 .ft C
14982 \-\-script\-opts=myscript\-optionA=TEST,myscript\-optionB=0,myscript\-optionC=yes
14983 .ft P
14984 .fi
14985 .UNINDENT
14986 .UNINDENT
14987 .SS mp.utils functions
14988 .sp
14989 This built\-in module provides generic helper functions for Lua, and have
14990 strictly speaking nothing to do with mpv or video/audio playback. They are
14991 provided for convenience. Most compensate for Lua\(aqs scarce standard library.
14992 .sp
14993 Be warned that any of these functions might disappear any time. They are not
14994 strictly part of the guaranteed API.
14995 .INDENT 0.0
14996 .TP
14997 .B \fButils.getcwd()\fP
14998 Returns the directory that mpv was launched from. On error, \fBnil, error\fP
14999 is returned.
15000 .TP
15001 .B \fButils.readdir(path [, filter])\fP
15002 Enumerate all entries at the given path on the filesystem, and return them
15003 as array. Each entry is a directory entry (without the path).
15004 The list is unsorted (in whatever order the operating system returns it).
15005 .sp
15006 If the \fBfilter\fP argument is given, it must be one of the following
15007 strings:
15008 .INDENT 7.0
15009 .INDENT 3.5
15010 .INDENT 0.0
15011 .TP
15012 .B \fBfiles\fP
15013 List regular files only. This excludes directories, special files
15014 (like UNIX device files or FIFOs), and dead symlinks. It includes
15015 UNIX symlinks to regular files.
15016 .TP
15017 .B \fBdirs\fP
15018 List directories only, or symlinks to directories. \fB\&.\fP and \fB\&..\fP
15019 are not included.
15020 .TP
15021 .B \fBnormal\fP
15022 Include the results of both \fBfiles\fP and \fBdirs\fP\&. (This is the
15023 default.)
15024 .TP
15025 .B \fBall\fP
15026 List all entries, even device files, dead symlinks, FIFOs, and the
15027 \fB\&.\fP and \fB\&..\fP entries.
15028 .UNINDENT
15029 .UNINDENT
15030 .UNINDENT
15031 .sp
15032 On error, \fBnil, error\fP is returned.
15033 .TP
15034 .B \fButils.file_info(path)\fP
15035 Stats the given path for information and returns a table with the
15036 following entries:
15037 .INDENT 7.0
15038 .INDENT 3.5
15039 .INDENT 0.0
15040 .TP
15041 .B \fBmode\fP
15042 protection bits (on Windows, always 755 (octal) for directories
15043 and 644 (octal) for files)
15044 .TP
15045 .B \fBsize\fP
15046 size in bytes
15047 .TP
15048 .B \fBatime\fP
15049 time of last access
15050 .TP
15051 .B \fBmtime\fP
15052 time of last modification
15053 .TP
15054 .B \fBctime\fP
15055 time of last metadata change (Linux) / time of creation (Windows)
15056 .TP
15057 .B \fBis_file\fP
15058 Whether \fBpath\fP is a regular file (boolean)
15059 .TP
15060 .B \fBis_dir\fP
15061 Whether \fBpath\fP is a directory (boolean)
15062 .UNINDENT
15063 .UNINDENT
15064 .UNINDENT
15065 .sp
15066 \fBmode\fP and \fBsize\fP are integers.
15067 Timestamps (\fBatime\fP, \fBmtime\fP and \fBctime\fP) are integer seconds since
15068 the Unix epoch (Unix time).
15069 The booleans \fBis_file\fP and \fBis_dir\fP are provided as a convenience;
15070 they can be and are derived from \fBmode\fP\&.
15071 .sp
15072 On error (eg. path does not exist), \fBnil, error\fP is returned.
15073 .TP
15074 .B \fButils.split_path(path)\fP
15075 Split a path into directory component and filename component, and return
15076 them. The first return value is always the directory. The second return
15077 value is the trailing part of the path, the directory entry.
15078 .TP
15079 .B \fButils.join_path(p1, p2)\fP
15080 Return the concatenation of the 2 paths. Tries to be clever. For example,
15081 if \fB\(gap2\fP is an absolute path, p2 is returned without change.
15082 .TP
15083 .B \fButils.subprocess(t)\fP
15084 Runs an external process and waits until it exits. Returns process status
15085 and the captured output. This is a legacy wrapper around calling the
15086 \fBsubprocess\fP command with \fBmp.command_native\fP\&. It does the following
15087 things:
15088 .INDENT 7.0
15089 .IP \(bu 2
15090 copy the table \fBt\fP
15091 .IP \(bu 2
15092 rename \fBcancellable\fP field to \fBplayback_only\fP
15093 .IP \(bu 2
15094 rename \fBmax_size\fP to \fBcapture_size\fP
15095 .IP \(bu 2
15096 set \fBcapture_stdout\fP field to \fBtrue\fP if unset
15097 .IP \(bu 2
15098 set \fBname\fP field to \fBsubprocess\fP
15099 .IP \(bu 2
15100 call \fBmp.command_native(copied_t)\fP
15101 .IP \(bu 2
15102 if the command failed, create a dummy result table
15103 .IP \(bu 2
15104 copy \fBerror_string\fP to \fBerror\fP field if the string is non\-empty
15105 .IP \(bu 2
15106 return the result table
15107 .UNINDENT
15108 .sp
15109 It is recommended to use \fBmp.command_native\fP or \fBmp.command_native_async\fP
15110 directly, instead of calling this legacy wrapper. It is for compatibility
15111 only.
15112 .sp
15113 See the \fBsubprocess\fP documentation for semantics and further parameters.
15114 .TP
15115 .B \fButils.subprocess_detached(t)\fP
15116 Runs an external process and detaches it from mpv\(aqs control.
15117 .sp
15118 The parameter \fBt\fP is a table. The function reads the following entries:
15119 .INDENT 7.0
15120 .INDENT 3.5
15121 .INDENT 0.0
15122 .TP
15123 .B \fBargs\fP
15124 Array of strings of the same semantics as the \fBargs\fP used in the
15125 \fBsubprocess\fP function.
15126 .UNINDENT
15127 .UNINDENT
15128 .UNINDENT
15129 .sp
15130 The function returns \fBnil\fP\&.
15131 .sp
15132 This is a legacy wrapper around calling the \fBrun\fP command with
15133 \fBmp.commandv\fP and other functions.
15134 .TP
15135 .B \fButils.getpid()\fP
15136 Returns the process ID of the running mpv process. This can be used to identify
15137 the calling mpv when launching (detached) subprocesses.
15138 .TP
15139 .B \fButils.parse_json(str [, trail])\fP
15140 Parses the given string argument as JSON, and returns it as a Lua table. On
15141 error, returns \fBnil, error\fP\&. (Currently, \fBerror\fP is just a string
15142 reading \fBerror\fP, because there is no fine\-grained error reporting of any
15143 kind.)
15144 .sp
15145 The returned value uses similar conventions as \fBmp.get_property_native()\fP
15146 to distinguish empty objects and arrays.
15147 .sp
15148 If the \fBtrail\fP parameter is \fBtrue\fP (or any value equal to \fBtrue\fP),
15149 then trailing non\-whitespace text is tolerated by the function, and the
15150 trailing text is returned as 3rd return value. (The 3rd return value is
15151 always there, but with \fBtrail\fP set, no error is raised.)
15152 .TP
15153 .B \fButils.format_json(v)\fP
15154 Format the given Lua table (or value) as a JSON string and return it. On
15155 error, returns \fBnil, error\fP\&. (Errors usually only happen on value types
15156 incompatible with JSON.)
15157 .sp
15158 The argument value uses similar conventions as \fBmp.set_property_native()\fP
15159 to distinguish empty objects and arrays.
15160 .TP
15161 .B \fButils.to_string(v)\fP
15162 Turn the given value into a string. Formats tables and their contents. This
15163 doesn\(aqt do anything special; it is only needed because Lua is terrible.
15164 .UNINDENT
15165 .SS Events
15166 .sp
15167 Events are notifications from player core to scripts. You can register an
15168 event handler with \fBmp.register_event\fP\&.
15169 .sp
15170 Note that all scripts (and other parts of the player) receive events equally,
15171 and there\(aqs no such thing as blocking other scripts from receiving events.
15172 .sp
15173 Example:
15174 .INDENT 0.0
15175 .INDENT 3.5
15176 .sp
15177 .nf
15178 .ft C
15179 function my_fn(event)
15180 print("start of playback!")
15181 end
15182
15183 mp.register_event("file\-loaded", my_fn)
15184 .ft P
15185 .fi
15186 .UNINDENT
15187 .UNINDENT
15188 .SS List of events
15189 .INDENT 0.0
15190 .TP
15191 .B \fBstart\-file\fP
15192 Happens right before a new file is loaded. When you receive this, the
15193 player is loading the file (or possibly already done with it).
15194 .TP
15195 .B \fBend\-file\fP
15196 Happens after a file was unloaded. Typically, the player will load the
15197 next file right away, or quit if this was the last file.
15198 .sp
15199 The event has the \fBreason\fP field, which takes one of these values:
15200 .INDENT 7.0
15201 .TP
15202 .B \fBeof\fP
15203 The file has ended. This can (but doesn\(aqt have to) include
15204 incomplete files or broken network connections under
15205 circumstances.
15206 .TP
15207 .B \fBstop\fP
15208 Playback was ended by a command.
15209 .TP
15210 .B \fBquit\fP
15211 Playback was ended by sending the quit command.
15212 .TP
15213 .B \fBerror\fP
15214 An error happened. In this case, an \fBerror\fP field is present with
15215 the error string.
15216 .TP
15217 .B \fBredirect\fP
15218 Happens with playlists and similar. Details see
15219 \fBMPV_END_FILE_REASON_REDIRECT\fP in the C API.
15220 .TP
15221 .B \fBunknown\fP
15222 Unknown. Normally doesn\(aqt happen, unless the Lua API is out of sync
15223 with the C API. (Likewise, it could happen that your script gets
15224 reason strings that did not exist yet at the time your script was
15225 written.)
15226 .UNINDENT
15227 .TP
15228 .B \fBfile\-loaded\fP
15229 Happens after a file was loaded and begins playback.
15230 .TP
15231 .B \fBseek\fP
15232 Happens on seeking. (This might include cases when the player seeks
15233 internally, even without user interaction. This includes e.g. segment
15234 changes when playing ordered chapters Matroska files.)
15235 .TP
15236 .B \fBplayback\-restart\fP
15237 Start of playback after seek or after file was loaded.
15238 .TP
15239 .B \fBidle\fP
15240 Idle mode is entered. This happens when playback ended, and the player was
15241 started with \fB\-\-idle\fP or \fB\-\-force\-window\fP\&. This mode is implicitly ended
15242 when the \fBstart\-file\fP or \fBshutdown\fP events happen.
15243 .TP
15244 .B \fBtick\fP
15245 Called after a video frame was displayed. This is a hack, and you should
15246 avoid using it. Use timers instead and maybe watch pausing/unpausing events
15247 to avoid wasting CPU when the player is paused.
15248 .TP
15249 .B \fBshutdown\fP
15250 Sent when the player quits, and the script should terminate. Normally
15251 handled automatically. See \fI\%Details on the script initialization and lifecycle\fP\&.
15252 .TP
15253 .B \fBlog\-message\fP
15254 Receives messages enabled with \fBmp.enable_messages\fP\&. The message data
15255 is contained in the table passed as first parameter to the event handler.
15256 The table contains, in addition to the default event fields, the following
15257 fields:
15258 .INDENT 7.0
15259 .TP
15260 .B \fBprefix\fP
15261 The module prefix, identifies the sender of the message. This is what
15262 the terminal player puts in front of the message text when using the
15263 \fB\-\-v\fP option, and is also what is used for \fB\-\-msg\-level\fP\&.
15264 .TP
15265 .B \fBlevel\fP
15266 The log level as string. See \fBmsg.log\fP for possible log level names.
15267 Note that later versions of mpv might add new levels or remove
15268 (undocumented) existing ones.
15269 .TP
15270 .B \fBtext\fP
15271 The log message. The text will end with a newline character. Sometimes
15272 it can contain multiple lines.
15273 .UNINDENT
15274 .sp
15275 Keep in mind that these messages are meant to be hints for humans. You
15276 should not parse them, and prefix/level/text of messages might change
15277 any time.
15278 .TP
15279 .B \fBget\-property\-reply\fP
15280 Undocumented (not useful for Lua scripts).
15281 .TP
15282 .B \fBset\-property\-reply\fP
15283 Undocumented (not useful for Lua scripts).
15284 .TP
15285 .B \fBcommand\-reply\fP
15286 Undocumented (not useful for Lua scripts).
15287 .TP
15288 .B \fBclient\-message\fP
15289 Undocumented (used internally).
15290 .TP
15291 .B \fBvideo\-reconfig\fP
15292 Happens on video output or filter reconfig.
15293 .TP
15294 .B \fBaudio\-reconfig\fP
15295 Happens on audio output or filter reconfig.
15296 .UNINDENT
15297 .sp
15298 The following events also happen, but are deprecated: \fBtracks\-changed\fP,
15299 \fBtrack\-switched\fP, \fBpause\fP, \fBunpause\fP, \fBmetadata\-update\fP,
15300 \fBchapter\-change\fP\&. Use \fBmp.observe_property()\fP instead.
15301 .SS Extras
15302 .sp
15303 This documents experimental features, or features that are "too special" to
15304 guarantee a stable interface.
15305 .INDENT 0.0
15306 .TP
15307 .B \fBmp.add_hook(type, priority, fn)\fP
15308 Add a hook callback for \fBtype\fP (a string identifying a certain kind of
15309 hook). These hooks allow the player to call script functions and wait for
15310 their result (normally, the Lua scripting interface is asynchronous from
15311 the point of view of the player core). \fBpriority\fP is an arbitrary integer
15312 that allows ordering among hooks of the same kind. Using the value 50 is
15313 recommended as neutral default value. \fBfn\fP is the function that will be
15314 called during execution of the hook.
15315 .sp
15316 See \fI\%Hooks\fP for currently existing hooks and what they do \- only the hook
15317 list is interesting; handling hook execution is done by the Lua script
15318 function automatically.
15319 .UNINDENT
15320 .SH JAVASCRIPT
15321 .sp
15322 JavaScript support in mpv is near identical to its Lua support. Use this section
15323 as reference on differences and availability of APIs, but otherwise you should
15324 refer to the Lua documentation for API details and general scripting in mpv.
15325 .SS Example
15326 .sp
15327 JavaScript code which leaves fullscreen mode when the player is paused:
15328 .INDENT 0.0
15329 .INDENT 3.5
15330 .sp
15331 .nf
15332 .ft C
15333 function on_pause_change(name, value) {
15334 if (value == true)
15335 mp.set_property("fullscreen", "no");
15336 }
15337 mp.observe_property("pause", "bool", on_pause_change);
15338 .ft P
15339 .fi
15340 .UNINDENT
15341 .UNINDENT
15342 .SS Similarities with Lua
15343 .sp
15344 mpv tries to load a script file as JavaScript if it has a \fB\&.js\fP extension, but
15345 otherwise, the documented Lua options, script directories, loading, etc apply to
15346 JavaScript files too.
15347 .sp
15348 Script initialization and lifecycle is the same as with Lua, and most of the Lua
15349 functions at the modules \fBmp\fP, \fBmp.utils\fP, \fBmp.msg\fP and \fBmp.options\fP are
15350 available to JavaScript with identical APIs \- including running commands,
15351 getting/setting properties, registering events/key\-bindings/hooks, etc.
15352 .SS Differences from Lua
15353 .sp
15354 No need to load modules. \fBmp\fP, \fBmp.utils\fP, \fBmp.msg\fP and \fBmp.options\fP
15355 are preloaded, and you can use e.g. \fBvar cwd = mp.utils.getcwd();\fP without
15356 prior setup.
15357 .sp
15358 Errors are slightly different. Where the Lua APIs return \fBnil\fP for error,
15359 the JavaScript ones return \fBundefined\fP\&. Where Lua returns \fBsomething, error\fP
15360 JavaScript returns only \fBsomething\fP \- and makes \fBerror\fP available via
15361 \fBmp.last_error()\fP\&. Note that only some of the functions have this additional
15362 \fBerror\fP value \- typically the same ones which have it in Lua.
15363 .sp
15364 Standard APIs are preferred. For instance \fBsetTimeout\fP and \fBJSON.stringify\fP
15365 are available, but \fBmp.add_timeout\fP and \fBmp.utils.format_json\fP are not.
15366 .sp
15367 No standard library. This means that interaction with anything outside of mpv is
15368 limited to the available APIs, typically via \fBmp.utils\fP\&. However, some file
15369 functions were added, and CommonJS \fBrequire\fP is available too \- where the
15370 loaded modules have the same privileges as normal scripts.
15371 .SS Language features \- ECMAScript 5
15372 .sp
15373 The scripting backend which mpv currently uses is MuJS \- a compatible minimal
15374 ES5 interpreter. As such, \fBString.substring\fP is implemented for instance,
15375 while the common but non\-standard \fBString.substr\fP is not. Please consult the
15376 MuJS pages on language features and platform support \- \fI\%http://mujs.com\fP .
15377 .SS Unsupported Lua APIs and their JS alternatives
15378 .sp
15379 \fBmp.add_timeout(seconds, fn)\fP JS: \fBid = setTimeout(fn, ms)\fP
15380 .sp
15381 \fBmp.add_periodic_timer(seconds, fn)\fP JS: \fBid = setInterval(fn, ms)\fP
15382 .sp
15383 \fButils.parse_json(str [, trail])\fP JS: \fBJSON.parse(str)\fP
15384 .sp
15385 \fButils.format_json(v)\fP JS: \fBJSON.stringify(v)\fP
15386 .sp
15387 \fButils.to_string(v)\fP see \fBdump\fP below.
15388 .sp
15389 \fBmp.suspend()\fP JS: none (deprecated).
15390 .sp
15391 \fBmp.resume()\fP JS: none (deprecated).
15392 .sp
15393 \fBmp.resume_all()\fP JS: none (deprecated).
15394 .sp
15395 \fBmp.get_next_timeout()\fP see event loop below.
15396 .sp
15397 \fBmp.dispatch_events([allow_wait])\fP see event loop below.
15398 .SS Scripting APIs \- identical to Lua
15399 .sp
15400 (LE) \- Last\-Error, indicates that \fBmp.last_error()\fP can be used after the
15401 call to test for success (empty string) or failure (non empty reason string).
15402 Where the Lua APIs use \fBnil\fP to indicate error, JS APIs use \fBundefined\fP\&.
15403 .sp
15404 \fBmp.command(string)\fP (LE)
15405 .sp
15406 \fBmp.commandv(arg1, arg2, ...)\fP (LE)
15407 .sp
15408 \fBmp.command_native(table [,def])\fP (LE)
15409 .sp
15410 \fBid = mp.command_native_async(table [,fn])\fP (LE) Notes: \fBid\fP is true\-thy on
15411 success, \fBfn\fP is called always a\-sync, \fBerror\fP is empty string on success.
15412 .sp
15413 \fBmp.abort_async_command(id)\fP
15414 .sp
15415 \fBmp.get_property(name [,def])\fP (LE)
15416 .sp
15417 \fBmp.get_property_osd(name [,def])\fP (LE)
15418 .sp
15419 \fBmp.get_property_bool(name [,def])\fP (LE)
15420 .sp
15421 \fBmp.get_property_number(name [,def])\fP (LE)
15422 .sp
15423 \fBmp.get_property_native(name [,def])\fP (LE)
15424 .sp
15425 \fBmp.set_property(name, value)\fP (LE)
15426 .sp
15427 \fBmp.set_property_bool(name, value)\fP (LE)
15428 .sp
15429 \fBmp.set_property_number(name, value)\fP (LE)
15430 .sp
15431 \fBmp.set_property_native(name, value)\fP (LE)
15432 .sp
15433 \fBmp.get_time()\fP
15434 .sp
15435 \fBmp.add_key_binding(key, name|fn [,fn [,flags]])\fP
15436 .sp
15437 \fBmp.add_forced_key_binding(...)\fP
15438 .sp
15439 \fBmp.remove_key_binding(name)\fP
15440 .sp
15441 \fBmp.register_event(name, fn)\fP
15442 .sp
15443 \fBmp.unregister_event(fn)\fP
15444 .sp
15445 \fBmp.observe_property(name, type, fn)\fP
15446 .sp
15447 \fBmp.unobserve_property(fn)\fP
15448 .sp
15449 \fBmp.get_opt(key)\fP
15450 .sp
15451 \fBmp.get_script_name()\fP
15452 .sp
15453 \fBmp.osd_message(text [,duration])\fP
15454 .sp
15455 \fBmp.get_wakeup_pipe()\fP
15456 .sp
15457 \fBmp.register_idle(fn)\fP
15458 .sp
15459 \fBmp.unregister_idle(fn)\fP
15460 .sp
15461 \fBmp.enable_messages(level)\fP
15462 .sp
15463 \fBmp.register_script_message(name, fn)\fP
15464 .sp
15465 \fBmp.unregister_script_message(name)\fP
15466 .sp
15467 \fBmp.msg.log(level, ...)\fP
15468 .sp
15469 \fBmp.msg.fatal(...)\fP
15470 .sp
15471 \fBmp.msg.error(...)\fP
15472 .sp
15473 \fBmp.msg.warn(...)\fP
15474 .sp
15475 \fBmp.msg.info(...)\fP
15476 .sp
15477 \fBmp.msg.verbose(...)\fP
15478 .sp
15479 \fBmp.msg.debug(...)\fP
15480 .sp
15481 \fBmp.msg.trace(...)\fP
15482 .sp
15483 \fBmp.utils.getcwd()\fP (LE)
15484 .sp
15485 \fBmp.utils.readdir(path [, filter])\fP (LE)
15486 .sp
15487 \fBmp.utils.file_info(path)\fP (LE)
15488 .sp
15489 \fBmp.utils.split_path(path)\fP
15490 .sp
15491 \fBmp.utils.join_path(p1, p2)\fP
15492 .sp
15493 \fBmp.utils.subprocess(t)\fP
15494 .sp
15495 \fBmp.utils.subprocess_detached(t)\fP
15496 .sp
15497 \fBmp.utils.getpid()\fP (LE)
15498 .sp
15499 \fBmp.add_hook(type, priority, fn)\fP
15500 .sp
15501 \fBmp.options.read_options(obj [, identifier])\fP (types: string/boolean/number)
15502 .SS Additional utilities
15503 .INDENT 0.0
15504 .TP
15505 .B \fBmp.last_error()\fP
15506 If used after an API call which updates last error, returns an empty string
15507 if the API call succeeded, or a non\-empty error reason string otherwise.
15508 .TP
15509 .B \fBError.stack\fP (string)
15510 When using \fBtry { ... } catch(e) { ... }\fP, then \fBe.stack\fP is the stack
15511 trace of the error \- if it was created using the \fBError(...)\fP constructor.
15512 .TP
15513 .B \fBprint\fP (global)
15514 A convenient alias to \fBmp.msg.info\fP\&.
15515 .TP
15516 .B \fBdump\fP (global)
15517 Like \fBprint\fP but also expands objects and arrays recursively.
15518 .TP
15519 .B \fBmp.utils.getenv(name)\fP
15520 Returns the value of the host environment variable \fBname\fP, or
15521 \fBundefined\fP if the variable is not defined.
15522 .TP
15523 .B \fBmp.utils.get_user_path(path)\fP
15524 Expands (mpv) meta paths like \fB~/x\fP, \fB~~/y\fP, \fB~~desktop/z\fP etc.
15525 \fBread_file\fP, \fBwrite_file\fP and \fBrequire\fP already use this internaly.
15526 .TP
15527 .B \fBmp.utils.read_file(fname [,max])\fP
15528 Returns the content of file \fBfname\fP as string. If \fBmax\fP is provided and
15529 not negative, limit the read to \fBmax\fP bytes.
15530 .TP
15531 .B \fBmp.utils.write_file(fname, str)\fP
15532 (Over)write file \fBfname\fP with text content \fBstr\fP\&. \fBfname\fP must be
15533 prefixed with \fBfile://\fP as simple protection against accidental arguments
15534 switch, e.g. \fBmp.utils.write_file("file://~/abc.txt", "hello world")\fP\&.
15535 .UNINDENT
15536 .sp
15537 Note: \fBread_file\fP and \fBwrite_file\fP throw on errors, allow text content only.
15538 .INDENT 0.0
15539 .TP
15540 .B \fBmp.get_time_ms()\fP
15541 Same as \fBmp.get_time()\fP but in ms instead of seconds.
15542 .TP
15543 .B \fBmp.get_script_file()\fP
15544 Returns the file name of the current script.
15545 .TP
15546 .B \fBexit()\fP (global)
15547 Make the script exit at the end of the current event loop iteration.
15548 Note: please remove added key bindings before calling \fBexit()\fP\&.
15549 .TP
15550 .B \fBmp.utils.compile_js(fname, content_str)\fP
15551 Compiles the JS code \fBcontent_str\fP as file name \fBfname\fP (without loading
15552 anything from the filesystem), and returns it as a function. Very similar
15553 to a \fBFunction\fP constructor, but shows at stack traces as \fBfname\fP\&.
15554 .UNINDENT
15555 .SS Timers (global)
15556 .sp
15557 The standard HTML/node.js timers are available:
15558 .sp
15559 \fBid = setTimeout(fn [,duration [,arg1 [,arg2...]]])\fP
15560 .sp
15561 \fBid = setTimeout(code_string [,duration])\fP
15562 .sp
15563 \fBclearTimeout(id)\fP
15564 .sp
15565 \fBid = setInterval(fn [,duration [,arg1 [,arg2...]]])\fP
15566 .sp
15567 \fBid = setInterval(code_string [,duration])\fP
15568 .sp
15569 \fBclearInterval(id)\fP
15570 .sp
15571 \fBsetTimeout\fP and \fBsetInterval\fP return id, and later call \fBfn\fP (or execute
15572 \fBcode_string\fP) after \fBduration\fP ms. Interval also repeat every \fBduration\fP\&.
15573 .sp
15574 \fBduration\fP has a minimum and default value of 0, \fBcode_string\fP is
15575 a plain string which is evaluated as JS code, and \fB[,arg1 [,arg2..]]\fP are used
15576 as arguments (if provided) when calling back \fBfn\fP\&.
15577 .sp
15578 The \fBclear...(id)\fP functions cancel timer \fBid\fP, and are irreversible.
15579 .sp
15580 Note: timers always call back asynchronously, e.g. \fBsetTimeout(fn)\fP will never
15581 call \fBfn\fP before returning. \fBfn\fP will be called either at the end of this
15582 event loop iteration or at a later event loop iteration. This is true also for
15583 intervals \- which also never call back twice at the same event loop iteration.
15584 .sp
15585 Additionally, timers are processed after the event queue is empty, so it\(aqs valid
15586 to use \fBsetTimeout(fn)\fP as a one\-time idle observer.
15587 .SS CommonJS modules and \fBrequire(id)\fP
15588 .sp
15589 CommonJS Modules are a standard system where scripts can export common functions
15590 for use by other scripts. A module is a script which adds properties (functions,
15591 etc) to its invisible \fBexports\fP object, which another script can access by
15592 loading it with \fBrequire(module\-id)\fP \- which returns that \fBexports\fP object.
15593 .sp
15594 Modules and \fBrequire\fP are supported, standard compliant, and generally similar
15595 to node.js. However, most node.js modules won\(aqt run due to missing modules such
15596 as \fBfs\fP, \fBprocess\fP, etc, but some node.js modules with minimal dependencies
15597 do work. In general, this is for mpv modules and not a node.js replacement.
15598 .sp
15599 A \fB\&.js\fP file extension is always added to \fBid\fP, e.g. \fBrequire("./foo")\fP
15600 will load the file \fB\&./foo.js\fP and return its \fBexports\fP object.
15601 .sp
15602 An id is relative (to the script which \fBrequire\fP\(aqd it) if it starts with
15603 \fB\&./\fP or \fB\&../\fP\&. Otherwise, it\(aqs considered a "top\-level id" (CommonJS term).
15604 .sp
15605 Top level id is evaluated as absolute filesystem path if possible (e.g. \fB/x/y\fP
15606 or \fB~/x\fP). Otherwise, it\(aqs searched at \fBscripts/modules.js/\fP in mpv config
15607 dirs \- in normal config search order. E.g. \fBrequire("x")\fP is searched as file
15608 \fBx.js\fP at those dirs, and id \fBfoo/x\fP is searched as file \fBfoo/x.js\fP\&.
15609 .sp
15610 No \fBglobal\fP variable, but a module\(aqs \fBthis\fP at its top lexical scope is the
15611 global object \- also in strict mode. If you have a module which needs \fBglobal\fP
15612 as the global object, you could do \fBthis.global = this;\fP before \fBrequire\fP\&.
15613 .sp
15614 Functions and variables declared at a module don\(aqt pollute the global object.
15615 .SS The event loop
15616 .sp
15617 The event loop poll/dispatch mpv events as long as the queue is not empty, then
15618 processes the timers, then waits for the next event, and repeats this forever.
15619 .sp
15620 You could put this code at your script to replace the built\-in event loop, and
15621 also print every event which mpv sends to your script:
15622 .INDENT 0.0
15623 .INDENT 3.5
15624 .sp
15625 .nf
15626 .ft C
15627 function mp_event_loop() {
15628 var wait = 0;
15629 do {
15630 var e = mp.wait_event(wait);
15631 dump(e); // there could be a lot of prints...
15632 if (e.event != "none") {
15633 mp.dispatch_event(e);
15634 wait = 0;
15635 } else {
15636 wait = mp.process_timers() / 1000;
15637 if (wait != 0) {
15638 mp.notify_idle_observers();
15639 wait = mp.peek_timers_wait() / 1000;
15640 }
15641 }
15642 } while (mp.keep_running);
15643 }
15644 .ft P
15645 .fi
15646 .UNINDENT
15647 .UNINDENT
15648 .sp
15649 \fBmp_event_loop\fP is a name which mpv tries to call after the script loads.
15650 The internal implementation is similar to this (without \fBdump\fP though..).
15651 .sp
15652 \fBe = mp.wait_event(wait)\fP returns when the next mpv event arrives, or after
15653 \fBwait\fP seconds if positive and no mpv events arrived. \fBwait\fP value of 0
15654 returns immediately (with \fBe.event == "none"\fP if the queue is empty).
15655 .sp
15656 \fBmp.dispatch_event(e)\fP calls back the handlers registered for \fBe.event\fP,
15657 if there are such (event handlers, property observers, script messages, etc).
15658 .sp
15659 \fBmp.process_timers()\fP calls back the already\-added, non\-canceled due timers,
15660 and returns the duration in ms till the next due timer (possibly 0), or \-1 if
15661 there are no pending timers. Must not be called recursively.
15662 .sp
15663 \fBmp.notify_idle_observers()\fP calls back the idle observers, which we do when
15664 we\(aqre about to sleep (wait != 0), but the observers may add timers or take
15665 non\-negligible duration to complete, so we re\-calculate \fBwait\fP afterwards.
15666 .sp
15667 \fBmp.peek_timers_wait()\fP returns the same values as \fBmp.process_timers()\fP
15668 but without doing anything. Invalid result if called from a timer callback.
15669 .sp
15670 Note: \fBexit()\fP is also registered for the \fBshutdown\fP event, and its
15671 implementation is a simple \fBmp.keep_running = false\fP\&.
15672 .SH JSON IPC
15673 .sp
15674 mpv can be controlled by external programs using the JSON\-based IPC protocol.
15675 It can be enabled by specifying the path to a unix socket or a named pipe using
15676 the option \fB\-\-input\-ipc\-server\fP\&. Clients can connect to this socket and send
15677 commands to the player or receive events from it.
15678 .sp
15679 \fBWARNING:\fP
15680 .INDENT 0.0
15681 .INDENT 3.5
15682 This is not intended to be a secure network protocol. It is explicitly
15683 insecure: there is no authentication, no encryption, and the commands
15684 themselves are insecure too. For example, the \fBrun\fP command is exposed,
15685 which can run arbitrary system commands. The use\-case is controlling the
15686 player locally. This is not different from the MPlayer slave protocol.
15687 .UNINDENT
15688 .UNINDENT
15689 .SS Socat example
15690 .sp
15691 You can use the \fBsocat\fP tool to send commands (and receive replies) from the
15692 shell. Assuming mpv was started with:
15693 .INDENT 0.0
15694 .INDENT 3.5
15695 .sp
15696 .nf
15697 .ft C
15698 mpv file.mkv \-\-input\-ipc\-server=/tmp/mpvsocket
15699 .ft P
15700 .fi
15701 .UNINDENT
15702 .UNINDENT
15703 .sp
15704 Then you can control it using socat:
15705 .INDENT 0.0
15706 .INDENT 3.5
15707 .sp
15708 .nf
15709 .ft C
15710 > echo \(aq{ "command": ["get_property", "playback\-time"] }\(aq | socat \- /tmp/mpvsocket
15711 {"data":190.482000,"error":"success"}
15712 .ft P
15713 .fi
15714 .UNINDENT
15715 .UNINDENT
15716 .sp
15717 In this case, socat copies data between stdin/stdout and the mpv socket
15718 connection.
15719 .sp
15720 See the \fB\-\-idle\fP option how to make mpv start without exiting immediately or
15721 playing a file.
15722 .sp
15723 It\(aqs also possible to send input.conf style text\-only commands:
15724 .INDENT 0.0
15725 .INDENT 3.5
15726 .sp
15727 .nf
15728 .ft C
15729 > echo \(aqshow\-text ${playback\-time}\(aq | socat \- /tmp/mpvsocket
15730 .ft P
15731 .fi
15732 .UNINDENT
15733 .UNINDENT
15734 .sp
15735 But you won\(aqt get a reply over the socket. (This particular command shows the
15736 playback time on the player\(aqs OSD.)
15737 .SS Command Prompt example
15738 .sp
15739 Unfortunately, it\(aqs not as easy to test the IPC protocol on Windows, since
15740 Windows ports of socat (in Cygwin and MSYS2) don\(aqt understand named pipes. In
15741 the absence of a simple tool to send and receive from bidirectional pipes, the
15742 \fBecho\fP command can be used to send commands, but not receive replies from the
15743 command prompt.
15744 .sp
15745 Assuming mpv was started with:
15746 .INDENT 0.0
15747 .INDENT 3.5
15748 .sp
15749 .nf
15750 .ft C
15751 mpv file.mkv \-\-input\-ipc\-server=\e\e.\epipe\empvsocket
15752 .ft P
15753 .fi
15754 .UNINDENT
15755 .UNINDENT
15756 .sp
15757 You can send commands from a command prompt:
15758 .INDENT 0.0
15759 .INDENT 3.5
15760 .sp
15761 .nf
15762 .ft C
15763 echo show\-text ${playback\-time} >\e\e.\epipe\empvsocket
15764 .ft P
15765 .fi
15766 .UNINDENT
15767 .UNINDENT
15768 .sp
15769 To be able to simultaneously read and write from the IPC pipe, like on Linux,
15770 it\(aqs necessary to write an external program that uses overlapped file I/O (or
15771 some wrapper like .NET\(aqs NamedPipeClientStream.)
15772 .SS Protocol
15773 .sp
15774 The protocol uses UTF\-8\-only JSON as defined by RFC\-8259. Unlike standard JSON,
15775 "u" escape sequences are not allowed to construct surrogate pairs. To avoid
15776 getting conflicts, encode all text characters including and above codepoint
15777 U+0020 as UTF\-8. mpv might output broken UTF\-8 in corner cases (see "UTF\-8"
15778 section below).
15779 .sp
15780 Clients can execute commands on the player by sending JSON messages of the
15781 following form:
15782 .INDENT 0.0
15783 .INDENT 3.5
15784 .sp
15785 .nf
15786 .ft C
15787 { "command": ["command_name", "param1", "param2", ...] }
15788 .ft P
15789 .fi
15790 .UNINDENT
15791 .UNINDENT
15792 .sp
15793 where \fBcommand_name\fP is the name of the command to be executed, followed by a
15794 list of parameters. Parameters must be formatted as native JSON values
15795 (integers, strings, booleans, ...). Every message \fBmust\fP be terminated with
15796 \fB\en\fP\&. Additionally, \fB\en\fP must not appear anywhere inside the message. In
15797 practice this means that messages should be minified before being sent to mpv.
15798 .sp
15799 mpv will then send back a reply indicating whether the command was run
15800 correctly, and an additional field holding the command\-specific return data (it
15801 can also be null).
15802 .INDENT 0.0
15803 .INDENT 3.5
15804 .sp
15805 .nf
15806 .ft C
15807 { "error": "success", "data": null }
15808 .ft P
15809 .fi
15810 .UNINDENT
15811 .UNINDENT
15812 .sp
15813 mpv will also send events to clients with JSON messages of the following form:
15814 .INDENT 0.0
15815 .INDENT 3.5
15816 .sp
15817 .nf
15818 .ft C
15819 { "event": "event_name" }
15820 .ft P
15821 .fi
15822 .UNINDENT
15823 .UNINDENT
15824 .sp
15825 where \fBevent_name\fP is the name of the event. Additional event\-specific fields
15826 can also be present. See \fI\%List of events\fP for a list of all supported events.
15827 .sp
15828 Because events can occur at any time, it may be difficult at times to determine
15829 which response goes with which command. Commands may optionally include a
15830 \fBrequest_id\fP which, if provided in the command request, will be copied
15831 verbatim into the response. mpv does not intrepret the \fBrequest_id\fP in any
15832 way; it is solely for the use of the requester. The only requirement is that
15833 the \fBrequest_id\fP field must be an integer (a number without fractional parts
15834 in the range \fB\-2^63..2^63\-1\fP). Using other types is deprecated and will
15835 currently show a warning. In the future, this will raise an error.
15836 .sp
15837 For example, this request:
15838 .INDENT 0.0
15839 .INDENT 3.5
15840 .sp
15841 .nf
15842 .ft C
15843 { "command": ["get_property", "time\-pos"], "request_id": 100 }
15844 .ft P
15845 .fi
15846 .UNINDENT
15847 .UNINDENT
15848 .sp
15849 Would generate this response:
15850 .INDENT 0.0
15851 .INDENT 3.5
15852 .sp
15853 .nf
15854 .ft C
15855 { "error": "success", "data": 1.468135, "request_id": 100 }
15856 .ft P
15857 .fi
15858 .UNINDENT
15859 .UNINDENT
15860 .sp
15861 If you don\(aqt specify a \fBrequest_id\fP, command replies will set it to 0.
15862 .sp
15863 Commands may run asynchronously in the future, instead of blocking the socket
15864 until a reply is sent.
15865 .sp
15866 All commands, replies, and events are separated from each other with a line
15867 break character (\fB\en\fP).
15868 .sp
15869 If the first character (after skipping whitespace) is not \fB{\fP, the command
15870 will be interpreted as non\-JSON text command, as they are used in input.conf
15871 (or \fBmpv_command_string()\fP in the client API). Additionally, lines starting
15872 with \fB#\fP and empty lines are ignored.
15873 .sp
15874 Currently, embedded 0 bytes terminate the current line, but you should not
15875 rely on this.
15876 .SS Commands
15877 .sp
15878 In addition to the commands described in \fI\%List of Input Commands\fP, a few
15879 extra commands can also be used as part of the protocol:
15880 .INDENT 0.0
15881 .TP
15882 .B \fBclient_name\fP
15883 Return the name of the client as string. This is the string \fBipc\-N\fP with
15884 N being an integer number.
15885 .TP
15886 .B \fBget_time_us\fP
15887 Return the current mpv internal time in microseconds as a number. This is
15888 basically the system time, with an arbitrary offset.
15889 .TP
15890 .B \fBget_property\fP
15891 Return the value of the given property. The value will be sent in the data
15892 field of the replay message.
15893 .sp
15894 Example:
15895 .INDENT 7.0
15896 .INDENT 3.5
15897 .sp
15898 .nf
15899 .ft C
15900 { "command": ["get_property", "volume"] }
15901 { "data": 50.0, "error": "success" }
15902 .ft P
15903 .fi
15904 .UNINDENT
15905 .UNINDENT
15906 .TP
15907 .B \fBget_property_string\fP
15908 Like \fBget_property\fP, but the resulting data will always be a string.
15909 .sp
15910 Example:
15911 .INDENT 7.0
15912 .INDENT 3.5
15913 .sp
15914 .nf
15915 .ft C
15916 { "command": ["get_property_string", "volume"] }
15917 { "data": "50.000000", "error": "success" }
15918 .ft P
15919 .fi
15920 .UNINDENT
15921 .UNINDENT
15922 .TP
15923 .B \fBset_property\fP
15924 Set the given property to the given value. See \fI\%Properties\fP for more
15925 information about properties.
15926 .sp
15927 Example:
15928 .INDENT 7.0
15929 .INDENT 3.5
15930 .sp
15931 .nf
15932 .ft C
15933 { "command": ["set_property", "pause", true] }
15934 { "error": "success" }
15935 .ft P
15936 .fi
15937 .UNINDENT
15938 .UNINDENT
15939 .TP
15940 .B \fBset_property_string\fP
15941 Alias for \fBset_property\fP\&. Both commands accept native values and strings.
15942 .TP
15943 .B \fBobserve_property\fP
15944 Watch a property for changes. If the given property is changed, then an
15945 event of type \fBproperty\-change\fP will be generated
15946 .sp
15947 Example:
15948 .INDENT 7.0
15949 .INDENT 3.5
15950 .sp
15951 .nf
15952 .ft C
15953 { "command": ["observe_property", 1, "volume"] }
15954 { "error": "success" }
15955 { "event": "property\-change", "id": 1, "data": 52.0, "name": "volume" }
15956 .ft P
15957 .fi
15958 .UNINDENT
15959 .UNINDENT
15960 .sp
15961 \fBWARNING:\fP
15962 .INDENT 7.0
15963 .INDENT 3.5
15964 If the connection is closed, the IPC client is destroyed internally,
15965 and the observed properties are unregistered. This happens for example
15966 when sending commands to a socket with separate \fBsocat\fP invocations.
15967 This can make it seem like property observation does not work. You must
15968 keep the IPC connection open to make it work.
15969 .UNINDENT
15970 .UNINDENT
15971 .TP
15972 .B \fBobserve_property_string\fP
15973 Like \fBobserve_property\fP, but the resulting data will always be a string.
15974 .sp
15975 Example:
15976 .INDENT 7.0
15977 .INDENT 3.5
15978 .sp
15979 .nf
15980 .ft C
15981 { "command": ["observe_property_string", 1, "volume"] }
15982 { "error": "success" }
15983 { "event": "property\-change", "id": 1, "data": "52.000000", "name": "volume" }
15984 .ft P
15985 .fi
15986 .UNINDENT
15987 .UNINDENT
15988 .TP
15989 .B \fBunobserve_property\fP
15990 Undo \fBobserve_property\fP or \fBobserve_property_string\fP\&. This requires the
15991 numeric id passed to the observed command as argument.
15992 .sp
15993 Example:
15994 .INDENT 7.0
15995 .INDENT 3.5
15996 .sp
15997 .nf
15998 .ft C
15999 { "command": ["unobserve_property", 1] }
16000 { "error": "success" }
16001 .ft P
16002 .fi
16003 .UNINDENT
16004 .UNINDENT
16005 .TP
16006 .B \fBrequest_log_messages\fP
16007 Enable output of mpv log messages. They will be received as events. The
16008 parameter to this command is the log\-level (see \fBmpv_request_log_messages\fP
16009 C API function).
16010 .sp
16011 Log message output is meant for humans only (mostly for debugging).
16012 Attempting to retrieve information by parsing these messages will just
16013 lead to breakages with future mpv releases. Instead, make a feature request,
16014 and ask for a proper event that returns the information you need.
16015 .TP
16016 .B \fBenable_event\fP, \fBdisable_event\fP
16017 Enables or disables the named event. Mirrors the \fBmpv_request_event\fP C
16018 API function. If the string \fBall\fP is used instead of an event name, all
16019 events are enabled or disabled.
16020 .sp
16021 By default, most events are enabled, and there is not much use for this
16022 command.
16023 .TP
16024 .B \fBget_version\fP
16025 Returns the client API version the C API of the remote mpv instance
16026 provides.
16027 .sp
16028 See also: \fBDOCS/client\-api\-changes.rst\fP\&.
16029 .UNINDENT
16030 .SS UTF\-8
16031 .sp
16032 Normally, all strings are in UTF\-8. Sometimes it can happen that strings are
16033 in some broken encoding (often happens with file tags and such, and filenames
16034 on many Unixes are not required to be in UTF\-8 either). This means that mpv
16035 sometimes sends invalid JSON. If that is a problem for the client application\(aqs
16036 parser, it should filter the raw data for invalid UTF\-8 sequences and perform
16037 the desired replacement, before feeding the data to its JSON parser.
16038 .sp
16039 mpv will not attempt to construct invalid UTF\-8 with broken "u" escape
16040 sequences. This includes surrogate pairs.
16041 .SS JSON extensions
16042 .sp
16043 The following non\-standard extensions are supported:
16044 .INDENT 0.0
16045 .INDENT 3.5
16046 .INDENT 0.0
16047 .IP \(bu 2
16048 a list or object item can have a trailing ","
16049 .IP \(bu 2
16050 object syntax accepts "=" in addition of ":"
16051 .IP \(bu 2
16052 object keys can be unquoted, if they start with a character in "A\-Za\-z_"
16053 and contain only characters in "A\-Za\-z0\-9_"
16054 .IP \(bu 2
16055 byte escapes with "xAB" are allowed (with AB being a 2 digit hex number)
16056 .UNINDENT
16057 .UNINDENT
16058 .UNINDENT
16059 .sp
16060 Example:
16061 .INDENT 0.0
16062 .INDENT 3.5
16063 .sp
16064 .nf
16065 .ft C
16066 { objkey = "value\ex0A" }
16067 .ft P
16068 .fi
16069 .UNINDENT
16070 .UNINDENT
16071 .sp
16072 Is equivalent to:
16073 .INDENT 0.0
16074 .INDENT 3.5
16075 .sp
16076 .nf
16077 .ft C
16078 { "objkey": "value\en" }
16079 .ft P
16080 .fi
16081 .UNINDENT
16082 .UNINDENT
16083 .SH CHANGELOG
16084 .sp
16085 There is no real changelog, but you can look at the following things:
16086 .INDENT 0.0
16087 .IP \(bu 2
16088 The release changelog, which should contain most user\-visible changes,
16089 including new features and bug fixes:
16090 .sp
16091 \fI\%https://github.com/mpv\-player/mpv/releases\fP
16092 .IP \(bu 2
16093 The git log, which is the "real" changelog
16094 .IP \(bu 2
16095 The files \fBclient\-api\-changes.rst\fP and \fBinterface\-changes.rst\fP in the
16096 \fBDOCS\fP sub directoryon the git repository, which document API and user
16097 interface changes (the latter usually documents breaking changes only, rather
16098 than additions).
16099 .IP \(bu 2
16100 The file \fBmplayer\-changes.rst\fP in the \fBDOCS\fP sub directory on the git
16101 repository, which used to be in place of this section. It documents some
16102 changes that happened since mplayer2 forked off MPlayer. (Not updated
16103 anymore.)
16104 .UNINDENT
16105 .SH EMBEDDING INTO OTHER PROGRAMS (LIBMPV)
16106 .sp
16107 mpv can be embedded into other programs as video/audio playback backend. The
16108 recommended way to do so is using libmpv. See \fBlibmpv/client.h\fP in the mpv
16109 source code repository. This provides a C API. Bindings for other languages
16110 might be available (see wiki).
16111 .sp
16112 Since libmpv merely allows access to underlying mechanisms that can control
16113 mpv, further documentation is spread over a few places:
16114 .INDENT 0.0
16115 .IP \(bu 2
16116 \fI\%https://github.com/mpv\-player/mpv/blob/master/libmpv/client.h\fP
16117 .IP \(bu 2
16118 \fI\%http://mpv.io/manual/master/#options\fP
16119 .IP \(bu 2
16120 \fI\%http://mpv.io/manual/master/#list\-of\-input\-commands\fP
16121 .IP \(bu 2
16122 \fI\%http://mpv.io/manual/master/#properties\fP
16123 .IP \(bu 2
16124 \fI\%https://github.com/mpv\-player/mpv\-examples/tree/master/libmpv\fP
16125 .UNINDENT
16126 .SH C PLUGINS
16127 .sp
16128 You can write C plugins for mpv. These use the libmpv API, although they do not
16129 use the libmpv library itself.
16130 .sp
16131 Currently, they must be explicitly enabled at build time with
16132 \fB\-\-enable\-cplugins\fP\&. They are available on Linux/BSD platforms only.
16133 .SS C plugins location
16134 .sp
16135 C plugins are put into the mpv scripts directory in its config directory
16136 (see the \fI\%FILES\fP section for details). They must have a \fB\&.so\fP file extension.
16137 They can also be explicitly loaded with the \fB\-\-script\fP option.
16138 .SS API
16139 .sp
16140 A C plugin must export the following function:
16141 .INDENT 0.0
16142 .INDENT 3.5
16143 .sp
16144 .nf
16145 .ft C
16146 int mpv_open_cplugin(mpv_handle *handle)
16147 .ft P
16148 .fi
16149 .UNINDENT
16150 .UNINDENT
16151 .sp
16152 The plugin function will be called on loading time. This function does not
16153 return as long as your plugin is loaded (it runs in its own thread). The
16154 \fBhandle\fP will be deallocated as soon as the plugin function returns.
16155 .sp
16156 The return value is interpreted as error status. A value of \fB0\fP is
16157 interpreted as success, while \fB\-1\fP signals an error. In the latter case,
16158 the player prints an uninformative error message that loading failed.
16159 .sp
16160 Return values other than \fB0\fP and \fB\-1\fP are reserved, and trigger undefined
16161 behavior.
16162 .sp
16163 Within the plugin function, you can call libmpv API functions. The \fBhandle\fP
16164 is created by \fBmpv_create_client()\fP (or actually an internal equivalent),
16165 and belongs to you. You can call \fBmpv_wait_event()\fP to wait for things
16166 happening, and so on.
16167 .sp
16168 Note that the player might block until your plugin calls \fBmpv_wait_event()\fP
16169 for the first time. This gives you a chance to install initial hooks etc.
16170 before playback begins.
16171 .sp
16172 The details are quite similar to Lua scripts.
16173 .SS Linkage to libmpv
16174 .sp
16175 The current implementation requires that your plugins are \fBnot\fP linked against
16176 libmpv. What your plugins uses are not symbols from a libmpv binary, but
16177 symbols from the mpv host binary.
16178 .SS Examples
16179 .sp
16180 See:
16181 .INDENT 0.0
16182 .IP \(bu 2
16183 \fI\%https://github.com/mpv\-player/mpv\-examples/tree/master/cplugins\fP
16184 .UNINDENT
16185 .SH ENVIRONMENT VARIABLES
16186 .sp
16187 There are a number of environment variables that can be used to control the
16188 behavior of mpv.
16189 .INDENT 0.0
16190 .TP
16191 .B \fBHOME\fP, \fBXDG_CONFIG_HOME\fP
16192 Used to determine mpv config directory. If \fBXDG_CONFIG_HOME\fP is not set,
16193 \fB$HOME/.config/mpv\fP is used.
16194 .sp
16195 \fB$HOME/.mpv\fP is always added to the list of config search paths with a
16196 lower priority.
16197 .TP
16198 .B \fBXDG_CONFIG_DIRS\fP
16199 If set, XDG\-style system configuration directories are used. Otherwise,
16200 the UNIX convention (\fBPREFIX/etc/mpv/\fP) is used.
16201 .TP
16202 .B \fBMPV_HOME\fP
16203 Directory where mpv looks for user settings. Overrides \fBHOME\fP, and mpv
16204 will try to load the config file as \fB$MPV_HOME/mpv.conf\fP\&.
16205 .TP
16206 .B \fBMPV_VERBOSE\fP (see also \fB\-v\fP and \fB\-\-msg\-level\fP)
16207 Set the initial verbosity level across all message modules (default: 0).
16208 This is an integer, and the resulting verbosity corresponds to the number
16209 of \fB\-\-v\fP options passed to the command line.
16210 .TP
16211 .B \fBMPV_LEAK_REPORT\fP
16212 If set to \fB1\fP, enable internal talloc leak reporting.
16213 .TP
16214 .B \fBLADSPA_PATH\fP
16215 Specifies the search path for LADSPA plugins. If it is unset, fully
16216 qualified path names must be used.
16217 .TP
16218 .B \fBDISPLAY\fP
16219 Standard X11 display name to use.
16220 .TP
16221 .B FFmpeg/Libav:
16222 This library accesses various environment variables. However, they are not
16223 centrally documented, and documenting them is not our job. Therefore, this
16224 list is incomplete.
16225 .sp
16226 Notable environment variables:
16227 .INDENT 7.0
16228 .TP
16229 .B \fBhttp_proxy\fP
16230 URL to proxy for \fBhttp://\fP and \fBhttps://\fP URLs.
16231 .TP
16232 .B \fBno_proxy\fP
16233 List of domain patterns for which no proxy should be used.
16234 List entries are separated by \fB,\fP\&. Patterns can include \fB*\fP\&.
16235 .UNINDENT
16236 .TP
16237 .B libdvdcss:
16238 .INDENT 7.0
16239 .TP
16240 .B \fBDVDCSS_CACHE\fP
16241 Specify a directory in which to store title key values. This will
16242 speed up descrambling of DVDs which are in the cache. The
16243 \fBDVDCSS_CACHE\fP directory is created if it does not exist, and a
16244 subdirectory is created named after the DVD\(aqs title or manufacturing
16245 date. If \fBDVDCSS_CACHE\fP is not set or is empty, libdvdcss will use
16246 the default value which is \fB${HOME}/.dvdcss/\fP under Unix and
16247 the roaming application data directory (\fB%APPDATA%\fP) under
16248 Windows. The special value "off" disables caching.
16249 .TP
16250 .B \fBDVDCSS_METHOD\fP
16251 Sets the authentication and decryption method that libdvdcss will use
16252 to read scrambled discs. Can be one of \fBtitle\fP, \fBkey\fP or \fBdisc\fP\&.
16253 .INDENT 7.0
16254 .TP
16255 .B key
16256 is the default method. libdvdcss will use a set of calculated
16257 player keys to try to get the disc key. This can fail if the drive
16258 does not recognize any of the player keys.
16259 .TP
16260 .B disc
16261 is a fallback method when key has failed. Instead of using player
16262 keys, libdvdcss will crack the disc key using a brute force
16263 algorithm. This process is CPU intensive and requires 64 MB of
16264 memory to store temporary data.
16265 .TP
16266 .B title
16267 is the fallback when all other methods have failed. It does not
16268 rely on a key exchange with the DVD drive, but rather uses a crypto
16269 attack to guess the title key. On rare cases this may fail because
16270 there is not enough encrypted data on the disc to perform a
16271 statistical attack, but on the other hand it is the only way to
16272 decrypt a DVD stored on a hard disc, or a DVD with the wrong region
16273 on an RPC2 drive.
16274 .UNINDENT
16275 .TP
16276 .B \fBDVDCSS_RAW_DEVICE\fP
16277 Specify the raw device to use. Exact usage will depend on your
16278 operating system, the Linux utility to set up raw devices is raw(8)
16279 for instance. Please note that on most operating systems, using a raw
16280 device requires highly aligned buffers: Linux requires a 2048 bytes
16281 alignment (which is the size of a DVD sector).
16282 .TP
16283 .B \fBDVDCSS_VERBOSE\fP
16284 Sets the libdvdcss verbosity level.
16285 .INDENT 7.0
16286 .TP
16287 .B 0
16288 Outputs no messages at all.
16289 .TP
16290 .B 1
16291 Outputs error messages to stderr.
16292 .TP
16293 .B 2
16294 Outputs error messages and debug messages to stderr.
16295 .UNINDENT
16296 .TP
16297 .B \fBDVDREAD_NOKEYS\fP
16298 Skip retrieving all keys on startup. Currently disabled.
16299 .TP
16300 .B \fBHOME\fP
16301 FIXME: Document this.
16302 .UNINDENT
16303 .UNINDENT
16304 .SH EXIT CODES
16305 .sp
16306 Normally \fBmpv\fP returns 0 as exit code after finishing playback successfully.
16307 If errors happen, the following exit codes can be returned:
16308 .INDENT 0.0
16309 .INDENT 3.5
16310 .INDENT 0.0
16311 .TP
16312 .B 1
16313 Error initializing mpv. This is also returned if unknown options are
16314 passed to mpv.
16315 .TP
16316 .B 2
16317 The file passed to mpv couldn\(aqt be played. This is somewhat fuzzy:
16318 currently, playback of a file is considered to be successful if
16319 initialization was mostly successful, even if playback fails
16320 immediately after initialization.
16321 .TP
16322 .B 3
16323 There were some files that could be played, and some files which
16324 couldn\(aqt (using the definition of success from above).
16325 .TP
16326 .B 4
16327 Quit due to a signal, Ctrl+c in a VO window (by default), or from the
16328 default quit key bindings in encoding mode.
16329 .UNINDENT
16330 .UNINDENT
16331 .UNINDENT
16332 .sp
16333 Note that quitting the player manually will always lead to exit code 0,
16334 overriding the exit code that would be returned normally. Also, the \fBquit\fP
16335 input command can take an exit code: in this case, that exit code is returned.
16336 .SH FILES
16337 .sp
16338 For Windows\-specifics, see \fI\%FILES ON WINDOWS\fP section.
16339 .INDENT 0.0
16340 .TP
16341 .B \fB/usr/local/etc/mpv/mpv.conf\fP
16342 mpv system\-wide settings (depends on \fB\-\-prefix\fP passed to configure \- mpv
16343 in default configuration will use \fB/usr/local/etc/mpv/\fP as config
16344 directory, while most Linux distributions will set it to \fB/etc/mpv/\fP).
16345 .TP
16346 .B \fB~/.config/mpv/mpv.conf\fP
16347 mpv user settings (see \fI\%CONFIGURATION FILES\fP section)
16348 .TP
16349 .B \fB~/.config/mpv/input.conf\fP
16350 key bindings (see \fI\%INPUT.CONF\fP section)
16351 .TP
16352 .B \fB~/.config/mpv/fonts.conf\fP
16353 Fontconfig fonts.conf that is customized for mpv. You should include system
16354 fonts.conf in this file or mpv would not know about fonts that you already
16355 have in the system.
16356 .sp
16357 Only available when libass is built with fontconfig.
16358 .TP
16359 .B \fB~/.config/mpv/subfont.ttf\fP
16360 fallback subtitle font
16361 .TP
16362 .B \fB~/.config/mpv/fonts/\fP
16363 Font files in this directory are used by mpv/libass for subtitles. Useful
16364 if you do not want to install fonts to your system. Note that files in this
16365 directory are loaded into memory before being used by mpv. If you have a
16366 lot of fonts, consider using fonts.conf (see above) to include additional
16367 fonts, which is more memory\-efficient.
16368 .TP
16369 .B \fB~/.config/mpv/scripts/\fP
16370 All files in this directory are loaded as if they were passed to the
16371 \fB\-\-script\fP option. They are loaded in alphabetical order, and sub\-directories
16372 and files with no \fB\&.lua\fP extension are ignored. The \fB\-\-load\-scripts=no\fP
16373 option disables loading these files.
16374 .TP
16375 .B \fB~/.config/mpv/watch_later/\fP
16376 Contains temporary config files needed for resuming playback of files with
16377 the watch later feature. See for example the \fBQ\fP key binding, or the
16378 \fBquit\-watch\-later\fP input command.
16379 .sp
16380 Each file is a small config file which is loaded if the corresponding media
16381 file is loaded. It contains the playback position and some (not necessarily
16382 all) settings that were changed during playback. The filenames are hashed
16383 from the full paths of the media files. It\(aqs in general not possible to
16384 extract the media filename from this hash. However, you can set the
16385 \fB\-\-write\-filename\-in\-watch\-later\-config\fP option, and the player will
16386 add the media filename to the contents of the resume config file.
16387 .TP
16388 .B \fB~/.config/mpv/script\-opts/osc.conf\fP
16389 This is loaded by the OSC script. See the \fI\%ON SCREEN CONTROLLER\fP docs
16390 for details.
16391 .sp
16392 Other files in this directory are specific to the corresponding scripts
16393 as well, and the mpv core doesn\(aqt touch them.
16394 .UNINDENT
16395 .sp
16396 Note that the environment variables \fB$XDG_CONFIG_HOME\fP and \fB$MPV_HOME\fP can
16397 override the standard directory \fB~/.config/mpv/\fP\&.
16398 .sp
16399 Also, the old config location at \fB~/.mpv/\fP is still read, and if the XDG
16400 variant does not exist, will still be preferred.
16401 .SH FILES ON WINDOWS
16402 .sp
16403 On win32 (if compiled with MinGW, but not Cygwin), the default config file
16404 locations are different. They are generally located under \fB%APPDATA%/mpv/\fP\&.
16405 For example, the path to mpv.conf is \fB%APPDATA%/mpv/mpv.conf\fP, which maps to
16406 a system and user\-specific path, for example
16407 .INDENT 0.0
16408 .INDENT 3.5
16409 \fBC:\eusers\eUSERNAME\eAppData\eRoaming\empv\empv.conf\fP
16410 .UNINDENT
16411 .UNINDENT
16412 .sp
16413 You can find the exact path by running \fBecho %APPDATA%\empv\empv.conf\fP in cmd.exe.
16414 .sp
16415 Other config files (such as \fBinput.conf\fP) are in the same directory. See the
16416 \fI\%FILES\fP section above.
16417 .sp
16418 The environment variable \fB$MPV_HOME\fP completely overrides these, like on
16419 UNIX.
16420 .sp
16421 If a directory named \fBportable_config\fP next to the mpv.exe exists, all
16422 config will be loaded from this directory only. Watch later config files are
16423 written to this directory as well. (This exists on Windows only and is redundant
16424 with \fB$MPV_HOME\fP\&. However, since Windows is very scripting unfriendly, a
16425 wrapper script just setting \fB$MPV_HOME\fP, like you could do it on other
16426 systems, won\(aqt work. \fBportable_config\fP is provided for convenience to get
16427 around this restriction.)
16428 .sp
16429 Config files located in the same directory as \fBmpv.exe\fP are loaded with
16430 lower priority. Some config files are loaded only once, which means that
16431 e.g. of 2 \fBinput.conf\fP files located in two config directories, only the
16432 one from the directory with higher priority will be loaded.
16433 .sp
16434 A third config directory with the lowest priority is the directory named \fBmpv\fP
16435 in the same directory as \fBmpv.exe\fP\&. This used to be the directory with the
16436 highest priority, but is now discouraged to use and might be removed in the
16437 future.
16438 .sp
16439 Note that mpv likes to mix \fB/\fP and \fB\e\fP path separators for simplicity.
16440 kernel32.dll accepts this, but cmd.exe does not.
16441 .SH COPYRIGHT
16442 GPLv2+
16443 .\" Generated by docutils manpage writer.
16444 .
|
