-
Notifications
You must be signed in to change notification settings - Fork 0
API
easympv features a JSON-based API which can be used by other mpv plugins to access easympv features.
The way this works is similar to APIs on the web.
A plugin (we will refer to this as sender
) sends a request to easympv and receives a response, where requests and responses are matched by a context
.
The basic command looks like this:
mp.commandv("script-message-to",TARGET,DATA1,DATA2[,DATAn...]);
Where TARGET
is the recipient.
The DATA
arguments are completely arbitrary and are chosen by the recipient.
Let's fill in the blanks:
mp.commandv("script-message-to","easympv","json",JSON.stringify(REQUEST_OBJECT_GOES_HERE));
- As you can see, the recipient is simply
easympv
. It is possible for plugins to set custom names, but by default it is just the script name. - easympv uses the first data argument as a message type. Currently only
json
is implemented. This is because easympv might add another, lua-friendlier message type down the line. - Finally, a JSON string containing the actual request.
A request generally looks like this:
{
"sender": "YOUR_SCRIPT_NAME_GOES_HERE",
"context": "ID_GOES_HERE",
"command": "COMMAND_GOES_HERE",
"arguments": {
"some": "data",
[...]
}
}
arguments
can also be an empty object.
See the examples below for more information.
For more information on script-message-to
read the official mpv documentation (CTRL+F for it).
easympv responds the same way it expects requests, that is TARGET
,json
,JSON_RESPONSE
.
In order to handle this, register a script message for easympv-response
:
mp.register_script_message("easympv-response", HANDLER_FUNCTION_GOES_HERE);
The handler function takes one argument, which will be the JSON_RESPONSE
.
Note that it will be in string form, so you probably want to JSON.parse()
it.
Now for the actual structure of a generic JSON_RESPONSE:
{
"result": STATUS_GOES_HERE,
"context": ID_GOES_HERE
}
result
will be one of these strings:
-
success
, your request was processed correctly -
error
, something is wrong with your request (or you found an easympv bug)
context
is copied from the request. This is so you can match request and response.
Keep in mind that this is just the generic response, depending on the actual command the response might look a bit different.
List of implemented commands:
Command |
---|
createmenu |
removemenu |
This command lets any plugin create a menu in easympv.
At least for now, these menus are immutable after creation.
One way around this would be to first remove and then recreate a menu to change its values.
When the user interacts with such a menu, a JSON string containing the actions will be sent to sender
.
Using the previously designated context
, a pseudo-callback function can be created to react accordingly.
Command | Argument(s) |
---|---|
createmenu |
JSON object |
The JSON object should look like this:
- Key "menuName" -> String
- Key "menuSettings" -> Object
- Same as native menus
- Key "menuItems" -> Array of Objects
- Same as native menus
{
"sender": "your-script-name-here",
"context": "my-super-unique-id",
"command": "createmenu",
"arguments": {
"menuName": "My Awesome Menu",
"menuSettings": {
"title": "My Awesome Title",
"description": "My Awesome Description",
"descriptionColor": "ff0000"
},
"menuItems": [
{
"title": "Option 1",
"item": "option1"
},
{
"title": "Option 2",
"item": "option2"
}
]
}
}
The sender
will receive an immediate generic response.
The user pressed enter on "Option 1":
{
"sender": "easympv",
"context": "my-super-unique-id",
"data": {
"event": "enter",
"action": "option1"
}
}
This command lets a plugin remove a previously created menu.
It will only work if the sender
is also the owner of the menu.
Command | Argument(s) |
---|---|
removemenu |
None (empty object) |
The menu is not identified by its name, but rather by its associated owner (sender
) and context
.
This would remove the menu we created in the previous example.
{
"sender": "your-script-name-here",
"context": "my-super-unique-id",
"command": "removemenu",
"arguments": {}
}
The sender
will receive an immediate generic response.