sdljava.mixer

Class SDLMixer

public class SDLMixer extends Object

Binding to the SDL_mixer library.

Please see the documentation here.

This library wraps all the functionality provided, however, no support for callbacks is currently implemented.

All audio data currently lives at the C layer and is never copied or deal with at the java side.

Version: $Id: SDLMixer.java,v 1.18 2005/02/19 02:26:02 ivan_ganza Exp $

Author: Ivan Z. Ganza

Field Summary
static intAUDIO_S16
static intAUDIO_S16LSB
static intAUDIO_S16MSB
static intAUDIO_S16SYS
static intAUDIO_S8
static intAUDIO_U16
static intAUDIO_U16LSB
static intAUDIO_U16MSB
static intAUDIO_U16SYS
static intAUDIO_U8
Method Summary
static intallocateChannels(int count)
Set the number of channels being mixed.
static voidclose()
Shutdown and cleanup the mixer API.
static intexpireChannel(int channel, int ticks)
Halt channel playback, or all channels if -1 is passed in, after ticks milliseconds.
static intfadeInChannel(int channel, MixChunk chunk, int loops, int ms)
Play chunk on channel, or if channel is -1, pick the first free unreserved channel.
static intfadeInChannelTimed(int channel, MixChunk chunk, int loops, int ms, int ticks)
f the sample is long enough and has enough loops then the sample will stop after ticks milliseconds.
static voidfadeInMusic(MixMusic music, int loops, int ms)
Fade in over ms milliseconds of time, the loaded music, playing it loop times through from start to finish.
static voidfadeInMusicPos(MixMusic music, int loops, int ms, double position)
Fade in over ms milliseconds of time, the loaded music, playing it loop times through from start to finish.
static intfadeOutChannel(int channel, int ms)
Gradually fade out which channel over ms milliseconds starting from now.
static intfadeOutGroup(int tag, int ms)
Gradually fade out channels in group tag over ms milliseconds starting from now.
static voidfadeOutMusic(int ms)
Gradually fade out the music over ms milliseconds starting from now.
static Mix_FadingfadingChannel(int which)
Tells you if which channel is fading in, out, or not.
static Mix_FadingfadingMusic()
Tells you if music is fading in, out, or not at all.
static voidfreeChunk(MixChunk chunk)
Free the memory used in chunk, and free chunk itself as well.
static voidfreeMusic(MixMusic music)
Free the loaded music.
static MixChunkgetChunk(int channel)
Get the most recent sample chunk pointer played on channel.
static SDLVersiongetMixVersion()
get a version structure with the compile-time version of the SDL_mixer library.
static Mix_MusicTypegetMusicType(MixMusic music)
Tells you the file format encoding of the music.
static intgroupAvailable(int tag)
Find the first available (not playing) channel in group tag.
static voidgroupChannel(int which, int tag)
Add which channel to group tag, or reset it's group to the default group tag (-1).
static intgroupChannels(int from, int to, int tag)
Add channels starting at from up through to to group tag, or reset it's group to the default group tag (-1).
static intgroupCount(int tag)
Count the number of channels in group tag.
static intgroupNewer(int tag)
Find the newest, most recently started, actively playing channel in group tag.
static intgroupOldest(int tag)
Find the oldest actively playing channel in group tag.
static voidhaltChannel(int channel)
Halt channel playback, or all channels if -1 is passed in.
static voidhaltGroup(int tag)
Halt playback on all channels in group tag.
static voidhaltMusic()
Halt playback of music.
static MixMusicloadMUS(String path)
Load music file to use.
static MixMusicloadMUS(ByteBuffer buf)
Load music file to use.
static MixMusicloadMUS(byte[] data)
Load music file to use.
static MixMusicloadMUS(URL url)
Load music file to use.
static MixMusicloadMUS(InputStream in)
Load music file to use.
static MixChunkloadWAV(String path)
Load file for use as a sample.
static MixChunkloadWAV(Buffer buf)
Load file for use as a sample.
static MixChunkloadWAV(byte[] data)
Load file for use as a sample.
static MixChunkloadWAV(URL url)
Load file for use as a sample.
static MixChunkloadWAV(InputStream in)
Load file for use as a sample.
static voidopenAudio(int frequency, int format, int channels, int chunksize)
Initialize the mixer API.
static voidpause(int channel)
Pause channel, or all playing channels if -1 is passed in.
static intpaused(int channel)
Tells you if channel is paused, or not.
static booleanpausedMusic()
Tells you if music is paused, or not.
static voidpauseMusic()
Pause the music playback.
static intplayChannel(int channel, MixChunk chunk, int loops)
Play chunk on channel, or if channel is -1, pick the first free unreserved channel.
static intplayChannelTimed(int channel, MixChunk chunk, int loops, int ticks)
If the sample is long enough and has enough loops then the sample will stop after ticks milliseconds.
static intplaying(int channel)
Tells you if channel is playing, or not.
static booleanplayingMusic()
Tells you if music is actively playing, or not.
static voidplayMusic(MixMusic music, int loops)
Play the loaded music loop times through from start to finish.
static MixerSpecquerySpec()
Get the actual audio format in use by the opened audio device.
static intreserveChannels(int num)
Reserve num channels from being used when playing samples when passing in -1 as a channel number to playback functions.
static voidresume(int channel)
Unpause channel, or all playing and paused channels if -1 is passed in.
static voidresumeMusic()
Unpause the music.
static voidrewindMusic()
Rewind the music to the start.
static voidsetDistance(int channel, int distance)
This effect simulates a simple attenuation of volume due to distance.
static booleansetMusicPosition(double position)
Set the position of the currently playing music.
static voidsetPanning(int channel, int left, int right)
This effect will only work on stereo audio.
static voidsetPosition(int channel, int angle, int distance)
This effect emulates a simple 3D audio effect.
static intvolume(int channel, int volume)
Set the volume for any allocated channel.
static intvolumeChunk(MixChunk chunk, int volume)
Set chunk->volume to volume.
static intvolumeMusic(int volume)
Set the volume to volume, if it is 0 or greater, and return the previous volume setting.

