API Mixer

SDL_mixer API

Back to API Reference

Audio mixer, track, group, and decoder functions.

• Functions: 91
• Functions with XML docs: 91

Mixer

Mixer.AudioFramesToMS

public static long AudioFramesToMS(IntPtr audio, long frames);

SDL declaration

extern SDL_DECLSPEC Sint64 SDLCALL MIX_AudioFramesToMS(MIX_Audio *audio, Sint64 frames);

Convert sample frames for a MIX_Audio's format to milliseconds. 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

Name	Type	Description
audio	IntPtr	the audio to query.
frames	long	the audio-specific sample frames to convert to milliseconds.

Returns

Converted number of milliseconds, or -1 for errors/no input; call SDL.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.

XML member id: M:SDL3.Mixer.AudioFramesToMS(System.IntPtr,System.Int64)

Mixer.AudioMSToFrames

public static long AudioMSToFrames(IntPtr audio, long ms);

SDL declaration

extern SDL_DECLSPEC Sint64 SDLCALL MIX_AudioMSToFrames(MIX_Audio *audio, Sint64 ms);

Convert milliseconds to sample frames for a MIX_Audio's format. 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

Name	Type	Description
audio	IntPtr	the audio to query.
ms	long	the milliseconds to convert to audio-specific sample frames.

Returns

Converted number of sample frames, or -1 for errors/no input; call SDL.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.

XML member id: M:SDL3.Mixer.AudioMSToFrames(System.IntPtr,System.Int64)

Mixer.CreateAudioDecoder

public static IntPtr CreateAudioDecoder(string path, uint props);

SDL declaration

extern SDL_DECLSPEC MIX_AudioDecoder * SDLCALL MIX_CreateAudioDecoder(const char *path, SDL_PropertiesID props);

Create a MIX_AudioDecoder from a path on the filesystem. 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 zero to specify no extra properties.

SDL_PropertiesID are discussed in SDL's documentation .

When done with the audio decoder, it can be destroyed with Mixer.DestroyAudioDecoder.

This function requires SDL_mixer to have been initialized with a successful call to Mixer.Init, but does not need an actual MIX_Mixer to have been created.

Parameters

Name	Type	Description
path	string	the path on the filesystem from which to load data.
props	uint	decoder-specific properties. May be zero.

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.

XML member id: M:SDL3.Mixer.CreateAudioDecoder(System.String,System.UInt32)

Mixer.CreateAudioDecoderIO

public static IntPtr CreateAudioDecoderIO(IntPtr io, bool closeio, uint props);

SDL declaration

extern SDL_DECLSPEC MIX_AudioDecoder * SDLCALL MIX_CreateAudioDecoder_IO(SDL_IOStream *io, bool closeio, SDL_PropertiesID props);

Create a MIX_AudioDecoder from an SDL_IOStream. 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 zero 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 Mixer.DestroyAudioDecoder.

This function requires SDL_mixer to have been initialized with a successful call to Mixer.Init, but does not need an actual MIX_Mixer to have been created.

Parameters

Name	Type	Description
io	IntPtr	the i/o stream from which to load data.
closeio	bool	if true, close the i/o stream when done with it.
props	uint	decoder-specific properties. May be zero.

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.

XML member id: M:SDL3.Mixer.CreateAudioDecoderIO(System.IntPtr,System.Boolean,System.UInt32)

Mixer.CreateGroup

public static IntPtr CreateGroup(IntPtr mixer);

SDL declaration

extern SDL_DECLSPEC MIX_Group * SDLCALL MIX_CreateGroup(MIX_Mixer *mixer);

Create a mixing group.

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 Mixer.SetTrackGroup. Use Mixer.SetGroupPostMixCallback to access the group's mixed data.

A mixing group can be destroyed with Mixer.DestroyGroup when no longer needed. Destroying the mixer will also destroy all its still-existing mixing groups.

Parameters

Name	Type	Description
mixer	IntPtr	the mixer on which to create a mixing group.

Returns

a newly-created mixing group, or null on error; call SDL.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.

XML member id: M:SDL3.Mixer.CreateGroup(System.IntPtr)

Mixer.CreateMixer

public static IntPtr CreateMixer(IntPtr spec);

SDL declaration

extern SDL_DECLSPEC MIX_Mixer * SDLCALL MIX_CreateMixer(const SDL_AudioSpec *spec);

Create a mixer that generates audio to a memory buffer. Usually you want Mixer.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 null.

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.DestroyMixer.

Parameters

Name	Type	Description
spec	IntPtr	the audio format that mixer will generate.

Returns

a mixer that can be used to generate audio, or null on failure; call SDL.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.

XML member id: M:SDL3.Mixer.CreateMixer(System.IntPtr)

Mixer.CreateMixerDevice

public static IntPtr CreateMixerDevice(uint devid, IntPtr spec);

SDL declaration

extern SDL_DECLSPEC MIX_Mixer * SDLCALL MIX_CreateMixerDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec);

Create a mixer that plays sound directly to an audio device. This is usually the function you want, vs Mixer.CreateMixer.

You can choose a specific device ID to open, following SDL's usual rules, but often the correct choice is to specify SDL.AudioDeviceDefaultPlayback 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 SDL.Init(InitFlags.Audio) internally; it's safe to call Mixer.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 null 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.GetMixerFormat.

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.DestroyMixer.

Parameters

Name	Type	Description
devid	uint	the device to open for playback, or SDL.AudioDeviceDefaultPlayback for the default.
spec	IntPtr	spec the audio format to request from the device. May be null.

Returns

a mixer that can be used to play audio, or null on failure; call SDL.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.

XML member id: M:SDL3.Mixer.CreateMixerDevice(System.UInt32,System.IntPtr)

Mixer.CreateSineWaveAudio

public static IntPtr CreateSineWaveAudio(IntPtr mixer, int hz, float amplitude);

SDL declaration

extern SDL_DECLSPEC MIX_Audio * SDLCALL MIX_CreateSineWaveAudio(MIX_Mixer *mixer, int hz, float amplitude);

Create a MIX_Audio that generates a sinewave. This is useful just to have something to play, perhaps for testing or debugging purposes.

The resulting MIX_Audio will generate infinite audio when assigned to a track.

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 MIX_Track, the sinewave will play forever).

MIX_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 null mixer may be specified.

Parameters

Name	Type	Description
mixer	IntPtr	a mixer this audio is intended to be used with. May be null.
hz	int	the sinewave's frequency in Hz.
amplitude	float	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, or null on failure; call SDL.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.

XML member id: M:SDL3.Mixer.CreateSineWaveAudio(System.IntPtr,System.Int32,System.Single)

Mixer.CreateTrack

public static IntPtr CreateTrack(IntPtr mixer);

SDL declaration

extern SDL_DECLSPEC MIX_Track * SDLCALL MIX_CreateTrack(MIX_Mixer *mixer);

Create a new track on a mixer. 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 MIX_Mixer and can't be transferred between them.

Parameters

Name	Type	Description
mixer	IntPtr	the mixer on which to create this track.

Returns

a new MIX_Track on success, null on error; call SDL.GetError for more informations.

Thread safety

It is safe to call this function from any thread.

Since: This function is available since SDL_mixer 3.0.0.

XML member id: M:SDL3.Mixer.CreateTrack(System.IntPtr)

Mixer.DecodeAudio

public static int DecodeAudio(IntPtr audiodecoder, IntPtr buffer, int buflen, IntPtr spec);

SDL declaration

extern SDL_DECLSPEC int SDLCALL MIX_DecodeAudio(MIX_AudioDecoder *audiodecoder, void *buffer, int buflen, const SDL_AudioSpec *spec);

Decode more audio from a MIX_AudioDecoder. 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

Name	Type	Description
audiodecoder	IntPtr	the decoder from which to retrieve more data.
buffer	IntPtr	the memory buffer to store decoded audio.
buflen	int	the maximum number of bytes to store to buffer.
spec	IntPtr	the format that audio data will be stored to buffer.

Returns

number of bytes decoded, or -1 on error; call SDL.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

XML member id: M:SDL3.Mixer.DecodeAudio(System.IntPtr,System.IntPtr,System.Int32,System.IntPtr)

Mixer.DestroyAudio

public static void DestroyAudio(IntPtr audio);

SDL declaration

extern SDL_DECLSPEC void SDLCALL MIX_DestroyAudio(MIX_Audio *audio);

Destroy the specified audio. MIX_Audio is reference-counted internally, so this function only unrefs it. If doing so causes the reference count to drop to zero, the MIX_Audio will be deallocated. This allows the system to safely operate if the audio is still assigned to a MIX_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 null MIX_Audio is a legal no-op.

Parameters

Name	Type	Description
audio	IntPtr	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.

XML member id: M:SDL3.Mixer.DestroyAudio(System.IntPtr)

