Mpv Manual

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 215

Download
Open PDF In Browser	View PDF

mpv
a media player
Copyright:
Manual
section:
Manual group:

GPLv2+
1
multimedia

Table of Contents
SYNOPSIS

DESCRIPTION

INTERACTIVE CONTROL

Keyboard Control

Mouse Control
USAGE

11
12

Legacy option syntax

Escaping spaces and other special characters

Paths

Per-File Options

List Options

Playing DVDs

CONFIGURATION FILES

Location and Syntax

Escaping spaces and special characters

Putting Command Line Options into the Configuration File

File-specific Configuration Files

Profiles

Auto profiles

TAKING SCREENSHOTS

TERMINAL STATUS LINE

LOW LATENCY PLAYBACK

PROTOCOLS

PSEUDO GUI MODE

OPTIONS

Track Selection

Playback Control

Program Behavior

Video

Audio

Subtitles

Window

Disc Devices

Equalizer

Demuxer

Input

OSD

Screenshot

Software Scaler

Audio Resampler

Terminal

Cache

Network

DVB

ALSA audio output options

GPU renderer options

Miscellaneous

109

AUDIO OUTPUT DRIVERS

114

VIDEO OUTPUT DRIVERS

118

AUDIO FILTERS

127

VIDEO FILTERS

132

ENCODING

142

COMMAND INTERFACE

144

input.conf

144

General Input Command Syntax

144

List of Input Commands

145

Input Commands that are Possibly Subject to Change

150

Hooks

154

Legacy hook API

155

Input Command Prefixes

156

Input Sections

156

Properties

157

Property list

157

Inconsistencies between options and properties

176

Property Expansion

177

Raw and Formatted Properties

178

ON SCREEN CONTROLLER
Using the OSC

179
179

The Interface

179

Key Bindings

180

Configuration

180

Config Syntax

180

Command-line Syntax

181

Configurable Options

181

Script Commands

183

STATS

184

Usage

184

Font

184

Configuration

184

Configurable Options

184

Different key bindings

186

LUA SCRIPTING

187

Example

187

Details on the script initialization and lifecycle

187

mp functions

187

Advanced mp functions

192

mp.msg functions

193

mp.options functions

193

mp.utils functions

194

Events

196

List of events

197

Extras

198

JAVASCRIPT

199

Example

199

Similarities with Lua

199

Differences from Lua

199

Language features - ECMAScript 5

199

Unsupported Lua APIs and their JS alternatives

199

Scripting APIs - identical to Lua

200

Additional utilities

201

Timers (global)

202

CommonJS modules and require(id)

202

The event loop

203

JSON IPC

204

Socat example

204

Command Prompt example

204

Protocol

205

Commands

205

UTF-8

207

CHANGELOG

208

EMBEDDING INTO OTHER PROGRAMS (LIBMPV)

209

C PLUGINS

210

C plugins location

210

API

210

Linkage to libmpv

210

Examples

210

ENVIRONMENT VARIABLES

211

EXIT CODES

213

FILES

214

FILES ON WINDOWS

215

SYNOPSIS
mpv [options] [file|URL|PLAYLIST|-]
mpv [options] files

DESCRIPTION
mpv is a media player based on MPlayer and mplayer2. It supports a wide variety of video file formats,
audio and video codecs, and subtitle types. Special input URL types are available to read input from a
variety of sources other than disk files. Depending on platform, a variety of different video and audio output
methods are supported.
Usage examples to get you started quickly can be found at the end of this man page.

INTERACTIVE CONTROL
mpv has a fully configurable, command-driven control layer which allows you to control mpv using
keyboard, mouse, or remote control (there is no LIRC support - configure remotes as input devices
instead).
See the --input- options for ways to customize it.
The following listings are not necessarily complete. See etc/input.conf for a list of default bindings.
User input.conf files and Lua scripts can define additional key bindings.

Keyboard Control
LEFT and RIGHT
Seek backward/forward 5 seconds. Shift+arrow does a 1 second exact seek (see --hr-seek).
UP and DOWN
Seek forward/backward 1 minute. Shift+arrow does a 5 second exact seek (see --hr-seek).
Ctrl+LEFT and Ctrl+RIGHT
Seek to the previous/next subtitle. Subject to some restrictions and might not always work; see
sub-seek command.
Ctrl+Shift+Left and Ctrl+Shift+Right
Adjust subtitle delay so that the next or previous subtitle is displayed now. This is especially useful to
sync subtitles to audio.
[ and ]
Decrease/increase current playback speed by 10%.
{ and }
Halve/double current playback speed.
BACKSPACE
Reset playback speed to normal.
Shift+BACKSPACE
Undo the last seek. This works only if the playlist entry was not changed. Hitting it a second time will
go back to the original position. See revert-seek command for details.
Shift+Ctrl+BACKSPACE
Mark the current position. This will then be used by Shift+BACKSPACE as revert position (once you
seek back, the marker will be reset). You can use this to seek around in the file and then return to the
exact position where you left off.
< and >
Go backward/forward in the playlist.
ENTER
Go forward in the playlist.
p / SPACE
Pause (pressing again unpauses).
.
Step forward. Pressing once will pause, every consecutive press will play one frame and then go into
pause mode again.
,
Step backward. Pressing once will pause, every consecutive press will play one frame in reverse and
then go into pause mode again.
q

Stop playing and quit.
Q
Like q, but store the current playback position. Playing the same file later will resume at the old
playback position if possible.
/ and *
Decrease/increase volume.
9 and 0
Decrease/increase volume.
m
Mute sound.
_
Cycle through the available video tracks.
#
Cycle through the available audio tracks.
f
Toggle fullscreen (see also --fs).
ESC
Exit fullscreen mode.
T
Toggle stay-on-top (see also --ontop).
w and W
Decrease/increase pan-and-scan range. The e key does the same as W currently, but use is
discouraged.
o (also P)
Show progression bar, elapsed time and total duration on the OSD.
O
Toggle OSD states between normal and playback time/duration.
v
Toggle subtitle visibility.
j and J
Cycle through the available subtitles.
z and Z
Adjust subtitle delay by +/- 0.1 seconds. The x key does the same as Z currently, but use is
discouraged.
l
Set/clear A-B loop points. See ab-loop command for details.
L
Toggle infinite looping.
Ctrl + and Ctrl Adjust audio delay (A/V sync) by +/- 0.1 seconds.
u
Switch between applying no style overrides to SSA/ASS subtitles, and overriding them almost
completely with the normal subtitle style. See --sub-ass-override for more info.
V

Toggle subtitle VSFilter aspect compatibility mode. See --sub-ass-vsfilter-aspect-compat
for more info.
r and R
Move subtitles up/down. The t key does the same as R currently, but use is discouraged.
s
Take a screenshot.
S
Take a screenshot, without subtitles. (Whether this works depends on VO driver support.)
Ctrl s
Take a screenshot, as the window shows it (with subtitles, OSD, and scaled video).
PGUP and PGDWN
Seek to the beginning of the previous/next chapter. In most cases, "previous" will actually go to the
beginning of the current chapter; see --chapter-seek-threshold.
Shift+PGUP and Shift+PGDWN
Seek backward or forward by 10 minutes. (This used to be mapped to PGUP/PGDWN without Shift.)
d
Activate/deactivate deinterlacer.
A
Cycle aspect ratio override.
Ctrl h
Toggle hardware video decoding on/off.
Alt+LEFT, Alt+RIGHT, Alt+UP, Alt+DOWN
Move the video rectangle (panning).
Alt + and Alt Combining Alt with the + or - keys changes video zoom.
Alt+BACKSPACE
Reset the pan/zoom settings.
F9
Show the playlist and the current position in it (useful only if a UI window is used, broken on the
terminal).
F10
Show the list of audio and subtitle streams (useful only if a UI window is used, broken on the
terminal).
(The following keys are valid only when using a video output that supports the corresponding adjustment.)
1 and 2
Adjust contrast.
3 and 4
Adjust brightness.
5 and 6
Adjust gamma.
7 and 8
Adjust saturation.
Alt+0 (and command+0 on OSX)
Resize video window to half its original size.
Alt+1 (and command+1 on OSX)

Resize video window to its original size.
Alt+2 (and command+2 on OSX)
Resize video window to double its original size.
command + f (OSX only)
Toggle fullscreen (see also --fs).
(The following keys are valid if you have a keyboard with multimedia keys.)
PAUSE
Pause.
STOP
Stop playing and quit.
PREVIOUS and NEXT
Seek backward/forward 1 minute.
If you miss some older key bindings, look at etc/restore-old-bindings.conf in the mpv git
repository.

Mouse Control
button 3 and button 4
Seek backward/forward 1 minute.
button 5 and button 6
Decrease/increase volume.

USAGE
Command line arguments starting with - are interpreted as options, everything else as filenames or URLs.
All options except flag options (or choice options which include yes) require a parameter in the form
--option=value.
One exception is the lone - (without anything else), which means media data will be read from stdin. Also,
-- (without anything else) will make the player interpret all following arguments as filenames, even if they
start with -. (To play a file named -, you need to use ./-.)
Every flag option has a no-flag counterpart, e.g. the opposite of the --fs option is --no-fs. --fs=yes is
same as --fs, --fs=no is the same as --no-fs.
If an option is marked as (XXX only), it will only work in combination with the XXX option or if XXX is
compiled in.

Legacy option syntax
The --option=value syntax is not strictly enforced, and the alternative legacy syntax -option value
and --option value will also work. This is mostly for compatibility with MPlayer. Using these should be
avoided. Their semantics can change any time in the future.
For example, the alternative syntax will consider an argument following the option a filename.
mpv -fs no will attempt to play a file named no, because --fs is a flag option that requires no
parameter. If an option changes and its parameter becomes optional, then a command line using the
alternative syntax will break.
Currently, the parser makes no difference whether an option starts with -- or a single -. This might also
change in the future, and --option value might always interpret value as filename in order to reduce
ambiguities.

Escaping spaces and other special characters
Keep in mind that the shell will partially parse and mangle the arguments you pass to mpv. For example,
you might need to quote or escape options and filenames:
mpv "filename with spaces.mkv" --title="window title"
It gets more complicated if the suboption parser is involved. The suboption parser puts several options
into a single string, and passes them to a component at once, instead of using multiple options on the
level of the command line.
The suboption parser can quote strings with " and [...]. Additionally, there is a special form of quoting
with %n% described below.
For example, assume the hypothetical foo filter can take multiple options:
mpv test.mkv --vf=foo:option1=value1:option2:option3=value3,bar
This passes option1 and option3 to the foo filter, with option2 as flag (implicitly option2=yes), and
adds a bar filter after that. If an option contains spaces or characters like , or :, you need to quote them:
mpv '--vf=foo:option1="option value with spaces",bar'
Shells may actually strip some quotes from the string passed to the commandline, so the example quotes
the string twice, ensuring that mpv receives the " quotes.
The [...] form of quotes wraps everything between [ and ]. It's useful with shells that don't interpret
these characters in the middle of an argument (like bash). These quotes are balanced (since mpv 0.9.0):
the [ and ] nest, and the quote terminates on the last ] that has no matching [ within the string. (For
example, [a[b]c] results in a[b]c.)
The fixed-length quoting syntax is intended for use with external scripts and programs.
It is started with % and has the following format:

%n%string_of_length_n

Examples
mpv '--vf=foo:option1=%11%quoted text' test.avi
Or in a script:
mpv --vf=foo:option1=%`expr length "$NAME"`%"$NAME" test.avi

Suboptions passed to the client API are also subject to escaping. Using mpv_set_option_string() is
exactly like passing --name=data to the command line (but without shell processing of the string). Some
options support passing values in a more structured way instead of flat strings, and can avoid the
suboption parsing mess. For example, --vf supports MPV_FORMAT_NODE, which lets you pass
suboptions as a nested data structure of maps and arrays.

Paths
Some care must be taken when passing arbitrary paths and filenames to mpv. For example, paths starting
with - will be interpreted as options. Likewise, if a path contains the sequence ://, the string before that
might be interpreted as protocol prefix, even though :// can be part of a legal UNIX path. To avoid
problems with arbitrary paths, you should be sure that absolute paths passed to mpv start with /, and
prefix relative paths with ./.
Using the file:// pseudo-protocol is discouraged, because it involves strange URL unescaping rules.
The name - itself is interpreted as stdin, and will cause mpv to disable console controls. (Which makes it
suitable for playing data piped to stdin.)
The special argument -- can be used to stop mpv from interpreting the following arguments as options.
When using the client API, you should strictly avoid using mpv_command_string for invoking the
loadfile command, and instead prefer e.g. mpv_command to avoid the need for filename escaping.
For paths passed to suboptions, the situation is further complicated by the need to escape special
characters. To work this around, the path can be additionally wrapped in the fixed-length syntax, e.g.
%n%string_of_length_n (see above).
Some mpv options interpret paths starting with ~. Currently, the prefix ~~/ expands to the mpv
configuration directory (usually ~/.config/mpv/). ~/ expands to the user's home directory. (The trailing
/ is always required.) There are the following paths as well:
Name

Meaning

~~home/

same as ~~/

~~global/

the global config path, if available (not on win32)

~~osxbundle/

the OSX bundle resource path (OSX only)

~~desktop/

the path to the desktop (win32, OSX)

Per-File Options
When playing multiple files, any option given on the command line usually affects all files. Example:
mpv --a file1.mkv --b file2.mkv --c

File

Active options

file1.mkv

--a --b --c

file2.mkv

--a --b --c

(This is different from MPlayer and mplayer2.)
Also, if any option is changed at runtime (via input commands), they are not reset when a new file is
played.
Sometimes, it is useful to change options per-file. This can be achieved by adding the special per-file
markers --{ and --}. (Note that you must escape these on some shells.) Example:
mpv --a file1.mkv --b --\{ --c file2.mkv --d file3.mkv --e --\} file4.mkv --f

File

Active options

file1.mkv

--a --b --f

file2.mkv

--a --b --f --c --d --e

file3.mkv

--a --b --f --c --d --e

file4.mkv

--a --b --f

Additionally, any file-local option changed at runtime is reset when the current file stops playing. If option
--c is changed during playback of file2.mkv, it is reset when advancing to file3.mkv. This only
affects file-local options. The option --a is never reset here.

List Options
Some options which store lists of option values can have action suffixes. For example, you can set a
,-separated list of filters with --vf, but the option also allows you to append filters with --vf-append.
Options for filenames do not use , as separator, but : (Unix) or ; (Windows).
Suffix

Meaning

-add

Append 1 or more items (may become alias for -append)

-append

Append single item (avoids need for escaping)

-clr

Clear the option

-del

Delete an existing item by integer index

-pre

Prepend 1 or more items

-set

Set a list of items

-toggle

Append an item, or remove if if it already exists

Although some operations allow specifying multiple ,-separated items, using this is strongly discouraged
and deprecated, except for -set.
Without suffix, the action taken is normally -set.
Some options (like --sub-file, --audio-file, --glsl-shader) are aliases for the proper option
with -append action. For example, --sub-file is an alias for --sub-files-append.
Some options only support a subset of the above.
Options of this type can be changed at runtime using the change-list command, which takes the suffix
as separate operation parameter.

