player/command: refactor loadfile and loadlist to be more flexible by kasper93 · Pull Request #17458 · mpv-player/mpv

kasper93 · 2026-02-26T18:44:22Z

No description provided.

DOCS/man/input.rst

kasper93 · 2026-02-27T07:03:41Z

This needs some testing, but this would be my idea to make it more flexible. Same as the old #15927, but using old commands. Back then I wanted to have master command for everything, but we might start with loadfile/loadlist.

This mostly allows replace to work on single playlist elements, instead of nuking whole playlist. Additionally adds few helpful position helpers, so we can do insert+prev or insert+first and so on. The idea is stolen from #17250, but using separate flags, instead of mangling position into action.

Some combinations of flags naturally doesn't make sense, insert+prev+next, it is not defined what exactly will happen, but it depends on the order of checking. Technically we could sanitize flags, but not sure if there is needed in practice, if user do silly things they get silly output, nothing breaks.

I didn't test this thoroughly, but should work. When requested position is not found we show warning and file is appended at the end. Same as previously would.

Comments welcome, if that's something that is useful and how to make it better.

guidocella · 2026-02-27T10:36:51Z

Having both prepend and insert+first is redundant, it just makes it harder to learn the interface.

You can also explain that index defaults to -1 and thus replace defaults to clearing the playlist.

Is it feasible to pass next/current/first/last in the index field?

kasper93 · 2026-02-27T19:37:22Z

Having both prepend and insert+first is redundant, it just makes it harder to learn the interface.

It's there to mirror append command. I don't mind deprecating it. Though, it seems simpler to remember append to me.

You can also explain that index defaults to -1 and thus replace defaults to clearing the playlist.

Isn't this enough?

There is special case where, by default (``replace+at`` and ``index`` == ``-1``), the whole playlist is cleared and the file is added as the only entry.

Is it feasible to pass next/current/first/last in the index field?

Yes, I can try that.

guidocella · 2026-02-27T19:53:47Z

It's there to mirror append command. I don't mind deprecating it. Though, it seems simpler to remember append to me.

That's fair though the duplication is annoying. Not sure what is better.

Isn't this enough?

There is special case where, by default (``replace+at`` and ``index`` == ``-1``), the whole playlist is cleared and the file is added as the only entry.

Sorry I missed "by default".

kasper93 · 2026-02-27T21:34:51Z

Updated to move relative position flags to index argument.

github-actions · 2026-02-27T22:32:44Z

Download the artifacts for this pull request:

Windows

macOS

DOCS/man/input.rst

na-na-hi · 2026-02-28T01:34:36Z

DOCS/man/input.rst

+    <prepend>
+        Prepend the file to the playlist.


As mentioned there is no reason for this to exist. append is grandfathered and I do not see it a reason to add this. If you want "mirroring" I would rather deprecate append.

We can deprecate append instead, but I would like to hear others opinion.

I think insert 0 require user to understand array indexing and have mental model of array manipulation. Not everyone is "programmer" and prepend/append is natural language understood by anyone.

Like insert -1 may do the append, it's technically the same thing, but this wouldn't be my first guess when I was trying to append, without preexisting knowledge.

I think insert 0 require user to understand array indexing and have mental model of array manipulation.

We can just document insert 0 and insert -1 as example usage to achieve the effect of prepend/append.

While deprecating append is unfortunate I found the API overwhelming at first. Also prepending to the playlist is an extremely niche use case so it doesn't need to be super convenient. (--playlist-start also has this 0 index issue).

The docs say appending is the default for insert without index so why would you need to pass -1? In fact in this case you can just make append a deprecated alias for insert and it will insert at the end by default.

I've removed all the helper names from documentation. I'm still not sure what's so bad in providing shortcuts like that.

na-na-hi · 2026-02-28T01:46:29Z

DOCS/man/input.rst

+    <next>
+        Next playlist entry after the current one.
+    <prev>
+        Previous playlist entry before the current one.
+    <current>
+        The current playlist entry. With ``insert`` action.
+    <first>
+        The first playlist entry.
+    <last>
+        The last playlist entry.


There is no reason for any of these to exist. They can be expressed as 0 or -1 or calculated from playlist-pos.

It's way easier to type loadfile <file> insert next instead of doing the math on playlist-pos in script. It doesn't cost anything to support those aliases. Especially if playlist-pos is not yet available, this command handles this too.

It's way easier to type loadfile <file> insert next instead of doing the math on playlist-pos in script.

There is no math involved other than prev. current is playlist-pos and next is playlist-pos-1, both are usable in input.conf without script. And even for the case for prev in input.conf, a general mechanism for more numeric manipulation capability in property expansion is better and can be useful for many more cases.

It doesn't cost anything to support those aliases.

We have enough backwards compatibility baggage already for the loadfile flags. There is no reason to add even more when we know they are redundant.

Especially if playlist-pos is not yet available, this command handles this too.