Mixer.DestroyAudioDecoder

public static void DestroyAudioDecoder(IntPtr audiodecoder);

SDL declaration

extern SDL_DECLSPEC void SDLCALL MIX_DestroyAudioDecoder(MIX_AudioDecoder *audiodecoder);

Destroy the specified audio decoder. Destroying a null MIX_AudioDecoder is a legal no-op.

Parameters

Name	Type	Description
audiodecoder	IntPtr	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.

XML member id: M:SDL3.Mixer.DestroyAudioDecoder(System.IntPtr)

Mixer.DestroyGroup

public static void DestroyGroup(IntPtr group);

SDL declaration

extern SDL_DECLSPEC void SDLCALL MIX_DestroyGroup(MIX_Group *group);

Destroy a mixing group. Any tracks currently assigned to this group will be reassigned to the mixer's internal default group.

Parameters

Name	Type	Description
group	IntPtr	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.

XML member id: M:SDL3.Mixer.DestroyGroup(System.IntPtr)

Mixer.DestroyMixer

public static void DestroyMixer(IntPtr mixer);

SDL declaration

extern SDL_DECLSPEC void SDLCALL MIX_DestroyMixer(MIX_Mixer *mixer);

Free a mixer. If this mixer was created with Mixer.CreateMixerDevice, this function will also close the audio device and call SDL.QuitSubSystem(InitFlags.Audio).

Any MIX_Group or MIX_Track created for this mixer will also be destroyed. Do not access them again or attempt to destroy them after the device is destroyed. MIX_Audio objects will not be destroyed, since they can be shared between mixers (but those will all be destroyed during Mixer.Quit).

Parameters

Name	Type	Description
mixer	IntPtr	the mixer 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.

XML member id: M:SDL3.Mixer.DestroyMixer(System.IntPtr)

Mixer.DestroyTrack

public static void DestroyTrack(IntPtr track);

SDL declaration

extern SDL_DECLSPEC void SDLCALL MIX_DestroyTrack(MIX_Track *track);

Destroy the specified track. If the track is currently playing, it will be stopped immediately, without any fadeout. If there is a callback set through Mixer.SetTrackStoppedCallback, it will not be called.

If the mixer is currently mixing in another thread, this will block until it finishes.

Destroying a null MIX_Track is a legal no-op.

Parameters

Name	Type	Description
track	IntPtr	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.

XML member id: M:SDL3.Mixer.DestroyTrack(System.IntPtr)

Mixer.FramesToMS

public static long FramesToMS(int sampleRate, long frames);

SDL declaration

extern SDL_DECLSPEC Sint64 SDLCALL MIX_FramesToMS(int sample_rate, Sint64 frames);

Convert sample frames, at a specific sample rate, to milliseconds. Sample frames are more precise than milliseconds, so out of necessity, this function will approximate by rounding down to the closest full millisecond.

If sampleRate is <= 0, this returns -1. If frames is < 0, this returns -1.

Parameters

Name	Type	Description
sampleRate	int	the sample rate to use for conversion.
frames	long	the rate-specific sample frames to convert to milliseconds.

Returns

Converted number of milliseconds, or -1 for errors; call SDL.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.

XML member id: M:SDL3.Mixer.FramesToMS(System.Int32,System.Int64)

Mixer.Generate

public static int Generate(IntPtr mixer, IntPtr buffer, int buflen);

SDL declaration

extern SDL_DECLSPEC int SDLCALL MIX_Generate(MIX_Mixer *mixer, void *buffer, int buflen);

Generate mixer output when not driving an audio device.

SDL_mixer allows the creation of MIX_Mixer objects that are not connected to an audio device, by calling Mixer.CreateMixer instead of Mixer.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 Mixer.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

Name	Type	Description
mixer	IntPtr	the mixer for which to generate more audio.
buffer	IntPtr	a pointer to a buffer to store audio in.
buflen	int	the number of bytes to store in buffer.

Returns

the number of bytes of mixed audio, discounting appended silence, on success, or -1 on failure; call SDL.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.

XML member id: M:SDL3.Mixer.Generate(System.IntPtr,System.IntPtr,System.Int32)

Mixer.GetAudioDecoder

public static string GetAudioDecoder(int index);

SDL declaration

extern SDL_DECLSPEC const char * SDLCALL MIX_GetAudioDecoder(int index);

Report the name of a specific audio decoders.

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 Mixer.Init and does not change until the library is deinitialized. Valid indices are between zero and the return value of Mixer.GetNumAudioDecoders.

The returned pointer is const memory owned by SDL_mixer; do not free it.

Parameters

Name	Type	Description
index	int	the index of the decoder to query.

Returns

a UTF-8 (really, ASCII) string of the decoder's name, or null if index is invalid.

Thread safety

It is safe to call this function from any thread.

Since: This function is available since SDL_mixer 3.0.0.

XML member id: M:SDL3.Mixer.GetAudioDecoder(System.Int32)

Mixer.GetAudioDecoderFormat

public static bool GetAudioDecoderFormat(IntPtr audiodecoder, IntPtr spec);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_GetAudioDecoderFormat(MIX_AudioDecoder *audiodecoder, SDL_AudioSpec *spec);

Query the initial audio format of a MIX_AudioDecoder. 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

Name	Type	Description
audiodecoder	IntPtr	the audio decoder to query.
spec	IntPtr	on success, audio format details will be stored here.

Returns

true on success or false on failure; call SDL.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.

XML member id: M:SDL3.Mixer.GetAudioDecoderFormat(System.IntPtr,System.IntPtr)

Mixer.GetAudioDecoderProperties

public static uint GetAudioDecoderProperties(IntPtr audiodecoder);

SDL declaration

extern SDL_DECLSPEC SDL_PropertiesID SDLCALL MIX_GetAudioDecoderProperties(MIX_AudioDecoder *audiodecoder);

Get the properties associated with a MIX_AudioDecoder.

SDL_mixer offers some properties of its own, but this can also be a convenient place to store app-specific data.

A SDL_PropertiesID is created the first time this function is called for a given MIX_AudioDecoder, if necessary.

The file-specific metadata exposed through this function is identical to those available through Mixer.GetAudioProperties. Please refer to that function's documentation for details.

Parameters

Name	Type	Description
audiodecoder	IntPtr	the audio decoder to query.

Returns

a valid property ID on success or 0 on failure; call SDL.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.

XML member id: M:SDL3.Mixer.GetAudioDecoderProperties(System.IntPtr)

Mixer.GetAudioDuration

public static long GetAudioDuration(IntPtr audio);

SDL declaration

extern SDL_DECLSPEC Sint64 SDLCALL MIX_GetAudioDuration(MIX_Audio *audio);

Get the length of a MIX_Audio's playback in sample frames. This information is also available via the Mixer.Props.MetadataDurationFramesNumber 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 Mixer.AudioFramesToMS.

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 Mixer.DurationUnknown or Mixer.DurationInfinite.

Parameters

Name	Type	Description
audio	IntPtr	the audio to query.

Returns

the length of the audio in sample frames, or Mixer.DurationUnknown or Mixer.DurationInfinite.

Thread safety

It is safe to call this function from any thread.

Since: This function is available since SDL_mixer 3.0.0.

XML member id: M:SDL3.Mixer.GetAudioDuration(System.IntPtr)

Mixer.GetAudioFormat

public static bool GetAudioFormat(IntPtr audio, IntPtr spec);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_GetAudioFormat(MIX_Audio *audio, SDL_AudioSpec *spec);

Query the initial audio format of a MIX_Audio. 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

Name	Type	Description
audio	IntPtr	the audio to query.
spec	IntPtr	on success, audio format details will be stored here.

Returns

true on success or false on failure; call SDL.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.

XML member id: M:SDL3.Mixer.GetAudioFormat(System.IntPtr,System.IntPtr)

Mixer.GetAudioProperties

public static uint GetAudioProperties(IntPtr audio);

SDL declaration

extern SDL_DECLSPEC SDL_PropertiesID SDLCALL MIX_GetAudioProperties(MIX_Audio *audio);

The following read-only properties are provided by SDL_mixer:

• Mixer.Props.MetadataTitleString: the audio's title ("Smells Like Teen Spirit").
• Mixer.Props.MetadataArtistString: the audio's artist name ("Nirvana").
• Mixer.Props.MetadataAlbumString: the audio's album name ("Nevermind").
• Mixer.Props.MetadataCopyrightString: the audio's copyright info ("Copyright (c) 1991")
• Mixer.Props.MetadataTrackNumber: the audio's track number on the album (1)
• Mixer.Props.MetadataTotalTrackSNumber: the total tracks on the album (13)
• Mixer.Props.MetadataYearNumber: the year the audio was released (1991)
• Mixer.Props.MetadataDurationFramesNumber: 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.
• Mixer.Props.MetadataDurationInfiniteBoolean: if true, audio never runs out of sound to generate. This isn't necessarily always known to SDL_mixer, though. Other properties, documented with Mixer.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