Field Detail

AUDIO_S16

public static final int AUDIO_S16

AUDIO_S16LSB

public static final int AUDIO_S16LSB

AUDIO_S16MSB

public static final int AUDIO_S16MSB

AUDIO_S16SYS

public static final int AUDIO_S16SYS

AUDIO_S8

public static final int AUDIO_S8

AUDIO_U16

public static final int AUDIO_U16

AUDIO_U16LSB

public static final int AUDIO_U16LSB

AUDIO_U16MSB

public static final int AUDIO_U16MSB

AUDIO_U16SYS

public static final int AUDIO_U16SYS

AUDIO_U8

public static final int AUDIO_U8

Method Detail

allocateChannels

public static int allocateChannels(int count)
Set the number of channels being mixed. This can be called multiple times, even with sounds playing. If numchans is less than the current number of channels, then the higher channels will be stopped, freed, and therefore not mixed any longer. It's probably not a good idea to change the size 1000 times a second though. If any channels are deallocated, any callback set by Mix_ChannelFinished will be called when each channel is halted to be freed. Note: passing in zero WILL free all mixing channels, however music will still play.

Never fails...but a high number of channels can segfault if you run out of memory. We're talking REALLY high!

Parameters: count Number of channels to allocate for mixing. A negative number will not do anything, it will tell you how many channels are currently allocated.

Returns: The number of channels allocated.

Throws: SDLException if an error occurs

close

public static void close()
Shutdown and cleanup the mixer API. After calling this all audio is stopped, the device is closed, and the SDL_mixer functions should not be used. You may, of course, use Mix_OpenAudio to start the functionality again. Note: This function doesn't do anything until you have called it the same number of times that you called Mix_OpenAudio. You may use Mix_QuerySpec to find out how many times Mix_CloseAudio needs to be called before the device is actually closed.

Throws: SDLException if an error occurs

expireChannel

public static int expireChannel(int channel, int ticks)
Halt channel playback, or all channels if -1 is passed in, after ticks milliseconds. Any callback set by Mix_ChannelFinished will be called when the channel expires.

Parameters: channel Channel to stop playing, or -1 for all channels. ticks Millisecons until channel(s) halt playback.

Returns: Number of channels set to expire. Whether or not they are active.

Throws: SDLException if an error occurs