Playing DVDs
DVDs can be played with the dvd://[title] syntax. The optional title specifier is a number which
selects between separate video streams on the DVD. If no title is given (dvd://) then the longest title is
selected automatically by the library. This is usually what you want. mpv does not support DVD menus.
DVDs which have been copied on to a hard drive or other mounted filesystem (by e.g. the dvdbackup
tool) are accommodated by specifying the path to the local copy: --dvd-device=PATH. Alternatively,
running mpv PATH should auto-detect a DVD directory tree and play the longest title.

Note
DVD library choices
mpv uses a different default DVD library than MPlayer. MPlayer uses libdvdread by default, and
mpv uses libdvdnav by default. Both libraries are developed in parallel, but libdvdnav is intended to
support more sophisticated DVD features such as menus and multi-angle playback. mpv uses
libdvdnav for files specified as either dvd://... or dvdnav://.... To use libdvdread, which will
produce behavior more like MPlayer, specify dvdread://... instead. Some users have
experienced problems when using libdvdnav, in which playback gets stuck in a DVD menu stream.
These problems are reported to go away when auto-selecting the title (dvd:// rather than
dvd://1) or when using libdvdread (e.g. dvdread://0). There are also outstanding bugs in
libdvdnav with seeking backwards and forwards in a video stream. Specify dvdread://... to fix
such problems.

Note
DVD subtitles
DVDs use image-based subtitles. Image subtitles are implemented as a bitmap video stream which
can be superimposed over the main movie. mpv's subtitle styling and positioning options and
keyboard shortcuts generally do not work with image-based subtitles. Exceptions include options
like --stretch-dvd-subs and --stretch-image-subs-to-screen.

CONFIGURATION FILES
Location and Syntax
You can put all of the options in configuration files which will be read every time mpv is run. The
system-wide configuration file 'mpv.conf' is in your configuration directory (e.g. /etc/mpv or
/usr/local/etc/mpv), the user-specific one is ~/.config/mpv/mpv.conf. For details and platform
specifics (in particular Windows paths) see the FILES section.
User-specific options override system-wide options and options given on the command line override either.
The syntax of the configuration files is option=value. Everything after a # is considered a comment.
Options that work without values can be enabled by setting them to yes and disabled by setting them to
no. Even suboptions can be specified in this way.

Example configuration file
# Use GPU-accelerated video output by default.
vo=gpu
# Use quotes for text that can contain spaces:
status-msg="Time: ${time-pos}"

Escaping spaces and special characters
This is done like with command line options. The shell is not involved here, but option values still need to
be quoted as a whole if it contains certain characters like spaces. A config entry can be quoted with ", as
well as with the fixed-length syntax (%n%) mentioned before. This is like passing the exact contents of the
quoted string as command line option. C-style escapes are currently _not_ interpreted on this level,
although some options do this manually. (This is a mess and should probably be changed at some point.)

Putting Command Line Options into the Configuration File
Almost all command line options can be put into the configuration file. Here is a small guide:
Option

Configuration file entry

--flag

flag

-opt val

opt=val

--opt=val

opt=val

-opt "has spaces"

opt="has spaces"

File-specific Configuration Files
You can also write file-specific configuration files. If you wish to have a configuration file for a file called
'video.avi', create a file named 'video.avi.conf' with the file-specific options in it and put it in
~/.config/mpv/. You can also put the configuration file in the same directory as the file to be played.
Both require you to set the --use-filedir-conf option (either on the command line or in your global
config file). If a file-specific configuration file is found in the same directory, no file-specific configuration is
loaded from ~/.config/mpv. In addition, the --use-filedir-conf option enables directory-specific
configuration files. For this, mpv first tries to load a mpv.conf from the same directory as the file played and
then tries to load any file-specific configuration.

Profiles
To ease working with different configurations, profiles can be defined in the configuration files. A profile
starts with its name in square brackets, e.g. [my-profile]. All following options will be part of the profile.
A description (shown by --profile=help) can be defined with the profile-desc option. To end the
profile, start another one or use the profile name default to continue with normal options.
You can list profiles with --profile=help, and show the contents of a profile with
--show-profile= (replace with the profile name). You can apply profiles on start with
the --profile= option, or at runtime with the apply-profile command.

Example mpv config file with profiles
# normal top-level option
fullscreen=yes
# a profile that can be enabled with --profile=big-cache
[big-cache]
cache=123400
demuxer-readahead-secs=20
[slow]
profile-desc="some profile name"
# reference a builtin profile
profile=gpu-hq
[fast]
vo=vdpau
# using a profile again extends it
[slow]
framedrop=no
# you can also include other profiles
profile=big-cache

Auto profiles
Some profiles are loaded automatically. The following example demonstrates this:

Auto profile loading
[protocol.dvd]
profile-desc="profile for dvd:// streams"
alang=en
[extension.flv]
profile-desc="profile for .flv files"
vf=flip

The profile name follows the schema type.name, where type can be protocol for the input/output
protocol in use (see --list-protocols), and extension for the extension of the path of the currently
played file (not the file format).
This feature is very limited, and there are no other auto profiles.

TAKING SCREENSHOTS
Screenshots of the currently played file can be taken using the 'screenshot' input mode command, which is
by default bound to the s key. Files named mpv-shotNNNN.jpg will be saved in the working directory,
using the first available number - no files will be overwritten. In pseudo-GUI mode, the screenshot will be
saved somewhere else. See PSEUDO GUI MODE.
A screenshot will usually contain the unscaled video contents at the end of the video filter chain and
subtitles. By default, S takes screenshots without subtitles, while s includes subtitles.
Unlike with MPlayer, the screenshot video filter is not required. This filter was never required in mpv,
and has been removed.

TERMINAL STATUS LINE
During playback, mpv shows the playback status on the terminal. It looks like something like this:
AV: 00:03:12 / 00:24:25 (13%) A-V: -0.000
The status line can be overridden with the --term-status-msg option.
The following is a list of things that can show up in the status line. Input properties, that can be used to get
the same information manually, are also listed.
• AV: or V: (video only) or A: (audio only)
• The current time position in HH:MM:SS format (playback-time property)
• The total file duration (absent if unknown) (length property)
• Playback speed, e.g. `` x2.0``. Only visible if the speed is not normal. This is the user-requested
speed, and not the actual speed (usually they should be the same, unless playback is too slow).
(speed property.)
• Playback percentage, e.g. (13%). How much of the file has been played. Normally calculated out of
playback position and duration, but can fallback to other methods (like byte position) if these are not
available. (percent-pos property.)
• The audio/video sync as A-V:
0.000. This is the difference between audio and video time.
Normally it should be 0 or close to 0. If it's growing, it might indicate a playback problem. (avsync
property.)
• Total A/V sync change, e.g. ct: -0.417. Normally invisible. Can show up if there is audio
"missing", or not enough frames can be dropped. Usually this will indicate a problem.
(total-avsync-change property.)
• Encoding state in {...}, only shown in encoding mode.
• Display sync state. If display sync is active (display-sync-active property), this shows
DS: 2.500/13, where the first number is average number of vsyncs per video frame (e.g. 2.5 when
playing 24Hz videos on 60Hz screens), which might jitter if the ratio doesn't round off, or there are
mistimed frames (vsync-ratio), and the second number of estimated number of vsyncs which took
too long (vo-delayed-frame-count property). The latter is a heuristic, as it's generally not
possible to determine this with certainty.
• Dropped frames, e.g. Dropped: 4. Shows up only if the count is not 0. Can grow if the video
framerate is higher than that of the display, or if video rendering is too slow. May also be incremented
on "hiccups" and when the video frame couldn't be displayed on time. (vo-drop-frame-count
property.) If the decoder drops frames, the number of decoder-dropped frames is appended to the
display as well, e.g.: Dropped: 4/34. This happens only if decoder frame dropping is enabled with
the --framedrop options. (drop-frame-count property.)
• Cache state, e.g. Cache: 2s+134KB. Visible if the stream cache is enabled. The first value shows
the amount of video buffered in the demuxer in seconds, the second value shows the sum of the
demuxer forward cache size and the additional data buffered in the stream cache in kilobytes.
(demuxer-cache-duration, demuxer-cache-state, cache-used properties.)

LOW LATENCY PLAYBACK
mpv is optimized for normal video playback, meaning it actually tries to buffer as much data as it seems to
make sense. This will increase latency. Reducing latency is possible only by specifically disabling features
which increase latency.
The builtin low-latency profile tries to apply some of the options which can reduce latency. You can use
--profile=low-latency to apply all of them. You can list the contents with
--show-profile=low-latency (some of the options are quite obscure, and may change every mpv
release).
Be aware that some of the options can reduce playback quality.
Most latency is actually caused by inconvenient timing behavior. You can disable this with --untimed,
but it will likely break, unless the stream has no audio, and the input feeds data to the player at a constant
rate.
Another common problem is with MJPEG streams. These do not signal the correct framerate. Using
--untimed or --no-correct-pts --fps=60 might help.
For livestreams, data can build up due to pausing the stream, due to slightly lower playback rate, or
"buffering" pauses. If the demuxer cache is enabled, these can be skipped manually. The experimental
drop-buffers command can be used to discard any buffered data, though it's very disruptive.
In some cases, manually tuning TCP buffer sizes and such can help to reduce latency.
Additional options that can be tried:
• --opengl-glfinish=yes, can reduce buffering in the graphics driver
• --opengl-swapinterval=0, same
• --vo=xv, same
• without audio --framedrop=no --speed=1.01 may help for live sources (results can be mixed)

PROTOCOLS
http://..., https://, ...
Many network protocols are supported, but the protocol prefix must always be specified. mpv will
never attempt to guess whether a filename is actually a network address. A protocol prefix is always
required.
Note that not all prefixes are documented here. Undocumented prefixes are either aliases to
documented protocols, or are just redirections to protocols implemented and documented in FFmpeg.
data: is supported in FFmpeg (not in Libav), but needs to be in the format data://. This is done to
avoid ambiguity with filenames. You can also prefix it with lavf:// or ffmpeg://.
ytdl://...
By default, the youtube-dl hook script (enabled by default for mpv CLI) only looks at http URLs.
Prefixing an URL with ytdl:// forces it to be always processed by the script. This can also be used
to invoke special youtube-dl functionality like playing a video by ID or invoking search.
Keep in mind that you can't pass youtube-dl command line options by this, and you have to use
--ytdl-raw-options instead.
Play data from stdin.
smb://PATH
Play a path from Samba share.
bd://[title][/device] --bluray-device=PATH
Play a Blu-ray disc. Since libbluray 1.0.1, you can read from ISO files by passing them to
--bluray-device.
title can be: longest or first (selects the default playlist); mpls/ (selects
.mpls playlist); (select playlist with the same index). mpv will list the available
playlists on loading.
bluray:// is an alias.
dvd://[title|[starttitle]-endtitle][/device] --dvd-device=PATH
Play a DVD. DVD menus are not supported. If no title is given, the longest title is auto-selected.
dvdnav:// is an old alias for dvd:// and does exactly the same thing.
dvdread://...:
Play a DVD using the old libdvdread code. This is what MPlayer and older mpv versions used for
dvd://. Use is discouraged. It's provided only for compatibility and for transition, and to work around
outstanding dvdnav bugs (see "DVD library choices" above).
tv://[channel][/input_id] --tv-...
Analogue TV via V4L. Also useful for webcams. (Linux only.)
pvr:// --pvr-...
PVR. (Linux only.)
dvb://[cardnumber@]channel --dvbin-...
Digital TV via DVB. (Linux only.)
mf://[filemask|@listfile] --mf-...
Play a series of images as video.
cdda://[device] --cdrom-device=PATH --cdda-...