Name	Type	Description
audio	IntPtr	the audio to query.

Returns

a valid property ID on success or 0 on failure; call SDL.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.

XML member id: M:SDL3.Mixer.GetAudioProperties(System.IntPtr)

Mixer.GetGroupMixer

public static IntPtr GetGroupMixer(IntPtr group);

SDL declaration

extern SDL_DECLSPEC MIX_Mixer * SDLCALL MIX_GetGroupMixer(MIX_Group *group);

Get the MIX_Mixer that owns a MIX_Group. This is the mixer pointer that was passed to Mixer.CreateGroup.

Parameters

Name	Type	Description
group	IntPtr	the group to query.

Returns

the mixer associated with the group, or null on error; call SDL.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.

XML member id: M:SDL3.Mixer.GetGroupMixer(System.IntPtr)

Mixer.GetGroupProperties

public static uint GetGroupProperties(IntPtr group);

SDL declaration

extern SDL_DECLSPEC SDL_PropertiesID SDLCALL MIX_GetGroupProperties(MIX_Group *group);

Get the properties associated with a group. 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 SDL_PropertiesID is created the first time this function is called for a given group.

Parameters

Name	Type	Description
group	IntPtr	the group to query.

Returns

a valid property ID on success or 0 on failure; call SDL.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.

XML member id: M:SDL3.Mixer.GetGroupProperties(System.IntPtr)

Mixer.GetMixerFormat

public static bool GetMixerFormat(IntPtr mixer, IntPtr spec);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_GetMixerFormat(MIX_Mixer *mixer, SDL_AudioSpec *spec);

Get the audio format a mixer is generating. 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 Mixer.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 Mixer.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 SDL.AudioFormat.AudioF32 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

Name	Type	Description
mixer	IntPtr	the mixer to query.
spec	IntPtr	where to store the mixer audio format.

Returns

true on success or false on failure; call SDL.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.

XML member id: M:SDL3.Mixer.GetMixerFormat(System.IntPtr,System.IntPtr)

Mixer.GetMixerFrequencyRatio

public static float GetMixerFrequencyRatio(IntPtr mixer);

SDL declaration

extern SDL_DECLSPEC float SDLCALL MIX_GetMixerFrequencyRatio(MIX_Mixer *mixer);

Get a mixer's master frequency ratio. This returns the last value set through Mixer.SetMixerFrequencyRatio, or 1.0f if no value has ever been explicitly set.

Parameters

Name	Type	Description
mixer	IntPtr	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.

XML member id: M:SDL3.Mixer.GetMixerFrequencyRatio(System.IntPtr)

Mixer.GetMixerGain

public static float GetMixerGain(IntPtr mixer);

SDL declaration

extern SDL_DECLSPEC float SDLCALL MIX_GetMixerGain(MIX_Mixer *mixer);

Get a mixer's master gain control. This returns the last value set through Mixer.SetMixerGain, or 1.0f if no value has ever been explicitly set.

Parameters

Name	Type	Description
mixer	IntPtr	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.

XML member id: M:SDL3.Mixer.GetMixerGain(System.IntPtr)

Mixer.GetMixerProperties

public static uint GetMixerProperties(IntPtr mixer);

SDL declaration

extern SDL_DECLSPEC SDL_PropertiesID SDLCALL MIX_GetMixerProperties(MIX_Mixer *mixer);

Get the properties associated with a mixer. The following read-only properties are provided by SDL_mixer:

MIX_PROP_MIXER_DEVICE_NUMBER``Mixer.Props.MixerDeviceNumber: the SDL_AudioDeviceID that this mixer has opened for playback. This will be zero (no device) if the mixer was created with Mixer.CreateMixer instead of Mixer.CreateMixerDevice.

Parameters

Name	Type	Description
mixer	IntPtr	the mixer to query.

Returns

a valid property ID on success or 0 on failure; call SDL.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.

XML member id: M:SDL3.Mixer.GetMixerProperties(System.IntPtr)

Mixer.GetNumAudioDecoders

public static int GetNumAudioDecoders();

SDL declaration

extern SDL_DECLSPEC int SDLCALL MIX_GetNumAudioDecoders(void);

Report the number of audio decoders available for use. 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 Mixer.GetAudioDecoder in a loop.

The number of decoders available is decided during Mixer.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.

XML member id: M:SDL3.Mixer.GetNumAudioDecoders

Mixer.GetTaggedTracks

public static IntPtr[] GetTaggedTracks(IntPtr mixer, string tag, out int count);

Get all tracks with a specific tag.

Tracks are not provided in any guaranteed order.

Parameters

Name	Type	Description
mixer	IntPtr	mixer the mixer to query.
tag	string	tag the tag to search.
count	out int	count a pointer filled in with the number of tracks returned, can be null.

Returns

SDL.GetError for more information. The returned pointer should be freed with SDL.Free when it is no longer needed.

Thread safety

It is safe to call this function from any thread.

Since: This function is available since SDL_mixer 3.0.0.

XML member id: M:SDL3.Mixer.GetTaggedTracks(System.IntPtr,System.String,System.Int32@)

Mixer.GetTrack3DPosition

public static bool GetTrack3DPosition(IntPtr track, IntPtr position);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_GetTrack3DPosition(MIX_Track *track, MIX_Point3D *position);

Get a track's current position in 3D space. If 3D positioning isn't enabled for this track, through a call to Mixer.SetTrack3DPosition, this will return (0,0,0).

Parameters

Name	Type	Description
track	IntPtr	the track to query.
position	IntPtr	on successful return, will contain the track's position.

Returns

true on success or false on failure; call SDL.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.

XML member id: M:SDL3.Mixer.GetTrack3DPosition(System.IntPtr,System.IntPtr)

Mixer.GetTrackAudio

public static IntPtr GetTrackAudio(IntPtr track);

SDL declaration

extern SDL_DECLSPEC MIX_Audio * SDLCALL MIX_GetTrackAudio(MIX_Track *track);

Query the MIX_Audio assigned to a track. This returns the MIX_Audio object currently assigned to null through a call to Mixer.SetTrackAudio. If there is none assigned, or the track has an input that isn't a MIX_Audio (such as an SDL_AudioStream or SDL_IOStream), this will return null.

On various errors (Mixer.Init was not called, the track is null), this returns null, but there is no mechanism to distinguish errors from tracks without a valid input.

Parameters

Name	Type	Description
track	IntPtr	the track to query.

Returns

a MIX_Audio if available, Mixer.Init 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.

XML member id: M:SDL3.Mixer.GetTrackAudio(System.IntPtr)

Mixer.GetTrackAudioStream

public static IntPtr GetTrackAudioStream(IntPtr track);

SDL declaration

extern SDL_DECLSPEC SDL_AudioStream * SDLCALL MIX_GetTrackAudioStream(MIX_Track *track);

Query the SDL_AudioStream assigned to a track. This returns the SDL_AudioStream object currently assigned to track through a call to Mixer.SetTrackAudioStream. If there is none assigned, or the track has an input that isn't an SDL_AudioStream (such as a MIX_Audio or SDL_IOStream), this will return null.

On various errors (Mixer.Init was not called, the track is null), this returns null, but there is no mechanism to distinguish errors from tracks without a valid input.

Parameters

Name	Type	Description
track	IntPtr	the track to query.

Returns

an SDL_AudioStream if available, Mixer.Init 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.

XML member id: M:SDL3.Mixer.GetTrackAudioStream(System.IntPtr)

Mixer.GetTrackFadeFrames

public static long GetTrackFadeFrames(IntPtr track);

SDL declaration

extern SDL_DECLSPEC Sint64 SDLCALL MIX_GetTrackFadeFrames(MIX_Track *track);

Query whether a given track is fading. 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 (Mixer.Init was not called, the track is null), this returns 0, but there is no mechanism to distinguish errors from tracks that aren't fading.

Parameters

Name	Type	Description
track	IntPtr	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.

XML member id: M:SDL3.Mixer.GetTrackFadeFrames(System.IntPtr)

Mixer.GetTrackFrequencyRatio

public static float GetTrackFrequencyRatio(IntPtr track);

SDL declaration

extern SDL_DECLSPEC float SDLCALL MIX_GetTrackFrequencyRatio(MIX_Track *track);

Query the frequency ratio of a track. 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 (Mixer.Init was not called, the track is null), this returns 0.0f. Since this is not a valid value to set, this can be seen as an error state.

Parameters

Name	Type	Description
track	IntPtr	the track on which to query the frequency ratio.

Returns

the current frequency ratio, or 0.0f on failure; call SDL.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.

