ch.aplu.util
Class SoundPlayer

java.lang.Object
  ch.aplu.util.SoundPlayer

Direct Known Subclasses:

SoundPlayerExt

public class SoundPlayer
extends java.lang.Object

Class for playing sound files using file streaming in a separate thread. Sound format supported: WAV, ALAW, ULAW For MP3 format, use class SoundPlayerExt.

See Also:

SoundPlayerExt

Constructor Summary

SoundPlayer(javax.sound.sampled.AudioInputStream audioInputStream)
Same as SoundPlayer(audioInputStream, mixerIndex) using the default sound device.

SoundPlayer(javax.sound.sampled.AudioInputStream audioInputStream, int mixerIndex)
Construct a sound player attached to the given AudioInputStream using the given mixer index (sound device).

SoundPlayer(byte[] ary, javax.sound.sampled.AudioFormat audioFormat)
Same as SoundPlayer(byte[] ary, AudioFormat audioFormat, int mixerIndex) using the default sound device.

SoundPlayer(byte[] ary, javax.sound.sampled.AudioFormat audioFormat, int mixerIndex)
Construct a sound player with data from the given byte array using the given mixer index (sound device).

SoundPlayer(java.io.ByteArrayOutputStream os, javax.sound.sampled.AudioFormat audioFormat)
Same as SoundPlayer(os, audioFormat, mixerIndex) using the default sound device.

SoundPlayer(java.io.ByteArrayOutputStream os, javax.sound.sampled.AudioFormat audioFormat, int mixerIndex)
Construct a sound player with data from the given ByteArrayOutputStream using the given mixer index (sound device).

SoundPlayer(java.io.File audioFile)
Same as SoundPlayer(audioFile, mixerIndex) using the default sound device.

SoundPlayer(java.io.File audioFile, int mixerIndex)
Construct a sound player attached to given File instance using the given mixer index (sound device).

SoundPlayer(int[] ary, javax.sound.sampled.AudioFormat audioFormat)
Same as SoundPlayer(int[] ary, AudioFormat audioFormat, int mixerIndex) using the default sound device.

SoundPlayer(int[] ary, javax.sound.sampled.AudioFormat audioFormat, int mixerIndex)
Construct a sound player with data from the given int array using the given mixer index (sound device).

SoundPlayer(java.lang.Object resourceObj, java.lang.String audioPathname)
Same as SoundPlayer(obj, audioPathname, mixerIndex) using the default sound device.

SoundPlayer(java.lang.Object resourceObj, java.lang.String audioPathname, int mixerIndex)
Construct a sound player attached to given pathname from a JAR archive using the given mixer index (sound device).

SoundPlayer(java.lang.String audioPathname)
Same as SoundPlayer(audioPathname, mixerIndex) using the default sound device.

SoundPlayer(java.lang.String audioPathname, int mixerIndex)
Construct a sound player attached to given pathname (relative or fully qualified) using the given mixer index (sound device).

SoundPlayer(java.net.URL url)
Same as SoundPlayer(url, mixerIndex) using the default sound device.

SoundPlayer(java.net.URL url, int mixerIndex)
Construct a sound player attached to given URL using the given mixer index (sound device).

Method Summary

