MIX_SetTrac...ackPosition(3)

💖 MIX_SetTrac...ackPosition(3) 💖

okay bestie, sit down, we're doing SDL_mixer3 FUNCTIONS today and this one is lowkey iconic. it's the "teleport my track to a different spot in the audio" function. no cap.

---

✨ NAME ✨

MIX_SetTrackPlaybackPosition — seek a playing track to a new position in its input. that's it, that's the whole vibe: move the playhead, keep the song going. 🎀

---

🌸 SYNOPSIS 🌸

#include <SDL3_mixer/SDL_mixer.h>

bool MIX_SetTrackPlaybackPosition(MIX_Track *track, Sint64 frames);

---

🦋 DESCRIPTION 🦋

first things first, do not confuse this with MIX_SetTrack3DPosition(), okay?? that one is about where the track sits in 3D space — like, which direction the sound comes from. THIS one is about where you are in the actual audio data. two completely different girls, don't mix them up 💅

so on a playing track, the next time the mixer runs, it starts mixing from your new position. the way that this works is genuinely so clean.

here's the key thing: position is defined in _sample frames_ of decoded audio, not units of time. that's on purpose!! it's how you get sample-perfect mixing. want to think in time instead? go use MIX_TrackMSToFrames() to get the approximate sample frames for a given tick. periodt.

now the requirements, listen up 🙈 this function needs an input that can seek, so:

• it can not be used if the input was set with MIX_SetTrackAudioStream()
• you also need an audio file format that allows seeking

and some of SDL_mixer's decoders for certain file formats just... don't offer seeking at all, or they can only seek to times rather than exact sample frames — in which case your final position may be off by some amount of sample frames. so please check your audio data, and file bug reports if appropriate. fr fr.

oh and it's totally legal to call this on a track that's stopped — but a future call to MIX_PlayTrack() will reset the start position anyhow. so like, whatever. paused tracks, though? those will resume at the new input position. slay. ✨

ngl, the seek-precision thing is the one to watch out for. if your decoder can't do exact frames, you're getting close enough, not exact. check your data!!

---

🎀 FUNCTION PARAMETERS 🎀

• track — the track to change. the one you're moving.
• frames — the sample frame position to seek to. where the playhead is going, bestie.

---

💜 RETURN VALUE 💜

Returns true on success, false on error — and if it's error o'clock, call SDL_GetError() for the details. she'll tell you what went wrong. 😭

---

🔥 THREAD SAFETY 🔥

It is safe to call this function from any thread. multitask, queen. 👑

---

🌈 AVAILABILITY 🌈

This function is available since SDL_mixer 3.0.0.

---

⭐ SEE ALSO ⭐

• MIX_GetTrackPlaybackPosition(3) — the other half of the duo, she reads, this one writes 🫶

---

okay that's the page!!! go forth and seek responsibly 🧚

mwah — this was brought to you by SDL_mixer, version 3.2.4, and yeah the date situation is that classic SDL_mixer 3.2.4 footer energy, so we're signing off with the source and version only, as the universe intended. bye bestie 💖🌸🎀