mixer topic

CategorySDLMixer

SDL_mixer is a library to make complicated audio processing tasks easier.

It offers audio file decoding, mixing multiple sounds together, basic 3D positional audio, and various audio effects.

It can mix sound to multiple audio devices in real time, or generate mixed audio data to a memory buffer for any other use. It can do both at the same time!

To use the library, first call MIX_Init(). Then create a mixer with MIX_CreateMixerDevice() (or MIX_CreateMixer() to render to memory).

Once you have a mixer, you can load sound data with MIX_LoadAudio(), MIX_LoadAudio_IO(), or MIX_LoadAudioWithProperties(). Data gets loaded once and can be played over and over.

When loading audio, SDL_mixer can parse out several metadata tag formats, such as ID3 and APE tags, and exposes this information through the MIX_GetAudioProperties() function.

To play audio, you create a track with MIX_CreateTrack(). You need one track for each sound that will be played simultaneously; think of tracks as individual sliders on a mixer board. You might have loaded hundreds of audio files, but you probably only have a handful of tracks that you assign those loaded files to when they are ready to play, and reuse those tracks with different audio later. Tracks take their input from a MIX_Audio (static data to be played multiple times) or an SDL_AudioStream (streaming PCM audio the app supplies, possibly as needed). A third option is to supply an SDL_IOStream, to load and decode on the fly, which might be more efficient for background music that is only used once, etc.

Assign input to a MIX_Track with MIX_SetTrackAudio(), MIX_SetTrackAudioStream(), or MIX_SetTrackIOStream().

Once a track has an input, start it playing with MIX_PlayTrack(). There are many options to this function to dictate mixing features: looping, fades, etc.

Tracks can be tagged with arbitrary strings, like "music" or "ingame" or "ui". These tags can be used to start, stop, and pause a selection of tracks at the same moment.

All significant portions of the mixing pipeline have callbacks, so that an app can hook in to the appropriate locations to examine or modify audio data as it passes through the mixer: a "raw" callback for raw PCM data decoded from an audio file without any modifications, a "cooked" callback for that same data after all transformations (fade, positioning, etc) have been processed, a "stopped" callback for when the track finishes mixing, a "postmix" callback for the final mixed audio about to be sent to the audio hardware to play. Additionally, you can use MIX_Group objects to mix a subset of playing tracks and access the data before it is mixed in with other tracks. All of this is optional, but allows for powerful access and control of the mixing process.

SDL_mixer can also be used for decoding audio files without actually rendering a mix. This is done with MIX_AudioDecoder. Even though SDL_mixer handles decoding transparently when used as the audio engine for an app, and probably won't need this interface in that normal scenario, this can be useful when using a different audio library to access many file formats.

This library offers several features on top of mixing sounds together: a track can have its own gain, to adjust its volume, in addition to a master gain applied as well. One can set the "frequency ratio" of a track, to speed it up or slow it down, which also adjusts its pitch. A channel map can also be applied per-track, to change what speaker a given channel of audio is output to.

Almost all timing in SDL_mixer is in sample frames. Stereo PCM audio data in Sint16 format takes 4 bytes per sample frame (2 bytes per sample times 2 channels), for example. This allows everything in SDL_mixer to run at sample-perfect accuracy, and it lets it run without concern for wall clock time--you can produce audio faster than real-time, if desired. The problem, though, is different pieces of audio at different sample rates will produce a different number of sample frames for the same length of time. To deal with this, conversion routines are offered: MIX_TrackMSToFrames(), MIX_TrackFramesToMS(), etc. Functions that operate on multiple tracks at once will deal with time in milliseconds, so it can do these conversions internally; be sure to read the documentation for these small quirks!

SDL_mixer offers basic positional audio: a simple 3D positioning API through MIX_SetTrack3DPosition() and MIX_SetTrackStereo(). The former will do simple distance attenuation and spatialization--on a stereo setup, you will hear sounds move from left to right--and on a surround-sound configuration, individual tracks can move around the user. The latter, MIX_SetTrackStereo(), will force a sound to the Front Left and Front Right speakers and let the app pan it left and right as desired. Either effect can be useful for different situations. SDL_mixer is not meant to be a full 3D audio engine, but rather Good Enough for many purposes; if something more powerful in terms of 3D audio is needed, consider a proper 3D library like OpenAL.