void	addSoundConverter(SoundConverter soundConverter) Registers a sound converter.
void	addSoundPlayerListener(SoundPlayerListener listener) Register a SoundPlayerListener to get notifications from the SoundPlayer.
void	advanceFrames(long nbFrames) Advance current position (number of frames).
void	advanceTime(double time) Advance current time (in ms).
void	blockingPlay() Start playing and block until the sound file is completely played.
static void	delay(long time) Suspend thread execution for the given amount of time (in ms).
static java.lang.String[]	getAvailableMixers() Return a list of the names of available mixers (sound devices).
long	getCurrentPos() Return the current position (in frames from beginning).
double	getCurrentTime() Return the current time (in ms from beginning).
javax.sound.sampled.AudioFormat	getFormat() Return AudioFormat of player's (decoded) resource.
float	getFrameRate() Return frame rate (number of frames per seconds) of player's (decoded) resource.
int	getFrameSize() Return frame size (nb of bytes per sound sample) of player's (decoded) resource.
int	getMixerIndex()
static int[]	getMono(javax.sound.sampled.AudioInputStream ais) Return the sound data of the given AudioInputStream in a integer array.
static int[]	getStereo(javax.sound.sampled.AudioInputStream ais) Return the sound data in given AudioInputStream in a integer array.
int	getVolume() Return the current volume (range 0..1000).
static java.lang.String	getWavInfo(java.lang.String filename) Return the audio file format information.
static int[]	getWavMono(java.lang.String filename) Return the sound data of the given WAV file in a integer array.
static byte[]	getWavRaw(java.lang.String filename) Return the raw byte data of the give WAV file.
static int[]	getWavStereo(java.lang.String filename) Return the sound data of the given WAV file in a integer array.
boolean	isPlaying() Return true, if playing (and not pausing), otherwise false.
void	mute(boolean isMuting) If isMuting is true, set sound level to mimimum; otherwise reset it to the old value.
void	pause() Stop playing momentarily.
int	play() Start or resume playing and return immediately.
void	playLoop() Start a loop playing mode, e.g. when the playing ends, it is restarted automatically until stop() is called.
void	replay() Wait until a playing underway has ended.
void	rewindFrames(long nbFrames) Rewind current position (number of frames).
void	rewindTime(double time) Rewind current time (in ms).
void	setVolume(int value) Set the volume to the give value (range 0..1000).
void	stop() Stop playing.
static java.net.URL	URLfromJAR(java.lang.String audioPath) Return the URL of a sound resource from the JAR archive.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SoundPlayer

public SoundPlayer(java.net.URL url,
                   int mixerIndex)

Construct a sound player attached to given URL using the given mixer index (sound device). To find the mixer indices of all installed sound devices call getAvailableMixers().
Normally an installed sound device has two entries, one for playing and one for recording. You must use the index for the playing device.

The given input stream is closed, when the playing ends, so playLoop() is not working. To load a resource from a jar file use
URL url = Thread.currentThread().getContextClassLoader().getResource("<relPath>");

or call URLfromJAR()

Throws:

java.lang.RuntimeException - if sound initialization fails

SoundPlayer

public SoundPlayer(java.net.URL url)

Same as SoundPlayer(url, mixerIndex) using the default sound device.

SoundPlayer

public SoundPlayer(java.lang.Object resourceObj,
                   java.lang.String audioPathname,
                   int mixerIndex)

Construct a sound player attached to given pathname from a JAR archive using the given mixer index (sound device). The class loader of the specified object is used.

Deprecated: Use SoundPlayer(url, mixerIndex) instead.

SoundPlayer

public SoundPlayer(java.lang.Object resourceObj,
                   java.lang.String audioPathname)

Same as SoundPlayer(obj, audioPathname, mixerIndex) using the default sound device.

Deprecated: Use SoundPlayer(url) instead.

SoundPlayer

public SoundPlayer(java.io.File audioFile,
                   int mixerIndex)

Construct a sound player attached to given File instance using the given mixer index (sound device). To find the mixer indices of all installed sound devices call getAvailableMixers().

Throws:

java.lang.RuntimeException - if sound initialization fails

SoundPlayer

public SoundPlayer(java.io.File audioFile)

Same as SoundPlayer(audioFile, mixerIndex) using the default sound device.

SoundPlayer

public SoundPlayer(java.lang.String audioPathname,
                   int mixerIndex)

Construct a sound player attached to given pathname (relative or fully qualified) using the given mixer index (sound device).
If the file is not found in the given audioPathname, it is searched in the JAR resource. If it is not found there, an _ is appended to audioPathname and the file is searched again in the JAR. To find the mixer indices of all installed sound devices call getAvailableMixers().

Throws:

java.lang.RuntimeException - if sound initialization fails

SoundPlayer

public SoundPlayer(java.lang.String audioPathname)

Same as SoundPlayer(audioPathname, mixerIndex) using the default sound device.

SoundPlayer

public SoundPlayer(javax.sound.sampled.AudioInputStream audioInputStream,
                   int mixerIndex)

