am d24d00ae: am f9e7442a: Update sample code in documentation

<h2 id="capture">Audio Capture</h2>

<p>Audio capture from the device is a bit more complicated than audio/video playback, but still fairly simple:</p>

<ol>

  <li>Create a new instance of {@link android.media.MediaRecorder 

  android.media.MediaRecorder} using <code>new</code></li>

  <li>Create a new instance of {@link android.content.ContentValues 

  android.content.ContentValues} and put in some standard properties like

  <code>TITLE</code>, <code>TIMESTAMP</code>, and the all important 

  <code>MIME_TYPE</code></li>

  <li>Create a file path for the data to go to (you can use {@link

  android.content.ContentResolver android.content.ContentResolver} to

  create an entry in the Content database and get it to assign a path

  automatically which you can then use)</li>

  <li>Set the audio source using {@link android.media.MediaRecorder#setAudioSource

  MediaRecorder.setAudioSource()}. You will probably want to use

  <li>Create a new instance of {@link android.media.MediaRecorder android.media.MediaRecorder} using <code>new</code></li>

  <li>Set the audio source using

        {@link android.media.MediaRecorder#setAudioSource MediaRecorder.setAudioSource()}. You will probably want to use

  <code>MediaRecorder.AudioSource.MIC</code></li>

  <li>Set output file format using {@link 

        android.media.MediaRecorder#setOutputFormat MediaRecorder.setOutputFormat()}

  <li>Set output file format using

        {@link android.media.MediaRecorder#setOutputFormat MediaRecorder.setOutputFormat()}

  </li>

  <li>Set output file name using

        {@link android.media.MediaRecorder#setOutputFile MediaRecorder.setOutputFile()}

  </li>

  <li>Set the audio encoder using 

        {@link android.media.MediaRecorder#setAudioEncoder MediaRecorder.setAudioEncoder()}

  </li>

  <li>Call {@link android.media.MediaRecorder#prepare prepare()} 

  <li>Call {@link android.media.MediaRecorder#prepare MediaRecorder.prepare()}

   on the MediaRecorder instance.</li>

  <li>To start audio capture, call 

  {@link android.media.MediaRecorder#start start()}. </li>

  <li>To stop audio capture, call {@link android.media.MediaRecorder#stop stop()}.

  {@link android.media.MediaRecorder#start MediaRecorder.start()}. </li>

  <li>To stop audio capture, call {@link android.media.MediaRecorder#stop MediaRecorder.stop()}.

  <li>When you are done with the MediaRecorder instance, call

{@link android.media.MediaRecorder#release release()} on it. </li>

{@link android.media.MediaRecorder#release MediaRecorder.release()} on it. Calling

{@link android.media.MediaRecorder#release MediaRecorder.release()} is always recommended to

free the resource immediately.</li>

</ol>

<h3>Example: Audio Capture Setup and Start</h3>

<p>The example below illustrates how to set up, then start audio capture.</p>

<h3>Example: Record audio and play the recorded audio</h3>

<p>The example class below illustrates how to set up, start and stop audio capture, and to play the recorded audio file.</p>

<pre>

    recorder = new MediaRecorder();

    ContentValues values = new ContentValues(3);

/*

 * The application needs to have the permission to write to external storage

 * if the output file is written to the external storage, and also the

 * permission to record audio. These permissions must be set in the

 * application's AndroidManifest.xml file, with something like:

 *

 * <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

 * <uses-permission android:name="android.permission.RECORD_AUDIO" />

 *

 */

package com.android.audiorecordtest;

import android.app.Activity;

import android.widget.LinearLayout;

import android.os.Bundle;

import android.os.Environment;

import android.view.ViewGroup;

import android.widget.Button;

import android.view.View;

import android.view.View.OnClickListener;

import android.content.Context;

import android.util.Log;

import android.media.MediaRecorder;

import android.media.MediaPlayer;

import java.io.IOException;

public class AudioRecordTest extends Activity

{

    private static final String LOG_TAG = "AudioRecordTest";

    private static String mFileName = null;

    private RecordButton mRecordButton = null;

    private MediaRecorder mRecorder = null;

    private PlayButton   mPlayButton = null;

    private MediaPlayer   mPlayer = null;

    private void onRecord(boolean start) {

        if (start) {

            startRecording();

        } else {

            stopRecording();

        }

    }

    private void onPlay(boolean start) {

        if (start) {

            startPlaying();

        } else {

            stopPlaying();

        }

    }

    private void startPlaying() {

        mPlayer = new MediaPlayer();

        try {

            mPlayer.setDataSource(mFileName);

            mPlayer.prepare();

            mPlayer.start();

        } catch (IOException e) {

            Log.e(LOG_TAG, "prepare() failed");

        }

    }

    values.put(MediaStore.MediaColumns.TITLE, SOME_NAME_HERE);

    values.put(MediaStore.MediaColumns.TIMESTAMP, System.currentTimeMillis());

    values.put(MediaStore.MediaColumns.MIME_TYPE, recorder.getMimeContentType());

    private void stopPlaying() {

        mPlayer.release();

        mPlayer = null;

    }

    ContentResolver contentResolver = new ContentResolver();

    private void startRecording() {

        mRecorder = new MediaRecorder();

        mRecorder.setAudioSource(MediaRecorder.AudioSource.MIC);

        mRecorder.setOutputFormat(MediaRecorder.OutputFormat.THREE_GPP);

        mRecorder.setOutputFile(mFileName);

        mRecorder.setAudioEncoder(MediaRecorder.AudioEncoder.AMR_NB);

        try {

            mRecorder.prepare();

        } catch (IOException e) {

            Log.e(LOG_TAG, "prepare() failed");

        }

    Uri base = MediaStore.Audio.INTERNAL_CONTENT_URI;

    Uri newUri = contentResolver.insert(base, values);

        mRecorder.start();

    }

    if (newUri == null) {

        // need to handle exception here - we were not able to create a new

        // content entry

    private void stopRecording() {

        mRecorder.stop();

        mRecorder.release();

        mRecorder = null;

    }

    String path = contentResolver.getDataFilePath(newUri);

    class RecordButton extends Button {

        boolean mStartRecording = true;

    // could use setPreviewDisplay() to display a preview to suitable View here

        OnClickListener clicker = new OnClickListener() {

            public void onClick(View v) {

                onRecord(mStartRecording);

                if (mStartRecording) {

                    setText("Stop recording");

                } else {

                    setText("Start recording");

                }

                mStartRecording = !mStartRecording;

            }

        };

    recorder.setAudioSource(MediaRecorder.AudioSource.MIC);

    recorder.setOutputFormat(MediaRecorder.OutputFormat.THREE_GPP);

    recorder.setAudioEncoder(MediaRecorder.AudioEncoder.AMR_NB);

    recorder.setOutputFile(path);

        public RecordButton(Context ctx) {

            super(ctx);

            setText("Start recording");

            setOnClickListener(clicker);

        }

    }

    recorder.prepare();

    recorder.start();

</pre>

<h3>Stop Recording</h3>

<p>Based on the example above, here's how you would stop audio capture. </p>

<pre>

    recorder.stop();

    recorder.release();

    class PlayButton extends Button {

        boolean mStartPlaying = true;

        OnClickListener clicker = new OnClickListener() {

            public void onClick(View v) {

                onPlay(mStartPlaying);

                if (mStartPlaying) {

                    setText("Stop playing");

                } else {

                    setText("Start playing");

                }

                mStartPlaying = !mStartPlaying;

            }

        };

        public PlayButton(Context ctx) {

            super(ctx);

            setText("Start playing");

            setOnClickListener(clicker);

        }

    }

    public AudioRecordTest() {

        mFileName = Environment.getExternalStorageDirectory().getAbsolutePath();

        mFileName += "/audiorecordtest.3gp";

    }

    @Override

    public void onCreate(Bundle icicle) {

        super.onCreate(icicle);

        LinearLayout ll = new LinearLayout(this);

        mRecordButton = new RecordButton(this);

        ll.addView(mRecordButton,

            new LinearLayout.LayoutParams(

                ViewGroup.LayoutParams.WRAP_CONTENT,

                ViewGroup.LayoutParams.WRAP_CONTENT,

                0));

        mPlayButton = new PlayButton(this);

        ll.addView(mPlayButton,

            new LinearLayout.LayoutParams(

                ViewGroup.LayoutParams.WRAP_CONTENT,

                ViewGroup.LayoutParams.WRAP_CONTENT,

                0));

        setContentView(ll);

    }

    @Override

    public void onPause() {

        super.onPause();

        if (mRecorder != null) {

            mRecorder.release();

            mRecorder = null;

        }

        if (mPlayer != null) {

            mPlayer.release();

            mPlayer = null;

        }

    }

}

</pre>