index.jd revision 6565a5a3002410583b7bdaa5147879032bc3bfb2
1page.title=Audio and Video 2@jd:body 3 4 <div id="qv-wrapper"> 5 <div id="qv"> 6 7<h2>Audio/Video quickview</h2> 8<ul> 9<li>Audio playback and record</li> 10<li>Video playback</li> 11<li>Handles data from raw resources, files, streams</li> 12<li>Built-in codecs for a variety of media. See <a href="{@docRoot}guide/appendix/media-formats.html">Android Supported Media Formats</a></li> 13</ul> 14 15<h2>Key classes</h2> 16<ol> 17<li><a href="{@docRoot}reference/android/media/MediaPlayer.html">MediaPlayer</a> (all audio and video formats)</li> 18<li><a href="{@docRoot}reference/android/media/MediaRecorder.html">MediaRecorder</a> (record, all audio formats)</li> 19</ol> 20 21<h2>In this document</h2> 22<ol> 23<li><a href="#playback.html">Audio and Video Playback</a></li> 24<li><a href="#capture">Audio Capture</a></li> 25</ol> 26 27<h2>See also</h2> 28<ol> 29<li><a href="{@docRoot}guide/topics/data/data-storage.html">Data Storage</a></li> 30</ol> 31 32</div> 33</div> 34 35<p>The Android platform offers built-in encoding/decoding for a variety of 36common media types, so that you can easily integrate audio, video, and images into your 37applications. Accessing the platform's media capabilities is fairly straightforward 38— you do so using the same intents and activities mechanism that the rest of 39Android uses.</p> 40 41<p>Android lets you play audio and video from several types of data sources. You 42can play audio or video from media files stored in the application's resources 43(raw resources), from standalone files in the filesystem, or from a data stream 44arriving over a network connection. To play audio or video from your 45application, use the {@link android.media.MediaPlayer} class.</p> 46 47<p>The platform also lets you record audio and video, where supported by the 48mobile device hardware. To record audio or video, use the {@link 49android.media.MediaRecorder} class. Note that the emulator doesn't have hardware 50to capture audio or video, but actual mobile devices are likely to provide these 51capabilities, accessible through the MediaRecorder class. </p> 52 53<p>For a list of media formats for which Android offers built-in support, 54see the <a href="{@docRoot}guide/appendix/media-formats.html">Android Media 55Formats</a> appendix. </p> 56 57<h2 id="play">Audio and Video Playback</h2> 58<p>Media can be played from anywhere: from a raw resource, from a file from the system, 59or from an available network (URL).</p> 60 61<p>You can play back the audio data only to the standard 62output device; currently, that is the mobile device speaker or Bluetooth headset. You 63cannot play sound files in the conversation audio. </p> 64 65<h3 id="playraw">Playing from a Raw Resource</h3> 66<p>Perhaps the most common thing to want to do is play back media (notably sound) 67within your own applications. Doing this is easy:</p> 68<ol> 69 <li>Put the sound (or other media resource) file into the <code>res/raw</code> 70 folder of your project, where the Eclipse plugin (or aapt) will find it and 71 make it into a resource that can be referenced from your R class</li> 72 <li>Create an instance of <code>MediaPlayer</code>, referencing that resource using 73 {@link android.media.MediaPlayer#create MediaPlayer.create}, and then call 74 {@link android.media.MediaPlayer#start() start()} on the instance:</li> 75</ol> 76<pre> 77 MediaPlayer mp = MediaPlayer.create(context, R.raw.sound_file_1); 78 mp.start(); 79</pre> 80<p>To stop playback, call {@link android.media.MediaPlayer#stop() stop()}. If 81you wish to later replay the media, then you must 82{@link android.media.MediaPlayer#reset() reset()} and 83{@link android.media.MediaPlayer#prepare() prepare()} the MediaPlayer object 84before calling {@link android.media.MediaPlayer#start() start()} again. 85(<code>create()</code> calls <code>prepare()</code> the first time.)</p> 86<p>To pause playback, call {@link android.media.MediaPlayer#pause() pause()}. 87Resume playback from where you paused with 88{@link android.media.MediaPlayer#start() start()}.</p> 89 90<h3 id="playfile">Playing from a File or Stream</h3> 91<p>You can play back media files from the filesystem or a web URL:</p> 92<ol> 93 <li>Create an instance of the <code>MediaPlayer</code> using <code>new</code></li> 94 <li>Call {@link android.media.MediaPlayer#setDataSource setDataSource()} 95 with a String containing the path (local filesystem or URL) 96 to the file you want to play</li> 97 <li>First {@link android.media.MediaPlayer#prepare prepare()} then 98 {@link android.media.MediaPlayer#start() start()} on the instance:</li> 99</ol> 100<pre> 101 MediaPlayer mp = new MediaPlayer(); 102 mp.setDataSource(PATH_TO_FILE); 103 mp.prepare(); 104 mp.start(); 105</pre> 106<p>{@link android.media.MediaPlayer#stop() stop()} and 107{@link android.media.MediaPlayer#pause() pause()} work the same as discussed 108above.</p> 109 <p class="note"><strong>Note:</strong> It is possible that <code>mp</code> could be 110 null, so good code should <code>null</code> check after the <code>new</code>. 111 Also, <code>IllegalArgumentException</code> and <code>IOException</code> either 112 need to be caught or passed on when using <code>setDataSource()</code>, since 113 the file you are referencing may not exist.</p> 114<p class="note"><strong>Note:</strong> 115If you're passing a URL to an online media file, the file must be capable of 116progressive download.</p> 117 118<h2 id="capture">Audio Capture</h2> 119<p>Audio capture from the device is a bit more complicated than audio/video playback, but still fairly simple:</p> 120<ol> 121 <li>Create a new instance of {@link android.media.MediaRecorder 122 android.media.MediaRecorder} using <code>new</code></li> 123 <li>Create a new instance of {@link android.content.ContentValues 124 android.content.ContentValues} and put in some standard properties like 125 <code>TITLE</code>, <code>TIMESTAMP</code>, and the all important 126 <code>MIME_TYPE</code></li> 127 <li>Create a file path for the data to go to (you can use {@link 128 android.content.ContentResolver android.content.ContentResolver} to 129 create an entry in the Content database and get it to assign a path 130 automatically which you can then use)</li> 131 <li>Set the audio source using {@link android.media.MediaRecorder#setAudioSource 132 MediaRecorder.setAudioSource()}. You will probably want to use 133 <code>MediaRecorder.AudioSource.MIC</code></li> 134 <li>Set output file format using {@link 135 android.media.MediaRecorder#setOutputFormat MediaRecorder.setOutputFormat()} 136 </li> 137 <li>Set the audio encoder using 138 {@link android.media.MediaRecorder#setAudioEncoder MediaRecorder.setAudioEncoder()} 139 </li> 140 <li>Call {@link android.media.MediaRecorder#prepare prepare()} 141 on the MediaRecorder instance.</li> 142 <li>To start audio capture, call 143 {@link android.media.MediaRecorder#start start()}. </li> 144 <li>To stop audio capture, call {@link android.media.MediaRecorder#stop stop()}. 145 <li>When you are done with the MediaRecorder instance, call 146{@link android.media.MediaRecorder#release release()} on it. </li> 147</ol> 148 149<h3>Example: Audio Capture Setup and Start</h3> 150<p>The example below illustrates how to set up, then start audio capture.</p> 151<pre> 152 recorder = new MediaRecorder(); 153 ContentValues values = new ContentValues(3); 154 155 values.put(MediaStore.MediaColumns.TITLE, SOME_NAME_HERE); 156 values.put(MediaStore.MediaColumns.TIMESTAMP, System.currentTimeMillis()); 157 values.put(MediaStore.MediaColumns.MIME_TYPE, recorder.getMimeContentType()); 158 159 ContentResolver contentResolver = new ContentResolver(); 160 161 Uri base = MediaStore.Audio.INTERNAL_CONTENT_URI; 162 Uri newUri = contentResolver.insert(base, values); 163 164 if (newUri == null) { 165 // need to handle exception here - we were not able to create a new 166 // content entry 167 } 168 169 String path = contentResolver.getDataFilePath(newUri); 170 171 // could use setPreviewDisplay() to display a preview to suitable View here 172 173 recorder.setAudioSource(MediaRecorder.AudioSource.MIC); 174 recorder.setOutputFormat(MediaRecorder.OutputFormat.THREE_GPP); 175 recorder.setAudioEncoder(MediaRecorder.AudioEncoder.AMR_NB); 176 recorder.setOutputFile(path); 177 178 recorder.prepare(); 179 recorder.start(); 180</pre> 181<h3>Stop Recording</h3> 182<p>Based on the example above, here's how you would stop audio capture. </p> 183<pre> 184 recorder.stop(); 185 recorder.release(); 186</pre> 187 188