Construct a sound player attached to the given AudioInputStream using the given mixer index (sound device). To find the mixer indices of all installed sound devices call getAvailableMixers().

Throws:

java.lang.RuntimeException - if sound initialization fails

SoundPlayer

public SoundPlayer(javax.sound.sampled.AudioInputStream audioInputStream)

Same as SoundPlayer(audioInputStream, mixerIndex) using the default sound device.

SoundPlayer

public SoundPlayer(java.io.ByteArrayOutputStream os,
                   javax.sound.sampled.AudioFormat audioFormat,
                   int mixerIndex)

Construct a sound player with data from the given ByteArrayOutputStream using the given mixer index (sound device). To find the mixer indices of all installed sound devices call getAvailableMixers().

Throws:

java.lang.RuntimeException - if sound initialization fails

SoundPlayer

public SoundPlayer(java.io.ByteArrayOutputStream os,
                   javax.sound.sampled.AudioFormat audioFormat)

Same as SoundPlayer(os, audioFormat, mixerIndex) using the default sound device.

SoundPlayer

public SoundPlayer(byte[] ary,
                   javax.sound.sampled.AudioFormat audioFormat,
                   int mixerIndex)

Construct a sound player with data from the given byte array using the given mixer index (sound device). To find the mixer indices of all installed sound devices, call getAvailableMixers().

Throws:

java.lang.RuntimeException - if sound initialization fails

SoundPlayer

public SoundPlayer(byte[] ary,
                   javax.sound.sampled.AudioFormat audioFormat)

Same as SoundPlayer(byte[] ary, AudioFormat audioFormat, int mixerIndex) using the default sound device.

SoundPlayer

public SoundPlayer(int[] ary,
                   javax.sound.sampled.AudioFormat audioFormat,
                   int mixerIndex)

Construct a sound player with data from the given int array using the given mixer index (sound device). To find the mixer indices of all installed sound devices, call getAvailableMixers(). The int samples are converted to 2 bytes data depending on big or little endian format.

Throws:

java.lang.RuntimeException - if sound initialization fails

SoundPlayer

public SoundPlayer(int[] ary,
                   javax.sound.sampled.AudioFormat audioFormat)

Same as SoundPlayer(int[] ary, AudioFormat audioFormat, int mixerIndex) using the default sound device.

Method Detail

addSoundPlayerListener

public void addSoundPlayerListener(SoundPlayerListener listener)

Register a SoundPlayerListener to get notifications from the SoundPlayer.

replay

public void replay()

Wait until a playing underway has ended. Then restart playing and return immediately.
When the playing is over, paused or stopped, notifySoundPlayerStateChange(int reason) is invoked.

play

public int play()

Start or resume playing and return immediately.
When the playing is over, paused or stopped, notifySoundPlayerStateChange(int reason) is invoked. Return values:
0: Successfully started
1: Successfully resumed
2: Playing underway. Nothing happens.

blockingPlay

public void blockingPlay()

Start playing and block until the sound file is completely played.

stop

public void stop()

Stop playing. If playing or pausing, play() will restart playing from the beginning. Block until all resources are released.

pause

public void pause()

Stop playing momentarily. If not playing nothing happens. play() must be called to resume playing.

isPlaying

public boolean isPlaying()

Return true, if playing (and not pausing), otherwise false. (In other words, if true, you should hear something).

getCurrentPos

public long getCurrentPos()

Return the current position (in frames from beginning).

getCurrentTime

public double getCurrentTime()

Return the current time (in ms from beginning).

getFormat

public javax.sound.sampled.AudioFormat getFormat()

Return AudioFormat of player's (decoded) resource. If playing MP3 files, the decoded format is AudioFormat.Encoding.PCM_SIGNED.

See Also:

AudioFormat

getFrameSize

public int getFrameSize()

Return frame size (nb of bytes per sound sample) of player's (decoded) resource.

getFrameRate

public float getFrameRate()

Return frame rate (number of frames per seconds) of player's (decoded) resource.

advanceFrames

public void advanceFrames(long nbFrames)

Advance current position (number of frames). If pausing, remain pausing at new position. If still stopped, advance start position. If advanced past end of resource, advance to end of resource. May be called before play() to start playing at given byte offset.

