Awesome
mpv-user-data-loader
A script that allows the mpv user-data
property to be more easily
configured using config files.
The script does this in two ways:
user-data
fields can be set on startup using config files.user-data
fields can be set during runtime usingscript-opts
.
Changing Properties at Startup
There are a few different ways of setting
user-data
fields at startup.
Config File
~~/script-opts/user-data.conf
This is a config file that uses the standard
script config syntax
of <key>=<value>
.
key
is the path to the user-data
field that will be modified, e.g.
script_name/visibility
.
value
is the JSON formatted value that will be set to that field.
The key cannot contain any =
characters, however you can
use escaped character sequences
to substitute them.
user-data.conf
example:
# comment
script_name/visibility=true
script2/number-of-items=21
script2/text/header="header text"
user-data
output:
{
"script_name": {
"visibility":true
},
"script2": {
"number-of-items": 21,
"text": {
"header": "header text"
}
}
}
Escaped Character Sequences
These are character sequences that can be included in the
key to handle characters that cannot be typed directly.
The ~0
sequence is only necessary to escape the other
sequences, e.g., if you want the output to be param~1
you
would use param~01
.
The ~1
sequence is currently useless as /
characters can
be used directly. However, it is reserved for the future in case
it becomes possible to include /
characters in the name
of a user-data
field. This is technically allowed by user-data
already, but is not supported when trying to access the property
directly (set
/del
commands, property expansion, property observation, etc).
sequence | output |
---|---|
~0 | ~ |
~1 | / |
~2 | \n - newline |
~3 | \r - carriage return |
~4 | = |
These sequences are based and extended from RFC 6901. It is possible additional character sequences are added in the future
JSON Config File
~~/script-opts/user-data.json
This config file uses JSON syntax, which should make it
easier to define highly nested user-data
values.
The file represents the full user-data
property,
so to replicate the previous example
the json file could simply contain:
{
"script_name": { "visibility":true },
"script2": {
"number-of-items": 21,
"text": { "header": "header text" }
}
}
Note that all of the top-level fields (e.g. script_name
and script2
)
directly overwrite the existing value in user-data
.
This means that if script_name/other_field
exists in user-data
,
it will be removed after "script_name": { "visibility":true }
is applied.
This will likely change in the future.
The JSON file can be used in conjunction with user-data.conf
.
The JSON file will be applied first, so will not overwrite
the values set in user-data.conf
.
script-opts
The script-opts
property can also be set at startup using mpv.conf
or with
commandline arguments. See
changing properties at runtime for
the correct syntax.
Values set with script-opts always overwrite the config files.
Changing Properties at Runtime
user-data
fields can be modified at runtime using
script-opts
.
This allows the fields to be set from the commandline, from
mpv.conf
, and from profiles, including
conditional auto profiles.
The script-opt is in the form user-data/path/to/field=<JSON value><parameters>
.
It is nearly identical to the user-data.conf
syntax, except that
the keys must be prefixed with user-data/
and a list of parameters can optionally
be appended to the end (see script-opt parameters).
Escaped character sequences are supported for the key.
If a script-opt
is removed, then the associated user-data
field is
reset to the value it had when the first script-opt was applied.
This behaviour can be changed with the restore
parameter.
If, by some unfortunate coincidence, you are using a script that uses the
user-
prefix (or perhaps you just prefer underscores)
you can substitute the -
for a _
, e.g. user_data/path/to/field=<JSON value>
.
script-opt parameters
Parameters are a list of optional key-value pairs appended after the
JSON value in the form <key>=<value>
. Whitespace around the =
is allowed and
parameters can be separated from the JSON value (and each other) using any
character except the following: a-zA-Z0-9_-
.
Here are some examples with valid syntax:
script-opts-append=user-data/script_name/visibility=true|param=val|param2=val
script-opts-append=user-data/script2/num=21: param = val param2=val
script-opts-append=user-data/script2/text/header="header text" param = val
Currently there is only one parameter, restore
, which
behaves similarly to the mpv
profile-restore
option.
restore
This parameter controls what happens when the script-opt is removed. There are three options:
option | description |
---|---|
copy | Copy the original value of the field and restore it when the script-opt is removed (default). |
copy-equal | Copy the original value, but only restore if the current field value is equal to the value set by the script-opt. |
no | Do not do anything when the script-opt is removed. |
Currently, if a script-opt is changed instead of removed,
then only the restore
value of the original script-opt is
considered (unless that original value was no
).
This may change in the future.
Examples
mpv.conf
script-opts-append=user-data/script_name/visibility=true
script-opts-append=user-data/script2/number-of-items=21
script-opts-append=user-data/script2/text/header="header text"
Applying the script-opts with a profile:
[profile1]
script-opts-append=user-data/script_name/visibility=true
script-opts-append=user-data/script2/number-of-items=21
script-opts-append=user-data/script2/text/header="header text"
Conditional Auto Profiles
Sets a primary-monitor
field based on the
monitor the mpv window is currently displayed on.
The default value would be better placed in user-data.conf
where the restore=no
would not be necessary. It has been
placed here to make the example easier to read.
# sets the default value (probably better to do this is a config file)
script-opts-append=user-data/primary-monitor=false|restore=no
[PrimaryMonitor]
profile-cond=display_names[1] == 'DP-1'
script-opts-append=user-data/primary-monitor=true|restore=copy-equal
[OtherMonitor]
profile-cond=display_names[1] ~= 'DP-1'
script-opts-remove=user-data/primary-monitor
Uses user-data property expansion to append PRIMARY MONITOR
to the
title of the mpv window:
title='${?media-title:${media-title}}${!media-title:No file} - mpv${?user-data/primary-monitor: - PRIMARY MONITOR}'
[PrimaryMonitor]
profile-cond=display_names[1] == 'DP-1'
script-opts-append=user-data/primary-monitor=true|restore=copy-equal
[OtherMonitor]
profile-cond=display_names[1] ~= 'DP-1'
script-opts-remove=user-data/primary-monitor
Commandline
mpv --script-opts-append='user-data/script_name/visibility=true' \
--script-opts-append='user-data/script2/number-of-items=21' \
--script-opts-append='user-data/script2/text/header="header text"'
Make sure that the "
characters around strings are not stripped by the shell.