Classes

MixAudio

MixAudioDecoder

MixGroup

MixMixer

MixPoint3D

MixStereoGains

MixTrack

Functions

mixAudioFramesToMs(Pointer<MixAudio> audio, int frames) → int

Convert sample frames for a MIX_Audio's format to milliseconds.

mixAudioMsToFrames(Pointer<MixAudio> audio, int ms) → int

Convert milliseconds to sample frames for a MIX_Audio's format.

mixCreateAudioDecoder(String? path, int props) → Pointer<MixAudioDecoder>

Create a MIX_AudioDecoder from a path on the filesystem.

mixCreateAudioDecoderIo(Pointer<SdlIoStream> io, bool closeio, int props) → Pointer<MixAudioDecoder>

Create a MIX_AudioDecoder from an SDL_IOStream.

mixCreateGroup(Pointer<MixMixer> mixer) → Pointer<MixGroup>

Create a mixing group.

mixCreateMixer(Pointer<SdlAudioSpec> spec) → Pointer<MixMixer>

Create a mixer that generates audio to a memory buffer.

mixCreateMixerDevice(int devid, Pointer<SdlAudioSpec> spec) → Pointer<MixMixer>

Create a mixer that plays sound directly to an audio device.

mixCreateSineWaveAudio(Pointer<MixMixer> mixer, int hz, double amplitude) → Pointer<MixAudio>

Create a MIX_Audio that generates a sinewave.

mixCreateTrack(Pointer<MixMixer> mixer) → Pointer<MixTrack>

Create a new track on a mixer.

mixDecodeAudio(Pointer<MixAudioDecoder> audiodecoder, Pointer<NativeType> buffer, int buflen, Pointer<SdlAudioSpec> spec) → int

Decode more audio from a MIX_AudioDecoder.

mixDestroyAudio(Pointer<MixAudio> audio) → void

Destroy the specified audio.

mixDestroyAudioDecoder(Pointer<MixAudioDecoder> audiodecoder) → void

Destroy the specified audio decoder.

mixDestroyGroup(Pointer<MixGroup> group) → void

Destroy a mixing group.

mixDestroyMixer(Pointer<MixMixer> mixer) → void

Free a mixer.

mixDestroyTrack(Pointer<MixTrack> track) → void

Destroy the specified track.

mixFramesToMs(int sampleRate, int frames) → int

Convert sample frames, at a specific sample rate, to milliseconds.

mixGenerate(Pointer<MixMixer> mixer, Pointer<NativeType> buffer, int buflen) → bool

Generate mixer output when not driving an audio device.

mixGetAudioDecoder(int index) → String?

Report the name of a specific audio decoders.

mixGetAudioDecoderFormat(Pointer<MixAudioDecoder> audiodecoder, Pointer<SdlAudioSpec> spec) → bool

Query the initial audio format of a MIX_AudioDecoder.

mixGetAudioDecoderProperties(Pointer<MixAudioDecoder> audiodecoder) → int

Get the properties associated with a MIX_AudioDecoder.

mixGetAudioDuration(Pointer<MixAudio> audio) → int

Get the length of a MIX_Audio's playback in sample frames.

mixGetAudioFormat(Pointer<MixAudio> audio, Pointer<SdlAudioSpec> spec) → bool

Query the initial audio format of a MIX_Audio.

mixGetAudioProperties(Pointer<MixAudio> audio) → int

Get the properties associated with a MIX_Audio.

mixGetGroupMixer(Pointer<MixGroup> group) → Pointer<MixMixer>

Get the MIX_Mixer that owns a MIX_Group.

mixGetGroupProperties(Pointer<MixGroup> group) → int

Get the properties associated with a group.

mixGetMasterGain(Pointer<MixMixer> mixer) → double

Get a mixer's master gain control.

mixGetMixerFormat(Pointer<MixMixer> mixer, Pointer<SdlAudioSpec> spec) → bool

Get the audio format a mixer is generating.

mixGetMixerProperties(Pointer<MixMixer> mixer) → int

