The breaking changes in libmpv 0.38 were a little rough

[leon-costa]

Hello,

First of all, I'd like to thank the authors and contributors of mpv. It's a wonderful program that I've been using almost daily for years, both as a player and as a library.

I use libmpv to embed video into an application and 2 breaking changes in 0.38 were somewhat difficult to fix. I had to bisect mpv to find out exactly what was going on and how to fix my program. I understand that breaking changes are sometimes necessary, and the compatibility policy in the doc looks pretty good to me, but it might be beneficial to make these breaking changes easier to handle.

The first breaking change I had to fix was the change to the arguments of the loadfile command. A new argument has been introduced before the options argument, breaking compatibility with any software that passes options to loadfile. It is listed in the interface changes, but slightly hidden among many smaller or non-breaking changes.

Also, the compatibility policy states that "important/often used parts must be deprecated for at least 2 releases before they can be broken". loadfile is certainly an important and often used part. Passing options to it may not be used as often, but it's still an important part of this important command.

Adding the new argument at the end (or making it an option) would have completely avoided this breaking change. But now that the release is done, it's probably too late to change. So all programs that pass options to loadfile now require a change, and those that are not tied to a specific version of libmpv have to handle both cases.

The second breaking change was the removal of libmpv as the default VO. It is listed in the client api changes, but it was difficult for me to understand if it was the cause of my problem and how to fix it. Because libmpv was the default VO, it was never documented that you had to set the VO when embedding mpv in an application. But now all those applications need to do it. All the libmpv examples that embed a player are probably broken (I only tried the SDL one and it indeed renders the video in an external window). The fix was pretty simple (add a mpv_set_option_string(mpv, "vo", "libmpv")), but it was not obvious when I read the client api change note.

My application is now fixed, but could we make future breaking changes easier to manage? This could include:

• Highlighting breaking changes in interface-changes.rst, perhaps by moving them to a specific section separated from the non-breaking changes.
• Explaining what needs to be done to adapt to the changes if it's not obvious.
• Mention the breaking changes in the release notes.
• Avoid breaking changes whenever possible, and follow the compatibility policy more closely when you can't.

I think these suggestions would help reduce potential frustrations when updating to a new version. Let me know if there's anything I can do to help.

[verygoodlee]

for the loadfile syntax change, we can use command-list to get the arguments of loadfile, if the index argument is present, use new syntax, otherwise use old syntax.
just like this commit kjtsune/embyToLocalPlayer@9d77e0e , it's a python project to control mpv by JSON IPC.

contributors have tried to solve compatibility issue but failed #13624

[kasper93]

Related issue #14022

Another related comment: c678033#commitcomment-141497165 with hacks for plex compatibility.

[Almamu]

The second breaking change was the removal of libmpv as the default VO. It is listed in the client api changes, but it was difficult for me to understand if it was the cause of my problem and how to fix it. Because libmpv was the default VO, it was never documented that you had to set the VO when embedding mpv in an application. But now all those applications need to do it. All the libmpv examples that embed a player are probably broken (I only tried the SDL one and it indeed renders the video in an external window). The fix was pretty simple (add a mpv_set_option_string(mpv, "vo", "libmpv")), but it was not obvious when I read the client api change note.

I've gotta be honest, as someone that is using libmpv embedded in a different application I'm really thankful that I stumbled upon this discussion, otherwise I would have spent hours trying to identify why suddenly my app opens a new window instead of rendering things how it should! It doesn't help that most examples don't mention what a VO is or what it is for, and the fact that I wrote the code for using libmpv some time ago I didn't even remember how it was supposed to work.

One thing that I feel could have eased the pain in a breaking change like this is for the changelog to include a bit more information on what the change implies or what a developer might observe after the update... I don't know, something that makes it a little easier to identify if it affects my use-case or not.

[MystEr3-84]

Hi @leon-costa and @Almamu,
on which os are you?
I've the same problem of the mpv (0.39.0) embedded that is opening in another window. But if I set the vo to libmpv I have sound but no video. I am on MacBook Pro M3 (Sonoma 14.1).
Best regards