Audio Capture

This page describes the underpinnings of the Audio Recorder feature including the Service, Activity, and within the Chatterbox form.

Recording Service

The IAudioCaptureService interface lists methods that each AudioCaptureService must implement and all of the possible states that the service can be in.

Methods

String getName() - gets the name of this audio capture service
int getState() - retrieves the current state of this service and value returned must not be outside the range of the states defined in the interface
void startRecord() - begins capturing audio throws AudioException
void stopRecord() - stops capturing audio throws AudioException
void startPlayback() - begins audio playback throws AudioException
void stopPlayback() - stops audio playback throws AudioException
OutputStream getAudio() - returns the captured audio as an OutputStream
String getAudioPath() - retrieves the full path to the recorded audio
void saveRecording(String) - saves the recorded audio to a file
void void removeRecording() - removes the captured audio
void closeStreams() - closes all open streams; the AudioCaptureService must never be used in this state until it is reinstantiated

States

IDLE - intial state of the Service BR
CAPTURE_STARTED - audio capture has startedBR
CAPTURE_STOPPED - audio capture has stoppedBR
PLAYBACK_STARTED - audio playback has startedBR
PLAYBACK_STOPPED - audio playback has stoppedBR
CLOSED - all streams have been closed and this service can never be utilized without a complete instantiation BR

An AudioException corresponds to any type of error received by the service during an audio operation.

The J2MEAudioCaptureService is an example of a class that implements the IAudioCaptureService utilizing the J2ME Media Library.

Recording Activity

The AudioCaptureActivity is a multi-threaded Activity that utilizes a separate thread for recording audio and the initial thread for playback of the audio and responding to other commands. It makes heavy use of an AudioCaptureService, which if not available will immediately prevent the user from continuing to use the Activiy.

Activating the Menu command for the first time will unleash only one command:

The Activity will be in several modes corresponding to those stated in the IAudioCaptureServiceBR

'''Idle Mode'''

Record - begins the audio capture

Image(AC_IDLE.png)

'''Recording Mode'''

Stop - stops the audio capture
Save - stops the audio capture and saves the captured audio

'''Record Stopped Mode'''

Save - saves the captured audio
Record - begins the audio capture and prepares to save it under a new file name
Erase - erased the captured audio
Play - plays the captured audio
Finish - ends the current activity, closes all open streams, and passes the recorded audio if it were saved

Image(AC_CAP_STOP(w_Erase).png)

'''Playback Mode'''

Stop - stops the current playback
Finish - ends the playback and performs the same function as in the "Recorded Stopped Mode"

Image(AC_PLAY_START.png)

'''Playback Stopped Mode'''

Record - begins the audio capture and prepares to save it under a new file name
Save - saves the captured audio
Erase - erased the captured audio
Play - plays the captured audio
Finish - ends the current activity, closes all open streams, and passes the recorded audio if it were saved

'''Closed Mode'''

all open streams should be closed and the activity should not be present on the screen

Recording within the Forms

Capturing audio is integrated into the form via the AudioCaptureWidget. One must select the “Get Audio” command in the Recording entry and the AudioCaptureActivity will load. After recording the audio, saving it to a file, and pressing Finish, the Recording entry will be filled with the filename of the saved audio, and should proceed to the next option in the widget.

<h:html xmlns:jr="http://openrosa.org/javarosa">
<h:head>
    <h:title>CCPTZ Demo</h:title>
    <model>
    <instance>
        <data>
          <Subject>
            <Audio />            
          </Subject>          

          <DataCapture>
        <EnteredBy />
          </DataCapture>
        </data>
    </instance>
      <bind id="Audio" nodeset="/data/Subject/Audio" type="xsd:anyURI" />
      <!-- Other bindings excluded-->
    </model>
</h:head>           
<h:body>
     <upload bind="Audio" mediatype="audio/*">
      <label>Record Audio:</label>
      <hint>This will record an audio clip.</hint>
      <filename ref="@filename" />
      <mediatype ref="@mediatype" />
    </upload>
   <!-- Remainder of form -->
  </h:body>
</h:html>

Caveats

Unfortunately, audio records only to a WAV file, but someone has already written an MP3 encoder. It can be found at [http://www.javazoom.net/javalayer/javalayerme.html].

JAD Permissions

Assuming you've got a fully signed jar, you can enable your application to not prompt the user for permission to do audio recording. Unfortunately, the set of permissions required is pretty broad and very poorly documented. For Nokia S40 phones, the following set should be sufficient in the jad parameters. '''INCLUDE ALL OF THE PARAMETERS'''. Phones often reject using any of the interfaces unless they are all enabled.

MIDlet-Permissions: javax.microedition.media.control.RecordControl,javax.microedition.io.Connector.file.write,javax.microedition.io.Connector.file.read
MIDlet-Permissions-Opt: javax.microedition.media.protocol.Datasource,javax.microedition.media.control.RecordControl,javax.microedition.media.control.VideoControl.getSnapshot,javax.microedition.media.Player,javax.microedition.media.Manager

Note that the media permissions need to be in Opt because even on phones with the optional package Nokia rejects the permissions if they are not in Opt. Also be sure to remember to manually enable in the Nokia Phone Interface the "Always Allowed" setting for Data and Recording from '''Options->App. Access->Data access'''

Wiki

javarosa / AudioCapture