Custom Audio Capture

Of course, using an intent to trigger the sound recorder isn't the only way we can capture audio. The Android SDK includes a MediaRecorder class, which we can leverage to build our own audio recording functionality. Doing so enables a lot more flexibility, such as controlling the length of time audio is recorded for.

The MediaRecorder class is used for both audio and video capture. After constructing a MediaRecorder object, to capture audio, the setAudioEncoder and setAudioSource methods must be called. If these methods are not called, audio will not be recorded. (The same goes for video. If setVideoEncoder and setVideoSource methods are not called, video will not be recorded. We won't be dealing with video in this chapter; therefore we won't use either of these methods.)

Additionally, two other methods are generally called before having the MediaRecorder prepare to record. These are setOutputFormat and setOutputFile. setOutputFormat allows us to choose what file format should be used for the recording and setOutputFile allows us to specify the file that we will record to. It is important to note that the order of each of these calls matters quite a bit.

MediaRecorder Audio Sources

The first method that should be called after the MediaRecorder is instantiated is setAudioSource. setAudioSource takes in a constant that is defined in the AudioSource inner class. Generally we will want to use MediaRecorder.AudioSource.MIC, but it is interesting to note that MediaRecorder.AudioSource also contains constants for VOICE_CALL, VOICE_DOWNLINK, and VOICE_UPLINK. Unfortunately, it appears as though there aren't any handsets or versions of Android where recording audio from the call actually works. Also of note, as of Froyo, Android version 2.2, there are constants for CAMCORDER and VOICE_RECOGNITION. These may be used if the device has more than one microphone.

MediaRecorder Output Formats

The next method to be called in sequence is setOutputFormat. The values this takes in are specified as constants in the MediaRecorder.OutputFormat inner class.

• MediaRecorder.OutputFormat.MPEG_4: This specifies that the file written will be an MPEG-4 file. It may contain both audio and video tracks.
• MediaRecorder.OutputFormat.RAW_AMR: This represents a raw file without any type of container. This should be used only when capturing audio without video and when the audio encoder is AMR_NB.
• MediaRecorder.OutputFormat.THREE_GPP: This specifies that the file written will be a 3GPP file (extension .3gp). It may contain both audio and video tracks.

MediaRecorder Audio Encoders

Following the setting of the output format, we can call setAudioEncoder to set the codec that should be used. The possible values are specified as constants in the MediaRecorder.AudioEncoder class and other than DEFAULT, only one other value exists: MediaRecorder.AudioEncoder.AMR_NB, which is the Adaptive Multi-Rate Narrow Band codec. This codec is tuned for speech and is therefore not a great choice for anything other than speech. By default it has a sample rate of 8 kHz and a bitrate between 4.75 and 12.2 kbps, both of which are very low for recoding anything but speech. Unfortunately, this is our only choice for use with the MediaRecorder at the moment.

MediaRecorder Output and Recording

Last, we'll want to call setOutputFile with the location of the file we want to record to. The following snippet of code creates a file using File.createTempFile in the preferred file location for applications that need to store files on the SD card.

Now we can actually call prepare, which signals the end of the configuration stage and tells the MediaRecorder to get ready to start recording. We call the start method to actually start recording.

To stop recording, we call the stop method.

MediaRecorder State Machine

The MediaRecorder, similar to the MediaPlayer, operates as a state machine. Figure 7–2 shows a diagram from the Android API reference page for MediaRecorder, which describes the various states and the methods that may be called from each state.

Figure 7–2. MediaRecorder state diagram from Android API Reference

MediaRecorder Example

Here is the code for a full custom audio capture and playback example using the MediaRecorder class.

Our CustomRecorder activity implements OnClickListener so that it may be notified when Buttons are pressed, and OnCompletionListener so that it can respond when MediaPlayer has completed playing audio.

We'll have a series of user interface components. The first, a TextView called statusTextView, will report the status of the application to the user: “Recording,” “Ready to Play,” and so on.

A series of buttons will be used for controlling various aspects. The names of the Buttons describe their use.

We'll have a MediaRecorder for recording the audio and a MediaPlayer for playing it back.

Finally, we have a File object called audioFile, which will reference the file that is recorded to.

When the activity starts up, we'll set the text of the statusTextView to be “Ready.”

We'll set all of the Buttons' onClickListeners to be this so that our onClick method is called when any of them are pressed.

Finally, in the onCreate method, we'll disable the stopRecording and playRecording Buttons since they won't work until we either start recording or finish recording respectively.

In the following onClick method, we handle all of the Button presses.

If the finishButton is pressed, we finish the activity.

