docs/html/guide/topics/media/index.jd

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>