player/command: refactor loadfile and loadlist commands to use flags

DOCS/interface-changes/loadfile-refactor.txt

@@ -0,0 +1 @@
+the `loadfile` and `loadlist` commands can now take multiple flags (i.e. `append+play`)

DOCS/man/input.rst

@@ -553,29 +553,44 @@ Playlist Manipulation
         Stop playback of the current file, and play the new file immediately.
     <append>
         Append the file to the playlist.
+    <insert-next>
+        Insert the file into the playlist, directly after the current entry.
+    <insert-at>
+        Insert the file into the playlist, at the index given in the third
+        argument.
+    <play>
+        If nothing is currently playing, start playback. (Always starts with the
+        added file, even if the playlist was not empty before running this
+        command).
+
+    Multiple flags can be combined, e.g.: ``append+play``.
+
+    By default, ``append``, ``insert-next``, and ``insert-at`` will not
+    immediately start playback even if the playlist was previously empty. Adding
+    the ``play`` flag to them forces playback to start.
+
+    The following values are considered deprecated and were the old way
+    (before mpv 0.41) of forcing playback to start before the ``play`` flag was
+    added.
+
     <append-play>
         Append the file, and if nothing is currently playing, start playback.
         (Always starts with the added file, even if the playlist was not empty
         before running this command.)
-    <insert-next>
-        Insert the file into the playlist, directly after the current entry.
     <insert-next-play>
         Insert the file next, and if nothing is currently playing, start playback.
         (Always starts with the added file, even if the playlist was not empty
         before running this command.)
-    <insert-at>
-        Insert the file into the playlist, at the index given in the third
-        argument.
     <insert-at-play>
         Insert the file at the index given in the third argument, and if nothing
         is currently playing, start playback. (Always starts with the added
         file, even if the playlist was not empty before running this command.)
 
-    The third argument is an insertion index, used only by the ``insert-at`` and
-    ``insert-at-play`` actions. When used with those actions, the new item will
-    be inserted at the index position in the playlist, or appended to the end if
-    index is less than 0 or greater than the size of the playlist. This argument
-    will be ignored for all other actions. This argument is added in mpv 0.38.0.
+    The third argument is an insertion index, used only by the ``insert-at``
+    action. When used with those actions, the new item will be inserted at the
+    index position in the playlist, or appended to the end if index is less than
+    0 or greater than the size of the playlist. This argument will be ignored for
+    all other actions. This argument was added in mpv 0.38.0.
 
     The fourth argument is a list of options and values which should be set
     while the file is playing. It is of the form ``opt1=value1,opt2=value2,..``.
@@ -601,30 +616,45 @@ Playlist Manipulation
         Stop playback and replace the internal playlist with the new one.
     <append>
         Append the new playlist at the end of the current internal playlist.
+    <insert-next>
+        Insert the new playlist into the current internal playlist, directly
+        after the current entry.
+    <insert-at>
+        Insert the new playlist at the index given in the third argument.
+    <play>
+        If nothing is currently playing, start playback. (Always starts with the
+        added playlist, even if the internal playlist was not empty before running
+        this command).
+
+    Multiple flags can be combined, e.g.: ``append+play``.
+
+    By default, ``append``, ``insert-next``, and ``insert-at`` will not
+    immediately start playback even if the playlist was previously empty. Adding
+    the ``play`` flag to them forces playback to start.
+
+    The following values are considered deprecated and were the old way
+    (before mpv 0.41) of forcing playback to start before the ``play`` flag was
+    added.
+
     <append-play>
         Append the new playlist, and if nothing is currently playing, start
         playback. (Always starts with the new playlist, even if the internal
         playlist was not empty before running this command.)
-    <insert-next>
-        Insert the new playlist into the current internal playlist, directly
-        after the current entry.
     <insert-next-play>
         Insert the new playlist, and if nothing is currently playing, start
         playback. (Always starts with the new playlist, even if the internal
         playlist was not empty before running this command.)
-    <insert-at>
-        Insert the new playlist at the index given in the third argument.
     <insert-at-play>
         Insert the new playlist at the index given in the third argument, and if
         nothing is currently playing, start playback. (Always starts with the
         new playlist, even if the internal playlist was not empty before running
         this command.)
 
-    The third argument is an insertion index, used only by the ``insert-at`` and
-    ``insert-at-play`` actions. When used with those actions, the new playlist
-    will be inserted at the index position in the internal playlist, or appended
-    to the end if index is less than 0 or greater than the size of the internal
-    playlist. This argument will be ignored for all other actions.
+    The third argument is an insertion index, used only by the ``insert-at`` action.
+    When used with those actions, the new playlist will be inserted at the index
+    position in the internal playlist, or appended to the end if index is less
+    than 0 or greater than the size of the internal playlist. This argument will be
+    ignored for all other actions. This argument was added in mpv 0.38.0.
 
 ``playlist-clear``
     Clear the playlist, except the currently played file.

