com.vodafone.v10.sound
Class SoundTrack

java.lang.Object
  |
  +--com.vodafone.v10.sound.SoundTrack

public class SoundTrack

extends java.lang.Object

SoundTrack is a class providing functions for sound data playback. The following explains the functionality available in this class:

• 1. Play sound data
  • 1.1. Set/cancel sound data
  • 1.2. Set event listener (SoundTrackListener)
  • 1.3. Get track state/set volume
  • 1.4. Play/stop/pause/resume sound data
• 2. Play sound data synchronously
  • 2.1. Set synchronization
  • 2.2. Cancel synchronization
  • 2.3. Play/stop

1. Play Sound Data

SoundTrack objects are used to play individual sound data. The SoundPlayer object getTrack(int track) or getTrack() is used to get a SoundTrack object. The SoundTrack methods are classified broadly as indicated below in the following sub-sets.

• Set/cancel sound data
• Set event listener (SoundTrackListener) to receive sound playback events
• Get track state/set volume
• Play/stop/pause/resume sound data

1.1. Set/Cancel Sound Data

The Java application must set sound data for playback in the SoundTrack object by calling the setSound() method. A Sound object can be removed by calling removeSound(). A Sound object that has been deleted can be set again by calling the setSound() method. From the time sound starts playing until it is stopped, setSound() and removeSound() cannot be called. If they are called, an exception is thrown.

1.2. Set Event Listener (SoundTrackListener)

Prior to playback, a listener implementing the SoundTrackListener interface is set using the SoundTrack object setEventListener() method, in order to wait for receipt of sound playing-related events. These events are notified in parameters of the SoundTrackListener interface eventOccurred() method. Event notification is made in the following cases.

When sound data playback ends, SoundEventType.EV_END is notified.

When sound data playback is repeated, SoundEventType.EV_LOOP is notified.

When sound data playback is paused, SoundEventType.EV_PAUSE is notified.

When a "user event" is embedded in sound data, SoundEventType.EV_USER_* (where * is a string representing numbers from 0 to 15) is notified.

The relation between user event values and sound data format depends on how the sound player is implemented in the native system.

Note Regarding Resident Java Application

When a Java application runs as a resident program and events for incoming voice calls, mail arrival or a scheduled alarm are notified, the sound player is stopped. In this case SoundTrackListener's eventOccurred() method is not called.

After the sound player is stopped, the handset notifies the user of the incoming call, mail or alarm. Attempting to control the sound player at this time throws an exception. For details see the explanation of the ResidentMIDlet class.

1.3. Get Track State/Set Volume

Volume can be set before starting sound playback or during play. This is done using the setVolume() method. Sound can be muted with the mute() method. The isMute() method is used to find out whether sound is muted or not. The current track state is acquired using the getState() method. The following state information is provided.

SoundTrack.NO_DATA

No data

SoundTrack.PLAYING

Playing

SoundTrack.PAUSED

Paused

SoundTrack.READY

Ready

When a SoundTrack object is acquired without designating the track number in the Java application, the SoundPlayer object automatically assigns a track number. The assigned track number can be found out by means of the SoundTrack object getID() method.

1.4. Play/Stop/Pause/Resume Sound Data

Once a Sound object is set in a SoundTrack object, playback can begin. The play, stop, pause and resume methods are described below.

play()

Plays sound data. The number of repeats can be designated, or endless looping can be requested.

stop()

Stop playing sound, from paused or play state.

pause()

Pause sound playback.

resume()

Resume playing from paused state.

When endless looping is designated with the play() method, eventually the stop() method must be called to stop playback. Methods for sound setting and removal (setSound() and removeSound()) cannot be called after playback starts until it is stopped. An exception is thrown if they are called.

2. Play Sound Data Synchronously

A sound player can perform synchronous playback of different sound data.

This is possible only with sound data; synchronous play of audio data is not possible.

2.1. Set Synchronization

The setSubjectTo() method is used to set synchronicity between tracks. The setSubjectTo() method is called to designate SoundTrack objects as slave tracks of a master track. For example, if track0 is to be made the master track and track1 and track2 are to be slave tracks, the setSubjectTo() method is called as follows for each slave track.

