diff options
Diffstat (limited to 'DOCS/man')
-rw-r--r-- | DOCS/man/input.rst | 14 | ||||
-rw-r--r-- | DOCS/man/mpv.rst | 66 |
2 files changed, 77 insertions, 3 deletions
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 6df7890383..8593dd75a2 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -1220,13 +1220,21 @@ Input Commands that are Possibly Subject to Change ``af-command <label> <command> <argument>`` Same as ``vf-command``, but for audio filters. -``apply-profile <name>`` +``apply-profile <name> [<mode>]`` 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. + The mode argument: + + ``default`` + Apply the profile. Default if the argument is omitted. + + ``restore`` + Restore options set by a previous ``apply-profile`` command for this + profile. Only works if the profile has ``profile-restore`` set to a + relevant mode. Prints a warning if nothing could be done. See + `Runtime profiles`_ for details. ``load-script <filename>`` Load a script, similar to the ``--script`` option. Whether this waits for diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst index a7202864e4..ee28dd5c67 100644 --- a/DOCS/man/mpv.rst +++ b/DOCS/man/mpv.rst @@ -693,6 +693,72 @@ or at runtime with the ``apply-profile <name>`` command. # you can also include other profiles profile=big-cache +Runtime profiles +---------------- + +Profiles can be set at runtime with ``apply-profile`` command. Since this +operation is "destructive" (every item in a profile is simply set as an +option, overwriting the previous value), you can't just enable and disable +profiles again. + +As a partial remedy, there is a way to make profiles save old option values +before overwriting them with the profile values, and then restoring the old +values at a later point using ``apply-profile <profile-name> restore``. + +This can be enabled with the ``profile-restore`` option, which takes one of +the following options: + + ``default`` + Does nothing, and nothing can be restored (default). + + ``copy`` + When applying a profile, copy the old values of all profile options to a + backup before setting them from the profile. These options are reset to + their old values using the backup when restoring. + + Every profile has its own list of backed up values. If the backup + already exists (e.g. if ``apply-profile name`` was called more than + once in a row), the existing backup is no changed. The restore operation + will remove the backup. + + It's important to know that restoring does not "undo" setting an option, + but simply copies the old option value. Consider for example ``vf-add``, + appends an entry to ``vf``. This mechanism will simply copy the entire + ``vf`` list, and does _not_ execute the inverse of ``vf-add`` (that + would be ``vf-remove``) on restoring. + + Note that if a profile contains recursive profiles (via the ``profile`` + option), the options in these recursive profiles are treated as if they + were part of this profile. The referenced profile's backup list is not + used when creating or using the backup. Restoring a profile does not + restore referenced profiles, only the options of referenced profiles (as + if they were part of the main profile). + + ``copy-equal`` + Similar to ``copy``, but restore an option only if it has the same value + as the value effectively set by the profile. This tries to deal with + the situation when the user does not want the option to be reset after + interactively changing it. + +.. admonition:: Example + + :: + + [something] + profile-restore=copy-equal + vf-add=rotate=90 + + Then running these commands will result in behavior as commented: + + :: + + set vf vflip + apply-profile something + vf-add=hflip + apply-profile something + # vf == vflip,rotate=90,hflip,rotate=90 + apply-profile something restore + # vf == vflip Conditional auto profiles ------------------------- |