Code drop from //branches/cupcake/...@124589

2 files changed, 189 insertions, 0 deletions

diff --git a/docs/html/guide/topics/media/index.jd b/docs/html/guide/topics/media/index.jd
new file mode 100644
index 0000000..ba6d89f
--- /dev/null
+++ b/docs/html/guide/topics/media/index.jd
@@ -0,0 +1,188 @@
+page.title=Audio and Video
+@jd:body
+
+    <div id="qv-wrapper">
+    <div id="qv">
+
+<h2>Audio/Video quickview</h2>
+<ul>
+<li>Audio playback and record</li>
+<li>Video playback</li>
+<li>Handles data from raw resources, files, streams</li>
+<li>Built-in codecs for a variety of media. See <a href="{@docRoot}guide/appendix/media-formats.html">Android 1.0 Media Formats</a></li>
+</ul>
+
+<h2>Key classes</h2>
+<ol>
+<li><a href="{@docRoot}reference/android/media/MediaPlayer.html">MediaPlayer</a> (all audio and video formats)</li>
+<li><a href="{@docRoot}reference/android/media/MediaRecorder.html">MediaRecorder</a> (record, all audio formats)</li>
+</ol>
+
+<h2>In this document</h2>
+<ol>
+<li><a href="#playback.html">Audio and Video Playback</a></li>
+<li><a href="#capture">Audio Capture</a></li>
+</ol>
+
+<h2>See also</h2>
+<ol>
+<li><a href="{@docRoot}guide/topics/data/data-storage.html">Data Storage</a></li>
+</ol>
+
+</div>
+</div>
+
+<p>The Android platform offers built-in encoding/decoding for a variety of
+common media types, so that you can easily integrate audio, video, and images into your
+applications. Accessing the platform's media capabilities is fairly straightforward 
+&mdash; you do so using the same intents and activities mechanism that the rest of
+Android uses.</p>
+
+<p>Android lets you play audio and video from several types of data sources. You
+can play audio or video from media files stored in the application's resources
+(raw resources), from standalone files in the filesystem, or from a data stream
+arriving over a network connection. To play audio or video from your
+application, use the {@link android.media.MediaPlayer} class.</p>
+
+<p>The platform also lets you record audio, where supported by the mobile device
+hardware. Recording of video is not currently supported, but is planned for a
+future release. To record audio, use the 
+{@link android.media.MediaRecorder} class. Note that the emulator doesn't have
+hardware to capture audio, but actual mobile devices are likely to provide these
+capabilities that you can access through MediaRecorder. </p>
+
+<p>For a list of the media formats for which Android offers built-in support,
+see the <a href="{@docRoot}guide/appendix/media-formats.html">Android Media
+Formats</a> appendix. </p>
+
+<h2 id="play">Audio and Video Playback</h2>
+<p>Media can be played from anywhere: from a raw resource, from a file from the system, 
+or from an available network (URL).</p>
+  
+<p>You can play back the audio data only to the standard
+output device; currently, that is the mobile device speaker or Bluetooth headset. You
+cannot play sound files in the conversation audio. </p>
+
+<h3 id="playraw">Playing from a Raw Resource</h3>
+<p>Perhaps the most common thing to want to do is play back media (notably sound)
+within your own applications. Doing this is easy:</p>
+<ol>
+  <li>Put the sound (or other media resource) file into the <code>res/raw</code>
+  folder of your project, where the Eclipse plugin (or aapt) will find it and
+  make it into a resource that can be referenced from your R class</li>
+  <li>Create an instance of <code>MediaPlayer</code>, referencing that resource using
+  {@link android.media.MediaPlayer#create MediaPlayer.create}, and then call
+  {@link android.media.MediaPlayer#start() start()} on the instance:</li>
+</ol>
+<pre>
+    MediaPlayer mp = MediaPlayer.create(context, R.raw.sound_file_1);
+    mp.start();
+</pre>
+<p>To stop playback, call {@link android.media.MediaPlayer#stop() stop()}. If 
+you wish to later replay the media, then you must 
+{@link android.media.MediaPlayer#reset() reset()} and
+{@link android.media.MediaPlayer#prepare() prepare()} the MediaPlayer object
+before calling {@link android.media.MediaPlayer#start() start()} again. 
+(<code>create()</code> calls <code>prepare()</code> the first time.)</p>
+<p>To pause playback, call {@link android.media.MediaPlayer#pause() pause()}. 
+Resume playback from where you paused with 
+{@link android.media.MediaPlayer#start() start()}.</p>
+
+<h3 id="playfile">Playing from a File or Stream</h3>
+<p>You can play back media files from the filesystem or a web URL:</p>
+<ol>
+  <li>Create an instance of the <code>MediaPlayer</code> using <code>new</code></li>
+  <li>Call {@link android.media.MediaPlayer#setDataSource setDataSource()}
+    with a String containing the path (local filesystem or URL)
+    to the file you want to play</li>
+  <li>First {@link android.media.MediaPlayer#prepare prepare()} then
+  {@link android.media.MediaPlayer#start() start()} on the instance:</li>
+</ol>
+<pre>
+    MediaPlayer mp = new MediaPlayer();
+    mp.setDataSource(PATH_TO_FILE);
+    mp.prepare();
+    mp.start();
+</pre>
+<p>{@link android.media.MediaPlayer#stop() stop()} and 
+{@link android.media.MediaPlayer#pause() pause()} work the same as discussed
+above.</p>
+  <p class="note"><strong>Note:</strong> It is possible that <code>mp</code> could be
+  null, so good code should <code>null</code> check after the <code>new</code>.
+  Also, <code>IllegalArgumentException</code> and <code>IOException</code> either
+  need to be caught or passed on when using <code>setDataSource()</code>, since
+  the file you are referencing may not exist.</p>
+<p class="note"><strong>Note:</strong>
+If you're passing a URL to an online media file, the file must be capable of 
+progressive download.</p>
+
+<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
+  <code>MediaRecorder.AudioSource.MIC</code></li>
+  <li>Set output file format using {@link 
+        android.media.MediaRecorder#setOutputFormat MediaRecorder.setOutputFormat()}
+  </li>
+  <li>Set the audio encoder using 
+        {@link android.media.MediaRecorder#setAudioEncoder MediaRecorder.setAudioEncoder()}
+  </li>
+  <li>Call {@link android.media.MediaRecorder#prepare 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()}.
+  <li>When you are done with the MediaRecorder instance, call
+{@link android.media.MediaRecorder#release release()} on it. </li>
+</ol>
+
+<h3>Example: Audio Capture Setup and Start</h3>
+<p>The example below illustrates how to set up, then start audio capture.</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
+    }
+    
+    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();
+</pre>
+
diff --git a/docs/html/guide/topics/media/media.jd b/docs/html/guide/topics/media/media.jd
index 16ad2b7..463686d 100644
--- a/docs/html/guide/topics/media/media.jd
+++ b/docs/html/guide/topics/media/media.jd
@@ -28,6 +28,7 @@ page.title=Media Capabilities
 <li>{@link android.media.MediaPlayer} (playback, all audio and video formats)</li>
 <li>{@link android.media.MediaRecorder} (record, all audio formats)</li>
 </ul>
+</div>
 
 <p>The Android platform offers built-in encoding/decoding for a variety of common media types, 
 so that you can easily integrate audio, video, and images into your applications. Accessing the platform's media