diff options
Diffstat (limited to 'DOCS/man/options.rst')
| -rw-r--r-- | DOCS/man/options.rst | 219 |
1 files changed, 166 insertions, 53 deletions
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index eab9f8fefd..af9a3b913d 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -640,8 +640,8 @@ Video ``--opengl-backend=dxinterop`` (Windows only) :dxva2-copy: copies video back to system RAM (Windows only) :d3d11va: requires ``--vo=opengl`` with ``--opengl-backend=angle`` - (Windows only) - :d3d11va-copy: copies video back to system RAM (Windows only) + (Windows 8+ only) + :d3d11va-copy: copies video back to system RAM (Windows 8+ only) :mediacodec: copies video back to system RAM (Android only) :rpi: requires ``--vo=opengl`` (Raspberry Pi only - default if available) :rpi-copy: copies video back to system RAM (Raspberry Pi only) @@ -669,6 +669,14 @@ Video forcing it with ``--opengl-backend=x11``, but the vaapi/GLX interop is said to be slower than ``vaapi-copy``. + 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 ``opengl`` + vo is not being used or filters are required. + 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. @@ -719,18 +727,6 @@ 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. - 10 and 12bit HEVC is available if the hardware supports it and a - sufficiently new driver (> 375.xx) is used. - - ``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``. @@ -746,12 +742,12 @@ Video In particular, ``auto-copy`` will only select safe modes (although potentially slower than other methods). -``--hwdec-preload=<api>`` +``--opengl-hwdec-interop=<name>`` This is useful for the ``opengl`` and ``opengl-cb`` VOs for creating the hardware decoding OpenGL interop context, but without actually enabling hardware decoding itself (like ``--hwdec`` does). - If set to ``no`` (default), the ``--hwdec`` option is used. + If set to an empty string (default), the ``--hwdec`` option is used. For ``opengl``, if set, do not create the interop context on demand, but when the VO is created. @@ -762,6 +758,19 @@ Video to temporarily set the ``hwdec`` option just during OpenGL context initialization with ``mpv_opengl_cb_init_gl()``. + See ``--opengl-hwdec-interop=help`` for accepted values. This lists the + interop backend, with the ``--hwdec`` alias after it in ``[...]``. Consider + all values except the proper interop backend name, ``auto``, and ``no`` as + silently deprecated and subject to change. Also, if you use this in + application code (e.g. via libmpv), any value other than ``auto`` and ``no`` + should be avoided, as backends can change. + + Currently the option sets a single value. It is possible that the option + type changes to a list in the future. + + The old alias ``--hwdec-preload`` has different behavior if the option value + is ``no``. + ``--videotoolbox-format=<name>`` Set the internal pixel format used by ``--hwdec=videotoolbox`` on OSX. The choice of the format can influence performance considerably. On the other @@ -1132,41 +1141,31 @@ Audio multichannel PCM, and mpv supports lossless DTS-HD decoding via FFmpeg's new DCA decoder (based on libdcadec). -``--ad=<[+|-]family1:(*|decoder1),[+|-]family2:(*|decoder2),...[-]>`` +``--ad=<decoder1,decoder2,...[-]>`` 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. - Specifying family names is deprecated. Entries like ``family:*`` prioritize - all decoders of the given family. - ``-`` 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. - ``-`` in front of an entry disables selection of the decoder. This is - deprecated. - .. admonition:: Examples ``--ad=mp3float`` Prefer the FFmpeg/Libav ``mp3float`` decoder over all other MP3 decoders. - ``--ad=lavc:mp3float`` - Prefer the FFmpeg/Libav ``mp3float`` decoder over all other MP3 - decoders. (Using deprecated family syntax.) - ``--ad=help`` List all available decoders. .. admonition:: Warning Enabling compressed audio passthrough (AC3 and DTS via SPDIF/HDMI) with - this option is deprecated. Use ``--audio-spdif`` instead. + this option is not possible. Use ``--audio-spdif`` instead. ``--volume=<value>`` Set the startup volume. 0 means silence, 100 means no volume reduction or @@ -1727,6 +1726,13 @@ Subtitles Disabled by default. +``--image-subs-video-resolution=<yes|no>`` + 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). @@ -1781,8 +1787,9 @@ Subtitles 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. The old syntax is still emulated to some - degree. + This option changed in mpv 0.23.0. Support for the old syntax was fully + removed in mpv 0.24.0. + ``--sub-fix-timing``, ``--no-sub-fix-timing`` By default, subtitle timing is adjusted to remove minor gaps or overlaps @@ -1965,6 +1972,18 @@ Subtitles Vertical position (default: ``bottom``). Details see ``--sub-align-x``. +``--sub-justify=<auto|left|center|right>`` + 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=<yes|no>`` + Applies justification as defined by ``--sub-justify`` on ASS subtitles + if ``--sub-ass-style-override`` is not set to ``no``. + Default: ``no``. + ``--sub-shadow-color=<color>`` See ``--sub-color``. Color used for sub text shadow. @@ -2101,6 +2120,9 @@ Window 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. @@ -2339,7 +2361,7 @@ Window - ``--monitoraspect=16:9`` or ``--monitoraspect=1.7777`` ``--hidpi-window-scale``, ``--no-hidpi-window-scale`` - (OS X only) + (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 @@ -2724,6 +2746,27 @@ Demuxer (This value tends to be fuzzy, because many file formats don't store linear timestamps.) +``--prefetch-playlist=<yes|no>`` + 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=<yes|no>`` 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 @@ -4288,16 +4331,70 @@ The following video options are currently all specific to ``--vo=opengl`` and Windows only. -``--opengl-dcomposition=<yes|no>`` - Allows DirectComposition when using the ANGLE backend (default: yes). - DirectComposition implies flip-model presentation, which can improve - rendering efficiency on Windows 8+ by avoiding a copy of the video frame. - mpv uses it by default where possible, but it can cause poor behaviour with - some drivers, such as a black screen or graphical corruption when leaving - full-screen mode. Use "no" to disable it. +``--angle-d3d11-feature-level=<11_0|10_1|10_0|9_3>`` + Selects a specific feature level when using the ANGLE backend with D3D11. + By default, the highest available feature level is used. This option can be + used to select a lower feature level, which is mainly useful for debugging. + Note that OpenGL ES 3.0 is only supported at feature level 10_1 or higher. + Most extended OpenGL features will not work at lower feature levels + (similar to ``--opengl-dumb-mode``). Windows with ANGLE only. +``--angle-d3d11-warp=<yes|no|auto>`` + Use WARP (Windows Advanced Rasterization Platform) when using the ANGLE + backend with D3D11 (default: auto). This is a high performance software + renderer. By default, it is used when the Direct3D hardware does not + support Direct3D 11 feature level 9_3. While the extended OpenGL features + will work with WARP, they can be very slow. + + Windows with ANGLE only. + +``--angle-egl-windowing=<yes|no|auto>`` + Use ANGLE's built in EGL windowing functions to create a swap chain + (default: auto). If this is set to ``no`` and the D3D11 renderer is in use, + ANGLE's built in swap chain will not be used and a custom swap chain that + is optimized for video rendering will be created instead. If set to + ``auto``, a custom swap chain will be used for D3D11 and the built in swap + chain will be used for D3D9. This option is mainly for debugging purposes, + in case the custom swap chain has poor performance or does not work. + + If set to ``yes``, the ``--angle-max-frame-latency`` and + ``--angle-swapchain-length`` options will have no effect. + + Windows with ANGLE only. + +``--angle-max-frame-latency=<1-16>`` + Sets the maximum number of frames that the system is allowed to queue for + rendering with the ANGLE backend (default: 3). Lower values should make + VSync timing more accurate, but a value of ``1`` requires powerful + hardware, since the CPU will not be able to "render ahead" of the GPU. + + Windows with ANGLE only. + +``--angle-renderer=<d3d9|d3d11|auto>`` + Forces a specific renderer when using the ANGLE backend (default: auto). In + auto mode this will pick D3D11 for systems that support Direct3D 11 feature + level 9_3 or higher, and D3D9 otherwise. This option is mainly for + debugging purposes. Normally there is no reason to force a specific + renderer, though ``--angle-renderer=d3d9`` may give slightly better + performance on old hardware. Note that the D3D9 renderer only supports + OpenGL ES 2.0, so most extended OpenGL features will not work if this + renderer is selected (similar to ``--opengl-dumb-mode``). + + Windows with ANGLE only. + +``--angle-swapchain-length=<2-16>`` + Sets the number of buffers in the D3D11 presentation queue when using the + ANGLE backend (default: 6). At least 2 are required, since one is the back + buffer that mpv renders to and the other is the front buffer that is + presented by the DWM. Additional buffers can improve performance, because + for example, mpv will not have to wait on the DWM to release the front + buffer before rendering a new frame to it. For this reason, Microsoft + recommends at least 4. + + Windows 8+ with ANGLE only. + ``--opengl-sw`` Continue even if a software renderer is detected. @@ -4322,6 +4419,9 @@ The following video options are currently all specific to ``--vo=opengl`` and work. x11 X11/GLX + x11probe + For internal autoprobing, equivalent to ``x11`` otherwise. Don't use + directly, it could be removed without warning as autoprobing is changed. wayland Wayland/EGL drm @@ -4561,6 +4661,7 @@ The following video options are currently all specific to ``--vo=opengl`` and unavailable, it silently falls back on a normal framebuffer. Note that if you set the ``--opengl-fbo-format`` option to a non-default value, a format with alpha must be specified, or this won't work. + This does not work on X11 with EGL and Mesa (freedesktop bug 67676). no Ignore alpha component. @@ -4716,21 +4817,10 @@ Miscellaneous Input file type for ``mf://`` (available: jpeg, png, tga, sgi). By default, this is guessed from the file extension. -``--stream-capture=<filename>`` - Allows capturing the primary stream (not additional audio tracks or other - kind of streams) into the given file. Capturing can also be started and - stopped by changing the filename with the ``stream-capture`` property. - Generally this will not produce usable results for anything else than MPEG - or raw streams, unless capturing includes the file headers and is not - interrupted. Note that, due to cache latencies, captured data may begin and - end somewhat delayed compared to what you see displayed. - - The destination file is always appended. (Before mpv 0.8.0, the file was - overwritten.) - -``--stream-dump=<filename>`` - Same as ``--stream-capture``, but do not start playback. Instead, the entire - file is dumped. +``--stream-dump=<destination-filename>`` + Instead of playing a file, read its byte stream and write it to the given + destination file. The destination is overwritten. Can be useful to test + network-related behavior. ``--stream-lavf-o=opt1=value1,opt2=value2,...`` Set AVOptions on streams opened with libavformat. Unknown or misspelled @@ -4773,6 +4863,29 @@ Miscellaneous This does not affect playlist expansion, redirection, or other loading of referenced files like with ordered chapters. +``--record-file=<file>`` + Record the current stream to the given target file. The target file will + always be overwritten without asking. + + This remuxes the source stream without reencoding, which makes this a + highly fragile and experimental feature. It's entirely possible that this + writes files which are broken, not standards compliant, not playable with + all players (including mpv), or incomplete. + + The target file format is determined by the file extension of the target + filename. It is recommended to use the same target container as the source + container if possible, and preferring Matroska as fallback. + + Seeking during stream recording, or enabling/disabling stream recording + during playback, can cut off data, or produce "holes" in the output file. + These are technical restrictions. In particular, video data or subtitles + which were read ahead can produce such holes, which might cause playback + problems with various players (including mpv). + + The behavior of this option might changed in the future, such as changing + it to a template (similar to ``--screenshot-template``), being renamed, + removed, or anything else, until it is declared semi-stable. + ``--lavfi-complex=<string>`` Set a "complex" libavfilter filter, which means a single filter graph can take input from multiple source audio and video tracks. The graph can result |