XML member id: M:SDL3.Mixer.GetTrackFrequencyRatio(System.IntPtr)

Mixer.GetTrackGain

public static float GetTrackGain(IntPtr track);

SDL declaration

extern SDL_DECLSPEC float SDLCALL MIX_GetTrackGain(MIX_Track *track);

Get a track's gain control. This returns the last value set through Mixer.SetTrackGain, or 1.0f if no value has ever been explicitly set.

Parameters

Name	Type	Description
track	IntPtr	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.

XML member id: M:SDL3.Mixer.GetTrackGain(System.IntPtr)

Mixer.GetTrackLoops

public static int GetTrackLoops(IntPtr track);

SDL declaration

extern SDL_DECLSPEC int SDLCALL MIX_GetTrackLoops(MIX_Track *track);

Query how many loops remain for a given track. 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.

On various errors (Mixer.Init was not called, the track is null), this returns false, but there is no mechanism to distinguish errors from non-looping tracks.

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 Mixer.Init was not called, the track is null), this returns zero, but there is no mechanism to distinguish errors from non-looping tracks.

Parameters

Name	Type	Description
track	IntPtr	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.

XML member id: M:SDL3.Mixer.GetTrackLoops(System.IntPtr)

Mixer.GetTrackMixer

public static IntPtr GetTrackMixer(IntPtr track);

SDL declaration

extern SDL_DECLSPEC MIX_Mixer * SDLCALL MIX_GetTrackMixer(MIX_Track *track);

Get the MIX_Mixer that owns a MIX_Track. This is the mixer pointer that was passed to Mixer.CreateTrack.

Parameters

Name	Type	Description
track	IntPtr	the track to query.

Returns

the mixer associated with the track, or null on error; call SDL.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.

XML member id: M:SDL3.Mixer.GetTrackMixer(System.IntPtr)

Mixer.GetTrackPlaybackPosition

public static long GetTrackPlaybackPosition(IntPtr track);

SDL declaration

extern SDL_DECLSPEC Sint64 SDLCALL MIX_GetTrackPlaybackPosition(MIX_Track *track);

Get the current input position of a playing track. (Not to be confused with Mixer.GetTrack3DPosition, 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 Mixer.TrackFramesToMS 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

Name	Type	Description
track	IntPtr	the track to change.

Returns

the track's current sample frame position, or -1 on error; call SDL.GetError for details.

XML member id: M:SDL3.Mixer.GetTrackPlaybackPosition(System.IntPtr)

Mixer.GetTrackProperties

public static uint GetTrackProperties(IntPtr track);

SDL declaration

extern SDL_DECLSPEC SDL_PropertiesID SDLCALL MIX_GetTrackProperties(MIX_Track *track);

Get the properties associated with a track. 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 SDL_PropertiesID is created the first time this function is called for a given track.

Parameters

Name	Type	Description
track	IntPtr	the track to query.

Returns

a valid property ID on success or 0 on failure; call SDL.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.

XML member id: M:SDL3.Mixer.GetTrackProperties(System.IntPtr)

Mixer.GetTrackRemaining

public static long GetTrackRemaining(IntPtr track);

SDL declaration

extern SDL_DECLSPEC Sint64 SDLCALL MIX_GetTrackRemaining(MIX_Track *track);

Return the number of sample frames remaining to be mixed in a track. 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 Mixer.TrackFramesToMS 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 null, this function returns -1. A stopped track reports 0.

Parameters

Name	Type	Description
track	IntPtr	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.

XML member id: M:SDL3.Mixer.GetTrackRemaining(System.IntPtr)

Mixer.GetTrackTags

public static string[] GetTrackTags(IntPtr track, out int count);

SDL declaration

extern SDL_DECLSPEC char ** SDLCALL MIX_GetTrackTags(MIX_Track *track, int *count);

Get the tags currently associated with a track.

Tags are not provided in any guaranteed order.

Parameters

Name	Type	Description
track	IntPtr	track the track to query.
count	out int	count a pointer filled in with the number of tags returned, can be null.

Returns

an array of the tags, null-terminated, or null on failure; call SDL.GetError for more information. This is a single allocation that should be freed with SDL.Free when it is no longer needed.

Thread safety

It is safe to call this function from any thread.

Since: This function is available since SDL_mixer 3.0.0.

XML member id: M:SDL3.Mixer.GetTrackTags(System.IntPtr,System.Int32@)

Mixer.Init

public static bool Init();

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_Init(void);

Initialize the SDL_mixer library.

This must be successfully called once before (almost) any other SDL_mixer function can be used.

It is safe to call this multiple times; the library will only initialize once, and won't deinitialize until Mixer.Quit has been called a matching number of times. Extra attempts to init report success.

Returns

true on success, false on error; call SDL.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.

XML member id: M:SDL3.Mixer.Init

Mixer.LoadAudio

public static IntPtr LoadAudio(IntPtr mixer, string path, bool predecode);

SDL declaration

extern SDL_DECLSPEC MIX_Audio * SDLCALL MIX_LoadAudio(MIX_Mixer *mixer, const char *path, bool predecode);

Load audio for playback from a file. This is equivalent to calling:

c Mixer.LoadAudioIO(mixer, SDL.IOFromFile(path, "rb"), predecode, true); This function loads data from a path on the filesystem. There is also a version that loads from an SDL_IOStream (Mixer.LoadAudioIO), and one that accepts properties for ultimate control (Mixer.LoadAudioWithProperties).

Parameters

Name	Type	Description
mixer	IntPtr	a mixer this audio is intended to be used with. May be null.
path	string	the path on the filesystem to load data from.
predecode	bool	if true, data will be fully uncompressed before returning.

Returns

an audio object that can be used to make sound on a mixer, or null on failure; call SDL.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.

XML member id: M:SDL3.Mixer.LoadAudio(System.IntPtr,System.String,System.Boolean)

Mixer.LoadAudioIO

public static IntPtr LoadAudioIO(IntPtr mixer, IntPtr io, bool predecode, bool closeio);

SDL declaration

extern SDL_DECLSPEC MIX_Audio * SDLCALL MIX_LoadAudio_IO(MIX_Mixer *mixer, SDL_IOStream *io, bool predecode, bool closeio);

Load audio for playback from an SDL_IOStream. 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 Mixer.SetTrackIOStream 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.)

MIX_Audio objects can be shared between mixers. This function takes a MIX_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 null, SDL_mixer will set reasonable defaults.

Once a MIX_Audio is created, it can be assigned to a MIX_Track with Mixer.SetTrackAudio, or played without any management with Mixer.PlayAudio.

When done with a MIX_Audio, it can be freed with Mixer.DestroyAudio.

This function loads data from an SDL_IOStream. There is also a version that loads from a path on the filesystem (Mixer.LoadAudio), and one that accepts properties for ultimate control (Mixer.LoadAudioWithProperties).

The SDL_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

Name	Type	Description
mixer	IntPtr	a mixer this audio is intended to be used with. May be null.
io	IntPtr	the SDL_IOStream to load data from.
predecode	bool	if true, data will be fully uncompressed before returning.
closeio	bool	true if SDL_mixer should close io before returning (success or failure).

Returns

an audio object that can be used to make sound on a mixer, or null on failure; call SDL.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.

XML member id: M:SDL3.Mixer.LoadAudioIO(System.IntPtr,System.IntPtr,System.Boolean,System.Boolean)

Mixer.LoadAudioNoCopy

public static IntPtr LoadAudioNoCopy(IntPtr mixer, IntPtr data, UIntPtr datalen, bool freeWhenDone);

SDL declaration

extern SDL_DECLSPEC MIX_Audio * SDLCALL MIX_LoadAudioNoCopy(MIX_Mixer *mixer, const void *data, size_t datalen, bool free_when_done);

Load audio for playback from a memory buffer without making a copy. 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 MIX_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.IOFromConstMem and pass that to Mixer.LoadAudioIO.

MIX_Audio objects can be shared between multiple mixers. The mixer parameter just suggests the most likely mixer to use this audio in, in case some optimization might be applied, but this is not required, and a null mixer may be specified.

If freeWhenDone is true, SDL_mixer will call SDL.Free(data) when the returned MIX_Audio is eventually destroyed. This can be useful when the data is not static, but rather loaded elsewhere for this specific MIX_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 SDL_Audiospec.

Once a MIX_Audio is created, it can be assigned to a MIX_Track with Mixer.SetTrackAudio, or played without any management with Mixer.PlayAudio.

When done with a MIX_Audio, it can be freed with Mixer.DestroyAudio.

Parameters

Name	Type	Description
mixer	IntPtr	a mixer this audio is intended to be used with. May be null.
data	IntPtr	the buffer where the audio data lives.
datalen	UIntPtr	the size, in bytes, of the buffer.
freeWhenDone	bool	if true, data will be given to SDL.Free when the MIX_Audio is destroyed.