Play CD.
lavf://...
Access any FFmpeg/Libav libavformat protocol. Basically, this passed the string after the // directly
to libavformat.
av://type:options
This is intended for using libavdevice inputs. type is the libavdevice demuxer name, and options is
the (pseudo-)filename passed to the demuxer.
For example, mpv av://lavfi:mandelbrot makes use of the libavfilter wrapper included in
libavdevice, and will use the mandelbrot source filter to generate input data.
avdevice:// is an alias.
file://PATH
A local path as URL. Might be useful in some special use-cases. Note that PATH itself should start
with a third / to make the path an absolute path.
appending://PATH
Play a local file, but assume it's being appended to. This is useful for example for files that are
currently being downloaded to disk. This will block playback, and stop playback only if no new data
was appended after a timeout of about 2 seconds.
Using this is still a bit of a bad idea, because there is no way to detect if a file is actually being
appended, or if it's still written. If you're trying to play the output of some program, consider using a
pipe (something | mpv -). If it really has to be a file on disk, use tail to make it wait forever, e.g.
tail -f -c +0 file.mkv | mpv -.
fd://123
Read data from the given file descriptor (for example 123). This is similar to piping data to stdin via -,
but can use an arbitrary file descriptor.
fdclose://123
Like fd://, but the file descriptor is closed after use. When using this you need to ensure that the
same fd URL will only be used once.
edl://[edl specification as in edl-mpv.rst]
Stitch together parts of multiple files and play them.
null://
Simulate an empty file. If opened for writing, it will discard all data. The null demuxer will specifically
pass autoprobing if this protocol is used (while it's not automatically invoked for empty files).
memory://data
Use the data part as source data.
hex://data
Like memory://, but the string is interpreted as hexdump.

PSEUDO GUI MODE
mpv has no official GUI, other than the OSC (ON SCREEN CONTROLLER), which is not a full GUI and is
not meant to be. However, to compensate for the lack of expected GUI behavior, mpv will in some cases
start with some settings changed to behave slightly more like a GUI mode.
Currently this happens only in the following cases:
• if started using the mpv.desktop file on Linux (e.g. started from menus or file associations provided
by desktop environments)
• if started from explorer.exe on Windows (technically, if it was started on Windows, and all of the
stdout/stderr/stdin handles are unset)
• started out of the bundle on OSX
• if you manually use --player-operation-mode=pseudo-gui on the command line
This mode applies options from the builtin profile builtin-pseudo-gui, but only if these haven't been
set in the user's config file or on the command line. Also, for compatibility with the old pseudo-gui behavior,
the options in the pseudo-gui profile are applied unconditionally. In addition, the profile makes sure to
enable the pseudo-GUI mode, so that --profile=pseudo-gui works like in older mpv releases. The
profiles are currently defined as follows:
[builtin-pseudo-gui]
terminal=no
force-window=yes
idle=once
screenshot-directory=~~desktop/
[pseudo-gui]
player-operation-mode=pseudo-gui

Warning
Currently, you can extend the pseudo-gui profile in the config file the normal way. This is
deprecated. In future mpv releases, the behavior might change, and not apply your additional
settings, and/or use a different profile name.

OPTIONS
Track Selection
--alang=
Specify a priority list of audio languages to use. Different container formats employ different language
codes. DVDs use ISO 639-1 two-letter language codes, Matroska, MPEG-TS and NUT use ISO 639-2
three-letter language codes, while OGM uses a free-form identifier. See also --aid.

Examples
• mpv dvd://1 --alang=hu,en chooses the Hungarian language track on a DVD and
falls back on English if Hungarian is not available.
• mpv --alang=jpn example.mkv plays a Matroska file with Japanese audio.

--slang=
Specify a priority list of subtitle languages to use. Different container formats employ different
language codes. DVDs use ISO 639-1 two letter language codes, Matroska uses ISO 639-2 three
letter language codes while OGM uses a free-form identifier. See also --sid.

Examples
• mpv dvd://1 --slang=hu,en chooses the Hungarian subtitle track on a DVD and
falls back on English if Hungarian is not available.
• mpv --slang=jpn example.mkv plays a Matroska file with Japanese subtitles.

--vlang=<...>
Equivalent to --alang and --slang, for video tracks.
--aid=
Select audio track. auto selects the default, no disables audio. See also --alang. mpv normally
prints available audio tracks on the terminal when starting playback of a file.
--audio is an alias for --aid.
--aid=no or --audio=no or --no-audio disables audio playback. (The latter variant does not
work with the client API.)
--sid=
Display the subtitle stream specified by . auto selects the default, no disables subtitles.
--sub is an alias for --sid.
--sid=no or --sub=no or --no-sub disables subtitle decoding. (The latter variant does not work
with the client API.)
--vid=
Select video channel. auto selects the default, no disables video.
--video is an alias for --vid.
--vid=no or --video=no or --no-video disables video playback. (The latter variant does not
work with the client API.)

If video is disabled, mpv will try to download the audio only if media is streamed with youtube-dl,
because it saves bandwidth. This is done by setting the ytdl_format to "bestaudio/best" in the
ytdl_hook.lua script.
--edition=
(Matroska files only) Specify the edition (set of chapters) to use, where 0 is the first. If set to auto (the
default), mpv will choose the first edition declared as a default, or if there is no default, the first edition
defined.
--track-auto-selection=
Enable the default track auto-selection (default: yes). Enabling this will make the player select streams
according to --aid, --alang, and others. If it is disabled, no tracks are selected. In addition, the
player will not exit if no tracks are selected, and wait instead (this wait mode is similar to pausing, but
the pause option is not set).
This is useful with --lavfi-complex: you can start playback in this mode, and then set select
tracks at runtime by setting the filter graph. Note that if --lavfi-complex is set before playback is
started, the referenced tracks are always selected.

Playback Control
--start=
Seek to given time position.
The general format for absolute times is [[hh:]mm:]ss[.ms]. If the time is given with a prefix of +
or -, the seek is relative from the start or end of the file. (Since mpv 0.14, the start of the file is always
considered 0.)
pp% seeks to percent position pp (0-100).
#c seeks to chapter number c. (Chapters start from 1.)
none resets any previously set option (useful for libmpv).

Examples
--start=+56, --start=+00:56
Seeks to the start time + 56 seconds.
--start=-56, --start=-00:56
Seeks to the end time - 56 seconds.
--start=01:10:00
Seeks to 1 hour 10 min.
--start=50%
Seeks to the middle of the file.
--start=30 --end=40
Seeks to 30 seconds, plays 10 seconds, and exits.
--start=-3:20 --length=10
Seeks to 3 minutes and 20 seconds before the end of the file, plays 10 seconds, and
exits.
--start='#2' --end='#4'
Plays chapters 2 and 3, and exits.

--end=

Stop at given time. Use --length if the time should be relative to --start. See --start for valid
option values and examples.
--length=
Stop after a given time relative to the start time. See --start for valid option values and examples.
If both --end and --length are provided, playback will stop when it reaches either of the two
endpoints.
--rebase-start-time=
Whether to move the file start time to 00:00:00 (default: yes). This is less awkward for files which
start at a random timestamp, such as transport streams. On the other hand, if there are timestamp
resets, the resulting behavior can be rather weird. For this reason, and in case you are actually
interested in the real timestamps, this behavior can be disabled with no.
--speed=<0.01-100>
Slow down or speed up playback by the factor given as parameter.
If --audio-pitch-correction (on by default) is used, playing with a speed higher than normal
automatically inserts the scaletempo audio filter.
--pause
Start the player in paused state.
--shuffle
Play files in random order.
--chapter=
Specify which chapter to start playing at. Optionally specify which chapter to end playing at.
See also: --start.
--playlist-start=
Set which file on the internal playlist to start playback with. The index is an integer, with 0 meaning the
first file. The value auto means that the selection of the entry to play is left to the playback resume
mechanism (default). If an entry with the given index doesn't exist, the behavior is unspecified and
might change in future mpv versions. The same applies if the playlist contains further playlists (don't
expect any reasonable behavior). Passing a playlist file to mpv should work with this option, though.
E.g. mpv playlist.m3u --playlist-start=123 will work as expected, as long as
playlist.m3u does not link to further playlists.
The value no is a deprecated alias for auto.
--playlist=

Play files according to a playlist file (Supports some common formats. If no format is detected, it will
be treated as list of files, separated by newline characters. Note that XML playlist formats are not
supported.)
You can play playlists directly and without this option, however, this option disables any security
mechanisms that might be in place. You may also need this option to load plaintext files as playlist.

Warning
The way mpv uses playlist files via --playlist is not safe against maliciously constructed
files. Such files may trigger harmful actions. This has been the case for all mpv and MPlayer
versions, but unfortunately this fact was not well documented earlier, and some people have
even misguidedly recommended use of --playlist with untrusted sources. Do NOT use
--playlist with random internet sources or files you do not trust!
Playlist can contain entries using other protocols, such as local files, or (most severely),
special protocols like avdevice://, which are inherently unsafe.

--chapter-merge-threshold=
Threshold for merging almost consecutive ordered chapter parts in milliseconds (default: 100). Some
Matroska files with ordered chapters have inaccurate chapter end timestamps, causing a small gap
between the end of one chapter and the start of the next one when they should match. If the end of
one playback part is less than the given threshold away from the start of the next one then keep
playing video normally over the chapter change instead of doing a seek.
--chapter-seek-threshold=
Distance in seconds from the beginning of a chapter within which a backward chapter seek will go to
the previous chapter (default: 5.0). Past this threshold, a backward chapter seek will go to the
beginning of the current chapter instead. A negative value means always go back to the previous
chapter.
--hr-seek=
Select when to use precise seeks that are not limited to keyframes. Such seeks require decoding
video from the previous keyframe up to the target position and so can take some time depending on
decoding performance. For some video formats, precise seeks are disabled. This option selects the
default choice to use for seeks; it is possible to explicitly override that default in the definition of key
bindings and in input commands.
no:
absolute:

yes:
always:

Never use precise seeks.
Use precise seeks if the seek is to an absolute position in the file, such as a
chapter seek, but not for relative seeks like the default behavior of arrow keys
(default).
Use precise seeks whenever possible.
Same as yes (for compatibility).

--hr-seek-demuxer-offset=
This option exists to work around failures to do precise seeks (as in --hr-seek) caused by bugs or
limitations in the demuxers for some file formats. Some demuxers fail to seek to a keyframe before the
given target position, going to a later position instead. The value of this option is subtracted from the
time stamp given to the demuxer. Thus, if you set this option to 1.5 and try to do a precise seek to 60
seconds, the demuxer is told to seek to time 58.5, which hopefully reduces the chance that it
erroneously goes to some time later than 60 seconds. The downside of setting this option is that
precise seeks become slower, as video between the earlier demuxer position and the real target may
be unnecessarily decoded.
--hr-seek-framedrop=

Allow the video decoder to drop frames during seek, if these frames are before the seek target. If this
is enabled, precise seeking can be faster, but if you're using video filters which modify timestamps or
add new frames, it can lead to precise seeking skipping the target frame. This e.g. can break frame
backstepping when deinterlacing is enabled.
Default: yes
--index=
Controls how to seek in files. Note that if the index is missing from a file, it will be built on the fly by
default, so you don't need to change this. But it might help with some broken files.
default:
recreate:

use an index if the file has one, or build it if missing
don't read or use the file's index

Note
This option only works if the underlying media supports seeking (i.e. not with stdin, pipe, etc).

--load-unsafe-playlists
Load URLs from playlists which are considered unsafe (default: no). This includes special protocols
and anything that doesn't refer to normal files. Local files and HTTP links on the other hand are
always considered safe.
Note that --playlist always loads all entries, so you use that instead if you really have the need for
this functionality.
--access-references=
Follow any references in the file being opened (default: yes). Disabling this is helpful if the file is
automatically scanned (e.g. thumbnail generation). If the thumbnail scanner for example encounters a
playlist file, which contains network URLs, and the scanner should not open these, enabling this
option will prevent it. This option also disables ordered chapters, mov reference files, opening of
archives, and a number of other features.
On older FFmpeg versions, this will not work in some cases. Some FFmpeg demuxers might not
respect this option.
This option does not prevent opening of paired subtitle files and such. Use --autoload-files=no
to prevent this.
This option does not always work if you open non-files (for example using dvd://directory would
open a whole bunch of files in the given directory). Prefixing the filename with ./ if it doesn't start with
a / will avoid this.
--loop-playlist=, --loop-playlist
Loops playback N times. A value of 1 plays it one time (default), 2 two times, etc. inf means forever.
no is the same as 1 and disables looping. If several files are specified on command line, the entire
playlist is looped. --loop-playlist is the same as --loop-playlist=inf.
The force mode is like inf, but does not skip playlist entries which have been marked as failing.
This means the player might waste CPU time trying to loop a file that doesn't exist. But it might be
useful for playing webradios under very bad network conditions.
--loop-file=, --loop=
Loop a single file N times. inf means forever, no means normal playback. For compatibility,
--loop-file and --loop-file=yes are also accepted, and are the same as
--loop-file=inf.

The difference to --loop-playlist is that this doesn't loop the playlist, just the file itself. If the
playlist contains only a single file, the difference between the two option is that this option performs a
seek on loop, instead of reloading the file.
--loop is an alias for this option.
--ab-loop-a=, --ab-loop-b=
Set loop points. If playback passes the b timestamp, it will seek to the a timestamp. Seeking past the
b point doesn't loop (this is intentional).
If both options are set to no or unset, looping is disabled. Otherwise, the start/end of playback is used
if one of the options is set to no or unset.
The loop-points can be adjusted at runtime with the corresponding properties. See also ab-loop
command.
--ordered-chapters, --no-ordered-chapters
Enabled by default. Disable support for Matroska ordered chapters. mpv will not load or search for
video segments from other files, and will also ignore any chapter order specified for the main file.
--ordered-chapters-files=
Loads the given file as playlist, and tries to use the files contained in it as reference files when
opening a Matroska file that uses ordered chapters. This overrides the normal mechanism for loading
referenced files by scanning the same directory the main file is located in.
Useful for loading ordered chapter files that are not located on the local filesystem, or if the
referenced files are in different directories.
Note: a playlist can be as simple as a text file containing filenames separated by newlines.
--chapters-file=
Load chapters from this file, instead of using the chapter metadata found in the main file.
This accepts a media file (like mkv) or even a pseudo-format like ffmetadata and uses its chapters to
replace the current file's chapters. This doesn't work with OGM or XML chapters directly.
--sstep=
Skip seconds after every frame.

Note
Without --hr-seek, skipping will snap to keyframes.

--stop-playback-on-init-failure=
Stop playback if either audio or video fails to initialize (default: no). With no, playback will continue in
video-only or audio-only mode if one of them fails. This doesn't affect playback of audio-only or
video-only files.

Program Behavior
--help, --h
Show short summary of options.
You can also pass a string to this option, which will list all top-level options which contain the string in
the name, e.g. --h=scale for all options that contain the word scale. The special string * lists all
top-level options.
-v
Increment verbosity level, one level for each -v found on the command line.

--version, -V
Print version string and exit.
--no-config
Do not load default configuration files. This prevents loading of both the user-level and system-wide
mpv.conf and input.conf files. Other configuration files are blocked as well, such as resume
playback files.

Note
Files explicitly requested by command
--use-filedir-conf, will still be loaded.

line

options,

--include

See also: --config-dir.
--list-options
Prints all available options.
--list-properties
Print a list of the available properties.
--list-protocols
Print a list of the supported protocols.
--log-file=
Opens the given path for writing, and print log messages to it. Existing files will be truncated. The log
level is at least -v -v, but can be raised via --msg-level (the option cannot lower it below the
forced minimum log level).
--config-dir=
Force a different configuration directory. If this is set, the given directory is used to load configuration
files, and all other configuration directories are ignored. This means the global mpv configuration
directory as well as per-user directories are ignored, and overrides through environment variables
(MPV_HOME) are also ignored.
Note that the --no-config option takes precedence over this option.
--save-position-on-quit
Always save the current playback position on quit. When this file is played again later, the player will
seek to the old playback position on start. This does not happen if playback of a file is stopped in any
other way than quitting. For example, going to the next file in the playlist will not save the position,
and start playback at beginning the next time the file is played.
This behavior is disabled by default, but is always available when quitting the player with Shift+Q.
--watch-later-directory=
The directory in which to store the "watch later" temporary files.
The default is a subdirectory named "watch_later" underneath the config directory (usually
~/.config/mpv/).
--dump-stats=
Write certain statistics to the given file. The file is truncated on opening. The file will contain raw
samples, each with a timestamp. To make this file into a readable, the script
TOOLS/stats-conv.py can be used (which currently displays it as a graph).
This option is useful for debugging only.
--idle=

Makes mpv wait idly instead of quitting when there is no file to play. Mostly useful in input mode,
where mpv can be controlled through input commands. (Default: no)
once will only idle at start and let the player close once the first playlist has finished playing back.
--include=
Specify configuration file to be parsed after the default ones.
--load-scripts=
If set to no, don't auto-load scripts from the scripts configuration subdirectory (usually
~/.config/mpv/scripts/). (Default: yes)
--script=
Load a Lua script. You can load multiple scripts by separating them with commas (,).
--script-opts=key1=value1,key2=value2,...
Set options for scripts. A script can query an option by key. If an option is used and what semantics
the option value has depends entirely on the loaded scripts. Values not claimed by any scripts are
ignored.
--merge-files
Pretend that all files passed to mpv are concatenated into a single, big file. This uses timeline/EDL
support internally.
--no-resume-playback
Do not restore playback position from the watch_later configuration subdirectory (usually
~/.config/mpv/watch_later/). See quit-watch-later input command.
--profile=
Use the given profile(s), --profile=help displays a list of the defined profiles.
--reset-on-next-file=
Normally, mpv will try to keep all settings when playing the next file on the playlist, even if they were
changed by the user during playback. (This behavior is the opposite of MPlayer's, which tries to reset
all settings when starting next file.)
Default: Do not reset anything.
This can be changed with this option. It accepts a list of options, and mpv will reset the value of these
options on playback start to the initial value. The initial value is either the default value, or as set by
the config file or command line.
In some cases, this might not work as expected. For example, --volume will only be reset if it is
explicitly set in the config file or the command line.
The special name all resets as many options as possible.

Examples
• --reset-on-next-file=pause Reset pause mode when switching to the next file.
• --reset-on-next-file=fullscreen,speed Reset fullscreen and playback speed
settings if they were changed during playback.
• --reset-on-next-file=all Try to reset all settings that were changed during
playback.

--write-filename-in-watch-later-config
Prepend the watch later config files with the name of the file they refer to. This is simply written as
comment on the top of the file.

Warning
This option may expose privacy-sensitive information and is thus disabled by default.

--ignore-path-in-watch-later-config
Ignore path (i.e. use filename only) when using watch later feature. (Default: disabled)
--show-profile=
Show the description and content of a profile.
--use-filedir-conf
Look for a file-specific configuration file in the same directory as the file that is being played. See
File-specific Configuration Files.

Warning
May be dangerous if playing from untrusted media.

--ytdl, --no-ytdl
Enable the youtube-dl hook-script. It will look at the input URL, and will play the video located on the
website. This works with many streaming sites, not just the one that the script is named after. This
requires a recent version of youtube-dl to be installed on the system. (Enabled by default.)
If the script can't do anything with an URL, it will do nothing.
The try_ytdl_first script option accepts a boolean 'yes' or 'no', and if 'yes' will try parsing the URL with
youtube-dl first, instead of the default where it's only after mpv failed to open it. This mostly depends
on whether most of your URLs need youtube-dl parsing.
The exclude script option accepts a |-separated list of URL patterns which mpv should not use with
youtube-dl. The patterns are matched after the http(s):// part of the URL.
The use_manifests script option makes mpv use the master manifest URL for formats like HLS and
DASH, if available, allowing for video/audio selection in runtime. It's disabled ("no") by default for
performance reasons.
^ matches the beginning of the URL, $ matches its end, and you should use % before any of the
characters ^$()%|,.[]*+-? to match that character.

Examples
• --script-opts=ytdl_hook-exclude='^youtube%.com' will exclude any URL
that starts with http://youtube.com or https://youtube.com.
• --script-opts=ytdl_hook-exclude='%.mkv$|%.mp4$' will exclude any URL
that ends with .mkv or .mp4.

See more lua patterns here: https://www.lua.org/manual/5.1/manual.html#5.4.1
--ytdl-format=

Video format/quality that is directly passed to youtube-dl. The possible values are specific to the
website and the video, for a given url the available formats can be found with the command
youtube-dl --list-formats URL. See youtube-dl's documentation for available aliases.
(Default: youtube-dl's default, currently bestvideo+bestaudio/best)
--ytdl-raw-options==[,=[,...]]
Pass arbitrary options to youtube-dl. Parameter and argument should be passed as a key-value pair.
Options without argument must include =.
There is no sanity checking so it's possible to break things (i.e. passing invalid parameters to
youtube-dl).
A proxy URL can be passed for youtube-dl to use it in parsing the website. This is useful for
geo-restricted URLs. After youtube-dl parsing, some URLs also require a proxy for playback, so this
can pass that proxy information to mpv. Take note that SOCKS proxies aren't supported and https
URLs also bypass the proxy. This is a limitation in FFmpeg.

