diff options
Diffstat (limited to 'DOCS')
-rw-r--r-- | DOCS/edl-mpv.rst | 5 | ||||
-rw-r--r-- | DOCS/interface-changes.rst | 19 | ||||
-rw-r--r-- | DOCS/man/af.rst | 10 | ||||
-rw-r--r-- | DOCS/man/input.rst | 46 | ||||
-rw-r--r-- | DOCS/man/mpv.rst | 43 | ||||
-rw-r--r-- | DOCS/man/options.rst | 95 | ||||
-rw-r--r-- | DOCS/man/osc.rst | 25 | ||||
-rw-r--r-- | DOCS/man/vf.rst | 42 | ||||
-rw-r--r-- | DOCS/man/vo.rst | 28 |
9 files changed, 249 insertions, 64 deletions
diff --git a/DOCS/edl-mpv.rst b/DOCS/edl-mpv.rst index b83706cf79..b0f7238307 100644 --- a/DOCS/edl-mpv.rst +++ b/DOCS/edl-mpv.rst @@ -31,9 +31,8 @@ estimated remaining duration of the source file is used. Note:: - mpv can't use ordered chapter files in EDL entries. Usage of relative or - absolute paths as well as any protocol prefixes is prevented for security - reasons. + Usage of relative or absolute paths as well as any protocol prefixes may be + prevented for security reasons. Syntax of mpv EDL files diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst index 11abdc2475..4217de86fc 100644 --- a/DOCS/interface-changes.rst +++ b/DOCS/interface-changes.rst @@ -1,7 +1,7 @@ Introduction ============ -mpv provides access to its internal via the following means: +mpv provides access to its internals via the following means: - options - commands @@ -19,6 +19,23 @@ Interface changes :: + --- mpv 0.16.0 --- + - change --audio-channels default to stereo (use --audio-channels=auto to + get the old default) + - add --audio-normalize-downmix + - change the default downmix behavior (--audio-normalize-downmix=yes to get + the old default) + - VO opengl custom shaders must now use "sample_pixel" as function name, + instead of "sample" + - change VO opengl scaler-resizes-only default to enabled + - add VO opengl "interpolation-threshold" suboption (introduces new default + behavior, which can change e.g. ``--video-sync=display-vdrop`` to the + worse, but is usually what you want) + - make "volume" and "mute" properties changeable even if no audio output is + active (this gives not-ideal behavior if --softvol=no is used) + - add "volume-max" and "mixer-active" properties + - ignore --input-cursor option for events injected by input commands like + "mouse", "keydown", etc. --- mpv 0.15.0 --- - change "yadif" video filter defaults --- mpv 0.14.0 --- diff --git a/DOCS/man/af.rst b/DOCS/man/af.rst index ec6ce3f6c3..be90f09b62 100644 --- a/DOCS/man/af.rst +++ b/DOCS/man/af.rst @@ -63,13 +63,9 @@ Available filters are: (If you just want to set defaults for this filter that will be used even by automatically inserted lavrresample instances, you should prefer setting them with ``--af-defaults=lavrresample:...``.) - ``normalize=<yes|no>`` - Whether to normalize when remixing channel layouts (default: yes). This - is e.g. applied when downmixing surround audio to stereo. The advantage - is that this guarantees that no clipping can happen. Unfortunately, - this can also lead to too low volume levels. Whether you enable or - disable this is essentially a matter of taste, but the default uses - the safer choice. + ``normalize=<yes|no|auto>`` + Whether to normalize when remixing channel layouts (default: auto). + ``auto`` uses the value set by ``--audio-normalize-downmix``. ``o=<string>`` Set AVOptions on the SwrContext or AVAudioResampleContext. These should be documented by FFmpeg or Libav. diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index ed523b2135..11a8f0021f 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -694,6 +694,18 @@ Input Commands that are Possibly Subject to Change field is of type MPV_FORMAT_BYTE_ARRAY with the actual image data. The image is freed as soon as the result node is freed. +``vf-command "<label>" "<cmd>" "<args>"`` + Send a command to the filter with the given ``<label>``. Use ``all`` to send + it to all filters at once. The command and argument string is filter + specific. Currently, this only works with the ``lavfi`` filter - see + the libavfilter documentation for which commands a filter supports. + + Note that the ``<label>`` is a mpv filter label, not a libavfilter filter + name. + +``af-command "<label>" "<cmd>" "<args>"`` + Same as ``vf-command``, but for audio filters. + Undocumented commands: ``tv-last-channel`` (TV/DVB only), ``ao-reload`` (experimental/internal). @@ -753,6 +765,17 @@ The following hooks are currently defined: ``file-local-options/<option name>``. The player will wait until all hooks are run. +``on_preloaded`` + Called after a file has been opened, and before tracks are selected and + decoders are created. This has some usefulness if an API users wants + to select tracks manually, based on the set of available tracks. It's + also useful to initialize ``--lavfi-complex`` in a specific way by API, + without having to "probe" the available streams at first. + + Note that this does not yet apply default track selection. Which operations + exactly can be done and not be done, and what information is available and + what is not yet available yet, is all subject to change. + ``on_unload`` Run before closing a file, and before actually uninitializing everything. It's not possible to resume playback in this state. @@ -1212,11 +1235,30 @@ Property list ``hr-seek`` (RW) See ``--hr-seek``. +``mixer-active`` + Return ``yes`` if the audio mixer is active, ``no`` otherwise. This has + implications for ``--softvol=no`` mode: if the mixer is active, changing + ``volume`` doesn't actually change anything on the system mixer. If the + ``--volume`` or ``--mute`` option are used, these might not be applied + property until the mixer becomes active either. (The options, if set, will + just overwrite the mixer state at audio initialization.) + + While the behavior with ``mixer-active==yes`` is relatively well-defined, + the ``no`` case will provide possibly wrong or insignificant values. + + Note that an active mixer does not necessarily imply active audio output, + although this is implied in the current implementation. + ``volume`` (RW) - Current volume (see ``--volume`` for details). + Current volume (see ``--volume`` for details). Also see ``mixer-active`` + property. + +``volume-max`` + Current maximum value the volume property can be set to. (This may depend + on the ``--softvol-max`` option.) ``mute`` (RW) - Current mute status (``yes``/``no``). + Current mute status (``yes``/``no``). Also see ``mixer-active`` property. ``audio-delay`` (RW) See ``--audio-delay``. diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst index 84c5247d2f..6716c382f2 100644 --- a/DOCS/man/mpv.rst +++ b/DOCS/man/mpv.rst @@ -37,6 +37,10 @@ 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 ---------------- @@ -381,6 +385,45 @@ 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. + +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:: + + 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``). + + 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 =================== diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index e5fe542712..ec71dd762b 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -394,8 +394,7 @@ Program Behavior ``--merge-files`` Pretend that all files passed to mpv are concatenated into a single, big - file. This uses timeline/EDL support internally. Note that this won't work - for ordered chapter files. + file. This uses timeline/EDL support internally. ``--no-resume-playback`` Do not restore playback position from the ``watch_later`` configuration @@ -539,7 +538,7 @@ Video 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 ``D:`` field. If the decoder is too slow, + 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. @@ -560,9 +559,13 @@ Video ``--display-fps=<fps>`` Set the display FPS used with the ``--video-sync=display-*`` modes. By - default, a detected value is used (X11 only, not correct on multi-monitor - systems). Keep in mind that setting an incorrect value (even if slightly - incorrect) can ruin video playback. + 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=<api>`` Specify the hardware video decoding API that should be used if possible. @@ -975,7 +978,7 @@ Audio There is not much reason to use this. HDMI supports uncompressed multichannel PCM, and mpv supports lossless DTS-HD decoding via - FFmpeg's libdcadec wrapper. + FFmpeg's new DCA decoder (based on libdcadec). ``--ad=<[+|-]family1:(*|decoder1),[+|-]family2:(*|decoder2),...[-]>`` Specify a priority list of audio decoders to be used, according to their @@ -1089,8 +1092,8 @@ Audio This and enabling passthrough via ``--ad`` are deprecated in favor of using ``--audio-spdif=dts-hd``. -``--audio-channels=<number|layout>`` - Request a channel layout for audio output (default: auto). This will ask +``--audio-channels=<auto|number|layout>`` + Request a channel layout for audio output (default: stereo). This will ask the AO to open a device with the given channel layout. It's up to the AO to accept this layout, or to pick a fallback or to error out if the requested layout is not supported. @@ -1103,9 +1106,10 @@ Audio lists speaker names, which can be used to express arbitrary channel layouts (e.g. ``fl-fr-lfe`` is 2.1). - The default is ``--audio-channels=auto``, which tries to play audio using - the input file's channel layout. (Or more precisely, the output of the - audio filter chain.) (``empty`` is an accepted obsolete alias for ``auto``.) + ``--audio-channels=auto`` tries to play audio using the input file's + channel layout. There is no guarantee that the audio API handles this + correctly. See the HDMI warning below. + (``empty`` is an accepted obsolete alias for ``auto``.) This will also request the channel layout from the decoder. If the decoder does not support the layout, it will fall back to its native channel layout. @@ -1124,6 +1128,16 @@ Audio channel layout, random things can happen, such as dropping the additional channels, or adding noise. +``--audio-normalize-downmix=<yes|no>`` + Enable/disable normalization if surround audio is downmixed to stereo + (default: no). If this is disabled, downmix can cause clipping. If it's + enabled, the output might be too silent. It depends on the source audio. + + Technically, this changes the ``normalize`` suboption of the + ``lavrresample`` audio filter, which performs the downmixing. + + If downmix happens outside of mpv for some reason, this has no effect. + ``--audio-display=<no|attachment>`` Setting this option to ``attachment`` (default) will display image attachments (e.g. album cover art) when playing audio files. It will @@ -1381,7 +1395,7 @@ Subtitles .. admonition:: Warning Enabling hinting can lead to mispositioned text (in situations it's - supposed to match up with video background), or reduce the smoothness + 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. @@ -3538,3 +3552,58 @@ Miscellaneous Force the contents of the ``media-title`` property to this value. Useful for scripts which want to set a title, without overriding the user's setting in ``--title``. + +``--external-file=<filename>`` + Add all tracks from the given file. Unlike ``--sub-file`` and + ``--audio-file``, this includes all tracks, and does not cause default + stream selection over the "proper" file. + +``--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 + in a single audio or video output (or both). + + Currently, the filter graph labels are used to select the participating + input tracks and audio/video output. The following rules apply: + + - A label of the form ``aidN`` selects audio track N as input (e.g. + ``aid1``). + - A label of the form ``vidN`` selects video track N as input. + - A label named ``ao`` will be connected to the audio input. + - A label named ``vo`` will be connected to the video output. + + Each label can be used only once. If you want to use e.g. an audio stream + for multiple filters, you need to use the ``asplit`` filter. Multiple + video or audio outputs are not possible, but you can use filters to merge + them into one. + + The complex filter can not be changed yet during playback. It's also not + possible to change the tracks connected to the filter at runtime. Other + tracks, as long as they're not connected to the filter, and the + corresponding output is not connected to the filter, can still be freely + changed. + + Note that the normal filter chains (``--af``, ``--vf``) are applied between + the complex graphs (e.g. ``ao`` label) and the actual output. + + .. admonition:: Examples + + - ``--lavfi-complex='[aid1] asplit [ao] [t] ; [t] aphasemeter [vo]'`` + Play audio track 1, and visualize it as video using the ``aphasemeter`` + filter. + - ``--lavfi-complex='[aid1] [aid2] amix [ao]'`` + Play audio track 1 and 2 at the same time. + - ``--lavfi-complex='[vid1] [vid2] vstack [vo]'`` + Stack video track 1 and 2 and play them at the same time. Note that + both tracks need to have the same width, or filter initialization + will fail (you can add ``scale`` filters before the ``vstack`` filter + to fix the size). + - ``--lavfi-complex='[aid1] asplit [ao] [t] ; [t] aphasemeter [t2] ; [vid1] [t2] overlay [vo]'`` + Play audio track 1, and overlay its visualization over video track 1. + - ``--lavfi-complex='[aid1] asplit [t1] [ao] ; [t1] showvolume [t2] ; [vid1] [t2] overlay [vo]'`` + Play audio track 1, and overlay the measured volume for each speaker + over video track 1. + + See the FFmpeg libavfilter documentation for details on the filter. + + diff --git a/DOCS/man/osc.rst b/DOCS/man/osc.rst index f4f8d66496..587b8104d2 100644 --- a/DOCS/man/osc.rst +++ b/DOCS/man/osc.rst @@ -130,7 +130,7 @@ these keys. In case of collision, the function needs to be bound to a different key. See the `Script Commands`_ section. ============= ================================================ -del Hide the OSC permanently until mpv is restarted. +del Cycles visibility between never / auto (mouse-move) / always ============= ================================================ Configuration @@ -206,8 +206,8 @@ Configurable Options ``hidetimeout`` | Default: 500 - | Duration in ms until the OSC hides if no mouse movement, negative value - disables auto-hide + | Duration in ms until the OSC hides if no mouse movement, must not be + negative ``fadeduration`` | Default: 200 @@ -243,28 +243,29 @@ Configurable Options | Default: no | Display timecodes with milliseconds +``visibility`` + | Default: auto (auto hide/show on mouse move) + | Also supports ``never`` and ``always`` + Script Commands ~~~~~~~~~~~~~~~ The OSC script listens to certain script commands. These commands can bound in ``input.conf``, or sent by other scripts. -``enable-osc`` - Undoes ``disable-osc`` or the effect of the ``del`` key. - -``disable-osc`` - Hide the OSC permanently. This is also what the ``del`` key does. - ``osc-message`` Show a message on screen using the OSC. First argument is the message, second the duration in seconds. +``osc-visibility`` + Controls visibility mode ``never`` / ``auto`` (on mouse move) / ``always`` + and also ``cycle`` to cycle between the modes Example You could put this into ``input.conf`` to hide the OSC with the ``a`` key and -to unhide it with ``b``:: +to set auto mode (the default) with ``b``:: - a script_message disable-osc - b script_message enable-osc + a script_message osc-visibility never + b script_message osc-visibility auto diff --git a/DOCS/man/vf.rst b/DOCS/man/vf.rst index ff3f539416..faca4114a9 100644 --- a/DOCS/man/vf.rst +++ b/DOCS/man/vf.rst @@ -289,27 +289,27 @@ Available filters are: :prophoto: ProPhoto RGB (ROMM) :cie1931: CIE 1931 RGB - ``<gamma>`` - Gamma function the source file was encoded with. Normally this should be set - in the file header, but when playing broken or mistagged files this can be - used to override the setting. - - This option only affects video output drivers that perform color management. - - If this option is set to ``auto`` (which is the default), the gamma will - be set to BT.1886 for YCbCr content, sRGB for RGB content and Linear for - XYZ content. - - Available gamma functions are: - - :auto: automatic selection (default) - :bt.1886: ITU-R BT.1886 (approximation of BT.601/BT.709/BT.2020 curve) - :srgb: IEC 61966-2-4 (sRGB) - :linear: Linear light - :gamma1.8: Pure power curve (gamma 1.8) - :gamma2.2: Pure power curve (gamma 2.2) - :gamma2.8: Pure power curve (gamma 2.8) - :prophoto: ProPhoto RGB (ROMM) curve + ``<gamma>`` + Gamma function the source file was encoded with. Normally this should be set + in the file header, but when playing broken or mistagged files this can be + used to override the setting. + + This option only affects video output drivers that perform color management. + + If this option is set to ``auto`` (which is the default), the gamma will + be set to BT.1886 for YCbCr content, sRGB for RGB content and Linear for + XYZ content. + + Available gamma functions are: + + :auto: automatic selection (default) + :bt.1886: ITU-R BT.1886 (approximation of BT.601/BT.709/BT.2020 curve) + :srgb: IEC 61966-2-4 (sRGB) + :linear: Linear light + :gamma1.8: Pure power curve (gamma 1.8) + :gamma2.2: Pure power curve (gamma 2.2) + :gamma2.8: Pure power curve (gamma 2.8) + :prophoto: ProPhoto RGB (ROMM) curve ``<stereo-in>`` Set the stereo mode the video is assumed to be encoded in. Takes the diff --git a/DOCS/man/vo.rst b/DOCS/man/vo.rst index bc0dd9fd12..58bd91cd55 100644 --- a/DOCS/man/vo.rst +++ b/DOCS/man/vo.rst @@ -444,7 +444,7 @@ Available video output drivers are: Disable the scaler if the video image is not resized. In that case, ``bilinear`` is used instead whatever is set with ``scale``. Bilinear will reproduce the source image perfectly if no scaling is performed. - Note that this option never affects ``cscale``. + Enabled by default. Note that this option never affects ``cscale``. ``pbo`` Enable use of PBOs. On some drivers this can be faster, especially if @@ -549,6 +549,20 @@ Available video output drivers are: manifest themselves as short flashes or fringes of black, mostly around moving edges) in exchange for potentially adding more blur. + ``interpolation-threshold=<0..1,-1>`` + Threshold below which frame ratio interpolation gets disabled (default: + ``0.0001``). This is calculated as ``abs(disphz/vfps - 1) < threshold``, + where ``vfps`` is the speed-adjusted display FPS, and ``disphz`` the + display refresh rate. + + The default is intended to almost always enable interpolation if the + playback rate is even slightly different from the display refresh rate. + But note that if you use e.g. ``--video-sync=display-vdrop``, small + deviations in the rate can disable interpolation and introduce a + discontinuity every other minute. + + Set this to ``-1`` to disable this logic. + ``dscale-radius``, ``cscale-radius``, ``tscale-radius``, etc. Set filter parameters for ``dscale``, ``cscale`` and ``tscale``, respectively. @@ -657,7 +671,11 @@ Available video output drivers are: These files must define a function with the following signature:: - vec4 sample(sampler2D tex, vec2 pos, vec2 tex_size) + vec4 sample_pixel(sampler2D tex, vec2 pos, vec2 tex_size) + + (If there is no string ``sample_pixel`` in the shader script, it will + use ``sample`` instead. This is a compatibility hack for older shader + scripts, and is deprecated.) The meanings of the parameters are as follows: @@ -796,7 +814,7 @@ Available video output drivers are: angle Direct3D11 through the OpenGL ES translation layer ANGLE. This supports almost everything the ``win`` backend does, except ICC - profiles, high bit depth video input, and the ``nnedi3`` prescaler. + profiles, and the ``nnedi3`` prescaler. dxinterop (experimental) Win32, using WGL for rendering and Direct3D 9Ex for presentation. Works on Nvidia and AMD only. @@ -824,8 +842,8 @@ Available video output drivers are: influence performance and quality of the video output. ``fmt`` can be one of: rgb, rgba, rgb8, rgb10, rgb10_a2, rgb16, rgb16f, rgb32f, rgba12, rgba16, rgba16f, rgba32f. - Default: ``auto``, which maps to rgba16 on desktop GL, and rgb10_a2 on - GLES (e.g. ANGLE). + Default: ``auto``, which maps to rgba16 on desktop GL, and rgba16f or + rgb10_a2 on GLES (e.g. ANGLE). ``gamma=<0.1..2.0>`` Set a gamma value (default: 1.0). If gamma is adjusted in other ways |