sdljava.mixer
Class SDLMixer

java.lang.Object
  extended by sdljava.mixer.SDLMixer

public class SDLMixer
extends java.lang.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 int AUDIO_S16
           
static int AUDIO_S16LSB
           
static int AUDIO_S16MSB
           
static int AUDIO_S16SYS
           
static int AUDIO_S8
           
static int AUDIO_U16
           
static int AUDIO_U16LSB
           
static int AUDIO_U16MSB
           
static int AUDIO_U16SYS
           
static int AUDIO_U8
           
 
Constructor Summary
SDLMixer()
           
 
Method Summary
static int allocateChannels(int count)
          Set the number of channels being mixed.
static void close()
          Shutdown and cleanup the mixer API.
static int expireChannel(int channel, int ticks)
          Halt channel playback, or all channels if -1 is passed in, after ticks milliseconds.
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.
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.
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.
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.
static int fadeOutChannel(int channel, int ms)
          Gradually fade out which channel over ms milliseconds starting from now.
static int fadeOutGroup(int tag, int ms)
          Gradually fade out channels in group tag over ms milliseconds starting from now.
static void fadeOutMusic(int ms)
          Gradually fade out the music over ms milliseconds starting from now.
static Mix_Fading fadingChannel(int which)
          Tells you if which channel is fading in, out, or not.
static Mix_Fading fadingMusic()
          Tells you if music is fading in, out, or not at all.
static void freeChunk(MixChunk chunk)
          Free the memory used in chunk, and free chunk itself as well.
static void freeMusic(MixMusic music)
          Free the loaded music.
static MixChunk getChunk(int channel)
          Get the most recent sample chunk pointer played on channel.
static SDLVersion getMixVersion()
          get a version structure with the compile-time version of the SDL_mixer library.
static Mix_MusicType getMusicType(MixMusic music)
          Tells you the file format encoding of the music.
static int groupAvailable(int tag)
          Find the first available (not playing) channel in group tag.
static void groupChannel(int which, int tag)
          Add which channel to group tag, or reset it's group to the default group tag (-1).
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).
static int groupCount(int tag)
          Count the number of channels in group tag.
static int groupNewer(int tag)
          Find the newest, most recently started, actively playing channel in group tag.
static int groupOldest(int tag)
          Find the oldest actively playing channel in group tag.
static void haltChannel(int channel)
          Halt channel playback, or all channels if -1 is passed in.
static void haltGroup(int tag)
          Halt playback on all channels in group tag.
static void haltMusic()
          Halt playback of music.
static MixMusic loadMUS(byte[] data)
          Load music file to use.
static MixMusic loadMUS(java.nio.ByteBuffer buf)
          Load music file to use.
static MixMusic loadMUS(java.io.InputStream in)
          Load music file to use.
static MixMusic loadMUS(java.lang.String path)
          Load music file to use.
static MixMusic loadMUS(java.net.URL url)
          Load music file to use.
static MixChunk loadWAV(java.nio.Buffer buf)
          Load file for use as a sample.
static MixChunk loadWAV(byte[] data)
          Load file for use as a sample.
static MixChunk loadWAV(java.io.InputStream in)
          Load file for use as a sample.
static MixChunk loadWAV(java.lang.String path)
          Load file for use as a sample.
static MixChunk loadWAV(java.net.URL url)
          Load file for use as a sample.
static void openAudio(int frequency, int format, int channels, int chunksize)
          Initialize the mixer API.
static void pause(int channel)
          Pause channel, or all playing channels if -1 is passed in.
static int paused(int channel)
          Tells you if channel is paused, or not.
static boolean pausedMusic()
          Tells you if music is paused, or not.
static void pauseMusic()
          Pause the music playback.
static int playChannel(int channel, MixChunk chunk, int loops)
          Play chunk on channel, or if channel is -1, pick the first free unreserved channel.
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.
static int playing(int channel)
          Tells you if channel is playing, or not.
static boolean playingMusic()
          Tells you if music is actively playing, or not.
static void playMusic(MixMusic music, int loops)
          Play the loaded music loop times through from start to finish.
static MixerSpec querySpec()
          Get the actual audio format in use by the opened audio device.
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.
static void resume(int channel)
          Unpause channel, or all playing and paused channels if -1 is passed in.
static void resumeMusic()
          Unpause the music.
static void rewindMusic()
          Rewind the music to the start.
static void setDistance(int channel, int distance)
          This effect simulates a simple attenuation of volume due to distance.
static boolean setMusicPosition(double position)
          Set the position of the currently playing music.
static void setPanning(int channel, int left, int right)
          This effect will only work on stereo audio.
static void setPosition(int channel, int angle, int distance)
          This effect emulates a simple 3D audio effect.
static int volume(int channel, int volume)
          Set the volume for any allocated channel.
static int volumeChunk(MixChunk chunk, int volume)
          Set chunk->volume to volume.
static int volumeMusic(int volume)
          Set the volume to volume, if it is 0 or greater, and return the previous volume setting.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

AUDIO_U8

public static final int AUDIO_U8
See Also:
Constant Field Values

AUDIO_S8

public static final int AUDIO_S8
See Also:
Constant Field Values

AUDIO_U16LSB

public static final int AUDIO_U16LSB
See Also:
Constant Field Values

AUDIO_S16LSB

public static final int AUDIO_S16LSB
See Also:
Constant Field Values