fadeInChannel

public static int fadeInChannel(int channel, MixChunk chunk, int loops, int ms)
Play chunk on channel, or if channel is -1, pick the first free unreserved channel. The channel volume starts at 0 and fades up to full volume over ms milliseconds of time. The sample may end before the fade-in is complete if it is too short or doesn't have enough loops. The sample will play for loops+1 number of times, unless stopped by halt, or fade out, or setting a new expiration time of less time than it would have originally taken to play the loops, or closing the mixer.

Note: this just calls Mix_FadeInChannelTimed() with ticks set to -1.

Parameters: channel Channel to play on, or -1 for the first free unreserved channel. chunk Sample to play loops Number of loops, -1 is infinite loops. Passing one here plays the sample twice (1 loop). ms Milliseconds of time that the fade-in effect should take to go from silence to full volume.

Returns: the channel the sample is played on

Throws: SDLException if an error occurs

fadeInChannelTimed

public static int fadeInChannelTimed(int channel, MixChunk chunk, int loops, int ms, int ticks)
f the sample is long enough and has enough loops then the sample will stop after ticks milliseconds. Otherwise this function is the same as Mix_FadeInChannel.

Parameters: channel Channel to play on, or -1 for the first free unreserved channel. chunk Sample to play loops Number of loops, -1 is infinite loops. Passing one here plays the sample twice (1 loop). ms Milliseconds of time that the fade-in effect should take to go from silence to full volume. ticks Millisecond limit to play sample, at most. If not enough loops or the sample chunk is not long enough, then the sample may stop before this timeout occurs. -1 means play forever.

Returns: the channel the sample is played on

Throws: SDLException if an error occurs

fadeInMusic

public static void fadeInMusic(MixMusic music, int loops, int ms)
Fade in over ms milliseconds of time, the loaded music, playing it loop times through from start to finish. The fade in effect only applies to the first loop. Any previous music will be halted, or if it is fading out it will wait (blocking) for the fade to complete. This function is the same as Mix_FadeInMusicPos(music, loops, ms, 0).

Parameters: music Music to play loops number of times to play through the music. 0 plays the music zero times... -1 plays the music forever (or as close as it can get to that) ms Milliseconds for the fade-in effect to complete.

Throws: SDLException if an error occurs

fadeInMusicPos

public static void fadeInMusicPos(MixMusic music, int loops, int ms, double position)
Fade in over ms milliseconds of time, the loaded music, playing it loop times through from start to finish. The fade in effect only applies to the first loop. The first time the music is played, it posistion will be set to posistion, which means different things for different types of music files, see Mix_SetMusicPosition for more info on that. Any previous music will be halted, or if it is fading out it will wait (blocking) for the fade to complete

Parameters: music Music to play loops number of times to play through the music. 0 plays the music zero times... -1 plays the music forever (or as close as it can get to that) ms Milliseconds for the fade-in effect to complete. position Posistion to play from, see setMusicPosition for meaning.

Throws: SDLException if an error occurs

fadeOutChannel

public static int fadeOutChannel(int channel, int ms)
Gradually fade out which channel over ms milliseconds starting from now. The channel will be halted after the fade out is completed. Only channels that are playing are set to fade out, including paused channels.

Any callback set by Mix_ChannelFinished will be called when the channel finishes fading out.

Parameters: channel Channel to fade out, or -1 to fade all channels out. ms Milliseconds of time that the fade-out effect should take to go to silence, starting now.

Returns: The number of channels set to fade out.

Throws: SDLException if an error occurs

fadeOutGroup

public static int fadeOutGroup(int tag, int ms)
Gradually fade out channels in group tag over ms milliseconds starting from now. The channels will be halted after the fade out is completed. Only channels that are playing are set to fade out, including paused channels. Any callback set by Mix_ChannelFinished will be called when each channel finishes fading out.

Parameters: tag Group to fade out. NOTE: -1 will NOT fade all channels out. Use Mix_FadeOutChannel(-1) for that instead. ms Milliseconds of time that the fade-out effect should take to go to silence, starting now.

Returns: The number of channels set to fade out.

Throws: SDLException if an error occurs

fadeOutMusic