advanceTime

public void advanceTime(double time)

Advance current time (in ms). If pausing, remain pausing at new time. If still stopped, advance start time. If new time exceeds length of resource, advance to end of resource. May be called before play() to start playing at given time offset.

rewindFrames

public void rewindFrames(long nbFrames)

Rewind current position (number of frames). If pausing, remain pausing at new position. If stopped, rewind start position, if eventually advanced (never below 0). If given nbBytes is greater than current position, rewind to start of resource.

rewindTime

public void rewindTime(double time)

Rewind current time (in ms). If stopped, nothing happens. If pausing, remain pausing at new time. If stopped, rewind start time, if eventually advanced (never below 0). If given time is greater than current time, rewind to start of resource.

setVolume

public void setVolume(int value)

Set the volume to the give value (range 0..1000). May be called in any player's state. If the sound system has no support for volume control, nothing happens.

mute

public void mute(boolean isMuting)

If isMuting is true, set sound level to mimimum; otherwise reset it to the old value.

getVolume

public int getVolume()

Return the current volume (range 0..1000). If the sound system has no support for volume control, return -1.

getAvailableMixers

public static java.lang.String[] getAvailableMixers()

Return a list of the names of available mixers (sound devices). To select one of these mixers, use its index in this list when constructing the SoundPlayer instance.
Normally an installed sound device has two entries, one for playing and one for recording.

getMixerIndex

public int getMixerIndex()

addSoundConverter

public void addSoundConverter(SoundConverter soundConverter)

Registers a sound converter. See documentation for interface 'SoundConverter' for more information.

See Also:

SoundConverter

playLoop

public void playLoop()

Start a loop playing mode, e.g. when the playing ends, it is restarted automatically until stop() is called. If already playing in normal mode, the loop playing mode is activated; if already playing in loop playing mode, remains in this mode.

Does not work, if the player was created by specifing an input stream, because the stream is closed when the playing ends.

getWavRaw

public static byte[] getWavRaw(java.lang.String filename)

Return the raw byte data of the give WAV file.

getStereo

public static int[] getStereo(javax.sound.sampled.AudioInputStream ais)

Return the sound data in given AudioInputStream in a integer array. The following audio formats are supported: mono:
- 8bit signed, unsigned, 16bit signed
stereo:
- 8bit signed, unsigned, 16bit signed

Sample data is grouped in pairs: left channel, right channel. For mono WAV audio format, both channels contain the same data.
The values are in range -32768..37768 for 8 and 16 bit formats.

getWavStereo

public static int[] getWavStereo(java.lang.String filename)

Return the sound data of the given WAV file in a integer array. The following audio formats are supported: mono:
- 8bit signed, unsigned, 16bit signed
stereo:
- 8bit signed, unsigned, 16bit signed

Sample data is grouped in pairs: left channel, right channel. For mono WAV files, both channels contain the same data.
The values are in range -32768..37768 for 8 and 16 bit formats.

getMono

public static int[] getMono(javax.sound.sampled.AudioInputStream ais)

Return the sound data of the given AudioInputStream in a integer array. The following audio formats are supported: mono:
- 8bit signed, unsigned, 16bit signed
stereo:
- 8bit signed, unsigned, 16bit signed

For stereo WAV audio format, the left and right channel values are averaged.
The values are in range -32768..37768 for 8 and 16 bit formats.

getWavMono

public static int[] getWavMono(java.lang.String filename)

Return the sound data of the given WAV file in a integer array. The following audio formats are supported: mono:
- 8bit signed, unsigned, 16bit signed
stereo:
- 8bit signed, unsigned, 16bit signed

For stereo WAV files, the left and right channel values are averaged.
The values are in range -32768..37768 for 8 and 16 bit formats.

getWavInfo

public static java.lang.String getWavInfo(java.lang.String filename)

Return the audio file format information.

URLfromJAR

public static java.net.URL URLfromJAR(java.lang.String audioPath)

Return the URL of a sound resource from the JAR archive. audioPath is relative to the root of the JAR.

delay

public static void delay(long time)

Suspend thread execution for the given amount of time (in ms).