client API: add a client message event

This comes with a "script_message" input command, which sends these
messages. Used by the following commits.

DOCS/man/en/lua.rst

@@ -287,3 +287,9 @@ List of events
 
 ``command-reply``
     Undocumented (not useful for Lua scripts).
+
+``script-input-dispatch``
+    Undocumented (used internally).
+
+``client-message``
+    Undocumented (used internally).

input/cmd_list.c

@@ -167,6 +167,8 @@ const struct mp_cmd_def mp_cmds[] = {
   { MP_CMD_VO_CMDLINE, "vo_cmdline", { ARG_STRING } },
 
   { MP_CMD_SCRIPT_DISPATCH, "script_dispatch", { ARG_STRING, ARG_INT } },
+  { MP_CMD_SCRIPT_MESSAGE, "script_message", { ARG_STRING, ARG_STRING },
+    .vararg = true },
 
   { MP_CMD_OVERLAY_ADD, "overlay_add",
       { ARG_INT, ARG_INT, ARG_INT, ARG_STRING, ARG_INT, ARG_STRING, ARG_INT,

input/cmd_list.h

@@ -98,6 +98,7 @@ enum mp_command_type {
 
     /// Internal for Lua scripts
     MP_CMD_SCRIPT_DISPATCH,
+    MP_CMD_SCRIPT_MESSAGE,
 
     MP_CMD_OVERLAY_ADD,
     MP_CMD_OVERLAY_REMOVE,

libmpv/client.h

@@ -615,6 +615,13 @@ typedef enum mpv_event_id {
      * to a client.
      */
     MPV_EVENT_SCRIPT_INPUT_DISPATCH = 15,
+    /**
+     * Triggered by the script_message input command. The command uses the
+     * first argument of the command as client name (see mpv_client_name()) to
+     * dispatch the message, and passes along the all arguments starting from
+     * the seconand argument as strings.
+     */
+    MPV_EVENT_CLIENT_MESSAGE    = 16,
 } mpv_event_id;
 
 /**
@@ -687,6 +694,17 @@ typedef struct mpv_event_script_input_dispatch {
     const char *type;
 } mpv_event_script_input_dispatch;
 
+typedef struct mpv_event_client_message {
+    /**
+     * Arbitrary arguments chosen by the sender of the message. If num_args > 0,
+     * you can access args[0] through args[num_args - 1] (inclusive). What
+     * these arguments mean is up to the sender and receiver.
+     * None of the valid items is NULL.
+     */
+    int num_args;
+    const char **args;
+} mpv_event_client_message;
+
 typedef struct mpv_event {
     /**
      * One of mpv_event. Keep in mind that later ABI compatible releases might
@@ -712,6 +730,7 @@ typedef struct mpv_event {
      *  MPV_EVENT_GET_PROPERTY_REPLY:     mpv_event_property*
      *  MPV_EVENT_LOG_MESSAGE:            mpv_event_log_message*
      *  MPV_EVENT_SCRIPT_INPUT_DISPATCH:  mpv_event_script_input_dispatch*
+     *  MPV_EVENT_CLIENT_MESSAGE:         mpv_event_client_message*
      *  other: NULL
      *
      * Note: future enhancements might add new event struct for existing or new

player/client.c

@@ -841,6 +841,7 @@ static const char *event_table[] = {
     [MPV_EVENT_UNPAUSE] = "unpause",
     [MPV_EVENT_TICK] = "tick",
     [MPV_EVENT_SCRIPT_INPUT_DISPATCH] = "script-input-dispatch",
+    [MPV_EVENT_CLIENT_MESSAGE] = "client-message",
 };
 
 const char *mpv_event_name(mpv_event_id event)

player/command.c

@@ -3200,6 +3200,22 @@ void run_command(MPContext *mpctx, mp_cmd_t *cmd)
         break;
     }
 
+    case MP_CMD_SCRIPT_MESSAGE: {
+        mpv_event_client_message *event = talloc_ptrtype(NULL, event);
+        *event = (mpv_event_client_message){0};
+        for (int n = 1; n < cmd->nargs; n++) {
+            MP_TARRAY_APPEND(event, event->args, event->num_args,
+                             cmd->args[n].v.s);
+        }
+        if (mp_client_send_event(mpctx, cmd->args[0].v.s,
+                                 MPV_EVENT_CLIENT_MESSAGE, event) < 0)
+        {
+            MP_VERBOSE(mpctx, "Can't find script '%s' for %s.\n",
+                       cmd->args[0].v.s, cmd->name);
+        }
+        break;
+    }
+
 #if HAVE_SYS_MMAN_H
     case MP_CMD_OVERLAY_ADD:
         overlay_add(mpctx,

player/lua.c

@@ -421,9 +421,22 @@ static int script_wait_event(lua_State *L)
         lua_setfield(L, -2, "type"); // event
         break;
     }
+    case MPV_EVENT_CLIENT_MESSAGE: {
+        mpv_event_client_message *msg = event->data;
+
+        lua_newtable(L); // event args
+        for (int n = 0; n < msg->num_args; n++) {
+            lua_pushinteger(L, n + 1); // event args N
+            lua_pushstring(L, msg->args[n]); // event args N val
+            lua_settable(L, -3); // event args
+        }
+        lua_setfield(L, -2, "args"); // event
+        break;
+    }
     default: ;
     }
 
+    // return event
     return 1;
 }