public static void fadeOutMusic(int ms)
Gradually fade out the music over ms milliseconds starting from now. The music will be halted after the fade out is completed. Only when music is playing and not fading already are set to fade out, including paused channels. Any callback set by Mix_HookMusicFinished will be called when the music finishes fading out.

Parameters: ms Milliseconds of time that the fade-out effect should take to go to silence, starting now.

Throws: SDLException if an error occurs

fadingChannel

public static Mix_Fading fadingChannel(int which)
Tells you if which channel is fading in, out, or not. Does not tell you if the channel is playing anything, or paused, so you'd need to test that separately.

Parameters: which Channel to get the fade activity status from.

Returns: the fading status

Throws: SDLException if an error occurs

fadingMusic

public static Mix_Fading fadingMusic()
Tells you if music is fading in, out, or not at all. Does not tell you if the channel is playing anything, or paused, so you'd need to test that separately.

Returns: a Mix_Fading value

freeChunk

public static void freeChunk(MixChunk chunk)
Free the memory used in chunk, and free chunk itself as well. Do not use chunk after this without loading a new sample to it. Note: It's a bad idea to free a chunk that is still being played...

Parameters: chunk a MixChunk value

Throws: SDLException if an error occurs

freeMusic

public static void freeMusic(MixMusic music)
Free the loaded music. If music is playing it will be halted. If music is fading out, then this function will wait (blocking) until the fade out is complete.

Parameters: music a MixMusic value

Throws: SDLException if an error occurs

getChunk

public static MixChunk getChunk(int channel)
Get the most recent sample chunk pointer played on channel. This pointer may be currently playing, or just the last used.

Note: The actual chunk may have been freed, so this may not be valid anymore.

Parameters: channel Channel to get the current Mix_Chunk playing. -1 is not valid

Returns: a MixChunk value

Throws: SDLException if an error occurs

getMixVersion

public static SDLVersion getMixVersion()
get a version structure with the compile-time version of the SDL_mixer library.

Returns: the compile-time version of the SDL_mixer library.

getMusicType

public static Mix_MusicType getMusicType(MixMusic music)
Tells you the file format encoding of the music. This may be handy when used with Mix_SetMusicPosition, and other music functions that vary based on the type of music being played. If you want to know the type of music currently being played, pass in NULL to music.

Parameters: music The music to get the type of. NULL will get the currently playing music type.

Returns: The type of music or if music is NULL then the currently playing music type, otherwise MUS_NONE if no music is playing

Throws: SDLException if an error occurs

groupAvailable

public static int groupAvailable(int tag)
Find the first available (not playing) channel in group tag.

Parameters: tag A group number Any positive numbers (including zero). -1 will search ALL channels.

Returns: The channel found on success. -1 is returned when no channels in the group are available.

Throws: SDLException if an error occurs

groupChannel

public static void groupChannel(int which, int tag)
Add which channel to group tag, or reset it's group to the default group tag (-1).

Parameters: which Channel number of channels to assign tag to. tag A group number Any positive numbers (including zero). -1 is the default group. Use -1 to remove a group tag essentially.

Throws: SDLException if an error occurs

groupChannels

public static int groupChannels(int from, int to, int tag)
Add channels starting at from up through to to group tag, or reset it's group to the default group tag (-1).

Parameters: from First Channel number of channels to assign tag to. Must be less or equal to to. to Last Channel number of channels to assign tag to. Must be greater or equal to from. tag A group number. Any positive numbers (including zero). -1 is the default group. Use -1 to remove a group tag essentially.

Returns: The number of tagged channels on success. If that number is less than to-from+1 then some channels were no tagged because they didn't exist.

groupCount

public static int groupCount(int tag)
Count the number of channels in group tag.

Parameters: tag A group number Any positive numbers (including zero). -1 will count ALL channels.

Returns: The number of channels found in the group. This function never fails.

Throws: SDLException if an error occurs

groupNewer

public static int groupNewer(int tag)
Find the newest, most recently started, actively playing channel in group tag.

Parameters: tag A group number Any positive numbers (including zero). -1 will search ALL channels.

Returns: The channel found on success. -1 is returned when no channels in the group are playing or the group is empty.

Throws: SDLException if an error occurs

groupOldest

