SDL_mixer, as far as my flaky memory can recall, was written at Loki because SimCity 3000 needed something more advanced than SDL 1.2's audio callback, and it seemed like the sort nice add-on to the base library the world was craving.
And then, we had to live with this thing for the last 25 years.
SDL_mixer 2.0 is a weird beast: it can mix audio, but only uncompressed things like WAV files (and VOC, which was added in anticipation of Duke Nukem 3D being open-sourced). It can also play a single compressed file, like MP3 or Ogg Vorbis, at a time. These are separate interfaces.
It is deeply obsessed with the quirks of MIDI and MOD file formats, threaded into the public API.
It has possibly the worst imaginable DSP API. This part was my fault. It seemed clever at the time.
For years now, I have been ignoring SDL_mixer bugs. Every time one would be reported, I would mumble "that's what you get for using it," and turn off notifications. I had personally disowned it a long time ago.
But hey, we rethought everything for SDL3. We threw out the entire SDL_net library and started over, could we kill a sacred cow like SDL_mixer, too?
Reader, we did.
I pitched a much simplified API, taking advantage of SDL3 features, that I thought would be more pleasant to use, without any of the cruft. It would be sample-perfect in its mixing, it wouldn't care what kind of audio files you used for what and how you loaded and decoded them. And I started building towards that. Before too long I had something to show, but then the Factorio developers showed up.
(Have you not played Factorio? You totally should.)
They had written a developer blog post about using SDL_mixer with their game, and some limitations they worked around in the library. This post haunted us; it was the thing that finally prompted us to throw everything out and make something better. So when the devs showed up in the bug tracker to talk about the new API, we were delighted. They were in the process of migrating to SDL3, so if they were ever going to tear up their sound subsystem, this was the time to do it! We took their day-to-day feedback on the new API as marching orders, and in turn they put my work directly into a cross-platform retail game. It was a meeting of the minds.
I don't really know how to explain how one develops an API. Unlike all this AI nonsense, this is the real "vibe coding." You're basically building out a thing that might have to live for a quarter of a century or more, for people you've never met, with nothing but raw hope that it's going to even work out for their needs, and it will feel good and fun to use. You design on vibes, and hope nothing harshes its mellow when it smacks face-first into the real world.
So all you can do is work with fundamentals. Is this thing easy to understand? Is that thing unnecessarily complex? Does this thing need to be here at all? Should we add a thing that makes the complex parts simple for common cases, or should we just make the complex parts less unwieldy?
I have to tell you, as someone that has shipped several libraries now...no one is an expert in this field. Some (most?) of the most important programming interfaces, across all of technology, designed by capable engineers, are honestly terrible. Past some obvious rookie mistakes, the best of us are just the most lucky, I suspect.
But the Factorio devs integrating my work--sometimes on the same day I finished a feature!--and immediately reporting back on the experience? Solid gold. Every API should be built in this way. There was a ton of "this is nice, but..." and "this works, but we also need this other way..." and that feedback loop was earth-shaking. The improvements to the library this caused can't be understated.
We also didn't want to lose functionality as we threw stuff away, so we made sure there were paths forward for most things. Native MIDI support is gone, but we spun it out into a separate library if you still need it. The positional effects functionality was terrible, but we added a new one that sucks less to replace it. Which had a nice bonus: handling positional audio is based on code from MojoAL, which has not only been migrated to SDL3 too, but has been pimped out with real surround sound support, so 3D audio can be heard behind you, on your sides...from all around! These improvements filtered down into SDL3_mixer.
Now we have something to show for all our work. You can try SDL3_mixer today, right from its GitHub repo. It currently requires the latest in SDL3's revision control (what will eventually ship as a stable SDL 3.4.0), as that has new APIs that SDL3_mixer relies on.
Everything is different from SDL2_mixer, but we, of course, have full documentation, a quick-reference card, and a complete migration guide.
My hope is that SDL3_mixer is powerful and packed full of useful features, but more than that, I hope it is a joy to use. That's the actual thing all libraries should run towards. It's the only feature that matters, really.