Returns

an audio object that can be used to make sound on a mixer, or null on failure; call SDL.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.

XML member id: M:SDL3.Mixer.LoadAudioNoCopy(System.IntPtr,System.IntPtr,System.UIntPtr,System.Boolean)

Mixer.LoadAudioWithProperties

public static IntPtr LoadAudioWithProperties(uint props);

SDL declaration

extern SDL_DECLSPEC MIX_Audio * SDLCALL MIX_LoadAudioWithProperties(SDL_PropertiesID props);

Load audio for playback through a collection of properties. Please see Mixer.LoadAudioIO 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.

SDL_PropertiesID are discussed in SDL's documentation .

These are the supported properties:

• Mixer.Props.AudioLoadIOStreamPointer: a pointer to an SDL_IOStream to be used to load audio data. Required. This stream must be able to seek!
• Mixer.Props.AudioLoadCloseIOBoolean: true if SDL_mixer should close the SDL_IOStream before returning (success or failure).
• Mixer.Props.AudioLoadPreDecodeBoolean: 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.
• Mixer.Props.AudioLoadPreferredMixerPointer: a pointer to a MIX_Mixer, in case steps can be made to match its format when decoding. Optional.
• Mixer.Props.AudioLoadSkipMetadataTagsBoolean: 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.
• Mixer.Props.AudioLoadIgnoreLoopsBoolean: true to ignore metadata in the audio data specifying loop points. This will make a file decode from start to finish without looping, even if the file specified it should have. This audio can still be looped at playback time via MIX_Track loop settings, regardless of this setting. Default false.
• Mixer.Props.AudioDecoderString: 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 Mixer.GetAudioDecoder. Specific decoders might accept additional custom properties, such as where to find soundfonts for MIDI playback, etc.

Parameters

Name	Type	Description
props	uint	a set of properties on how to load audio.

Returns

an audio object that can be used to make sound on a mixer, or null on failure; call SDL.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.

XML member id: M:SDL3.Mixer.LoadAudioWithProperties(System.UInt32)

Mixer.LoadRawAudio

public static IntPtr LoadRawAudio(IntPtr mixer, IntPtr data, UIntPtr datalen, in IntPtr spec);

SDL declaration

extern SDL_DECLSPEC MIX_Audio * SDLCALL MIX_LoadRawAudio(MIX_Mixer *mixer, const void *data, size_t datalen, const SDL_AudioSpec *spec);

Load raw PCM data from a memory buffer. There are other options for streaming raw PCM: an SDL_AudioStream can be connected to a track, as can an SDL_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 MIX_Audio, you can use Mixer.LoadRawAudioNoCopy to avoid extra allocations and copies.

MIX_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 null mixer may be specified.

Parameters

Name	Type	Description
mixer	IntPtr	a mixer this audio is intended to be used with. May be null.
data	IntPtr	the raw PCM data to load.
datalen	UIntPtr	the size, in bytes, of the raw PCM data.
spec	in IntPtr	what format the raw data is in.

Returns

an audio object that can be used to make sound on a mixer, or null on failure; call SDL.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.

XML member id: M:SDL3.Mixer.LoadRawAudio(System.IntPtr,System.IntPtr,System.UIntPtr,System.IntPtr@)

Mixer.LoadRawAudioIO

public static IntPtr LoadRawAudioIO(IntPtr mixer, IntPtr io, in IntPtr spec, bool closeio);

SDL declaration

extern SDL_DECLSPEC MIX_Audio * SDLCALL MIX_LoadRawAudio_IO(MIX_Mixer *mixer, SDL_IOStream *io, const SDL_AudioSpec *spec, bool closeio);

Load raw PCM data from an SDL_IOStream. There are other options for streaming raw PCM: an SDL_AudioStream can be connected to a track, as can an SDL_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.

MIX_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 null mixer may be specified.

Parameters

Name	Type	Description
mixer	IntPtr	a mixer this audio is intended to be used with. May be null.
io	IntPtr	the SDL_IOStream to load data from.
spec	in IntPtr	what format the raw data is in.
closeio	bool	true if SDL_mixer should close io before returning (success or failure).

Returns

an audio object that can be used to make sound on a mixer, or null on failure; call SDL.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.

XML member id: M:SDL3.Mixer.LoadRawAudioIO(System.IntPtr,System.IntPtr,System.IntPtr@,System.Boolean)

Mixer.LoadRawAudioNoCopy

public static IntPtr LoadRawAudioNoCopy(IntPtr mixer, IntPtr data, UIntPtr datalen, in IntPtr spec, bool freeWhenDone);

SDL declaration

extern SDL_DECLSPEC MIX_Audio * SDLCALL MIX_LoadRawAudioNoCopy(MIX_Mixer *mixer, const void *data, size_t datalen, const SDL_AudioSpec *spec, bool free_when_done);

Load raw PCM data from a memory buffer without making a copy. This buffer must live for the entire time the returned MIX_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.)

MIX_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 null mixer may be specified.

If freeWhenDone is true, SDL_mixer will call SDL.Free(data) when the returned MIX_Audio is eventually destroyed. This can be useful when the data is not static, but rather composed dynamically for this specific MIX_Audio and simply wants to avoid the extra copy.

Parameters

Name	Type	Description
mixer	IntPtr	a mixer this audio is intended to be used with. May be null.
data	IntPtr	the buffer where the raw PCM data lives.
datalen	UIntPtr	the size, in bytes, of the buffer.
spec	in IntPtr	what format the raw data is in.
freeWhenDone	bool	if true, data will be given to SDL.Free when the MIX_Audio is destroyed.

Returns

an audio object that can be used to make sound on a mixer, or null on failure; call SDL.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.

XML member id: M:SDL3.Mixer.LoadRawAudioNoCopy(System.IntPtr,System.IntPtr,System.UIntPtr,System.IntPtr@,System.Boolean)

Mixer.MSToFrames

public static long MSToFrames(int sampleRate, long ms);

SDL declaration

extern SDL_DECLSPEC Sint64 SDLCALL MIX_MSToFrames(int sample_rate, Sint64 ms);

Convert milliseconds to sample frames at a specific sample rate. If sampleRate is <= 0, this returns -1. If ms is < 0, this returns -1.

Parameters

Name	Type	Description
sampleRate	int	the sample rate to use for conversion.
ms	long	the milliseconds to convert to rate-specific sample frames.

Returns

Converted number of sample frames, or -1 for errors; call SDL.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.

XML member id: M:SDL3.Mixer.MSToFrames(System.Int32,System.Int64)

Mixer.PauseAllTracks

public static bool PauseAllTracks(IntPtr mixer);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_PauseAllTracks(MIX_Mixer *mixer);

Pause all currently-playing tracks. A paused track is not considered "stopped," so its Mixer.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

Name	Type	Description
mixer	IntPtr	the mixer on which to pause all tracks.

Returns

true on success, false on error; call SDL.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.

XML member id: M:SDL3.Mixer.PauseAllTracks(System.IntPtr)

Mixer.PauseTag

public static bool PauseTag(IntPtr mixer, string tag);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_PauseTag(MIX_Mixer *mixer, const char *tag);

Pause all tracks with a specific tag. A paused track is not considered "stopped," so its Mixer.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

Name	Type	Description
mixer	IntPtr	the mixer on which to pause tracks.
tag	string	the tag to use when searching for tracks.

Returns

true on success, false on error; call SDL.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.

XML member id: M:SDL3.Mixer.PauseTag(System.IntPtr,System.String)

Mixer.PauseTrack

public static bool PauseTrack(IntPtr track);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_PauseTrack(MIX_Track *track);

Pause a currently-playing track. A paused track is not considered "stopped," so its MIX_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 Mixer.Init not being called or track being null).

Parameters

Name	Type	Description
track	IntPtr	the track to pause.

Returns

true if the track has paused, false on error; call SDL.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.

XML member id: M:SDL3.Mixer.PauseTrack(System.IntPtr)

Mixer.PlayAudio

public static bool PlayAudio(IntPtr mixer, IntPtr audio);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_PlayAudio(MIX_Mixer *mixer, MIX_Audio *audio);

Play a MIX_Audio from start to finish without any management. This is what we term a "fire-and-forget" sound. Internally, SDL_mixer will manage a temporary track to mix the specified MIX_Audio, cleaning it up when complete. No options can be provided for how to do the mixing, like Mixer.PlayTrack 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

Name	Type	Description
mixer	IntPtr	the mixer on which to play this audio.
audio	IntPtr	the audio input to play.

Returns

true if the track has begun mixing, false on error; call SDL.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.

XML member id: M:SDL3.Mixer.PlayAudio(System.IntPtr,System.IntPtr)

Mixer.PlayTag