Get the properties associated with a mixer.

mixGetNumAudioDecoders() → int

Report the number of audio decoders available for use.

mixGetTrack3DPosition(Pointer<MixTrack> track, Pointer<MixPoint3D> position) → bool

Get a track's current position in 3D space.

mixGetTrackAudio(Pointer<MixTrack> track) → Pointer<MixAudio>

Query the MIX_Audio assigned to a track.

mixGetTrackAudioStream(Pointer<MixTrack> track) → Pointer<SdlAudioStream>

Query the SDL_AudioStream assigned to a track.

mixGetTrackFrequencyRatio(Pointer<MixTrack> track) → double

Query the frequency ratio of a track.

mixGetTrackGain(Pointer<MixTrack> track) → double

Get a track's gain control.

mixGetTrackMixer(Pointer<MixTrack> track) → Pointer<MixMixer>

Get the MIX_Mixer that owns a MIX_Track.

mixGetTrackPlaybackPosition(Pointer<MixTrack> track) → int

Get the current input position of a playing track.

mixGetTrackProperties(Pointer<MixTrack> track) → int

Get the properties associated with a track.

mixGetTrackRemaining(Pointer<MixTrack> track) → int

Return the number of sample frames remaining to be mixed in a track.

mixInit() → bool

Initialize the SDL_mixer library.

mixLoadAudio(Pointer<MixMixer> mixer, String? path, bool predecode) → Pointer<MixAudio>

Load audio for playback from a file.

mixLoadAudioIo(Pointer<MixMixer> mixer, Pointer<SdlIoStream> io, bool predecode, bool closeio) → Pointer<MixAudio>

Load audio for playback from an SDL_IOStream.

mixLoadAudioWithProperties(int props) → Pointer<MixAudio>

Load audio for playback through a collection of properties.

mixLoadRawAudio(Pointer<MixMixer> mixer, Pointer<NativeType> data, int datalen, Pointer<SdlAudioSpec> spec) → Pointer<MixAudio>

Load raw PCM data from a memory buffer.

mixLoadRawAudioIo(Pointer<MixMixer> mixer, Pointer<SdlIoStream> io, Pointer<SdlAudioSpec> spec, bool closeio) → Pointer<MixAudio>

Load raw PCM data from an SDL_IOStream.

mixLoadRawAudioNoCopy(Pointer<MixMixer> mixer, Pointer<NativeType> data, int datalen, Pointer<SdlAudioSpec> spec, bool freeWhenDone) → Pointer<MixAudio>

Load raw PCM data from a memory buffer without making a copy.

mixMsToFrames(int sampleRate, int ms) → int

Convert milliseconds to sample frames at a specific sample rate.

mixPauseAllTracks(Pointer<MixMixer> mixer) → bool

Pause all currently-playing tracks.

mixPauseTag(Pointer<MixMixer> mixer, String? tag) → bool

Pause all tracks with a specific tag.

mixPauseTrack(Pointer<MixTrack> track) → bool

Pause a currently-playing track.

mixPlayAudio(Pointer<MixMixer> mixer, Pointer<MixAudio> audio) → bool

Play a MIX_Audio from start to finish without any management.

mixPlayTag(Pointer<MixMixer> mixer, String? tag, int options) → bool

Start (or restart) mixing all tracks with a specific tag for playback.

mixPlayTrack(Pointer<MixTrack> track, int options) → bool

Start (or restart) mixing a track for playback.

mixQuit() → void

Deinitialize the SDL_mixer library.

mixResumeAllTracks(Pointer<MixMixer> mixer) → bool

Resume all currently-paused tracks.

mixResumeTag(Pointer<MixMixer> mixer, String? tag) → bool

Resume all tracks with a specific tag.

mixResumeTrack(Pointer<MixTrack> track) → bool

Resume a currently-paused track.

mixSetGroupPostMixCallback(Pointer<MixGroup> group, Pointer<NativeFunction<MixGroupMixCallback>> cb, Pointer<NativeType> userdata) → bool

Set a callback that fires when a mixer group has completed mixing.

mixSetMasterGain(Pointer<MixMixer> mixer, double gain) → bool