If the stopRecording Button is pressed, we call stop and release on the MediaRecorder object.

We then construct a MediaPlayer object and have it prepare to play back the audio file that we just recorded.

The following two methods that we are using on the MediaPlayer, setDataSource and prepare, may throw a variety of exceptions. In the following code, we are simply throwing them. In your application development, you will probably want to catch and deal with them more elegantly, such as alerting the user when a file doesn't exist.

We set the statusTextView to indicate to the user that we are ready to play the audio file.

We then set the playRecording and startRecording Buttons to be enabled and disable the stopRecording Button, as we are not currently recording.

When the startRecording Button is pressed, we construct a new MediaRecorder and call setAudioSource, setOutputFormat, and setAudioEncoder.

We then create a new File on the SD card and call setOutputFile on the MediaRecorder object.

We call prepare on the MediaRecorder and start to begin the recording.

Last, we update the statusTextView and change which Buttons are enabled and disabled.

The last Button that we need to respond to is playRecording. When the stopRecording Button is pressed, the MediaPlayer object, player, is constructed and configured. All that we need to do when the playRecording Button is pushed is to start the playback, set the status message, and change which Buttons are enabled.

The onCompletion method is called when the MediaPlayer object has completed playback of a recording. We use it to change the status message and set which Buttons are enabled.

Here is the layout XML file, main.xml, for the foregoing activity.

We'll also need to add the following permissions to the AndroidManifest.xml file.

As we have seen, developing a custom audio capture application using MediaRecorder is not too cumbersome. Now let's look at how we can use the MediaRecorder's other methods to add other features.

Other MediaRecorder Methods

MediaRecorder has a variety of other methods available that we can use in relation to audio capture.

• getMaxAmplitude: Allows us to request the maximum amplitude of audio that has been recorded by the MediaPlayer. The value is reset each time the method is called, so each call will return the maximum amplitude from the last time it is called. An audio level meter may be implemented by calling this method periodically.
• setMaxDuration: Allows us to specify a maximum recording duration in milliseconds. This method must be called after the setOutputFormat method but before the prepare method.
• setMaxFileSize: Allows us to specify a maximum file size for the recording in bytes. As with setMaxDuration, this method must be called after the setOutputFormat method but before the prepare method.

Here is an update to the custom recorder application we went through previously that includes a display of the current amplitude.

In this version, we have added a TextView called amplitudeTextView. This will display the numeric amplitude of the audio input.

We'll need an instance of a new class called RecordAmplitude. This class is an inner class that is defined toward the end of this source code listing. It uses a Boolean called isRecording that will be set to true when we start the MediaRecorder.

We'll use a TextView to display the current amplitude of the audio as it is captured.

When we finish the recording, we set the isRecording Boolean to false and call cancel on our RecordAmplitude class. Since RecordAmplitude extends AsyncTask, calling cancel with true as the parameter will interrupt its thread if necessary.

After we start the recording, we set the isRecording Boolean to true and create a new instance of RecordAmplitude. Since RecordAmplitude extends AsyncTask, we'll call the execute method to start the RecordAmplitude's task running.

Here is the definition of RecordAmplitude. It extends AsyncTask, which is a nice utility class in Android that provides a thread to run long-running tasks without tying up the user interface or making an application unresponsive.

The doInBackground method runs on a separate thread and is run when the execute method is called on the object. This method loops as long as isRecording is true and calls Thread.sleep(500), which causes it to not do anything for half a second. Once that is complete, it calls publishProgress and passes in the result of getMaxAmplitude on the MediaRecorder object.

The preceding call to publishProgress calls the onProgressUpdate method defined here, which runs on the main thread so it can interact with the user interface. In this case, it is updating the amplitudeTextView with the value that is passed in from the publishProgress method call.

Of course, we'll need to update the layout XML to include the TextView for displaying the amplitude.

As we can see, using an AsyncTask to do something periodically is a nice way to provide automatically updating information to the user while something else is in progress. This provides a nicer user experience for our MediaRecorder example. Using the getMaxAmplitude method provides the user with some feedback about the recording that is currently happening.

In Android 2.2, Froyo, the following methods were made available:

• setAudioChannels: Allows us to specify the number of audio channels that will be recorded. Typically this will be either one channel (mono) or two channels (stereo). This method must be called prior to the prepare method.
• setAudioEncodingBitRate: Allows us to specify the number of bits per second that will be used by the encoder when compressing the audio. This method must be called prior to the prepare method.
• setAudioSamplingRate: Allows us to specify the sampling rate of the audio as it is captured and encoded. The applicable rates are determined by the hardware and codec being used. This method must be called prior to the prepare method.