diff options
Diffstat (limited to 'DOCS/man')
| -rw-r--r-- | DOCS/man/af.rst | 31 | ||||
| -rw-r--r-- | DOCS/man/ao.rst | 6 | ||||
| -rw-r--r-- | DOCS/man/input.rst | 57 | ||||
| -rw-r--r-- | DOCS/man/lua.rst | 8 | ||||
| -rw-r--r-- | DOCS/man/mpv.rst | 37 | ||||
| -rw-r--r-- | DOCS/man/options.rst | 61 | ||||
| -rw-r--r-- | DOCS/man/vf.rst | 6 | ||||
| -rw-r--r-- | DOCS/man/vo.rst | 20 |
8 files changed, 155 insertions, 71 deletions
diff --git a/DOCS/man/af.rst b/DOCS/man/af.rst index 1ae3c092df..96e50686ae 100644 --- a/DOCS/man/af.rst +++ b/DOCS/man/af.rst @@ -225,14 +225,21 @@ Available filters are: automatically up- and downmix standard channel layouts. ``format=format:srate:channels:out-format:out-srate:out-channels`` - Force a specific audio format/configuration without actually changing the - audio data. Keep in mind that the filter system might auto-insert actual - conversion filters before or after this filter if needed. + Does not do any format conversion itself. Rather, it may cause the + filter system to insert necessary conversion filters before or after this + filter if needed. It is primarily useful for controlling the audio format + going into other filters. To specify the format for audio output, see + ``--audio-format``, ``--audio-samplerate``, and ``--audio-channels``. This + filter is able to force a particular format, whereas ``--audio-*`` + may be overridden by the ao based on output compatibility. All parameters are optional. The first 3 parameters restrict what the filter - accepts as input. The ``out-`` parameters change the audio format, without - actually doing a conversion. The data will be 'reinterpreted' by the - filters or audio outputs following this filter. + accepts as input. They will therefore cause conversion filters to be + inserted before this one. The ``out-`` parameters tell the filters or audio + outputs following this filter how to interpret the data without actually + doing a conversion. Setting these will probably just break things unless you + really know you want this for some reason, such as testing or dealing with + broken media. ``<format>`` Force conversion to this format. Use ``--af=format=format=help`` to get @@ -252,14 +259,9 @@ Available filters are: ``<out-channels>`` - See also ``--audio-format``, ``--audio-samplerate``, and - ``--audio-channels`` for related options. Keep in mind that - ``--audio-channels`` does not actually force the number of - channels in most cases, while this filter can do this. - - *NOTE*: this filter used to be named ``force``. Also, unlike the old - ``format`` filter, this does not do any actual conversion anymore. - Conversion is done by other, automatically inserted filters. + *NOTE*: this filter used to be named ``force``. The old ``format`` filter + used to do conversion itself, unlike this one which lets the filter system + handle the conversion. ``convert24`` Filter for internal use only. Converts between 24-bit and 32-bit sample @@ -629,4 +631,3 @@ Available filters are: ``o=<string>`` AVOptions. - diff --git a/DOCS/man/ao.rst b/DOCS/man/ao.rst index 5ca960c4ea..534f62588c 100644 --- a/DOCS/man/ao.rst +++ b/DOCS/man/ao.rst @@ -107,8 +107,10 @@ Available audio output drivers are: ``--audio-device`` to select the device (use ``--audio-device=help`` to get a list of all devices and their mpv name). - You can also try - `Using the upmix plugin <https://github.com/mpv-player/mpv/wiki/ALSA:-Surround-Sound-and-Upmixing>`_. + You can also try `using the upmix plugin <http://git.io/vfuAy>`_. + This setup enables multichannel audio on the ``default`` device + with automatic upmixing with shared access, so playing stereo + and multichannel audio at the same time will work as expected. ``oss`` OSS audio output driver diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index a3bad3706b..633f6a8308 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -187,8 +187,7 @@ List of Input Commands The second argument is like the first argument to ``screenshot``. - This command tries to never overwrite files. If the file already exists, - it fails. + If the file already exists, it's overwritten. Like all input command parameters, the filename is subject to property expansion as described in `Property Expansion`_. @@ -632,6 +631,15 @@ Input Commands that are Possibly Subject to Change unseekable streams that are going out of sync. This command might be changed or removed in the future. +``screenshot_raw [subtitles|video|window]`` + Return a screenshot in memory. This can be used only through the client + API. The MPV_FORMAT_NODE_MAP returned by this command has the ``w``, ``h``, + ``stride`` fields set to obvious contents. A ``format`` field is set to + ``bgr0`` by default. This format is organized as ``B8G8R8X8`` (where ``B`` + is the LSB). The contents of the padding ``X`` is undefined. The ``data`` + 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. + Undocumented commands: ``tv_last_channel`` (TV/DVB only), ``get_property`` (deprecated), ``ao_reload`` (experimental/internal). @@ -920,6 +928,10 @@ Property list a BD or DVD. Use the ``discnav menu`` command to actually enter or leave menu mode. +``disc-mouse-on-button`` + Return ``yes`` when the mouse cursor is located on a button, or ``no`` + when cursor is outside of any button for disc navigation. + ``chapters`` Number of chapters. @@ -1078,6 +1090,11 @@ Property list guess is very unreliable, and often the property will not be available at all, even if data is buffered. +``demuxer-cache-time`` + Approximate time of video buffered in the demuxer, in seconds. Same as + ``demuxer-cache-duration`` but returns the last timestamp of bufferred + data in demuxer. + ``demuxer-cache-idle`` Returns ``yes`` if the demuxer is idle, which means the demuxer cache is filled to the requested amount, and is currently not reading more data. @@ -1123,9 +1140,6 @@ Property list ``audio-codec`` Audio codec selected for decoding. -``audio-bitrate`` - Audio bitrate. This is probably a very bad guess in most cases. - ``audio-samplerate`` Audio samplerate. @@ -1222,9 +1236,6 @@ Property list ``video-codec`` Video codec selected for decoding. -``video-bitrate`` - Video bitrate (a bad guess). - ``width``, ``height`` Video size. This uses the size of the video as decoded, or if no video frame has been decoded yet, the (possibly incorrect) container indicated @@ -1513,6 +1524,13 @@ Property list ``track-list/N/selected`` ``yes`` if the track is currently decoded, ``no`` otherwise. + ``track-list/N/ff-index`` + The stream index as usually used by the FFmpeg utilities. Note that + this can be potentially wrong if a demuxer other than libavformat + (``--demuxer=lavf``) is used. For mkv files, the index will usually + match even if the default (builtin) demuxer is used, but there is + no hard guarantee. + When querying the property with the client API using ``MPV_FORMAT_NODE``, or with Lua ``mp.get_property_native``, this will return a mpv_node with the following contents: @@ -1634,7 +1652,7 @@ Property list whether the video window is visible. If the ``--force-window`` option is used, this is usually always returns ``yes``. -``packet-video-bitrate``, ``packet-audio-bitrate``, ``packet-sub-bitrate`` +``video-bitrate``, ``audio-bitrate``, ``sub-bitrate`` Bitrate values calculated on the packet level. This works by dividing the bit size of all packets between two keyframes by their presentation timestamp distance. (This uses the timestamps are stored in the file, so @@ -1643,8 +1661,29 @@ Property list bitrate. To make the property more UI friendly, updates to these properties are throttled in a certain way. + The unit is bits per second. OSD formatting turns these values in kilobits + (or megabits, if appropriate), which can be prevented by using the + raw property value, e.g. with ``${=video-bitrate}``. + + Note that the accuracy of these properties is influenced by a few factors. + If the underlying demuxer rewrites the packets on demuxing (done for some + file formats), the bitrate might be slightly off. If timestamps are bad + or jittery (like in Matroska), even constant bitrate streams might show + fluctuating bitrate. + How exactly these values are calculated might change in the future. + In earlier versions of mpv, these properties returned a static (but bad) + guess using a completely different method. + +``packet-video-bitrate``, ``packet-audio-bitrate``, ``packet-sub-bitrate`` + Old and deprecated properties for ``video-bitrate``, ``audio-bitrate``, + ``sub-bitrate``. They behave exactly the same, but return a value in + kilobits. Also, they don't have any OSD formatting, though the same can be + achieved with e.g. ``${=video-bitrate}``. + + These properties shouldn't be used anymore. + ``audio-device-list`` Return the list of discovered audio devices. This is mostly for use with the client API, and reflects what ``--audio-device=help`` with the command diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index 4700b90cb2..ff70600a1d 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -639,6 +639,14 @@ strictly part of the guaranteed API. trailing text is returned as 3rd return value. (The 3rd return value is always there, but with ``trail`` set, no error is raised.) +``utils.format_json(v)`` + Format the given Lua table (or value) as a JSON string and return it. On + error, returns ``nil, error``. (Errors usually only happen on value types + incompatible with JSON.) + + The argument value uses similar conventions as ``mp.set_property_native()`` + to distinguish empty objects and arrays. + ``utils.to_string(v)`` Turn the given value into a string. Formats tables and their contents. This doesn't do anything special; it is only needed because Lua is terrible. diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst index ca1e87105e..751b2b2b59 100644 --- a/DOCS/man/mpv.rst +++ b/DOCS/man/mpv.rst @@ -276,14 +276,16 @@ Shells may actually strip some quotes from the string passed to the commandline, so the example quotes the string twice, ensuring that mpv recieves the ``"`` quotes. -The ``[...]`` from of quotes wraps everything between ``[`` and ``]``. It's +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). +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``.) -A special kind of string-escaping intended for use with external scripts and -programs is started with ``%``. +The fixed-length quoting syntax is intended for use with external +scripts and programs. -It has the following format:: +It is started with ``%`` and has the following format:: %n%string_of_length_n @@ -319,7 +321,8 @@ console controls. (Which makes it suitable for playing data piped to stdin.) 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 ``%n%string_of_length_n`` syntax (see above). +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/``). @@ -397,10 +400,10 @@ 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 ``"`` and ``'``, -as well as with the ``%n%`` syntax 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 to this -manually. (This is a mess and should probably be changed at some point.) +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 to +this manually. (This is a mess and should probably be changed at some point.) Putting Command Line Options into the Configuration File -------------------------------------------------------- @@ -475,11 +478,8 @@ 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. -The ``screenshot`` video filter is not required when using a recommended GUI -video output driver. It should normally not be added to the config file, as -taking screenshots is handled by the VOs, and adding the screenshot filter will -break hardware decoding. (The filter may still be useful for taking screenshots -at a certain point within the video chain when using multiple video filters.) +Unlike with MPlayer, the ``screenshot`` video filter is not required. This +filter was never required in mpv, and has been removed. TERMINAL STATUS LINE ==================== @@ -517,10 +517,9 @@ listed. rendering is too slow. Also can 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 should almost never - happen, unless decoder-framedropping is enabled with one of the - ``--framedrop`` options, the stream contains errors, or a weird codec is in - use. (``drop-frame-count`` property.) + to the display as well, e.g.: ``Dropped: 4/34``. This happens only if + decoder-framedropping 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 *additional* data buffered in the stream cache in diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index b380db9ffb..dd85fbfd63 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -181,6 +181,7 @@ Playback Control file, such as a chapter seek, but not for relative seeks like the default behavior of arrow keys (default). :yes: Use precise seeks whenever possible. + :always: Same as ``yes`` (for compatibility). ``--hr-seek-demuxer-offset=<seconds>`` This option exists to work around failures to do precise seeks (as in @@ -566,8 +567,7 @@ Video The ``vaapi-copy`` mode allows you to use vaapi with any VO. Because this copies the decoded video back to system RAM, it's likely less efficient - than the ``vaapi`` mode. But there are reports that this is actually faster - as well, and avoids many issues with ``vaapi``. + than the ``vaapi`` mode. .. note:: @@ -983,8 +983,9 @@ Audio ``--audio-display=<no|attachment>`` Setting this option to ``attachment`` (default) will display image - attachments when playing audio files. It will display the first image - found, and additional images are available as video tracks. + 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. @@ -1723,19 +1724,13 @@ Window (depending on the video aspect ratio, the width or height will be larger than 500 in order to keep the aspect ratio the same). -``--autosync=<factor>`` - Gradually adjusts the A/V sync based on audio delay measurements. - Specifying ``--autosync=0``, the default, will cause frame timing to be - based entirely on audio delay measurements. Specifying ``--autosync=1`` - will do the same, but will subtly change the A/V correction algorithm. An - uneven video framerate in a video which plays fine with ``--no-audio`` can - often be helped by setting this to an integer value greater than 1. The - higher the value, the closer the timing will be to ``--no-audio``. Try - ``--autosync=30`` to smooth out problems with sound drivers which do not - implement a perfect audio delay measurement. With this value, if large A/V - sync offsets occur, they will only take about 1 or 2 seconds to settle - out. This delay in reaction time to sudden A/V offsets should be the only - side-effect of turning this option on, for all sound drivers. +``--window-scale=<factor>`` + 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=<number|no|always>`` Make mouse cursor automatically hide after given number of milliseconds. @@ -2021,6 +2016,12 @@ Demuxer ``--demuxer-lavf-format=<name>`` Force a specific libavformat demuxer. +``--demuxer-lavf-hacks=<yes|no>`` + 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=<no|lavf>`` Mode for deriving missing packet PTS values from packet DTS. ``lavf`` enables libavformat's ``genpts`` option. ``no`` disables it. This used @@ -2105,6 +2106,18 @@ Demuxer will be slower (especially when playing over http), or that behavior with broken files is much worse. So don't use this option. +``--demuxer-mkv-fix-timestamps=<yes|no>`` + Fix rounded Matroska timestamps (enabled by default). Matroska usually + stores timestamps rounded to milliseconds. This means timestamps jitter + by some amount around the intended timestamp. mpv can correct the timestamps + based on the framerate value stored in the file: the timestamp is rounded + to the next frame (according to the framerate), unless the new timestamp + would deviate more than 1ms from the old one. This should undo the rounding + done by the muxer. + + (The allowed deviation can be less than 1ms if the file uses a non-standard + timecode scale.) + ``--demuxer-rawaudio-channels=<value>`` Number of channels (or channel layout) if ``--demuxer=rawaudio`` is used (default: stereo). @@ -3231,6 +3244,20 @@ Miscellaneous ``--mc=<seconds/frame>`` Maximum A-V sync correction per frame (in seconds) +``--autosync=<factor>`` + Gradually adjusts the A/V sync based on audio delay measurements. + Specifying ``--autosync=0``, the default, will cause frame timing to be + based entirely on audio delay measurements. Specifying ``--autosync=1`` + will do the same, but will subtly change the A/V correction algorithm. An + uneven video framerate in a video which plays fine with ``--no-audio`` can + often be helped by setting this to an integer value greater than 1. The + higher the value, the closer the timing will be to ``--no-audio``. Try + ``--autosync=30`` to smooth out problems with sound drivers which do not + implement a perfect audio delay measurement. With this value, if large A/V + sync offsets occur, they will only take about 1 or 2 seconds to settle + out. This delay in reaction time to sudden A/V offsets should be the only + side-effect of turning this option on, for all sound drivers. + ``--mf-fps=<value>`` Framerate used when decoding from multiple PNG or JPEG files with ``mf://`` (default: 1). diff --git a/DOCS/man/vf.rst b/DOCS/man/vf.rst index be7daee09e..3739716340 100644 --- a/DOCS/man/vf.rst +++ b/DOCS/man/vf.rst @@ -561,12 +561,6 @@ Available filters are: ``show`` Draw a rectangle showing the area defined by x/y/w/h. -``screenshot`` - Optional filter for screenshot support. This is only needed if the video - output does not provide working direct screenshot support. Note that it is - not always safe to insert this filter by default. See `TAKING SCREENSHOTS`_ - for details. - ``sub=[=bottom-margin:top-margin]`` Moves subtitle rendering to an arbitrary point in the filter chain, or force subtitle rendering in the video filter as opposed to using video output OSD diff --git a/DOCS/man/vo.rst b/DOCS/man/vo.rst index 2447a8c455..b398d4f57d 100644 --- a/DOCS/man/vo.rst +++ b/DOCS/man/vo.rst @@ -548,10 +548,11 @@ Available video output drivers are: X11/GLX only. - ``dwmflush`` - Calls ``DwmFlush`` after swapping buffers on Windows (default: 0). + ``dwmflush=<no|windowed|yes>`` + Calls ``DwmFlush`` after swapping buffers on Windows (default: no). It also sets ``SwapInterval(0)`` to ignore the OpenGL timing. Values - are: 0 (disabled), 1 (only in windowed mode), 2 (also in full screen). + are: no (disabled), windowed (only in windowed mode), yes (also in + full screen). This may help getting more consistent frame intervals, especially with high-fps clips - which might also reduce dropped frames. Typically a value of 1 should be enough since full screen may bypass the DWM. @@ -919,3 +920,16 @@ Available video output drivers are: (default: -10). Note that mpv will also use the 2 layers above the selected layer, to handle the window background and OSD. Actual video rendering will happen on the layer above the selected layer. + +``drm`` (Direct Rendering Manager) + Video output driver using Kernel Mode Setting / Direct Rendering Manager. + Does not support hardware acceleration. Should be used when one doesn't + want to install full-blown graphical environment (e.g. no X). + + ``connector=<number>`` + Select the connector to use (usually this is a monitor.) If set to -1, + mpv renders the output on the first available connector. (default: -1) + + ``devpath=<filename>`` + Path to graphic card device. + (default: /dev/dri/card0) |