SDL_mixer is a library to make complicated audio processing tasks easier. More...
Classes | |
| class | SDL::Mixer |
| An opaque object that represents a mixer. More... | |
| struct | SDL::MixerRef |
| Reference for Mixer. More... | |
| class | SDL::MixerLock |
| Lock a mixer by obtaining its internal mutex. More... | |
| class | SDL::Audio |
| An opaque object that represents audio data. More... | |
| struct | SDL::AudioRef |
| Reference for Audio. More... | |
| class | SDL::Track |
| An opaque object that represents a source of sound output to be mixed. More... | |
| struct | SDL::TrackRef |
| Reference for Track. More... | |
| class | SDL::Group |
| An opaque object that represents a grouping of tracks. More... | |
| struct | SDL::GroupRef |
| Reference for Group. More... | |
| class | SDL::AudioDecoder |
| An opaque object that represents an audio decoder. More... | |
| struct | SDL::AudioDecoderRef |
| Reference for AudioDecoder. More... | |
Macros | |
| #define | SDL_MIXER_MAJOR_VERSION |
| The current major version of SDL_mixer headers. More... | |
| #define | SDL_MIXER_MINOR_VERSION |
| The current minor version of the SDL_mixer headers. More... | |
| #define | SDL_MIXER_MICRO_VERSION |
| The current micro (or patchlevel) version of the SDL_mixer headers. More... | |
| #define | SDL_MIXER_VERSION |
| This is the current version number macro of the SDL_mixer headers. More... | |
| #define | SDL_MIXER_VERSION_ATLEAST(X, Y, Z) |
| This macro will evaluate to true if compiled with SDL_mixer at least X.Y.Z. More... | |
Typedefs | |
| using | SDL::MixerRaw = MIX_Mixer * |
| Alias to raw representation for Mixer. | |
| using | SDL::AudioRaw = MIX_Audio * |
| Alias to raw representation for Audio. | |
| using | SDL::TrackRaw = MIX_Track * |
| Alias to raw representation for Track. | |
| using | SDL::GroupRaw = MIX_Group * |
| Alias to raw representation for Group. | |
| using | SDL::AudioDecoderRaw = MIX_AudioDecoder * |
| Alias to raw representation for AudioDecoder. | |
| using | SDL::PostMixCallback = void(SDLCALL *)(void *userdata, MixerRaw mixer, const AudioSpec *spec, float *pcm, int samples) |
| A callback that fires when all mixing has completed. More... | |
| using | SDL::PostMixCB = MakeFrontCallback< void(MixerRaw mixer, const AudioSpec *spec, float *pcm, int samples)> |
| A callback that fires when all mixing has completed. More... | |
| using | SDL::StereoGains = MIX_StereoGains |
| A set of per-channel gains for tracks using Track.SetStereo(). More... | |
| using | SDL::Point3D = MIX_Point3D |
| 3D coordinates for Track.Set3DPosition. More... | |
| using | SDL::TrackStoppedCallback = void(SDLCALL *)(void *userdata, TrackRaw track) |
| A callback that fires when a Track is stopped. More... | |
| using | SDL::TrackStoppedCB = MakeFrontCallback< void(TrackRaw track)> |
| A callback that fires when a Track is stopped. More... | |
| using | SDL::TrackMixCallback = void(SDLCALL *)(void *userdata, TrackRaw track, const AudioSpec *spec, float *pcm, int samples) |
| A callback that fires when a Track is mixing at various stages. More... | |
| using | SDL::TrackMixCB = MakeFrontCallback< void(TrackRaw track, const AudioSpec *spec, float *pcm, int samples)> |
| A callback that fires when a Track is mixing at various stages. More... | |
| using | SDL::GroupMixCallback = void(SDLCALL *)(void *userdata, GroupRaw group, const AudioSpec *spec, float *pcm, int samples) |
| A callback that fires when a Group has completed mixing. More... | |
| using | SDL::GroupMixCB = MakeFrontCallback< void(GroupRaw group, const AudioSpec *spec, float *pcm, int samples)> |
| A callback that fires when a Group has completed mixing. More... | |
Functions | |
| int | SDL::GetNumAudioDecoders () |
| Report the number of audio decoders available for use. More... | |
| const char * | SDL::GetAudioDecoder (int index) |
| Report the name of a specific audio decoders. More... | |
| Mixer | SDL::CreateMixerDevice (AudioDeviceRef devid, const AudioSpec &spec) |
| Create a mixer that plays sound directly to an audio device. More... | |
| Mixer | SDL::CreateMixer (const AudioSpec &spec) |
| Create a mixer that generates audio to a memory buffer. More... | |
| void | SDL::DestroyMixer (MixerRaw mixer) |
| Free a mixer. More... | |
| PropertiesRef | SDL::GetMixerProperties (MixerRef mixer) |
| Get the properties associated with a mixer. More... | |
| void | SDL::GetMixerFormat (MixerRef mixer, AudioSpec *spec) |
| Get the audio format a mixer is generating. More... | |
| void | SDL::LockMixer (MixerRef mixer) |
| Lock a mixer by obtaining its internal mutex. More... | |
| void | SDL::UnlockMixer (MixerRef mixer) |
| Unlock a mixer previously locked by a call to Mixer.Lock(). More... | |
| Audio | SDL::LoadAudio_IO (MixerRef mixer, IOStreamRef io, bool predecode, bool closeio=false) |
| Load audio for playback from an IOStream. More... | |
| Audio | SDL::LoadAudio (MixerRef mixer, StringParam path, bool predecode) |
| Load audio for playback from a file. More... | |
| Audio | SDL::LoadAudioNoCopy (MixerRef mixer, SourceBytes data, bool free_when_done) |
| Load audio for playback from a memory buffer without making a copy. More... | |
| Audio | SDL::LoadAudioWithProperties (PropertiesRef props) |
| Load audio for playback through a collection of properties. More... | |
| Audio | SDL::LoadRawAudio_IO (MixerRef mixer, IOStreamRef io, const AudioSpec &spec, bool closeio=false) |
| Load raw PCM data from an IOStream. More... | |
| Audio | SDL::LoadRawAudio (MixerRef mixer, SourceBytes data, const AudioSpec &spec) |
| Load raw PCM data from a memory buffer. More... | |
| Audio | SDL::LoadRawAudioNoCopy (MixerRef mixer, SourceBytes data, const AudioSpec &spec, bool free_when_done) |
| Load raw PCM data from a memory buffer without making a copy. More... | |
| Audio | SDL::CreateSineWaveAudio (MixerRef mixer, int hz, float amplitude, Sint64 ms) |
| Create a Audio that generates a sinewave. More... | |
| PropertiesRef | SDL::GetAudioProperties (AudioRef audio) |
| Get the properties associated with a Audio. More... | |
| Sint64 | SDL::GetAudioDuration (AudioRef audio) |
| Get the length of a Audio's playback in sample frames. More... | |
| void | SDL::GetAudioFormat (AudioRef audio, AudioSpec *spec) |
| Query the initial audio format of a Audio. More... | |
| void | SDL::DestroyAudio (AudioRaw audio) |
| Destroy the specified audio. More... | |
| Track | SDL::CreateTrack (MixerRef mixer) |
| Create a new track on a mixer. More... | |
| void | SDL::DestroyTrack (TrackRaw track) |
| Destroy the specified track. More... | |
| PropertiesRef | SDL::GetTrackProperties (TrackRef track) |
| Get the properties associated with a track. More... | |
| MixerRef | SDL::GetTrackMixer (TrackRef track) |
| Get the Mixer that owns a Track. More... | |
| void | SDL::SetTrackAudio (TrackRef track, AudioRef audio) |
| Set a Track's input to a Audio. More... | |
| void | SDL::SetTrackAudioStream (TrackRef track, AudioStreamRef stream) |
| Set a Track's input to an AudioStream. More... | |
| void | SDL::SetTrackIOStream (TrackRef track, IOStreamRef io, bool closeio=false) |
| Set a Track's input to an IOStream. More... | |
| void | SDL::SetTrackRawIOStream (TrackRef track, IOStreamRef io, const AudioSpec &spec, bool closeio=false) |
| Set a Track's input to an IOStream providing raw PCM data. More... | |
| void | SDL::TagTrack (TrackRef track, StringParam tag) |
| Assign an arbitrary tag to a track. More... | |
| void | SDL::UntagTrack (TrackRef track, StringParam tag) |
| Remove an arbitrary tag from a track. More... | |
| OwnArray< char * > | SDL::GetTrackTags (TrackRef track) |
| Get the tags currently associated with a track. More... | |
| OwnArray< TrackRef > | SDL::GetTaggedTracks (MixerRef mixer, StringParam tag) |
| Get all tracks with a specific tag. More... | |
| void | SDL::SetTrackPlaybackPosition (TrackRef track, Sint64 frames) |
| Seek a playing track to a new position in its input. More... | |
| Sint64 | SDL::GetTrackPlaybackPosition (TrackRef track) |
| Get the current input position of a playing track. More... | |
| Sint64 | SDL::GetTrackFadeFrames (TrackRef track) |
| Query whether a given track is fading. More... | |
| int | SDL::GetTrackLoops (TrackRef track) |
| Query how many loops remain for a given track. More... | |
| void | SDL::SetTrackLoops (TrackRef track, int num_loops) |
| Change the number of times a currently-playing track will loop. More... | |
| AudioRef | SDL::GetTrackAudio (TrackRef track) |
| Query the Audio assigned to a track. More... | |
| AudioStreamRef | SDL::GetTrackAudioStream (TrackRef track) |
| Query the AudioStream assigned to a track. More... | |
| Sint64 | SDL::GetTrackRemaining (TrackRef track) |
| Return the number of sample frames remaining to be mixed in a track. More... | |
| Sint64 | SDL::TrackMSToFrames (TrackRef track, Milliseconds ms) |
| Convert milliseconds to sample frames for a track's current format. More... | |
| Milliseconds | SDL::TrackFramesToMS (TrackRef track, Sint64 frames) |
| Convert sample frames for a track's current format to milliseconds. More... | |
| Sint64 | SDL::AudioMSToFrames (AudioRef audio, Milliseconds ms) |
| Convert milliseconds to sample frames for a Audio's format. More... | |
| Milliseconds | SDL::AudioFramesToMS (AudioRef audio, Sint64 frames) |
| Convert sample frames for a Audio's format to milliseconds. More... | |
| Sint64 | SDL::MSToFrames (int sample_rate, Milliseconds ms) |
| Convert milliseconds to sample frames at a specific sample rate. More... | |
| Milliseconds | SDL::FramesToMS (int sample_rate, Sint64 frames) |
| Convert sample frames, at a specific sample rate, to milliseconds. More... | |
| void | SDL::PlayTrack (TrackRef track, PropertiesRef options=nullptr) |
| Start (or restart) mixing a track for playback. More... | |
| void | SDL::PlayTag (MixerRef mixer, StringParam tag, PropertiesRef options) |
| Start (or restart) mixing all tracks with a specific tag for playback. More... | |
| bool | SDL::PlayAudio (MixerRef mixer, AudioRef audio) |
| Play a Audio from start to finish without any management. More... | |
| bool | SDL::StopTrack (TrackRef track, Sint64 fade_out_frames) |
| Halt a currently-playing track, possibly fading out over time. More... | |
| void | SDL::StopAllTracks (MixerRef mixer, Sint64 fade_out_ms) |
| Halt all currently-playing tracks, possibly fading out over time. More... | |
| void | SDL::StopTag (MixerRef mixer, StringParam tag, Sint64 fade_out_ms) |
| Halt all tracks with a specific tag, possibly fading out over time. More... | |
| bool | SDL::PauseTrack (TrackRef track) |
| Pause a currently-playing track. More... | |
| void | SDL::PauseAllTracks (MixerRef mixer) |
| Pause all currently-playing tracks. More... | |
| void | SDL::PauseTag (MixerRef mixer, StringParam tag) |
| Pause all tracks with a specific tag. More... | |
| bool | SDL::ResumeTrack (TrackRef track) |
| Resume a currently-paused track. More... | |
| void | SDL::ResumeAllTracks (MixerRef mixer) |
| Resume all currently-paused tracks. More... | |
| void | SDL::ResumeTag (MixerRef mixer, StringParam tag) |
| Resume all tracks with a specific tag. More... | |
| bool | SDL::TrackPlaying (TrackRef track) |
| Query if a track is currently playing. More... | |
| bool | SDL::TrackPaused (TrackRef track) |
| Query if a track is currently paused. More... | |
| void | SDL::SetMixerGain (MixerRef mixer, float gain) |
| Set a mixer's master gain control. More... | |
| float | SDL::GetMixerGain (MixerRef mixer) |
| Get a mixer's master gain control. More... | |
| void | SDL::SetTrackGain (TrackRef track, float gain) |
| Set a track's gain control. More... | |
| float | SDL::GetTrackGain (TrackRef track) |
| Get a track's gain control. More... | |
| void | SDL::SetTagGain (MixerRef mixer, StringParam tag, float gain) |
| Set the gain control of all tracks with a specific tag. More... | |
| void | SDL::SetMixerFrequencyRatio (MixerRef mixer, float ratio) |
| Set a mixer's master frequency ratio. More... | |
| float | SDL::GetMixerFrequencyRatio (MixerRef mixer) |
| Get a mixer's master frequency ratio. More... | |
| void | SDL::SetTrackFrequencyRatio (TrackRef track, float ratio) |
| Change the frequency ratio of a track. More... | |
| float | SDL::GetTrackFrequencyRatio (TrackRef track) |
| Query the frequency ratio of a track. More... | |
| void | SDL::SetTrackOutputChannelMap (TrackRef track, std::span< const int > chmap) |
| Set the current output channel map of a track. More... | |
| void | SDL::SetTrackStereo (TrackRef track, const StereoGains &gains) |
| Force a track to stereo output, with optionally left/right panning. More... | |
| void | SDL::SetTrack3DPosition (TrackRef track, const Point3D &position) |
| Set a track's position in 3D space. More... | |
| Point3D | SDL::GetTrack3DPosition (TrackRef track) |
| Get a track's current position in 3D space. More... | |
| Group | SDL::CreateGroup (MixerRef mixer) |
| Create a mixing group. More... | |
| void | SDL::DestroyGroup (GroupRaw group) |
| Destroy a mixing group. More... | |
| PropertiesRef | SDL::GetGroupProperties (GroupRef group) |
| Get the properties associated with a group. More... | |
| MixerRef | SDL::GetGroupMixer (GroupRef group) |
| Get the Mixer that owns a Group. More... | |
| void | SDL::SetTrackGroup (TrackRef track, GroupRef group) |
| Assign a track to a mixing group. More... | |
| void | SDL::SetTrackStoppedCallback (TrackRef track, TrackStoppedCallback cb, void *userdata) |
| Set a callback that fires when a Track is stopped. More... | |
| void | SDL::SetTrackStoppedCallback (TrackRef track, TrackStoppedCB cb) |
| Set a callback that fires when a Track is stopped. More... | |
| void | SDL::SetTrackRawCallback (TrackRef track, TrackMixCallback cb, void *userdata) |
| Set a callback that fires when a Track has initial decoded audio. More... | |
| void | SDL::SetTrackRawCallback (TrackRef track, TrackMixCB cb) |
| Set a callback that fires when a Track has initial decoded audio. More... | |
| void | SDL::SetTrackCookedCallback (TrackRef track, TrackMixCallback cb, void *userdata) |
| Set a callback that fires when the mixer has transformed a track's audio. More... | |
| void | SDL::SetTrackCookedCallback (TrackRef track, TrackMixCB cb) |
| Set a callback that fires when the mixer has transformed a track's audio. More... | |
| void | SDL::SetGroupPostMixCallback (GroupRef group, GroupMixCallback cb, void *userdata) |
| Set a callback that fires when a mixer group has completed mixing. More... | |
| void | SDL::SetGroupPostMixCallback (GroupRef group, GroupMixCB cb) |
| Set a callback that fires when a mixer group has completed mixing. More... | |
| void | SDL::SetPostMixCallback (MixerRef mixer, PostMixCallback cb, void *userdata) |
| Set a callback that fires when all mixing has completed. More... | |
| void | SDL::SetPostMixCallback (MixerRef mixer, PostMixCB cb) |
| Set a callback that fires when all mixing has completed. More... | |
| int | SDL::Generate (MixerRef mixer, TargetBytes buffer) |
| Generate mixer output when not driving an audio device. More... | |
| AudioDecoder | SDL::CreateAudioDecoder (StringParam path, PropertiesRef props=nullptr) |
| Create a AudioDecoder from a path on the filesystem. More... | |
| AudioDecoder | SDL::CreateAudioDecoder_IO (IOStreamRef io, bool closeio=false, PropertiesRef props=nullptr) |
| Create a AudioDecoder from an IOStream. More... | |
| void | SDL::DestroyAudioDecoder (AudioDecoderRaw audiodecoder) |
| Destroy the specified audio decoder. More... | |
| PropertiesRef | SDL::GetAudioDecoderProperties (AudioDecoderRef audiodecoder) |
| Get the properties associated with a AudioDecoder. More... | |
| void | SDL::GetAudioDecoderFormat (AudioDecoderRef audiodecoder, AudioSpec *spec) |
| Query the initial audio format of a AudioDecoder. More... | |
| int | SDL::DecodeAudio (AudioDecoderRef audiodecoder, TargetBytes buffer, const AudioSpec &spec) |
| Decode more audio from a AudioDecoder. More... | |
| SDL::Mixer::Mixer (AudioDeviceRef devid, const AudioSpec &spec) | |
| Create a mixer that plays sound directly to an audio device. More... | |
| SDL::Mixer::Mixer (const AudioSpec &spec) | |
| Create a mixer that generates audio to a memory buffer. More... | |
| void | SDL::Mixer::Destroy () |
| Free a mixer. More... | |
| PropertiesRef | SDL::Mixer::GetProperties () |
| Get the properties associated with a mixer. More... | |
| void | SDL::Mixer::GetFormat (AudioSpec *spec) |
| Get the audio format a mixer is generating. More... | |
| MixerLock | SDL::Mixer::Lock () |
| Lock a mixer by obtaining its internal mutex. More... | |
| SDL::MixerLock::MixerLock (MixerRef resource) | |
| Lock a mixer by obtaining its internal mutex. More... | |
| void | SDL::Mixer::Unlock (MixerLock &&lock) |
| Unlock a mixer previously locked by a call to Mixer.Lock(). More... | |
| void | SDL::MixerLock::reset () |
| Unlock a mixer previously locked by a call to Mixer.Lock(). More... | |
| Audio | SDL::Mixer::LoadAudio_IO (IOStreamRef io, bool predecode, bool closeio=false) |
| Load audio for playback from an IOStream. More... | |
| SDL::Audio::Audio (MixerRef mixer, IOStreamRef io, bool predecode, bool closeio=false) | |
| Load audio for playback from an IOStream. More... | |
| SDL::Audio::Audio (MixerRef mixer, StringParam path, bool predecode) | |
| Load audio for playback from a file. More... | |
| SDL::Audio::Audio (PropertiesRef props) | |
| Load audio for playback through a collection of properties. More... | |
| SDL::Audio::Audio (MixerRef mixer, IOStreamRef io, const AudioSpec &spec, bool closeio=false) | |
| Load raw PCM data from an IOStream. More... | |
| SDL::Audio::Audio (MixerRef mixer, SourceBytes data, const AudioSpec &spec) | |
| Load raw PCM data from a memory buffer. More... | |
| Audio | SDL::Mixer::LoadAudio (StringParam path, bool predecode) |
| Load audio for playback from a file. More... | |
| Audio | SDL::Mixer::LoadAudioNoCopy (SourceBytes data, bool free_when_done) |
| Load audio for playback from a memory buffer without making a copy. More... | |
| Audio | SDL::Mixer::LoadRawAudio_IO (IOStreamRef io, const AudioSpec &spec, bool closeio=false) |
| Load raw PCM data from an IOStream. More... | |
| Audio | SDL::Mixer::LoadRawAudio (SourceBytes data, const AudioSpec &spec) |
| Load raw PCM data from a memory buffer. More... | |
| Audio | SDL::Mixer::LoadRawAudioNoCopy (SourceBytes data, const AudioSpec &spec, bool free_when_done) |
| Load raw PCM data from a memory buffer without making a copy. More... | |
| Audio | SDL::Mixer::CreateSineWaveAudio (int hz, float amplitude, Sint64 ms) |
| Create a Audio that generates a sinewave. More... | |
| PropertiesRef | SDL::Audio::GetProperties () |
| Get the properties associated with a Audio. More... | |
| Sint64 | SDL::Audio::GetDuration () |
| Get the length of a Audio's playback in sample frames. More... | |
| void | SDL::Audio::GetFormat (AudioSpec *spec) |
| Query the initial audio format of a Audio. More... | |
| void | SDL::Audio::Destroy () |
| Destroy the specified audio. More... | |
| TrackRef | SDL::Mixer::CreateTrack () |
| Create a new track on a mixer. More... | |
| SDL::Track::Track (MixerRef mixer) | |
| Create a new track on a mixer. More... | |
| void | SDL::Track::Destroy () |
| Destroy the specified track. More... | |
| PropertiesRef | SDL::Track::GetProperties () |
| Get the properties associated with a track. More... | |
| MixerRef | SDL::Track::GetMixer () |
| Get the Mixer that owns a Track. More... | |
| void | SDL::Track::SetAudio (AudioRef audio) |
| Set a Track's input to a Audio. More... | |
| void | SDL::Track::SetAudioStream (AudioStreamRef stream) |
| Set a Track's input to an AudioStream. More... | |
| void | SDL::Track::SetIOStream (IOStreamRef io, bool closeio=false) |
| Set a Track's input to an IOStream. More... | |
| void | SDL::Track::SetRawIOStream (IOStreamRef io, const AudioSpec &spec, bool closeio=false) |
| Set a Track's input to an IOStream providing raw PCM data. More... | |
| void | SDL::Track::Tag (StringParam tag) |
| Assign an arbitrary tag to a track. More... | |
| void | SDL::Track::Untag (StringParam tag) |
| Remove an arbitrary tag from a track. More... | |
| OwnArray< char * > | SDL::Track::GetTags () |
| Get the tags currently associated with a track. More... | |
| OwnArray< TrackRef > | SDL::Mixer::GetTaggedTracks (StringParam tag) |
| Get all tracks with a specific tag. More... | |
| void | SDL::Track::SetPlaybackPosition (Sint64 frames) |
| Seek a playing track to a new position in its input. More... | |
| Sint64 | SDL::Track::GetPlaybackPosition () |
| Get the current input position of a playing track. More... | |
| Sint64 | SDL::Track::GetFadeFrames () |
| Query whether a given track is fading. More... | |
| int | SDL::Track::GetLoops () |
| Query how many loops remain for a given track. More... | |
| void | SDL::Track::SetLoops (int num_loops) |
| Change the number of times a currently-playing track will loop. More... | |
| AudioRef | SDL::Track::GetAudio () |
| Query the Audio assigned to a track. More... | |
| AudioStreamRef | SDL::Track::GetAudioStream () |
| Query the AudioStream assigned to a track. More... | |
| Sint64 | SDL::Track::GetRemaining () |
| Return the number of sample frames remaining to be mixed in a track. More... | |
| Sint64 | SDL::Track::MSToFrames (Milliseconds ms) |
| Convert milliseconds to sample frames for a track's current format. More... | |
| Milliseconds | SDL::Track::FramesToMS (Sint64 frames) |
| Convert sample frames for a track's current format to milliseconds. More... | |
| Sint64 | SDL::Audio::MSToFrames (Milliseconds ms) |
| Convert milliseconds to sample frames for a Audio's format. More... | |
| Milliseconds | SDL::Audio::FramesToMS (Sint64 frames) |
| Convert sample frames for a Audio's format to milliseconds. More... | |
| void | SDL::Track::Play (PropertiesRef options=nullptr) |
| Start (or restart) mixing a track for playback. More... | |
| void | SDL::Mixer::PlayTag (StringParam tag, PropertiesRef options) |
| Start (or restart) mixing all tracks with a specific tag for playback. More... | |
| bool | SDL::Mixer::PlayAudio (AudioRef audio) |
| Play a Audio from start to finish without any management. More... | |
| bool | SDL::Track::Stop (Sint64 fade_out_frames) |
| Halt a currently-playing track, possibly fading out over time. More... | |
| void | SDL::Mixer::StopAllTracks (Sint64 fade_out_ms) |
| Halt all currently-playing tracks, possibly fading out over time. More... | |
| void | SDL::Mixer::StopTag (StringParam tag, Sint64 fade_out_ms) |
| Halt all tracks with a specific tag, possibly fading out over time. More... | |
| bool | SDL::Track::Pause () |
| Pause a currently-playing track. More... | |
| void | SDL::Mixer::PauseAllTracks () |
| Pause all currently-playing tracks. More... | |
| void | SDL::Mixer::PauseTag (StringParam tag) |
| Pause all tracks with a specific tag. More... | |
| bool | SDL::Track::Resume () |
| Resume a currently-paused track. More... | |
| void | SDL::Mixer::ResumeAllTracks () |
| Resume all currently-paused tracks. More... | |
| void | SDL::Mixer::ResumeTag (StringParam tag) |
| Resume all tracks with a specific tag. More... | |
| bool | SDL::Track::Playing () |
| Query if a track is currently playing. More... | |
| bool | SDL::Track::Paused () |
| Query if a track is currently paused. More... | |
| void | SDL::Mixer::SetGain (float gain) |
| Set a mixer's master gain control. More... | |
| float | SDL::Mixer::GetGain () |
| Get a mixer's master gain control. More... | |
| void | SDL::Track::SetGain (float gain) |
| Set a track's gain control. More... | |
| float | SDL::Track::GetGain () |
| Get a track's gain control. More... | |
| void | SDL::Mixer::SetTagGain (StringParam tag, float gain) |
| Set the gain control of all tracks with a specific tag. More... | |
| void | SDL::Mixer::SetFrequencyRatio (float ratio) |
| Set a mixer's master frequency ratio. More... | |
| float | SDL::Mixer::GetFrequencyRatio () |
| Get a mixer's master frequency ratio. More... | |
| void | SDL::Track::SetFrequencyRatio (float ratio) |
| Change the frequency ratio of a track. More... | |
| float | SDL::Track::GetFrequencyRatio () |
| Query the frequency ratio of a track. More... | |
| void | SDL::Track::SetOutputChannelMap (std::span< const int > chmap) |
| Set the current output channel map of a track. More... | |
| void | SDL::Track::SetStereo (const StereoGains &gains) |
| Force a track to stereo output, with optionally left/right panning. More... | |
| void | SDL::Track::Set3DPosition (const Point3D &position) |
| Set a track's position in 3D space. More... | |
| Point3D | SDL::Track::Get3DPosition () |
| Get a track's current position in 3D space. More... | |
| GroupRef | SDL::Mixer::CreateGroup () |
| Create a mixing group. More... | |
| SDL::Group::Group (MixerRef mixer) | |
| Create a mixing group. More... | |
| void | SDL::Group::Destroy () |
| Destroy a mixing group. More... | |
| PropertiesRef | SDL::Group::GetProperties () |
| Get the properties associated with a group. More... | |
| MixerRef | SDL::Group::GetMixer () |
| Get the Mixer that owns a Group. More... | |
| void | SDL::Track::SetGroup (GroupRef group) |
| Assign a track to a mixing group. More... | |
| void | SDL::Track::SetStoppedCallback (TrackStoppedCallback cb, void *userdata) |
| Set a callback that fires when a Track is stopped. More... | |
| void | SDL::Track::SetStoppedCallback (TrackStoppedCB cb) |
| Set a callback that fires when a Track is stopped. More... | |
| void | SDL::Track::SetRawCallback (TrackMixCallback cb, void *userdata) |
| Set a callback that fires when a Track has initial decoded audio. More... | |
| void | SDL::Track::SetRawCallback (TrackMixCB cb) |
| Set a callback that fires when a Track has initial decoded audio. More... | |
| void | SDL::Track::SetCookedCallback (TrackMixCallback cb, void *userdata) |
| Set a callback that fires when the mixer has transformed a track's audio. More... | |
| void | SDL::Track::SetCookedCallback (TrackMixCB cb) |
| Set a callback that fires when the mixer has transformed a track's audio. More... | |
| void | SDL::Group::SetPostMixCallback (GroupMixCallback cb, void *userdata) |
| Set a callback that fires when a mixer group has completed mixing. More... | |
| void | SDL::Mixer::SetPostMixCallback (PostMixCallback cb, void *userdata) |
| Set a callback that fires when all mixing has completed. More... | |
| void | SDL::Mixer::SetPostMixCallback (PostMixCB cb) |
| Set a callback that fires when all mixing has completed. More... | |
| int | SDL::Mixer::Generate (TargetBytes buffer) |
| Generate mixer output when not driving an audio device. More... | |
| SDL::AudioDecoder::AudioDecoder (StringParam path, PropertiesRef props=nullptr) | |
| Create a AudioDecoder from a path on the filesystem. More... | |
| SDL::AudioDecoder::AudioDecoder (IOStreamRef io, bool closeio=false, PropertiesRef props=nullptr) | |
| Create a AudioDecoder from an IOStream. More... | |
| void | SDL::AudioDecoder::Destroy () |
| Destroy the specified audio decoder. More... | |
| PropertiesRef | SDL::AudioDecoder::GetProperties () |
| Get the properties associated with a AudioDecoder. More... | |
| void | SDL::AudioDecoder::GetFormat (AudioSpec *spec) |
| Query the initial audio format of a AudioDecoder. More... | |
| int | SDL::AudioDecoder::DecodeAudio (TargetBytes buffer, const AudioSpec &spec) |
| Decode more audio from a AudioDecoder. More... | |
Variables | |
| constexpr Sint64 | SDL::DURATION_UNKNOWN = MIX_DURATION_UNKNOWN |
| Unknown duration, when the length of the audio can't be determined. | |
| constexpr Sint64 | SDL::DURATION_INFINITE = MIX_DURATION_INFINITE |
| Infinite duration, when the audio never runs out of sound to generate. | |
Detailed Description
It offers audio file decoding, mixing multiple sounds together, basic 3D positional audio, and various audio effects.
It can mix sound to multiple audio devices in real time, or generate mixed audio data to a memory buffer for any other use. It can do both at the same time!
To use the library, first call MIX.Init(). Then create a mixer with CreateMixerDevice() (or CreateMixer() to render to memory).
Once you have a mixer, you can load sound data with Mixer.LoadAudio(), Mixer.LoadAudio_IO(), or LoadAudioWithProperties(). Data gets loaded once and can be played over and over.
When loading audio, SDL_mixer can parse out several metadata tag formats, such as ID3 and APE tags, and exposes this information through the Audio.GetProperties() function.
To play audio, you create a track with Mixer.CreateTrack(). You need one track for each sound that will be played simultaneously; think of tracks as individual sliders on a mixer board. You might have loaded hundreds of audio files, but you probably only have a handful of tracks that you assign those loaded files to when they are ready to play, and reuse those tracks with different audio later. Tracks take their input from a Audio (static data to be played multiple times) or an AudioStream (streaming PCM audio the app supplies, possibly as needed). A third option is to supply an IOStream, to load and decode on the fly, which might be more efficient for background music that is only used once, etc.
Assign input to a Track with Track.SetAudio(), Track.SetAudioStream(), or Track.SetIOStream().
Once a track has an input, start it playing with Track.Play(). There are many options to this function to dictate mixing features: looping, fades, etc.
Tracks can be tagged with arbitrary strings, like "music" or "ingame" or "ui". These tags can be used to start, stop, and pause a selection of tracks at the same moment.
All significant portions of the mixing pipeline have callbacks, so that an app can hook in to the appropriate locations to examine or modify audio data as it passes through the mixer: a "raw" callback for raw PCM data decoded from an audio file without any modifications, a "cooked" callback for that same data after all transformations (fade, positioning, etc) have been processed, a "stopped" callback for when the track finishes mixing, a "postmix" callback for the final mixed audio about to be sent to the audio hardware to play. Additionally, you can use Group objects to mix a subset of playing tracks and access the data before it is mixed in with other tracks. All of this is optional, but allows for powerful access and control of the mixing process.
SDL_mixer can also be used for decoding audio files without actually rendering a mix. This is done with AudioDecoder. Even though SDL_mixer handles decoding transparently when used as the audio engine for an app, and probably won't need this interface in that normal scenario, this can be useful when using a different audio library to access many file formats.
This library offers several features on top of mixing sounds together: a track can have its own gain, to adjust its volume, in addition to a master gain applied as well. One can set the "frequency ratio" of a track or the final mixed output, to speed it up or slow it down, which also adjusts its pitch. A channel map can also be applied per-track, to change what speaker a given channel of audio is output to.
Almost all timing in SDL_mixer is in sample frames. Stereo PCM audio data in Sint16 format takes 4 bytes per sample frame (2 bytes per sample times 2 channels), for example. This allows everything in SDL_mixer to run at sample-perfect accuracy, and it lets it run without concern for wall clock time–you can produce audio faster than real-time, if desired. The problem, though, is different pieces of audio at different sample rates will produce a different number of sample frames for the same length of time. To deal with this, conversion routines are offered: Track.MSToFrames(), Track.FramesToMS(), etc. Functions that operate on multiple tracks at once will deal with time in milliseconds, so it can do these conversions internally; be sure to read the documentation for these small quirks!
SDL_mixer offers basic positional audio: a simple 3D positioning API through Track.Set3DPosition() and Track.SetStereo(). The former will do simple distance attenuation and spatialization–on a stereo setup, you will hear sounds move from left to right–and on a surround-sound configuration, individual tracks can move around the user. The latter, Track.SetStereo(), will force a sound to the Front Left and Front Right speakers and let the app pan it left and right as desired. Either effect can be useful for different situations. SDL_mixer is not meant to be a full 3D audio engine, but rather Good Enough for many purposes; if something more powerful in terms of 3D audio is needed, consider a proper 3D library like OpenAL.
Macro Definition Documentation
◆ SDL_MIXER_MAJOR_VERSION
| #define SDL_MIXER_MAJOR_VERSION |
If this were SDL_mixer version 3.2.1, this value would be 3.
- Since
- This macro is available since SDL_mixer 3.0.0.
◆ SDL_MIXER_MICRO_VERSION
| #define SDL_MIXER_MICRO_VERSION |
If this were SDL_mixer version 3.2.1, this value would be 1.
- Since
- This macro is available since SDL_mixer 3.0.0.
◆ SDL_MIXER_MINOR_VERSION
| #define SDL_MIXER_MINOR_VERSION |
If this were SDL_mixer version 3.2.1, this value would be 2.
- Since
- This macro is available since SDL_mixer 3.0.0.
◆ SDL_MIXER_VERSION
| #define SDL_MIXER_VERSION |
- Since
- This macro is available since SDL_mixer 3.0.0.
- See also
- MIX.Version
◆ SDL_MIXER_VERSION_ATLEAST
| #define SDL_MIXER_VERSION_ATLEAST | ( | X, | |
| Y, | |||
| Z | |||
| ) |
- Since
- This macro is available since SDL_mixer 3.0.0.
Typedef Documentation
◆ GroupMixCallback
| using SDL::GroupMixCallback = typedef void(SDLCALL*)(void* userdata, GroupRaw group, const AudioSpec* spec, float* pcm, int samples) |
This callback is fired when a mixing group has finished mixing: all tracks in the group have mixed into a single buffer and are prepared to be mixed into all other groups for the final mix output.
The audio data passed through here is not const data; the app is permitted to change it in any way it likes, and those changes will propagate through the mixing pipeline.
An audiospec is provided. Different groups might be in different formats, and an app needs to be able to handle that, but SDL_mixer always does its mixing work in 32-bit float samples, even if the inputs or final output are not floating point. As such, spec->format will always be AUDIO_F32 and pcm hardcoded to be a float pointer.
samples is the number of float values pointed to by pcm: samples, not sample frames! There are no promises how many samples will be provided per-callback, and this number can vary wildly from call to call, depending on many factors.
- Parameters
-
userdata an opaque pointer provided by the app for its personal use. group the group that is being mixed. spec the format of the data in pcm.pcm the raw PCM data in float32 format. samples the number of float values pointed to by pcm.
- Since
- This datatype is available since SDL_mixer 3.0.0.
- See also
- Group.SetPostMixCallback
◆ GroupMixCB
| using SDL::GroupMixCB = typedef MakeFrontCallback< void(GroupRaw group, const AudioSpec* spec, float* pcm, int samples)> |
This callback is fired when a mixing group has finished mixing: all tracks in the group have mixed into a single buffer and are prepared to be mixed into all other groups for the final mix output.
The audio data passed through here is not const data; the app is permitted to change it in any way it likes, and those changes will propagate through the mixing pipeline.
An audiospec is provided. Different groups might be in different formats, and an app needs to be able to handle that, but SDL_mixer always does its mixing work in 32-bit float samples, even if the inputs or final output are not floating point. As such, spec->format will always be AUDIO_F32 and pcm hardcoded to be a float pointer.
samples is the number of float values pointed to by pcm: samples, not sample frames! There are no promises how many samples will be provided per-callback, and this number can vary wildly from call to call, depending on many factors.
- Parameters
-
group the group that is being mixed. spec the format of the data in pcm.pcm the raw PCM data in float32 format. samples the number of float values pointed to by pcm.
- Since
- This datatype is available since SDL_mixer 3.0.0.
◆ Point3D
| using SDL::Point3D = typedef MIX_Point3D |
The coordinates use a "right-handed" coordinate system, like OpenGL and OpenAL.
- Since
- This struct is available since SDL_mixer 3.0.0.
- See also
- Track.Set3DPosition
◆ PostMixCallback
| using SDL::PostMixCallback = typedef void(SDLCALL*)(void* userdata, MixerRaw mixer, const AudioSpec* spec, float* pcm, int samples) |
This callback is fired when the mixer has completed all its work. If this mixer was created with CreateMixerDevice(), the data provided by this callback is what is being sent to the audio hardware, minus last conversions for format requirements. If this mixer was created with CreateMixer(), this is what is being output from Mixer.Generate(), after final conversions.
The audio data passed through here is not const data; the app is permitted to change it in any way it likes, and those changes will replace the final mixer pipeline output.
An audiospec is provided. SDL_mixer always does its mixing work in 32-bit float samples, even if the inputs or final output are not floating point. As such, spec->format will always be AUDIO_F32 and pcm hardcoded to be a float pointer.
samples is the number of float values pointed to by pcm: samples, not sample frames! There are no promises how many samples will be provided per-callback, and this number can vary wildly from call to call, depending on many factors.
- Parameters
-
userdata an opaque pointer provided by the app for its personal use. mixer the mixer that is generating audio. spec the format of the data in pcm.pcm the raw PCM data in float32 format. samples the number of float values pointed to by pcm.
- Since
- This datatype is available since SDL_mixer 3.0.0.
- See also
- Mixer.SetPostMixCallback
◆ PostMixCB
| using SDL::PostMixCB = typedef MakeFrontCallback< void(MixerRaw mixer, const AudioSpec* spec, float* pcm, int samples)> |
This callback is fired when the mixer has completed all its work. If this mixer was created with CreateMixerDevice(), the data provided by this callback is what is being sent to the audio hardware, minus last conversions for format requirements. If this mixer was created with CreateMixer(), this is what is being output from Mixer.Generate(), after final conversions.
The audio data passed through here is not const data; the app is permitted to change it in any way it likes, and those changes will replace the final mixer pipeline output.
An audiospec is provided. SDL_mixer always does its mixing work in 32-bit float samples, even if the inputs or final output are not floating point. As such, spec->format will always be AUDIO_F32 and pcm hardcoded to be a float pointer.
samples is the number of float values pointed to by pcm: samples, not sample frames! There are no promises how many samples will be provided per-callback, and this number can vary wildly from call to call, depending on many factors.
- Parameters
-
mixer the mixer that is generating audio. spec the format of the data in pcm.pcm the raw PCM data in float32 format. samples the number of float values pointed to by pcm.
- Since
- This datatype is available since SDL_mixer 3.0.0.
◆ StereoGains
| using SDL::StereoGains = typedef MIX_StereoGains |
When forcing a track to stereo, the app can specify a per-channel gain, to further adjust the left or right outputs.
When mixing audio that has been forced to stereo, each channel is modulated by these values. A value of 1.0f produces no change, 0.0f produces silence.
A simple panning effect would be to set left to the desired value and right to 1.0f - left.
- Since
- This struct is available since SDL_mixer 3.0.0.
- See also
- Track.SetStereo
◆ TrackMixCallback
| using SDL::TrackMixCallback = typedef void(SDLCALL*)(void* userdata, TrackRaw track, const AudioSpec* spec, float* pcm, int samples) |
This callback is fired for different parts of the mixing pipeline, and gives the app visibility into the audio data that is being generated at various stages.
The audio data passed through here is not const data; the app is permitted to change it in any way it likes, and those changes will propagate through the mixing pipeline.
An audiospec is provided. Different tracks might be in different formats, and an app needs to be able to handle that, but SDL_mixer always does its mixing work in 32-bit float samples, even if the inputs or final output are not floating point. As such, spec->format will always be AUDIO_F32 and pcm hardcoded to be a float pointer.
samples is the number of float values pointed to by pcm: samples, not sample frames! There are no promises how many samples will be provided per-callback, and this number can vary wildly from call to call, depending on many factors.
Making changes to the track during this callback is undefined behavior. Change the data in pcm but not the track itself.
- Parameters
-
userdata an opaque pointer provided by the app for its personal use. track the track that is being mixed. spec the format of the data in pcm.pcm the raw PCM data in float32 format. samples the number of float values pointed to by pcm.
- Since
- This datatype is available since SDL_mixer 3.0.0.
◆ TrackMixCB
| using SDL::TrackMixCB = typedef MakeFrontCallback< void(TrackRaw track, const AudioSpec* spec, float* pcm, int samples)> |
This callback is fired for different parts of the mixing pipeline, and gives the app visibility into the audio data that is being generated at various stages.
The audio data passed through here is not const data; the app is permitted to change it in any way it likes, and those changes will propagate through the mixing pipeline.
An audiospec is provided. Different tracks might be in different formats, and an app needs to be able to handle that, but SDL_mixer always does its mixing work in 32-bit float samples, even if the inputs or final output are not floating point. As such, spec->format will always be AUDIO_F32 and pcm hardcoded to be a float pointer.
samples is the number of float values pointed to by pcm: samples, not sample frames! There are no promises how many samples will be provided per-callback, and this number can vary wildly from call to call, depending on many factors.
Making changes to the track during this callback is undefined behavior. Change the data in pcm but not the track itself.
- Parameters
-
track the track that is being mixed. spec the format of the data in pcm.pcm the raw PCM data in float32 format. samples the number of float values pointed to by pcm.
- Since
- This datatype is available since SDL_mixer 3.0.0.
◆ TrackStoppedCallback
| using SDL::TrackStoppedCallback = typedef void(SDLCALL*)(void* userdata, TrackRaw track) |
This callback is fired when a track completes playback, either because it ran out of data to mix (and all loops were completed as well), or it was explicitly stopped by the app. Pausing a track will not fire this callback.
It is legal to adjust the track, including changing its input and restarting it. If this is done because it ran out of data in the middle of mixing, the mixer will start mixing the new track state in its current run without any gap in the audio.
This callback will not fire when a playing track is destroyed.
- Parameters
-
userdata an opaque pointer provided by the app for its personal use. track the track that has stopped.
- Since
- This datatype is available since SDL_mixer 3.0.0.
- See also
- Track.SetStoppedCallback
◆ TrackStoppedCB
| using SDL::TrackStoppedCB = typedef MakeFrontCallback<void(TrackRaw track)> |
This callback is fired when a track completes playback, either because it ran out of data to mix (and all loops were completed as well), or it was explicitly stopped by the app. Pausing a track will not fire this callback.
It is legal to adjust the track, including changing its input and restarting it. If this is done because it ran out of data in the middle of mixing, the mixer will start mixing the new track state in its current run without any gap in the audio.
This callback will not fire when a playing track is destroyed.
- Parameters
-
track the track that has stopped.
- Since
- This datatype is available since SDL_mixer 3.0.0.
Function Documentation
◆ Audio() [1/5]
|
inline |
In normal usage, apps should load audio once, maybe at startup, then play it multiple times.
When loading audio, it will be cached fully in RAM in its original data format. Each time it plays, the data will be decoded. For example, an MP3 will be stored in memory in MP3 format and be decompressed on the fly during playback. This is a tradeoff between i/o overhead and memory usage.
If predecode is true, the data will be decompressed during load and stored as raw PCM data. This might dramatically increase loading time and memory usage, but there will be no need to decompress data during playback.
(One could also use Track.SetIOStream() to bypass loading the data into RAM upfront at all, but this offers still different tradeoffs. The correct approach depends on the app's needs and employing different approaches in different situations can make sense.)
Audio objects can be shared between mixers. This function takes a Mixer, to imply this is the most likely place it will be used and loading should try to match its audio format, but the resulting audio can be used elsewhere. If mixer is nullptr, SDL_mixer will set reasonable defaults.
Once a Audio is created, it can be assigned to a Track with Track.SetAudio(), or played without any management with Mixer.PlayAudio().
When done with a Audio, it can be freed with Audio.Destroy().
This function loads data from an IOStream. There is also a version that loads from a path on the filesystem (Mixer.LoadAudio()), and one that accepts properties for ultimate control (LoadAudioWithProperties()).
The IOStream provided must be able to seek, or loading will fail. If the stream can't seek (data is coming from an HTTP connection, etc), consider caching the data to memory or disk first and creating a new stream to read from there.
- Parameters
-
mixer a mixer this audio is intended to be used with. May be nullptr. io the IOStream to load data from. predecode if true, data will be fully uncompressed before returning. closeio true if SDL_mixer should close iobefore returning (success or failure).
- Postcondition
- an audio object that can be used to make sound on a mixer, or nullptr on failure; call GetError() for more information.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ Audio() [2/5]
|
inline |
There are other options for streaming raw PCM: an AudioStream can be connected to a track, as can an IOStream, and will read from those sources on-demand when it is time to mix the audio. This function is useful for loading static audio data that is meant to be played multiple times.
This function will load the raw data in its entirety and cache it in RAM.
Audio objects can be shared between multiple mixers. The mixer parameter just suggests the most likely mixer to use this audio, in case some optimization might be applied, but this is not required, and a nullptr mixer may be specified.
- Parameters
-
mixer a mixer this audio is intended to be used with. May be nullptr. io the IOStream to load data from. spec what format the raw data is in. closeio true if SDL_mixer should close iobefore returning (success or failure).
- Postcondition
- an audio object that can be used to make sound on a mixer on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ Audio() [3/5]
|
inline |
There are other options for streaming raw PCM: an AudioStream can be connected to a track, as can an IOStream, and will read from those sources on-demand when it is time to mix the audio. This function is useful for loading static audio data that is meant to be played multiple times.
This function will load the raw data in its entirety and cache it in RAM, allocating a copy. If the original data will outlive the created Audio, you can use Mixer.LoadRawAudioNoCopy() to avoid extra allocations and copies.
Audio objects can be shared between multiple mixers. The mixer parameter just suggests the most likely mixer to use this audio, in case some optimization might be applied, but this is not required, and a nullptr mixer may be specified.
- Parameters
-
mixer a mixer this audio is intended to be used with. May be nullptr. data the raw PCM data to load. spec what format the raw data is in.
- Postcondition
- an audio object that can be used to make sound on a mixer on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ Audio() [4/5]
|
inline |
This is equivalent to calling:
This function loads data from a path on the filesystem. There is also a version that loads from an IOStream (Mixer.LoadAudio_IO()), and one that accepts properties for ultimate control (LoadAudioWithProperties()).
- Parameters
-
mixer a mixer this audio is intended to be used with. May be nullptr. path the path on the filesystem to load data from. predecode if true, data will be fully uncompressed before returning.
- Postcondition
- an audio object that can be used to make sound on a mixer, or nullptr on failure; call GetError() for more information.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ Audio() [5/5]
|
inline |
Please see Mixer.LoadAudio_IO() for a description of what the various LoadAudio functions do. This function uses properties to dictate how it operates, and exposes functionality the other functions don't provide.
Properties are discussed in SDL's documentation .
These are the supported properties:
prop::Audio.LOAD_IOSTREAM_POINTER: a pointer to an IOStream to be used to load audio data. Required. This stream must be able to seek!prop::Audio.LOAD_CLOSEIO_BOOLEAN: true if SDL_mixer should close the IOStream before returning (success or failure).prop::Audio.LOAD_PREDECODE_BOOLEAN: true if SDL_mixer should fully decode and decompress the data before returning. Otherwise it will be stored in its original state and decompressed on demand.prop::Audio.LOAD_PREFERRED_MIXER_POINTER: a pointer to a Mixer, in case steps can be made to match its format when decoding. Optional.prop::Audio.LOAD_SKIP_METADATA_TAGS_BOOLEAN: true to skip parsing metadata tags, like ID3 and APE tags. This can be used to speed up loading if the data definitely doesn't have these tags. Some decoders will fail if these tags are present when this property is true.prop::Audio.DECODER_STRING: the name of the decoder to use for this data. Optional. If not specified, SDL_mixer will examine the data and choose the best decoder. These names are the same returned from GetAudioDecoder().
Specific decoders might accept additional custom properties, such as where to find soundfonts for MIDI playback, etc.
- Parameters
-
props a set of properties on how to load audio.
- Postcondition
- an audio object that can be used to make sound on a mixer on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ AudioDecoder() [1/2]
|
inline |
Most apps won't need this, as SDL_mixer's usual interfaces will decode audio as needed. However, if one wants to decode an audio file into a memory buffer without playing it, this interface offers that.
This function allows properties to be specified. This is intended to supply file-specific settings, such as where to find SoundFonts for a MIDI file, etc. In most cases, the caller should pass a nullptr to specify no extra properties.
If closeio is true, then io will be closed when this decoder is done with it. If this function fails and closeio is true, then io will be closed before this function returns.
When done with the audio decoder, it can be destroyed with AudioDecoder.Destroy().
This function requires SDL_mixer to have been initialized with a successful call to MIX.Init(), but does not need an actual Mixer to have been created.
- Parameters
-
io the i/o stream from which to load data. closeio if true, close the i/o stream when done with it. props decoder-specific properties. May be nullptr.
- Postcondition
- an audio decoder, ready to decode.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ AudioDecoder() [2/2]
|
inline |
Most apps won't need this, as SDL_mixer's usual interfaces will decode audio as needed. However, if one wants to decode an audio file into a memory buffer without playing it, this interface offers that.
This function allows properties to be specified. This is intended to supply file-specific settings, such as where to find SoundFonts for a MIDI file, etc. In most cases, the caller should pass a nullptr to specify no extra properties.
Properties are discussed in SDL's documentation .
When done with the audio decoder, it can be destroyed with AudioDecoder.Destroy().
This function requires SDL_mixer to have been initialized with a successful call to MIX.Init(), but does not need an actual Mixer to have been created.
- Parameters
-
path the path on the filesystem from which to load data. props decoder-specific properties. May be nullptr.
- Postcondition
- an audio decoder, ready to decode.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ AudioFramesToMS()
|
inline |
This calculates time based on the audio's initial format, even if the format would change mid-stream.
Sample frames are more precise than milliseconds, so out of necessity, this function will approximate by rounding down to the closest full millisecond.
If frames is < 0, this returns -1.
- Parameters
-
audio the audio to query. frames the audio-specific sample frames to convert to milliseconds.
- Returns
- Converted number of milliseconds, or -1 for errors/no input; call GetError() for details.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Audio.MSToFrames
◆ AudioMSToFrames()
|
inline |
This calculates time based on the audio's initial format, even if the format would change mid-stream.
If ms is < 0, this returns -1.
- Parameters
-
audio the audio to query. ms the milliseconds to convert to audio-specific sample frames.
- Returns
- Converted number of sample frames, or -1 for errors/no input; call GetError() for details.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Audio.FramesToMS
◆ CreateAudioDecoder()
|
inline |
Most apps won't need this, as SDL_mixer's usual interfaces will decode audio as needed. However, if one wants to decode an audio file into a memory buffer without playing it, this interface offers that.
This function allows properties to be specified. This is intended to supply file-specific settings, such as where to find SoundFonts for a MIDI file, etc. In most cases, the caller should pass a nullptr to specify no extra properties.
Properties are discussed in SDL's documentation .
When done with the audio decoder, it can be destroyed with AudioDecoder.Destroy().
This function requires SDL_mixer to have been initialized with a successful call to MIX.Init(), but does not need an actual Mixer to have been created.
- Parameters
-
path the path on the filesystem from which to load data. props decoder-specific properties. May be nullptr.
- Returns
- an audio decoder, ready to decode.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ CreateAudioDecoder_IO()
|
inline |
Most apps won't need this, as SDL_mixer's usual interfaces will decode audio as needed. However, if one wants to decode an audio file into a memory buffer without playing it, this interface offers that.
This function allows properties to be specified. This is intended to supply file-specific settings, such as where to find SoundFonts for a MIDI file, etc. In most cases, the caller should pass a nullptr to specify no extra properties.
If closeio is true, then io will be closed when this decoder is done with it. If this function fails and closeio is true, then io will be closed before this function returns.
When done with the audio decoder, it can be destroyed with AudioDecoder.Destroy().
This function requires SDL_mixer to have been initialized with a successful call to MIX.Init(), but does not need an actual Mixer to have been created.
- Parameters
-
io the i/o stream from which to load data. closeio if true, close the i/o stream when done with it. props decoder-specific properties. May be nullptr.
- Returns
- an audio decoder, ready to decode.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ CreateGroup() [1/2]
|
inline |
Tracks are assigned to a mixing group (or if unassigned, they live in a mixer's internal default group). All tracks in a group are mixed together and the app can access this mixed data before it is mixed with all other groups to produce the final output.
This can be a useful feature, but is completely optional; apps can ignore mixing groups entirely and still have a full experience with SDL_mixer.
After creating a group, assign tracks to it with Track.SetGroup(). Use Group.SetPostMixCallback() to access the group's mixed data.
A mixing group can be destroyed with Group.Destroy() when no longer needed. Destroying the mixer will also destroy all its still-existing mixing groups.
- Returns
- a newly-created mixing group on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ CreateGroup() [2/2]
Tracks are assigned to a mixing group (or if unassigned, they live in a mixer's internal default group). All tracks in a group are mixed together and the app can access this mixed data before it is mixed with all other groups to produce the final output.
This can be a useful feature, but is completely optional; apps can ignore mixing groups entirely and still have a full experience with SDL_mixer.
After creating a group, assign tracks to it with Track.SetGroup(). Use Group.SetPostMixCallback() to access the group's mixed data.
A mixing group can be destroyed with Group.Destroy() when no longer needed. Destroying the mixer will also destroy all its still-existing mixing groups.
- Parameters
-
mixer the mixer on which to create a mixing group.
- Returns
- a newly-created mixing group on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ CreateMixer()
Usually you want CreateMixerDevice() instead of this function. The mixer created here can be used with Mixer.Generate() to produce more data on demand, as fast as desired.
An audio format must be specified. This is the format it will output in. This cannot be nullptr.
Once a mixer is created, next steps are usually to load audio (through Mixer.LoadAudio() and friends), create a track (Mixer.CreateTrack()), and play that audio through that track.
When done with the mixer, it can be destroyed with Mixer.Destroy().
- Parameters
-
spec the audio format that mixer will generate.
- Returns
- a mixer that can be used to generate audio on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- CreateMixerDevice
- Mixer.Destroy
◆ CreateMixerDevice()
|
inline |
This is usually the function you want, vs CreateMixer().
You can choose a specific device ID to open, following SDL's usual rules, but often the correct choice is to specify AUDIO_DEVICE_DEFAULT_PLAYBACK and let SDL figure out what device to use (and seamlessly transition you to new hardware if the default changes).
Only playback devices make sense here. Attempting to open a recording device will fail.
This will call Init(INIT_AUDIO) internally; it's safe to call Init() before this call, too, if you intend to enumerate audio devices to choose one to open here.
An audio format can be requested, and the system will try to set the hardware to those specifications, or as close as possible, but this is just a hint. SDL_mixer will handle all data conversion behind the scenes in any case, and specifying a nullptr spec is a reasonable choice. The best reason to specify a format is because you know all your data is in that format and it might save some unnecessary CPU time on conversion.
The actual device format chosen is available through Mixer.GetFormat().
Once a mixer is created, next steps are usually to load audio (through Mixer.LoadAudio() and friends), create a track (Mixer.CreateTrack()), and play that audio through that track.
When done with the mixer, it can be destroyed with Mixer.Destroy().
- Parameters
-
devid the device to open for playback, or AUDIO_DEVICE_DEFAULT_PLAYBACK for the default. spec the audio format to request from the device. May be nullptr.
- Returns
- a mixer that can be used to play audio on success.
- Exceptions
-
Error on failure.
- Thread safety:
- This function should only be called on the main thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- CreateMixer
- Mixer.Destroy
◆ CreateSineWaveAudio() [1/2]
This is useful just to have something to play, perhaps for testing or debugging purposes.
You specify its frequency in Hz (determines the pitch of the sinewave's audio) and amplitude (determines the volume of the sinewave: 1.0f is very loud, 0.0f is silent).
A number of milliseconds of audio to generate can be specified. Specifying a value less than zero will generate infinite audio (when assigned to a Track, the sinewave will play forever).
Audio objects can be shared between multiple mixers. The mixer parameter just suggests the most likely mixer to use this audio, in case some optimization might be applied, but this is not required, and a nullptr mixer may be specified.
- Parameters
-
hz the sinewave's frequency in Hz. amplitude the sinewave's amplitude from 0.0f to 1.0f. ms the maximum number of milliseconds of audio to generate, or less than zero to generate infinite audio.
- Returns
- an audio object that can be used to make sound on a mixer on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ CreateSineWaveAudio() [2/2]
This is useful just to have something to play, perhaps for testing or debugging purposes.
You specify its frequency in Hz (determines the pitch of the sinewave's audio) and amplitude (determines the volume of the sinewave: 1.0f is very loud, 0.0f is silent).
A number of milliseconds of audio to generate can be specified. Specifying a value less than zero will generate infinite audio (when assigned to a Track, the sinewave will play forever).
Audio objects can be shared between multiple mixers. The mixer parameter just suggests the most likely mixer to use this audio, in case some optimization might be applied, but this is not required, and a nullptr mixer may be specified.
- Parameters
-
mixer a mixer this audio is intended to be used with. May be nullptr. hz the sinewave's frequency in Hz. amplitude the sinewave's amplitude from 0.0f to 1.0f. ms the maximum number of milliseconds of audio to generate, or less than zero to generate infinite audio.
- Returns
- an audio object that can be used to make sound on a mixer on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ CreateTrack() [1/2]
|
inline |
A track provides a single source of audio. All currently-playing tracks will be processed and mixed together to form the final output from the mixer.
There are no limits to the number of tracks one may create, beyond running out of memory, but in normal practice there are a small number of tracks that are reused between all loaded audio as appropriate.
Tracks are unique to a specific Mixer and can't be transferred between them.
- Returns
- a new Track on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Destroy
◆ CreateTrack() [2/2]
A track provides a single source of audio. All currently-playing tracks will be processed and mixed together to form the final output from the mixer.
There are no limits to the number of tracks one may create, beyond running out of memory, but in normal practice there are a small number of tracks that are reused between all loaded audio as appropriate.
Tracks are unique to a specific Mixer and can't be transferred between them.
- Parameters
-
mixer the mixer on which to create this track.
- Returns
- a new Track on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Destroy
◆ DecodeAudio() [1/2]
|
inline |
Data is decoded on demand in whatever format is requested. The format is permitted to change between calls.
This function will return the number of bytes decoded, which may be less than requested if there was an error or end-of-file. A return value of zero means the entire file was decoded, -1 means an unrecoverable error happened.
- Parameters
-
audiodecoder the decoder from which to retrieve more data. buffer the memory buffer to store decoded audio. spec the format that audio data will be stored to buffer.
- Returns
- number of bytes decoded on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ DecodeAudio() [2/2]
|
inline |
Data is decoded on demand in whatever format is requested. The format is permitted to change between calls.
This function will return the number of bytes decoded, which may be less than requested if there was an error or end-of-file. A return value of zero means the entire file was decoded, -1 means an unrecoverable error happened.
- Parameters
-
buffer the memory buffer to store decoded audio. spec the format that audio data will be stored to buffer.
- Returns
- number of bytes decoded on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ Destroy() [1/5]
|
inline |
If this mixer was created with CreateMixerDevice(), this function will also close the audio device and call QuitSubSystem(INIT_AUDIO).
Any Group or Track created for this mixer will also be destroyed. Do not access them again or attempt to destroy them after the device is destroyed. Audio objects will not be destroyed, since they can be shared between mixers (but those will all be destroyed during MIX.Quit()).
- Thread safety:
- If this is used with a Mixer from CreateMixerDevice, then this function should only be called on the main thread. If this is used with a Mixer from CreateMixer, then it is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- CreateMixerDevice
- CreateMixer
◆ Destroy() [2/5]
|
inline |
Audio is reference-counted internally, so this function only unrefs it. If doing so causes the reference count to drop to zero, the Audio will be deallocated. This allows the system to safely operate if the audio is still assigned to a Track at the time of destruction. The actual destroying will happen when the track stops using it.
But from the caller's perspective, once this function is called, it should assume the audio pointer has become invalid.
Destroying a nullptr Audio is a legal no-op.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ Destroy() [3/5]
|
inline |
If the track is currently playing, it will be stopped immediately, without any fadeout. If there is a callback set through Track.SetStoppedCallback(), it will not be called.
If the mixer is currently mixing in another thread, this will block until it finishes.
Destroying a nullptr Track is a legal no-op.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ Destroy() [4/5]
|
inline |
Any tracks currently assigned to this group will be reassigned to the mixer's internal default group.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Mixer.CreateGroup
◆ Destroy() [5/5]
|
inline |
Destroying a nullptr AudioDecoder is a legal no-op.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ DestroyAudio()
|
inline |
Audio is reference-counted internally, so this function only unrefs it. If doing so causes the reference count to drop to zero, the Audio will be deallocated. This allows the system to safely operate if the audio is still assigned to a Track at the time of destruction. The actual destroying will happen when the track stops using it.
But from the caller's perspective, once this function is called, it should assume the audio pointer has become invalid.
Destroying a nullptr Audio is a legal no-op.
- Parameters
-
audio the audio to destroy.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ DestroyAudioDecoder()
|
inline |
Destroying a nullptr AudioDecoder is a legal no-op.
- Parameters
-
audiodecoder the audio to destroy.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ DestroyGroup()
|
inline |
Any tracks currently assigned to this group will be reassigned to the mixer's internal default group.
- Parameters
-
group the mixing group to destroy.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Mixer.CreateGroup
◆ DestroyMixer()
|
inline |
If this mixer was created with CreateMixerDevice(), this function will also close the audio device and call QuitSubSystem(INIT_AUDIO).
Any Group or Track created for this mixer will also be destroyed. Do not access them again or attempt to destroy them after the device is destroyed. Audio objects will not be destroyed, since they can be shared between mixers (but those will all be destroyed during MIX.Quit()).
- Parameters
-
mixer the mixer to destroy.
- Thread safety:
- If this is used with a Mixer from CreateMixerDevice, then this function should only be called on the main thread. If this is used with a Mixer from CreateMixer, then it is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- CreateMixerDevice
- CreateMixer
◆ DestroyTrack()
|
inline |
If the track is currently playing, it will be stopped immediately, without any fadeout. If there is a callback set through Track.SetStoppedCallback(), it will not be called.
If the mixer is currently mixing in another thread, this will block until it finishes.
Destroying a nullptr Track is a legal no-op.
- Parameters
-
track the track to destroy.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ FramesToMS() [1/3]
|
inline |
Sample frames are more precise than milliseconds, so out of necessity, this function will approximate by rounding down to the closest full millisecond.
If sample_rate is <= 0, this returns -1. If frames is < 0, this returns
- 1.
- Parameters
-
sample_rate the sample rate to use for conversion. frames the rate-specific sample frames to convert to milliseconds.
- Returns
- Converted number of milliseconds, or -1 for errors; call GetError() for details.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- MSToFrames
◆ FramesToMS() [2/3]
|
inline |
This calculates time based on the audio's initial format, even if the format would change mid-stream.
Sample frames are more precise than milliseconds, so out of necessity, this function will approximate by rounding down to the closest full millisecond.
If frames is < 0, this returns -1.
- Parameters
-
frames the audio-specific sample frames to convert to milliseconds.
- Returns
- Converted number of milliseconds, or -1 for errors/no input; call GetError() for details.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Audio.MSToFrames
◆ FramesToMS() [3/3]
|
inline |
This calculates time based on the track's current input format, which can change when its input does, and also if that input changes formats mid-stream (for example, if decoding a file that is two MP3s concatenated together).
Sample frames are more precise than milliseconds, so out of necessity, this function will approximate by rounding down to the closest full millisecond.
On various errors (MIX.Init() was not called, the track is nullptr), this returns -1. If the track has no input, this returns -1. If frames is < 0, this returns -1.
- Parameters
-
frames the track-specific sample frames to convert to milliseconds.
- Returns
- Converted number of milliseconds, or -1 for errors/no input; call GetError() for details.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.MSToFrames
◆ Generate() [1/2]
|
inline |
SDL_mixer allows the creation of Mixer objects that are not connected to an audio device, by calling CreateMixer() instead of CreateMixerDevice(). Such mixers will not generate output until explicitly requested through this function.
The caller may request as much audio as desired, so long as buflen is a multiple of the sample frame size specified when creating the mixer (for example, if requesting stereo Sint16 audio, buflen must be a multiple of 4: 2 bytes-per-channel times 2 channels).
The mixer will mix as quickly as possible; since it works in sample frames instead of time, it can potentially generate enormous amounts of audio in a small amount of time.
On success, this always fills buffer with buflen bytes of audio; if all playing tracks finish mixing, it will fill the remaining buffer with silence.
Each call to this function will pick up where it left off, playing tracks will continue to mix from the point the previous call completed, etc. The mixer state can be changed between each call in any way desired: tracks can be added, played, stopped, changed, removed, etc. Effectively this function does the same thing SDL_mixer does internally when the audio device needs more audio to play.
This function can not be used with mixers from CreateMixerDevice(); those generate audio as needed internally.
This function returns the number of bytes of real audio mixed, which might be less than buflen. While all buflen bytes of buffer will be initialized, if available tracks to mix run out, the end of the buffer will be initialized with silence; this silence will not be counted in the return value, so the caller has the option to identify how much of the buffer has legitimate contents vs appended silence. As such, any value >= 0 signifies success. A return value of -1 means failure (out of memory, invalid parameters, etc).
- Parameters
-
mixer the mixer for which to generate more audio. buffer a pointer to a buffer to store audio in.
- Returns
- The number of bytes of mixed audio, discounting appended silence, on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- CreateMixer
◆ Generate() [2/2]
|
inline |
SDL_mixer allows the creation of Mixer objects that are not connected to an audio device, by calling CreateMixer() instead of CreateMixerDevice(). Such mixers will not generate output until explicitly requested through this function.
The caller may request as much audio as desired, so long as buflen is a multiple of the sample frame size specified when creating the mixer (for example, if requesting stereo Sint16 audio, buflen must be a multiple of 4: 2 bytes-per-channel times 2 channels).
The mixer will mix as quickly as possible; since it works in sample frames instead of time, it can potentially generate enormous amounts of audio in a small amount of time.
On success, this always fills buffer with buflen bytes of audio; if all playing tracks finish mixing, it will fill the remaining buffer with silence.
Each call to this function will pick up where it left off, playing tracks will continue to mix from the point the previous call completed, etc. The mixer state can be changed between each call in any way desired: tracks can be added, played, stopped, changed, removed, etc. Effectively this function does the same thing SDL_mixer does internally when the audio device needs more audio to play.
This function can not be used with mixers from CreateMixerDevice(); those generate audio as needed internally.
This function returns the number of bytes of real audio mixed, which might be less than buflen. While all buflen bytes of buffer will be initialized, if available tracks to mix run out, the end of the buffer will be initialized with silence; this silence will not be counted in the return value, so the caller has the option to identify how much of the buffer has legitimate contents vs appended silence. As such, any value >= 0 signifies success. A return value of -1 means failure (out of memory, invalid parameters, etc).
- Parameters
-
buffer a pointer to a buffer to store audio in.
- Returns
- The number of bytes of mixed audio, discounting appended silence, on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- CreateMixer
◆ Get3DPosition()
|
inline |
If 3D positioning isn't enabled for this track, through a call to Track.Set3DPosition(), this will return (0,0,0).
- Returns
- the he track's position on successful return.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Set3DPosition
◆ GetAudio()
|
inline |
This returns the Audio object currently assigned to track through a call to Track.SetAudio(). If there is none assigned, or the track has an input that isn't a Audio (such as an AudioStream or IOStream), this will return nullptr.
On various errors (MIX.Init() was not called, the track is nullptr), this returns nullptr, but there is no mechanism to distinguish errors from tracks without a valid input.
- Returns
- a Audio if available, nullptr if not.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.GetAudioStream
◆ GetAudioDecoder()
|
inline |
An audio decoder is what turns specific audio file formats into usable PCM data. For example, there might be an MP3 decoder, or a WAV decoder, etc. SDL_mixer probably has several decoders built in.
The names are capital English letters and numbers, low-ASCII. They don't necessarily map to a specific file format; Some decoders, like "XMP" operate on multiple file types, and more than one decoder might handle the same file type, like "DRMP3" vs "MPG123". Note that in that last example, neither decoder is called "MP3".
The index of a specific decoder is decided during MIX.Init() and does not change until the library is deinitialized. Valid indices are between zero and the return value of GetNumAudioDecoders().
The returned pointer is const memory owned by SDL_mixer; do not free it.
- Parameters
-
index the index of the decoder to query.
- Returns
- a UTF-8 (really, ASCII) string of the decoder's name, or nullptr if
indexis invalid.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- GetNumAudioDecoders
◆ GetAudioDecoderFormat()
|
inline |
Note that some audio files can change format in the middle; some explicitly support this, but a more common example is two MP3 files concatenated together. In many cases, SDL_mixer will correctly handle these sort of files, but this function will only report the initial format a file uses.
- Parameters
-
audiodecoder the audio decoder to query. spec on success, audio format details will be stored here.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetAudioDecoderProperties()
|
inline |
SDL_mixer offers some properties of its own, but this can also be a convenient place to store app-specific data.
A Properties is created the first time this function is called for a given AudioDecoder, if necessary.
The file-specific metadata exposed through this function is identical to those available through Audio.GetProperties(). Please refer to that function's documentation for details.
- Parameters
-
audiodecoder the audio decoder to query.
- Returns
- a valid property ID on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Audio.GetProperties
◆ GetAudioDuration()
This information is also available via the prop::MixMetadata.DURATION_FRAMES_NUMBER property, but it's common enough to provide a simple accessor function.
This reports the length of the data in sample frames, so sample-perfect mixing can be possible. Sample frames are only meaningful as a measure of time if the sample rate (frequency) is also known. To convert from sample frames to milliseconds, use Audio.FramesToMS().
Not all audio file formats can report the complete length of the data they will produce through decoding: some can't calculate it, some might produce infinite audio.
Also, some file formats can only report duration as a unit of time, which means SDL_mixer might have to estimate sample frames from that information. With less precision, the reported duration might be off by a few sample frames in either direction.
This will return a value >= 0 if a duration is known. It might also return DURATION_UNKNOWN or DURATION_INFINITE.
- Parameters
-
audio the audio to query.
- Returns
- the length of the audio in sample frames, or DURATION_UNKNOWN or DURATION_INFINITE.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetAudioFormat()
Note that some audio files can change format in the middle; some explicitly support this, but a more common example is two MP3 files concatenated together. In many cases, SDL_mixer will correctly handle these sort of files, but this function will only report the initial format a file uses.
- Parameters
-
audio the audio to query. spec on success, audio format details will be stored here.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetAudioProperties()
|
inline |
SDL_mixer offers some properties of its own, but this can also be a convenient place to store app-specific data.
A Properties is created the first time this function is called for a given Audio, if necessary.
The following read-only properties are provided by SDL_mixer:
prop::MixMetadata.TITLE_STRING: the audio's title ("Smells Like Teen Spirit").prop::MixMetadata.ARTIST_STRING: the audio's artist name ("Nirvana").prop::MixMetadata.ALBUM_STRING: the audio's album name ("Nevermind").prop::MixMetadata.COPYRIGHT_STRING: the audio's copyright info ("Copyright (c) 1991")prop::MixMetadata.TRACK_NUMBER: the audio's track number on the album (1)prop::MixMetadata.TOTAL_TRACKS_NUMBER: the total tracks on the album (13)prop::MixMetadata.YEAR_NUMBER: the year the audio was released (1991)prop::MixMetadata.DURATION_FRAMES_NUMBER: The sample frames worth of PCM data that comprise this audio. It might be off by a little if the decoder only knows the duration as a unit of time.prop::MixMetadata.DURATION_INFINITE_BOOLEAN: if true, audio never runs out of sound to generate. This isn't necessarily always known to SDL_mixer, though.
Other properties, documented with LoadAudioWithProperties(), may also be present.
Note that the metadata properties are whatever SDL_mixer finds in things like ID3 tags, and they often have very little standardized formatting, may be missing, and can be completely wrong if the original data is untrustworthy (like an MP3 from a P2P file sharing service).
- Parameters
-
audio the audio to query.
- Returns
- a valid property ID on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetAudioStream()
|
inline |
This returns the AudioStream object currently assigned to track through a call to Track.SetAudioStream(). If there is none assigned, or the track has an input that isn't an AudioStream (such as a Audio or IOStream), this will return nullptr.
On various errors (MIX.Init() was not called, the track is nullptr), this returns nullptr, but there is no mechanism to distinguish errors from tracks without a valid input.
- Returns
- an AudioStream if available, nullptr if not.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.GetAudio
◆ GetDuration()
|
inline |
This information is also available via the prop::MixMetadata.DURATION_FRAMES_NUMBER property, but it's common enough to provide a simple accessor function.
This reports the length of the data in sample frames, so sample-perfect mixing can be possible. Sample frames are only meaningful as a measure of time if the sample rate (frequency) is also known. To convert from sample frames to milliseconds, use Audio.FramesToMS().
Not all audio file formats can report the complete length of the data they will produce through decoding: some can't calculate it, some might produce infinite audio.
Also, some file formats can only report duration as a unit of time, which means SDL_mixer might have to estimate sample frames from that information. With less precision, the reported duration might be off by a few sample frames in either direction.
This will return a value >= 0 if a duration is known. It might also return DURATION_UNKNOWN or DURATION_INFINITE.
- Returns
- the length of the audio in sample frames, or DURATION_UNKNOWN or DURATION_INFINITE.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetFadeFrames()
|
inline |
This specifically checks if the track is not stopped (paused or playing), and it is fading in or out, and returns the number of frames remaining in the fade.
If fading out, the returned value will be negative. When fading in, the returned value will be positive. If not fading, this function returns zero.
On various errors (MIX.Init() was not called, the track is nullptr), this returns 0, but there is no mechanism to distinguish errors from tracks that aren't fading.
- Returns
- less than 0 if the track is fading out, greater than 0 if fading in, zero otherwise.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetFormat() [1/3]
|
inline |
Generally you don't need this information, as SDL_mixer will convert data as necessary between inputs you provide and its output format, but it might be useful if trying to match your inputs to reduce conversion and resampling costs.
For mixers created with CreateMixerDevice(), this is the format of the audio device (and may change later if the device itself changes; SDL_mixer will seamlessly handle this change internally, though).
For mixers created with CreateMixer(), this is the format that Mixer.Generate() will produce, as requested at create time, and does not change.
Note that internally, SDL_mixer will work in AUDIO_F32 format before outputting the format specified here, so it would be more efficient to match input data to that, not the final output format.
- Parameters
-
spec where to store the mixer audio format.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetFormat() [2/3]
|
inline |
Note that some audio files can change format in the middle; some explicitly support this, but a more common example is two MP3 files concatenated together. In many cases, SDL_mixer will correctly handle these sort of files, but this function will only report the initial format a file uses.
- Parameters
-
spec on success, audio format details will be stored here.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetFormat() [3/3]
|
inline |
Note that some audio files can change format in the middle; some explicitly support this, but a more common example is two MP3 files concatenated together. In many cases, SDL_mixer will correctly handle these sort of files, but this function will only report the initial format a file uses.
- Parameters
-
spec on success, audio format details will be stored here.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetFrequencyRatio() [1/2]
|
inline |
This returns the last value set through Mixer.SetFrequencyRatio(), or 1.0f if no value has ever been explicitly set.
- Returns
- the mixer's current master frequency ratio.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetFrequencyRatio() [2/2]
|
inline |
The frequency ratio is used to adjust the rate at which audio data is consumed. Changing this effectively modifies the speed and pitch of the track's audio. A value greater than 1.0f will play the audio faster, and at a higher pitch. A value less than 1.0f will play the audio slower, and at a lower pitch. 1.0f is normal speed.
The default value is 1.0f.
On various errors (MIX.Init() was not called, the track is nullptr), this returns 0.0f. Since this is not a valid value to set, this can be seen as an error state.
- Returns
- the current frequency ratio, or 0.0f on failure; call GetError() for more information.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.GetFrequencyRatio
◆ GetGain() [1/2]
|
inline |
This returns the last value set through Mixer.SetGain(), or 1.0f if no value has ever been explicitly set.
- Returns
- the mixer's current master gain.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Mixer.SetGain
- Track.GetGain
◆ GetGain() [2/2]
|
inline |
This returns the last value set through Track.SetGain(), or 1.0f if no value has ever been explicitly set.
- Returns
- the track's current gain.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.SetGain
- Mixer.GetGain
◆ GetGroupMixer()
This is the mixer pointer that was passed to Mixer.CreateGroup().
- Parameters
-
group the group to query.
- Returns
- the mixer associated with the group on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetGroupProperties()
|
inline |
Currently SDL_mixer assigns no properties of its own to a group, but this can be a convenient place to store app-specific data.
A Properties is created the first time this function is called for a given group.
- Parameters
-
group the group to query.
- Returns
- a valid property ID on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetLoops()
|
inline |
This returns the number of loops still pending; if a track will eventually complete and loop to play again one more time, this will return 1. If a track was looping but is on its final iteration of the loop (will stop when this iteration completes), this will return zero.
A track that is looping infinitely will return -1. This value does not report an error in this case.
A track that is stopped (not playing and not paused) will have zero loops remaining.
On various errors (MIX.Init() was not called, the track is nullptr), this returns zero, but there is no mechanism to distinguish errors from non-looping tracks.
- Returns
- the number of pending loops, zero if not looping, and -1 if looping infinitely.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetMixer() [1/2]
|
inline |
This is the mixer pointer that was passed to Mixer.CreateTrack().
- Returns
- the mixer associated with the track on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetMixer() [2/2]
|
inline |
This is the mixer pointer that was passed to Mixer.CreateGroup().
- Returns
- the mixer associated with the group on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetMixerFormat()
Generally you don't need this information, as SDL_mixer will convert data as necessary between inputs you provide and its output format, but it might be useful if trying to match your inputs to reduce conversion and resampling costs.
For mixers created with CreateMixerDevice(), this is the format of the audio device (and may change later if the device itself changes; SDL_mixer will seamlessly handle this change internally, though).
For mixers created with CreateMixer(), this is the format that Mixer.Generate() will produce, as requested at create time, and does not change.
Note that internally, SDL_mixer will work in AUDIO_F32 format before outputting the format specified here, so it would be more efficient to match input data to that, not the final output format.
- Parameters
-
mixer the mixer to query. spec where to store the mixer audio format.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetMixerFrequencyRatio()
|
inline |
This returns the last value set through Mixer.SetFrequencyRatio(), or 1.0f if no value has ever been explicitly set.
- Parameters
-
mixer the mixer to query.
- Returns
- the mixer's current master frequency ratio.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetMixerGain()
|
inline |
This returns the last value set through Mixer.SetGain(), or 1.0f if no value has ever been explicitly set.
- Parameters
-
mixer the mixer to query.
- Returns
- the mixer's current master gain.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Mixer.SetGain
- Track.GetGain
◆ GetMixerProperties()
|
inline |
The following read-only properties are provided by SDL_mixer:
prop::Mixer.DEVICE_NUMBER: the AudioDevice that this mixer has opened for playback. This will be zero (no device) if the mixer was created with Mix_CreateMixer() instead of Mix_CreateMixerDevice().
- Parameters
-
mixer the mixer to query.
- Returns
- a valid property ID on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetNumAudioDecoders()
|
inline |
An audio decoder is what turns specific audio file formats into usable PCM data. For example, there might be an MP3 decoder, or a WAV decoder, etc. SDL_mixer probably has several decoders built in.
The return value can be used to call GetAudioDecoder() in a loop.
The number of decoders available is decided during MIX.Init() and does not change until the library is deinitialized.
- Returns
- the number of decoders available.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- GetAudioDecoder
◆ GetPlaybackPosition()
|
inline |
(Not to be confused with Track.Get3DPosition(), which is positioning of the track in 3D space, not the playback position of its audio data.)
Position is defined in sample frames of decoded audio, not units of time, so that sample-perfect mixing can be achieved. To instead operate in units of time, use Track.FramesToMS() to convert the return value to milliseconds.
Stopped and paused tracks will report the position when they halted. Playing tracks will report the current position, which will change over time.
- Returns
- the track's current sample frame position, or -1 on error; call GetError() for details.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.SetPlaybackPosition
◆ GetProperties() [1/5]
|
inline |
The following read-only properties are provided by SDL_mixer:
prop::Mixer.DEVICE_NUMBER: the AudioDevice that this mixer has opened for playback. This will be zero (no device) if the mixer was created with Mix_CreateMixer() instead of Mix_CreateMixerDevice().
- Returns
- a valid property ID on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetProperties() [2/5]
|
inline |
SDL_mixer offers some properties of its own, but this can also be a convenient place to store app-specific data.
A Properties is created the first time this function is called for a given Audio, if necessary.
The following read-only properties are provided by SDL_mixer:
prop::MixMetadata.TITLE_STRING: the audio's title ("Smells Like Teen Spirit").prop::MixMetadata.ARTIST_STRING: the audio's artist name ("Nirvana").prop::MixMetadata.ALBUM_STRING: the audio's album name ("Nevermind").prop::MixMetadata.COPYRIGHT_STRING: the audio's copyright info ("Copyright (c) 1991")prop::MixMetadata.TRACK_NUMBER: the audio's track number on the album (1)prop::MixMetadata.TOTAL_TRACKS_NUMBER: the total tracks on the album (13)prop::MixMetadata.YEAR_NUMBER: the year the audio was released (1991)prop::MixMetadata.DURATION_FRAMES_NUMBER: The sample frames worth of PCM data that comprise this audio. It might be off by a little if the decoder only knows the duration as a unit of time.prop::MixMetadata.DURATION_INFINITE_BOOLEAN: if true, audio never runs out of sound to generate. This isn't necessarily always known to SDL_mixer, though.
Other properties, documented with LoadAudioWithProperties(), may also be present.
Note that the metadata properties are whatever SDL_mixer finds in things like ID3 tags, and they often have very little standardized formatting, may be missing, and can be completely wrong if the original data is untrustworthy (like an MP3 from a P2P file sharing service).
- Returns
- a valid property ID on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetProperties() [3/5]
|
inline |
Currently SDL_mixer assigns no properties of its own to a track, but this can be a convenient place to store app-specific data.
A Properties is created the first time this function is called for a given track.
- Returns
- a valid property ID on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetProperties() [4/5]
|
inline |
Currently SDL_mixer assigns no properties of its own to a group, but this can be a convenient place to store app-specific data.
A Properties is created the first time this function is called for a given group.
- Returns
- a valid property ID on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetProperties() [5/5]
|
inline |
SDL_mixer offers some properties of its own, but this can also be a convenient place to store app-specific data.
A Properties is created the first time this function is called for a given AudioDecoder, if necessary.
The file-specific metadata exposed through this function is identical to those available through Audio.GetProperties(). Please refer to that function's documentation for details.
- Returns
- a valid property ID on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Audio.GetProperties
◆ GetRemaining()
|
inline |
If the track is playing or paused, and its total duration is known, this will report how much audio is left to mix. If the track is playing, future calls to this function will report different values.
Remaining audio is defined in sample frames of decoded audio, not units of time, so that sample-perfect mixing can be achieved. To instead operate in units of time, use Track.FramesToMS() to convert the return value to milliseconds.
This function does not take into account fade-outs or looping, just the current mixing position vs the duration of the track.
If the duration of the track isn't known, or track is nullptr, this function returns -1. A stopped track reports 0.
- Returns
- the total sample frames still to be mixed, or -1 if unknown.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetTaggedTracks() [1/2]
|
inline |
Tracks are not provided in any guaranteed order.
- Parameters
-
mixer the mixer to query. tag the tag to search.
- Returns
- an array of the tracks, nullptr-terminated on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetTaggedTracks() [2/2]
|
inline |
Tracks are not provided in any guaranteed order.
- Parameters
-
tag the tag to search.
- Returns
- an array of the tracks, nullptr-terminated on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetTags()
|
inline |
Tags are not provided in any guaranteed order.
- Returns
- an array of the tags, nullptr-terminated on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetTrack3DPosition()
If 3D positioning isn't enabled for this track, through a call to Track.Set3DPosition(), this will return (0,0,0).
- Parameters
-
track the track to query.
- Returns
- the he track's position on successful return.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Set3DPosition
◆ GetTrackAudio()
This returns the Audio object currently assigned to track through a call to Track.SetAudio(). If there is none assigned, or the track has an input that isn't a Audio (such as an AudioStream or IOStream), this will return nullptr.
On various errors (MIX.Init() was not called, the track is nullptr), this returns nullptr, but there is no mechanism to distinguish errors from tracks without a valid input.
- Parameters
-
track the track to query.
- Returns
- a Audio if available, nullptr if not.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.GetAudioStream
◆ GetTrackAudioStream()
|
inline |
This returns the AudioStream object currently assigned to track through a call to Track.SetAudioStream(). If there is none assigned, or the track has an input that isn't an AudioStream (such as a Audio or IOStream), this will return nullptr.
On various errors (MIX.Init() was not called, the track is nullptr), this returns nullptr, but there is no mechanism to distinguish errors from tracks without a valid input.
- Parameters
-
track the track to query.
- Returns
- an AudioStream if available, nullptr if not.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.GetAudio
◆ GetTrackFadeFrames()
This specifically checks if the track is not stopped (paused or playing), and it is fading in or out, and returns the number of frames remaining in the fade.
If fading out, the returned value will be negative. When fading in, the returned value will be positive. If not fading, this function returns zero.
On various errors (MIX.Init() was not called, the track is nullptr), this returns 0, but there is no mechanism to distinguish errors from tracks that aren't fading.
- Parameters
-
track the track to query.
- Returns
- less than 0 if the track is fading out, greater than 0 if fading in, zero otherwise.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetTrackFrequencyRatio()
|
inline |
The frequency ratio is used to adjust the rate at which audio data is consumed. Changing this effectively modifies the speed and pitch of the track's audio. A value greater than 1.0f will play the audio faster, and at a higher pitch. A value less than 1.0f will play the audio slower, and at a lower pitch. 1.0f is normal speed.
The default value is 1.0f.
On various errors (MIX.Init() was not called, the track is nullptr), this returns 0.0f. Since this is not a valid value to set, this can be seen as an error state.
- Parameters
-
track the track on which to query the frequency ratio.
- Returns
- the current frequency ratio, or 0.0f on failure; call GetError() for more information.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.GetFrequencyRatio
◆ GetTrackGain()
|
inline |
This returns the last value set through Track.SetGain(), or 1.0f if no value has ever been explicitly set.
- Parameters
-
track the track to query.
- Returns
- the track's current gain.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.SetGain
- Mixer.GetGain
◆ GetTrackLoops()
|
inline |
This returns the number of loops still pending; if a track will eventually complete and loop to play again one more time, this will return 1. If a track was looping but is on its final iteration of the loop (will stop when this iteration completes), this will return zero.
A track that is looping infinitely will return -1. This value does not report an error in this case.
A track that is stopped (not playing and not paused) will have zero loops remaining.
On various errors (MIX.Init() was not called, the track is nullptr), this returns zero, but there is no mechanism to distinguish errors from non-looping tracks.
- Parameters
-
track the track to query.
- Returns
- the number of pending loops, zero if not looping, and -1 if looping infinitely.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetTrackMixer()
This is the mixer pointer that was passed to Mixer.CreateTrack().
- Parameters
-
track the track to query.
- Returns
- the mixer associated with the track on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetTrackPlaybackPosition()
(Not to be confused with Track.Get3DPosition(), which is positioning of the track in 3D space, not the playback position of its audio data.)
Position is defined in sample frames of decoded audio, not units of time, so that sample-perfect mixing can be achieved. To instead operate in units of time, use Track.FramesToMS() to convert the return value to milliseconds.
Stopped and paused tracks will report the position when they halted. Playing tracks will report the current position, which will change over time.
- Parameters
-
track the track to change.
- Returns
- the track's current sample frame position, or -1 on error; call GetError() for details.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.SetPlaybackPosition
◆ GetTrackProperties()
|
inline |
Currently SDL_mixer assigns no properties of its own to a track, but this can be a convenient place to store app-specific data.
A Properties is created the first time this function is called for a given track.
- Parameters
-
track the track to query.
- Returns
- a valid property ID on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetTrackRemaining()
If the track is playing or paused, and its total duration is known, this will report how much audio is left to mix. If the track is playing, future calls to this function will report different values.
Remaining audio is defined in sample frames of decoded audio, not units of time, so that sample-perfect mixing can be achieved. To instead operate in units of time, use Track.FramesToMS() to convert the return value to milliseconds.
This function does not take into account fade-outs or looping, just the current mixing position vs the duration of the track.
If the duration of the track isn't known, or track is nullptr, this function returns -1. A stopped track reports 0.
- Parameters
-
track the track to query.
- Returns
- the total sample frames still to be mixed, or -1 if unknown.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ GetTrackTags()
Tags are not provided in any guaranteed order.
- Parameters
-
track the track to query.
- Returns
- an array of the tags, nullptr-terminated on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ Group()
|
inline |
Tracks are assigned to a mixing group (or if unassigned, they live in a mixer's internal default group). All tracks in a group are mixed together and the app can access this mixed data before it is mixed with all other groups to produce the final output.
This can be a useful feature, but is completely optional; apps can ignore mixing groups entirely and still have a full experience with SDL_mixer.
After creating a group, assign tracks to it with Track.SetGroup(). Use Group.SetPostMixCallback() to access the group's mixed data.
A mixing group can be destroyed with Group.Destroy() when no longer needed. Destroying the mixer will also destroy all its still-existing mixing groups.
- Parameters
-
mixer the mixer on which to create a mixing group.
- Postcondition
- a newly-created mixing group on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ LoadAudio() [1/2]
|
inline |
This is equivalent to calling:
This function loads data from a path on the filesystem. There is also a version that loads from an IOStream (Mixer.LoadAudio_IO()), and one that accepts properties for ultimate control (LoadAudioWithProperties()).
- Parameters
-
mixer a mixer this audio is intended to be used with. May be nullptr. path the path on the filesystem to load data from. predecode if true, data will be fully uncompressed before returning.
- Returns
- an audio object that can be used to make sound on a mixer, or nullptr on failure; call GetError() for more information.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ LoadAudio() [2/2]
|
inline |
This is equivalent to calling:
This function loads data from a path on the filesystem. There is also a version that loads from an IOStream (Mixer.LoadAudio_IO()), and one that accepts properties for ultimate control (LoadAudioWithProperties()).
- Parameters
-
path the path on the filesystem to load data from. predecode if true, data will be fully uncompressed before returning.
- Returns
- an audio object that can be used to make sound on a mixer, or nullptr on failure; call GetError() for more information.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ LoadAudio_IO() [1/2]
|
inline |
In normal usage, apps should load audio once, maybe at startup, then play it multiple times.
When loading audio, it will be cached fully in RAM in its original data format. Each time it plays, the data will be decoded. For example, an MP3 will be stored in memory in MP3 format and be decompressed on the fly during playback. This is a tradeoff between i/o overhead and memory usage.
If predecode is true, the data will be decompressed during load and stored as raw PCM data. This might dramatically increase loading time and memory usage, but there will be no need to decompress data during playback.
(One could also use Track.SetIOStream() to bypass loading the data into RAM upfront at all, but this offers still different tradeoffs. The correct approach depends on the app's needs and employing different approaches in different situations can make sense.)
Audio objects can be shared between mixers. This function takes a Mixer, to imply this is the most likely place it will be used and loading should try to match its audio format, but the resulting audio can be used elsewhere. If mixer is nullptr, SDL_mixer will set reasonable defaults.
Once a Audio is created, it can be assigned to a Track with Track.SetAudio(), or played without any management with Mixer.PlayAudio().
When done with a Audio, it can be freed with Audio.Destroy().
This function loads data from an IOStream. There is also a version that loads from a path on the filesystem (Mixer.LoadAudio()), and one that accepts properties for ultimate control (LoadAudioWithProperties()).
The IOStream provided must be able to seek, or loading will fail. If the stream can't seek (data is coming from an HTTP connection, etc), consider caching the data to memory or disk first and creating a new stream to read from there.
- Parameters
-
io the IOStream to load data from. predecode if true, data will be fully uncompressed before returning. closeio true if SDL_mixer should close iobefore returning (success or failure).
- Returns
- an audio object that can be used to make sound on a mixer, or nullptr on failure; call GetError() for more information.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ LoadAudio_IO() [2/2]
|
inline |
In normal usage, apps should load audio once, maybe at startup, then play it multiple times.
When loading audio, it will be cached fully in RAM in its original data format. Each time it plays, the data will be decoded. For example, an MP3 will be stored in memory in MP3 format and be decompressed on the fly during playback. This is a tradeoff between i/o overhead and memory usage.
If predecode is true, the data will be decompressed during load and stored as raw PCM data. This might dramatically increase loading time and memory usage, but there will be no need to decompress data during playback.
(One could also use Track.SetIOStream() to bypass loading the data into RAM upfront at all, but this offers still different tradeoffs. The correct approach depends on the app's needs and employing different approaches in different situations can make sense.)
Audio objects can be shared between mixers. This function takes a Mixer, to imply this is the most likely place it will be used and loading should try to match its audio format, but the resulting audio can be used elsewhere. If mixer is nullptr, SDL_mixer will set reasonable defaults.
Once a Audio is created, it can be assigned to a Track with Track.SetAudio(), or played without any management with Mixer.PlayAudio().
When done with a Audio, it can be freed with Audio.Destroy().
This function loads data from an IOStream. There is also a version that loads from a path on the filesystem (Mixer.LoadAudio()), and one that accepts properties for ultimate control (LoadAudioWithProperties()).
The IOStream provided must be able to seek, or loading will fail. If the stream can't seek (data is coming from an HTTP connection, etc), consider caching the data to memory or disk first and creating a new stream to read from there.
- Parameters
-
mixer a mixer this audio is intended to be used with. May be nullptr. io the IOStream to load data from. predecode if true, data will be fully uncompressed before returning. closeio true if SDL_mixer should close iobefore returning (success or failure).
- Returns
- an audio object that can be used to make sound on a mixer, or nullptr on failure; call GetError() for more information.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ LoadAudioNoCopy() [1/2]
|
inline |
When loading audio through most other LoadAudio functions, the data will be cached fully in RAM in its original data format, for decoding on-demand. This function does most of the same work as those functions, but instead uses a buffer of memory provided by the app that it does not make a copy of.
This buffer must live for the entire time the returned Audio lives, as the mixer will access the buffer whenever it needs to mix more data.
This function is meant to maximize efficiency: if the data is already in memory and can remain there, don't copy it. This data can be in any supported audio file format (WAV, MP3, etc); it will be decoded on the fly while mixing. Unlike Mixer.LoadAudio(), there is no predecode option offered here, as this is meant to optimize for data that's already in memory and intends to exist there for significant time; since predecoding would only need the file format data once, upfront, one could simply wrap it in SDL_CreateIOFromConstMem() and pass that to Mixer.LoadAudio_IO().
Audio objects can be shared between multiple mixers. The mixer parameter just suggests the most likely mixer to use this audio, in case some optimization might be applied, but this is not required, and a nullptr mixer may be specified.
If free_when_done is true, SDL_mixer will call free(data) when the returned Audio is eventually destroyed. This can be useful when the data is not static, but rather loaded elsewhere for this specific Audio and simply wants to avoid the extra copy.
As audio format information is obtained from the file format metadata, this isn't useful for raw PCM data; in that case, use Mixer.LoadRawAudioNoCopy() instead, which offers an AudioSpec.
Once a Audio is created, it can be assigned to a Track with Track.SetAudio(), or played without any management with Mixer.PlayAudio().
When done with a Audio, it can be freed with Audio.Destroy().
- Parameters
-
mixer a mixer this audio is intended to be used with. May be nullptr. data the buffer where the audio data lives. free_when_done if true, datawill be given to free() when the Audio is destroyed.
- Returns
- an audio object that can be used to make sound on a mixer on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ LoadAudioNoCopy() [2/2]
|
inline |
When loading audio through most other LoadAudio functions, the data will be cached fully in RAM in its original data format, for decoding on-demand. This function does most of the same work as those functions, but instead uses a buffer of memory provided by the app that it does not make a copy of.
This buffer must live for the entire time the returned Audio lives, as the mixer will access the buffer whenever it needs to mix more data.
This function is meant to maximize efficiency: if the data is already in memory and can remain there, don't copy it. This data can be in any supported audio file format (WAV, MP3, etc); it will be decoded on the fly while mixing. Unlike Mixer.LoadAudio(), there is no predecode option offered here, as this is meant to optimize for data that's already in memory and intends to exist there for significant time; since predecoding would only need the file format data once, upfront, one could simply wrap it in SDL_CreateIOFromConstMem() and pass that to Mixer.LoadAudio_IO().
Audio objects can be shared between multiple mixers. The mixer parameter just suggests the most likely mixer to use this audio, in case some optimization might be applied, but this is not required, and a nullptr mixer may be specified.
If free_when_done is true, SDL_mixer will call free(data) when the returned Audio is eventually destroyed. This can be useful when the data is not static, but rather loaded elsewhere for this specific Audio and simply wants to avoid the extra copy.
As audio format information is obtained from the file format metadata, this isn't useful for raw PCM data; in that case, use Mixer.LoadRawAudioNoCopy() instead, which offers an AudioSpec.
Once a Audio is created, it can be assigned to a Track with Track.SetAudio(), or played without any management with Mixer.PlayAudio().
When done with a Audio, it can be freed with Audio.Destroy().
- Parameters
-
data the buffer where the audio data lives. free_when_done if true, datawill be given to free() when the Audio is destroyed.
- Returns
- an audio object that can be used to make sound on a mixer on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ LoadAudioWithProperties()
|
inline |
Please see Mixer.LoadAudio_IO() for a description of what the various LoadAudio functions do. This function uses properties to dictate how it operates, and exposes functionality the other functions don't provide.
Properties are discussed in SDL's documentation .
These are the supported properties:
prop::Audio.LOAD_IOSTREAM_POINTER: a pointer to an IOStream to be used to load audio data. Required. This stream must be able to seek!prop::Audio.LOAD_CLOSEIO_BOOLEAN: true if SDL_mixer should close the IOStream before returning (success or failure).prop::Audio.LOAD_PREDECODE_BOOLEAN: true if SDL_mixer should fully decode and decompress the data before returning. Otherwise it will be stored in its original state and decompressed on demand.prop::Audio.LOAD_PREFERRED_MIXER_POINTER: a pointer to a Mixer, in case steps can be made to match its format when decoding. Optional.prop::Audio.LOAD_SKIP_METADATA_TAGS_BOOLEAN: true to skip parsing metadata tags, like ID3 and APE tags. This can be used to speed up loading if the data definitely doesn't have these tags. Some decoders will fail if these tags are present when this property is true.prop::Audio.DECODER_STRING: the name of the decoder to use for this data. Optional. If not specified, SDL_mixer will examine the data and choose the best decoder. These names are the same returned from GetAudioDecoder().
Specific decoders might accept additional custom properties, such as where to find soundfonts for MIDI playback, etc.
- Parameters
-
props a set of properties on how to load audio.
- Returns
- an audio object that can be used to make sound on a mixer on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ LoadRawAudio() [1/2]
|
inline |
There are other options for streaming raw PCM: an AudioStream can be connected to a track, as can an IOStream, and will read from those sources on-demand when it is time to mix the audio. This function is useful for loading static audio data that is meant to be played multiple times.
This function will load the raw data in its entirety and cache it in RAM, allocating a copy. If the original data will outlive the created Audio, you can use Mixer.LoadRawAudioNoCopy() to avoid extra allocations and copies.
Audio objects can be shared between multiple mixers. The mixer parameter just suggests the most likely mixer to use this audio, in case some optimization might be applied, but this is not required, and a nullptr mixer may be specified.
- Parameters
-
mixer a mixer this audio is intended to be used with. May be nullptr. data the raw PCM data to load. spec what format the raw data is in.
- Returns
- an audio object that can be used to make sound on a mixer on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ LoadRawAudio() [2/2]
|
inline |
There are other options for streaming raw PCM: an AudioStream can be connected to a track, as can an IOStream, and will read from those sources on-demand when it is time to mix the audio. This function is useful for loading static audio data that is meant to be played multiple times.
This function will load the raw data in its entirety and cache it in RAM, allocating a copy. If the original data will outlive the created Audio, you can use Mixer.LoadRawAudioNoCopy() to avoid extra allocations and copies.
Audio objects can be shared between multiple mixers. The mixer parameter just suggests the most likely mixer to use this audio, in case some optimization might be applied, but this is not required, and a nullptr mixer may be specified.
- Parameters
-
data the raw PCM data to load. spec what format the raw data is in.
- Returns
- an audio object that can be used to make sound on a mixer on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ LoadRawAudio_IO() [1/2]
|
inline |
There are other options for streaming raw PCM: an AudioStream can be connected to a track, as can an IOStream, and will read from those sources on-demand when it is time to mix the audio. This function is useful for loading static audio data that is meant to be played multiple times.
This function will load the raw data in its entirety and cache it in RAM.
Audio objects can be shared between multiple mixers. The mixer parameter just suggests the most likely mixer to use this audio, in case some optimization might be applied, but this is not required, and a nullptr mixer may be specified.
- Parameters
-
io the IOStream to load data from. spec what format the raw data is in. closeio true if SDL_mixer should close iobefore returning (success or failure).
- Returns
- an audio object that can be used to make sound on a mixer on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ LoadRawAudio_IO() [2/2]
|
inline |
There are other options for streaming raw PCM: an AudioStream can be connected to a track, as can an IOStream, and will read from those sources on-demand when it is time to mix the audio. This function is useful for loading static audio data that is meant to be played multiple times.
This function will load the raw data in its entirety and cache it in RAM.
Audio objects can be shared between multiple mixers. The mixer parameter just suggests the most likely mixer to use this audio, in case some optimization might be applied, but this is not required, and a nullptr mixer may be specified.
- Parameters
-
mixer a mixer this audio is intended to be used with. May be nullptr. io the IOStream to load data from. spec what format the raw data is in. closeio true if SDL_mixer should close iobefore returning (success or failure).
- Returns
- an audio object that can be used to make sound on a mixer on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ LoadRawAudioNoCopy() [1/2]
|
inline |
This buffer must live for the entire time the returned Audio lives, as the mixer will access the buffer whenever it needs to mix more data.
This function is meant to maximize efficiency: if the data is already in memory and can remain there, don't copy it. But it can also lead to some interesting tricks, like changing the buffer's contents to alter multiple playing tracks at once. (But, of course, be careful when being too clever.)
Audio objects can be shared between multiple mixers. The mixer parameter just suggests the most likely mixer to use this audio, in case some optimization might be applied, but this is not required, and a nullptr mixer may be specified.
If free_when_done is true, SDL_mixer will call free(data) when the returned Audio is eventually destroyed. This can be useful when the data is not static, but rather composed dynamically for this specific Audio and simply wants to avoid the extra copy.
- Parameters
-
mixer a mixer this audio is intended to be used with. May be nullptr. data the buffer where the raw PCM data lives. spec what format the raw data is in. free_when_done if true, datawill be given to free() when the Audio is destroyed.
- Returns
- an audio object that can be used to make sound on a mixer on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ LoadRawAudioNoCopy() [2/2]
|
inline |
This buffer must live for the entire time the returned Audio lives, as the mixer will access the buffer whenever it needs to mix more data.
This function is meant to maximize efficiency: if the data is already in memory and can remain there, don't copy it. But it can also lead to some interesting tricks, like changing the buffer's contents to alter multiple playing tracks at once. (But, of course, be careful when being too clever.)
Audio objects can be shared between multiple mixers. The mixer parameter just suggests the most likely mixer to use this audio, in case some optimization might be applied, but this is not required, and a nullptr mixer may be specified.
If free_when_done is true, SDL_mixer will call free(data) when the returned Audio is eventually destroyed. This can be useful when the data is not static, but rather composed dynamically for this specific Audio and simply wants to avoid the extra copy.
- Parameters
-
data the buffer where the raw PCM data lives. spec what format the raw data is in. free_when_done if true, datawill be given to free() when the Audio is destroyed.
- Returns
- an audio object that can be used to make sound on a mixer on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ Lock()
|
inline |
While locked, the mixer will not be able to mix more audio or change its internal state in another thread. Those other threads will block until the mixer is unlocked again.
Under the hood, this function calls Mutex.Lock(), so all the same rules apply: the lock can be recursive, it must be unlocked the same number of times from the same thread that locked it, etc.
Just about every SDL_mixer API also locks the mixer while doing its work, as does the SDL audio device thread while actual mixing is in progress, so basic use of this library never requires the app to explicitly lock the device to be thread safe. There are two scenarios where this can be useful, however:
- The app has a provided a callback that the mixing thread might call, and there is some app state that needs to be protected against race conditions as changes are made and mixing progresses simultaneously. Any lock can be used for this, but this is a conveniently-available lock.
- The app wants to make multiple, atomic changes to the mix. For example, to start several tracks at the exact same moment, one would lock the mixer, call Track.Play multiple times, and then unlock again; all the tracks will start mixing on the same sample frame.
Each call to this function must be paired with a call to Mixer.Unlock from the same thread. It is safe to lock a mixer multiple times; it remains locked until the final matching unlock call.
Do not lock the mixer for significant amounts of time, or it can cause audio dropouts. Just do simply things quickly and unlock again.
Locking a nullptr mixer is a safe no-op.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Mixer.Unlock
◆ LockMixer()
|
inline |
While locked, the mixer will not be able to mix more audio or change its internal state in another thread. Those other threads will block until the mixer is unlocked again.
Under the hood, this function calls Mutex.Lock(), so all the same rules apply: the lock can be recursive, it must be unlocked the same number of times from the same thread that locked it, etc.
Just about every SDL_mixer API also locks the mixer while doing its work, as does the SDL audio device thread while actual mixing is in progress, so basic use of this library never requires the app to explicitly lock the device to be thread safe. There are two scenarios where this can be useful, however:
- The app has a provided a callback that the mixing thread might call, and there is some app state that needs to be protected against race conditions as changes are made and mixing progresses simultaneously. Any lock can be used for this, but this is a conveniently-available lock.
- The app wants to make multiple, atomic changes to the mix. For example, to start several tracks at the exact same moment, one would lock the mixer, call Track.Play multiple times, and then unlock again; all the tracks will start mixing on the same sample frame.
Each call to this function must be paired with a call to Mixer.Unlock from the same thread. It is safe to lock a mixer multiple times; it remains locked until the final matching unlock call.
Do not lock the mixer for significant amounts of time, or it can cause audio dropouts. Just do simply things quickly and unlock again.
Locking a nullptr mixer is a safe no-op.
- Parameters
-
mixer the mixer to lock. May be nullptr.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Mixer.Unlock
◆ Mixer() [1/2]
|
inline |
This is usually the function you want, vs CreateMixer().
You can choose a specific device ID to open, following SDL's usual rules, but often the correct choice is to specify AUDIO_DEVICE_DEFAULT_PLAYBACK and let SDL figure out what device to use (and seamlessly transition you to new hardware if the default changes).
Only playback devices make sense here. Attempting to open a recording device will fail.
This will call Init(INIT_AUDIO) internally; it's safe to call Init() before this call, too, if you intend to enumerate audio devices to choose one to open here.
An audio format can be requested, and the system will try to set the hardware to those specifications, or as close as possible, but this is just a hint. SDL_mixer will handle all data conversion behind the scenes in any case, and specifying a nullptr spec is a reasonable choice. The best reason to specify a format is because you know all your data is in that format and it might save some unnecessary CPU time on conversion.
The actual device format chosen is available through Mixer.GetFormat().
Once a mixer is created, next steps are usually to load audio (through Mixer.LoadAudio() and friends), create a track (Mixer.CreateTrack()), and play that audio through that track.
When done with the mixer, it can be destroyed with Mixer.Destroy().
- Parameters
-
devid the device to open for playback, or AUDIO_DEVICE_DEFAULT_PLAYBACK for the default. spec the audio format to request from the device. May be nullptr.
- Postcondition
- a mixer that can be used to play audio on success.
- Exceptions
-
Error on failure.
- Thread safety:
- This function should only be called on the main thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- CreateMixer
- Mixer.Destroy
◆ Mixer() [2/2]
|
inline |
Usually you want CreateMixerDevice() instead of this function. The mixer created here can be used with Mixer.Generate() to produce more data on demand, as fast as desired.
An audio format must be specified. This is the format it will output in. This cannot be nullptr.
Once a mixer is created, next steps are usually to load audio (through Mixer.LoadAudio() and friends), create a track (Mixer.CreateTrack()), and play that audio through that track.
When done with the mixer, it can be destroyed with Mixer.Destroy().
- Parameters
-
spec the audio format that mixer will generate.
- Postcondition
- a mixer that can be used to generate audio on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- CreateMixerDevice
- Mixer.Destroy
◆ MixerLock()
|
inline |
While locked, the mixer will not be able to mix more audio or change its internal state in another thread. Those other threads will block until the mixer is unlocked again.
Under the hood, this function calls Mutex.Lock(), so all the same rules apply: the lock can be recursive, it must be unlocked the same number of times from the same thread that locked it, etc.
Just about every SDL_mixer API also locks the mixer while doing its work, as does the SDL audio device thread while actual mixing is in progress, so basic use of this library never requires the app to explicitly lock the device to be thread safe. There are two scenarios where this can be useful, however:
- The app has a provided a callback that the mixing thread might call, and there is some app state that needs to be protected against race conditions as changes are made and mixing progresses simultaneously. Any lock can be used for this, but this is a conveniently-available lock.
- The app wants to make multiple, atomic changes to the mix. For example, to start several tracks at the exact same moment, one would lock the mixer, call Track.Play multiple times, and then unlock again; all the tracks will start mixing on the same sample frame.
Each call to this function must be paired with a call to Mixer.Unlock from the same thread. It is safe to lock a mixer multiple times; it remains locked until the final matching unlock call.
Do not lock the mixer for significant amounts of time, or it can cause audio dropouts. Just do simply things quickly and unlock again.
Locking a nullptr mixer is a safe no-op.
- Parameters
-
resource the mixer to lock. May be nullptr.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Mixer.Unlock
◆ MSToFrames() [1/3]
|
inline |
If sample_rate is <= 0, this returns -1. If ms is < 0, this returns -1.
- Parameters
-
sample_rate the sample rate to use for conversion. ms the milliseconds to convert to rate-specific sample frames.
- Returns
- Converted number of sample frames, or -1 for errors; call GetError() for details.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- FramesToMS
◆ MSToFrames() [2/3]
|
inline |
This calculates time based on the audio's initial format, even if the format would change mid-stream.
If ms is < 0, this returns -1.
- Parameters
-
ms the milliseconds to convert to audio-specific sample frames.
- Returns
- Converted number of sample frames, or -1 for errors/no input; call GetError() for details.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Audio.FramesToMS
◆ MSToFrames() [3/3]
|
inline |
This calculates time based on the track's current input format, which can change when its input does, and also if that input changes formats mid-stream (for example, if decoding a file that is two MP3s concatenated together).
On various errors (MIX.Init() was not called, the track is nullptr), this returns -1. If the track has no input, this returns -1. If ms is < 0, this returns -1.
- Parameters
-
ms the milliseconds to convert to track-specific sample frames.
- Returns
- Converted number of sample frames, or -1 for errors/no input; call GetError() for details.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.FramesToMS
◆ Pause()
|
inline |
A paused track is not considered "stopped," so its TrackStoppedCallback will not fire if paused, but it won't change state by default, generate audio, or generally make progress, until it is resumed.
It is legal to pause a track that's in any state (playing, already paused, or stopped). Unless the track is currently playing, pausing does nothing, and returns true. A false return is only used to signal errors here (such as MIX.Init not being called or track being nullptr).
- Returns
- true if the track has paused, false on error; call GetError() for details.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Resume
◆ PauseAllTracks() [1/2]
|
inline |
A paused track is not considered "stopped," so its TrackStoppedCallback will not fire if paused, but it won't change state by default, generate audio, or generally make progress, until it is resumed.
This function makes all tracks on the specified mixer that are currently playing move to a paused state. They can later be resumed.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Resume
- Mixer.ResumeAllTracks
◆ PauseAllTracks() [2/2]
|
inline |
A paused track is not considered "stopped," so its TrackStoppedCallback will not fire if paused, but it won't change state by default, generate audio, or generally make progress, until it is resumed.
This function makes all tracks on the specified mixer that are currently playing move to a paused state. They can later be resumed.
- Parameters
-
mixer the mixer on which to pause all tracks.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Resume
- Mixer.ResumeAllTracks
◆ Paused()
|
inline |
If this returns true, the track is not currently contributing to the mixer's output but will when resumed (it's "paused"). It is not playing nor stopped.
On various errors (MIX.Init() was not called, the track is nullptr), this returns false, but there is no mechanism to distinguish errors from non-playing tracks.
- Returns
- true if paused, false otherwise.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ PauseTag() [1/2]
|
inline |
A paused track is not considered "stopped," so its TrackStoppedCallback will not fire if paused, but it won't change state by default, generate audio, or generally make progress, until it is resumed.
This function makes all currently-playing tracks on the specified mixer, with a specific tag, move to a paused state. They can later be resumed.
Tracks that match the specified tag that aren't currently playing are ignored.
- Parameters
-
mixer the mixer on which to pause tracks. tag the tag to use when searching for tracks.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ PauseTag() [2/2]
|
inline |
A paused track is not considered "stopped," so its TrackStoppedCallback will not fire if paused, but it won't change state by default, generate audio, or generally make progress, until it is resumed.
This function makes all currently-playing tracks on the specified mixer, with a specific tag, move to a paused state. They can later be resumed.
Tracks that match the specified tag that aren't currently playing are ignored.
- Parameters
-
tag the tag to use when searching for tracks.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ PauseTrack()
|
inline |
A paused track is not considered "stopped," so its TrackStoppedCallback will not fire if paused, but it won't change state by default, generate audio, or generally make progress, until it is resumed.
It is legal to pause a track that's in any state (playing, already paused, or stopped). Unless the track is currently playing, pausing does nothing, and returns true. A false return is only used to signal errors here (such as MIX.Init not being called or track being nullptr).
- Parameters
-
track the track to pause.
- Returns
- true if the track has paused, false on error; call GetError() for details.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Resume
◆ Play()
|
inline |
The track will use whatever input was last assigned to it when playing; an input must be assigned to this track or this function will fail. Inputs are assigned with calls to Track.SetAudio(), Track.SetAudioStream(), or Track.SetIOStream().
If the track is already playing, or paused, this will restart the track with the newly-specified parameters.
As there are several parameters, and more may be added in the future, they are specified with an Properties. The parameters have reasonable defaults, and specifying a 0 for options will choose defaults for everything.
Properties are discussed in SDL's documentation .
These are the supported properties:
prop::Play.LOOPS_NUMBER: The number of times to loop the track when it reaches the end. A value of 1 will loop to the start one time. Zero will not loop at all. A value of -1 requests infinite loops. If the input is not seekable and this value isn't zero, this function will report success but the track will stop at the point it should loop. Default 0.prop::Play.MAX_FRAME_NUMBER: Mix at most to this sample frame position in the track. This will be treated as if the input reach EOF at this point in the audio file. If -1, mix all available audio without a limit. Default -1.prop::Play.MAX_MILLISECONDS_NUMBER: The same as using the prop::Play.MAX_FRAME_NUMBER property, but the value is specified in milliseconds instead of sample frames. If both properties are specified, the sample frames value is favored. Default -1.prop::Play.START_FRAME_NUMBER: Start mixing from this sample frame position in the track's input. A value <= 0 will begin from the start of the track's input. If the input is not seekable and this value is > 0, this function will report failure. Default 0.prop::Play.START_MILLISECOND_NUMBER: The same as using the prop::Play.START_FRAME_NUMBER property, but the value is specified in milliseconds instead of sample frames. If both properties are specified, the sample frames value is favored. Default 0.prop::Play.LOOP_START_FRAME_NUMBER: If the track is looping, this is the sample frame position that the track will loop back to; this lets one play an intro at the start of a track on the first iteration, but have a loop point somewhere in the middle thereafter. A value <= 0 will begin the loop from the start of the track's input. Default 0.prop::Play.LOOP_START_MILLISECOND_NUMBER: The same as using the prop::Play.LOOP_START_FRAME_NUMBER property, but the value is specified in milliseconds instead of sample frames. If both properties are specified, the sample frames value is favored. Default 0.prop::Play.FADE_IN_FRAMES_NUMBER: The number of sample frames over which to fade in the newly-started track. The track will begin mixing silence and reach full volume smoothly over this many sample frames. If the track loops before the fade-in is complete, it will continue to fade correctly from the loop point. A value <= 0 will disable fade-in, so the track starts mixing at full volume. Default 0.prop::Play.FADE_IN_MILLISECONDS_NUMBER: The same as using the prop::Play.FADE_IN_FRAMES_NUMBER property, but the value is specified in milliseconds instead of sample frames. If both properties are specified, the sample frames value is favored. Default 0.prop::Play.FADE_IN_START_GAIN_FLOAT: If fading in, start fading from this volume level. 0.0f is silence and 1.0f is full volume, every in between is a linear change in gain. The specified value will be clamped between 0.0f and 1.0f. Default 0.0f.prop::Play.APPEND_SILENCE_FRAMES_NUMBER: At the end of mixing this track, after all loops are complete, append this many sample frames of silence as if it were part of the audio file. This allows for apps to implement effects in callbacks, like reverb, that need to generate samples past the end of the stream's audio, or perhaps introduce a delay before starting a new sound on the track without having to manage it directly. A value <= 0 generates no silence before stopping the track. Default 0.prop::Play.APPEND_SILENCE_MILLISECONDS_NUMBER: The same as using the prop::Play.APPEND_SILENCE_FRAMES_NUMBER property, but the value is specified in milliseconds instead of sample frames. If both properties are specified, the sample frames value is favored. Default 0.prop::Play.HALT_WHEN_EXHAUSTED_BOOLEAN: If true, when input is completely consumed for the track, the mixer will mark the track as stopped (and call any appropriate TrackStoppedCallback, etc); to play more, the track will need to be restarted. If false, the track will just not contribute to the mix, but it will not be marked as stopped. There may be clever logic tricks this exposes generally, but this property is specifically useful when the track's input is an AudioStream assigned via Track.SetAudioStream(). Setting this property to true can be useful when pushing a complete piece of audio to the stream that has a definite ending, as the track will operate like any other audio was applied. Setting to false means as new data is added to the stream, the mixer will start using it as soon as possible, which is useful when audio should play immediately as it drips in: new VoIP packets, etc. Note that in this situation, if the audio runs out when needed, there will be gaps in the mixed output, so try to buffer enough data to avoid this when possible. Note that a track is not consider exhausted until all its loops and appended silence have been mixed (and also, that loops don't mean anything when the input is an AudioStream). Default true.
If this function fails, mixing of this track will not start (or restart, if it was already started).
- Parameters
-
options a set of properties that control playback. May be zero.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ PlayAudio() [1/2]
|
inline |
This is what we term a "fire-and-forget" sound. Internally, SDL_mixer will manage a temporary track to mix the specified Audio, cleaning it up when complete. No options can be provided for how to do the mixing, like Track.Play() offers, and since the track is not available to the caller, no adjustments can be made to mixing over time.
This is not the function to build an entire game of any complexity around, but it can be convenient to play simple, one-off sounds that can't be stopped early. An example would be a voice saying "GAME OVER" during an unpausable endgame sequence.
There are no limits to the number of fire-and-forget sounds that can mix at once (short of running out of memory), and SDL_mixer keeps an internal pool of temporary tracks it creates as needed and reuses when available.
- Parameters
-
audio the audio input to play.
- Returns
- true if the track has begun mixing, false on error; call GetError() for details.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Play
- Mixer.LoadAudio
◆ PlayAudio() [2/2]
This is what we term a "fire-and-forget" sound. Internally, SDL_mixer will manage a temporary track to mix the specified Audio, cleaning it up when complete. No options can be provided for how to do the mixing, like Track.Play() offers, and since the track is not available to the caller, no adjustments can be made to mixing over time.
This is not the function to build an entire game of any complexity around, but it can be convenient to play simple, one-off sounds that can't be stopped early. An example would be a voice saying "GAME OVER" during an unpausable endgame sequence.
There are no limits to the number of fire-and-forget sounds that can mix at once (short of running out of memory), and SDL_mixer keeps an internal pool of temporary tracks it creates as needed and reuses when available.
- Parameters
-
mixer the mixer on which to play this audio. audio the audio input to play.
- Returns
- true if the track has begun mixing, false on error; call GetError() for details.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Play
- Mixer.LoadAudio
◆ Playing()
|
inline |
If this returns true, the track is currently contributing to the mixer's output (it's "playing"). It is not stopped nor paused.
On various errors (MIX.Init() was not called, the track is nullptr), this returns false, but there is no mechanism to distinguish errors from non-playing tracks.
- Returns
- true if playing, false otherwise.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ PlayTag() [1/2]
|
inline |
This function follows all the same rules as Track.Play(); please refer to its documentation for the details. Unlike that function, Mixer.PlayTag() operates on multiple tracks at once that have the specified tag applied, via Track.Tag().
If all of your tagged tracks have different sample rates, it would make sense to use the *_MILLISECONDS_NUMBER properties in your options, instead of *_FRAMES_NUMBER, and let SDL_mixer figure out how to apply it to each track.
This function returns true if all tagged tracks are started (or restarted). If any track fails, this function returns false, but all tracks that could start will still be started even when this function reports failure.
From the point of view of the mixing process, all tracks that successfully (re)start will do so at the exact same moment.
- Parameters
-
mixer the mixer on which to look for tagged tracks. tag the tag to use when searching for tracks. options the set of options that will be applied to each track.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ PlayTag() [2/2]
|
inline |
This function follows all the same rules as Track.Play(); please refer to its documentation for the details. Unlike that function, Mixer.PlayTag() operates on multiple tracks at once that have the specified tag applied, via Track.Tag().
If all of your tagged tracks have different sample rates, it would make sense to use the *_MILLISECONDS_NUMBER properties in your options, instead of *_FRAMES_NUMBER, and let SDL_mixer figure out how to apply it to each track.
This function returns true if all tagged tracks are started (or restarted). If any track fails, this function returns false, but all tracks that could start will still be started even when this function reports failure.
From the point of view of the mixing process, all tracks that successfully (re)start will do so at the exact same moment.
- Parameters
-
tag the tag to use when searching for tracks. options the set of options that will be applied to each track.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ PlayTrack()
|
inline |
The track will use whatever input was last assigned to it when playing; an input must be assigned to this track or this function will fail. Inputs are assigned with calls to Track.SetAudio(), Track.SetAudioStream(), or Track.SetIOStream().
If the track is already playing, or paused, this will restart the track with the newly-specified parameters.
As there are several parameters, and more may be added in the future, they are specified with an Properties. The parameters have reasonable defaults, and specifying a 0 for options will choose defaults for everything.
Properties are discussed in SDL's documentation .
These are the supported properties:
prop::Play.LOOPS_NUMBER: The number of times to loop the track when it reaches the end. A value of 1 will loop to the start one time. Zero will not loop at all. A value of -1 requests infinite loops. If the input is not seekable and this value isn't zero, this function will report success but the track will stop at the point it should loop. Default 0.prop::Play.MAX_FRAME_NUMBER: Mix at most to this sample frame position in the track. This will be treated as if the input reach EOF at this point in the audio file. If -1, mix all available audio without a limit. Default -1.prop::Play.MAX_MILLISECONDS_NUMBER: The same as using the prop::Play.MAX_FRAME_NUMBER property, but the value is specified in milliseconds instead of sample frames. If both properties are specified, the sample frames value is favored. Default -1.prop::Play.START_FRAME_NUMBER: Start mixing from this sample frame position in the track's input. A value <= 0 will begin from the start of the track's input. If the input is not seekable and this value is > 0, this function will report failure. Default 0.prop::Play.START_MILLISECOND_NUMBER: The same as using the prop::Play.START_FRAME_NUMBER property, but the value is specified in milliseconds instead of sample frames. If both properties are specified, the sample frames value is favored. Default 0.prop::Play.LOOP_START_FRAME_NUMBER: If the track is looping, this is the sample frame position that the track will loop back to; this lets one play an intro at the start of a track on the first iteration, but have a loop point somewhere in the middle thereafter. A value <= 0 will begin the loop from the start of the track's input. Default 0.prop::Play.LOOP_START_MILLISECOND_NUMBER: The same as using the prop::Play.LOOP_START_FRAME_NUMBER property, but the value is specified in milliseconds instead of sample frames. If both properties are specified, the sample frames value is favored. Default 0.prop::Play.FADE_IN_FRAMES_NUMBER: The number of sample frames over which to fade in the newly-started track. The track will begin mixing silence and reach full volume smoothly over this many sample frames. If the track loops before the fade-in is complete, it will continue to fade correctly from the loop point. A value <= 0 will disable fade-in, so the track starts mixing at full volume. Default 0.prop::Play.FADE_IN_MILLISECONDS_NUMBER: The same as using the prop::Play.FADE_IN_FRAMES_NUMBER property, but the value is specified in milliseconds instead of sample frames. If both properties are specified, the sample frames value is favored. Default 0.prop::Play.FADE_IN_START_GAIN_FLOAT: If fading in, start fading from this volume level. 0.0f is silence and 1.0f is full volume, every in between is a linear change in gain. The specified value will be clamped between 0.0f and 1.0f. Default 0.0f.prop::Play.APPEND_SILENCE_FRAMES_NUMBER: At the end of mixing this track, after all loops are complete, append this many sample frames of silence as if it were part of the audio file. This allows for apps to implement effects in callbacks, like reverb, that need to generate samples past the end of the stream's audio, or perhaps introduce a delay before starting a new sound on the track without having to manage it directly. A value <= 0 generates no silence before stopping the track. Default 0.prop::Play.APPEND_SILENCE_MILLISECONDS_NUMBER: The same as using the prop::Play.APPEND_SILENCE_FRAMES_NUMBER property, but the value is specified in milliseconds instead of sample frames. If both properties are specified, the sample frames value is favored. Default 0.prop::Play.HALT_WHEN_EXHAUSTED_BOOLEAN: If true, when input is completely consumed for the track, the mixer will mark the track as stopped (and call any appropriate TrackStoppedCallback, etc); to play more, the track will need to be restarted. If false, the track will just not contribute to the mix, but it will not be marked as stopped. There may be clever logic tricks this exposes generally, but this property is specifically useful when the track's input is an AudioStream assigned via Track.SetAudioStream(). Setting this property to true can be useful when pushing a complete piece of audio to the stream that has a definite ending, as the track will operate like any other audio was applied. Setting to false means as new data is added to the stream, the mixer will start using it as soon as possible, which is useful when audio should play immediately as it drips in: new VoIP packets, etc. Note that in this situation, if the audio runs out when needed, there will be gaps in the mixed output, so try to buffer enough data to avoid this when possible. Note that a track is not consider exhausted until all its loops and appended silence have been mixed (and also, that loops don't mean anything when the input is an AudioStream). Default true.
If this function fails, mixing of this track will not start (or restart, if it was already started).
- Parameters
-
track the track to start (or restart) mixing. options a set of properties that control playback. May be zero.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ reset()
|
inline |
While locked, the mixer will not be able to mix more audio or change its internal state another thread. Those other threads will block until the mixer is unlocked again.
Under the hood, this function calls Mutex.Lock(), so all the same rules apply: the lock can be recursive, it must be unlocked the same number of times from the same thread that locked it, etc.
Unlocking a nullptr mixer is a safe no-op.
- Thread safety:
- This call must be paired with a previous Mixer.Lock call on the same thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Mixer.Lock
◆ Resume()
|
inline |
A paused track is not considered "stopped," so its TrackStoppedCallback will not fire if paused, but it won't change state by default, generate audio, or generally make progress, until it is resumed.
It is legal to resume a track that's in any state (playing, paused, or stopped). Unless the track is currently paused, resuming does nothing, and returns true. A false return is only used to signal errors here (such as MIX.Init not being called or track being nullptr).
- Returns
- true if the track has resumed, false on error; call GetError() for details.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Pause
◆ ResumeAllTracks() [1/2]
|
inline |
A paused track is not considered "stopped," so its TrackStoppedCallback will not fire if paused, but it won't change state by default, generate audio, or generally make progress, until it is resumed.
This function makes all tracks on the specified mixer that are currently paused move to a playing state.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Pause
- Mixer.PauseAllTracks
◆ ResumeAllTracks() [2/2]
|
inline |
A paused track is not considered "stopped," so its TrackStoppedCallback will not fire if paused, but it won't change state by default, generate audio, or generally make progress, until it is resumed.
This function makes all tracks on the specified mixer that are currently paused move to a playing state.
- Parameters
-
mixer the mixer on which to resume all tracks.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Pause
- Mixer.PauseAllTracks
◆ ResumeTag() [1/2]
|
inline |
A paused track is not considered "stopped," so its TrackStoppedCallback will not fire if paused, but it won't change state by default, generate audio, or generally make progress, until it is resumed.
This function makes all currently-paused tracks on the specified mixer, with a specific tag, move to a playing state.
Tracks that match the specified tag that aren't currently paused are ignored.
- Parameters
-
mixer the mixer on which to resume tracks. tag the tag to use when searching for tracks.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ ResumeTag() [2/2]
|
inline |
A paused track is not considered "stopped," so its TrackStoppedCallback will not fire if paused, but it won't change state by default, generate audio, or generally make progress, until it is resumed.
This function makes all currently-paused tracks on the specified mixer, with a specific tag, move to a playing state.
Tracks that match the specified tag that aren't currently paused are ignored.
- Parameters
-
tag the tag to use when searching for tracks.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ ResumeTrack()
|
inline |
A paused track is not considered "stopped," so its TrackStoppedCallback will not fire if paused, but it won't change state by default, generate audio, or generally make progress, until it is resumed.
It is legal to resume a track that's in any state (playing, paused, or stopped). Unless the track is currently paused, resuming does nothing, and returns true. A false return is only used to signal errors here (such as MIX.Init not being called or track being nullptr).
- Parameters
-
track the track to resume.
- Returns
- true if the track has resumed, false on error; call GetError() for details.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Pause
◆ Set3DPosition()
|
inline |
(Please note that SDL_mixer is not intended to be a extremely powerful 3D API. It lacks 3D features that other APIs like OpenAL offer: there's no doppler effect, distance models, rolloff, etc. This is meant to be Good Enough for games that can use some positional sounds and can even take advantage of surround-sound configurations.)
If position is not nullptr, this track will be switched into 3D positional mode. If position is nullptr, this will disable positional mixing (both the full 3D spatialization of this function and forced-stereo mode of Track.SetStereo()).
In 3D positional mode, SDL_mixer will mix this track as if it were positioned in 3D space, including distance attenuation (quieter as it gets further from the listener) and spatialization (positioned on the correct speakers to suggest direction, either with stereo outputs or full surround sound).
For a mono speaker output, spatialization is effectively disabled but distance attenuation will still work, which is all you can really do with a single speaker.
The coordinate system operates like OpenGL or OpenAL: a "right-handed" coordinate system. See Point3D for the details.
The listener is always at coordinate (0,0,0) and can't be changed.
The track's input will be converted to mono (1 channel) so it can be rendered across the correct speakers.
- Parameters
-
position the new 3D position for the track. May be nullptr.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Get3DPosition
- Track.SetStereo
◆ SetAudio()
|
inline |
A Audio is audio data stored in RAM (possibly still in a compressed form). One Audio can be assigned to multiple tracks at once.
Once a track has a valid input, it can start mixing sound by calling Track.Play(), or possibly Mixer.PlayTag().
Calling this function with a nullptr audio input is legal, and removes any input from the track. If the track was currently playing, the next time the mixer runs, it'll notice this and mark the track as stopped, calling any assigned TrackStoppedCallback.
It is legal to change the input of a track while it's playing, however some states, like loop points, may cease to make sense with the new audio. In such a case, one can call Track.Play again to adjust parameters.
The track will hold a reference to the provided Audio, so it is safe to call Audio.Destroy() on it while the track is still using it. The track will drop its reference (and possibly free the resources) once it is no longer using the Audio.
- Parameters
-
audio the new audio input to set. May be nullptr.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ SetAudioStream()
|
inline |
Using an audio stream allows the application to generate any type of audio, in any format, possibly procedurally or on-demand, and mix in with all other tracks.
When a track uses an audio stream, it will call AudioStream.GetData as it needs more audio to mix. The app can either buffer data to the stream ahead of time, or set a callback on the stream to provide data as needed. Please refer to SDL's documentation for details.
A given audio stream may only be assigned to a single track at a time; duplicate assignments won't return an error, but assigning a stream to multiple tracks will cause each track to read from the stream arbitrarily, causing confusion and incorrect mixing.
Once a track has a valid input, it can start mixing sound by calling Track.Play(), or possibly Mixer.PlayTag().
Calling this function with a nullptr audio stream is legal, and removes any input from the track. If the track was currently playing, the next time the mixer runs, it'll notice this and mark the track as stopped, calling any assigned TrackStoppedCallback.
It is legal to change the input of a track while it's playing, however some states, like loop points, may cease to make sense with the new audio. In such a case, one can call Track.Play again to adjust parameters.
The provided audio stream must remain valid until the track no longer needs it (either by changing the track's input or destroying the track).
- Parameters
-
stream the audio stream to use as the track's input.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ SetCookedCallback() [1/2]
|
inline |
As a track needs to mix more data, it pulls from its input (a Audio, an AudioStream, etc). This input might be a compressed file format, like MP3, so a little more data is uncompressed from it.
Once the track has PCM data to start operating on, and its raw callback has completed, it will begin to transform the audio: gain, fading, frequency ratio, 3D positioning, etc.
A callback can be fired after all these transformations, but before the transformed data is mixed into other tracks. This lets an app view the data at the last moment that it is still a part of this track. It can also change the data in any way it pleases during this callback, and the mixer will continue as if this data came directly from the input.
Each track has its own unique cooked callback.
Passing a nullptr callback here is legal; it disables this track's callback.
- Parameters
-
cb the function to call when the track mixes. May be nullptr. userdata an opaque pointer provided to the callback for its own personal use.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- TrackMixCallback
- Track.SetRawCallback
◆ SetCookedCallback() [2/2]
|
inline |
As a track needs to mix more data, it pulls from its input (a Audio, an AudioStream, etc). This input might be a compressed file format, like MP3, so a little more data is uncompressed from it.
Once the track has PCM data to start operating on, and its raw callback has completed, it will begin to transform the audio: gain, fading, frequency ratio, 3D positioning, etc.
A callback can be fired after all these transformations, but before the transformed data is mixed into other tracks. This lets an app view the data at the last moment that it is still a part of this track. It can also change the data in any way it pleases during this callback, and the mixer will continue as if this data came directly from the input.
Each track has its own unique cooked callback.
Passing a nullptr callback here is legal; it disables this track's callback.
- Parameters
-
cb the function to call when the track mixes. May be nullptr.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- TrackMixCallback
- Track.SetRawCallback
◆ SetFrequencyRatio() [1/2]
|
inline |
Each mixer has a master frequency ratio, that affects the entire mix. This can cause the final output to change speed and pitch. A value greater than 1.0f will play the audio faster, and at a higher pitch. A value less than 1.0f will play the audio slower, and at a lower pitch. 1.0f is normal speed.
Each track also has a frequency ratio; it will be applied when mixing that track's audio regardless of the master setting. The master setting affects the final output after all mixing has been completed.
A mixer's master frequency ratio defaults to 1.0f.
This value can be changed at any time to adjust the future mix.
- Parameters
-
ratio the frequency ratio. Must be between 0.01f and 100.0f.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ SetFrequencyRatio() [2/2]
|
inline |
The frequency ratio is used to adjust the rate at which audio data is consumed. Changing this effectively modifies the speed and pitch of the track's audio. A value greater than 1.0f will play the audio faster, and at a higher pitch. A value less than 1.0f will play the audio slower, and at a lower pitch. 1.0f is normal speed.
The default value is 1.0f.
This value can be changed at any time to adjust the future mix.
- Parameters
-
ratio the frequency ratio. Must be between 0.01f and 100.0f.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.GetFrequencyRatio
◆ SetGain() [1/2]
|
inline |
Each mixer has a master gain, to adjust the volume of the entire mix. Each sample passing through the pipeline is modulated by this gain value. A gain of zero will generate silence, 1.0f will not change the mixed volume, and larger than 1.0f will increase the volume. Negative values are illegal. There is no maximum gain specified, but this can quickly get extremely loud, so please be careful with this setting.
A mixer's master gain defaults to 1.0f.
This value can be changed at any time to adjust the future mix.
- Parameters
-
gain the new gain value.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Mixer.GetGain
- Track.SetGain
◆ SetGain() [2/2]
|
inline |
Each track has its own gain, to adjust its overall volume. Each sample from this track is modulated by this gain value. A gain of zero will generate silence, 1.0f will not change the mixed volume, and larger than 1.0f will increase the volume. Negative values are illegal. There is no maximum gain specified, but this can quickly get extremely loud, so please be careful with this setting.
A track's gain defaults to 1.0f.
This value can be changed at any time to adjust the future mix.
- Parameters
-
gain the new gain value.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.GetGain
- Mixer.SetGain
◆ SetGroup()
|
inline |
All tracks in a group are mixed together, and that output is made available to the app before it is mixed into the final output.
Tracks can only be in one group at a time, and the track and group must have been created on the same Mixer.
Setting a track to a nullptr group will remove it from any app-created groups, and reassign it to the mixer's internal default group.
- Parameters
-
group the new mixing group to assign to. May be nullptr.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ SetGroupPostMixCallback() [1/2]
|
inline |
After all playing tracks in a mixer group have pulled in more data from their inputs, transformed it, and mixed together into a single buffer, a callback can be fired. This lets an app view the data at the last moment that it is still a part of this group. It can also change the data in any way it pleases during this callback, and the mixer will continue as if this data came directly from the group's mix buffer.
Each group has its own unique callback. Tracks that aren't in an explicit Group are mixed in an internal grouping that is not available to the app.
Passing a nullptr callback here is legal; it disables this group's callback.
- Parameters
-
group the mixing group to assign this callback to. cb the function to call when the group mixes. May be nullptr. userdata an opaque pointer provided to the callback for its own personal use.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- GroupMixCallback
◆ SetGroupPostMixCallback() [2/2]
|
inline |
After all playing tracks in a mixer group have pulled in more data from their inputs, transformed it, and mixed together into a single buffer, a callback can be fired. This lets an app view the data at the last moment that it is still a part of this group. It can also change the data in any way it pleases during this callback, and the mixer will continue as if this data came directly from the group's mix buffer.
Each group has its own unique callback. Tracks that aren't in an explicit Group are mixed in an internal grouping that is not available to the app.
Passing a nullptr callback here is legal; it disables this group's callback.
- Parameters
-
group the mixing group to assign this callback to. cb the function to call when the group mixes. May be nullptr.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- GroupMixCallback
◆ SetIOStream()
|
inline |
This is not the recommended way to set a track's input, but this can be useful for a very specific scenario: a large file, to be played once, that must be read from disk in small chunks as needed. In most cases, however, it is preferable to create a Audio ahead of time and use Track.SetAudio() instead.
The stream supplied here should provide an audio file in a supported format. SDL_mixer will parse it during this call to make sure it's valid, and then will read file data from the stream as it needs to decode more during mixing.
The stream must be able to seek through the complete set of data, or this function will fail.
A given IOStream may only be assigned to a single track at a time; duplicate assignments won't return an error, but assigning a stream to multiple tracks will cause each track to read from the stream arbitrarily, causing confusion, incorrect mixing, or failure to decode.
Once a track has a valid input, it can start mixing sound by calling Track.Play(), or possibly Mixer.PlayTag().
Calling this function with a nullptr stream is legal, and removes any input from the track. If the track was currently playing, the next time the mixer runs, it'll notice this and mark the track as stopped, calling any assigned TrackStoppedCallback.
It is legal to change the input of a track while it's playing, however some states, like loop points, may cease to make sense with the new audio. In such a case, one can call Track.Play again to adjust parameters.
The provided stream must remain valid until the track no longer needs it (either by changing the track's input or destroying the track).
- Parameters
-
io the new i/o stream to use as the track's input. closeio if true, close the stream when done with it.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.SetRawIOStream
◆ SetLoops()
|
inline |
This replaces any previously-set remaining loops. A value of 1 will loop to the start of playback one time. Zero will not loop at all. A value of -1 requests infinite loops. If the input is not seekable and num_loops isn't zero, this function will report success but the track will stop at the point it should loop.
The new loop count replaces any previous state, even if the track has already looped.
This has no effect on a track that is stopped, or rather, starting a stopped track later will set a new loop count, replacing this value. Stopped tracks can specify a loop count while starting via prop::Play.LOOPS_NUMBER. This function is intended to alter that count in the middle of playback.
- Parameters
-
num_loops new number of times to loop. Zero to disable looping, -1 to loop infinitely.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.GetLoops
◆ SetMixerFrequencyRatio()
|
inline |
Each mixer has a master frequency ratio, that affects the entire mix. This can cause the final output to change speed and pitch. A value greater than 1.0f will play the audio faster, and at a higher pitch. A value less than 1.0f will play the audio slower, and at a lower pitch. 1.0f is normal speed.
Each track also has a frequency ratio; it will be applied when mixing that track's audio regardless of the master setting. The master setting affects the final output after all mixing has been completed.
A mixer's master frequency ratio defaults to 1.0f.
This value can be changed at any time to adjust the future mix.
- Parameters
-
mixer the mixer to adjust. ratio the frequency ratio. Must be between 0.01f and 100.0f.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ SetMixerGain()
|
inline |
Each mixer has a master gain, to adjust the volume of the entire mix. Each sample passing through the pipeline is modulated by this gain value. A gain of zero will generate silence, 1.0f will not change the mixed volume, and larger than 1.0f will increase the volume. Negative values are illegal. There is no maximum gain specified, but this can quickly get extremely loud, so please be careful with this setting.
A mixer's master gain defaults to 1.0f.
This value can be changed at any time to adjust the future mix.
- Parameters
-
mixer the mixer to adjust. gain the new gain value.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Mixer.GetGain
- Track.SetGain
◆ SetOutputChannelMap()
|
inline |
Channel maps are optional; most things do not need them, instead passing data in the order that SDL expects.
The output channel map reorders track data after transformations and before it is mixed into a mixer group. This can be useful for reversing stereo channels, for example.
Each item in the array represents an input channel, and its value is the channel that it should be remapped to. To reverse a stereo signal's left and right values, you'd have an array of { 1, 0 }. It is legal to remap multiple channels to the same thing, so { 1, 1 } would duplicate the right channel to both channels of a stereo signal. An element in the channel map set to -1 instead of a valid channel will mute that channel, setting it to a silence value.
You cannot change the number of channels through a channel map, just reorder/mute them.
Tracks default to no remapping applied. Passing a nullptr channel map is legal, and turns off remapping.
SDL_mixer will copy the channel map; the caller does not have to save this array after this call.
- Parameters
-
chmap the new channel map, nullptr to reset to default.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ SetPlaybackPosition()
|
inline |
(Not to be confused with Track.Set3DPosition(), which is positioning of the track in 3D space, not the playback position of its audio data.)
On a playing track, the next time the mixer runs, it will start mixing from the new position.
Position is defined in sample frames of decoded audio, not units of time, so that sample-perfect mixing can be achieved. To instead operate in units of time, use Track.MSToFrames() to get the approximate sample frames for a given tick.
This function requires an input that can seek (so it can not be used if the input was set with Track.SetAudioStream()), and a audio file format that allows seeking. SDL_mixer's decoders for some file formats do not offer seeking, or can only seek to times, not exact sample frames, in which case the final position may be off by some amount of sample frames. Please check your audio data and file bug reports if appropriate.
It's legal to call this function on a track that is stopped, but a future call to Track.Play() will reset the start position anyhow. Paused tracks will resume at the new input position.
- Parameters
-
frames the sample frame position to seek to.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.GetPlaybackPosition
◆ SetPostMixCallback() [1/5]
|
inline |
After all playing tracks in a mixer group have pulled in more data from their inputs, transformed it, and mixed together into a single buffer, a callback can be fired. This lets an app view the data at the last moment that it is still a part of this group. It can also change the data in any way it pleases during this callback, and the mixer will continue as if this data came directly from the group's mix buffer.
Each group has its own unique callback. Tracks that aren't in an explicit Group are mixed in an internal grouping that is not available to the app.
Passing a nullptr callback here is legal; it disables this group's callback.
- Parameters
-
cb the function to call when the group mixes. May be nullptr. userdata an opaque pointer provided to the callback for its own personal use.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- GroupMixCallback
◆ SetPostMixCallback() [2/5]
|
inline |
After all mixer groups have processed, their buffers are mixed together into a single buffer for the final output, at which point a callback can be fired. This lets an app view the data at the last moment before mixing completes. It can also change the data in any way it pleases during this callback, and the mixer will continue as if this data is the final output.
Each mixer has its own unique callback.
Passing a nullptr callback here is legal; it disables this mixer's callback.
- Parameters
-
mixer the mixer to assign this callback to. cb the function to call when the mixer mixes. May be nullptr. userdata an opaque pointer provided to the callback for its own personal use.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- PostMixCallback
◆ SetPostMixCallback() [3/5]
After all mixer groups have processed, their buffers are mixed together into a single buffer for the final output, at which point a callback can be fired. This lets an app view the data at the last moment before mixing completes. It can also change the data in any way it pleases during this callback, and the mixer will continue as if this data is the final output.
Each mixer has its own unique callback.
Passing a nullptr callback here is legal; it disables this mixer's callback.
- Parameters
-
mixer the mixer to assign this callback to. cb the function to call when the mixer mixes. May be nullptr.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- PostMixCallback
◆ SetPostMixCallback() [4/5]
|
inline |
After all mixer groups have processed, their buffers are mixed together into a single buffer for the final output, at which point a callback can be fired. This lets an app view the data at the last moment before mixing completes. It can also change the data in any way it pleases during this callback, and the mixer will continue as if this data is the final output.
Each mixer has its own unique callback.
Passing a nullptr callback here is legal; it disables this mixer's callback.
- Parameters
-
cb the function to call when the mixer mixes. May be nullptr. userdata an opaque pointer provided to the callback for its own personal use.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- PostMixCallback
◆ SetPostMixCallback() [5/5]
|
inline |
After all mixer groups have processed, their buffers are mixed together into a single buffer for the final output, at which point a callback can be fired. This lets an app view the data at the last moment before mixing completes. It can also change the data in any way it pleases during this callback, and the mixer will continue as if this data is the final output.
Each mixer has its own unique callback.
Passing a nullptr callback here is legal; it disables this mixer's callback.
- Parameters
-
cb the function to call when the mixer mixes. May be nullptr.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- PostMixCallback
◆ SetRawCallback() [1/2]
|
inline |
As a track needs to mix more data, it pulls from its input (a Audio, an AudioStream, etc). This input might be a compressed file format, like MP3, so a little more data is uncompressed from it.
Once the track has PCM data to start operating on, it can fire a callback before any changes to the raw PCM input have happened. This lets an app view the data before it has gone through transformations such as gain, 3D positioning, fading, etc. It can also change the data in any way it pleases during this callback, and the mixer will continue as if this data came directly from the input.
Each track has its own unique raw callback.
Passing a nullptr callback here is legal; it disables this track's callback.
- Parameters
-
cb the function to call when the track mixes. May be nullptr. userdata an opaque pointer provided to the callback for its own personal use.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ SetRawCallback() [2/2]
|
inline |
As a track needs to mix more data, it pulls from its input (a Audio, an AudioStream, etc). This input might be a compressed file format, like MP3, so a little more data is uncompressed from it.
Once the track has PCM data to start operating on, it can fire a callback before any changes to the raw PCM input have happened. This lets an app view the data before it has gone through transformations such as gain, 3D positioning, fading, etc. It can also change the data in any way it pleases during this callback, and the mixer will continue as if this data came directly from the input.
Each track has its own unique raw callback.
Passing a nullptr callback here is legal; it disables this track's callback.
- Parameters
-
cb the function to call when the track mixes. May be nullptr.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ SetRawIOStream()
|
inline |
This is not the recommended way to set a track's input, but this can be useful for a very specific scenario: a large file, to be played once, that must be read from disk in small chunks as needed. In most cases, however, it is preferable to create a Audio ahead of time and use Track.SetAudio() instead.
Also, an Track.SetAudioStream() can also provide raw PCM audio to a track, via an AudioStream, which might be preferable unless the data is already coming directly from an IOStream.
The stream supplied here should provide an audio in raw PCM format.
A given IOStream may only be assigned to a single track at a time; duplicate assignments won't return an error, but assigning a stream to multiple tracks will cause each track to read from the stream arbitrarily, causing confusion and incorrect mixing.
Once a track has a valid input, it can start mixing sound by calling Track.Play(), or possibly Mixer.PlayTag().
Calling this function with a nullptr stream is legal, and removes any input from the track. If the track was currently playing, the next time the mixer runs, it'll notice this and mark the track as stopped, calling any assigned TrackStoppedCallback.
It is legal to change the input of a track while it's playing, however some states, like loop points, may cease to make sense with the new audio. In such a case, one can call Track.Play again to adjust parameters.
The provided stream must remain valid until the track no longer needs it (either by changing the track's input or destroying the track).
- Parameters
-
io the new i/o stream to use as the track's input. spec the format of the PCM data that the IOStream will provide. closeio if true, close the stream when done with it.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ SetStereo()
|
inline |
This will cause the output of the track to convert to stereo, and then mix it only onto the Front Left and Front Right speakers, regardless of the speaker configuration. The left and right channels are modulated by gains, which can be used to produce panning effects. This function may be called to adjust the gains at any time.
If gains is not nullptr, this track will be switched into forced-stereo mode. If gains is nullptr, this will disable spatialization (both the forced-stereo mode of this function and full 3D spatialization of Track.Set3DPosition()).
Negative gains are clamped to zero; there is no clamp for maximum, so one could set the value > 1.0f to make a channel louder.
The track's 3D position, reported by Track.Get3DPosition(), will be reset to (0, 0, 0).
- Parameters
-
gains the per-channel gains, or nullptr to disable spatialization.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Set3DPosition
◆ SetStoppedCallback() [1/2]
|
inline |
When a track completes playback, either because it ran out of data to mix (and all loops were completed as well), or it was explicitly stopped by the app, it will fire the callback specified here.
Each track has its own unique callback.
Passing a nullptr callback here is legal; it disables this track's callback.
Pausing a track will not fire the callback, nor will the callback fire on a playing track that is being destroyed.
It is legal to adjust the track, including changing its input and restarting it. If this is done because it ran out of data in the middle of mixing, the mixer will start mixing the new track state in its current run without any gap in the audio.
- Parameters
-
cb the function to call when the track stops. May be nullptr. userdata an opaque pointer provided to the callback for its own personal use.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- TrackStoppedCallback
◆ SetStoppedCallback() [2/2]
|
inline |
When a track completes playback, either because it ran out of data to mix (and all loops were completed as well), or it was explicitly stopped by the app, it will fire the callback specified here.
Each track has its own unique callback.
Passing a nullptr callback here is legal; it disables this track's callback.
Pausing a track will not fire the callback, nor will the callback fire on a playing track that is being destroyed.
It is legal to adjust the track, including changing its input and restarting it. If this is done because it ran out of data in the middle of mixing, the mixer will start mixing the new track state in its current run without any gap in the audio.
- Parameters
-
cb the function to call when the track stops. May be nullptr.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- TrackStoppedCallback
◆ SetTagGain() [1/2]
|
inline |
Each track has its own gain, to adjust its overall volume. Each sample from this track is modulated by this gain value. A gain of zero will generate silence, 1.0f will not change the mixed volume, and larger than 1.0f will increase the volume. Negative values are illegal. There is no maximum gain specified, but this can quickly get extremely loud, so please be careful with this setting.
A track's gain defaults to 1.0f.
This will change the gain control on tracks on the specified mixer that have the specified tag.
From the point of view of the mixing process, all tracks that successfully change gain values will do so at the exact same moment.
This value can be changed at any time to adjust the future mix.
- Parameters
-
mixer the mixer on which to look for tagged tracks. tag the tag to use when searching for tracks. gain the new gain value.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ SetTagGain() [2/2]
|
inline |
Each track has its own gain, to adjust its overall volume. Each sample from this track is modulated by this gain value. A gain of zero will generate silence, 1.0f will not change the mixed volume, and larger than 1.0f will increase the volume. Negative values are illegal. There is no maximum gain specified, but this can quickly get extremely loud, so please be careful with this setting.
A track's gain defaults to 1.0f.
This will change the gain control on tracks on the specified mixer that have the specified tag.
From the point of view of the mixing process, all tracks that successfully change gain values will do so at the exact same moment.
This value can be changed at any time to adjust the future mix.
- Parameters
-
tag the tag to use when searching for tracks. gain the new gain value.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ SetTrack3DPosition()
(Please note that SDL_mixer is not intended to be a extremely powerful 3D API. It lacks 3D features that other APIs like OpenAL offer: there's no doppler effect, distance models, rolloff, etc. This is meant to be Good Enough for games that can use some positional sounds and can even take advantage of surround-sound configurations.)
If position is not nullptr, this track will be switched into 3D positional mode. If position is nullptr, this will disable positional mixing (both the full 3D spatialization of this function and forced-stereo mode of Track.SetStereo()).
In 3D positional mode, SDL_mixer will mix this track as if it were positioned in 3D space, including distance attenuation (quieter as it gets further from the listener) and spatialization (positioned on the correct speakers to suggest direction, either with stereo outputs or full surround sound).
For a mono speaker output, spatialization is effectively disabled but distance attenuation will still work, which is all you can really do with a single speaker.
The coordinate system operates like OpenGL or OpenAL: a "right-handed" coordinate system. See Point3D for the details.
The listener is always at coordinate (0,0,0) and can't be changed.
The track's input will be converted to mono (1 channel) so it can be rendered across the correct speakers.
- Parameters
-
track the track for which to set 3D position. position the new 3D position for the track. May be nullptr.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Get3DPosition
- Track.SetStereo
◆ SetTrackAudio()
A Audio is audio data stored in RAM (possibly still in a compressed form). One Audio can be assigned to multiple tracks at once.
Once a track has a valid input, it can start mixing sound by calling Track.Play(), or possibly Mixer.PlayTag().
Calling this function with a nullptr audio input is legal, and removes any input from the track. If the track was currently playing, the next time the mixer runs, it'll notice this and mark the track as stopped, calling any assigned TrackStoppedCallback.
It is legal to change the input of a track while it's playing, however some states, like loop points, may cease to make sense with the new audio. In such a case, one can call Track.Play again to adjust parameters.
The track will hold a reference to the provided Audio, so it is safe to call Audio.Destroy() on it while the track is still using it. The track will drop its reference (and possibly free the resources) once it is no longer using the Audio.
- Parameters
-
track the track on which to set a new audio input. audio the new audio input to set. May be nullptr.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ SetTrackAudioStream()
|
inline |
Using an audio stream allows the application to generate any type of audio, in any format, possibly procedurally or on-demand, and mix in with all other tracks.
When a track uses an audio stream, it will call AudioStream.GetData as it needs more audio to mix. The app can either buffer data to the stream ahead of time, or set a callback on the stream to provide data as needed. Please refer to SDL's documentation for details.
A given audio stream may only be assigned to a single track at a time; duplicate assignments won't return an error, but assigning a stream to multiple tracks will cause each track to read from the stream arbitrarily, causing confusion and incorrect mixing.
Once a track has a valid input, it can start mixing sound by calling Track.Play(), or possibly Mixer.PlayTag().
Calling this function with a nullptr audio stream is legal, and removes any input from the track. If the track was currently playing, the next time the mixer runs, it'll notice this and mark the track as stopped, calling any assigned TrackStoppedCallback.
It is legal to change the input of a track while it's playing, however some states, like loop points, may cease to make sense with the new audio. In such a case, one can call Track.Play again to adjust parameters.
The provided audio stream must remain valid until the track no longer needs it (either by changing the track's input or destroying the track).
- Parameters
-
track the track on which to set a new audio input. stream the audio stream to use as the track's input.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ SetTrackCookedCallback() [1/2]
|
inline |
As a track needs to mix more data, it pulls from its input (a Audio, an AudioStream, etc). This input might be a compressed file format, like MP3, so a little more data is uncompressed from it.
Once the track has PCM data to start operating on, and its raw callback has completed, it will begin to transform the audio: gain, fading, frequency ratio, 3D positioning, etc.
A callback can be fired after all these transformations, but before the transformed data is mixed into other tracks. This lets an app view the data at the last moment that it is still a part of this track. It can also change the data in any way it pleases during this callback, and the mixer will continue as if this data came directly from the input.
Each track has its own unique cooked callback.
Passing a nullptr callback here is legal; it disables this track's callback.
- Parameters
-
track the track to assign this callback to. cb the function to call when the track mixes. May be nullptr. userdata an opaque pointer provided to the callback for its own personal use.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- TrackMixCallback
- Track.SetRawCallback
◆ SetTrackCookedCallback() [2/2]
|
inline |
As a track needs to mix more data, it pulls from its input (a Audio, an AudioStream, etc). This input might be a compressed file format, like MP3, so a little more data is uncompressed from it.
Once the track has PCM data to start operating on, and its raw callback has completed, it will begin to transform the audio: gain, fading, frequency ratio, 3D positioning, etc.
A callback can be fired after all these transformations, but before the transformed data is mixed into other tracks. This lets an app view the data at the last moment that it is still a part of this track. It can also change the data in any way it pleases during this callback, and the mixer will continue as if this data came directly from the input.
Each track has its own unique cooked callback.
Passing a nullptr callback here is legal; it disables this track's callback.
- Parameters
-
track the track to assign this callback to. cb the function to call when the track mixes. May be nullptr.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- TrackMixCallback
- Track.SetRawCallback
◆ SetTrackFrequencyRatio()
|
inline |
The frequency ratio is used to adjust the rate at which audio data is consumed. Changing this effectively modifies the speed and pitch of the track's audio. A value greater than 1.0f will play the audio faster, and at a higher pitch. A value less than 1.0f will play the audio slower, and at a lower pitch. 1.0f is normal speed.
The default value is 1.0f.
This value can be changed at any time to adjust the future mix.
- Parameters
-
track the track on which to change the frequency ratio. ratio the frequency ratio. Must be between 0.01f and 100.0f.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.GetFrequencyRatio
◆ SetTrackGain()
|
inline |
Each track has its own gain, to adjust its overall volume. Each sample from this track is modulated by this gain value. A gain of zero will generate silence, 1.0f will not change the mixed volume, and larger than 1.0f will increase the volume. Negative values are illegal. There is no maximum gain specified, but this can quickly get extremely loud, so please be careful with this setting.
A track's gain defaults to 1.0f.
This value can be changed at any time to adjust the future mix.
- Parameters
-
track the track to adjust. gain the new gain value.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.GetGain
- Mixer.SetGain
◆ SetTrackGroup()
All tracks in a group are mixed together, and that output is made available to the app before it is mixed into the final output.
Tracks can only be in one group at a time, and the track and group must have been created on the same Mixer.
Setting a track to a nullptr group will remove it from any app-created groups, and reassign it to the mixer's internal default group.
- Parameters
-
track the track to set mixing group assignment. group the new mixing group to assign to. May be nullptr.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ SetTrackIOStream()
|
inline |
This is not the recommended way to set a track's input, but this can be useful for a very specific scenario: a large file, to be played once, that must be read from disk in small chunks as needed. In most cases, however, it is preferable to create a Audio ahead of time and use Track.SetAudio() instead.
The stream supplied here should provide an audio file in a supported format. SDL_mixer will parse it during this call to make sure it's valid, and then will read file data from the stream as it needs to decode more during mixing.
The stream must be able to seek through the complete set of data, or this function will fail.
A given IOStream may only be assigned to a single track at a time; duplicate assignments won't return an error, but assigning a stream to multiple tracks will cause each track to read from the stream arbitrarily, causing confusion, incorrect mixing, or failure to decode.
Once a track has a valid input, it can start mixing sound by calling Track.Play(), or possibly Mixer.PlayTag().
Calling this function with a nullptr stream is legal, and removes any input from the track. If the track was currently playing, the next time the mixer runs, it'll notice this and mark the track as stopped, calling any assigned TrackStoppedCallback.
It is legal to change the input of a track while it's playing, however some states, like loop points, may cease to make sense with the new audio. In such a case, one can call Track.Play again to adjust parameters.
The provided stream must remain valid until the track no longer needs it (either by changing the track's input or destroying the track).
- Parameters
-
track the track on which to set a new audio input. io the new i/o stream to use as the track's input. closeio if true, close the stream when done with it.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.SetRawIOStream
◆ SetTrackLoops()
|
inline |
This replaces any previously-set remaining loops. A value of 1 will loop to the start of playback one time. Zero will not loop at all. A value of -1 requests infinite loops. If the input is not seekable and num_loops isn't zero, this function will report success but the track will stop at the point it should loop.
The new loop count replaces any previous state, even if the track has already looped.
This has no effect on a track that is stopped, or rather, starting a stopped track later will set a new loop count, replacing this value. Stopped tracks can specify a loop count while starting via prop::Play.LOOPS_NUMBER. This function is intended to alter that count in the middle of playback.
- Parameters
-
track the track to configure. num_loops new number of times to loop. Zero to disable looping, -1 to loop infinitely.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.GetLoops
◆ SetTrackOutputChannelMap()
|
inline |
Channel maps are optional; most things do not need them, instead passing data in the order that SDL expects.
The output channel map reorders track data after transformations and before it is mixed into a mixer group. This can be useful for reversing stereo channels, for example.
Each item in the array represents an input channel, and its value is the channel that it should be remapped to. To reverse a stereo signal's left and right values, you'd have an array of { 1, 0 }. It is legal to remap multiple channels to the same thing, so { 1, 1 } would duplicate the right channel to both channels of a stereo signal. An element in the channel map set to -1 instead of a valid channel will mute that channel, setting it to a silence value.
You cannot change the number of channels through a channel map, just reorder/mute them.
Tracks default to no remapping applied. Passing a nullptr channel map is legal, and turns off remapping.
SDL_mixer will copy the channel map; the caller does not have to save this array after this call.
- Parameters
-
track the track to change. chmap the new channel map, nullptr to reset to default.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ SetTrackPlaybackPosition()
(Not to be confused with Track.Set3DPosition(), which is positioning of the track in 3D space, not the playback position of its audio data.)
On a playing track, the next time the mixer runs, it will start mixing from the new position.
Position is defined in sample frames of decoded audio, not units of time, so that sample-perfect mixing can be achieved. To instead operate in units of time, use Track.MSToFrames() to get the approximate sample frames for a given tick.
This function requires an input that can seek (so it can not be used if the input was set with Track.SetAudioStream()), and a audio file format that allows seeking. SDL_mixer's decoders for some file formats do not offer seeking, or can only seek to times, not exact sample frames, in which case the final position may be off by some amount of sample frames. Please check your audio data and file bug reports if appropriate.
It's legal to call this function on a track that is stopped, but a future call to Track.Play() will reset the start position anyhow. Paused tracks will resume at the new input position.
- Parameters
-
track the track to change. frames the sample frame position to seek to.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.GetPlaybackPosition
◆ SetTrackRawCallback() [1/2]
|
inline |
As a track needs to mix more data, it pulls from its input (a Audio, an AudioStream, etc). This input might be a compressed file format, like MP3, so a little more data is uncompressed from it.
Once the track has PCM data to start operating on, it can fire a callback before any changes to the raw PCM input have happened. This lets an app view the data before it has gone through transformations such as gain, 3D positioning, fading, etc. It can also change the data in any way it pleases during this callback, and the mixer will continue as if this data came directly from the input.
Each track has its own unique raw callback.
Passing a nullptr callback here is legal; it disables this track's callback.
- Parameters
-
track the track to assign this callback to. cb the function to call when the track mixes. May be nullptr. userdata an opaque pointer provided to the callback for its own personal use.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ SetTrackRawCallback() [2/2]
|
inline |
As a track needs to mix more data, it pulls from its input (a Audio, an AudioStream, etc). This input might be a compressed file format, like MP3, so a little more data is uncompressed from it.
Once the track has PCM data to start operating on, it can fire a callback before any changes to the raw PCM input have happened. This lets an app view the data before it has gone through transformations such as gain, 3D positioning, fading, etc. It can also change the data in any way it pleases during this callback, and the mixer will continue as if this data came directly from the input.
Each track has its own unique raw callback.
Passing a nullptr callback here is legal; it disables this track's callback.
- Parameters
-
track the track to assign this callback to. cb the function to call when the track mixes. May be nullptr.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ SetTrackRawIOStream()
|
inline |
This is not the recommended way to set a track's input, but this can be useful for a very specific scenario: a large file, to be played once, that must be read from disk in small chunks as needed. In most cases, however, it is preferable to create a Audio ahead of time and use Track.SetAudio() instead.
Also, an Track.SetAudioStream() can also provide raw PCM audio to a track, via an AudioStream, which might be preferable unless the data is already coming directly from an IOStream.
The stream supplied here should provide an audio in raw PCM format.
A given IOStream may only be assigned to a single track at a time; duplicate assignments won't return an error, but assigning a stream to multiple tracks will cause each track to read from the stream arbitrarily, causing confusion and incorrect mixing.
Once a track has a valid input, it can start mixing sound by calling Track.Play(), or possibly Mixer.PlayTag().
Calling this function with a nullptr stream is legal, and removes any input from the track. If the track was currently playing, the next time the mixer runs, it'll notice this and mark the track as stopped, calling any assigned TrackStoppedCallback.
It is legal to change the input of a track while it's playing, however some states, like loop points, may cease to make sense with the new audio. In such a case, one can call Track.Play again to adjust parameters.
The provided stream must remain valid until the track no longer needs it (either by changing the track's input or destroying the track).
- Parameters
-
track the track on which to set a new audio input. io the new i/o stream to use as the track's input. spec the format of the PCM data that the IOStream will provide. closeio if true, close the stream when done with it.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ SetTrackStereo()
|
inline |
This will cause the output of the track to convert to stereo, and then mix it only onto the Front Left and Front Right speakers, regardless of the speaker configuration. The left and right channels are modulated by gains, which can be used to produce panning effects. This function may be called to adjust the gains at any time.
If gains is not nullptr, this track will be switched into forced-stereo mode. If gains is nullptr, this will disable spatialization (both the forced-stereo mode of this function and full 3D spatialization of Track.Set3DPosition()).
Negative gains are clamped to zero; there is no clamp for maximum, so one could set the value > 1.0f to make a channel louder.
The track's 3D position, reported by Track.Get3DPosition(), will be reset to (0, 0, 0).
- Parameters
-
track the track to adjust. gains the per-channel gains, or nullptr to disable spatialization.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Set3DPosition
◆ SetTrackStoppedCallback() [1/2]
|
inline |
When a track completes playback, either because it ran out of data to mix (and all loops were completed as well), or it was explicitly stopped by the app, it will fire the callback specified here.
Each track has its own unique callback.
Passing a nullptr callback here is legal; it disables this track's callback.
Pausing a track will not fire the callback, nor will the callback fire on a playing track that is being destroyed.
It is legal to adjust the track, including changing its input and restarting it. If this is done because it ran out of data in the middle of mixing, the mixer will start mixing the new track state in its current run without any gap in the audio.
- Parameters
-
track the track to assign this callback to. cb the function to call when the track stops. May be nullptr. userdata an opaque pointer provided to the callback for its own personal use.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- TrackStoppedCallback
◆ SetTrackStoppedCallback() [2/2]
|
inline |
When a track completes playback, either because it ran out of data to mix (and all loops were completed as well), or it was explicitly stopped by the app, it will fire the callback specified here.
Each track has its own unique callback.
Passing a nullptr callback here is legal; it disables this track's callback.
Pausing a track will not fire the callback, nor will the callback fire on a playing track that is being destroyed.
It is legal to adjust the track, including changing its input and restarting it. If this is done because it ran out of data in the middle of mixing, the mixer will start mixing the new track state in its current run without any gap in the audio.
- Parameters
-
track the track to assign this callback to. cb the function to call when the track stops. May be nullptr.
- Exceptions
-
Error on failure.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- TrackStoppedCallback
◆ Stop()
|
inline |
If fade_out_frames is > 0, the track does not stop mixing immediately, but rather fades to silence over that many sample frames before stopping. Sample frames are specific to the input assigned to the track, to allow for sample-perfect mixing. Track.MSToFrames() can be used to convert milliseconds to an appropriate value here.
If the track ends normally while the fade-out is still in progress, the audio stops there; the fade is not adjusted to be shorter if it will last longer than the audio remaining.
Once a track has completed any fadeout and come to a stop, it will call its TrackStoppedCallback, if any. It is legal to assign the track a new input and/or restart it during this callback.
It is legal to halt a track that's already stopped. It does nothing, and returns true.
- Parameters
-
fade_out_frames the number of sample frames to spend fading out to silence before halting. 0 to stop immediately.
- Returns
- true if the track has stopped, false on error; call GetError() for details.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Play
◆ StopAllTracks() [1/2]
If fade_out_ms is > 0, the tracks do not stop mixing immediately, but rather fades to silence over that many milliseconds before stopping. Note that this is different than Track.Stop(), which wants sample frames; this function takes milliseconds because different tracks might have different sample rates.
If a track ends normally while the fade-out is still in progress, the audio stops there; the fade is not adjusted to be shorter if it will last longer than the audio remaining.
Once a track has completed any fadeout and come to a stop, it will call its TrackStoppedCallback, if any. It is legal to assign the track a new input and/or restart it during this callback. This function does not prevent new play requests from being made.
- Parameters
-
mixer the mixer on which to stop all tracks. fade_out_ms the number of milliseconds to spend fading out to silence before halting. 0 to stop immediately.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Stop
◆ StopAllTracks() [2/2]
|
inline |
If fade_out_ms is > 0, the tracks do not stop mixing immediately, but rather fades to silence over that many milliseconds before stopping. Note that this is different than Track.Stop(), which wants sample frames; this function takes milliseconds because different tracks might have different sample rates.
If a track ends normally while the fade-out is still in progress, the audio stops there; the fade is not adjusted to be shorter if it will last longer than the audio remaining.
Once a track has completed any fadeout and come to a stop, it will call its TrackStoppedCallback, if any. It is legal to assign the track a new input and/or restart it during this callback. This function does not prevent new play requests from being made.
- Parameters
-
fade_out_ms the number of milliseconds to spend fading out to silence before halting. 0 to stop immediately.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Stop
◆ StopTag() [1/2]
|
inline |
If fade_out_ms is > 0, the tracks do not stop mixing immediately, but rather fades to silence over that many milliseconds before stopping. Note that this is different than Track.Stop(), which wants sample frames; this function takes milliseconds because different tracks might have different sample rates.
If a track ends normally while the fade-out is still in progress, the audio stops there; the fade is not adjusted to be shorter if it will last longer than the audio remaining.
Once a track has completed any fadeout and come to a stop, it will call its TrackStoppedCallback, if any. It is legal to assign the track a new input and/or restart it during this callback. This function does not prevent new play requests from being made.
- Parameters
-
mixer the mixer on which to stop tracks. tag the tag to use when searching for tracks. fade_out_ms the number of milliseconds to spend fading out to silence before halting. 0 to stop immediately.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Stop
- Track.Tag
◆ StopTag() [2/2]
|
inline |
If fade_out_ms is > 0, the tracks do not stop mixing immediately, but rather fades to silence over that many milliseconds before stopping. Note that this is different than Track.Stop(), which wants sample frames; this function takes milliseconds because different tracks might have different sample rates.
If a track ends normally while the fade-out is still in progress, the audio stops there; the fade is not adjusted to be shorter if it will last longer than the audio remaining.
Once a track has completed any fadeout and come to a stop, it will call its TrackStoppedCallback, if any. It is legal to assign the track a new input and/or restart it during this callback. This function does not prevent new play requests from being made.
- Parameters
-
tag the tag to use when searching for tracks. fade_out_ms the number of milliseconds to spend fading out to silence before halting. 0 to stop immediately.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Stop
- Track.Tag
◆ StopTrack()
If fade_out_frames is > 0, the track does not stop mixing immediately, but rather fades to silence over that many sample frames before stopping. Sample frames are specific to the input assigned to the track, to allow for sample-perfect mixing. Track.MSToFrames() can be used to convert milliseconds to an appropriate value here.
If the track ends normally while the fade-out is still in progress, the audio stops there; the fade is not adjusted to be shorter if it will last longer than the audio remaining.
Once a track has completed any fadeout and come to a stop, it will call its TrackStoppedCallback, if any. It is legal to assign the track a new input and/or restart it during this callback.
It is legal to halt a track that's already stopped. It does nothing, and returns true.
- Parameters
-
track the track to halt. fade_out_frames the number of sample frames to spend fading out to silence before halting. 0 to stop immediately.
- Returns
- true if the track has stopped, false on error; call GetError() for details.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Play
◆ Tag()
|
inline |
A tag can be any valid C string in UTF-8 encoding. It can be useful to group tracks in various ways. For example, everything in-game might be marked as "game", so when the user brings up the settings menu, the app can pause all tracks involved in gameplay at once, but keep background music and menu sound effects running.
A track can have as many tags as desired, until the machine runs out of memory.
It's legal to add the same tag to a track more than once; the extra attempts will report success but not change anything.
Tags can later be removed with Track.Untag().
- Parameters
-
tag the tag to add.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Untag
◆ TagTrack()
|
inline |
A tag can be any valid C string in UTF-8 encoding. It can be useful to group tracks in various ways. For example, everything in-game might be marked as "game", so when the user brings up the settings menu, the app can pause all tracks involved in gameplay at once, but keep background music and menu sound effects running.
A track can have as many tags as desired, until the machine runs out of memory.
It's legal to add the same tag to a track more than once; the extra attempts will report success but not change anything.
Tags can later be removed with Track.Untag().
- Parameters
-
track the track to add a tag to. tag the tag to add.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Untag
◆ Track()
|
inline |
A track provides a single source of audio. All currently-playing tracks will be processed and mixed together to form the final output from the mixer.
There are no limits to the number of tracks one may create, beyond running out of memory, but in normal practice there are a small number of tracks that are reused between all loaded audio as appropriate.
Tracks are unique to a specific Mixer and can't be transferred between them.
- Parameters
-
mixer the mixer on which to create this track.
- Postcondition
- a new Track on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Destroy
◆ TrackFramesToMS()
|
inline |
This calculates time based on the track's current input format, which can change when its input does, and also if that input changes formats mid-stream (for example, if decoding a file that is two MP3s concatenated together).
Sample frames are more precise than milliseconds, so out of necessity, this function will approximate by rounding down to the closest full millisecond.
On various errors (MIX.Init() was not called, the track is nullptr), this returns -1. If the track has no input, this returns -1. If frames is < 0, this returns -1.
- Parameters
-
track the track to query. frames the track-specific sample frames to convert to milliseconds.
- Returns
- Converted number of milliseconds, or -1 for errors/no input; call GetError() for details.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.MSToFrames
◆ TrackMSToFrames()
|
inline |
This calculates time based on the track's current input format, which can change when its input does, and also if that input changes formats mid-stream (for example, if decoding a file that is two MP3s concatenated together).
On various errors (MIX.Init() was not called, the track is nullptr), this returns -1. If the track has no input, this returns -1. If ms is < 0, this returns -1.
- Parameters
-
track the track to query. ms the milliseconds to convert to track-specific sample frames.
- Returns
- Converted number of sample frames, or -1 for errors/no input; call GetError() for details.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.FramesToMS
◆ TrackPaused()
|
inline |
If this returns true, the track is not currently contributing to the mixer's output but will when resumed (it's "paused"). It is not playing nor stopped.
On various errors (MIX.Init() was not called, the track is nullptr), this returns false, but there is no mechanism to distinguish errors from non-playing tracks.
- Parameters
-
track the track to query.
- Returns
- true if paused, false otherwise.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ TrackPlaying()
|
inline |
If this returns true, the track is currently contributing to the mixer's output (it's "playing"). It is not stopped nor paused.
On various errors (MIX.Init() was not called, the track is nullptr), this returns false, but there is no mechanism to distinguish errors from non-playing tracks.
- Parameters
-
track the track to query.
- Returns
- true if playing, false otherwise.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
◆ Unlock()
|
inline |
While locked, the mixer will not be able to mix more audio or change its internal state another thread. Those other threads will block until the mixer is unlocked again.
Under the hood, this function calls Mutex.Lock(), so all the same rules apply: the lock can be recursive, it must be unlocked the same number of times from the same thread that locked it, etc.
Unlocking a nullptr mixer is a safe no-op.
- Thread safety:
- This call must be paired with a previous Mixer.Lock call on the same thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Mixer.Lock
◆ UnlockMixer()
|
inline |
While locked, the mixer will not be able to mix more audio or change its internal state another thread. Those other threads will block until the mixer is unlocked again.
Under the hood, this function calls Mutex.Lock(), so all the same rules apply: the lock can be recursive, it must be unlocked the same number of times from the same thread that locked it, etc.
Unlocking a nullptr mixer is a safe no-op.
- Parameters
-
mixer the mixer to unlock. May be nullptr.
- Thread safety:
- This call must be paired with a previous Mixer.Lock call on the same thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Mixer.Lock
◆ Untag()
|
inline |
A tag can be any valid C string in UTF-8 encoding. It can be useful to group tracks in various ways. For example, everything in-game might be marked as "game", so when the user brings up the settings menu, the app can pause all tracks involved in gameplay at once, but keep background music and menu sound effects running.
It's legal to remove a tag that the track doesn't have; this function doesn't report errors, so this simply does nothing.
Specifying a nullptr tag will remove all tags on a track.
- Parameters
-
tag the tag to remove, or nullptr to remove all current tags.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Tag
◆ UntagTrack()
|
inline |
A tag can be any valid C string in UTF-8 encoding. It can be useful to group tracks in various ways. For example, everything in-game might be marked as "game", so when the user brings up the settings menu, the app can pause all tracks involved in gameplay at once, but keep background music and menu sound effects running.
It's legal to remove a tag that the track doesn't have; this function doesn't report errors, so this simply does nothing.
Specifying a nullptr tag will remove all tags on a track.
- Parameters
-
track the track from which to remove a tag. tag the tag to remove, or nullptr to remove all current tags.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL_mixer 3.0.0.
- See also
- Track.Tag