Example
• --ytdl-raw-options=username=user,password=pass
• --ytdl-raw-options=force-ipv6=
• --ytdl-raw-options=proxy=[http://127.0.0.1:3128]
• --ytdl-raw-options-append=proxy=http://127.0.0.1:3128

--load-stats-overlay=
Enable the builtin script that shows useful playback information on a key binding (default: yes). By
default, the i key is used (I to make the overlay permanent).
--player-operation-mode=
For enabling "pseudo GUI mode", which means that the defaults for some options are changed. This
option should not normally be used directly, but only by mpv internally, or mpv-provided scripts, config
files, or .desktop files.

Video
--vo=
Specify the video output backend to be used. See VIDEO OUTPUT DRIVERS for details and
descriptions of available drivers.
--vd=<...>
Specify a priority list of video decoders to be used, according to their family and name. See --ad for
further details. Both of these options use the same syntax and semantics; the only difference is that
they operate on different codec lists.

Note
See --vd=help for a full list of available decoders.

--vf=

Specify a list of video filters to apply to the video stream. See VIDEO FILTERS for details and
descriptions of the available filters. The option variants --vf-add, --vf-pre, --vf-del and
--vf-clr exist to modify a previously specified list, but you should not need these for typical use.
--untimed
Do not sleep when outputting video frames. Useful for benchmarks when used with --no-audio.
--framedrop=
Skip displaying some frames to maintain A/V sync on slow systems, or playing high framerate video
on video outputs that have an upper framerate limit.
The argument selects the drop methods, and can be one of the following:

Disable any framedropping.

Drop late frames on video output (default). This still decodes and filters all frames, but doesn't
render them on the VO. It tries to query the display FPS (X11 only, not correct on multi-monitor
systems), or assumes infinite display FPS if that fails. Drops are indicated in the terminal status
line as Dropped: field. If the decoder is too slow, in theory all frames would have to be dropped
(because all frames are too late) - to avoid this, frame dropping stops if the effective framerate is
below 10 FPS.

Old, decoder-based framedrop mode. (This is the same as --framedrop=yes in mpv 0.5.x and
before.) This tells the decoder to skip frames (unless they are needed to decode future frames).
May help with slow systems, but can produce unwatchable choppy output, or even freeze the
display completely. Not recommended. The --vd-lavc-framedrop option controls what
frames to drop.

Enable both modes. Not recommended.

Note
--vo=vdpau has its own code for the vo framedrop mode. Slight differences to other VOs are
possible.

--video-latency-hacks=
Enable some things which tend to reduce video latency by 1 or 2 frames (default: no). Note that this
option might be removed without notice once the player's timing code does not inherently need to do
these things anymore.
This does:
• Use the demuxer reported FPS for frame dropping. This avoids that the player needs to decode
1 frame in advance, lowering total latency in effect. This also means that if the demuxer reported
FPS is wrong, or the video filter chain changes FPS (e.g. deinterlacing), then it could drop too
many or not enough frames.
• Disable waiting for the first video frame. Normally the player waits for the first video frame to be
fully rendered before starting playback properly. Some VOs will lazily initialize stuff when
rendering the first frame, so if this is not done, there is some likeliness that the VO has to drop
some frames if rendering the first frame takes longer than needed.
--display-fps=

Set the display FPS used with the --video-sync=display-* modes. By default, a detected value
is used. Keep in mind that setting an incorrect value (even if slightly incorrect) can ruin video
playback. On multi-monitor systems, there is a chance that the detected value is from the wrong
monitor.
Set this option only if you have reason to believe the automatically determined value is wrong.
--hwdec=
Specify the hardware video decoding API that should be used if possible. Whether hardware
decoding is actually done depends on the video codec. If hardware decoding is not possible, mpv will
fall back on software decoding.
can be one of the following:
no:
auto:
yes:
auto-copy:
vdpau:
vdpau-copy:
vaapi:
vaapi-copy:
videotoolbox:
videotoolbox-c
opy:
dxva2:
dxva2-copy:
d3d11va:
d3d11va-copy:
mediacodec:
mediacodec-co
py:
mmal:
mmal-copy:
cuda:
cuda-copy:
nvdec:
nvdec-copy:
crystalhd:
rkmpp:

always use software decoding (default)
enable best hw decoder (see below)
exactly the same as auto
enable best hw decoder with copy-back (see below)
requires --vo=gpu or --vo=vdpau (Linux only)
copies video back into system RAM (Linux with some GPUs only)
requires --vo=gpu or --vo=vaapi (Linux only)
copies video back into system RAM (Linux with some GPUs only)
requires --vo=gpu (OS X 10.8 and up), or --vo=opengl-cb (iOS 9.0 and up)
copies video back into system RAM (OS X 10.8 or iOS 9.0 and up)
requires --vo=gpu with --gpu-context=d3d11, --gpu-context=angle
or --gpu-context=dxinterop (Windows only)
copies video back to system RAM (Windows only)
requires --vo=gpu with --gpu-context=d3d11 or --gpu-context=angle
(Windows 8+ only)
copies video back to system RAM (Windows 8+ only)
requires --vo=mediacodec_embed (Android only)
copies video back to system RAM (Android only)
requires --vo=gpu (Raspberry Pi only - default if available)
copies video back to system RAM (Raspberry Pi only)
requires --vo=gpu (Any platform CUDA is available)
copies video back to system RAM (Any platform CUDA is available)
requires --vo=gpu (Any platform CUDA is available)
copies video back to system RAM (Any platform CUDA is available)
copies video back to system RAM (Any platform supported by hardware)
requires --vo=gpu (some RockChip devices only)

auto tries to automatically enable hardware decoding using the first available method. This still
depends what VO you are using. For example, if you are not using --vo=gpu or --vo=vdpau, vdpau
decoding will never be enabled. Also note that if the first found method doesn't actually work, it will
always fall back to software decoding, instead of trying the next method (might matter on some Linux
systems).
auto-copy selects only modes that copy the video data back to system memory after decoding. This
selects modes like vaapi-copy (and so on). If none of these work, hardware decoding is disabled.
This mode is always guaranteed to incur no additional loss compared to software decoding, and will
allow CPU processing with video filters.

The vaapi mode, if used with --vo=gpu, requires Mesa 11 and most likely works with Intel GPUs
only. It also requires the opengl EGL backend.
The cuda and cuda-copy modes provides deinterlacing in the decoder which is useful as there is no
other deinterlacing mechanism in the opengl output path. To use this deinterlacing you must pass the
option: vd-lavc-o=deint=[weave|bob|adaptive]. Pass weave (or leave the option unset) to
not attempt any deinterlacing. cuda should always be preferred unless the gpu vo is not being used
or filters are required.
nvdec is a newer implementation of CUVID/CUDA decoding, which uses the FFmpeg decoders for
file parsing. Experimental, is known not to correctly check whether decoding is supported by the
hardware at all. Deinterlacing is not supported. Since this uses FFmpeg's codec parsers, it is
expected that this generally causes fewer issues than cuda.
Most video filters will not work with hardware decoding as they are primarily implemented on the CPU.
Some exceptions are vdpaupp, vdpaurb and vavpp. See VIDEO FILTERS for more details.
The ...-copy modes (e.g. dxva2-copy) allow you to use hardware decoding with any VO,
backend or filter. Because these copy the decoded video back to system RAM, they're likely less
efficient than the direct modes (like e.g. dxva2), and probably not more efficient than software
decoding except for some codecs (e.g. HEVC).

Note
When using this switch, hardware decoding is still only done for some codecs. See
--hwdec-codecs to enable hardware decoding for more codecs.

Quality reduction with hardware decoding
In theory, hardware decoding does not reduce video quality (at least for the codecs h264 and
HEVC). However, due to restrictions in video output APIs, as well as bugs in the actual
hardware decoders, there can be some loss, or even blatantly incorrect results.
In some cases, RGB conversion is forced, which means the RGB conversion is performed by
the hardware decoding API, instead of the shaders used by --vo=gpu. This means certain
colorspaces may not display correctly, and certain filtering (such as debanding) cannot be
applied in an ideal way. This will also usually force the use of low quality chroma scalers
instead of the one specified by --cscale. In other cases, hardware decoding can also reduce
the bit depth of the decoded image, which can introduce banding or precision loss for 10-bit
files.
vdpau is usually safe. If deinterlacing enabled (or the vdpaupp video filter is active in
general), it forces RGB conversion. The latter currently does not treat certain colorspaces like
BT.2020 correctly (which is mostly a mpv-specific restriction). The vdpauprb video filter
retrieves image data without RGB conversion and is safe (but precludes use of vdpau
postprocessing).
vaapi is safe if the vaapi-egl backend is indicated in the logs. If vaapi-glx is indicated,
and the video colorspace is either BT.601 or BT.709, a forced, low-quality but correct RGB
conversion is performed. Otherwise, the result will be totally incorrect.
d3d11va is safe when used with the d3d11 backend. If used with angle is it usually safe,
except that 10 bit input (HEVC main 10 profiles) will be rounded down to 8 bits, which will
result in reduced quality. Also note that with very old ANGLE builds (without
EGL_KHR_stream path,) all input will be converted to RGB.
dxva2 is not safe. It appears to always use BT.601 for forced RGB conversion, but actual
behavior depends on the GPU drivers. Some drivers appear to convert to limited range RGB,

which gives a faded appearance. In addition to driver-specific behavior, global system settings
might affect this additionally. This can give incorrect results even with completely ordinary
video sources.
rpi always uses the hardware overlay renderer, even with --vo=gpu.
cuda should be safe, but it has been reported to corrupt the timestamps causing glitched,
flashing frames on some files. It can also sometimes cause massive framedrops for unknown
reasons. Caution is advised.
crystalhd is not safe. It always converts to 4:2:2 YUV, which may be lossy, depending on
how chroma sub-sampling is done during conversion. It also discards the top left pixel of each
frame for some reason.
All other methods, in particular the copy-back methods (like dxva2-copy etc.) should
hopefully be safe, although they can still cause random decoding issues. At the very least, they
shouldn't affect the colors of the image.
In particular, auto-copy will only select "safe" modes (although potentially slower than other
methods), but there's still no guarantee the chosen hardware decoder will actually work
correctly.
In general, it's very strongly advised to avoid hardware decoding unless absolutely necessary,
i.e. if your CPU is insufficient to decode the file in questions. If you run into any weird decoding
issues, frame glitches or discoloration, and you have --hwdec turned on, the first thing you
should try is disabling it.

--gpu-hwdec-interop=
This option is for troubleshooting hwdec interop issues. Since it's a debugging option, its semantics
may change at any time.
This is useful for the gpu and opengl-cb VOs for selecting which hwdec interop context to use
exactly. Effectively it also can be used to block loading of certain backends.
If set to auto (default), the behavior depends on the VO: for gpu, it does nothing, and the interop
context is loaded on demand (when the decoder probes for --hwdec support). For opengl-cb,
which has has no on-demand loading, this is equivalent to all.
The empty string is equivalent to auto.
If set to all, it attempts to load all interop contexts at GL context creation time.
Other than that, a specific backend can be set, and the list of them can be queried with help (mpv
CLI only).
Runtime changes to this are ignored (the current option value is used whenever the renderer is
created).
The old aliases --opengl-hwdec-interop and --hwdec-preload are barely related to this
anymore, but will be somewhat compatible in some cases.
--hwdec-image-format=
Set the internal pixel format used by hardware decoding via --hwdec (default no). The special value
no selects an implementation specific standard format. Most decoder implementations support only
one format, and will fail to initialize if the format is not supported.
Some implementations might support multiple formats. In particular, videotoolbox is known to require
uyvy422 for good performance on some older hardware. d3d11va can always use yuv420p, which
uses an opaque format, with likely no advantages.
--cuda-decode-device=

Choose the GPU device used for decoding when using the cuda hwdec.
By default, the device that is being used to provide OpenGL output will also be used for decoding
(and in the vast majority of cases, only one GPU will be present).
Note that when using the
--vd-lavc-o=gpu=<0..>.

cuda-copy

hwdec,

different

option

must

passed:

--vaapi-device=
Choose the DRM device for vaapi-copy. This should be the path to a DRM device file. (Default:
/dev/dri/renderD128)
--panscan=<0.0-1.0>
Enables pan-and-scan functionality (cropping the sides of e.g. a 16:9 video to make it fit a 4:3 display
without black bands). The range controls how much of the image is cropped. May not work with all
video output drivers.
This option has no effect if --video-unscaled option is used.
--video-aspect=
Override video aspect ratio, in case aspect information is incorrect or missing in the file being played.
See also --no-video-aspect.
These values have special meaning:
0:
no:
-1:

disable aspect ratio handling, pretend the video has square pixels
same as 0
use the video stream or container aspect (default)

But note that handling of these special values might change in the future.

Examples
• --video-aspect=4:3 or --video-aspect=1.3333
• --video-aspect=16:9 or --video-aspect=1.7777
• --no-video-aspect or --video-aspect=no

--video-aspect-method=
This sets the default video aspect determination method (if the aspect is _not_ overridden by the user
with --video-aspect or others).
container:

bitstream:

Strictly prefer the container aspect ratio. This is apparently the default behavior
with VLC, at least with Matroska. Note that if the container has no aspect ratio
set, the behavior is the same as with bitstream.
Strictly prefer the bitstream aspect ratio, unless the bitstream aspect ratio is not
set. This is apparently the default behavior with XBMC/kodi, at least with
Matroska.

The current default for mpv is container.
Normally you should not set this. Try the various choices if you encounter video that has the wrong
aspect ratio in mpv, but seems to be correct in other players.
--video-unscaled=
Disable scaling of the video. If the window is larger than the video, black bars are added. Otherwise,
the video is cropped, unless the option is set to downscale-big, in which case the video is fit to

window. The video still can be influenced by the other --video-... options. This option disables the
effect of --panscan.
Note that the scaler algorithm may still be used, even if the video isn't scaled. For example, this can
influence chroma conversion. The video will also still be scaled in one dimension if the source uses
non-square pixels (e.g. anamorphic widescreen DVDs).
This option is disabled if the --no-keepaspect option is used.
--video-pan-x=, --video-pan-y=
Moves the displayed video rectangle by the given value in the X or Y direction. The unit is in fractions
of the size of the scaled video (the full size, even if parts of the video are not visible due to panscan or
other options).
For example, displaying a 1280x720 video fullscreen on a 1680x1050 screen with
--video-pan-x=-0.1 would move the video 168 pixels to the left (making 128 pixels of the source
video invisible).
This option is disabled if the --no-keepaspect option is used.
--video-rotate=<0-359|no>
Rotate the video clockwise, in degrees. Currently supports 90° steps only. If no is given, the video is
never rotated, even if the file has rotation metadata. (The rotation value is added to the rotation
metadata, which means the value 0 would rotate the video according to the rotation metadata.)
--video-stereo-mode=
Set the stereo 3D output mode (default: mono). This is mostly broken and thus deprecated.
The pseudo-mode no disables automatic conversion completely.
The mode mono is an alias to ml, which refers to the left frame in 2D. This is the default, which means
mpv will try to show 3D movies in 2D, instead of the mangled 3D image not intended for consumption
(such as showing the left and right frame side by side, etc.).
Use --video-stereo-mode=help to list all available modes. Check with the stereo3d filter
documentation to see what the names mean. Note that some names refer to modes not supported by
stereo3d - these modes can appear in files, but can't be handled properly by mpv.
--video-zoom=
Adjust the video display scale factor by the given value. The parameter is given log 2. For example,
--video-zoom=0 is unscaled, --video-zoom=1 is twice the size, --video-zoom=-2 is one
fourth of the size, and so on.
This option is disabled if the --no-keepaspect option is used.
--video-align-x=<-1-1>, --video-align-y=<-1-1>
Moves the video rectangle within the black borders, which are usually added to pad the video to
screen if video and screen aspect ratios are different. --video-align-y=-1 would move the video
to the top of the screen (leaving a border only on the bottom), a value of 0 centers it (default), and a
value of 1 would put the video at the bottom of the screen.
If video and screen aspect match perfectly, these options do nothing.
This option is disabled if the --no-keepaspect option is used.
--correct-pts, --no-correct-pts
--no-correct-pts switches mpv to a mode where video timing is determined using a fixed
framerate value (either using the --fps option, or using file information). Sometimes, files with very
broken timestamps can be played somewhat well in this mode. Note that video filters, subtitle
rendering and audio synchronization can be completely broken in this mode.
--fps=
Override video framerate. Useful if the original value is wrong or missing.

Note
Works in --no-correct-pts mode only.

--deinterlace=
Enable or disable interlacing (default: no). Interlaced video shows ugly comb-like artifacts, which are
visible on fast movement. Enabling this typically inserts the yadif video filter in order to deinterlace the
video, or lets the video output apply deinterlacing if supported.
This behaves exactly like the deinterlace input property (usually mapped to d).
Keep in mind that this will conflict with manually inserted deinterlacing filters, unless you take care.
(Since mpv 0.27.0, even the hardware deinterlace filters will conflict. Also since that version,
--deinterlace=auto was removed, which used to mean that the default interlacing option of
possibly inserted video filters was used.)
Note that this will make video look worse if it's not actually interlaced.
--frames=
Play/convert only first video frames, then quit.
--frames=0 loads the file, but immediately quits before initializing playback. (Might be useful for
scripts which just want to determine some file properties.)
For audio-only playback, any value greater than 0 will quit playback immediately after initialization.
The value 0 works as with video.
--video-output-levels=
RGB color levels used with YUV to RGB conversion. Normally, output devices such as PC monitors
use full range color levels. However, some TVs and video monitors expect studio RGB levels.
Providing full range output to a device expecting studio level input results in crushed blacks and
whites, the reverse in dim gray blacks and dim whites.
Not all VOs support this option. Some will silently ignore it.
Available color ranges are:
auto:
limited:
full:

automatic selection (equals to full range) (default)
limited range (16-235 per component), studio levels
full range (0-255 per component), PC levels

Note
It is advisable to use your graphics driver's color range option instead, if available.

--hwdec-codecs=
Allow hardware decoding for a given list of codecs only. The special value all always allows all
codecs.
You can get the list of allowed codecs with mpv --vd=help. Remove the prefix, e.g. instead of
lavc:h264 use h264.
By default, this is set to h264,vc1,wmv3,hevc,mpeg2video,vp9. Note that the hardware
acceleration special codecs like h264_vdpau are not relevant anymore, and in fact have been
removed from Libav in this form.

This is usually only needed with broken GPUs, where a codec is reported as supported, but decoding
causes more problems than it solves.

Example
mpv --hwdec=vdpau --vo=vdpau --hwdec-codecs=h264,mpeg2video
Enable vdpau decoding for h264 and mpeg2 only.

--vd-lavc-check-hw-profile=
Check hardware decoder profile (default: yes). If no is set, the highest profile of the hardware decoder
is unconditionally selected, and decoding is forced even if the profile of the video is higher than that.
The result is most likely broken decoding, but may also help if the detected or reported profiles are
somehow incorrect.
--vd-lavc-software-fallback=
Fallback to software decoding if the hardware-accelerated decoder fails (default: 3). If this is a
number, then fallback will be triggered if N frames fail to decode in a row. 1 is equivalent to yes.
--vd-lavc-dr=
Enable direct rendering (default: yes). If this is set to yes, the video will be decoded directly to GPU
video memory (or staging buffers). This can speed up video upload, and may help with large
resolutions or slow hardware. This works only with the following VOs:
• gpu: requires at least OpenGL 4.4 or Vulkan.
(In particular, this can't be made work with opengl-cb, but the libmpv render API has optional
support.)
Using video filters of any kind that write to the image data (or output newly allocated frames) will
silently disable the DR code path.
--vd-lavc-bitexact
Only use bit-exact algorithms in all decoding steps (for codec testing).
--vd-lavc-fast (MPEG-2, MPEG-4, and H.264 only)
Enable optimizations which do not comply with the format specification and potentially cause
problems, like simpler dequantization, simpler motion compensation, assuming use of the default
quantization matrix, assuming YUV 4:2:0 and skipping a few checks to detect damaged bitstreams.
--vd-lavc-o==[,=[,...]]
Pass AVOptions to libavcodec decoder. Note, a patch to make the o= unneeded and pass all
unknown options through the AVOption system is welcome. A full list of AVOptions can be found in
the FFmpeg manual.
Some options which used to be direct options can be set with this mechanism, like bug, gray, idct,
ec, vismv, skip_top (was st), skip_bottom (was sb), debug.

Example
--vd-lavc-o=debug=pict

--vd-lavc-show-all=

Show even broken/corrupt frames (default: no). If this option is set to no, libavcodec won't output
frames that were either decoded before an initial keyframe was decoded, or frames that are
recognized as corrupted.
--vd-lavc-skiploopfilter= (H.264 only)
Skips the loop filter (AKA deblocking) during H.264 decoding. Since the filtered frame is supposed to
be used as reference for decoding dependent frames, this has a worse effect on quality than not
doing deblocking on e.g. MPEG-2 video. But at least for high bitrate HDTV, this provides a big
speedup with little visible quality loss.
can be one of the following:
none:
default:
nonref:
bidir:
nonkey:
all:

Never skip.
Skip useless processing steps (e.g. 0 size packets in AVI).
Skip frames that are not referenced (i.e. not used for decoding other frames,
the error cannot "build up").
Skip B-Frames.
Skip all frames except keyframes.
Skip all frames.

--vd-lavc-skipidct= (MPEG-1/2 only)
Skips the IDCT step. This degrades quality a lot in almost all cases (see skiploopfilter for available
skip values).
--vd-lavc-skipframe=
Skips decoding of frames completely. Big speedup, but jerky motion and sometimes bad artifacts
(see skiploopfilter for available skip values).
--vd-lavc-framedrop=
Set framedropping mode used with --framedrop (see skiploopfilter for available skip values).
--vd-lavc-threads=
Number of threads to use for decoding. Whether threading is actually supported depends on codec
(default: 0). 0 means autodetect number of cores on the machine and use that, up to the maximum of
16. You can set more than 16 threads manually.
--vd-lavc-assume-old-x264=
Assume the video was encoded by an old, buggy x264 version (default: no). Normally, this is
autodetected by libavcodec. But if the bitstream contains no x264 version info (or it was somehow
skipped), and the stream was in fact encoded by an old x264 version (build 150 or earlier), and if the
stream uses 4:4:4 chroma, then libavcodec will by default show corrupted video. This option sets the
libavcodec x264_build option to 150, which means that if the stream contains no version info, or
was not encoded by x264 at all, it assumes it was encoded by the old version. Enabling this option is
pretty safe if you want your broken files to work, but in theory this can break on streams not encoded
by x264, or if a stream encoded by a newer x264 version contains no version info.

Audio
--audio-pitch-correction=
If this is enabled (default), playing with a speed different from normal automatically inserts the
scaletempo audio filter. For details, see audio filter section.
--audio-device=
Use the given audio device. This consists of the audio output name, e.g. alsa, followed by /,
followed by the audio output specific device name. The default value for this option is auto, which
tries every audio output in preference order with the default device.
You can list audio devices with --audio-device=help. This outputs the device name in quotes,
followed by a description. The device name is what you have to pass to the --audio-device

option. The list of audio devices can be retrieved by API by using the audio-device-list property.
While the option normally takes one of the strings as indicated by the methods above, you can also
force the device for most AOs by building it manually. For example name/foobar forces the AO
name to use the device foobar. However, the --ao option will strictly force a specific AO. To avoid
confusion, don't use --ao and --audio-device together.

Example for ALSA
MPlayer and mplayer2 required you to replace any ',' with '.' and any ':' with '=' in the ALSA
device name. For example, to use the device named dmix:default, you had to do:
-ao alsa:device=dmix=default
In mpv you could instead use:
--audio-device=alsa/dmix:default

--audio-exclusive=
Enable exclusive output mode. In this mode, the system is usually locked out, and only mpv will be
able to output audio.
This only works for some audio outputs, such as wasapi and coreaudio. Other audio outputs
silently ignore this options. They either have no concept of exclusive mode, or the mpv side of the
implementation is missing.
--audio-fallback-to-null=
If no audio device can be opened, behave as if --ao=null was given. This is useful in combination
with --audio-device: instead of causing an error if the selected device does not exist, the client
API user (or a Lua script) could let playback continue normally, and check the current-ao and
audio-device-list properties to make high-level decisions about how to continue.
--ao=
Specify the audio output drivers to be used. See AUDIO OUTPUT DRIVERS for details and
descriptions of available drivers.
--af=
Specify a list of audio filters to apply to the audio stream. See AUDIO FILTERS for details and
descriptions of the available filters. The option variants --af-add, --af-pre, --af-del and
--af-clr exist to modify a previously specified list, but you should not need these for typical use.
--audio-spdif=

List of codecs for which compressed audio passthrough should be used. This works for both classic
S/PDIF and HDMI.
Possible codecs are ac3, dts, dts-hd, eac3, truehd. Multiple codecs can be specified by
separating them with ,. dts refers to low bitrate DTS core, while dts-hd refers to DTS MA (receiver
and OS support varies). If both dts and dts-hd are specified, it behaves equivalent to specifying
dts-hd only.
In earlier mpv versions you could use --ad to force the spdif wrapper. This does not work anymore.

Warning
There is not much reason to use this. HDMI supports uncompressed multichannel PCM, and
mpv supports lossless DTS-HD decoding via FFmpeg's new DCA decoder (based on
libdcadec).

