Developers

Local Navigation

Home  >  Developers  >  Resources  >  Developer Journals  >  September 2006  > 

Why Make a Mental Note When You Can Make a Voice Note?

Richard Evers, Editor, and Brian Zubert, Research In Motion

 

Ideas come at all times of the day and there isn't always enough time to do something about them. The common solution for most people is to make a mental note and take action later. However, a common problem with this solution is that the chances of forgetting some of the idea's details or even forgetting the idea altogether, grow stronger with every passing moment.

A feature introduced in BlackBerry® Device Software v4.0 for the BlackBerry 7520™ and all software versions of the BlackBerry 7100i™ was that of voice notes. This functionality includes the ability to record, play, stop, and delete user recorded audio files -- it even allows an application to detect when these actions have taken place!

The original goal of this functionality was to give the user a way to make a simple recording for playback at a later date. However, some software vendors have taken this technology to a whole new level by incorporating voice recognition technologies that allow email messages to be composed and sent by voice commands alone. For a complete listing of third party solutions, visit www.blackberry.com/ThirdParty.

Developing an Application That Uses Voice Notes

 

While the feature set of the API set might seem rather large and maybe even overwhelming, using the API is actually very easy to do and can give your application the edge it needs to gain widespread customer acceptance. A fully functional sample application is included with BlackBerry Java™ Development Environment (BlackBerry JDE) v4.1, but listed below is each feature of the API along with sample code illustrating how simple it is to use it.

Feature:

Record a voice note.

Example: 
int returnValue = Audio.recordFile
    (Audio.AUDIO_CODEC_VOICENOTE, File.FILESYSTEM_PATRIOT, "file name");
Feature:

Play a voice note.

Example: 
int returnValue = Audio.playFile
    (Audio.AUDIO_CODEC_VOICENOTE, File.FILESYSTEM_PATRIOT, "file name");
Feature:

Stop while playing voice note.

Example: 
int returnValue = Audio.stopFile
    (Audio.AUDIO_CODEC_VOICENOTE, File.FILESYSTEM_PATRIOT, "file name");
Feature:

Delete a voice note.

Example: 
File.delete(File.FILESYSTEM_PATRIOT, "file name");
Feature:

Listen for audio events.

Full Example: 
//Add an AudioFileListener to an Application
Audio.addListener(myApplication, myAudioFileListener);

// implement AudioFileListener.audioFileOperationComplete
//    (int operation)
public void audioFileOperationComplete(int operation)
{
    if(operation == AudioFileListener.OPERATION_RECORD)
    {
        //record finished
    } else if(operation == AudioFileListener.OPERATION_PLAY)
    {
        //play finished
    } else if(operation == AudioFileListener.OPERATION_STOP)
    {
        //stop finished
    }
}

//implement AudioFileListener.audioFileOperationFailed
//    (int operation)
public void audioFileOperationFailed(int operation, int errorCode)
{
    if(operation == AudioFileListener.OPERATION_RECORD)
    {
        //record failed
        if(errorCode == AUDIO_ERROR_BAD_DATA)
        {
            /invalid data provided
        } else if(errorCode == AUDIO_ERROR_BAD_STATE)
        {
            //playback is already in progress
        } else if(errorCode == AUDIO_ERROR_FILESYSTEM_FULL)
        {
            //filesystem is full
        } else if(errorCode == AUDIO_ERROR_UNKNOWN)
        {
            //unknown error
        }
    } else if(operation == AudioFileListener.OPERATION_PLAY)
    {
        //play failed == error codes similar to above
    } else if(operation == AudioFileListener.OPERATION_STOP)
    {
        //stop failed == error codes similar to above
    }
}

The VoiceNotes API in depth

 

The following diagram shows how the Audio components fit together. All handling is performed through the Audio class, the Listener interfaces are used to record and stop activities after they complete, and the "File" classes handle all low-level aspects of VoiceNotes file handling.

net.rim.device.api.system.Audio

 

The Audio class is used to record and play audio files. Audio file storage occurs on the flat file system that is currently supported on the BlackBerry 7520 Wireless Handheld™. Audio is stored on the microprocessor and has a 250 kb limit. This means that audio recordings are restricted to a maximum of 8 minutes and 9 seconds.

Methods are provided to play and record audio files, and stop the process. You can also set and get the volume level, add and remove listeners, and test for device capabilities.

Returns Method Parameters
int playFile int audioCodex
int fs
String fileName

Use this method to play an audio file that exists within the flat file system. If the process is successful, the method AudioFileListener.audioFileOperationComplete() is invoked on the event thread. AudioFileListener.audioFileOperationFailed() will be invoked on the event thread if the process fails.

The "audioCodec" parameter is stated to be "one of the AUDIO_CODEC_" values within the JavaDocs. As of this date, one value has been defined: 

