API

Introduction

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.

Sending Requests

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

Handling Responses

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.

Commands

List of implemented commands:

Command
createmenu
removemenu

Create Menu

Purpose

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.

Syntax

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

Example Request

{
    "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.

Example Response

The user pressed enter on "Option 1":

{
    "sender": "easympv",
    "context": "my-super-unique-id",
    "data": {
        "event": "enter",
        "action": "option1"
    }
}

Remove Menu

Purpose

This command lets a plugin remove a previously created menu.
It will only work if the sender is also the owner of the menu.

Syntax

Command	Argument(s)
removemenu	None (empty object)

The menu is not identified by its name, but rather by its associated owner (sender) and context.

Example Request

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.