MIX_StopTag(3)

📦
version 3.2.4 · 2 versions
, in fedora 44

💖 MIX_StopTag(3) 💖

okay bestie, welcome to the SDL_mixer 3 girlies' corner of the manual — this one is MIX_StopTag, and it's genuinely one of the most satisfying little functions in the whole library. no cap. ✨

🌸 NAME 🌸

MIX_StopTag — halt every single track that's rocking a specific tag, and yeah, it can fade out over time if you want it to be dramatic about it. 💅

✨ SYNOPSIS ✨

#include <SDL3_mixer/SDL_mixer.h>

bool MIX_StopTag(MIX_Mixer *mixer, const char *tag, Sint64 fade_out_ms);

🎀 DESCRIPTION 🎀

So here's the tea, bestie. 🫖

If fade_out_ms is greater than 0, the tracks don't just stop mixing instantly — no, they fade to silence over that many milliseconds before actually stopping. cinematic. gorgeous. a whole moment. 🌈

Important distinction alert!! This is different from MIX_StopTrack(), which wants sample frames. This function takes milliseconds, because different tracks might have different sample rates, and the function is out here being thoughtful about it. 🧚

If a track ends normally while the fade-out is still in progress, the audio just stops right there — periodt. The fade is not adjusted to be shorter if it's going to last longer than the audio that's actually remaining. it's not gonna rush itself for anyone. 💀

Once a track has completed any fadeout and come to a stop, it will call its MIX_TrackStoppedCallback, if any. And here's the slay part: it is legal to assign the track a new input and/or restart it during this callback. 🌟

Also, this function does not prevent new play requests from being made. it's stopping stuff, not gatekeeping. 🙈

👑 FUNCTION PARAMETERS 👑

  • mixer — the mixer on which to stop tracks. your main character mixer. 💜
  • tag — the tag to use when searching for tracks. this is how we find our targets, iykyk. 🔍
  • fade_out_ms — the number of milliseconds to spend fading out to silence before halting. 0 to stop immediately. zero drama, instant exit. 😭

⭐ RETURN VALUE ⭐

Returns true on success, false on error — and if it errors, call SDL_GetError() for the details. she will tell you what went wrong, bestie. 💀

🦋 THREAD SAFETY 🦋

It is safe to call this function from any thread. go off, thread. 🔥

🌈 AVAILABILITY 🌈

This function is available since SDL_mixer 3.0.0. OGs remember. 👑

🍓 SEE ALSO 🍓

that's the whole page, babe — you're officially fluent in MIX_StopTag. this documentation situation is brought to you by SDL_mixer 3.2.4, so shoutout to the version that made it all possible. now go fade something out with style. 💖✨🎀

📦 where this page comes from