path: root/DOCS
diff options
authorwm4 <wm4@nowhere>2016-09-18 16:06:12 +0200
committerwm4 <wm4@nowhere>2016-09-18 16:08:21 +0200
commit2415b695724c15def54a039527ee9eb574ffb65f (patch)
tree97ed9e4c272bf3ac29764557db73b24d99503945 /DOCS
parent3ecc6d0a7934c42395d863b74e47f903fe864760 (diff)
player: more option/property consistency fixes
Some properties had a different type from their equivalent options (such as mute, volume, deinterlace, edition). This wasn't really sane, as raw option values should be always within their bounds. On the other hand, these properties use a different type to reflect runtime limits (such as range of available editions), or simply to improve the "UI" (you don't want to cycle throuhg the completely useless "auto" value when cycling the "mute" property). Handle this by making them always return the option type, but also allowing them to provide a "constricted" type, which is used for UI purposes. All M_PROPERTY_GET_CONSTRICTED_TYPE changes are related to this. One consequence is that you can set the volume property to arbitrary high values just like with the --volume option, but using the "add" command it still restricts it to the --volume-max range. Also deprecate --chapter, as it is grossly incompatible to the chapter property. We pondered renaming it to --chapters, or introducing a more powerful --range option, but concluded that --start --end is actually enough. These changes appear to take care of the last gross property/option incompatibilities, although there might still be a few lurking.
Diffstat (limited to 'DOCS')
2 files changed, 13 insertions, 18 deletions
diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst
index 339b7ffd9e..8472da4ff2 100644
--- a/DOCS/interface-changes.rst
+++ b/DOCS/interface-changes.rst
@@ -64,6 +64,8 @@ Interface changes
- deprecate "--vo=direct3d_shaders" - use "--vo=direct3d" instead.
Change "--vo=direct3d" to always use shaders by default.
- deprecate --playlist-pos option, renamed to --playlist-start
+ - deprecate the --chapter option, as it is redundant with --start/--end,
+ and conflicts with the semantics of the "chapter" property
- incompatible change to cdda:// protocol options: the part after cdda://
now always sets the device, not the span or speed to be played. No
separating extra "/" is needed. The hidden --cdda-device options is also
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 17bba1c2ab..1f7862d1c1 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -2079,12 +2079,14 @@ caveats with some properties (due to historical reasons):
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). You cannot set ``auto`` either.
- Option changes at runtime are affected by this as well.
+ 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.
- While video is active, always returns the effective aspect ratio.
+ 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
@@ -2103,19 +2105,10 @@ caveats with some properties (due to historical reasons):
Option changes at runtime are affected by this as well.
- While playback is *not* active, the property behaves like the option, and
- you can set a chapter range. While playback is active, you can set only
- the current chapter (to which the player will seek immediately).
- Option changes at runtime are affected by this as well.
- When set as option, the maximum (set by ``--volume-max``) is not checked,
- while when set as property, the maximum is enforced.
- The option has a deprecated ``auto`` value, which is equal to ``no``.
+ 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).
The property is read-only and returns the current internal playlist. The
@@ -2138,7 +2131,7 @@ caveats with some properties (due to historical reasons):
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``
+``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.