try{
....
track1.setSubjectTo(track0);
track2.setSubjectTo(track0);
}
catch(...){
...

In order to set synchronicity by the setSubjectTo() method, the following conditions must be met.

• A track newly set as a slave track must not already be the slave of another master track, and must not be the master of any track.
• The master and slave tracks to be set for synchronous play must be stopped.

The setSubjectTo() method throws an exception if any of these conditions is not met.

To get the master track of a SoundTrack object defined as a slave track, call the getSyncMaster() method of the SoundTrack object that is a slave track. If no synchronous relation is set, null is returned.

2.2. Cancel Synchronization

Synchronization of a slave track to a master track is canceled by calling the setSubjectTo() method of the SoundTrack object set as slave track and setting null as its master track object. To clear all synchronous relations of a master track, the setSubjectTo() method must be called for all its slave tracks. If track0 is master track with track1 and track2 as slave tracks, clearing all their synchronous relations is done as follows.

track1.setSubjectTo(null);
track2.setSubjectTo(null);

When the removeSound() method is called to remove sound data from a SoundTrack object for which a synchronous relation is set, that relation will be canceled.

• Removing sound data from a slave track cancels the synchronous relation between that slave track and its master track. This does not affect the relation between that master track and other slave tracks.
• Removing sound data from a master track cancels the synchronous relation between that master track and all its slave tracks.

Canceling a synchronous relation can be done only while a track is stopped. Attempting to cancel a synchronization setting while a track is playing will throw an exception.

2.3. Play/Stop

Synchronous play is started and stopped by calling the play() method and stop() method of the SoundTrack object set as master track. If the slave track SoundTrack object play() method or stop() method is called, the request is completed normally but no operation is performed. (The request is ignored without starting or stopping play.)

When tracks set as synchronous are playing, event notification relating to individual track playback is made separately for each track.

Field Summary

static int	NO_DATA No data
static int	PAUSED Paused
static int	PLAYING Playing
static int	READY Ready

Method Summary

int	getID() Gets the track number.
int	getPanpot() Gets the panpot setting (left-right position in soundfield).
Sound	getSound() Gets the sound data set in a track.
int	getState() Gets the track state.
SoundTrack	getSyncMaster() Gets the master track for synchronous play.
int	getVolume() Gets the playback volume.
boolean	isMute() Gets the mute status.
void	mute(boolean mute) Mutes playback.
void	pause() Pauses playback
void	play() Plays sound data.
void	play(int loop) Repeats sound data playback.
void	removeSound() Deletes the sound data setting in a track.
void	resume() Resumes playback.
void	setEventListener(SoundTrackListener l) Registers an event listener.
void	setPanpot(int value) Sets the panpot (left-right position in soundfield).
void	setSound(Sound p) Sets sound data in a track.
void	setSubjectTo(SoundTrack master) Sets the association of slave tracks to a master track for synchronous play.
void	setVolume(int value) Sets the playback volume.
void	stop() Stops playback.

Methods inherited from class java.lang.Object

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

Field Detail

NO_DATA

public static final int NO_DATA

No data

READY

public static final int READY

Ready

PLAYING

public static final int PLAYING

Playing

PAUSED

public static final int PAUSED

Paused

Method Detail

setSound

public void setSound(Sound p)

Sets sound data in a track.

Parameters:

p - sound data

Throws:

NullPointerException - if parameter p is null.

IllegalArgumentException - if the number of tracks needed to play the sound data differs from the number of allocated tracks.

RuntimeException - if the sound data could not be set in the native sound player.

getSound

public Sound getSound()

Gets the sound data set in a track.

Returns:

Sound - Sound data

removeSound

public void removeSound()

Deletes the sound data setting in a track.

Throws:

IllegalStateException - if SoundPlayer was not created.

RuntimeException - if sound data setting could not be deleted from the native sound player.

play

public void play()

Plays sound data. No operation is performed when this method is called during playback.

play

public void play(int loop)

Repeats sound data playback.

The number of repetitions designated in the loop parameter can be any number from 1 to 255 for limited repetition. A setting of 1 means the data is played only once. Endless looping is set by designating 0.

No operation is performed when this method is called during playback.

Parameters:

loop: - Number of repetitions

Throws:

RuntimeException - if the native sound player could not play.

stop

public void stop()

Stops playback.

pause

public void pause()

Pauses playback

Throws:

RuntimeException - if the native sound player could not be paused.

resume

public void resume()

Resumes playback.

Throws:

RuntimeException - if the native sound player could not be resumed.

mute

public void mute(boolean mute)

Mutes playback.

Parameters:

mute - Mute or not (true: mute, false: cancel mute)

getState

public int getState()

Gets the track state.

Returns:

int - Track state

setVolume

public void setVolume(int value)

Sets the playback volume.

Parameters:

value - - Playback volume (0: silent, 127: maximum)

Throws:

IllegalArgumentException - if the value parameter is not in the valid range.

RuntimeException - if the value could not be set in the native sound player.

getVolume

public int getVolume()

Gets the playback volume.

Returns:

int - Playback volume (0: silent, 127: maximum)

setPanpot

public void setPanpot(int value)

Sets the panpot (left-right position in soundfield).

Parameters:

value - - Position (0: left, 64: center, 127: right)

Throws:

IllegalArgumentException - if the value parameter is not in the valid range.

RuntimeException - if the value could not be set in the native sound player.

getPanpot

public int getPanpot()

Gets the panpot setting (left-right position in soundfield).

Returns:

int - Position (0: left, 64: center, 127: right)

setSubjectTo

public void setSubjectTo(SoundTrack master)

Sets the association of slave tracks to a master track for synchronous play. The SoundTrack whose method is called is set as slave track of the SoundTrack designated in the master parameter. Setting the master parameter to null clears the association to a master track.

Parameters:

master - Master track

Throws:

RuntimeException - if no native sound player was set.

getSyncMaster

public SoundTrack getSyncMaster()

Gets the master track for synchronous play. The SoundTrack set as master track for the SoundTrack object whose method was called is returned.

Returns:

SoundTrack - Master track

getID

public int getID()

Gets the track number.

Returns:

int Track number

setEventListener

public void setEventListener(SoundTrackListener l)

Registers an event listener.

Parameters:

l - Event listener

isMute

public boolean isMute()

Gets the mute status.

Returns:

boolean - Whether muted or not (true: muted, false: not muted)