Set a mixer's master gain control.

mixSetPostMixCallback(Pointer<MixMixer> mixer, Pointer<NativeFunction<MixPostMixCallback>> cb, Pointer<NativeType> userdata) → bool

Set a callback that fires when all mixing has completed.

mixSetTagGain(Pointer<MixMixer> mixer, String? tag, double gain) → bool

Set the gain control of all tracks with a specific tag.

mixSetTrack3DPosition(Pointer<MixTrack> track, Pointer<MixPoint3D> position) → bool

Set a track's position in 3D space.

mixSetTrackAudio(Pointer<MixTrack> track, Pointer<MixAudio> audio) → bool

Set a MIX_Track's input to a MIX_Audio.

mixSetTrackAudioStream(Pointer<MixTrack> track, Pointer<SdlAudioStream> stream) → bool

Set a MIX_Track's input to an SDL_AudioStream.

mixSetTrackCookedCallback(Pointer<MixTrack> track, Pointer<NativeFunction<MixTrackMixCallback>> cb, Pointer<NativeType> userdata) → bool

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

mixSetTrackFrequencyRatio(Pointer<MixTrack> track, double ratio) → bool

Change the frequency ratio of a track.

mixSetTrackGain(Pointer<MixTrack> track, double gain) → bool

Set a track's gain control.

mixSetTrackGroup(Pointer<MixTrack> track, Pointer<MixGroup> group) → bool

Assign a track to a mixing group.

mixSetTrackIoStream(Pointer<MixTrack> track, Pointer<SdlIoStream> io, bool closeio) → bool

Set a MIX_Track's input to an SDL_IOStream.

mixSetTrackOutputChannelMap(Pointer<MixTrack> track, Pointer<Int32> chmap, int count) → bool

Set the current output channel map of a track.

mixSetTrackPlaybackPosition(Pointer<MixTrack> track, int frames) → bool

Seek a playing track to a new position in its input.

mixSetTrackRawCallback(Pointer<MixTrack> track, Pointer<NativeFunction<MixTrackMixCallback>> cb, Pointer<NativeType> userdata) → bool

Set a callback that fires when a MIX_Track has initial decoded audio.

mixSetTrackRawIoStream(Pointer<MixTrack> track, Pointer<SdlIoStream> io, Pointer<SdlAudioSpec> spec, bool closeio) → bool

Set a MIX_Track's input to an SDL_IOStream providing raw PCM data.

mixSetTrackStereo(Pointer<MixTrack> track, Pointer<MixStereoGains> gains) → bool

Force a track to stereo output, with optionally left/right panning.

mixSetTrackStoppedCallback(Pointer<MixTrack> track, Pointer<NativeFunction<MixTrackStoppedCallback>> cb, Pointer<NativeType> userdata) → bool

Set a callback that fires when a MIX_Track is stopped.

mixStopAllTracks(Pointer<MixMixer> mixer, int fadeOutMs) → bool

Halt all currently-playing tracks, possibly fading out over time.

mixStopTag(Pointer<MixMixer> mixer, String? tag, int fadeOutMs) → bool

Halt all tracks with a specific tag, possibly fading out over time.

mixStopTrack(Pointer<MixTrack> track, int fadeOutFrames) → bool

Halt a currently-playing track, possibly fading out over time.

mixTagTrack(Pointer<MixTrack> track, String? tag) → bool

Assign an arbitrary tag to a track.

mixTrackFramesToMs(Pointer<MixTrack> track, int frames) → int

Convert sample frames for a track's current format to milliseconds.

mixTrackLooping(Pointer<MixTrack> track) → bool

Query whether a given track is looping.

mixTrackMsToFrames(Pointer<MixTrack> track, int ms) → int

Convert milliseconds to sample frames for a track's current format.

mixTrackPaused(Pointer<MixTrack> track) → bool

Query if a track is currently paused.

mixTrackPlaying(Pointer<MixTrack> track) → bool

Query if a track is currently playing.

mixUntagTrack(Pointer<MixTrack> track, String? tag) → void

Remove an arbitrary tag from a track.

mixVersion() → int

Get the version of SDL_mixer that is linked against your program.