public static int groupOldest(int tag)
Find the oldest actively playing channel in group tag.

Parameters: tag A group number Any positive numbers (including zero). -1 will search ALL channels.

Returns: The channel found on success. -1 is returned when no channels in the group are playing or the group is empty

Throws: SDLException if an error occurs

haltChannel

public static void haltChannel(int channel)
Halt channel playback, or all channels if -1 is passed in. Any callback set by Mix_ChannelFinished will be called.

Parameters: channel Channel to stop playing, or -1 for all channels.

Throws: SDLException if an error occurs

haltGroup

public static void haltGroup(int tag)
Halt playback on all channels in group tag. Any callback set by Mix_ChannelFinished will be called once for each channel that stops.

Parameters: tag Group to fade out. NOTE: -1 will NOT halt all channels. Use Mix_HaltChannel(-1) for that instead.

Throws: SDLException if an error occurs

haltMusic

public static void haltMusic()
Halt playback of music. This interrupts music fader effects. Any callback set by Mix_HookMusicFinished will be called when the music stops.

Throws: SDLException if an error occurs

loadMUS

public static MixMusic loadMUS(String path)
Load music file to use. This can load WAVE, MOD, MIDI, OGG, MP3, and any file that you use a command to play with. If you are using an external command to play the music, you must call Mix_SetMusicCMD before this, otherwise the internal players will be used. Alternatively, if you have set an external command up and don't want to use it, you must call Mix_SetMusicCMD(NULL) to use the built-in players again.

Parameters: path The path to the music file

Returns: A MixMusic instance

Throws: SDLException if an error occurs

loadMUS

public static MixMusic loadMUS(ByteBuffer buf)
Load music file to use. This can load WAVE, MOD, MIDI, OGG, MP3, and any file that you use a command to play with. If you are using an external command to play the music, you must call Mix_SetMusicCMD before this, otherwise the internal players will be used. Alternatively, if you have set an external command up and don't want to use it, you must call Mix_SetMusicCMD(NULL) to use the built-in players again.

Parameters: buf a DIRECT Buffer value

Returns: A MixMusic instance

Throws: SDLException if an error occurs

loadMUS

public static MixMusic loadMUS(byte[] data)
Load music file to use. This can load WAVE, MOD, MIDI, OGG, MP3, and any file that you use a command to play with. If you are using an external command to play the music, you must call Mix_SetMusicCMD before this, otherwise the internal players will be used. Alternatively, if you have set an external command up and don't want to use it, you must call Mix_SetMusicCMD(NULL) to use the built-in players again.

Parameters: data a byte[] value

Returns: A MixMusic instance

Throws: SDLException if an error occurs

This method automatically creates the NIO Direct Buffer from the given byte array

loadMUS

public static MixMusic loadMUS(URL url)
Load music file to use. This can load WAVE, MOD, MIDI, OGG, MP3, and any file that you use a command to play with. If you are using an external command to play the music, you must call Mix_SetMusicCMD before this, otherwise the internal players will be used. Alternatively, if you have set an external command up and don't want to use it, you must call Mix_SetMusicCMD(NULL) to use the built-in players again.

Parameters: url an URL value

Returns: A MixMusic instance

Throws: SDLException if an error occurs IOException if an error occurs MalformedURLException if an error occurs

This method automatically creates the NIO Direct Buffer from the given byte array

NOTE: for now this method downloads the url and saves the data in a temporary file then invokes the standard loadMUS(String path) method to load it, deleting the file afterwards. Once we move to Mixer 1.2.6 this will not longer be necessary.

loadMUS

public static MixMusic loadMUS(InputStream in)
Load music file to use. This can load WAVE, MOD, MIDI, OGG, MP3, and any file that you use a command to play with. If you are using an external command to play the music, you must call Mix_SetMusicCMD before this, otherwise the internal players will be used. Alternatively, if you have set an external command up and don't want to use it, you must call Mix_SetMusicCMD(NULL) to use the built-in players again.

Parameters: in an InputStream value

Returns: A MixMusic instance

Throws: SDLException if an error occurs IOException if an error occurs

This method automatically creates the NIO Direct Buffer

loadWAV