AUDIO_U16MSB

public static final int AUDIO_U16MSB
See Also:
Constant Field Values

AUDIO_S16MSB

public static final int AUDIO_S16MSB
See Also:
Constant Field Values

AUDIO_U16

public static final int AUDIO_U16
See Also:
Constant Field Values

AUDIO_S16

public static final int AUDIO_S16
See Also:
Constant Field Values

AUDIO_S16SYS

public static final int AUDIO_S16SYS
See Also:
Constant Field Values

AUDIO_U16SYS

public static final int AUDIO_U16SYS
See Also:
Constant Field Values
Constructor Detail

SDLMixer

public SDLMixer()
Method Detail

openAudio

public static void openAudio(int frequency,
                             int format,
                             int channels,
                             int chunksize)
                      throws SDLException
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

close

public static void close()
                  throws SDLException
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

querySpec

public static MixerSpec querySpec()
                           throws SDLException
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

loadWAV

public static MixChunk loadWAV(java.lang.String path)
                        throws SDLException
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(java.nio.Buffer buf)
                        throws SDLException
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)
                        throws SDLException
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(java.net.URL url)
                        throws SDLException,
                               java.io.IOException,
                               java.net.MalformedURLException
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
java.io.IOException
java.net.MalformedURLException

loadWAV

public static MixChunk loadWAV(java.io.InputStream in)
                        throws SDLException,
                               java.io.IOException
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
java.io.IOException

volumeChunk

public static int volumeChunk(MixChunk chunk,
                              int volume)
                       throws SDLException
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

freeChunk

public static void freeChunk(MixChunk chunk)
                      throws SDLException
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

allocateChannels

public static int allocateChannels(int count)
                            throws SDLException
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

volume

public static int volume(int channel,
                         int volume)
                  throws SDLException
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

playChannel

public static int playChannel(int channel,
                              MixChunk chunk,
                              int loops)
                       throws SDLException
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)
                            throws SDLException
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

fadeInChannel

public static int fadeInChannel(int channel,
                                MixChunk chunk,
                                int loops,
                                int ms)
                         throws SDLException
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)
                              throws SDLException
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

pause

public static void pause(int channel)
                  throws SDLException
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

resume

public static void resume(int channel)
                   throws SDLException
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

haltChannel

public static void haltChannel(int channel)
                        throws SDLException
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

expireChannel

public static int expireChannel(int channel,
                                int ticks)
                         throws SDLException
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

fadeOutChannel

public static int fadeOutChannel(int channel,
                                 int ms)
                          throws SDLException
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

playing

public static int playing(int channel)
                   throws SDLException
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

paused

public static int paused(int channel)
                  throws SDLException
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

fadingChannel

public static Mix_Fading fadingChannel(int which)
                                throws SDLException
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

getChunk

public static MixChunk getChunk(int channel)
                         throws SDLException
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

reserveChannels

public static int reserveChannels(int num)
                           throws SDLException
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

groupChannel

public static void groupChannel(int which,
                                int tag)
                         throws SDLException
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)
                      throws SDLException
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

groupAvailable

public static int groupAvailable(int tag)
                          throws SDLException
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

groupOldest

public static int groupOldest(int tag)
                       throws SDLException
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

groupNewer

public static int groupNewer(int tag)
                      throws SDLException
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

fadeOutGroup

public static int fadeOutGroup(int tag,
                               int ms)
                        throws SDLException
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

haltGroup

public static void haltGroup(int tag)
                      throws SDLException
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

loadMUS

public static MixMusic loadMUS(java.lang.String path)
                        throws SDLException
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(java.nio.ByteBuffer buf)
                        throws SDLException,
                               java.io.IOException
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
java.io.IOException

loadMUS

public static MixMusic loadMUS(byte[] data)
                        throws SDLException,
                               java.io.IOException
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

java.io.IOException

loadMUS

public static MixMusic loadMUS(java.net.URL url)
                        throws SDLException,
                               java.io.IOException,
                               java.net.MalformedURLException
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
java.io.IOException - if an error occurs
java.net.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(java.io.InputStream in)
                        throws SDLException,
                               java.io.IOException
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
java.io.IOException - if an error occurs

This method automatically creates the NIO Direct Buffer


freeMusic

public static void freeMusic(MixMusic music)
                      throws SDLException
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

playMusic

public static void playMusic(MixMusic music,
                             int loops)
                      throws SDLException
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

fadeInMusic

public static void fadeInMusic(MixMusic music,
                               int loops,
                               int ms)
                        throws SDLException
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)
                           throws SDLException
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

volumeMusic

public static int volumeMusic(int volume)
                       throws SDLException
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

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.


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.


setMusicPosition

public static boolean setMusicPosition(double position)
                                throws SDLException
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

haltMusic

public static void haltMusic()
                      throws SDLException
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

fadeOutMusic

public static void fadeOutMusic(int ms)
                         throws SDLException
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

getMusicType

public static Mix_MusicType getMusicType(MixMusic music)
                                  throws SDLException
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

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

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

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

setPanning

public static void setPanning(int channel,
                              int left,
                              int right)
                       throws SDLException
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

setDistance

public static void setDistance(int channel,
                               int distance)
                        throws SDLException
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

setPosition

public static void setPosition(int channel,
                               int angle,
                               int distance)
                        throws SDLException
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

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.