--ad=
Specify a priority list of audio decoders to be used, according to their decoder name. When
determining which decoder to use, the first decoder that matches the audio format is selected. If that
is unavailable, the next decoder is used. Finally, it tries all other decoders that are not explicitly
selected or rejected by the option.
- at the end of the list suppresses fallback on other available decoders not on the --ad list. + in front
of an entry forces the decoder. Both of these should not normally be used, because they break normal
decoder auto-selection! Both of these methods are deprecated.

Examples
--ad=mp3float
Prefer the FFmpeg/Libav mp3float decoder over all other MP3 decoders.
--ad=help
List all available decoders.

Warning
Enabling compressed audio passthrough (AC3 and DTS via SPDIF/HDMI) with this option is
not possible. Use --audio-spdif instead.

--volume=
Set the startup volume. 0 means silence, 100 means no volume reduction or amplification. Negative
values can be passed for compatibility, but are treated as 0.
Since mpv 0.18.1, this always controls the internal mixer (aka "softvol").
--replaygain=
Adjust volume gain according to the track-gain or album-gain replaygain value stored in the file
metadata (default: no replaygain).
--replaygain-preamp=

Pre-amplification gain in dB to apply to the selected replaygain gain (default: 0).
--replaygain-clip=
Prevent clipping caused by replaygain by automatically lowering the gain (default). Use
--replaygain-clip=no to disable this.
--replaygain-fallback=
Gain in dB to apply if the file has no replay gain tags. This option is always applied if the replaygain
logic is somehow inactive. If this is applied, no other replaygain options are applied.
--audio-delay=
Audio delay in seconds (positive or negative float value). Positive values delay the audio, and
negative values delay the video.
--mute=
Set startup audio mute status (default: no).
auto is a deprecated possible value that is equivalent to no.
See also: --volume.
--softvol=
Deprecated/unfunctional. Before mpv 0.18.1, this used to control whether to use the volume controls
of the audio output driver or the internal mpv volume filter.
The current behavior is that softvol is always enabled, i.e. as if this option is set to yes. The other
behaviors are not available anymore, although auto almost matches current behavior in most cases.
The no behavior is still partially available through the ao-volume and ao-mute properties. But there
are no options to reset these.
--audio-demuxer=<[+]name>
Use this audio demuxer type when using --audio-file. Use a '+' before the name to force it; this
will skip some checks. Give the demuxer name as printed by --audio-demuxer=help.
--ad-lavc-ac3drc=
Select the Dynamic Range Compression level for AC-3 audio streams. is a float value
ranging from 0 to 1, where 0 means no compression (which is the default) and 1 means full
compression (make loud passages more silent and vice versa). Values up to 6 are also accepted, but
are purely experimental. This option only shows an effect if the AC-3 stream contains the required
range compression information.
The standard mandates that DRC is enabled by default, but mpv (and some other players) ignore this
for the sake of better audio quality.
--ad-lavc-downmix=
Whether to request audio channel downmixing from the decoder (default: yes). Some decoders, like
AC-3, AAC and DTS, can remix audio on decoding. The requested number of output channels is set
with the --audio-channels option. Useful for playing surround audio on a stereo system.
--ad-lavc-threads=<0-16>
Number of threads to use for decoding. Whether threading is actually supported depends on codec.
As of this writing, it's supported for some lossless codecs only. 0 means autodetect number of cores
on the machine and use that, up to the maximum of 16 (default: 1).
--ad-lavc-o==[,=[,...]]
Pass AVOptions to libavcodec decoder. Note, a patch to make the o= unneeded and pass all
unknown options through the AVOption system is welcome. A full list of AVOptions can be found in
the FFmpeg manual.
--ad-spdif-dtshd=, --dtshd, --no-dtshd
If DTS is passed through, use DTS-HD.

Warning
This and enabling passthrough
--audio-spdif=dts-hd.

via

--ad

are

deprecated

favor

using

--audio-channels=
Control which audio channels are output (e.g. surround vs. stereo). There are the following
possibilities:
• --audio-channels=auto-safe
Use the system's preferred channel layout. If there is none (such as when accessing a
hardware device instead of the system mixer), force stereo. Some audio outputs might
simply accept any layout and do downmixing on their own.
This is the default.
• --audio-channels=auto
Send the audio device whatever it accepts, preferring the audio's original channel layout.
Can cause issues with HDMI (see the warning below).
• --audio-channels=layout1,layout2,...
List of ,-separated channel layouts which should be allowed. Technically, this only adjusts
the filter chain output to the best matching layout in the list, and passes the result to the
audio API. It's possible that the audio API will select a different channel layout.
Using this mode is recommended for direct hardware output, especially over HDMI (see
HDMI warning below).
• --audio-channels=stereo
Force a plain stereo downmix. This is a special-case of the previous item. (See paragraphs
below for implications.)
If a list of layouts is given, each item can be either an explicit channel layout name (like 5.1), or a
channel number. Channel numbers refer to default layouts, e.g. 2 channels refer to stereo, 6 refers to
5.1.
See --audio-channels=help output for defined default layouts. This also lists speaker names,
which can be used to express arbitrary channel layouts (e.g. fl-fr-lfe is 2.1).
If the list of channel layouts has only 1 item, the decoder is asked to produce according output. This
sometimes triggers decoder-downmix, which might be different from the normal mpv downmix. (Only
some decoders support remixing audio, like AC-3, AAC or DTS. You can use
--ad-lavc-downmix=no to make the decoder always output its native layout.) One consequence is
that --audio-channels=stereo triggers decoder downmix, while auto or auto-safe never will,
even if they end up selecting stereo. This happens because the decision whether to use decoder
downmix happens long before the audio device is opened.
If the channel layout of the media file (i.e. the decoder) and the AO's channel layout don't match, mpv
will attempt to insert a conversion filter. You may need to change the channel layout of the system
mixer to achieve your desired output as mpv does not have control over it. Another work-around for
this on some AOs is to use --audio-exclusive=yes to circumvent the system mixer entirely.

Warning
Using auto can cause issues when using audio over HDMI. The OS will typically report all
channel layouts that _can_ go over HDMI, even if the receiver does not support them. If a

receiver gets an unsupported channel layout, random things can happen, such as dropping the
additional channels, or adding noise.
You are recommended to set an explicit whitelist of the layouts you want. For example, most
A/V receivers connected via HDMI and that can do 7.1 would be served by:
--audio-channels=7.1,5.1,stereo

--audio-display=
Setting this option to attachment (default) will display image attachments (e.g. album cover art)
when playing audio files. It will display the first image found, and additional images are available as
video tracks.
Setting this option to no disables display of video entirely when playing audio files.
This option has no influence on files with normal video tracks.
--audio-files=
Play audio from an external file while viewing a video.
This is a list option. See List Options for details.
--audio-file=
CLI/config file only alias for --audio-files-append. Each use of this option will add a new audio
track. The details are similar to how --sub-file works.
--audio-format=
Select the sample format used for output from the audio filter layer to the sound card. The values that
can adopt are listed below in the description of the format audio filter.
--audio-samplerate=
Select the output sample rate to be used (of course sound cards have limits on this). If the sample
frequency selected is different from that of the current media, the lavrresample audio filter will be
inserted into the audio filter layer to compensate for the difference.
--gapless-audio=
Try to play consecutive audio files with no silence or disruption at the point of file change. Default:
weak.
no:
yes:

weak:

Disable gapless audio.
The audio device is opened using parameters chosen for the first file played
and is then kept open for gapless playback. This means that if the first file for
example has a low sample rate, then the following files may get resampled to
the same low sample rate, resulting in reduced sound quality. If you play files
with
different
parameters,
consider
using
options
such
as
--audio-samplerate and --audio-format to explicitly select what the
shared output format will be.
Normally, the audio device is kept open (using the format it was first initialized
with). If the audio format the decoder output changes, the audio device is
closed and reopened. This means that you will normally get gapless audio with
files that were encoded using the same settings, but might not be gapless in
other cases. The exact conditions under which the audio device is kept open is
an implementation detail, and can change from version to version. Currently,
the device is kept even if the sample format changes, but the sample formats
are convertible.

Note
This feature is implemented in a simple manner and relies on audio output device buffering to
continue playback while moving from one file to another. If playback of the new file starts
slowly, for example because it is played from a remote network location or because you have
specified cache settings that require time for the initial cache fill, then the buffered audio may
run out before playback of the new file can start.

--initial-audio-sync, --no-initial-audio-sync
When starting a video file or after events such as seeking, mpv will by default modify the audio
stream to make it start from the same timestamp as video, by either inserting silence at the start or
cutting away the first samples. Disabling this option makes the player behave like older mpv versions
did: video and audio are both started immediately even if their start timestamps differ, and then video
timing is gradually adjusted if necessary to reach correct synchronization later.
--volume-max=<100.0-1000.0>, --softvol-max=<...>
Set the maximum amplification level in percent (default: 130). A value of 130 will allow you to adjust
the volume up to about double the normal level.
--softvol-max is a deprecated alias and should not be used.
--audio-file-auto=, --no-audio-file-auto
Load additional audio files matching the video filename. The parameter specifies how external audio
files are matched.
no:
exact:
fuzzy:
all:

Don't automatically load external audio files (default).
Load the media filename with audio file extension.
Load all audio files containing media filename.
Load all audio files in the current and --audio-file-paths directories.

--audio-file-paths=
Equivalent to --sub-file-paths option, but for auto-loaded audio files.
--audio-client-name=
The application name the player reports to the audio API. Can be useful if you want to force a
different audio profile (e.g. with PulseAudio), or to set your own application name when using libmpv.
--audio-buffer=
Set the audio output minimum buffer. The audio device might actually create a larger buffer if it
pleases. If the device creates a smaller buffer, additional audio is buffered in an additional software
buffer.
Making this larger will make soft-volume and other filters react slower, introduce additional issues on
playback speed change, and block the player on audio format changes. A smaller buffer might lead to
audio dropouts.
This option should be used for testing only. If a non-default value helps significantly, the mpv
developers should be contacted.
Default: 0.2 (200 ms).
--audio-stream-silence=
Cash-grab consumer audio hardware (such as A/V receivers) often ignore initial audio sent over
HDMI. This can happen every time audio over HDMI is stopped and resumed. In order to compensate
for this, you can enable this option to not to stop and restart audio on seeks, and fill the gaps with
silence. Likewise, when pausing playback, audio is not stopped, and silence is played

while paused. Note that if no audio track is selected, the audio device will still be closed immediately.
Not all AOs support this.
--audio-wait-open=
This makes sense for use with --audio-stream-silence=yes. If this option is given, the player
will wait for the given amount of seconds after opening the audio device before sending actual audio
data to it. Useful if your expensive hardware discards the first 1 or 2 seconds of audio data sent to it. If
--audio-stream-silence=yes is not set, this option will likely just waste time.

Subtitles
Note
Changing styling and position does not work with all subtitles. Image-based subtitles (DVD,
Bluray/PGS, DVB) cannot changed for fundamental reasons. Subtitles in ASS format are normally
not changed intentionally, but overriding them can be controlled with --sub-ass-override.
Previously some options working on text subtitles were called --sub-text-*, they are now
named --sub-*, and those specifically for ASS have been renamed from --ass-* to
--sub-ass-*. They are now all in this section.

--sub-demuxer=<[+]name>
Force subtitle demuxer type for --sub-file. Give the demuxer name as printed by
--sub-demuxer=help.
--sub-delay=
Delays subtitles by seconds. Can be negative.
--sub-files=, --sub-file=
Add a subtitle file to the list of external subtitles.
If you use --sub-file only once, this subtitle file is displayed by default.
If --sub-file is used multiple times, the subtitle to use can be switched at runtime by cycling
subtitle tracks. It's possible to show two subtitles at once: use --sid to select the first subtitle index,
and --secondary-sid to select the second index. (The index is printed on the terminal output after
the --sid= in the list of streams.)
--sub-files is a list option (see List Options for details), and can take multiple file names
separated by : (Unix) or ; (Windows), while --sub-file takes a single filename, but can be used
multiple times to add multiple files. Technically, --sub-file is a CLI/config file only alias for
--sub-files-append.
--secondary-sid=
Select a secondary subtitle stream. This is similar to --sid. If a secondary subtitle is selected, it will
be rendered as toptitle (i.e. on the top of the screen) alongside the normal subtitle, and provides a way
to render two subtitles at once.
There are some caveats associated with this feature. For example, bitmap subtitles will always be
rendered in their usual position, so selecting a bitmap subtitle as secondary subtitle will result in
overlapping subtitles. Secondary subtitles are never shown on the terminal if video is disabled.

Note
Styling and interpretation of any formatting tags is disabled for the secondary subtitle.
Internally, the same mechanism as --no-sub-ass is used to strip the styling.

Note
If the main subtitle stream contains formatting tags which display the subtitle at the top of the
screen, it will overlap with the secondary subtitle. To prevent this, you could use
--no-sub-ass to disable styling in the main subtitle stream.

--sub-scale=<0-100>
Factor for the text subtitle font size (default: 1).

Note
This affects ASS subtitles as well, and may lead to incorrect subtitle rendering. Use with care,
or use --sub-font-size instead.