public static MixChunk loadWAV(String path)
Load file for use as a sample. This can load WAVE, AIFF, RIFF, OGG, and VOC files. Note: You must call SDL_OpenAudio before this. It must know the output characteristics so it can convert the sample for playback, it does this conversion at load time.

Parameters: The path to the file to load

Returns: The MixChunk

Throws: SDLException if an error occurs

loadWAV

public static MixChunk loadWAV(Buffer buf)
Load file for use as a sample. This can load WAVE, AIFF, RIFF, OGG, and VOC files. Note: You must call SDL_OpenAudio before this. It must know the output characteristics so it can convert the sample for playback, it does this conversion at load time.

Parameters: buf a DIRECT Buffer with the Sample data

Returns: The MixChunk

Throws: SDLException if an error occurs

loadWAV

public static MixChunk loadWAV(byte[] data)
Load file for use as a sample. This can load WAVE, AIFF, RIFF, OGG, and VOC files. Note: You must call SDL_OpenAudio before this. It must know the output characteristics so it can convert the sample for playback, it does this conversion at load time.

This method automatically creates the NIO Direct Buffer from the given byte array

Parameters: data a byte[] value

Returns: The MixChunk

Throws: SDLException if an error occurs

loadWAV

public static MixChunk loadWAV(URL url)
Load file for use as a sample. This can load WAVE, AIFF, RIFF, OGG, and VOC files. Note: You must call SDL_OpenAudio before this. It must know the output characteristics so it can convert the sample for playback, it does this conversion at load time.

This method automatically creates the NIO Direct Buffer from the given byte array

Parameters: url The URL to fetch the data from

Returns: The MixChunk

Throws: SDLException if an error occurs

loadWAV

public static MixChunk loadWAV(InputStream in)
Load file for use as a sample. This can load WAVE, AIFF, RIFF, OGG, and VOC files. Note: You must call SDL_OpenAudio before this. It must know the output characteristics so it can convert the sample for playback, it does this conversion at load time.

This method automatically creates the NIO Direct Buffer

Parameters: url The URL to fetch the data from

Returns: The MixChunk

Throws: SDLException if an error occurs

openAudio

public static void openAudio(int frequency, int format, int channels, int chunksize)
Initialize the mixer API.

This must be called before using other functions in this library. SDL must be initialized with SDL_INIT_AUDIO before this call. frequency would be 44100 for 44.1KHz, which is CD audio rate. Most games use 22050, because 44100 requires too much CPU power on older computers. chunksize is the size of each mixed sample. The smaller this is the more your hooks will be called. If make this too small on a slow system, sound may skip. If made to large, sound effects will lag behind the action more. You want a happy medium for your target computer. You also may make this 4096, or larger, if you are just playing music. MIX_CHANNELS(8) mixing channels will be allocated by default. You may call this function multiple times, however you will have to call Mix_CloseAudio just as many times for the device to actually close. The format will not changed on subsequent calls. So you will have to close all the way before trying to open with different format parameters. format is based on SDL audio support, see SDL_audio.h. Here are the values listed there:

MIX_DEFAULT_FORMAT is the same as AUDIO_S16SYS.

Parameters: frequency Output sampling frequency in samples per second (Hz). format Output sample format. channels Number of sound channels in output. Set to 2 for stereo, 1 for mono. This has nothing to do with mixing channels. chunksize Bytes used per output sample.

Throws: SDLException if an error occurs

pause

public static void pause(int channel)
Pause channel, or all playing channels if -1 is passed in. You may still halt a paused channel.

Note: Only channels which are actively playing will be paused.

Parameters: channel Channel to pause playing, or -1 for all channels.

Throws: SDLException if an error occurs

paused

public static int paused(int channel)
Tells you if channel is paused, or not.

Note: Does not check if the channel has been halted after it was paused, which may seem a little weird.

Parameters: channel Channel to test whether it is paused or not. -1 will tell you how many channels are paused.

Returns: Zero if the channel is not paused. Otherwise if you passed in -1, the number of paused channels is returned. If you passed in a specific channel, then 1 is returned if it is paused.

Throws: SDLException if an error occurs

pausedMusic

public static boolean pausedMusic()
Tells you if music is paused, or not.

Note: Does not check if the music was been halted after it was paused, which may seem a little weird.

