diff options
Diffstat (limited to 'DOCS/man/input.rst')
| -rw-r--r-- | DOCS/man/input.rst | 325 |
1 files changed, 136 insertions, 189 deletions
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 8cdba41a3d..d15aa41903 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -95,7 +95,7 @@ List of Input Commands relative (default) Seek relative to current position (a negative value seeks backwards). absolute - Seek to a given time. + Seek to a given time (a negative value starts from the end of the file). absolute-percent Seek to a given percent position. relative-percent @@ -665,13 +665,6 @@ Input Commands that are Possibly Subject to Change (the ``ab-loop-a`` property); the second the ``B`` point, and the third will clear both points. -``vo-cmdline "<args>"`` - Reset the sub-option of the current VO. Currently works with ``opengl`` - (including ``opengl-hq``). The argument is the sub-option string usually - passed to the VO on the command line. Not all sub-options can be set, but - those which can will be reset even if they don't appear in the argument. - This command might be changed or removed in the future. - ``drop-buffers`` Drop audio/video/demuxer buffers, and restart from fresh. Might help with unseekable streams that are going out of sync. @@ -698,6 +691,17 @@ Input Commands that are Possibly Subject to Change ``af-command "<label>" "<cmd>" "<args>"`` Same as ``vf-command``, but for audio filters. +``apply-profile "<name>"`` + Apply the contents of a named profile. This is like using ``profile=name`` + in a config file, except you can map it to a key binding to change it at + runtime. + + There is no such thing as "unapplying" a profile - applying a profile + merely sets all option values listed within the profile. + +``load-script "<path>"`` + Load a script, similar to the ``--script`` option. + Undocumented commands: ``tv-last-channel`` (TV/DVB only), ``ao-reload`` (experimental/internal). @@ -838,20 +842,12 @@ an option at runtime. Property list ------------- -``osd-level`` (RW) - See ``--osd-level``. +.. note:: -``osd-scale`` (RW) - OSD font size multiplier, see ``--osd-scale``. - -``loop`` (RW) - See ``--loop``. - -``loop-file`` (RW) - See ``--loop-file`` (uses ``yes``/``no``). - -``speed`` (RW) - See ``--speed``. + Most options can be set as runtime via properties as well. Just remove the + leading ``--`` from the option name. These are not documented. Only + properties which do not exist as option with the same name, or which have + very different behavior from the options are documented below. ``audio-speed-correction``, ``video-speed-correction`` Factor multiplied with ``speed`` at which the player attempts to play the @@ -911,9 +907,11 @@ Property list list of format names, e.g. mp4 is ``mov,mp4,m4a,3gp,3g2,mj2`` (the list may grow in the future for any format). -``demuxer`` +``current-demuxer`` Name of the current demuxer. (This is useless.) + (Renamed from ``demuxer``.) + ``stream-path`` Filename (full path) of the stream layer filename. (This is probably useless. It looks like this can be different from ``path`` only when @@ -989,6 +987,12 @@ Property list Remaining length of the file in seconds. Note that the file duration is not always exactly known, so this is an estimate. +``audio-pts`` (R) + Current audio playback position in current file in seconds. Unlike time-pos, + this updates more often than once per frame. For audio-only files, it is + mostly equivalent to time-pos, while for video-only files this property is + not available. + ``playtime-remaining`` ``time-remaining`` scaled by the current ``speed``. @@ -1078,10 +1082,6 @@ Property list "title" MPV_FORMAT_STRING "default" MPV_FORMAT_FLAG -``ab-loop-a``, ``ab-loop-b`` (RW) - Set/get A-B loop points. See corresponding options and ``ab-loop`` command - for details. - ``angle`` (RW) Current DVD angle. @@ -1154,13 +1154,12 @@ Property list ``af-metadata/<filter-label>`` Equivalent to ``vf-metadata/<filter-label>``, but for audio filters. -``pause`` (RW) - Pause status. This is usually ``yes`` or ``no``. See ``--pause``. - -``idle`` +``idle-active`` Return ``yes`` if no file is loaded, but the player is staying around because of the ``--idle`` option. + (Renamed from ``idle``.) + ``core-idle`` Return ``yes`` if the playback core is paused, otherwise ``no``. This can be different ``pause`` in special situations, such as when the player @@ -1236,25 +1235,12 @@ Property list is loaded, or when switching ordered chapter segments. This is because the same underlying code is used for seeking and resyncing.) -``hr-seek`` (RW) - See ``--hr-seek``. - ``mixer-active`` Return ``yes`` if the audio mixer is active, ``no`` otherwise. This option is relatively useless. Before mpv 0.18.1, it could be used to infer behavior of the ``volume`` property. -``volume`` (RW) - Current volume (see ``--volume`` for details). - -``volume-max`` (RW) - Current maximum value the volume property can be set to. (Equivalent to the - ``--volume-max`` option.) - -``mute`` (RW) - Current mute status (``yes``/``no``). - ``ao-volume`` (RW) System volume. This property is available only if mpv audio output is currently active, and only if the underlying implementation supports volume @@ -1266,9 +1252,6 @@ Property list Similar to ``ao-volume``, but controls the mute state. May be unimplemented even if ``ao-volume`` works. -``audio-delay`` (RW) - See ``--audio-delay``. - ``audio-codec`` Audio codec selected for decoding. @@ -1316,28 +1299,6 @@ Property list Same as ``audio-params``, but the format of the data written to the audio API. -``aid`` (RW) - Current audio track (similar to ``--aid``). - -``audio`` (RW) - Alias for ``aid``. - -``balance`` (RW) - Audio channel balance. (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. - -``fullscreen`` (RW) - See ``--fullscreen``. - -``deinterlace`` (RW) - See ``--deinterlace``. - -``field-dominance`` (RW) - See ``--field-dominance`` - ``colormatrix`` (R) Redirects to ``video-params/colormatrix``. This parameter (as well as similar ones) can be overridden with the ``format`` video filter. @@ -1345,42 +1306,9 @@ Property list ``colormatrix-input-range`` (R) See ``colormatrix``. -``video-output-levels`` (RW) - See ``--video-output-levels``, - ``colormatrix-primaries`` (R) See ``colormatrix``. -``taskbar-progress`` (RW) - See ``--taskbar-progress``. - -``ontop`` (RW) - See ``--ontop``. - -``border`` (RW) - See ``--border``. - -``on-all-workspaces`` (RW) - See ``--on-all-workspaces``. Unsetting may not work on all WMs. - -``framedrop`` (RW) - See ``--framedrop``. - -``gamma`` (RW) - See ``--gamma``. - -``brightness`` (RW) - See ``--brightness``. - -``contrast`` (RW) - See ``--contrast``. - -``saturation`` (RW) - See ``--saturation``. - -``hue`` (RW) - See ``--hue``. - ``hwdec`` (RW) Reflects the ``--hwdec`` option. @@ -1413,27 +1341,6 @@ Property list multiple interop drivers for the same hardware decoder, depending on platform and VO. -``hwdec-active`` - Deprecated. To be removed in mpv 0.20.0. Use ``hwdec-current`` instead. - - Return ``yes`` or ``no``, depending on whether any type of hardware decoding - is actually in use. - -``hwdec-detected`` - Deprecated. To be removed in mpv 0.20.0. - - If hardware decoding is active, this returns the hardware decoder in use. - Otherwise, it returns either ``no``, or if applicable, the currently loaded - hardware decoding API. This is known only once the VO has opened (and - possibly later). With some VOs (like ``opengl``), this is never known in - advance, but only when the decoder attempted to create the hw decoder - successfully. Also, hw decoders with ``-copy`` suffix will return ``no`` - while no video is being decoded. All this reflects how detecting hw decoders - are detected and used internally in mpv. - -``panscan`` (RW) - See ``--panscan``. - ``video-format`` Video format as string. @@ -1534,6 +1441,9 @@ Property list These have the same values as ``video-out-params/dw`` and ``video-out-params/dh``. +``video-dec-params`` + Exactly like ``video-params``, but no overrides applied. + ``video-out-params`` Same as ``video-params``, but after video filters have been applied. If there are no video filters in use, this will contain the same values as @@ -1556,10 +1466,12 @@ Property list ``video-frame-info/tff`` ``video-frame-info/repeat`` -``fps`` +``container-fps`` Container FPS. This can easily contain bogus values. For videos that use modern container formats or video codecs, this will often be incorrect. + (Renamed from ``fps``.) + ``estimated-vf-fps`` Estimated/measured FPS of the video filter chain output. (If no filters are used, this corresponds to decoder output.) This uses the average of @@ -1580,7 +1492,10 @@ Property list ``display-names`` Names of the displays that the mpv window covers. On X11, these - are the xrandr names (LVDS1, HDMI1, DP1, VGA1, etc.). + are the xrandr names (LVDS1, HDMI1, DP1, VGA1, etc.). On Windows, these + are the GDI names (\\.\DISPLAY1, \\.\DISPLAY2, etc.) and the first display + in the list will be the one that Windows considers associated with the + window (as determined by the MonitorFromWindow API.) ``display-fps`` (RW) The refresh rate of the current display. Currently, this is the lowest FPS @@ -1600,6 +1515,9 @@ Property list ``video-aspect`` (RW) Video aspect, see ``--video-aspect``. + If video is active, this reports the effective aspect value, instead of + the value of the ``--video-aspect`` option. + ``osd-width``, ``osd-height`` Last known OSD width (can be 0). This is needed if you want to use the ``overlay-add`` command. It gives you the actual OSD size, which can be @@ -1608,71 +1526,24 @@ Property list ``osd-par`` Last known OSD display pixel aspect (can be 0). -``vid`` (RW) - Current video track (similar to ``--vid``). - -``video`` (RW) - Alias for ``vid``. - -``video-align-x``, ``video-align-y`` (RW) - See ``--video-align-x`` and ``--video-align-y``. - -``video-pan-x``, ``video-pan-y`` (RW) - See ``--video-pan-x`` and ``--video-pan-y``. - -``video-zoom`` (RW) - See ``--video-zoom``. - -``video-unscaled`` (W) - See ``--video-unscaled``. - ``program`` (W) Switch TS program (write-only). ``dvb-channel`` (W) Pair of integers: card,channel of current DVB stream. - Can be switched to switch to another channel on the same card. + Can be switched to switch to another channel on the same card. ``dvb-channel-name`` (RW) Name of current DVB program. On write, a channel-switch to the named channel on the same - card is performed. Can also be used for channel switching. - -``sid`` (RW) - Current subtitle track (similar to ``--sid``). + card is performed. Can also be used for channel switching. -``secondary-sid`` (RW) - Secondary subtitle track (see ``--secondary-sid``). +``sub-text`` + Return the current subtitle text. Formatting is stripped. If a subtitle + is selected, but no text is currently visible, or the subtitle is not + text-based (i.e. DVD/BD subtitles), an empty string is returned. -``sub`` (RW) - Alias for ``sid``. - -``sub-delay`` (RW) - See ``--sub-delay``. - -``sub-pos`` (RW) - See ``--sub-pos``. - -``sub-visibility`` (RW) - See ``--sub-visibility``. - -``sub-forced-only`` (RW) - See ``--sub-forced-only``. - -``sub-scale`` (RW) - Subtitle font size multiplier. - -``ass-force-margins`` (RW) - See ``--ass-force-margins``. - -``sub-use-margins`` (RW) - See ``--sub-use-margins``. - -``ass-vsfilter-aspect-compat`` (RW) - See ``--ass-vsfilter-aspect-compat``. - -``ass-style-override`` (RW) - See ``--ass-style-override``. + This property is experimental and might be removed in the future. ``stream-capture`` (RW) A filename, see ``--stream-capture``. Setting this will start capture using @@ -1884,11 +1755,8 @@ Property list "title" MPV_FORMAT_STRING "time" MPV_FORMAT_DOUBLE -``af`` (RW) - See ``--af`` and the ``af`` command. - -``vf`` (RW) - See ``--vf`` and the ``vf`` command. +``af``, ``vf`` (RW) + See ``--vf``/``--af`` and the ``vf``/``af`` command. 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 @@ -1906,12 +1774,6 @@ Property list It's also possible to write the property using this format. -``video-rotate`` (RW) - See ``--video-rotate`` option. - -``video-stereo-mode`` (RW) - See ``--video-stereo-mode`` option. - ``seekable`` Return whether it's generally possible to seek in the current file. @@ -2151,6 +2013,10 @@ Property list require reloading the file for changes to take effect. If there is an equivalent property, prefer setting the property instead. + There shouldn't be any reason to access ``options/<name>`` instead of + ``<name>``, except in situations in which the properties have different + behavior or conflicting semantics. + ``file-local-options/<name>`` Similar to ``options/<name>``, but when setting an option through this property, the option is reset to its old value once the current file has @@ -2204,6 +2070,87 @@ Property list ``property-list`` Return the list of top-level properties. +``profile-list`` + Return the list of profiles and their contents. This is highly + implementation-specific, and may change any time. Currently, it returns + an array of options for each profile. Each option has a name and a value, + with the value currently always being a string. Note that the options array + is not a map, as order matters and duplicate entries are possible. Recursive + profiles are not expanded, and show up as special ``profile`` options. + +Inconsistencies between options and properties +---------------------------------------------- + +You can access (almost) all options as properties, though there are some +caveats with some properties (due to historical reasons): + +``vid``, ``aid``, ``sid`` + While playback is active, you can set existing tracks only. (The option + allows setting any track ID, and which tracks to enable is chosen at + loading time.) + + Option changes at runtime are affected by this as well. + +``deinterlace`` + While video is active, this behaves differently from the option. It will + never return the ``auto`` value (but the state as observed by the video + chain). If you set ``auto``, the property will set this as the option value, + and will return the actual video chain state as observed instead of auto. + +``video-aspect`` + While video is active, always returns the effective aspect ratio. Setting + a special value (like ``no``, values ``<= 0``) will make the property + set this as option, and return whatever actual aspect was derived from the + option setting. + +``brightness`` (and other color options) + If ``--vo=xv`` is used, these properties may return the adapter's current + values instead of the option values. + +``display-fps`` + If a VO is created, this will return either the actual display FPS, or + an invalid value, instead of the option value. + +``vf``, ``af`` + If you set the properties during playback, and the filter chain fails to + reinitialize, the new value will be rejected. Setting the option or + setting the property outside of playback will always succeed/fail in the + same way. Also, there are no ``vf-add`` etc. properties, but you can use + the ``vf``/``af`` group of commands to achieve the same. + + Option changes at runtime are affected by this as well. + +``edition`` + While a file is loaded, the property will always return the effective + edition, and setting the ``auto`` value will show somewhat strange behavior + (the property eventually switching to whatever is the default edition). + +``playlist`` + The property is read-only and returns the current internal playlist. The + option is for loading playlist during command line parsing. For client API + uses, you should use the ``loadlist`` command instead. + +``window-scale`` + Might verify the set value when setting while a window is created. + +``audio-file``, ``sub-file``, ``external-file`` + These options/properties are actually lists of filenames. To make the + command-line interface easier, each ``--audio-file=...`` option appends + the full string to the internal list. However, when used as properties, + every time you set the property as a string the internal list will be + replaced with a single entry containing the string you set. ``,`` or other + separators are never used. You have to use ``MPV_FORMAT_NODE_ARRAY`` (or + corresponding API, e.g. ``mp.set_property_native()`` with a table in Lua) + to set multiple entries. + + Strictly speaking, option access via API (e.g. ``mpv_set_option_string()``) + has the same problem, and it's only a difference between CLI/API. + +``demuxer``, ``idle``, ``length``, ``audio-samplerate``, ``audio-channels``, ``audio-format``, ``fps``, ``cache``, ``playlist-pos``, ``chapter`` + These behave completely different as property, but are deprecated (newer + aliases which don't conflict have been added). After the deprecation period + they will be changed to the proper option behavior. + Property Expansion ------------------ |