--sub-scale-by-window=
Whether to scale subtitles with the window size (default: yes). If this is disabled, changing the window
size won't change the subtitle font size.
Like --sub-scale, this can break ASS subtitles.
--sub-scale-with-window=
Make the subtitle font size relative to the window, instead of the video. This is useful if you always
want the same font size, even if the video doesn't cover the window fully, e.g. because screen aspect
and window aspect mismatch (and the player adds black bars).
Default: yes.
This option is misnamed. The difference to the confusingly similar sounding option
--sub-scale-by-window is that --sub-scale-with-window still scales with the approximate
window size, while the other option disables this scaling.
Affects plain text subtitles only (or ASS if --sub-ass-override is set high enough).
--sub-ass-scale-with-window=
Like --sub-scale-with-window, but affects subtitles in ASS format only. Like --sub-scale, this
can break ASS subtitles.
Default: no.
--embeddedfonts, --no-embeddedfonts
Use fonts embedded in Matroska container files and ASS scripts (default: enabled). These fonts can
be used for SSA/ASS subtitle rendering.
--sub-pos=<0-100>
Specify the position of subtitles on the screen. The value is the vertical position of the subtitle in % of
the screen height.

Note
This affects ASS subtitles as well, and may lead to incorrect subtitle rendering. Use with care,
or use --sub-margin-y instead.

--sub-speed=<0.1-10.0>
Multiply the subtitle event timestamps with the given value. Can be used to fix the playback speed for
frame-based subtitle formats. Affects text subtitles only.

Example
--sub-speed=25/23.976 plays frame based subtitles which have been loaded assuming a
framerate of 23.976 at 25 FPS.

--sub-ass-force-style=<[Style.]Param=Value[,...]>
Override some style or script info parameters.

Examples
• --sub-ass-force-style=FontName=Arial,Default.Bold=1
• --sub-ass-force-style=PlayResY=768

Note
Using this option may lead to incorrect subtitle rendering.

--sub-ass-hinting=
Set font hinting type. can be:
none:
light:
normal:
native:

no hinting (default)
FreeType autohinter, light mode
FreeType autohinter, normal mode
font native hinter

Warning
Enabling hinting can lead to mispositioned text (in situations it's supposed to match up video
background), or reduce the smoothness of animations with some badly authored ASS scripts.
It is recommended to not use this option, unless really needed.

--sub-ass-line-spacing=
Set line spacing value for SSA/ASS renderer.
--sub-ass-shaper=
Set the text layout engine used by libass.
simple:
complex:

uses Fribidi only, fast, doesn't render some languages correctly
uses HarfBuzz, slower, wider language support

complex is the default. If libass hasn't been compiled against HarfBuzz, libass silently reverts to
simple.
--sub-ass-styles=
Load all SSA/ASS styles found in the specified file and use them for rendering text subtitles. The
syntax of the file is exactly like the [V4 Styles] / [V4+ Styles] section of SSA/ASS.

Note
Using this option may lead to incorrect subtitle rendering.

--sub-ass-override=
Control whether user style overrides should be applied. Note that all of these overrides try to be
somewhat smart about figuring out whether or not a subtitle is considered a "sign".
no:
yes:
force:
scale:
strip:

Render subtitles as specified by the subtitle scripts, without overrides.
Apply all the --sub-ass-* style override options. Changing the default for any
of these options can lead to incorrect subtitle rendering (default).
Like yes, but also force all --sub-* options. Can break rendering easily.
Like yes, but also apply --sub-scale.
Radically strip all ASS tags and styles from the subtitle. This is equivalent to the
old --no-ass / --no-sub-ass options.

--sub-ass-force-margins
Enables placing toptitles and subtitles in black borders when they are available, if the subtitles are in
the ASS format.
Default: no.
--sub-use-margins
Enables placing toptitles and subtitles in black borders when they are available, if the subtitles are in a
plain text format (or ASS if --sub-ass-override is set high enough).
Default: yes.
Renamed from --sub-ass-use-margins. To place ASS subtitles in the borders too (like the old
option did), also add --sub-ass-force-margins.
--sub-ass-vsfilter-aspect-compat=
Stretch SSA/ASS subtitles when playing anamorphic videos for compatibility with traditional VSFilter
behavior. This switch has no effect when the video is stored with square pixels.
The renderer historically most commonly used for the SSA/ASS subtitle formats, VSFilter, had
questionable behavior that resulted in subtitles being stretched too if the video was stored in
anamorphic format that required scaling for display. This behavior is usually undesirable and newer
VSFilter versions may behave differently. However, many existing scripts compensate for the
stretching by modifying things in the opposite direction. Thus, if such scripts are displayed "correctly",
they will not appear as intended. This switch enables emulation of the old VSFilter behavior
(undesirable but expected by many existing scripts).

Enabled by default.
--sub-ass-vsfilter-blur-compat=
Scale \blur tags by video resolution instead of script resolution (enabled by default). This is bug in
VSFilter, which according to some, can't be fixed anymore in the name of compatibility.
Note that this uses the actual video resolution for calculating the offset scale factor, not what the
video filter chain or the video output use.
--sub-ass-vsfilter-color-compat=
Mangle colors like (xy-)vsfilter do (default: basic). Historically, VSFilter was not color space aware.
This was no problem as long as the color space used for SD video (BT.601) was used. But when
everything switched to HD (BT.709), VSFilter was still converting RGB colors to BT.601, rendered
them into the video frame, and handled the frame to the video output, which would use BT.709 for
conversion to RGB. The result were mangled subtitle colors. Later on, bad hacks were added on top
of the ASS format to control how colors are to be mangled.
basic:
full:

force-601:
no:

Handle only BT.601->BT.709 mangling, if the subtitles seem to indicate that this
is required (default).
Handle the full YCbCr Matrix header with all video color spaces supported by
libass and mpv. This might lead to bad breakages in corner cases and is not
strictly needed for compatibility (hopefully), which is why this is not default.
Force BT.601->BT.709 mangling, regardless of subtitle headers or video color
space.
Disable color mangling completely. All colors are RGB.

Choosing anything other than no will make the subtitle color depend on the video color space, and it's
for example in theory not possible to reuse a subtitle script with another video file. The
--sub-ass-override option doesn't affect how this option is interpreted.
--stretch-dvd-subs=
Stretch DVD subtitles when playing anamorphic videos for better looking fonts on badly mastered
DVDs. This switch has no effect when the video is stored with square pixels - which for DVD input
cannot be the case though.
Many studios tend to use bitmap fonts designed for square pixels when authoring DVDs, causing the
fonts to look stretched on playback on DVD players. This option fixes them, however at the price of
possibly misaligning some subtitles (e.g. sign translations).
Disabled by default.
--stretch-image-subs-to-screen=
Stretch DVD and other image subtitles to the screen, ignoring the video margins. This has a similar
effect as --sub-use-margins for text subtitles, except that the text itself will be stretched, not only
just repositioned. (At least in general it is unavoidable, as an image bitmap can in theory consist of a
single bitmap covering the whole screen, and the player won't know where exactly the text parts are
located.)
This option does not display subtitles correctly. Use with care.
Disabled by default.
--image-subs-video-resolution=
Override the image subtitle resolution with the video resolution (default: no). Normally, the subtitle
canvas is fit into the video canvas (e.g. letterboxed). Setting this option uses the video size as subtitle
canvas size. Can be useful to test broken subtitles, which often happen when the video was
trancoded, while attempting to keep the old subtitles.
--sub-ass, --no-sub-ass
Render ASS subtitles natively (enabled by default).

Note
This has been deprecated by --sub-ass-override=strip. You also may need
--embeddedfonts=no
to
get
the
same
behavior.
Also,
using
--sub-ass-override=style should give better results without breaking subtitles too
much.

If --no-sub-ass is specified, all tags and style declarations are stripped and ignored on display. The
subtitle renderer uses the font style as specified by the --sub- options instead.

Note
Using --no-sub-ass may lead to incorrect or completely broken rendering of ASS/SSA
subtitles. It can sometimes be useful to forcibly override the styling of ASS subtitles, but should
be avoided in general.

--sub-auto=, --no-sub-auto
Load additional subtitle files matching the video filename. The parameter specifies how external
subtitle files are matched. exact is enabled by default.
no:
exact:
fuzzy:
all:

Don't automatically load external subtitle files.
Load the media filename with subtitle file extension (default).
Load all subs containing media filename.
Load all subs in the current and --sub-file-paths directories.

--sub-codepage=

You can use this option to specify the subtitle codepage. uchardet will be used to guess the charset.
(If mpv was not compiled with uchardet, then utf-8 is the effective default.)
The default value for this option is auto, which enables autodetection.
The following steps are taken to determine the final codepage, in order:
• if the specific codepage has a +, use that codepage
• if the data looks like UTF-8, assume it is UTF-8
• if --sub-codepage is set to a specific codepage, use that
• run uchardet, and if successful, use that
• otherwise, use UTF-8-BROKEN

Examples
• --sub-codepage=latin2 Use Latin 2 if input is not UTF-8.
• --sub-codepage=+cp1250 Always force recoding to cp1250.

The pseudo codepage UTF-8-BROKEN is used internally. If it's set, subtitles are interpreted as UTF-8
with "Latin 1" as fallback for bytes which are not valid UTF-8 sequences. iconv is never involved in this
mode.
This option changed in mpv 0.23.0. Support for the old syntax was fully removed in mpv 0.24.0.
--sub-fix-timing=
Adjust subtitle timing is to remove minor gaps or overlaps between subtitles (if the difference is
smaller than 210 ms, the gap or overlap is removed).
--sub-forced-only
Display only forced subtitles for the DVD subtitle stream selected by e.g. --slang.
--sub-fps=
Specify the framerate of the subtitle file (default: video fps). Affects text subtitles only.

Note
> video fps speeds the subtitles up for frame-based subtitle files and slows them down
for time-based ones.

See also: --sub-speed.
--sub-gauss=<0.0-3.0>
Apply Gaussian blur to image subtitles (default: 0). This can help to make pixelated DVD/Vobsubs
look nicer. A value other than 0 also switches to software subtitle scaling. Might be slow.

Note
Never applied to text subtitles.

--sub-gray
Convert image subtitles to grayscale. Can help to make yellow DVD/Vobsubs look nicer.

Note
Never applied to text subtitles.

--sub-paths=
Deprecated, use --sub-file-paths.
--sub-file-paths=
Specify extra directories to search for subtitles matching the video. Multiple directories can be
separated by ":" (";" on Windows). Paths can be relative or absolute. Relative paths are interpreted
relative to video file directory. If the file is a URL, only absolute paths and sub configuration
subdirectory will be scanned.

Example
Assuming
that
/path/to/video/video.avi
is
played
and
--sub-file-paths=sub:subtitles is specified, mpv searches for subtitle files in these
directories:
• /path/to/video/
• /path/to/video/sub/
• /path/to/video/subtitles/
• the sub configuration subdirectory (usually ~/.config/mpv/sub/)

This is a list option. See List Options for details.
--sub-visibility, --no-sub-visibility
Can be used to disable display of subtitles, but still select and decode them.
--sub-clear-on-seek
(Obscure, rarely useful.) Can be used to play broken mkv files with duplicate ReadOrder fields.
ReadOrder is the first field in a Matroska-style ASS subtitle packets. It should be unique, and libass
uses it for fast elimination of duplicates. This option disables caching of subtitles across seeks, so
after a seek libass can't eliminate subtitle packets with the same ReadOrder as earlier packets.
--teletext-page=<1-999>
This works for dvb_teletext subtitle streams, and if FFmpeg has been compiled with support for it.
--sub-font=
Specify font to use for subtitles that do not themselves specify a particular font. The default is
sans-serif.

Examples
• --sub-font='Bitstream Vera Sans'
• --sub-font='Comic Sans MS'

Note
The --sub-font option (and many other style related --sub- options) are ignored when
ASS-subtitles are rendered, unless the --no-sub-ass option is specified.
This used to support fontconfig patterns. Starting with libass 0.13.0, this stopped working.

--sub-font-size=
Specify the sub font size. The unit is the size in scaled pixels at a window height of 720. The actual
pixel size is scaled with the window height: if the window height is larger or smaller than 720, the
actual size of the text increases or decreases as well.
Default: 55.
--sub-back-color=
See --sub-color. Color used for sub text background. You can use --sub-shadow-offset to
change its size relative to the text.
--sub-blur=<0..20.0>
Gaussian blur factor. 0 means no blur applied (default).
--sub-bold=
Format text on bold.
--sub-italic=
Format text on italic.
--sub-border-color=
See --sub-color. Color used for the sub font border.

Note
ignored when --sub-back-color is specified (or more exactly: when that option is not set to
completely transparent).

--sub-border-size=
Size of the sub font border in scaled pixels (see --sub-font-size for details). A value of 0 disables
borders.
Default: 3.
--sub-color=
Specify the color used for unstyled text subtitles.
The color is specified in the form r/g/b, where each color component is specified as number in the
range 0.0 to 1.0. It's also possible to specify the transparency by using r/g/b/a, where the alpha

value 0 means fully transparent, and 1.0 means opaque. If the alpha component is not given, the color
is 100% opaque.
Passing a single number to the option sets the sub to gray, and the form gray/a lets you specify
alpha additionally.

Examples
• --sub-color=1.0/0.0/0.0 set sub to opaque red
• --sub-color=1.0/0.0/0.0/0.75 set sub to opaque red with 75% alpha
• --sub-color=0.5/0.75 set sub to 50% gray with 75% alpha

Alternatively, the color can be specified as a RGB hex triplet in the form #RRGGBB, where each 2-digit
group expresses a color value in the range 0 (00) to 255 (FF). For example, #FF0000 is red. This is
similar to web colors. Alpha is given with #AARRGGBB.

Examples
• --sub-color='#FF0000' set sub to opaque red
• --sub-color='#C0808080' set sub to 50% gray with 75% alpha

--sub-margin-x=
Left and right screen margin for the subs in scaled pixels (see --sub-font-size for details).
This option specifies the distance of the sub to the left, as well as at which distance from the right
border long sub text will be broken.
Default: 25.
--sub-margin-y=
Top and bottom screen margin for the subs in scaled pixels (see --sub-font-size for details).
This option specifies the vertical margins of unstyled text subtitles. If you just want to raise the vertical
subtitle position, use --sub-pos.
Default: 22.
--sub-align-x=
Control to which corner of the screen text subtitles should be aligned to (default: center).
Never applied to ASS subtitles, except in --no-sub-ass mode. Likewise, this does not apply to
image subtitles.
--sub-align-y=
Vertical position (default: bottom). Details see --sub-align-x.
--sub-justify=
Control how multi line subs are justified irrespective of where they are aligned (default: auto which
justifies as defined by --sub-align-y). Left justification is recommended to make the subs easier to
read as it is easier for the eyes.
--sub-ass-justify=
Applies justification as defined by --sub-justify on ASS subtitles if --sub-ass-override is not
set to no. Default: no.

--sub-shadow-color=
See --sub-color. Color used for sub text shadow.
--sub-shadow-offset=
Displacement of the sub text shadow in scaled pixels (see --sub-font-size for details). A value of
0 disables shadows.
Default: 0.
--sub-spacing=
Horizontal sub font spacing in scaled pixels (see --sub-font-size for details). This value is added
to the normal letter spacing. Negative values are allowed.
Default: 0.
--sub-filter-sdh=
Applies filter removing subtitle additions for the deaf or hard-of-hearing (SDH). This is intended for
English, but may in part work for other languages too. The intention is that it can be always enabled
so may not remove all parts added. It removes speaker labels (like MAN:), upper case text in
parentheses and any text in brackets.
Default: no.
--sub-filter-sdh-harder=
Do harder SDH filtering (if enabled by --sub-filter-sdh). Will also remove speaker labels and
text within parentheses using both lower and upper case letters.
Default: no.
--sub-create-cc-track=
For every video stream, create a closed captions track (default: no). The only purpose is to make the
track available for selection at the start of playback, instead of creating it lazily. This applies only to
ATSC A53 Part 4 Closed Captions (displayed by mpv as subtitle tracks using the codec
eia_608). The CC track is marked "default" and selected according to the normal subtitle track
selection rules. You can then use --sid to explicitly select the correct track too.
If the video stream contains no closed captions, or if no video is being decoded, the CC track will
remain empty and will not show any text.

Window
--title=
Set the window title. This is used for the video window, and if possible, also sets the audio stream
title.
Properties are expanded. (See Property Expansion.)

Warning
There is a danger of this causing significant CPU usage, depending on the properties used.
Changing the window title is often a slow operation, and if the title changes every frame,
playback can be ruined.

--screen=
In multi-monitor configurations (i.e. a single desktop that spans across multiple displays), this option
tells mpv which screen to display the video on.

Note (X11)
This option does not work properly with all window managers. In these cases, you can try to
use --geometry to position the window explicitly. It's also possible that the window manager
provides native features to control which screens application windows should use.

See also --fs-screen.
--fullscreen, --fs
Fullscreen playback.
--fs-screen=
In multi-monitor configurations (i.e. a single desktop that spans across multiple displays), this option
tells mpv which screen to go fullscreen to. If default is provided mpv will fallback on using the
behavior depending on what the user provided with the screen option.

Note (X11)
This option works properly only with window managers which understand the EWMH
_NET_WM_FULLSCREEN_MONITORS hint.

Note (OS X)
all does not work on OS X and will behave like current.

See also --screen.
--keep-open=
Do not terminate when playing or seeking beyond the end of the file, and there is not next file to be
played (and --loop is not used). Instead, pause the player. When trying to seek beyond end of the
file, the player will attempt to seek to the last frame.
Normally, this will act like set pause yes on EOF, unless the --keep-open-pause=no option is
set.
The following arguments can be given:
no:
yes:
always:

