Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/CogentRedTester/mpv-user-data-loader

A script that allows the mpv `user-data` property to be set at launch and runtime using config files.
https://github.com/CogentRedTester/mpv-user-data-loader

configuration mpv-player mpv-script

Last synced: about 2 months ago
JSON representation

A script that allows the mpv `user-data` property to be set at launch and runtime using config files.

Awesome Lists containing this project

README 

        
# 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 using `script-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](https://mpv.io/manual/master/#lua-scripting-on-update]]%29)

of `=`.



`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](#escaped-character-sequences)

to substitute them.



`user-data.conf` example:



```properties

# comment

script_name/visibility=true

script2/number-of-items=21

script2/text/header="header text"

```



`user-data` output:

```json

{

    "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:



```json

{

    "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`](https://mpv.io/manual/master/#options-script-opts)

property can also be set at startup using `mpv.conf` or with

commandline arguments. See

[changing properties at runtime](#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`](https://mpv.io/manual/master/#options-script-opts).

This allows the fields to be set from the commandline, from

`mpv.conf`, and from profiles, including

[conditional auto profiles](https://mpv.io/manual/master/#conditional-auto-profiles).



The script-opt is in the form `user-data/path/to/field=`.

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](#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](#restore).



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=`.



### script-opt parameters

Parameters are a list of optional key-value pairs appended after the

JSON value in the form `=`. 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:



```properties

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`](https://mpv.io/manual/master/#runtime-profiles)

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`



```properties

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:

```properties

[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.



```properties

# 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:



```properties

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



```bash

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.