public static bool PlayTag(IntPtr mixer, string tag, uint options);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_PlayTag(MIX_Mixer *mixer, const char *tag, SDL_PropertiesID options);

Start (or restart) mixing all tracks with a specific tag for playback. This function follows all the same rules as Mixer.PlayTrack; 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 Mixer.TagTrack.

If all of your tagged tracks have different sample rates, it would make sense to use the *MillisecondsNumber properties in your options, instead of *FramesNumber, 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

Name	Type	Description
mixer	IntPtr	the mixer on which to look for tagged tracks.
tag	string	the tag to use when searching for tracks.
options	uint	the set of options that will be applied to each track.

Returns

true on success, false on error; call SDL.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.

XML member id: M:SDL3.Mixer.PlayTag(System.IntPtr,System.String,System.UInt32)

Mixer.PlayTrack

public static bool PlayTrack(IntPtr track, uint options);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_PlayTrack(MIX_Track *track, SDL_PropertiesID options);

Start (or restart) mixing a track for playback. 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 Mixer.SetTrackAudio, Mixer.SetTrackAudioStream, or Mixer.SetTrackIOStream.

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 SDL_PropertiesID. The parameters have reasonable defaults, and specifying a 0 for options will choose defaults for everything.

SDL_PropertiesID are discussed in SDL's documentation .

These are the supported properties:

• Mixer.Props.PlayLoopsNumber: 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.
• Mixer.Props.PlayMaxFrameNumber: 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.
• Mixer.Props.PlayMaxMillisecondsNumber: The same as using the Mixer.Props.PlayMaxFrameNumber 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.
• Mixer.Props.PlayStartFrameNumber: 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.
• Mixer.Props.PlayStartMillisecondNumber: The same as using the Mixer.Props.PlayMaxFrameNumber 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.
• Mixer.Props.PlayLoopStartFrameNumber: 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.
• Mixer.Props.PlayLoopStartMillisecondNumber: The same as using the Mixer.Props.PlayLoopStartFrameNumber 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.
• Mixer.Props.PlayFadeInFramesNumber: 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.
• Mixer.Props.PlayStartMillisecondNumber: The same as using the Mixer.Props.PlayFadeInFramesNumber 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.
• Mixer.Props.PlayFadeInStartGainFloat: 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.
• Mixer.Props.PlayAppendSilenceFramesNumber: 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.
• Mixer.Props.PlayAppendSilenceMillisecondsNumber: The same as using the Mixer.Props.PlayAppendSilenceFramesNumber 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.
• Mixer.Props.PlayHaltWhenExhaustedBoolean: If true, when input is completely consumed for the track, the mixer will mark the track as stopped (and call any appropriate MIX_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 SDL_AudioStream assigned via Mixer.SetTrackAudioStream(). 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.
• Mixer.Props.PlayStartOrderNumber: This is a special-case property that most apps can ignore. For mod file formats, start mixing from a specific "order" index instead of the start of the file. A value < 0 will cause this property to be ignored. If the decoder doesn't support this property, it will also be ignored. If this property is not ignored, the Mixer.Props.PlayStartFrameNumber and Mixer.Props.PlayStartMillisecondNumber properties will be ignored instead. Default -1. Since SDL_mixer 3.2.2. If this function fails, mixing of this track will not start (or restart, if it was already started).

Parameters

Name	Type	Description
track	IntPtr	the track to start (or restart) mixing.
options	uint	a set of properties that control playback. May be zero.

Returns

true on success, false on error; call SDL.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.

XML member id: M:SDL3.Mixer.PlayTrack(System.IntPtr,System.UInt32)

Mixer.Quit

public static void Quit();

SDL declaration

extern SDL_DECLSPEC void SDLCALL MIX_Quit(void);

Deinitialize the SDL_mixer library.

This must be called when done with the library, probably at the end of your program.

It is safe to call this multiple times; the library will only deinitialize once, when this function is called the same number of times as MIX_Init was successfully called.

Once you have successfully deinitialized the library, it is safe to call MIX_Init to reinitialize it for further use.

On successful deinitialization, SDL_mixer will destroy almost all created objects, including objects of type:

• MIX_Mixer
• MIX_Track
• MIX_Audio
• MIX_Group
• MIX_AudioDecoder ...which is to say: it's possible a single call to this function will clean up anything it allocated, stop all audio output, close audio devices, etc. Don't attempt to destroy objects after this call. The app is still encouraged to manage their resources carefully and clean up first, treating this function as a safety net against memory leaks.

Thread safety

It is safe to call this function from any thread.

Since: This function is available since SDL_mixer 3.0.0.

XML member id: M:SDL3.Mixer.Quit

Mixer.ResumeAllTracks

public static bool ResumeAllTracks(IntPtr mixer);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_ResumeAllTracks(MIX_Mixer *mixer);

Resume all currently-paused tracks. A paused track is not considered "stopped," so its Mixer.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

Name	Type	Description
mixer	IntPtr	the mixer on which to resume all tracks.

Returns

true on success, false on error; call SDL.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.

XML member id: M:SDL3.Mixer.ResumeAllTracks(System.IntPtr)

Mixer.ResumeTag

public static bool ResumeTag(IntPtr mixer, string tag);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_ResumeTag(MIX_Mixer *mixer, const char *tag);

Resume all tracks with a specific tag. A paused track is not considered "stopped," so its Mixer.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

Name	Type	Description
mixer	IntPtr	the mixer on which to resume tracks.
tag	string	the tag to use when searching for tracks.

Returns

true on success, false on error; call SDL.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.

XML member id: M:SDL3.Mixer.ResumeTag(System.IntPtr,System.String)

Mixer.ResumeTrack

public static bool ResumeTrack(IntPtr track);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_ResumeTrack(MIX_Track *track);

Resume a currently-paused track. A paused track is not considered "stopped," so its Mixer.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 Mixer.Init not being called or track being null).

Parameters

Name	Type	Description
track	IntPtr	the track to resume.

Returns

true if the track has resumed, false on error; call SDL.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.

XML member id: M:SDL3.Mixer.ResumeTrack(System.IntPtr)

Mixer.SetGroupPostMixCallback

public static bool SetGroupPostMixCallback(IntPtr group, Mixer.GroupMixCallback cb, IntPtr userdata);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_SetGroupPostMixCallback(MIX_Group *group, MIX_GroupMixCallback cb, void *userdata);

Set a callback that fires when a mixer group has completed mixing. 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 MIX_Group are mixed in an internal grouping that is not available to the app.

Passing a null callback here is legal; it disables this group's callback.

Parameters

Name	Type	Description
group	IntPtr	the mixing group to assign this callback to.
cb	Mixer.GroupMixCallback	the function to call when the group mixes. May be null.
userdata	IntPtr	an opaque pointer provided to the callback for its own personal use.

Returns

true on success or false on failure; call SDL.GetError for more information.

Since: This function is available since SDL_mixer 3.0.0.

XML member id: M:SDL3.Mixer.SetGroupPostMixCallback(System.IntPtr,SDL3.Mixer.GroupMixCallback,System.IntPtr)

Mixer.SetMixerFrequencyRatio

public static bool SetMixerFrequencyRatio(IntPtr mixer, float ratio);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_SetMixerFrequencyRatio(MIX_Mixer *mixer, float ratio);

Set a mixer's master frequency ratio. 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

Name	Type	Description
mixer	IntPtr	the mixer to adjust.
ratio	float	the frequency ratio. Must be between 0.01f and 100.0f.

Returns

true on success or false on failure; call SDL.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.

XML member id: M:SDL3.Mixer.SetMixerFrequencyRatio(System.IntPtr,System.Single)

Mixer.SetMixerGain

public static bool SetMixerGain(IntPtr mixer, float gain);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_SetMixerGain(MIX_Mixer *mixer, float gain);

Set a mixer's master gain control. 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

Name	Type	Description
mixer	IntPtr	the mixer to adjust.
gain	float	the new gain value.

Returns

true on success or false on failure; call SDL.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.

XML member id: M:SDL3.Mixer.SetMixerGain(System.IntPtr,System.Single)

Mixer.SetPostMixCallback

public static bool SetPostMixCallback(IntPtr mixer, Mixer.PostMixCallback cb, IntPtr userdata);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_SetPostMixCallback(MIX_Mixer *mixer, MIX_PostMixCallback cb, void *userdata);

Set a callback that fires when all mixing has completed.

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 null callback here is legal; it disables this mixer's callback.

Parameters

Name	Type	Description
mixer	IntPtr	the mixer to assign this callback to.
cb	Mixer.PostMixCallback	the function to call when the mixer mixes. May be null.
userdata	IntPtr	an opaque pointer provided to the callback for its own personal use.

Returns

true on success or false on failure; call SDL.GetError for more information.

Since: This function is available since SDL_mixer 3.0.0.

