+ * Provides simple Sound API for playing tones and digitized audio. + *
+ * Since MIDP doesn't have any Sound API for games there is a need + * for proprietary sound extension to support devices audio + * capabilities. Every implementation has capability to produce tone + * sounds (e.g. ringing tones), this is the minimum support. Currently + * some products support or will support also digitized audio formats. + * The Game sound API will support both buzzer and digitized audio. + * Buzzer must be supported by all implementations. If implementation + * doesn't have buzzer the buzzer tones are emulated. + *
+ * Since implementations have different audio capabilities, + * application can query which audio formats are supported by + * implementation by calling {@link #getSupportedFormats()}. + *+ * All implementations need to support at least tone based sounds + * (type FORMAT_TONE) via {@link #Sound(int freq, long duration)} and + * {@link #init(int freq, long duration)}. In addition all implementations + * must support Smart messaging ringingtone format (type FORMAT_TONE) + * via {@link #Sound(byte[] data, int type)} and + * {@link #init(byte[] data, int type) }. + *
+ * Note that there is also work going on with Multimedia API that + * is done in JCP as + * JSR 135. + * The standard Multimedia API + * will replace the proprietary Game Sound API when it is ready. However + * Sound API will be supported also later on but probably it will be + * stated as deprecated. + *
+ * @version 1.1 + * @see com.nokia.mid.ui.DeviceControl + * @since 1.0 + */ + +public class Sound +{ + + /** + * Tone based format is used. + * + * init(int freq, int duration) puts sound into this format. + * @since 1.0 + * + */ + public static final int FORMAT_TONE = 1; + + /** + * Content is in WAV format. + * @since 1.0 + * + */ + public static final int FORMAT_WAV = 5; + + /** + * Sound is playing. + * @since 1.0 + * + */ + public static final int SOUND_PLAYING = 0; + + /** + * Sound is stopped. + * @since 1.0 + * + */ + public static final int SOUND_STOPPED = 1; + + /** + * Sound is uninitialized (released). + * @since 1.0 + */ + public static final int SOUND_UNINITIALIZED = 3; + + /** + * Sound is reinitialising + */ + private static final int SOUND_REINITIALISING = 4; + + private static final int FORMAT_BEEP = 2; + private static final int NOT_SUPPORTED_ERROR = 3; + + private static final int ERR_NOT_READY = -18; + private static final int ERR_ARGUMENT = -6; + + private int iHandle; + + private Finalizer iFinalizer; + private int iCurrentType; + private int iState; + private int iGain = -1; + + Vector iSoundListeners = new Vector(); + + private static Sound iPlayingSound; + + static + { + com.nokia.mj.impl.rt.support.Jvm.loadSystemLibrary("javanokiasound"); + } + + /** + * Constructors initialize the Sound object so that it is ready for + * playback. This constructor is used for initializing Sound + * object based on byte array data. The data should contain the data + * presented in the data format specified by type parameter. The Sound + * class defines also 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. + *
+ * Note: some implementations can't throw exceptions about + * sound data being corrupted or illegal during construction. + * This will result that IllagalArgumentException is 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. + *
+ * @throws java.lang.IllegalArgumentException if the data can not be + recognized to + * given type or the type is unsupported or unknown + * @throws java.lang.NullPointerException if the data is null + * @since 1.0 + * + */ + public Sound(byte[] data, int type) + { + Logger.LOG(Logger.EJavaUI, Logger.EInfo, "Sound Constructor"); + iFinalizer = registerForFinalization(); + + iHandle = _create(); + + iState = SOUND_UNINITIALIZED; + + init(data, type); + } + + /** + * Constructors initialize the Sound object so that it is ready for + * playback. Sound is initialized as a simple tone based sound. + *
+ * See method {@link #init(int freq, long duration)} for + * freq value descriptions. See also a note on exceptions semantics in + * {@link #init(int freq, long duration)}. + * + * @param freq a frequency value + * @param duration the duration 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 + */ + public Sound(int freq, long duration) + { + + iFinalizer = registerForFinalization(); + iHandle = _create(); + + iState = SOUND_UNINITIALIZED; + + init(freq, duration); + } + + /** + * Called when this object is finalized, frees native resources + */ + + public Finalizer registerForFinalization() + { + + return new Finalizer() + { + public void finalizeImpl() + { + doFinalize(); + } + }; + } + + void doFinalize() + { + + if (iFinalizer == null) + { + return; + } + iFinalizer = null; + + if (iHandle > 0) + { + _dispose(iHandle); + } + } + + /** + * Releases audio resources reserved by this object. After object + * is released it goes to uninitialized state. This method should + * be called when Sound object is not needed anymore. + * @since 1.0 + */ + public void release() + { + if ((iState != SOUND_UNINITIALIZED) && + (iState != SOUND_REINITIALISING)) + { + iState = SOUND_REINITIALISING; + soundStateChanged(SOUND_UNINITIALIZED); + } + + _release(iHandle); + + iState = SOUND_UNINITIALIZED; + + } + + /** + * Initializes Sound to play a simple beep. + *
+ * Note: some implementations may not support the full frequency + * scale defined in table below. They will throw + * IllegalArgumentException instead for unsupported values. The + * exception may also be delayed + * until the play(int loop) method is called. + *
+ * Following table describes some freq argument + * values: + *
+ * Description Frequency + * 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 + * + *+ * + * @param duration length of the beep in milliseconds + * @param freq frequency 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 + */ + public void init(int freq, long duration) + { + if (duration < 1 || duration > 10000000) + { + throw(new IllegalArgumentException( + "Bad duration value, must be 1-10000000")); + } + if (freq < 0 || freq > 15000) + { + throw(new IllegalArgumentException( + "Bad frequency value, must be 0-15000")); + } + // if the uninitialised event is sent from native side, it reaches + // listener too late in TCK test sound8004, thus we send the event + // already here + if ((iState != SOUND_UNINITIALIZED) && + (iState != SOUND_REINITIALISING)) + { + iState = SOUND_REINITIALISING; + soundStateChanged(SOUND_UNINITIALIZED); + } // end of if (iState != SOUND_UNINITIALIZED) + + iCurrentType = FORMAT_BEEP; + int err = _init(iHandle, iCurrentType, null, freq, duration); + if (err == ERR_NOT_READY) + { + throw new RuntimeException(Integer.toString(err)); + } + else if (err == ERR_ARGUMENT) + { + throw new IllegalArgumentException("Data is invalid"); + } + iState = SOUND_STOPPED; + } + + /** + * Initializes Sound object based on byte + * array data. The data should contain the data presented in the data + * format specified by type parameter. The Sound class defines also + * 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. + *
+ * Note: some implementations can't throw exceptions about + * sound data being corrupted or illegal during this method call. + * This will result that IllagalArgumentException is 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. + *
+ * @param data a byte array containing the data to be played + * @param type type of the audio + * @throws java.lang.IllegalArgumentException if the data can not be + recognized to + * given type or the type is unsupported or unknown + * @throws java.lang.NullPointerException if the data is null + * @since 1.0 + */ + public void init(byte[] data, int type) + { + if (!(type == FORMAT_WAV || type == FORMAT_TONE)) + { + throw(new IllegalArgumentException("Type is not supported")); + } + if (data == null) + { + throw(new NullPointerException("Data is null")); + } + + if ((iState != SOUND_UNINITIALIZED) && + (iState != SOUND_REINITIALISING)) + { + iState = SOUND_REINITIALISING; + soundStateChanged(SOUND_UNINITIALIZED); + } // end of if (iState != SOUND_UNINITIALIZED) + + iCurrentType = type; + int err = _init(iHandle, iCurrentType, data, 0, 0); + if (err == ERR_NOT_READY || err == ERR_ARGUMENT ) + { + throw new IllegalArgumentException("Data is invalid"); + } + + iState = SOUND_STOPPED; + } + + + /** + * Get the current state of the Sound object. + * + * @return current state, SOUND_PLAYING, SOUND_STOPPED or + SOUND_UNINITIALIZED + * @since 1.0 + * + */ + public int getState() + { + if (iState == SOUND_REINITIALISING) + { + return SOUND_UNINITIALIZED; + } + + iState = _getState(iHandle); + switch (iState) + { + case(0): // ENotReady + case(4): // EInitialising + iState = SOUND_UNINITIALIZED; + break; + case(1): // EReadyToPlay + iState = SOUND_STOPPED; + break; + case(2): // EPlaying + iState = SOUND_PLAYING; + break; + default: + } + return iState; + } + + /** + * This method is used for starting the playback from the beginning of a + * sound object. The loop parameter defined the loop count for playback. + * Argument zero (0) means continuos looping. For uninitialized sound the + * play method doesn't do anything and silently returns. For stopped and + * playing sounds the playback starts from beginning of the sound with new + * looping information. + *
+ * This method will throw IllegalStateException if playback cannot be + * started since all channels are in use, or playback is not possible + * because there is more higher priority system sounds being played. + *
+ * If Sound playback is possible this method will return immediately and + * thus will not block the calling thread during the playback. If any error + * that prevents the playback is encountered during the playback, the + * playback is silently stopped as if called to the stop method. + * + * @param number number of times audio is played. Value 0 plays audio in + * continous loop. + * @throws java.lang.IllegalStateException if the sound object cannot be + * played because all the channels are already in use. + * @throws java.lang.IllegalArgumentException if the loop value is negative, + * or if sound values/date is illegal or corrupted. + * @since 1.0 + * + */ + public void play(int loop) throws IllegalArgumentException + { + if (loop < 0) + { + throw(new IllegalArgumentException("Negative loop value")); + } + if (iState == SOUND_REINITIALISING) + { + return; + } // end of if (iState == SOUND_REINITIALISING) + + if (iPlayingSound != null) + { + if (iPlayingSound.getState() == SOUND_PLAYING) + { + iPlayingSound.stop(); + } + } // end of if (iPlayingSound != null) + + int error = _play(iHandle, loop); + if ((error == NOT_SUPPORTED_ERROR)) + { + throw(new IllegalArgumentException("Sound is not supported")); + } + iPlayingSound = this; + } + + /** + * The method will stop the sound playback, storing the current position. + * For sound that has never been started (may be uninitialized), or is + * currently being stopped the method call doesn't do anything and returns + * silently. + * + * Note that for tone based sounds it is not possible to resume from + * position the sound was stopped at, to be specific, stop will reset + * the position to the beginning of the sound. + * @since 1.0 + */ + public void stop() + { + if (iState == SOUND_REINITIALISING) + { + return; + } // end of if (iState == SOUND_REINITIALISING) + _stop(iHandle); + } + + /** + * The method will continue the stopped sound object from the position it + * was stopped to. For sound that has never been started (may be + * uninitialized), or is currently being played the method call doesn't + * do anything. + *
+ * Note: For tone based sounds the resume starts the sound from the + * beginning of the sound clip. + * @since 1.0 + * + */ + public void resume() + { + if (iState == SOUND_REINITIALISING) + { + return; + } // end of if (iState == SOUND_REINITIALISING) + _resume(iHandle); + } + + /** + * Sets the gain for the sound object. The gain is a value between + * 0 and 255. Implementation scales the gain value to the limits it + * supports. Notice that any gain value > 0 should result a gain + * value > 0. If the gain is smaller than this minimum value then + * gain is set to 0, if the gain greater than this maximum value + * then the gain is set to maximum value (255). + * + * @param gain gain value: 0 - 255 + * @throws java.lang.IllegalArgumentException if the gain not 0 - 255 + * @since 1.0 + */ + public void setGain(int gain) + { + if (iState == SOUND_REINITIALISING) + { + return; + } // end of if (iState == SOUND_REINITIALISING) + if (gain < 0) + { + gain = 0; + } + else if (gain > 255) + { + gain = 255; + } + iGain = gain; + _setVolume(iHandle, iGain); + } + + /** + * Get the gain (or volume) of Sound object. The gain is a value + * between 0 and 255. System returns a scaled value based on the + * limits it supports. Notice that any system gain value > 0 should + * return a gain value > 0. + * + * @return gain value 0 - 255 + * @since 1.0 + * + */ + public int getGain() + { + if (iGain == -1) + { + return _volume(iHandle); + } + // we have previously set gain + return iGain; + } + + /** + * Returns number of concurrent sounds the device can play for + * specific audio type. Returns 1 if only one sound can be played + * at a time. Notice that most types use same channel resources. + * @return total number of available channels. + * @param type the media type + * @throws java.lang.IllegalArgumentException if the type is unsupported + * or unknown + * @since 1.0 + */ + public static int getConcurrentSoundCount(int type) + { + if ((type != FORMAT_TONE) && (type != FORMAT_WAV)) + { + throw(new IllegalArgumentException("Type is not supported")); + } + + return 1; + } + + /** + * Returns the supported audio formats as an int array. + * + * @return 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 + */ + static public int[] getSupportedFormats() + { + return(new int[] { FORMAT_TONE, FORMAT_WAV }); + } + + /** + * Registeres a listener for playback state notifications. + * @see com.nokia.mid.sound.SoundListener + * @param listener a listener that is notified when state + * changes occur or null if listener is to be + * removed. + * @since 1.0 + * + */ + public void setSoundListener(SoundListener listener) + { + iSoundListeners.addElement(listener); + } + + /** + * Callback method when sound state changes + * + */ + public void soundStateChanged(final int event) + { + /* + for(int i = 0; i < iSoundListeners.size(); i++) + { + ((SoundListener)iSoundListeners.elementAt(i)).soundStateChanged(this, event); + } + */ + //Notify SoundState Listeners in a separate thread, so that application doesn't + //block main thread + new Thread(new Runnable() + { + public void run() + { + notifySoundStateListeners(event); + } + }).start(); + } + + /** + * Notify Sound State Listeners + */ + public synchronized void notifySoundStateListeners(int event) + { + for (int i = 0; i < iSoundListeners.size(); i++) + { + ((SoundListener)iSoundListeners.elementAt(i)).soundStateChanged(this, event); + } + } + + private native void _dispose(int aHandle); + private native int _create(); + private native int _init(int aHandle, int aType, + byte[] aData, + int aFrequency, long aDuration); + private native void _release(int aHandle); + private native int _play(int aHandle, int aLoop); + private native void _stop(int aHandle); + private native void _resume(int aHandle); + private native void _setVolume(int aHandle, int aVolume); + private native int _volume(int aHandle); + private native int _getState(int aHandle); + +} //End of Sound class +