Android Media APIs

The Android Platform boasts strong multimedia capabilities, as you would expect from a modern embedded operating system. Using the multimedia capabilities is fairly straightforward, going through the same intents and activities mechanism that the rest of Android uses.

Multimedia Capabilities

The Android platform is capable of playing both audio and video media. It is also capable of playing media contained in the resources for an application, or a standalone file in the filesystem, or even streaming media over a data connection. Playback is achieved through the android.media.MediaPlayer class.

The Android platform can also record audio. Video recording capabilities are coming in the future. This is achieved through the android.media.MediaRecorder class. While the emulator obviously doesn't have hardware to capture and record audio and video, the eventual devices will have these capabilities, and the APIs are there already to develop against.

Playing Media Resources

Media can be played from anywhere: a raw resource, a file from the system, or from an available network (URL).

Note: You can only send audio files to the standard output device; currently, that is the device speaker or a Bluetooth headset. You cannot currently play sound files in the conversation audio.

Playing a Raw Resource

Perhaps the most common thing to want to do is play back media (notably sound) within your own applications. Doing this is easy:

1. Put the sound (or other media resource) file into the res/raw 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
2. Create an instance of MediaPlayer, referencing that resource using MediaPlayer.create, and then call start() on the instance:
   
   

    MediaPlayer mp = MediaPlayer.create(context, R.raw.sound_file_1);
    mp.start();

To stop playback, call stop(). If you wish to later replay the media, then you must reset() and prepare() the MediaPlayer object before calling start() again. (create() calls prepare() the first time.)

To pause playback, call pause(). Resume playback from where you paused with start().

Playing a File

You can play back media files from the filesystem or a web URL:

1. Create an instance of the MediaPlayer using new
2. Call setDataSource() with a String containing the path (local filesystem or URL) to the file you want to play
3. First prepare() then start() on the instance:
   
   

    MediaPlayer mp = new MediaPlayer();
    mp.setDataSource(PATH_TO_FILE);
    mp.prepare();
    mp.start();

stop() and pause() work the same as discussed above.

Note: It is possible that mp could be null, so good code should null check after the new. Also, IllegalArgumentException and IOException either need to be caught or passed on when using setDataSource(), since the file you are referencing may not exist.

Note: If you're passing a URL to an online media file, the file must be capable of progressive download.

Recording Media Resources

Recording media is a little more involved than playing it back, as you would probably expect, but it is still fairly simple. There is just a little more set up to do

1. Create a new instance of android.media.MediaRecorder using new
2. Create a new instance of android.content.ContentValues and put in some standard properties like TITLE, TIMESTAMP, and the all important MIME_TYPE
3. Create a file path for the data to go to (you can use android.content.ContentResolver to create an entry in the Content database and get it to assign a path automatically which you can then use)
4. Set the audio source using MediaRecorder.setAudioSource(). You will probably want to use MediaRecorder.AudioSource.MIC
5. Set output file format using MediaRecorder.setOutputFormat()
6. Set the audio encoder using MediaRecorder.setAudioEncoder()
7. Finally, prepare() and start() the recording. stop() and release() when you are done

Here is a code example that will hopefully help fill in the gaps:

Start Recording

    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();

Stop Recording

    recorder.stop();
    recorder.release();