diff options
Diffstat (limited to 'DOCS/man/options.rst')
| -rw-r--r-- | DOCS/man/options.rst | 1365 |
1 files changed, 1194 insertions, 171 deletions
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index ec8f82349d..374cdaf1a5 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -36,15 +36,32 @@ Track Selection 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=<ID|auto|no>`` Display the subtitle stream specified by ``<ID>``. ``auto`` selects the default, ``no`` disables subtitles. - See also ``--slang``, ``--no-sub``. + ``--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=<ID|auto|no>`` 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. + ``--ff-aid=<ID|auto|no>``, ``--ff-sid=<ID|auto|no>``, ``--ff-vid=<ID|auto|no>`` Select audio/subtitle/video streams by the FFmpeg stream index. The FFmpeg stream index is relatively arbitrary, but useful when interacting with @@ -140,17 +157,19 @@ Playback Control See also: ``--start``. -``--playlist-pos=<no|index>`` +``--playlist-start=<auto|index>`` Set which file on the internal playlist to start playback with. The index - is an integer, with 0 meaning the first file. The value ``no`` means that + 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-pos=123`` will work as expected, + 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=<filename>`` 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 @@ -308,9 +327,13 @@ Playback Control Program Behavior ---------------- -``--help`` +``--help``, ``--h`` Show short summary of options. + You can also pass a shell pattern to this option, which will list all + matching top-level options, e.g. ``--h=*scale*`` for all options that + contain the word "scale". + ``-v`` Increment verbosity level, one level for each ``-v`` found on the command line. @@ -364,6 +387,13 @@ Program Behavior This behavior is disabled by default, but is always available when quitting the player with Shift+Q. +``--watch-later-directory=<path>`` + + 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=<filename>`` Write certain statistics to the given file. The file is truncated on opening. The file will contain raw samples, each with a timestamp. To @@ -491,14 +521,18 @@ Program Behavior ``--ytdl-raw-options=username=user,password=pass`` ``--ytdl-raw-options=force-ipv6=`` +``--player-operation-mode=<cplayer|pseudo-gui>`` + 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=<driver1[:suboption1[=value]:...],driver2,...[,]>`` - Specify a priority list of video output drivers to be used. For - interactive use, one would normally specify a single one to use, but in - configuration files, specifying a list of fallbacks may make sense. See - `VIDEO OUTPUT DRIVERS`_ for details and descriptions of available drivers. +``--vo=<driver>`` + Specify the video output backend to be used. See `VIDEO OUTPUT DRIVERS`_ for + details and descriptions of available drivers. ``--vd=<[+|-]family1:(*|decoder1),[+|-]family2:(*|decoder2),...[-]>`` Specify a priority list of video decoders to be used, according to their @@ -517,14 +551,6 @@ Video ``--vf-clr`` exist to modify a previously specified list, but you should not need these for typical use. -``--no-video`` - Do not play video. With some demuxers this may not work. In those cases - you can try ``--vo=null`` instead. - - 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. - ``--untimed`` Do not sleep when outputting video frames. Useful for benchmarks when used with ``--no-audio.`` @@ -580,21 +606,26 @@ Video ``<api>`` can be one of the following: :no: always use software decoding (default) - :auto: see below - :auto-copy: see below + :auto: enable best hw decoder (see below) + :yes: exactly the same as ``auto`` + :auto-copy: enable best hw decoder with copy-back (see below) :vdpau: requires ``--vo=vdpau`` or ``--vo=opengl`` (Linux only) :vaapi: requires ``--vo=opengl`` or ``--vo=vaapi`` (Linux only) :vaapi-copy: copies video back into system RAM (Linux with Intel GPUs only) :videotoolbox: requires ``--vo=opengl`` (OS X 10.8 and up only) :videotoolbox-copy: copies video back into system RAM (OS X 10.8 and up only) - :dxva2: requires ``--vo=opengl:backend=angle`` or - - ``--vo=opengl:backend=dxinterop`` (Windows only) + :dxva2: requires ``--vo=opengl`` with ``--opengl-backend=angle`` or + ``--opengl-backend=dxinterop`` (Windows only) :dxva2-copy: copies video back to system RAM (Windows only) - :d3d11va: requires ``--vo=opengl:backend=angle`` (Windows only) + :d3d11va: requires ``--vo=opengl`` with ``--opengl-backend=angle`` + (Windows only) :d3d11va-copy: copies video back to system RAM (Windows only) :mediacodec: copies video back to system RAM (Android only) - :rpi: requires ``--vo=rpi`` (Raspberry Pi only - default if available) + :rpi: requires ``--vo=opengl`` (Raspberry Pi only - default if available) + :rpi-copy: copies video back to system RAM (Raspberry Pi only) + :cuda: requires ``--vo=opengl`` (Any platform CUDA is available) + :cuda-copy: copies video back to system RAM (Any platform CUDA is available) + :crystalhd: copies video back to system RAM (Any platform supported by hardware) ``auto`` tries to automatically enable hardware decoding using the first available method. This still depends what VO you are using. For example, @@ -613,7 +644,7 @@ Video The ``vaapi`` mode, if used with ``--vo=opengl``, requires Mesa 11 and most likely works with Intel GPUs only. It also requires the opengl EGL backend (automatically used if available). You can also try the old GLX backend by - forcing it with ``--vo=opengl:backend=x11``, but the vaapi/GLX interop is + forcing it with ``--opengl-backend=x11``, but the vaapi/GLX interop is said to be slower than ``vaapi-copy``. Most video filters will not work with hardware decoding as they are @@ -666,9 +697,31 @@ Video affect this additionally. This can give incorrect results even with completely ordinary video sources. + ``cuda`` is usually safe. Interlaced content can be deinterlaced by + 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`` to not attempt any deinterlacing. + 10bit HEVC is available if the hardware supports it but it will be + rounded down to 8 bits. + + ``cuda-copy`` has the same behaviour as ``cuda`` - including the ability + to deinterlace inside the decoder. However, traditional deinterlacing + filters can be used in this case. + + ``rpi`` always uses the hardware overlay renderer, even with + ``--vo=opengl``. + + ``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.) are either fully safe, or not worse than software - decoding. In particular, ``auto-copy`` will only select safe modes + decoding. + + In particular, ``auto-copy`` will only select safe modes (although potentially slower than other methods). ``--hwdec-preload=<api>`` @@ -703,13 +756,14 @@ Video This option has no effect if ``--video-unscaled`` option is used. -``--video-aspect=<ratio>`` +``--video-aspect=<ratio|no>`` Override video aspect ratio, in case aspect information is incorrect or missing in the file being played. See also ``--no-video-aspect``. - Two values have special meaning: + These values have special meaning: :0: disable aspect ratio handling, pretend the video has square pixels + :no: same as ``0`` :-1: use the video stream or container aspect (default) But note that handling of these special values might change in the future. @@ -718,10 +772,7 @@ Video - ``--video-aspect=4:3`` or ``--video-aspect=1.3333`` - ``--video-aspect=16:9`` or ``--video-aspect=1.7777`` - -``--no-video-aspect`` - Ignore aspect ratio information from video file and assume the video has - square pixels. See also ``--video-aspect``. + - ``--no-video-aspect`` or ``--video-aspect=no`` ``--video-aspect-method=<hybrid|bitstream|container>`` This sets the default video aspect determination method (if the aspect is @@ -840,8 +891,7 @@ Video disable deinterlacing just because the ``--deinterlace`` was not set. ``--field-dominance=<auto|top|bottom>`` - Set first field for interlaced content. Useful for deinterlacers that - double the framerate: ``--vf=yadif=field`` and ``--vo=vdpau:deint``. + Set first field for interlaced content. :auto: (default) If the decoder does not export the appropriate information, it falls back on ``top`` (top field first). @@ -988,21 +1038,40 @@ Audio ``--audio-device=<name>`` 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. + 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. + 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. - The default value for this option is ``auto``, which tries every audio - output in preference order with the default device. + 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``. - Note that many AOs have a ``device`` sub-option, which overrides the - device selection of this option (but not the audio output selection). - Likewise, forcing an AO with ``--ao`` will override the audio output - selection of ``--audio-device`` (but not the device selection). + .. admonition:: Example for ALSA - Currently not implemented for most AOs. + 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=<yes|no>`` + 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=<yes|no>`` If no audio device can be opened, behave as if ``--ao=null`` was given. This @@ -1012,11 +1081,9 @@ Audio ``current-ao`` and ``audio-device-list`` properties to make high-level decisions about how to continue. -``--ao=<driver1[:suboption1[=value]:...],driver2,...[,]>`` - Specify a priority list of audio output drivers to be used. For - interactive use one would normally specify a single one to use, but in - configuration files specifying a list of fallbacks may make sense. See - `AUDIO OUTPUT DRIVERS`_ for details and descriptions of available drivers. +``--ao=<driver>`` + Specify the audio output drivers to be used. See `AUDIO OUTPUT DRIVERS`_ for + details and descriptions of available drivers. ``--af=<filter1[=parameter1:parameter2:...],filter2,...>`` Specify a list of audio filters to apply to the audio stream. See @@ -1084,7 +1151,10 @@ Audio Since mpv 0.18.1, this always controls the internal mixer (aka "softvol"). ``--balance=<value>`` - How much left/right channels contribute to the audio. + How much left/right channels contribute to the audio. (The implementation + of this feature is rather odd. It doesn't change the volumes of each + channel, but instead sets up a pan matrix to mix the left and right + channels.) Deprecated. @@ -1092,12 +1162,10 @@ Audio Audio delay in seconds (positive or negative float value). Positive values delay the audio, and negative values delay the video. -``--no-audio`` - Do not play sound. +``--mute=<yes|no|auto>`` + Set startup audio mute status (default: no). -``--mute=<auto|yes|no>`` - Set startup audio mute status. ``auto`` (default) will not change the mute - status. + ``auto`` is a deprecated possible value that is equivalent to ``no``. See also: ``--volume``. @@ -1372,11 +1440,12 @@ Subtitles 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 ``--ass-style-override``. + overriding them can be controlled with ``--sub-ass-style-override``. - -``--no-sub`` - Do not select any subtitle when the file is loaded. + 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 @@ -1427,7 +1496,7 @@ Subtitles .. note:: This affects ASS subtitles as well, and may lead to incorrect subtitle - rendering. Use with care, or use ``--sub-text-font-size`` instead. + rendering. Use with care, or use ``--sub-font-size`` instead. ``--sub-scale-by-window=<yes|no>`` Whether to scale subtitles with the window size (default: yes). If this is @@ -1448,10 +1517,10 @@ Subtitles scales with the approximate window size, while the other option disables this scaling. - Affects plain text subtitles only (or ASS if ``--ass-style-override`` is + Affects plain text subtitles only (or ASS if ``--sub-ass-style-override`` is set high enough). -``--ass-scale-with-window=<yes|no>`` +``--sub-ass-scale-with-window=<yes|no>`` Like ``--sub-scale-with-window``, but affects subtitles in ASS format only. Like ``--sub-scale``, this can break ASS subtitles. @@ -1468,7 +1537,7 @@ Subtitles .. note:: This affects ASS subtitles as well, and may lead to incorrect subtitle - rendering. Use with care, or use ``--sub-text-margin-y`` instead. + 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 @@ -1480,19 +1549,19 @@ Subtitles `--sub-speed=25/23.976`` plays frame based subtitles which have been loaded assuming a framerate of 23.976 at 25 FPS. -``--ass-force-style=<[Style.]Param=Value[,...]>`` +``--sub-ass-force-style=<[Style.]Param=Value[,...]>`` Override some style or script info parameters. .. admonition:: Examples - - ``--ass-force-style=FontName=Arial,Default.Bold=1`` - - ``--ass-force-style=PlayResY=768`` + - ``--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. -``--ass-hinting=<none|light|normal|native>`` +``--sub-ass-hinting=<none|light|normal|native>`` Set font hinting type. <type> can be: :none: no hinting (default) @@ -1507,10 +1576,10 @@ Subtitles of animations with some badly authored ASS scripts. It is recommended to not use this option, unless really needed. -``--ass-line-spacing=<value>`` +``--sub-ass-line-spacing=<value>`` Set line spacing value for SSA/ASS renderer. -``--ass-shaper=<simple|complex>`` +``--sub-ass-shaper=<simple|complex>`` Set the text layout engine used by libass. :simple: uses Fribidi only, fast, doesn't render some languages correctly @@ -1519,7 +1588,7 @@ Subtitles ``complex`` is the default. If libass hasn't been compiled against HarfBuzz, libass silently reverts to ``simple``. -``--ass-styles=<filename>`` +``--sub-ass-styles=<filename>`` 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. @@ -1528,20 +1597,20 @@ Subtitles Using this option may lead to incorrect subtitle rendering. -``--ass-style-override=<yes|no|force|signfs|strip>`` +``--sub-ass-style-override=<yes|no|force|signfs|strip>`` Control whether user style overrides should be applied. - :yes: Apply all the ``--ass-*`` style override options. Changing the default + :yes: Apply all the ``--sub-ass-*`` style override options. Changing the default for any of these options can lead to incorrect subtitle rendering (default). :signfs: like ``yes``, but apply ``--sub-scale`` only to signs :no: Render subtitles as forced by subtitle scripts. - :force: Try to force the font style as defined by the ``--sub-text-*`` + :force: Try to force the font style as defined by the ``--sub-*`` options. Can break rendering easily. :strip: Radically strip all ASS tags and styles from the subtitle. This is equivalent to the old ``--no-ass`` / ``--no-sub-ass`` options. -``--ass-force-margins`` +``--sub-ass-force-margins`` Enables placing toptitles and subtitles in black borders when they are available, if the subtitles are in the ASS format. @@ -1550,14 +1619,14 @@ Subtitles ``--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 - ``--ass-style-override`` is set high enough). + ``--sub-ass-style-override`` is set high enough). Default: yes. - Renamed from ``--ass-use-margins``. To place ASS subtitles in the borders - too (like the old option did), also add ``--ass-force-margins``. + 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``. -``--ass-vsfilter-aspect-compat=<yes|no>`` +``--sub-ass-vsfilter-aspect-compat=<yes|no>`` 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. @@ -1574,7 +1643,7 @@ Subtitles Enabled by default. -``--ass-vsfilter-blur-compat=<yes|no>`` +``--sub-ass-vsfilter-blur-compat=<yes|no>`` 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. @@ -1583,7 +1652,7 @@ Subtitles offset scale factor, not what the video filter chain or the video output use. -``--ass-vsfilter-color-compat=<basic|full|force-601|no>`` +``--sub-ass-vsfilter-color-compat=<basic|full|force-601|no>`` 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 @@ -1605,7 +1674,7 @@ Subtitles 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 ``--ass-style-override`` + a subtitle script with another video file. The ``--sub-ass-style-override`` option doesn't affect how this option is interpreted. ``--stretch-dvd-subs=<yes|no>`` @@ -1638,14 +1707,14 @@ Subtitles .. note:: - This has been deprecated by ``--ass-style-override=strip``. You also + This has been deprecated by ``--sub-ass-style-override=strip``. You also may need ``--embeddedfonts=no`` to get the same behavior. Also, - using ``--ass-style-override=force`` should give better results + using ``--sub-ass-style-override=force`` 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-text-`` options instead. + as specified by the ``--sub-`` options instead. .. note:: @@ -1792,6 +1861,136 @@ Subtitles 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=<name>`` + Specify font to use for subtitles that do not themselves + specify a particular font. The default is ``sans-serif``. + + .. admonition:: Examples + + - ``--sub-font='Bitstream Vera Sans'`` + - ``--sub-font='MS Comic Sans'`` + + .. 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=<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=<color>`` + See ``--sub-color``. Color used for sub text background. + +``--sub-blur=<0..20.0>`` + Gaussian blur factor. 0 means no blur applied (default). + +``--sub-bold=<yes|no>`` + Format text on bold. + +``--sub-italic=<yes|no>`` + Format text on italic. + +``--sub-border-color=<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>`` + 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=<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. + + .. admonition:: 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``. + + .. admonition:: Examples + + - ``--sub-color='#FF0000'`` set sub to opaque red + - ``--sub-color='#C0808080'`` set sub to 50% gray with 75% alpha + +``--sub-margin-x=<size>`` + 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=<size>`` + 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=<left|center|right>`` + 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=<top|center|bottom>`` + Vertical position (default: ``bottom``). + Details see ``--sub-align-x``. + +``--sub-shadow-color=<color>`` + See ``--sub-color``. Color used for sub text shadow. + +``--sub-shadow-offset=<size>`` + 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=<size>`` + 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. + Window ------ @@ -1913,7 +2112,7 @@ Window ``--taskbar-progress``, ``--no-taskbar-progress`` (Windows only) Enable/disable playback progress rendering in taskbar (Windows 7 and above). - + Enabled by default. ``--ontop`` @@ -2252,10 +2451,6 @@ Disc Devices ``mpv bd:// --bluray-device=/path/to/bd/`` -``--bluray-angle=<ID>`` - Some Blu-ray discs contain scenes that can be viewed from multiple angles. - This option tells mpv which angle to use (default: 1). - ``--cdda-...`` These options can be used to tune the CD Audio reading feature of mpv. @@ -2689,29 +2884,16 @@ OSD ``--osd-duration=<time>`` Set the duration of the OSD messages in ms (default: 1000). -``--osd-font=<name>``, ``--sub-text-font=<name>`` - Specify font to use for OSD and for subtitles that do not themselves - specify a particular font. The default is ``sans-serif``. +``--osd-font=<name>`` + Specify font to use for OSD. The default is ``sans-serif``. .. admonition:: Examples - ``--osd-font='Bitstream Vera Sans'`` - ``--osd-font='MS Comic Sans'`` - .. note:: - - The ``--sub-text-font`` option (and most other ``--sub-text-`` - 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. - -``--osd-font-size=<size>``, ``--sub-text-font-size=<size>`` - Specify the OSD/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. +``--osd-font-size=<size>`` + Specify the OSD font size. See ``--sub-font-size`` for details. Default: 55. @@ -2768,60 +2950,36 @@ OSD ``--osd-bar-h=<0.1-50>`` Height of the OSD bar, in percentage of the screen height (default: 3.125). -``--osd-back-color=<color>``, ``--sub-text-back-color=<color>`` - See ``--osd-color``. Color used for OSD/sub text background. +``--osd-back-color=<color>`` + See ``--osd-color``. Color used for OSD text background. -``--osd-blur=<0..20.0>``, ``--sub-text-blur=<0..20.0>`` +``--osd-blur=<0..20.0>`` Gaussian blur factor. 0 means no blur applied (default). -``--osd-bold=<yes|no>``, ``--sub-text-bold=<yes|no>`` +``--osd-bold=<yes|no>`` Format text on bold. -``--osd-italic=<yes|no>``, ``--sub-text-italic=<yes|no>`` +``--osd-italic=<yes|no>`` Format text on italic. -``--osd-border-color=<color>``, ``--sub-text-border-color=<color>`` - See ``--osd-color``. Color used for the OSD/sub font border. +``--osd-border-color=<color>`` + See ``--osd-color``. Color used for the OSD font border. .. note:: - ignored when ``--osd-back-color``/``--sub-text-back-color`` is + ignored when ``--osd-back-color`` is specified (or more exactly: when that option is not set to completely transparent). -``--osd-border-size=<size>``, ``--sub-text-border-size=<size>`` - Size of the OSD/sub font border in scaled pixels (see ``--osd-font-size`` +``--osd-border-size=<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=<color>``, ``--sub-text-color=<color>`` - Specify the color used for OSD/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 OSD to gray, and the form - ``gray/a`` lets you specify alpha additionally. - - .. admonition:: Examples - - - ``--osd-color=1.0/0.0/0.0`` set OSD to opaque red - - ``--osd-color=1.0/0.0/0.0/0.75`` set OSD to opaque red with 75% alpha - - ``--osd-color=0.5/0.75`` set OSD 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``. - - .. admonition:: Examples - - - ``--osd-color='#FF0000'`` set OSD to opaque red - - ``--osd-color='#C0808080'`` set OSD to 50% gray with 75% alpha +``--osd-color=<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 @@ -2835,34 +2993,29 @@ OSD :2: enabled + current time visible by default :3: enabled + ``--osd-status-msg`` (current time and status by default) -``--osd-margin-x=<size>, --sub-text-margin-x=<size>`` - Left and right screen margin for the OSD/subs in scaled pixels (see - ``--osd-font-size`` for details). +``--osd-margin-x=<size>`` + 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=<size>, --sub-text-margin-y=<size>`` - Top and bottom screen margin for the OSD/subs in scaled pixels (see - ``--osd-font-size`` for details). +``--osd-margin-y=<size>`` + 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. This is also used - for unstyled text subtitles. If you just want to raise the vertical - subtitle position, use ``--sub-pos``. + This option specifies the vertical margins of the OSD. Default: 22. -``--osd-align-x=<left|center|right>``, ``--sub-text-align-x=...`` - Control to which corner of the screen OSD or text subtitles should be - aligned to (default: ``center`` for subs, ``left`` for OSD). - - Never applied to ASS subtitles, except in ``--no-sub-ass`` mode. Likewise, - this does not apply to image subtitles. +``--osd-align-x=<left|center|right>`` + Control to which corner of the screen OSD should be + aligned to (default: ``left``). -``--osd-align-y=<top|center|bottom>`` ``--sub-text-align-y=...`` - Vertical position (default: ``bottom`` for subs, ``top`` for OSD). +``--osd-align-y=<top|center|bottom>`` + Vertical position (default: ``top``). Details see ``--osd-align-x``. ``--osd-scale=<factor>`` @@ -2874,22 +3027,33 @@ OSD are always in actual pixels. The effect is that changing the window size won't change the OSD font size. -``--osd-shadow-color=<color>, --sub-text-shadow-color=<color>`` - See ``--osd-color``. Color used for OSD/sub text shadow. +``--osd-shadow-color=<color>`` + See ``--sub-color``. Color used for OSD shadow. -``--osd-shadow-offset=<size>, --sub-text-shadow-offset=<size>`` - Displacement of the OSD/sub text shadow in scaled pixels (see - ``--osd-font-size`` for details). A value of 0 disables shadows. +``--osd-shadow-offset=<size>`` + Displacement of the OSD shadow in scaled pixels (see + ``--sub-font-size`` for details). A value of 0 disables shadows. Default: 0. -``--osd-spacing=<size>, --sub-text-spacing=<size>`` - Horizontal OSD/sub font spacing in scaled pixels (see ``--osd-font-size`` +``--osd-spacing=<size>`` + 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=<yes|no>`` + 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 ---------- @@ -3136,11 +3300,15 @@ Terminal Only show warnings or worse, and let the ao_alsa output show errors only. -``--term-osd, --no-term-osd``, ``--term-osd=force`` - Display OSD messages on the console when no video output is available. - Enabled by default. +``--term-osd=<auto|no|force>`` + Control whether OSD messages are shown on the console when no video output + is available (default: auto). + + :auto: use terminal OSD if no video output active + :no: disable terminal OSD + :force: use terminal OSD even if video output active - ``force`` enables terminal OSD even if a video window is created. + The ``auto`` mode also enables terminal OSD if ``--video-osd=no`` was set. ``--term-osd-bar``, ``--no-term-osd-bar`` Enable printing a progress bar under the |