From 13d354e46d27fd0c433880839abcf9096dbcbc2f Mon Sep 17 00:00:00 2001 From: wm4 Date: Wed, 5 Aug 2020 22:37:47 +0200 Subject: auto_profiles: add this script This is taken from a somewhat older proof-of-concept script. The basic idea, and most of the implementation, is still the same. The way the profiles are actually defined changed. I still feel bad about this being a Lua script, and running user expressions as Lua code in a vaguely defined environment, but I guess as far as balance of effort/maintenance/results goes, this is fine. It's a bit bloated (the Lua scripting state is at least 150KB or so in total), so in order to enable this by default, I decided it should unload itself by default if no auto-profiles are used. (And currently, it does not actually rescan the profile list if a new config file is loaded some time later, so the script would do nothing anyway if no auto profiles were defined.) This still requires defining inverse profiles for "unapplying" a profile. Also this is still somewhat racy. Both will probably be alleviated to some degree in the future. --- DOCS/interface-changes.rst | 2 + DOCS/man/mpv.rst | 131 +++++++++++++++++++++++++++++++++++++++++++-- DOCS/man/options.rst | 5 ++ 3 files changed, 133 insertions(+), 5 deletions(-) (limited to 'DOCS') diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst index 4cbeb98cce..e58c13216d 100644 --- a/DOCS/interface-changes.rst +++ b/DOCS/interface-changes.rst @@ -72,6 +72,8 @@ Interface changes - remove --video-sync-adrop-size option (implementation was changed, no replacement for what this option did) - undeprecate --video-sync=display-adrop + - deprecate legacy auto profiles (profiles starting with "extension." and + "protocol."). Use conditional auto profiles instead. --- mpv 0.32.0 --- - change behavior when using legacy option syntax with options that start with two dashes (``--`` instead of a ``-``). Now, using the recommended diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst index dbd700cc9e..a7202864e4 100644 --- a/DOCS/man/mpv.rst +++ b/DOCS/man/mpv.rst @@ -694,10 +694,130 @@ or at runtime with the ``apply-profile `` command. profile=big-cache -Auto profiles -------------- +Conditional auto profiles +------------------------- + +Profiles which have the ``profile-cond`` option set are applied automatically +if the associated condition matches (unless auto profiles are disabled). The +option takes a string, which is interpreted as Lua condition. If evaluating the +expression returns true, the profile is applied, if it returns false, it is +ignored. This Lua code execution is not sandboxed. + +Any variables in condition expressions can reference properties. If an +identifier is not already by defined by Lua or mpv, it is interpreted as +property. For example, ``pause`` would return the current pause status. If the +variable name contains any ``_`` characters, they are turned into ``-``. For +example, ``playback_time`` would return the property ``playback-time``. + +A more robust way to access properties is using ``p.property_name`` or +``get("property-name", default_value)``. The automatic variable to property +magic will break if a new identifier with the same name is introduced (for +example, if a function named ``pause()`` were added, ``pause`` would return a +function value instead of the value of the ``pause`` property). + +Note that if a property is not available, it will return ``nil``, which can +cause errors if used in expressions. These are logged in verbose mode, and the +expression is considered to be false. + +Whenever a property referenced by a profile condition changes, the condition +is re-evaluated. If the return value of the condition changes from false or +error to true, the profile is applied. + +Note that profiles cannot be "unapplied", so you may have to define inverse +profiles with inverse conditions do undo a profile. + +.. admonition:: Example + + Make only HD video look funny: + + :: + + [something] + profile-desc=HD video sucks + profile-cond=width >= 1280 + hue=-50 + + If you want the profile to be reverted if the condition goes to false again, + you need to do this by manually creating an inverse profile: + + :: + + [something] + profile-desc=Flip video when entering fullscreen + profile-cond=fullscreen + vf=vflip + + [something2] + profile-desc=Inverse of [something] + profile-cond=not fullscreen + vf= + + This sets the video filter chain to ``vflip`` when entering fullscreen. The + first profile does not cause the filter to be removed when leaving + fullscreen. A second profile has to be defined, which is explicitly applied + on leaving fullscreen, and which explicitly clears the filter list. (This + would also clear the filter list at program start when starting the player + in windowed mode.) + +.. warning:: + + Every time an involved property changes, the condition is evaluated again. + If your condition uses ``p.playback_time`` for example, the condition is + re-evaluated approximately on every video frame. This is probably slow. + +This feature is managed by an internal Lua script. Conditions are executed as +Lua code within this script. Its environment contains at least the following +things: + +``(function environment table)`` + Every Lua function has an environment table. This is used for identifier + access. There is no named Lua symbol for it; it is implicit. + + The environment does "magic" accesses to mpv properties. If an identifier + is not already defined in ``_G``, it retrieves the mpv property of the same + name. Any occurrences of ``_`` in the name are replaced with ``-`` before + reading the property. The returned value is as retrieved by + ``mp.get_property_native(name)``. Internally, a cache of property values, + updated by observing the property is used instead, so properties that are + not observable will be stuck at the initial value forever. + + If you want to access properties, that actually contain ``_`` in the name, + use ``get()`` (which does not perform transliteration). + + Internally, the environment table has a ``__index`` meta method set, which + performs the access logic. + +``p`` + A "magic" table similar to the environment table. Unlike the latter, this + does not prefer accessing variables defined in ``_G`` - it always accesses + properties. + +``get(name [, def])`` + Read a property and return its value. If the property value is ``nil`` (e.g. + if the property does not exist), ``def`` is returned. + + This is superficially similar to ``mp.get_property_native(name)``. An + important difference is that this accesses the property cache, and enables + the change detection logic (which is essential to the dynamic runtime + behavior of auto profiles). Also, it does not return an error value as + second return value. + + The "magic" tables mentioned above use this function as backend. It does not + perform the ``_`` transliteration. + +In addition, the same environment as in a blank mpv Lua script is present. For +example, ``math`` is defined and gives access to the Lua standard math library. + +.. warning:: + + This feature is subject to change indefinitely. You might be forced to + adjust your profiles on mpv updates. + +Legacy auto profiles +-------------------- -Some profiles are loaded automatically. The following example demonstrates this: +Some profiles are loaded automatically using a legacy mechanism. The following +example demonstrates this: .. admonition:: Auto profile loading @@ -705,14 +825,15 @@ Some profiles are loaded automatically. The following example demonstrates this: [extension.mkv] profile-desc="profile for .mkv files" - vf=flip + vf=vflip The profile name follows the schema ``type.name``, where type can be ``protocol`` for the input/output protocol in use (see ``--list-protocols``), and ``extension`` for the extension of the path of the currently played file (*not* the file format). -This feature is very limited, and there are no other auto profiles. +This feature is very limited, and is considered soft-deprecated. Use conditional +auto profiles. Using mpv from other programs or scripts ======================================== diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index 95bec1c3d3..ad7d449b33 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -999,6 +999,11 @@ Program Behavior show the console, and ``ESC`` to hide it again. (This is based on a user script called ``repl.lua``.) +``--load-auto-profiles=`` + Enable the builtin script that does auto profiles (default: auto). See + `Conditional auto profiles`_ for details. ``auto`` will load the script, + but immediately unload it if there are no conditional profiles. + ``--player-operation-mode=`` For enabling "pseudo GUI mode", which means that the defaults for some options are changed. This option should not normally be used directly, but -- cgit v1.2.3