path: root/docs/html/guide/topics/media/index.jd

page.title=Audio and Video
@jd:body

    <div id="qv-wrapper">
    <div id="qv">

<h2>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 Supported Media Formats</a></li>
</ul>

<h2>In this document</h2>
<ol>
<li><a href="#playback">Audio and Video Playback</a>
    <ol>
      <li><a href="#playraw">Playing from a Raw Resource</li>
      <li><a href="#playfile">Playing from a File or Stream</li>
      <li><a href="#jet">Playing JET Content</li>
    </ol>
</li>
<li><a href="#capture">Audio Capture</a></li>
</ol>

<h2>Key classes</h2>
<ol>
<li>{@link android.media.MediaPlayer MediaPlayer}</li>
<li>{@link android.media.MediaRecorder MediaRecorder}</li>
<li>{@link android.media.JetPlayer JetPlayer}</li>
<li>{@link android.media.SoundPool SoundPool}</li>
</ol>

<h2>See also</h2>
<ol>
<li><a href="{@docRoot}guide/topics/data/data-storage.html">Data Storage</a></li>
<li><a href="{@docRoot}guide/topics/media/jet/jetcreator_manual.html">JetCreator User Manual</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 and video, where supported by the
mobile device hardware. To record audio or video, use the {@link
android.media.MediaRecorder} class. Note that the emulator doesn't have hardware
to capture audio or video, but actual mobile devices are likely to provide these
capabilities, accessible through the MediaRecorder class. </p>

<p>For a list of 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="playback">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>
  <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>

<h3 id="jet">Playing JET content</h3>
<p>The Android platform includes a JET engine that lets you add interactive playback of JET audio content in your applications. You can create JET content for interactive playback using the JetCreator authoring application that ships with the SDK. To play and manage JET content from your application, use the {@link android.media.JetPlayer JetPlayer} class.</p>

<p>For a description of JET concepts and instructions on how to use the JetCreator authoring tool, see the <a href="{@docRoot}guide/topics/media/jet/jetcreator_manual.html">JetCreator User Manual</a>. The tool is available fully-featured on the OS X and Windows platforms and the Linux version supports all the content creation features, but not the auditioning of the imported assets. </p>

<p>Here's an example of how to set up JET playback from a .jet file stored on the SD card:</p>

<pre>
JetPlayer myJet = JetPlayer.getJetPlayer();
myJet.loadJetFile("/sdcard/level1.jet");
byte segmentId = 0;

// queue segment 5, repeat once, use General MIDI, transpose by -1 octave
myJet.queueJetSegment(5, -1, 1, -1, 0, segmentId++);
// queue segment 2
myJet.queueJetSegment(2, -1, 0, 0, 0, segmentId++);

myJet.play();
</pre>

<p>The SDK includes an example application &mdash; JetBoy &mdash; that shows how to use {@link android.media.JetPlayer JetPlayer} to create an interactive music soundtrack in your game. It also illustrates how to use JET events to synchronize music and game logic. The application is located at <code>&lt;sdk&gt;/platforms/android-1.5/samples/JetBoy</code>.

<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>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 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 MediaRecorder.prepare()}
   on the MediaRecorder instance.</li>
  <li>To start audio capture, call 
  {@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 MediaRecorder.release()} on it. Calling
{@link android.media.MediaRecorder#release MediaRecorder.release()} is always recommended to
free the resource immediately.</li>
</ol>

<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>
/*
 * 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();
        }
    }

    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>