If the current file ends, go to the next file or terminate. (Default.)
Don't terminate if the current file is the last playlist entry. Equivalent to
--keep-open without arguments.
Like yes, but also applies to files before the last playlist entry. This means
playback will never automatically advance to the next file.

Note
This option is not respected when using --frames. Explicitly skipping to the next file if the
binding uses force will terminate playback as well.

Also, if errors or unusual circumstances happen, the player can quit anyway.

Since mpv 0.6.0, this doesn't pause if there is a next file in the playlist, or the playlist is looped.
Approximately, this will pause when the player would normally exit, but in practice there are corner
cases in which this is not the case (e.g. mpv --keep-open file.mkv /dev/null will play
file.mkv normally, then fail to open /dev/null, then exit). (In mpv 0.8.0, always was introduced,
which restores the old behavior.)
--keep-open-pause=
If set to no, instead of pausing when --keep-open is active, just stop at end of file and continue
playing forward when you seek backwards until end where it stops again. Default: yes.
--image-display-duration=
If the current file is an image, play the image for the given amount of seconds (default: 1). inf means
the file is kept open forever (until the user stops playback manually).
Unlike --keep-open, the player is not paused, but simply continues playback until the time has
elapsed. (It should not use any resources during "playback".)
This affects image files, which are defined as having only 1 video frame and no audio. The player may
recognize certain non-images as images, for example if --length is used to reduce the length to 1
frame, or if you seek to the last frame.
This option does not affect the framerate used for mf:// or --merge-files. For that, use
--mf-fps instead.
Setting --image-display-duration hides the OSC and does not track playback time on the
command-line output, and also does not duplicate the image frame when encoding. To force the
player into "dumb mode" and actually count out seconds, or to duplicate the image when encoding,
you need to use --demuxer=lavf --demuxer-lavf-o=loop=1, and use --length or
--frames to stop after a particular time.
--force-window=
Create a video output window even if there is no video. This can be useful when pretending that mpv
is a GUI application. Currently, the window always has the size 640x480, and is subject to
--geometry, --autofit, and similar options.

Warning
The window is created only after initialization (to make sure default window placement still
works if the video size is different from the --force-window default window size). This can
be a problem if initialization doesn't work perfectly, such as when opening URLs with bad
network connection, or opening broken video files. The immediate mode can be used to
create the window always on program start, but this may cause other issues.

--taskbar-progress, --no-taskbar-progress
(Windows only) Enable/disable playback progress rendering in taskbar (Windows 7 and above).
Enabled by default.
--snap-window
(Windows only) Snap the player window to screen edges.
--ontop
Makes the player window stay on top of other windows.

On Windows, if combined with fullscreen mode, this causes mpv to be treated as exclusive fullscreen
window that bypasses the Desktop Window Manager.
--ontop-level=
(OS X only) Sets the level of an ontop window (default: window).
window:
system:
level:

On top of all other windows.
On top of system elements like Taskbar, Menubar and Dock.
A level as integer.

--border, --no-border
Play video with window border and decorations. Since this is on by default, use --no-border to
disable the standard window decorations.
--fit-border, --no-fit-border
(Windows only) Fit the whole window with border and decorations on the screen. Since this is on by
default, use --no-fit-border to make mpv try to only fit client area with video on the screen. This
behavior only applied to window/video with size exceeding size of the screen.
--on-all-workspaces
(X11 only) Show the video window on all virtual desktops.
--geometry=<[W[xH]][+-x+-y]>, --geometry=
Adjust the initial window position or size. W and H set the window size in pixels. x and y set the window
position, measured in pixels from the top-left corner of the screen to the top-left corner of the image
being displayed. If a percentage sign (%) is given after the argument, it turns the value into a
percentage of the screen size in that direction. Positions are specified similar to the standard X11
--geometry option format, in which e.g. +10-50 means "place 10 pixels from the left border and 50
pixels from the lower border" and "--20+-10" means "place 20 pixels beyond the right and 10 pixels
beyond the top border".
If an external window is specified using the --wid option, this option is ignored.
The coordinates are relative to the screen given with --screen for the video output drivers that fully
support --screen.

Note
Generally only supported by GUI VOs. Ignored for encoding.

Note (X11)
This option does not work properly with all window managers.

Examples
50:40
Places the window at x=50, y=40.
50%:50%
Places the window in the middle of the screen.
100%:100%
Places the window at the bottom right corner of the screen.

50%
Sets the window width to half the screen width. Window height is set so that the window
has the video aspect ratio.
50%x50%
Forces the window width and height to half the screen width and height. Will show black
borders to compensate for the video aspect ratio (with most VOs and without
--no-keepaspect).
50%+10+10
Sets the window to half the screen widths, and positions it 10 pixels below/left of the top
left corner of the screen.

See also --autofit and --autofit-larger for fitting the window into a given size without
changing aspect ratio.
--autofit=<[W[xH]]>
Set the initial window size to a maximum size specified by WxH, without changing the window's aspect
ratio. The size is measured in pixels, or if a number is followed by a percentage sign (%), in percents of
the screen size.
This option never changes the aspect ratio of the window. If the aspect ratio mismatches, the
window's size is reduced until it fits into the specified size.
Window position is not taken into account, nor is it modified by this option (the window manager still
may place the window differently depending on size). Use --geometry to change the window
position. Its effects are applied after this option.
See --geometry for details how this is handled with multi-monitor setups.
Use --autofit-larger instead if you just want to limit the maximum size of the window, rather
than always forcing a window size.
Use --geometry if you want to force both window width and height to a specific size.

Note
Generally only supported by GUI VOs. Ignored for encoding.

Examples
70%
Make the window width 70% of the screen size, keeping aspect ratio.
1000
Set the window width to 1000 pixels, keeping aspect ratio.
70%x60%
Make the window as large as possible, without being wider than 70% of the screen width,
or higher than 60% of the screen height.

--autofit-larger=<[W[xH]]>

This option behaves exactly like --autofit, except the window size is only changed if the window
would be larger than the specified size.

Example
90%x80%
If the video is larger than 90% of the screen width or 80% of the screen height, make the
window smaller until either its width is 90% of the screen, or its height is 80% of the
screen.

--autofit-smaller=<[W[xH]]>
This option behaves exactly like --autofit, except that it sets the minimum size of the window (just
as --autofit-larger sets the maximum).

Example
500x500
Make the window at least 500 pixels wide and 500 pixels high (depending on the video
aspect ratio, the width or height will be larger than 500 in order to keep the aspect ratio
the same).

--window-scale=
Resize the video window to a multiple (or fraction) of the video size. This option is applied before
--autofit and other options are applied (so they override this option).
For example, --window-scale=0.5 would show the window at half the video size.
--cursor-autohide=
Make mouse cursor automatically hide after given number of milliseconds. no will disable cursor
autohide. always means the cursor will stay hidden.
--cursor-autohide-fs-only
If this option is given, the cursor is always visible in windowed mode. In fullscreen mode, the cursor is
shown or hidden according to --cursor-autohide.
--no-fixed-vo, --fixed-vo
--no-fixed-vo enforces closing and reopening the video window for multiple files (one
(un)initialization for each file).
--force-rgba-osd-rendering
Change how some video outputs render the OSD and text subtitles. This does not change
appearance of the subtitles and only has performance implications. For VOs which support native
ASS rendering (like gpu, vdpau, direct3d), this can be slightly faster or slower, depending on GPU
drivers and hardware. For other VOs, this just makes rendering slower.
--force-window-position
Forcefully move mpv's video output window to default location whenever there is a change in video
parameters, video stream or file. This used to be the default behavior. Currently only affects X11
VOs.
--no-keepaspect, --keepaspect
--no-keepaspect will always stretch the video to window size, and will disable the window
manager hints that force the window aspect ratio. (Ignored in fullscreen mode.)

--no-keepaspect-window, --keepaspect-window
--keepaspect-window (the default) will lock the window size to the video aspect.
--no-keepaspect-window disables this behavior, and will instead add black bars if window aspect
and video aspect mismatch. Whether this actually works depends on the VO backend. (Ignored in
fullscreen mode.)
--monitoraspect=
Set the aspect ratio of your monitor or TV screen. A value of 0 disables a previous setting (e.g. in the
config file). Overrides the --monitorpixelaspect setting if enabled.
See also --monitorpixelaspect and --video-aspect.

Examples
• --monitoraspect=4:3 or --monitoraspect=1.3333
• --monitoraspect=16:9 or --monitoraspect=1.7777

--hidpi-window-scale, --no-hidpi-window-scale
(OS X and X11 only) Scale the window size according to the backing scale factor (default: yes). On
regular HiDPI resolutions the window opens with double the size but appears as having the same
size as on none-HiDPI resolutions. This is the default OS X behavior.
--native-fs, --no-native-fs
(OS X only) Uses the native fullscreen mechanism of the OS (default: yes).
--monitorpixelaspect=
Set the aspect of a single pixel of your monitor or TV screen (default: 1). A value of 1 means square
pixels (correct for (almost?) all LCDs). See also --monitoraspect and --video-aspect.
--stop-screensaver, --no-stop-screensaver
Turns off the screensaver (or screen blanker and similar mechanisms) at startup and turns it on again
on exit (default: yes). The screensaver is always re-enabled when the player is paused.
This is not supported on all video outputs or platforms. Sometimes it is implemented, but does not
work (known to happen with GNOME). You might be able to work around this using
--heartbeat-cmd instead.
--wid=
This tells mpv to attach to an existing window. If a VO is selected that supports this option, it will use
that window for video output. mpv will scale the video to the size of this window, and will add black
bars to compensate if the aspect ratio of the video is different.
On X11, the ID is interpreted as a Window on X11. Unlike MPlayer/mplayer2, mpv always creates its
own window, and sets the wid window as parent. The window will always be resized to cover the
parent window fully. The value 0 is interpreted specially, and mpv will draw directly on the root
window.
On win32, the ID is interpreted as HWND. Pass it as value cast to intptr_t. mpv will create its own
window, and set the wid window as parent, like with X11.
On OSX/Cocoa, the ID is interpreted as NSView*. Pass it as value cast to intptr_t. mpv will create
its own sub-view. Because OSX does not support window embedding of foreign processes, this works
only with libmpv, and will crash when used from the command line.
On Android, the ID is interpreted as android.view.Surface. Pass it as a value cast to intptr_t.
Use with --vo=mediacodec_embed and --hwdec=mediacodec for direct rendering using
MediaCodec,
or
with
--vo=gpu
--gpu-context=android
(with
or
without
--hwdec=mediacodec-copy).