AUDIO_CODEC_VOICENOTES

This identifies Voicenote coded audio files.

The "fs" parameter is a one of the "File.FILESYSTEM_" values. As of this date, one value has been defined: 

FILESYSTEM_PATRIOT

This identifies the flat file system built into the BlackBerry 7520 handheld.

Make sure to check the latest JavaDocs for additional definitions for both parameters in the future.

The "fileName" parameter is the name of the audio file.

This method returns the audioCodec value used, and throws UnsupportedOperationException if an unsupported file system identifier is passed in parameter "fs"

Returns Method Parameters
int recordFile int audioCodex
int fs
String fileName

Use this method to record audio to the file system. The parameters are identical to playFile() except that the passed "fileName" is used to create a file rather than play an existing file. The AudioFileListener.audioFileOperationFailed() method is invoked on the event thread if the process fails.

This method returns the audioCodec value used, and throws UnsupportedOperationException if an unsupported file system identifier is passed in parameter "fs".

Returns Method Parameters
int stopFile int audioCodex
int fs
String fileName

Use this method to stop the recording or playing of an audio file. The parameters are identical to playFile(). If the process is successful, the AudioFileListener.audioFileOperationComplete() method will be invoked on the event thread. AudioFileListener.audioFileOperationFailed() will be invoked on the event thread if the process fails.

This method returns the audioCodec value used, and throws UnsupportedOperationException if an unsupported file system identifier is passed in parameter "fs".

Returns Method Parameter
int getVolume void

Returns the current audio level in percentage value: 0 to 100.

Returns Method Parameter
boolean setVolume int volume

Sets the audio level as a percentage of the maximum value from 0 to 100. This method returns false on error.

Returns Method Parameters
void addListener Application app
AudioListener listener

Used to add an application audio listener. The "app" parameter represents the application, while the "listener" parameter is the audio listener to register.

Returns Method Parameters
void removeListener Application app
AudioListener listener

Used to remove an audio listener from the passed application. The "app" parameter represents the application, while the "listener" parameter is the audio listener to de-register.

Returns Method Parameter
boolean isSupported void

Returns true if the device supports audio. Call this method before attempting any activity relating to VoiceNotes audio.

Returns Method Parameter
boolean isCodecSupported int codec

Returns true if the device supports the audio codec passed in parameter "codec".

Returns Method Parameter
boolean isHeadsetSupported void

Returns true if the device headset (earbud) is connected.

Returns Method Parameter
boolean hasBuiltInHeadset void

Returns true if the device has a built-in headset.

Fields

AUDIO_CODEC_VOICENOTE

  • Identifies a Voicenote audio file
  • Passed through the "audioCodec" parameter in the playFile(), recordFile() and stopFile() methods.

AUDIO_ERROR_BAD_DATA

  • Invalid data was provided

AUDIO_ERROR_BAD_STATE

  • Playback is already in progress

AUDIO_ERROR_FILESYSTEM_FULL

  • File system is full

AUDIO_ERROR_UNKNOWN

  • Unknown error

AUDIO_OK

  • No error

AUDIO_REQUEST_PENDING

  • Request pending

Audio Listeners

 

There are two audio listener interfaces provided, but you will only need to extend net.rim.device.api.system.AudioFileListener because it extends net.rim.device.api.system.AudioListener. Two methods and three fields are implemented.

Returns Method Parameter
void audioFileOperationComplete int operation

This method is automatically invoked after Audio.playFile() or Audio.stopFile() completes successfully. The "operation" parameter will be detailed shortly.

Returns Method Parameters
void audioFileOperationFailed int operation
int errorCode

This method is automatically invoked after Audio.playFile(), Audio.recordFile or Audio.stopFile() fails during execution. The "operation" parameter is detailed below. The "errorCode" parameter is one of the Audio.AUDIO_ERROR_ values.

Fields

There are three possible values for the "operation" parameter used in both methods. Each is self-explanatory:

  • OPERATION_PLAY
  • OPERATION_RECORD
  • OPERATION_STOP

net.rim.device.api.io.File
net.rim.device.api.io.FileInfo
net.rim.device.api.io.FileInputStream
net.rim.device.api.io.FileOutputStream

 

These classes are responsible for all low-level handling of files. As they are rarely used directly and may change as new BlackBerry devices are released in future, it would be best if you referred to the JavaDocs provided with the BlackBerry Java Development Environment to get further details.

Conclusion

The Voice Notes API provides a robust solution to recording audio that can help take an application from good to extraordinary. With over 8 minutes of recording capability (depending on memory availability), this API opens the door to a world of possibilities -- add basic audio functionality to any application or combine it with voice recognition technologies to create rich, powerful and in-demand applications. With Voice Notes, your voice is my command!

 

Please email your comments, suggestions and editorial submissions to

Related Links