XML member id: M:SDL3.Mixer.SetPostMixCallback(System.IntPtr,SDL3.Mixer.PostMixCallback,System.IntPtr)

Mixer.SetTagGain

public static bool SetTagGain(IntPtr mixer, string tag, float gain);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_SetTagGain(MIX_Mixer *mixer, const char *tag, float gain);

Set the gain control of all tracks with a specific tag. 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

Name	Type	Description
mixer	IntPtr	the mixer on which to look for tagged tracks.
tag	string	the tag to use when searching for tracks.
gain	float	the new gain value.

Returns

true on success or false on failure; call SDL.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.

XML member id: M:SDL3.Mixer.SetTagGain(System.IntPtr,System.String,System.Single)

Mixer.SetTrack3DPosition

public static bool SetTrack3DPosition(IntPtr track, IntPtr position);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_SetTrack3DPosition(MIX_Track *track, const MIX_Point3D *position);

Set a track's position in 3D space. (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 null, this track will be switched into 3D positional mode. If position is null, this will disable positional mixing (both the full 3D spatialization of this function and forced-stereo mode of Mixer.SetTrackStereo).

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 Mixer.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

Name	Type	Description
track	IntPtr	the track for which to set 3D position.
position	IntPtr	the new 3D position for the track. May be null.

Returns

true on success or false on failure; call SDL.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.

XML member id: M:SDL3.Mixer.SetTrack3DPosition(System.IntPtr,System.IntPtr)

Mixer.SetTrackAudio

public static bool SetTrackAudio(IntPtr track, IntPtr audio);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_SetTrackAudio(MIX_Track *track, MIX_Audio *audio);

Set a MIX_Track's input to a MIX_Audio. A MIX_Audio is audio data stored in RAM (possibly still in a compressed form). One MIX_Audio can be assigned to multiple tracks at once.

Once a track has a valid input, it can start mixing sound by calling Mixer.PlayTrack, or possibly Mixer.PlayTag.

Calling this function with a null 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 Mixer.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 Mixer.PlayTrack again to adjust parameters.

The track will hold a reference to the provided MIX_Audio, so it is safe to call Mixer.DestroyAudio 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 MIX_Audio.

Parameters

Name	Type	Description
track	IntPtr	the track on which to set a new audio input.
audio	IntPtr	the new audio input to set. May be null.

Returns

on success, false on error; call SDL.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.

XML member id: M:SDL3.Mixer.SetTrackAudio(System.IntPtr,System.IntPtr)

Mixer.SetTrackAudioStream

public static bool SetTrackAudioStream(IntPtr track, IntPtr stream);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_SetTrackAudioStream(MIX_Track *track, SDL_AudioStream *stream);

Set a MIX_Track's input to an SDL_AudioStream. 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 SDL_GetAudioStreamData 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 Mixer.PlayTrack, or possibly Mixer.PlayTag.

Calling this function with a null 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 Mixer.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 Mixer.PlayTrack 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

Name	Type	Description
track	IntPtr	the track on which to set a new audio input.
stream	IntPtr	the audio stream to use as the track's input.

Returns

true on success, false on error; call SDL.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.

XML member id: M:SDL3.Mixer.SetTrackAudioStream(System.IntPtr,System.IntPtr)

Mixer.SetTrackCookedCallback

public static bool SetTrackCookedCallback(IntPtr track, Mixer.TrackMixCallback cb, IntPtr userdata);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_SetTrackCookedCallback(MIX_Track *track, MIX_TrackMixCallback cb, void *userdata);

Set a callback that fires when the mixer has transformed a track's audio.