This only happens in idle mode when there is no "current item" in the playlist. next, prev, and current are meaningless at this state.

I agree on not adding more legacy baggage and note that for the longest time loadfile only had append and replace, inserting at specific positions is very niche so it doesn't need convenient aliases.

There is no math involved other than prev. current is playlist-pos and next is playlist-pos-1, both are usable in input.conf without script.

next being playlist-pos-1, is just a workaround of inability of doing math. But, like said, I've removed all helpers. They still exists in the code naturally, for backward compatibility, just not exposed for the users, if that's what you prefer.

a general mechanism for more numeric manipulation capability in property expansion is better

This is just moving the bar. This is simple PR for loadfile/loadlist, not adding math to property expansion. I understand that it would be useful, but out of the scope.

na-na-hi · 2026-02-28T01:48:46Z

DOCS/man/input.rst

        this command.)

-    The third argument is an insertion index, used only by the ``insert-at`` action.
+    The third argument is an insertion index, used only by the ``insert+at`` action.


Why does this only work with insert but not replace like loadfile does?

Also there is no flag called at here.

Why does this only work with insert but not replace like loadfile does?

Because replace doesn't make sense for loadlist except when replacing whole playlist. Unlike loadfile which work on single files basis.

Also there is no flag called at here.

Thanks, will remove.

Because replace doesn't make sense for loadlist except when replacing whole playlist.

It makes sense by replacing multiple consecutive items from the same loaded playlist (same playlist-path). It essentially replaces all videos from a "sub playlist".

I didn't consider such complex usecase to be useful, but sure, added subset replace now.

It seems that the current implementation just replaces all future entries instead of checking playlist-path? Anyway I think the proposal is overkill. loadlist can just replace the current entry. The only difference between loadfile and loadlist is that loadlist append expands playlists before playing them so I don't think replacing the current entry makes more or less sense with loadlist. In fact this behavior should just be a loadfile flag instead of duplicating the whole command.

I think the new API is simpler to digest and more flexible overall.

player/command.c

Replace not only stops the current file playback, but also clear whole playlist before staring the new file playback.

By allowing more flexible flags combinations we can replace current single playlist entry, instead of replacing whole thing. And on top of that adds convinience positional flags, while refactoring everything to be use enum flags, instead of hardcoded values.

guidocella · 2026-03-03T10:13:16Z

player/lua/commands.lua

        ["apply-profile"] = {"apply", "restore"},
        ["frame-step"] = {"play", "seek", "mute"},
-        ["loadfile"] = {"replace", "append", "insert-next", "insert-at", "play"},
+        ["loadfile"] = {"replace", "insert", "play", "prepend", "append"},


Needs updating

na-na-hi reviewed Feb 27, 2026

View reviewed changes

DOCS/man/input.rst Outdated Show resolved Hide resolved

kasper93 force-pushed the loadfile-replace-current branch from ad02260 to 0b8eea9 Compare February 27, 2026 06:55

kasper93 force-pushed the loadfile-replace-current branch from 0b8eea9 to 27f27c2 Compare February 27, 2026 07:04

kasper93 changed the title ~~player/command: add replace-current flag to loadfile command~~ player/command: refactor loadfile and loadlist to be more flexible Feb 27, 2026

kasper93 force-pushed the loadfile-replace-current branch 2 times, most recently from 43156d1 to fc6f697 Compare February 27, 2026 21:34

kasper93 force-pushed the loadfile-replace-current branch 3 times, most recently from fe6683e to ce52ae0 Compare February 27, 2026 22:11

kasper93 force-pushed the loadfile-replace-current branch from ce52ae0 to 9e2688a Compare February 27, 2026 23:03

kasper93 requested review from Dudemanguy and na-na-hi and removed request for na-na-hi February 27, 2026 23:23

na-na-hi reviewed Feb 28, 2026

View reviewed changes

kasper93 force-pushed the loadfile-replace-current branch from 9e2688a to 4794d57 Compare February 28, 2026 02:05

kasper93 added 2 commits March 3, 2026 04:06

DOCS/man/input: fix loadfile replace docs

2422db7

Replace not only stops the current file playback, but also clear whole playlist before staring the new file playback.

kasper93 force-pushed the loadfile-replace-current branch from 4794d57 to 40fefd0 Compare March 3, 2026 03:06

kasper93 requested review from guidocella and na-na-hi March 3, 2026 06:47

guidocella reviewed Mar 3, 2026

View reviewed changes

Conversation

kasper93 commented Feb 26, 2026

Uh oh!

Uh oh!

kasper93 commented Feb 27, 2026

Uh oh!

guidocella commented Feb 27, 2026

Uh oh!

kasper93 commented Feb 27, 2026

Uh oh!

guidocella commented Feb 27, 2026

Uh oh!

kasper93 commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kasper93 commented Feb 27, 2026 •

edited

Loading

github-actions bot commented Feb 27, 2026 •

edited

Loading