This document introduces the basic concepts you should
be familiar with before you work with Media Player.

## Sound and video classes

The following classes play sound and video in the Android framework:

- [`MediaPlayer`](https://developer.android.com/reference/android/media/MediaPlayer): This class is the primary API for playing sound and video.
- [`AudioManager`](https://developer.android.com/reference/android/media/AudioManager): This class manages audio sources and audio output on a device.

## Manifest declarations

Before you start development on your application using MediaPlayer, make sure
your manifest has the appropriate declarations to allow use of related features.

- **Internet Permission:** If you are using MediaPlayer to stream
  network-based content, your application must request network access.

      <uses-permission android:name="android.permission.INTERNET" />

- **Wake Lock Permission:** If your player application needs to keep the
  screen from dimming or the processor from sleeping, or uses the
  [`MediaPlayer.setScreenOnWhilePlaying(boolean)`](https://developer.android.com/reference/android/media/MediaPlayer#setScreenOnWhilePlaying(boolean)) or
  [`MediaPlayer.setWakeMode(android.content.Context, int)`](https://developer.android.com/reference/android/media/MediaPlayer#setWakeMode(android.content.Context,%20int)) methods, you
  must request this permission.

      <uses-permission android:name="android.permission.WAKE_LOCK" />

## Use the MediaPlayer class

The [`MediaPlayer`](https://developer.android.com/reference/android/media/MediaPlayer) class is n essential component of the media framework.
An object of this class can fetch, decode, and play
both audio and video with minimal setup. `MediaPlayer` supports several media
sources, including:

- Local resources
- Internal URIs, such as one you might obtain from a Content Resolver
- External URLs (streaming)

For a list of media formats that Android supports, see the [Supported Media
Formats](https://developer.android.com/guide/topics/media/media-formats) page.

### Examples of working with audio sources

Here is an example of how to play audio that's available as a local raw resource
(saved in your application's `res/raw/` directory):  

### Kotlin

    var mediaPlayer = MediaPlayer.create(context, R.raw.sound_file_1)
    mediaPlayer.start() // no need to call prepare(); create() does that for you

### Java

    MediaPlayer mediaPlayer = MediaPlayer.create(context, R.raw.sound_file_1);
    mediaPlayer.start(); // no need to call prepare(); create() does that for you

In this case, a "raw" resource is a file that the system does not try to parse
in any particular way. However, the content of this resource shouldn't be raw
audio. It should be a properly encoded and formatted media file in one of the
supported formats.

And here is how you might play from a URI available locally in the system (that
you obtained through a Content Resolver, for instance):  

### Kotlin

    val myUri: Uri = .... // initialize Uri here
    val mediaPlayer = MediaPlayer().apply {
        setAudioAttributes(
            AudioAttributes.Builder()
                .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
                .setUsage(AudioAttributes.USAGE_MEDIA)
                .build()
        )
        setDataSource(applicationContext, myUri)
        prepare()
        start()
    }

### Java

    Uri myUri = ....; // initialize Uri here
    MediaPlayer mediaPlayer = new MediaPlayer();
    mediaPlayer.setAudioAttributes(
        new AudioAttributes.Builder()
            .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
            .setUsage(AudioAttributes.USAGE_MEDIA)
            .build()
    );
    mediaPlayer.setDataSource(getApplicationContext(), myUri);
    mediaPlayer.prepare();
    mediaPlayer.start();

Playing from a remote URL using HTTP streaming looks like this:  

### Kotlin

    val url = "http://........" // your URL here
    val mediaPlayer = MediaPlayer().apply {
        setAudioAttributes(
            AudioAttributes.Builder()
                .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
                .setUsage(AudioAttributes.USAGE_MEDIA)
                .build()
        )
        setDataSource(url)
        prepare() // might take long! (for buffering, etc)
        start()
    }

### Java

    String url = "http://........"; // your URL here
    MediaPlayer mediaPlayer = new MediaPlayer();
    mediaPlayer.setAudioAttributes(
        new AudioAttributes.Builder()
            .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
            .setUsage(AudioAttributes.USAGE_MEDIA)
            .build()
    );
    mediaPlayer.setDataSource(url);
    mediaPlayer.prepare(); // might take long! (for buffering, etc)
    mediaPlayer.start();

| **Note:** If you're passing a URL to stream an online media file, the file must be capable of progressive download.
| **Caution:** You must either catch or pass [`IllegalArgumentException`](https://developer.android.com/reference/java/lang/IllegalArgumentException) and [`IOException`](https://developer.android.com/reference/java/io/IOException) when using [`setDataSource()`](https://developer.android.com/reference/android/media/MediaPlayer#setDataSource(android.content.Context,%20android.net.Uri)) because the file you are referencing might not exist.

## Use Asynchronous preparation to improve performance

Keep performance in mind when you use [`MediaPlayer`](https://developer.android.com/reference/android/media/MediaPlayer). For example, the call
to [`prepare()`](https://developer.android.com/reference/android/media/MediaPlayer#prepare()) can take a long time to execute, because it might involve
fetching and decoding media data. So, like any method that may take a long time
to execute, **never call it from your application's UI thread**. Doing so causes
the UI to stop responding until the method returns, which is a bad user
experience and can cause an ANR (Application Not Responding) error.

To avoid hanging your UI thread, spawn another thread to prepare the
[`MediaPlayer`](https://developer.android.com/reference/android/media/MediaPlayer) and notify the main thread when done. The framework supplies
a convenient way to accomplish the [`prepareAsync()`](https://developer.android.com/reference/android/media/MediaPlayer#prepareAsync()) method for doing this
task. This method starts preparing the media in the background and returns
immediately. When the media is done preparing, the [`onPrepared()`](https://developer.android.com/reference/android/media/MediaPlayer.OnPreparedListener#onPrepared(android.media.MediaPlayer)) method
of the [`MediaPlayer.OnPreparedListener`](https://developer.android.com/reference/android/media/MediaPlayer.OnPreparedListener), configured through
[`setOnPreparedListener()`](https://developer.android.com/reference/android/media/MediaPlayer#setOnPreparedListener(android.media.MediaPlayer.OnPreparedListener)) is called.

## Learn more

Jetpack Media3 is the recommended solution for media playback in your app. [Read
more](https://developer.android.com/media/media3) about it.

These pages cover topics relating to recording, storing, and playing back audio
and video:

- [Supported Media Formats](https://developer.android.com/guide/topics/media/media-formats)
- [MediaRecorder](https://developer.android.com/guide/topics/media/mediarecorder)
- [Data Storage](https://developer.android.com/guide/topics/data/data-storage)