As a track needs to mix more data, it pulls from its input (a MIX_Audio, an SDL_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 null callback here is legal; it disables this track's callback.

Parameters

Name	Type	Description
track	IntPtr	the track to assign this callback to.
cb	Mixer.TrackMixCallback	the function to call when the track mixes. May be null.
userdata	IntPtr	an opaque pointer provided to the callback for its own personal use.

Returns

true on success or false on failure; call SDL.GetError for more information.

Since: This function is available since SDL_mixer 3.0.0.

XML member id: M:SDL3.Mixer.SetTrackCookedCallback(System.IntPtr,SDL3.Mixer.TrackMixCallback,System.IntPtr)

Mixer.SetTrackFrequencyRatio

public static bool SetTrackFrequencyRatio(IntPtr track, float ratio);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_SetTrackFrequencyRatio(MIX_Track *track, float ratio);

Change the frequency ratio of a track. 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

Name	Type	Description
track	IntPtr	the track on which to change the frequency ratio.
ratio	float	the frequency ratio. Must be between 0.01f and 100.0f.

Returns

true on success or false on failure; call SDL.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.

XML member id: M:SDL3.Mixer.SetTrackFrequencyRatio(System.IntPtr,System.Single)

Mixer.SetTrackGain

public static bool SetTrackGain(IntPtr track, float gain);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_SetTrackGain(MIX_Track *track, float gain);

Set a track's gain control. 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

Name	Type	Description
track	IntPtr	the track to adjust.
gain	float	the new gain value.

Returns

true on success or false on failure; call SDL.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.

XML member id: M:SDL3.Mixer.SetTrackGain(System.IntPtr,System.Single)

Mixer.SetTrackGroup

public static bool SetTrackGroup(IntPtr track, IntPtr group);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_SetTrackGroup(MIX_Track *track, MIX_Group *group);

Assign a track to a mixing group. 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 MIX_Mixer.

Setting a track to a null group will remove it from any app-created groups, and reassign it to the mixer's internal default group.

Parameters

Name	Type	Description
track	IntPtr	the track to set mixing group assignment.
group	IntPtr	the new mixing group to assign to. May be null

Returns

true on success or false on failure; call SDL.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.

XML member id: M:SDL3.Mixer.SetTrackGroup(System.IntPtr,System.IntPtr)

Mixer.SetTrackIOStream

public static bool SetTrackIOStream(IntPtr track, IntPtr io, bool closeio);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_SetTrackIOStream(MIX_Track *track, SDL_IOStream *io, bool closeio);

Set a MIX_Track's input to an SDL_IOStream. 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 MIX_Audio ahead of time and use Mixer.SetTrackAudio 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 Mixer.PlayTrack, or possibly Mixer.PlayTag.

Calling this function with a null 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 Mixer.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 Mixer.PlayTrack 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

Name	Type	Description
track	IntPtr	the track on which to set a new audio input.
io	IntPtr	the new i/o stream to use as the track's input.
closeio	bool	if true, close the stream when done with it.

Returns

true on success, false on error; call SDL.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.

XML member id: M:SDL3.Mixer.SetTrackIOStream(System.IntPtr,System.IntPtr,System.Boolean)

Mixer.SetTrackLoops

public static bool SetTrackLoops(IntPtr track, int numLoops);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_SetTrackLoops(MIX_Track *track, int num_loops);

Change the number of times a currently-playing track will loop. 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 numLoops 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 Mixer.Props.PlayLoopsNumber. This function is intended to alter that count in the middle of playback.

Parameters

Name	Type	Description
track	IntPtr	the track to configure.
numLoops	int	new number of times to loop. Zero to disable looping, -1 to loop infinitely.

Returns

true on success, false on error; call SDL.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.

XML member id: M:SDL3.Mixer.SetTrackLoops(System.IntPtr,System.Int32)

Mixer.SetTrackOutputChannelMap

public static bool SetTrackOutputChannelMap(IntPtr track, IntPtr chmap, int count);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_SetTrackOutputChannelMap(MIX_Track *track, const int *chmap, int count);

Set the current output channel map of a track. 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 null 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

Name	Type	Description
track	IntPtr	the track to change.
chmap	IntPtr	the new channel map, null to reset to default.
count	int	The number of channels in the map.

Returns

true on success or false on failure; call SDL.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.

XML member id: M:SDL3.Mixer.SetTrackOutputChannelMap(System.IntPtr,System.IntPtr,System.Int32)

Mixer.SetTrackPlaybackPosition

public static bool SetTrackPlaybackPosition(IntPtr track, long frames);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_SetTrackPlaybackPosition(MIX_Track *track, Sint64 frames);

Seek a playing track to a new position in its input. (Not to be confused with Mixer.SetTrack3DPosition, 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 Mixer.TrackMSToFrames 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 Mixer.SetTrackAudioStream), 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 Mixer.PlayTrack will reset the start position anyhow. Paused tracks will resume at the new input position.

Parameters

Name	Type	Description
track	IntPtr	the track to change.
frames	long	the sample frame position to seek to.

Returns

true on success, false on error; call SDL.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.

XML member id: M:SDL3.Mixer.SetTrackPlaybackPosition(System.IntPtr,System.Int64)

Mixer.SetTrackRawIOStream

public static bool SetTrackRawIOStream(IntPtr track, IntPtr io, in IntPtr spec, bool closeio);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_SetTrackRawIOStream(MIX_Track *track, SDL_IOStream *io, const SDL_AudioSpec *spec, bool closeio);

Set a MIX_Track's input to an SDL_IOStream providing raw PCM data. 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 MIX_Audio ahead of time and use Mixer.SetTrackAudio instead.

Also, an Mixer.SetTrackAudioStream can also provide raw PCM audio to a track, via an SDL_AudioStream, which might be preferable unless the data is already coming directly from an SDL_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 Mixer.PlayTrack, or possibly Mixer.PlayTag.

Calling this function with a null 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 Mixer.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 Mixer.PlayTrack 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

Name	Type	Description
track	IntPtr	the track on which to set a new audio input.
io	IntPtr	the new i/o stream to use as the track's input.
spec	in IntPtr	the format of the PCM data that the SDL_IOStream will provide
closeio	bool	if true, close the stream when done with it.

Returns

true on success, false on error; call SDL.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.

XML member id: M:SDL3.Mixer.SetTrackRawIOStream(System.IntPtr,System.IntPtr,System.IntPtr@,System.Boolean)

Mixer.SetTrackStereo

public static bool SetTrackStereo(IntPtr track, IntPtr gains);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_SetTrackStereo(MIX_Track *track, const MIX_StereoGains *gains);

Force a track to stereo output, with optionally left/right panning. 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 null, this track will be switched into forced-stereo mode. If gains is null, this will disable spatialization (both the forced-stereo mode of this function and full 3D spatialization of Mixer.SetTrack3DPosition).

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 Mixer.GetTrack3DPosition, will be reset to (0, 0, 0).

Parameters

Name	Type	Description
track	IntPtr	the track to adjust.
gains	IntPtr	the per-channel gains, or null to disable spatialization.

Returns

true on success or false on failure; call SDL.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.

XML member id: M:SDL3.Mixer.SetTrackStereo(System.IntPtr,System.IntPtr)

Mixer.SetTrackStoppedCallback

public static bool SetTrackStoppedCallback(IntPtr track, Mixer.TrackStoppedCallback cb, IntPtr userdata);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_SetTrackStoppedCallback(MIX_Track *track, MIX_TrackStoppedCallback cb, void *userdata);

Set a callback that fires when a MIX_Track is stopped. 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 null 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

Name	Type	Description
track	IntPtr	the track to assign this callback to.
cb	Mixer.TrackStoppedCallback	the function to call when the track stops. May be null.
userdata	IntPtr	an opaque pointer provided to the callback for its own personal use.

Returns

true on success or false on failure; call SDL.GetError for more information.

Since: This function is available since SDL_mixer 3.0.0.

XML member id: M:SDL3.Mixer.SetTrackStoppedCallback(System.IntPtr,SDL3.Mixer.TrackStoppedCallback,System.IntPtr)

Mixer.StopAllTracks

public static bool StopAllTracks(IntPtr mixer, long fadeOutMs);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_StopAllTracks(MIX_Mixer *mixer, Sint64 fade_out_ms);

Halt all currently-playing tracks, possibly fading out over time. If fadeOutMs 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 Mixer.StopTrack, 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 Mixer.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; it's legal to use this function to begin fading all playing tracks but then start other tracks playing normally while those fade-outs are still in progress.

Parameters

Name	Type	Description
mixer	IntPtr	the mixer on which to stop all tracks.
fadeOutMs	long	the number of milliseconds to spend fading out to silence before halting. 0 to stop immediately.

Returns

true on success, false on error; call SDL.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.

XML member id: M:SDL3.Mixer.StopAllTracks(System.IntPtr,System.Int64)

Mixer.StopTag

public static bool StopTag(IntPtr mixer, string tag, long fadeOutMs);

SDL declaration

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

Halt all tracks with a specific tag, possibly fading out over time. If fadeOutMs 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 Mixer.StopTrack, 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 Mixer.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

Name	Type	Description
mixer	IntPtr	the mixer on which to stop tracks.
tag	string	the tag to use when searching for tracks.
fadeOutMs	long	the number of milliseconds to spend fading out to silence before halting. 0 to stop immediately.

Returns

true on success, false on error; call SDL.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.

XML member id: M:SDL3.Mixer.StopTag(System.IntPtr,System.String,System.Int64)

Mixer.StopTrack

public static bool StopTrack(IntPtr track, long fadeOutFrames);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_StopTrack(MIX_Track *track, Sint64 fade_out_frames);

Halt a currently-playing track, possibly fading out over time. If fadeOutFrames 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. Mixer.TrackMSToFrames 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 Mixer.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

Name	Type	Description
track	IntPtr	the track to halt.
fadeOutFrames	long	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 SDL.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.

XML member id: M:SDL3.Mixer.StopTrack(System.IntPtr,System.Int64)

Mixer.TagTrack

public static bool TagTrack(IntPtr track, string tag);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_TagTrack(MIX_Track *track, const char *tag);

Assign an arbitrary tag to a track. 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 Mixer.UntagTrack.

Parameters

Name	Type	Description
track	IntPtr	the track to add a tag to.
tag	string	the tag to add.

Returns

true on success, false on error; call SDL.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.

XML member id: M:SDL3.Mixer.TagTrack(System.IntPtr,System.String)

Mixer.TrackFramesToMS

public static long TrackFramesToMS(IntPtr track, long frames);

SDL declaration

extern SDL_DECLSPEC Sint64 SDLCALL MIX_TrackFramesToMS(MIX_Track *track, Sint64 frames);

Convert sample frames for a track's current format to milliseconds. 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 (Mixer.Init was not called, the track is null), this returns -1. If the track has no input, this returns -1. If frames is < 0, this returns -1.

Parameters

Name	Type	Description
track	IntPtr	the track to query.
frames	long	the track-specific sample frames to convert to milliseconds.

Returns

Converted number of milliseconds, or -1 for errors/no input; call SDL.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.

XML member id: M:SDL3.Mixer.TrackFramesToMS(System.IntPtr,System.Int64)

Mixer.TrackMSToFrames

public static long TrackMSToFrames(IntPtr track, long ms);

SDL declaration

extern SDL_DECLSPEC Sint64 SDLCALL MIX_TrackMSToFrames(MIX_Track *track, Sint64 ms);

Convert milliseconds to sample frames for a track's current format. 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 (Mixer.Init was not called, the track is null), this returns -1. If the track has no input, this returns -1. If ms is < 0, this returns -1.

Parameters

Name	Type	Description
track	IntPtr	the track to query.
ms	long	the milliseconds to convert to track-specific sample frames.

Returns

Converted number of sample frames, or -1 for errors/no input; call SDL.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.

XML member id: M:SDL3.Mixer.TrackMSToFrames(System.IntPtr,System.Int64)

Mixer.TrackPaused

public static bool TrackPaused(IntPtr track);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_TrackPaused(MIX_Track *track);

Query if a track is currently paused. 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 (Mixer.Init was not called, the track is null), this returns false, but there is no mechanism to distinguish errors from non-playing tracks.

Parameters

Name	Type	Description
track	IntPtr	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.

XML member id: M:SDL3.Mixer.TrackPaused(System.IntPtr)

Mixer.TrackPlaying

public static bool TrackPlaying(IntPtr track);

SDL declaration

extern SDL_DECLSPEC bool SDLCALL MIX_TrackPlaying(MIX_Track *track);

Query if a track is currently playing. 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 null), this returns false, but there is no mechanism to distinguish errors from non-playing tracks.

Parameters

Name	Type	Description
track	IntPtr	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.

XML member id: M:SDL3.Mixer.TrackPlaying(System.IntPtr)

Mixer.UntagTrack

public static void UntagTrack(IntPtr track, string tag);

SDL declaration

extern SDL_DECLSPEC void SDLCALL MIX_UntagTrack(MIX_Track *track, const char *tag);

Remove an arbitrary tag from a track. 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 null tag will remove all tags on a track.

Parameters

Name	Type	Description
track	IntPtr	the track from which to remove a tag.
tag	string	the tag to remove, or null to remove all current tags.

Thread safety

It is safe to call this function from any thread.

XML member id: M:SDL3.Mixer.UntagTrack(System.IntPtr,System.String)

Mixer.Version

public static int Version();

SDL declaration

extern SDL_DECLSPEC int SDLCALL MIX_Version(void);

Get the version of SDL_mixer that is linked against your program. If you are linking to SDL_mixer dynamically, then it is possible that the current version will be different than the version you compiled against. This function returns the current version, while SDL_MIXER_VERSION is the version you compiled with.

Returns

the version of the linked library.

Remarks

This function may be called safely at any time, even before Mixer.Init.

Since: This function is available since SDL_mixer 3.0.0.

XML member id: M:SDL3.Mixer.Version