Returns: if music is paused

pauseMusic

public static void pauseMusic()
Pause the music playback. You may halt paused music.

Note: Music can only be paused if it is actively playing.

playChannel

public static int playChannel(int channel, MixChunk chunk, int loops)
Play chunk on channel, or if channel is -1, pick the first free unreserved channel. The sample will play for loops+1 number of times, unless stopped by halt, or fade out, or setting a new expiration time of less time than it would have originally taken to play the loops, or closing the mixer.

Note: this just calls Mix_PlayChannelTimed() with ticks set to -1.

Parameters: channel Channel to play on, or -1 for the first free unreserved channel. chunk Sample to play loops Number of loops, -1 is infinite loops. Passing one here plays the sample twice (1 loop).

Returns: the channel the sample is played on

Throws: SDLException if an error occurs

playChannelTimed

public static int playChannelTimed(int channel, MixChunk chunk, int loops, int ticks)
If the sample is long enough and has enough loops then the sample will stop after ticks milliseconds. Otherwise this function is the same as playChannel.

Parameters: channel Channel to play on, or -1 for the first free unreserved channel. chunk Sample to play loops Number of loops, -1 is infinite loops. Passing one here plays the sample twice (1 loop). ticks Millisecond limit to play sample, at most. If not enough loops or the sample chunk is not long enough, then the sample may stop before this timeout occurs. -1 means play forever.

Returns: the channel the sample is played on

Throws: SDLException if an error occurs

playing

public static int playing(int channel)
Tells you if channel is playing, or not. Note: Does not check if the channel has been paused.

Parameters: channel Channel to test whether it is playing or not. -1 will tell you how many channels are playing.

Returns: Zero if the channel is not playing. Otherwise if you passed in -1, the number of channels playing is returned. If you passed in a specific channel, then 1 is returned if it is playing

Throws: SDLException if an error occurs

playingMusic

public static boolean playingMusic()
Tells you if music is actively playing, or not.

Note: Does not check if the channel has been paused.

Returns: if music is actively playing

playMusic

public static void playMusic(MixMusic music, int loops)
Play the loaded music loop times through from start to finish. The previous music will be halted, or if fading out it waits (blocking) for that to finish.

Parameters: music Music to play loops number of times to play through the music. 0 plays the music zero times... -1 plays the music forever (or as close as it can get to that)

Throws: SDLException if an error occurs

querySpec

public static MixerSpec querySpec()
Get the actual audio format in use by the opened audio device. This may or may not match the parameters you passed to Mix_OpenAudio.

Returns: The current audio settings

Throws: SDLException if an error occurs

reserveChannels

public static int reserveChannels(int num)
Reserve num channels from being used when playing samples when passing in -1 as a channel number to playback functions. The channels are reserved starting from channel 0 to num-1. Passing in zero will unreserve all channels. Normally SDL_mixer starts without any channels reserved.

The following functions are affected by this setting:

Mix_PlayChannel

Mix_PlayChannelTimed

Mix_FadeInChannel

Mix_FadeInChannelTimed

Parameters: num Number of channels to reserve from default mixing. Zero removes all reservations.

Returns: The number of channels reserved. Never fails, but may return less channels than you ask for, depending on the number of channels previously allocated.

Throws: SDLException if an error occurs

resume

public static void resume(int channel)
Unpause channel, or all playing and paused channels if -1 is passed in.

Parameters: channel Channel to resume playing, or -1 for all channels.

Throws: SDLException if an error occurs

resumeMusic

public static void resumeMusic()
Unpause the music. This is safe to use on halted, paused, and already playing music.

rewindMusic

public static void rewindMusic()
Rewind the music to the start. This is safe to use on halted, paused, and already playing music. It is not useful to rewind the music immediately after starting playback, because it starts at the beginning by default.

This function only works for these streams: MOD, OGG, MP3, Native MIDI.

setDistance

public static void setDistance(int channel, int distance)
This effect simulates a simple attenuation of volume due to distance. The volume never quite reaches silence, even at max distance.

NOTE: Using a distance of 0 will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel.

Parameters: channel Channel number to register this effect on. Use MIX_CHANNEL_POST to process the postmix stream. distance Specify the distance from the listener, from 0(close/loud) to 255(far/quiet).