--no-window-dragging
Don't move the window when clicking on it and moving the mouse pointer.
--x11-name
Set the window class name for X11-based video output methods.
--x11-netwm=
(X11 only) Control the use of NetWM protocol features.
This may or may not help with broken window managers. This provides some functionality that was
implemented by the now removed --fstype option. Actually, it is not known to the developers to
which degree this option was needed, so feedback is welcome.
Specifically, yes will force use of NetWM fullscreen support, even if not advertised by the WM. This
can be useful for WMs that are broken on purpose, like XMonad. (XMonad supposedly doesn't
advertise fullscreen support, because Flash uses it. Apparently, applications which want to use
fullscreen anyway are supposed to either ignore the NetWM support hints, or provide a workaround.
Shame on XMonad for deliberately breaking X protocols (as if X isn't bad enough already).
By default, NetWM support is autodetected (auto).
This option might be removed in the future.
--x11-bypass-compositor=
If set to yes, then ask the compositor to unredirect the mpv window (default: fs-only). This uses the
_NET_WM_BYPASS_COMPOSITOR hint.
fs-only asks the window manager to disable the compositor only in fullscreen mode.
no sets _NET_WM_BYPASS_COMPOSITOR to 0, which is the default value as declared by the EWMH
specification, i.e. no change is done.
never asks the window manager to never disable the compositor.

Disc Devices
--cdrom-device=
Specify the CD-ROM device (default: /dev/cdrom).
--dvd-device=
Specify the DVD device or .iso filename (default: /dev/dvd). You can also specify a directory that
contains files previously copied directly from a DVD (with e.g. vobcopy).

Example
mpv dvd:// --dvd-device=/path/to/dvd/

--bluray-device=
(Blu-ray only) Specify the Blu-ray disc location. Must be a directory with Blu-ray structure.

Example
mpv bd:// --bluray-device=/path/to/bd/

--cdda-...
These options can be used to tune the CD Audio reading feature of mpv.

--cdda-speed=
Set CD spin speed.
--cdda-paranoia=<0-2>
Set paranoia level. Values other than 0 seem to break playback of anything but the first track.
0:
1:
2:

disable checking (default)
overlap checking only
full data correction and verification

--cdda-sector-size=
Set atomic read size.
--cdda-overlap=
Force minimum overlap search during verification to sectors.
--cdda-toc-bias
Assume that the beginning offset of track 1 as reported in the TOC will be addressed as LBA 0. Some
discs need this for getting track boundaries correctly.
--cdda-toc-offset=
Add sectors to the values reported when addressing tracks. May be negative.
--cdda-skip=
(Never) accept imperfect data reconstruction.
--cdda-cdtext=
Print CD text. This is disabled by default, because it ruins performance with CD-ROM drives for
unknown reasons.
--dvd-speed=
Try to limit DVD speed (default: 0, no change). DVD base speed is 1385 kB/s, so an 8x drive can read
at speeds up to 11080 kB/s. Slower speeds make the drive more quiet. For watching DVDs, 2700
kB/s should be quiet and fast enough. mpv resets the speed to the drive default value on close.
Values of at least 100 mean speed in kB/s. Values less than 100 mean multiples of 1385 kB/s, i.e.
--dvd-speed=8 selects 11080 kB/s.

Note
You need write access to the DVD device to change the speed.

--dvd-angle=
Some DVDs contain scenes that can be viewed from multiple angles. This option tells mpv which
angle to use (default: 1).

Equalizer
--brightness=<-100-100>
Adjust the brightness of the video signal (default: 0). Not supported by all video output drivers.
--contrast=<-100-100>
Adjust the contrast of the video signal (default: 0). Not supported by all video output drivers.
--saturation=<-100-100>
Adjust the saturation of the video signal (default: 0). You can get grayscale output with this option.
Not supported by all video output drivers.
--gamma=<-100-100>

Adjust the gamma of the video signal (default: 0). Not supported by all video output drivers.
--hue=<-100-100>
Adjust the hue of the video signal (default: 0). You can get a colored negative of the image with this
option. Not supported by all video output drivers.

Demuxer
--demuxer=<[+]name>
Force demuxer type. Use a '+' before the name to force it; this will skip some checks. Give the
demuxer name as printed by --demuxer=help.
--demuxer-lavf-analyzeduration=
Maximum length in seconds to analyze the stream properties.
--demuxer-lavf-probe-info=
Whether to probe stream information (default: auto). Technically, this controls whether libavformat's
avformat_find_stream_info() function is called. Usually it's safer to call it, but it can also make
startup slower.
The auto choice (the default) tries to skip this for a few know-safe whitelisted formats, while calling it
for everything else.
The nostreams choice only calls it if and only if the file seems to contain no streams after opening
(helpful in cases when calling the function is needed to detect streams at all, such as with FLV files).
--demuxer-lavf-probescore=<1-100>
Minimum required libavformat probe score. Lower values will require less data to be loaded (makes
streams start faster), but makes file format detection less reliable. Can be used to force auto-detected
libavformat demuxers, even if libavformat considers the detection not reliable enough. (Default: 26.)
--demuxer-lavf-allow-mimetype=
Allow deriving the format from the HTTP MIME type (default: yes). Set this to no in case playing
things from HTTP mysteriously fails, even though the same files work from local disk.
This is default in order to reduce latency when opening HTTP streams.
--demuxer-lavf-format=
Force a specific libavformat demuxer.
--demuxer-lavf-hacks=
By default, some formats will be handled differently from other formats by explicitly checking for them.
Most of these compensate for weird or imperfect behavior from libavformat demuxers. Passing no
disables these. For debugging and testing only.
--demuxer-lavf-genpts-mode=
Mode for deriving missing packet PTS values from packet DTS. lavf enables libavformat's genpts
option. no disables it. This used to be enabled by default, but then it was deemed as not needed
anymore. Enabling this might help with timestamp problems, or make them worse.
--demuxer-lavf-o==[,=[,...]]

Pass AVOptions to libavformat demuxer.
Note, a patch to make the o= unneeded and pass all unknown options through the AVOption system
is welcome. A full list of AVOptions can be found in the FFmpeg manual. Note that some options may
conflict with mpv options.

Example
--demuxer-lavf-o=fflags=+ignidx

--demuxer-lavf-probesize=
Maximum amount of data to probe during the detection phase. In the case of MPEG-TS this value
identifies the maximum number of TS packets to scan.
--demuxer-lavf-buffersize=
Size of the stream read buffer allocated for libavformat in bytes (default: 32768). Lowering the size
could lower latency. Note that libavformat might reallocate the buffer internally, or not fully use all of it.
--demuxer-mkv-subtitle-preroll=, --mkv-subtitle-preroll
Try harder to show embedded soft subtitles when seeking somewhere. Normally, it can happen that
the subtitle at the seek target is not shown due to how some container file formats are designed. The
subtitles appear only if seeking before or exactly to the position a subtitle first appears. To make this
worse, subtitles are often timed to appear a very small amount before the associated video frame, so
that seeking to the video frame typically does not demux the subtitle at that position.
Enabling this option makes the demuxer start reading data a bit before the seek target, so that
subtitles appear correctly. Note that this makes seeking slower, and is not guaranteed to always
work. It only works if the subtitle is close enough to the seek target.
Works with the internal Matroska demuxer only. Always enabled for absolute and hr-seeks, and this
option changes behavior with relative or imprecise seeks only.
You can use the --demuxer-mkv-subtitle-preroll-secs option to specify how much data the
demuxer should pre-read at most in order to find subtitle packets that may overlap. Setting this to 0
will effectively disable this preroll mechanism. Setting a very large value can make seeking very slow,
and an extremely large value would completely reread the entire file from start to seek target on every
seek - seeking can become slower towards the end of the file. The details are messy, and the value is
actually rounded down to the cluster with the previous video keyframe.
Some files, especially files muxed with newer mkvmerge versions, have information embedded that
can be used to determine what subtitle packets overlap with a seek target. In these cases, mpv will
reduce the amount of data read to a minimum. (Although it will still read all data between the cluster
that contains the first wanted subtitle packet, and the seek target.) If the index choice (which is the
default) is specified, then prerolling will be done only if this information is actually available. If this
method is used, the maximum amount of data to skip can be additionally controlled by
--demuxer-mkv-subtitle-preroll-secs-index (it still uses the value of the option without
-index if that is higher).
See also --hr-seek-demuxer-offset option. This option can achieve a similar effect, but only if
hr-seek is active. It works with any demuxer, but makes seeking much slower, as it has to decode
audio and video data instead of just skipping over it.
--mkv-subtitle-preroll is a deprecated alias.
--demuxer-mkv-subtitle-preroll-secs=
See --demuxer-mkv-subtitle-preroll.
--demuxer-mkv-subtitle-preroll-secs-index=
See --demuxer-mkv-subtitle-preroll.

--demuxer-mkv-probe-video-duration=
When opening the file, seek to the end of it, and check what timestamp the last video packet has, and
report that as file duration. This is strictly for compatibility with Haali only. In this mode, it's possible
that opening will be slower (especially when playing over http), or that behavior with broken files is
much worse. So don't use this option.
The yes mode merely uses the index and reads a small number of blocks from the end of the file. The
full mode actually traverses the entire file and can make a reliable estimate even without an index
present (such as partial files).
--demuxer-rawaudio-channels=
Number of channels (or channel layout) if --demuxer=rawaudio is used (default: stereo).
--demuxer-rawaudio-format=
Sample
format
for
--demuxer=rawaudio
--demuxer-rawaudio-format=help to get a list of all formats.

(default:

s16le).

Use

--demuxer-rawaudio-rate=
Sample rate for --demuxer=rawaudio (default: 44 kHz).
--demuxer-rawvideo-fps=
Rate in frames per second for --demuxer=rawvideo (default: 25.0).
--demuxer-rawvideo-w=, --demuxer-rawvideo-h=
Image dimension in pixels for --demuxer=rawvideo.

Example
Play a raw YUV sample:
mpv sample-720x576.yuv --demuxer=rawvideo \
--demuxer-rawvideo-w=720 --demuxer-rawvideo-h=576

--demuxer-rawvideo-format=
Color space (fourcc) in hex or string for --demuxer=rawvideo (default: YV12).
--demuxer-rawvideo-mp-format=
Color
space
by
internal
video
format
for
--demuxer=rawvideo.
--demuxer-rawvideo-mp-format=help for a list of possible formats.

Use

--demuxer-rawvideo-codec=
Set the video codec instead of selecting the rawvideo codec when using --demuxer=rawvideo.
This uses the same values as codec names in --vd (but it does not accept decoder names).
--demuxer-rawvideo-size=
Frame size in bytes when using --demuxer=rawvideo.
--demuxer-max-bytes=
This controls how much the demuxer is allowed to buffer ahead. The demuxer will normally try to read
ahead as much as necessary, or as much is requested with --demuxer-readahead-secs. The
option can be used to restrict the maximum readahead. This limits excessive readahead in case of
broken files or desynced playback. The demuxer will stop reading additional packets as soon as one
of the limits is reached. (The limits still can be slightly overstepped due to technical reasons.)
Set these limits higher if you get a packet queue overflow warning, and you think normal playback
would be possible with a larger packet queue.

See --list-options for defaults and value range. options accept suffixes such as
KiB and MiB.
--demuxer-max-back-bytes=
This controls how much past data the demuxer is allowed to preserve. This is useful only if the
--demuxer-seekable-cache option is enabled. Unlike the forward cache, there is no control how
many seconds are actually cached - it will simply use as much memory this option allows. Setting this
option to 0 will strictly disable any back buffer, but this will lead to the situation that the forward seek
range starts after the current playback position (as it removes past packets that are seek points).
Keep in mind that other buffers in the player (like decoders) will cause the demuxer to cache "future"
frames in the back buffer, which can skew the impression about how much data the backbuffer
contains.
See --list-options for defaults and value range.
--demuxer-seekable-cache=
This controls whether seeking can use the demuxer cache (default: auto). If enabled, short seek
offsets will not trigger a low level demuxer seek (which means for example that slow network round
trips or FFmpeg seek bugs can be avoided). If a seek cannot happen within the cached range, a low
level seek will be triggered. Seeking outside of the cache will start a new cached range, but can
discard the old cache range if the demuxer exhibits certain unsupported behavior.
Keep in mind that some events can flush the cache or force a low level seek anyway, such as
switching tracks, or attempting to seek before the start or after the end of the file.
The special value auto means yes in the same situation as --cache-secs is used (i.e. when the
stream appears to be a network stream or the stream cache is enabled).
--demuxer-thread=
Run the demuxer in a separate thread, and let it prefetch a certain amount of packets (default: yes).
Having this enabled may lead to smoother playback, but on the other hand can add delays to seeking
or track switching.
--demuxer-readahead-secs=
If --demuxer-thread is enabled, this controls how much the demuxer should buffer ahead in
seconds (default: 1). As long as no packet has a timestamp difference higher than the readahead
amount relative to the last packet returned to the decoder, the demuxer keeps reading.
Note that the --cache-secs option will override this value if a cache is enabled, and the value is
larger.
(This value tends to be fuzzy, because many file formats don't store linear timestamps.)
--prefetch-playlist=
Prefetch next playlist entry while playback of the current entry is ending (default: no). This merely
opens the URL of the next playlist entry as soon as the current URL is fully read.
This does not work with URLs resolved by the youtube-dl wrapper, and it won't.
This does not affect HLS (.m3u8 URLs) - HLS prefetching depends on the demuxer cache settings
and is on by default.
This can give subtly wrong results if per-file options are used, or if options are changed in the time
window between prefetching start and next file played.
This can occasionally make wrong prefetching decisions. For example, it can't predict whether you go
backwards in the playlist, and assumes you won't edit the playlist.
Highly experimental.
--force-seekable=
If the player thinks that the media is not seekable (e.g. playing from a pipe, or it's an http stream with
a server that doesn't support range requests), seeking will be disabled. This option can forcibly
enable it. For seeks within the cache, there's a good chance of success.

Input
--native-keyrepeat
Use system settings for keyrepeat delay and rate, instead of --input-ar-delay and
--input-ar-rate. (Whether this applies depends on the VO backend and how it handles keyboard
input. Does not apply to terminal input.)
--input-ar-delay
Delay in milliseconds before we start to autorepeat a key (0 to disable).
--input-ar-rate
Number of key presses to generate per second on autorepeat.
--input-conf=
Specify input configuration file other than the default location in the mpv configuration directory
(usually ~/.config/mpv/input.conf).
--no-input-default-bindings
Disable mpv default (built-in) key bindings.
--input-cmdlist
Prints all commands that can be bound to keys.
--input-doubleclick-time=
Time in milliseconds to recognize two consecutive button presses as a double-click (default: 300).
--input-keylist
Prints all keys that can be bound to commands.
--input-key-fifo-size=<2-65000>
Specify the size of the FIFO that buffers key events (default: 7). If it is too small, some events may be
lost. The main disadvantage of setting it to a very large value is that if you hold down a key triggering
some particularly slow command then the player may be unresponsive while it processes all the
queued commands.
--input-test
Input test mode. Instead of executing commands on key presses, mpv will show the keys and the
bound commands on the OSD. Has to be used with a dummy video, and the normal ways to quit the
player will not work (key bindings that normally quit will be shown on OSD only, just like any other
binding). See INPUT.CONF.
--input-file=
Read commands from the given file. Mostly useful with a FIFO. Since mpv 0.7.0 also understands
JSON commands (see JSON IPC), but you can't get replies or events. Use --input-ipc-server
for something bi-directional. On MS Windows, JSON commands are not available.
This can also specify a direct file descriptor with fd://N (UNIX only). In this case, JSON replies will
be written if the FD is writable.

Note
When the given file is a FIFO mpv opens both ends, so you can do several echo "seek 10" >
mp_pipe and the pipe will stay valid.

--input-terminal, --no-input-terminal
--no-input-terminal prevents the player from reading key events from standard input. Useful
when reading data from standard input. This is automatically enabled when - is found on the
command line. There are situations where you have to set it manually, e.g. if you open /dev/stdin

(or the equivalent on your system), use stdin in a playlist or intend to read from stdin later on via the
loadfile or loadlist input commands.
--input-ipc-server=
Enable the IPC support and create the listening socket at the given path.
On Linux and Unix, the given path is a regular filesystem path. On Windows, named pipes are used,
so the path refers to the pipe namespace (\\.\pipe\). If the \\.\pipe\ prefix is missing,
mpv
will
add
it
automatically
before
creating
the
pipe,
so
--input-ipc-server=/tmp/mpv-socket
and
--input-ipc-server=\\.\pipe\tmp\mpv-socket are equivalent for IPC on Windows.
See JSON IPC for details.
--input-appleremote=
(OS X only) Enable/disable Apple Remote support. Enabled by default (except for libmpv).
--input-cursor, --no-input-cursor
Permit mpv to receive pointer events reported by the video output driver. Necessary to use the OSC,
or to select the buttons in DVD menus. Support depends on the VO in use.
--input-media-keys=
(OS X and Windows only) Enable/disable media keys support. Enabled by default (except for libmpv).
--input-right-alt-gr, --no-input-right-alt-gr
(Cocoa and Windows only) Use the right Alt key as Alt Gr to produce special characters. If disabled,
count the right Alt as an Alt modifier key. Enabled by default.
--input-vo-keyboard=
Disable all keyboard input on for VOs which can't participate in proper keyboard input dispatching.
May not affect all VOs. Generally useful for embedding only.
On X11, a sub-window with input enabled grabs all keyboard input as long as it is 1. a child of a
focused window, and 2. the mouse is inside of the sub-window. It can steal away all keyboard input
from the application embedding the mpv window, and on the other hand, the mpv window will receive
no input if the mouse is outside of the mpv window, even though mpv has focus. Modern toolkits work
around this weird X11 behavior, but naively embedding foreign windows breaks it.
The only way to handle this reasonably is using the XEmbed protocol, which was designed to solve
these problems. GTK provides GtkSocket, which supports XEmbed. Qt doesn't seem to provide
anything working in newer versions.
If the embedder supports XEmbed, input should work with default settings and with this option
disabled. Note that input-default-bindings is disabled by default in libmpv as well - it should be
enabled if you want the mpv default key bindings.
(This option was renamed from --input-x11-keyboard.)

OSD
--osc, --no-osc
Whether to load the on-screen-controller (default: yes).
--no-osd-bar, --osd-bar
Disable display of the OSD bar.
You can configure this on a per-command basis in input.conf using osd- prefixes, see
Input Command Prefixes. If you want to disable the OSD completely, use --osd-level=0.
--osd-on-seek=
Set what is displayed on the OSD during seeks. The default is bar.
You can configure this on a per-command basis in input.conf using osd- prefixes, see
Input Command Prefixes.

--osd-duration=
Set the duration of the OSD messages in ms (default: 1000).
--osd-font=
Specify font to use for OSD. The default is sans-serif.

Examples
• --osd-font='Bitstream Vera Sans'
• --osd-font='Comic Sans MS'

--osd-font-size=
Specify the OSD font size. See --sub-font-size for details.
Default: 55.
--osd-msg1=
Show this string as message on OSD with OSD level 1 (visible by default). The message will be
visible by default, and as long as no other message covers it, and the OSD level isn't changed (see
--osd-level). Expands properties; see Property Expansion.
--osd-msg2=
Similar to --osd-msg1, but for OSD level 2. If this is an empty string (default), then the playback time
is shown.
--osd-msg3=
Similar to --osd-msg1, but for OSD level 3. If this is an empty string (default), then the playback
time, duration, and some more information is shown.
This is used for the show-progress command (by default mapped to P), and when seeking if
enabled with --osd-on-seek or by osd- prefixes in input.conf (see Input Command Prefixes).
--osd-status-msg is a legacy equivalent (but with a minor difference).
--osd-status-msg=
Show a custom string during playback instead of the standard status text. This overrides the status
text used for --osd-level=3, when using the show-progress command (by default mapped to P),
and when seeking if enabled with --osd-on-seek or osd- prefixes in input.conf (see
Input Command Prefixes). Expands properties. See Property Expansion.
This option has been replaced with --osd-msg3. The only difference is that this option implicitly
includes ${osd-sym-cc}. This option is ignored if --osd-msg3 is not empty.
--osd-playing-msg=
Show a message on OSD when playback starts. The string is expanded for properties, e.g.
--osd-playing-msg='file: ${filename}' will show the message file: followed by a space
and the currently played filename.
See Property Expansion.
--osd-bar-align-x=<-1-1>
Position of the OSD bar. -1 is far left, 0 is centered, 1 is far right. Fractional values (like 0.5) are
allowed.
--osd-bar-align-y=<-1-1>
Position of the OSD bar. -1 is top, 0 is centered, 1 is bottom. Fractional values (like 0.5) are allowed.
--osd-bar-w=<1-100>

Width of the OSD bar, in percentage of the screen width (default: 75). A value of 50 means the bar is
half the screen wide.
--osd-bar-h=<0.1-50>
Height of the OSD bar, in percentage of the screen height (default: 3.125).
--osd-back-color=
See --osd-color. Color used for OSD text background.
--osd-blur=<0..20.0>
Gaussian blur factor. 0 means no blur applied (default).
--osd-bold=
Format text on bold.
--osd-italic=
Format text on italic.
--osd-border-color=
See --osd-color. Color used for the OSD font border.

Note
ignored when --osd-back-color is specified (or more exactly: when that option is not set to
completely transparent).

--osd-border-size=
Size of the OSD font border in scaled pixels (see --sub-font-size for details). A value of 0
disables borders.
Default: 3.
--osd-color=
Specify the color used for OSD. See --sub-color for details.
--osd-fractions
Show OSD times with fractions of seconds (in millisecond precision). Useful to see the exact
timestamp of a video frame.
--osd-level=<0-3>
Specifies which mode the OSD should start in.
0:
1:
2:
3:

OSD completely disabled (subtitles only)
enabled (shows up only on user interaction)
enabled + current time visible by default
enabled + --osd-status-msg (current time and status by default)

--osd-margin-x=
Left and right screen margin for the OSD in scaled pixels (see --sub-font-size for details).
This option specifies the distance of the OSD to the left, as well as at which distance from the right
border long OSD text will be broken.
Default: 25.
--osd-margin-y=
Top and bottom screen margin for the OSD in scaled pixels (see --sub-font-size for details).
This option specifies the vertical margins of the OSD.

Default: 22.
--osd-align-x=
Control to which corner of the screen OSD should be aligned to (default: left).
--osd-align-y=
Vertical position (default: top). Details see --osd-align-x.
--osd-scale=
OSD font size multiplier, multiplied with --osd-font-size value.
--osd-scale-by-window=
Whether to scale the OSD with the window size (default: yes). If this is disabled, --osd-font-size
and other OSD options that use scaled pixels are always in actual pixels. The effect is that changing
the window size won't change the OSD font size.
--osd-shadow-color=
See --sub-color. Color used for OSD shadow.
--osd-shadow-offset=
Displacement of the OSD shadow in scaled pixels (see --sub-font-size for details). A value of 0
disables shadows.
Default: 0.
--osd-spacing=
Horizontal OSD/sub font spacing in scaled pixels (see --sub-font-size for details). This value is
added to the normal letter spacing. Negative values are allowed.
Default: 0.
--video-osd=
Enabled OSD rendering on the video window (default: yes). This can be used in situations where
terminal OSD is preferred. If you just want to disable all OSD rendering, use --osd-level=0.
It does not affect subtitles or overlays created by scripts (in particular, the OSC needs to be disabled
with --no-osc).
This option is somewhat experimental and could be replaced by another mechanism in the future.

Screenshot
--screenshot-format=
Set the image file type used for saving screenshots.
Available choices:
png:
jpg:
jpeg:

PNG
JPEG (default)
JPEG (alias for jpg)

--screenshot-tag-colorspace=
Tag screenshots with the appropriate colorspace.
Note that not all formats are supported.
Default: no.
--screenshot-high-bit-depth=
If possible, write screenshots with a bit depth similar to the source video (default: yes). This is
interesting in particular for PNG, as this sometimes triggers writing 16 bit PNGs with huge file sizes.
This will also include an unused alpha channel in the resulting files if 16 bit is used.
--screenshot-template=