com.nokia.mid.sound
Class Sound

java.lang.Object
  |
  +--com.nokia.mid.sound.Sound

Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by classes in javax.microedition.media package.

public class Sound

extends java.lang.Object

Provides a simple sound API for playing tones and digitized audio.

Since MIDP 1.0 does not have a sound API for games, there is a need for Nokia sound extension to support a device's audio capabilities. Every implementation has the capacity to produce tone sounds (e.g., ringtones), which is the minimum support. Currently, some products also support or will support digitized audio formats. Tone-based sounds must be supported by all implementations. The sound API will support digitized audio if it is available in a device.

Since implementations have different audio capabilities, applications can query which audio formats are supported by implementation by calling getSupportedFormats().

All implementations need to support at least tone-based sounds (type FORMAT_TONE) via Sound(int freq, long duration) and init(int freq, long duration). In addition, all implementations must support Smart messaging ringingtone format (type FORMAT_TONE) via Sound(byte[] data, int type) and init(byte[] data, int type).

This class is thread safe.

Since:

1.0

Field Summary

static int	FORMAT_TONE Deprecated. A tone-based format is used.
static int	FORMAT_WAV Deprecated. Content is in WAV format.
static int	SOUND_PLAYING Deprecated. Sound is in a playing state.
static int	SOUND_STOPPED Deprecated. Sound is in a stopped state.
static int	SOUND_UNINITIALIZED Deprecated. Sound is in an uninitialized (already released) state.

Constructor Summary

Sound(byte[] data, int type)
Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Manager.createPlayer(java.io.InputStream, String).

Sound(int freq, long duration)
Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Manager.playTone(int, int, int).

Method Summary

static int	getConcurrentSoundCount(int type) Deprecated. Returns the maximum number of concurrent sounds the device can play for a specific audio type.
int	getGain() Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.VolumeControl.getLevel(int).
int	getState() Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Manager.Player.getState().
static int[]	getSupportedFormats() Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Manager.getSupportedContentTypes(String).
void	init(byte[] data, int type) Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Manager.createPlayer(java.io.InputStream, String).
void	init(int freq, long duration) Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Manager.playTone(int, int, int).
void	play(int loop) Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Player.setLoopCount(int).
void	release() Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Player.deallocate().
void	resume() Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Player.start().
void	setGain(int gain) Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.VolumeControl.setLevel(int).
void	setSoundListener(SoundListener listener) Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Player.addPlayerListener(javax.microedition.media.PlayerListener).
void	stop() Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Player.stop().

Methods inherited from class java.lang.Object

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

Field Detail

FORMAT_TONE

public static final int FORMAT_TONE

Deprecated.

A tone-based format is used. init(int freq, int duration) puts sound into this format.

Value 1 is assigned to FORMAT_TONE.

Since:

1.0

See Also:

Constant Field Values

FORMAT_WAV

public static final int FORMAT_WAV

Deprecated.

Content is in WAV format.

Value 5 is assigned to FORMAT_WAV.

Since:

1.0

See Also:

Constant Field Values

SOUND_PLAYING

public static final int SOUND_PLAYING

Deprecated.

Sound is in a playing state.

Value 0 is assigned to SOUND_PLAYING.

Since:

1.0

See Also:

Constant Field Values

SOUND_STOPPED

public static final int SOUND_STOPPED

Deprecated.

Sound is in a stopped state.

Value 1 is assigned to SOUND_STOPPED.

Since:

1.0

See Also:

Constant Field Values

SOUND_UNINITIALIZED

public static final int SOUND_UNINITIALIZED

Deprecated.

Sound is in an uninitialized (already released) state.

Value 3 is assigned to SOUND_UNINITIALIZED.

Since:

1.0

See Also:

Constant Field Values

Constructor Detail

Sound

public Sound(byte[] data,
             int type)

Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Manager.createPlayer(java.io.InputStream, String).

Constructors initialize Sound object so that it is ready for playback. This constructor is used for initializing Sound based on byte array data. The data should contain the data presented in the data format specified by type parameter. The Sound class also defines generally supported types as constants.