player/command.c

@@ -6069,21 +6069,17 @@ static void cmd_escape_ass(void *p)
 
 static struct load_action get_load_action(struct MPContext *mpctx, int action_flag)
 {
-    switch (action_flag) {
-    case 0: // replace
-        return (struct load_action){LOAD_TYPE_REPLACE, .play = true};
-    case 1: // append
-        return (struct load_action){LOAD_TYPE_APPEND, .play = false};
-    case 2: // append-play
-        return (struct load_action){LOAD_TYPE_APPEND, .play = true};
-    case 3: // insert-next
-        return (struct load_action){LOAD_TYPE_INSERT_NEXT, .play = false};
-    case 4: // insert-next-play
-        return (struct load_action){LOAD_TYPE_INSERT_NEXT, .play = true};
-    case 5: // insert-at
-        return (struct load_action){LOAD_TYPE_INSERT_AT, .play = false};
-    case 6: // insert-at-play
-        return (struct load_action){LOAD_TYPE_INSERT_AT, .play = true};
+    int type = action_flag & 3;
+    bool play = (action_flag >> 3) & 1;
+    switch (type) {
+    case 0:
+        return (struct load_action){LOAD_TYPE_REPLACE, .play = play};
+    case 1:
+        return (struct load_action){LOAD_TYPE_APPEND, .play = play};
+    case 2:
+        return (struct load_action){LOAD_TYPE_INSERT_NEXT, .play = play};
+    case 3:
+        return (struct load_action){LOAD_TYPE_INSERT_AT, .play = play};
     default: // default: replace
         return (struct load_action){LOAD_TYPE_REPLACE, .play = true};
     }
@@ -7389,14 +7385,16 @@ const struct mp_cmd_def mp_cmds[] = {
     { "loadfile", cmd_loadfile,
         {
             {"url", OPT_STRING(v.s)},
-            {"flags", OPT_CHOICE(v.i,
-                {"replace", 0},
-                {"append", 1},
-                {"append-play", 2},
-                {"insert-next", 3},
-                {"insert-next-play", 4},
-                {"insert-at", 5},
-                {"insert-at-play", 6}),
+            {"flags", OPT_FLAGS(v.i,
+                {"replace", 4|0},
+                {"append", 4|1},
+                {"insert-next", 4|2},
+                {"insert-at", 4|3},
+                {"play", 32|8},
+                // backwards compatibility
+                {"append-play", (4|1) + (16|8)},
+                {"insert-next-play", (4|2) + (16|8)},
+                {"insert-at-play", (4|3) + (16|8)}),
                 .flags = MP_CMD_OPT_ARG},
             {"index", OPT_INT(v.i), OPTDEF_INT(-1)},
             {"options", OPT_KEYVALUELIST(v.str_list), .flags = MP_CMD_OPT_ARG},
@@ -7405,14 +7403,16 @@ const struct mp_cmd_def mp_cmds[] = {
     { "loadlist", cmd_loadlist,
         {
             {"url", OPT_STRING(v.s)},
-            {"flags", OPT_CHOICE(v.i,
-                {"replace", 0},
-                {"append", 1},
-                {"append-play", 2},
-                {"insert-next", 3},
-                {"insert-next-play", 4},
-                {"insert-at", 5},
-                {"insert-at-play", 6}),
+            {"flags", OPT_FLAGS(v.i,
+                {"replace", 4|0},
+                {"append", 4|1},
+                {"insert-next", 4|2},
+                {"insert-at", 4|3},
+                {"play", 32|8},
+                // backwards compatibility
+                {"append-play", (4|1) + (16|8)},
+                {"insert-next-play", (4|2) + (16|8)},
+                {"insert-at-play", (4|3) + (16|8)}),
                 .flags = MP_CMD_OPT_ARG},
             {"index", OPT_INT(v.i), OPTDEF_INT(-1)},
         },

player/lua/commands.lua

@@ -335,8 +335,7 @@ local function command_flags_at_2nd_argument_list(command)
     local flags = {
         ["apply-profile"] = {"apply", "restore"},
         ["frame-step"] = {"play", "seek", "mute"},
-        ["loadfile"] = {"replace", "append", "append-play", "insert-next",
-                        "insert-next-play", "insert-at", "insert-at-play"},
+        ["loadfile"] = {"replace", "append", "insert-next", "insert-at", "play"},
         ["screenshot-to-file"] = {"subtitles", "video", "window", "each-frame"},
         ["screenshot-raw"] = {"bgr0", "bgra", "rgba", "rgba64"},
         ["seek"] = {"relative", "absolute", "absolute-percent",