Update sample code in documentation

bug - 3364497

Change-Id: I4cad247a403917aa7816350454c9ae3930dd3d25

1 files changed, 192 insertions, 53 deletions

diff --git a/docs/html/guide/topics/media/index.jd b/docs/html/guide/topics/media/index.jd
index e355212..b6d1629 100644
--- a/docs/html/guide/topics/media/index.jd
+++ b/docs/html/guide/topics/media/index.jd
@@ -148,70 +148,209 @@ myJet.play();
 <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);
-
-    values.put(MediaStore.MediaColumns.TITLE, SOME_NAME_HERE);
-    values.put(MediaStore.MediaColumns.TIMESTAMP, System.currentTimeMillis());
-    values.put(MediaStore.MediaColumns.MIME_TYPE, recorder.getMimeContentType());
-    
-    ContentResolver contentResolver = new ContentResolver();
-    
-    Uri base = MediaStore.Audio.INTERNAL_CONTENT_URI;
-    Uri newUri = contentResolver.insert(base, values);
-    
-    if (newUri == null) {
-        // need to handle exception here - we were not able to create a new
-        // content entry
+/*
+ * 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:
+ *
+ * &lt;uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /&gt;
+ * &lt;uses-permission android:name="android.permission.RECORD_AUDIO" /&gt;
+ *
+ */
+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();
+        }
     }
-    
-    String path = contentResolver.getDataFilePath(newUri);
-
-    // could use setPreviewDisplay() to display a preview to suitable View here
-    
-    recorder.setAudioSource(MediaRecorder.AudioSource.MIC);
-    recorder.setOutputFormat(MediaRecorder.OutputFormat.THREE_GPP);
-    recorder.setAudioEncoder(MediaRecorder.AudioEncoder.AMR_NB);
-    recorder.setOutputFile(path);
-    
-    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();
+
+    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");
+        }
+    }
+
+    private void stopPlaying() {
+        mPlayer.release();
+        mPlayer = null;
+    }
+
+    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");
+        }
+
+        mRecorder.start();
+    }
+
+    private void stopRecording() {
+        mRecorder.stop();
+        mRecorder.release();
+        mRecorder = null;
+    }
+
+    class RecordButton extends Button {
+        boolean mStartRecording = true;
+
+        OnClickListener clicker = new OnClickListener() {
+            public void onClick(View v) {
+                onRecord(mStartRecording);
+                if (mStartRecording) {
+                    setText("Stop recording");
+                } else {
+                    setText("Start recording");
+                }
+                mStartRecording = !mStartRecording;
+            }
+        };
+
+        public RecordButton(Context ctx) {
+            super(ctx);
+            setText("Start recording");
+            setOnClickListener(clicker);
+        }
+    }
+
+    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";
+    }
+
+    &#64;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);
+    }
+
+    &#64;Override
+    public void onPause() {
+        super.onPause();
+        if (mRecorder != null) {
+            mRecorder.release();
+            mRecorder = null;
+        }
+
+        if (mPlayer != null) {
+            mPlayer.release();
+            mPlayer = null;
+        }
+    }
+}
 </pre>
 
+