All implementations need to support at least Nokia Smart Messaging, Over the Air (OTA) ringtone format as defined by Smart Messaging Specification (see Section 3.6 Ringing Tones). At least 'basic song' and 'temporary song' OTA types must be supported. The specification can be found from the Messaging section of Forum Nokia (http://www.forum.nokia.com). The type of this format is FORMAT_TONE.

Note: some implementations cannot throw exceptions about sound data being corrupted or illegal during construction. This will result in IllegalArgumentException being delayed until play(int loop) method is called. Applications thus need to except that IllegalArgumentException is thrown in this method or during play method call.

After construction the state is SOUND_STOPPED.

Parameters:

data - an array of bytes specifying the sound data in the format specified by type parameter

type - the type of the sound data, for example, FORMAT_WAV or FORMAT_TONE

Throws:

java.lang.IllegalArgumentException - if the data can not be recognized as a given type or the type is unsupported or unknown

java.lang.NullPointerException - if the data is null

Since:

1.0

Sound

public Sound(int freq,
             long duration)

Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Manager.playTone(int, int, int).

Constructors initialize Sound so that it is ready for playback. Sound is initialized as a simple tone-based sound.

See method init(int freq, long duration) for complete descriptions.

After construction the state is SOUND_STOPPED.

Parameters:

freq - a frequency value in Hz

duration - the length of the tone in milliseconds

Throws:

java.lang.IllegalArgumentException - if parameter values are illegal, freq is not in given range or duration is negative or zero

Since:

1.0

Method Detail

init

public void init(int freq,
                 long duration)

Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Manager.playTone(int, int, int).

Initializes Sound to play a simple beep. The duration (milliseconds) indicates the length of time the tone is played with freq as frequency (Hz). The length of time should be short, at the most, a couple of seconds. The implementation may decide not to play tone sounds at all that are initialized with this method and that last longer than two or more seconds. If this happens, the implementation will just silently return from play(int loop) method call. Applications should prefer OTA Ringtone format over simple init(int freq, long duration) tones.

A Sound that is already initialized is first released as if by calling the release() method. This will also stop the sound if necessary. If any exception is thrown during the init method the sound moves to uninitialized state. If initialization is successful then the state changes to SOUND_STOPPED.

Note: some implementations may not support the full frequency scale defined in the table below. They will instead throw IllegalArgumentException for unsupported values. The exception may also be delayed until the play(int loop) method is called. All implementations are required to support freq values between 440 Hz (A1) and 3951 Hz (B4). All implementations also need to support the freq value 0 (Freq off).

The following table describes some freq argument values:

 Description            Frequency (Hz)
 Freq off               0
 Ring freq A0           220
 Ring freq B0b          233
 Ring freq B0           247
 Ring freq C0           262
 Ring freq D0b          277
 Ring freq D0           294
 Ring freq E0b          311
 Ring freq E0           330
 Ring freq F0           349
 Ring freq G0b          370
 Ring freq G0           392
 Ring freq A1b          416
 Ring freq A1           440
 Ring freq B1b          466
 Ring freq B1           494
 Ring freq C1           523
 Ring freq D1b          554
 Ring freq D1           587
 Ring freq E1b          622
 Ring freq E1           659
 Ring freq F1           698
 Ring freq G1b          740
 Ring freq G1           784
 Ring freq A2b          831
 Ring freq A2           880
 Ring freq B2b          932
 Ring freq B2           988
 Ring freq C2           1047
 Ring freq D2b          1109
 Ring freq D2           1175
 Ring freq E2b          1245
 Ring freq E2           1319
 Ring freq F2           1397
 Ring freq G2b          1480
 Ring freq G2           1568
 Ring freq A3b          1661
 Ring freq A3           1760
 Ring freq B3b          1865
 Ring freq B3           1976
 Ring freq C3           2093
 Ring freq D3b          2217
 Ring freq D3           2349
 Ring freq E3b          2489
 Ring freq E3           2637
 Ring freq F3           2794
 Ring freq G3b          2960
 Ring freq G3           3136
 Ring freq A4b          3322
 Ring freq A4           3520
 Ring freq B4b          3729
 Ring freq B4           3951
 Ring freq C4           4186
 Ring freq D4b          4434
 Ring freq D4           4698
 Ring freq E4b          4978
 Ring freq E4           5274
 Ring freq F4           5588
 Ring freq G4b          5920
 Ring freq G4           6272
 Ring freq A5b          6644
 Ring freq A5           7040
 Ring freq B5b          7458
 Ring freq B5           7902
 Ring freq C5           8372
 Ring freq D5b          8870
 Ring freq D5           9396
 Ring freq E5b          9956
 Ring freq E5           10548
 Ring freq F5           11176
 Ring freq G5b          11840
 Ring freq G5           12544
 Ring freq A6b          13288

 

Parameters:

duration - length of the beep in milliseconds

freq - frequency (Hz) to be played

Throws:

java.lang.IllegalArgumentException - if parameter values are illegal, freq is not in given range or duration is negative or zero

Since:

1.0

init

public void init(byte[] data,
                 int type)

Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Manager.createPlayer(java.io.InputStream, String).

Initializes Sound based on byte array data. The data should contain the data presented in the data format specified by type parameter. The Sound class also defines generally supported types as constants.

All implementations need to support at least Nokia Smart Messaging, Over the Air (OTA) ringingtone format. The type of this format is FORMAT_TONE.

A Sound that is already initialized is first released as if by calling the release() method. This will also stop the sound if necessary. If any exception is thrown during the init method the sound moves to uninitialized state. If initialization is successful then the state changes to SOUND_STOPPED.

Note: some implementations cannot throw exceptions about sound data being corrupted or illegal during this method call. This will result in IllegalArgumentException being delayed until play(int loop) method is called. Applications thus need to except that IllegalArgumentException is thrown in this method or during play method call.

Parameters:

data - a byte array containing the data to be played

type - type of the audio

Throws:

java.lang.IllegalArgumentException - if the data can not be recognized as a given type or the type is unsupported or unknown

java.lang.NullPointerException - if the data is null

Since:

1.0

getState

public int getState()

Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Manager.Player.getState().

Gets the current state of Sound.

Returns:

current state, SOUND_PLAYING, SOUND_STOPPED or SOUND_UNINITIALIZED

Since:

1.0

play

public void play(int loop)

Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Player.setLoopCount(int).

This method is used for starting the playback from the beginning of a sound object.

The loop parameter defines the repetition count for the playback. Value zero (0) means continuous looping. Value 1 means that the clip is played once. Applications should not use large loop values. The implementation may decide not to play sounds at all with looping values >=255. If this happens, the implementation will just silently return from play(int loop) method call.

For uninitialized sound, the play method does not do anything and silently returns. For sounds that have been stopped or are still playing, the playback starts from beginning of the sound with new looping information. This means that for a sound that is already being played, the sound is restarted and SOUND_STOPPED and SOUND_PLAYING events are generated.

If there are limits playing multiple concurrent sounds the latest play method call is always effective. If other currently played sound need to be interrupted it is stopped as if called to the stop method. The sound that will be stopped is the one that has been started the earliest.

If there is higher priority system -sounds being played when a sound is tried to be started then the playing is not started and the sound state remains stopped. This causes no event.

If a higher priority system sound interrupts a sound already being played the currently playing sound is stopped as if called to the stop method.

If sound playback is possible, this method will return immediately and thus will not block the calling thread during playback. The state of the sound also changes to SOUND_PLAYING. If any error that prevents playback is encountered during playback, it is silently stopped as if called to the stop method.

Parameters:

loop - the number of times audio is looped. Value 0 plays audio in continous loop.

Throws:

java.lang.IllegalArgumentException - if the loop value is negative, or if sound values/data is illegal or corrupt.

Since:

1.0

stop

public void stop()

Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Player.stop().

The method will stop the sound playback and changes the state to SOUND_STOPPED.

For sound that has never been started, is uninitialized, or is currently being stopped, the method call does not do anything and returns silently. No state change occurs.

Since:

1.0

resume

public void resume()

Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Player.start().

The method will continue the playback of the stopped sound object from the position it was stopped at. The state changes to SOUND_PLAYING.

For sound that has never been started (may be uninitialized), or is currently being played the method call does not do anything.

Note that it depends on the implementation whether a specific sound format supports resume funtionality. If it is not supported then resume starts the playback from the beginning of the sound. For tone-based sounds (type FORMAT_TONE), it is not possible to resume from the position the sound was stopped at; resume starts from the beginning of the sound.

Since:

1.0

release

public void release()

Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Player.deallocate().

Releases audio resources reserved by this object. If the sound is currently being played the sound is first stopped as if by calling the stop() method. After the object is released, it goes to an uninitialized state. This method should be called when a Sound object is not needed anymore.

For a sound that is already uninitialized the method call does not do anything.

Since:

1.0

setGain

public void setGain(int gain)

Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.VolumeControl.setLevel(int).

Sets the gain for the sound object. The gain is a value between 0 and 255. Gain value 0 means silence. Implementation scales the gain value to the limits it supports. Notice that any gain value > 0 should result in a gain that then results in some sound output. If the gain is smaller than 0, then the gain is set to 0; if the gain is greater than 255, then the gain is set to its maximum value (255).

Parameters:

gain - gain value: 0 - 255

Since:

1.0

See Also:

getGain()

getGain

public int getGain()

Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.VolumeControl.getLevel(int).

Get the gain (or volume) of the sound. The gain is a value between 0 and 255. Method returns back the exact value previously set with setGain(int gain). Any gain value > 0 must result in some sound output.

If setGain(int gain) has not been called for the sound object, the gain value is a default defined by the implementation. If for some reason the implementation cannot return the default gain value via this method, it returns -1. Note: -1 passed to the setGain(int gain) method will result a gain value of 0.

Returns:

gain value 0 - 255 or -1 if gain value is the default and implementation cannot report actual gain value.

Since:

1.0

See Also:

setGain(int)

getConcurrentSoundCount

public static int getConcurrentSoundCount(int type)

Deprecated.

Returns the maximum number of concurrent sounds the device can play for a specific audio type. Returns 1 if only one sound can be played at a time.

Parameters:

type - the media type

Returns:

total number of available channels.

Throws:

java.lang.IllegalArgumentException - if the type is unsupported or unknown

Since:

1.0

getSupportedFormats

public static int[] getSupportedFormats()

Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Manager.getSupportedContentTypes(String).

Returns the supported audio formats as an int array.

Returns:

an array containing supported audio formats as int values (e.g. FORMAT_TONE, FORMAT_WAV), or an empty array if no audio formats are supported.

Since:

1.0

setSoundListener

public void setSoundListener(SoundListener listener)

Deprecated. As of Nokia UI API 1.1 in devices with MIDP 2.0 or higher, replaced by javax.microedition.media.Player.addPlayerListener(javax.microedition.media.PlayerListener).

Registers a listener for playback state notifications.

Parameters:

listener - a listener that is notified when state changes occur or null if listener is to be removed.

Since:

1.0

See Also:

SoundListener