Throws: SDLException if an error occurs

setMusicPosition

public static boolean setMusicPosition(double position)
Set the position of the currently playing music. The position takes different meanings for different music sources. It only works on the music sources listed below.

Parameters: position Position to play from

Returns: true on success, -1 if the codec doesn't support this function

Throws: SDLException if an error occurs

setPanning

public static void setPanning(int channel, int left, int right)
This effect will only work on stereo audio. Meaning you called Mix_OpenAudio with 2 channels (MIX_DEFAULT_CHANNELS). The easiest way to do true panning is to call Mix_SetPanning(channel, left, 254 - left); so that the total volume is correct, if you consider the maximum volume to be 127 per channel for center, or 254 max for left, this works, but about halves the effective volume. This Function registers the effect for you, so don't try to Mix_RegisterEffect it yourself.

NOTE: Setting both left and right to 255 will unregister the effect from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel. NOTE: Using this function on a mono audio device will not register the effect, nor will it return an error status.

Parameters: channel Channel number to register this effect on. Use MIX_CHANNEL_POST to process the postmix stream. left Volume for the left channel, range is 0(silence) to 255(loud) right Volume for the left channel, range is 0(silence) to 255(loud)

Throws: SDLException if an error occurs

setPosition

public static void setPosition(int channel, int angle, int distance)
This effect emulates a simple 3D audio effect. It's not all that realistic, but it can help improve some level of realism. By giving it the angle and distance from the camera's point of view, the effect pans and attenuates volumes. If you are looking for better positional audio, using OpenAL is suggested.

NOTE: Using angle and distance of 0, will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel.

Parameters: channel Channel number to register this effect on. Use MIX_CHANNEL_POST to process the postmix stream. angle Direction in relation to forward from 0 to 360 degrees. Larger angles will be reduced to this range using angles % 360.
0 = directly in front.
90 = directly to the right.
180 = directly behind.
270 = directly to the left.

So you can see it goes clockwise starting at directly in front. This ends up being similar in effect to Mix_SetPanning. distance The distance from the listener, from 0(near/loud) to 255(far/quiet). This is the same as the Mix_SetDistance effect.

Throws: SDLException if an error occurs

volume

public static int volume(int channel, int volume)
Set the volume for any allocated channel. If channel is -1 then all channels at are set at once. The volume is applied during the final mix, along with the sample volume. So setting this volume to 64 will halve the output of all samples played on the specified channel. All channels default to a volume of 128, which is the max. Newly allocated channels will have the max volume set, so setting all channels volumes does not affect subsequent channel allocations.

Parameters: Channel to set mix volume for. -1 will set the volume for all allocated channels. volume The volume to use from 0 to MIX_MAX_VOLUME(128). If greater than MIX_MAX_VOLUME, then it will be set to MIX_MAX_VOLUME. If less than 0 then the volume will not be set.

Returns: current volume of the channel. If channel is -1, the average volume is returned.

Throws: SDLException if an error occurs

volumeChunk

public static int volumeChunk(MixChunk chunk, int volume)
Set chunk->volume to volume. The volume setting will take effect when the chunk is used on a channel, being mixed into the output.

Parameters: The chunk to set the volume in The volume to use from 0 to MIX_MAX_VOLUME(128). If greater than MIX_MAX_VOLUME, then it will be set to MIX_MAX_VOLUME. If less than 0 then chunk->volume will not be set.

Returns: previous chunk->volume setting. if you passed a negative value for volume then this volume is still the current volume for the chunk

Throws: SDLException if an error occurs

volumeMusic

public static int volumeMusic(int volume)
Set the volume to volume, if it is 0 or greater, and return the previous volume setting. Setting the volume during a fade will not work, the faders use this function to perform their effect! Setting volume while using an external music player set by Mix_SetMusicCMD will have no effect, and Mix_GetError will show the reason why not.

Parameters: volume Music volume, from 0 to MIX_MAX_VOLUME(128). Values greater than MIX_MAX_VOLUME will use MIX_MAX_VOLUME. -1 does not set the volume, but does return the current volume setting.

Returns: The previous volume setting.

Throws: SDLException if an error occurs