API Reference | developer.brewmp.com API Reference | developer.brewmp.com

Developer

API Reference

ISOUNDPLAYER

Brew Release
Brew MP 1.0.2
See Also
Description

The ISoundPlayer Interface has been deprecated, use the IMedia Interface.
ISoundPlayer interface provides audio multimedia services. ISoundPlayer supports MIDI, MP3 and QCP (QUALCOMM PureVoice or QCELP) formats. For more details on QCP format and the associated BREW SDK tools, please refer to BREW SDK User's Guide.
Usage
The ISoundPlayer Interface has been deprecated, use the IMedia Interface.
Creating ISoundPlayer Instance
You can create ISoundPlayer instance in two ways:
1. Using ISHELL_CreateInstance() with AEECLSID_SOUNDPLAYER as ClassID.
2. Using ISHELL_GetHandler() with AEEHandlerType set to HTYPE_SOUND and MIME string set to snd/midi for MIDI, snd/mp3 for MP3, or snd/qcp for QCP formats. Call ISHELL_CreateInstance() with the returned ClassID.
ISoundPlayer Input Types
You can specify the audio source,(input type and data), in AEESoundPlayerInfo structure and set it using ISOUNDPLAYER_SetInfo(). The ISoundPlayer Interface can play using a memory buffer, SDT_BUFFER or file, SDT_FILE. Playback while streaming is not supported, but you can associate an IAStream with ISoundPlayer using ISOUNDPLAYER_SetStream(). ISoundPlayer reads the entire data from the stream into a buffer, and plays the buffer.
ISOUNDPLAYER_GetInfo() returns the current audio source if a pointer to AEESoundPlayerInfo is given.
NOTE: ISoundPlayer does not set the audio source if it is busy. ISoundPlayer is busy if it is playing, executing a command, or streaming input data. To find if ISoundPlayer is busy, you call: int ISOUNDPLAYER_GetInfo(pISoundPlayer, NULL); It returns EIDLE if ISoundPlayer is idle or EITEMBUSY if it is busy.
NOTE: ISOUNDPLAYER_Set() is deprecated. Instead use ISOUNDPLAYER_SetInfo() which provides better access to ISoundPlayer.
Playback Control
ISoundPlayer provides the following playback control functions:

ISOUNDPLAYER_Play() To play the MIDI/MP3/QCP file
ISOUNDPLAYER_Stop() To stop the playback
ISOUNDPLAYER_Rewind() To rewind playback for n milliseconds. This command is not supported for QCP format.
ISOUNDPLAYER_FastForward() To fast forward playback for n milliseconds This command is not supported for QCP format.
ISOUNDPLAYER_Pause() To pause the playback, This command is not supported for QCP format.
ISOUNDPLAYER_Resume() To resume the playback This command is not supported for QCP format.
ISOUNDPLAYER_SetTempo() To set playback tempo for MIDI. Not applicable for MP3 and QCP.
ISOUNDPLAYER_SetTune() To set the pitch level, in half step increments, of the current MIDI playback. Not applicable for MP3 and QCP


ISOUNDPLAYER_Play() gets precedence over ISOUNDPLAYER_GetTotalTime(). There can be only one active ISOUNDPLAYER_Play(). You need to issue a stop before you can call another ISOUNDPLAYER_Play(). Only one of the commands from #4 -#9 (in the table above) can be active at any time. ISoundPlayer sends AEE_SOUNDPLAYER_FAILURE if a command does not succeed.
Callback Notification
Most of the calls to ISoundPlayer API are asynchronous in nature. If application is to receive status and events from ISoundPlayer, the application must register a callback notification function using ISOUNDPLAYER_RegisterNotify(). ISoundPlayer sends status and events to the user application through this registered callback function.
There are five types of callback functions invoked by the ISoundPlayer Interface.
AEE_SOUNDPLAYER_PLAY_CB
AEE_SOUNDPLAYER_STATUS_CB
AEE_SOUNDPLAYER_TIME_CB
AEE_SOUNDPLAYER_SOUND_CB
AEE_SOUNDPLAYER_VOLUME_CB
Each callback type, in turn, contains a set of status indications and data that are valid only for callbacks of that type.
For example, for AEE_SOUNDPLAYER_PLAY_CB, the status type can be:
AEE_SOUNDPLAYER_SUCCESS
AEE_SOUNDPLAYER_PAUSE
AEE_SOUNDPLAYER_RESUME
and so forth
Any Data is returned in a callback through the dwParam parameter that points to an AEESoundPlayerCmdData structure if data is present. Otherwise the dwParam is NULL.
During playback, every second the applet is notified of AEE_SOUNDPLAYER_TICK_ UPDATE status by AEE_SOUNDPLAYER_PLAY_CB. This can be used by the applet to update the progress of playback.
After rewind, fast forward, pause, or resume, the dwParam parameter of AEE_SOUNDPLAYER_PLAY_CB callback function's dwParam points to the current position in milliseconds of the playback. Again, applets can use this to update the playback progress. These mechanisms are demonstrated in the sample MIDI-MP3 Player applet.
It is not always required to register a callback function. Choose not to get any ISoundPlayer events by calling ISOUNDPLAYER_RegisterNotify() as follows:
ISOUNDPLAYER_RegisterNotify(pISoundPlayer, NULL, NULL);
Audio Device And Volume Control
ISoundPlayer internally uses an instance of ISound for setting the audio device parameters (ISOUNDPLAYER_SetSoundDevice()) and for setting/getting the volume of the output (ISOUNDPLAYER_SetVolume() and ISOUNDPLAYER_GetVolume()). You do not need to create an ISound instance for these operations.
To use the services of ISoundPlayer Interface
1. Create the ISoundPlayer object by calling ISHELL_CreateInstance() with AEECLSID_SOUNDPLAYER as ClassID.
2. Call ISOUNDPLAYER_RegisterNotify() to register the ISoundPlayer callback function. The ISoundPlayer Interface always uses this callback function to notify the applet of any events or status changes.
3. Set the source of the MIDI/MP3/QCP media (file/buffer using the ISOUNDPLAYER_SetInfo() function. Be sure to check if it is successful.
4. In the applet event handler, call any of the playback control functions like ISOUNDPLAYER_GetTotalTime(), ISOUNDPLAYER_Play().
5. Before exiting, always:
a. Un-register the callback function by calling
ISOUNDPLAYER_RegisterNotify(pISoundPlayer, NULL, NULL)
b. Call ISOUNDPLAYER_Stop() if playback is active.
The following header file is required: AEESoundPlayer.h