# MediaSession.Builder

Artifact: [androidx.media3:media3-session](https://developer.android.com/jetpack/androidx/releases/media3) [View Source](https://cs.android.com/search?q=file:androidx/media3/session/MediaSession.java+class:androidx.media3.session.MediaSession.Builder)

*** ** * ** ***


```
public final class MediaSession.Builder
```

<br />

*** ** * ** ***

A builder for `https://developer.android.com/reference/androidx/media3/session/MediaSession`.

Any incoming requests from the `https://developer.android.com/reference/androidx/media3/session/MediaController` will be handled on the application thread of the underlying `https://developer.android.com/reference/androidx/media3/common/Player`.

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder#Builder(android.content.Context,androidx.media3.common.Player)(https://developer.android.com/reference/android/content/Context.html context, https://developer.android.com/reference/androidx/media3/common/Player player)` Creates a builder for `https://developer.android.com/reference/androidx/media3/session/MediaSession`. |

| ### Public methods |
|---|---|
| `https://developer.android.com/reference/androidx/media3/session/MediaSession` | `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder#build()()` Builds a `https://developer.android.com/reference/androidx/media3/session/MediaSession`. |
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | `@https://developer.android.com/reference/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder#setBitmapLoader(androidx.media3.common.util.BitmapLoader)(https://developer.android.com/reference/androidx/media3/common/util/BitmapLoader bitmapLoader)` Sets a `https://developer.android.com/reference/androidx/media3/common/util/BitmapLoader` for the `https://developer.android.com/reference/androidx/media3/session/MediaSession` to decode bitmaps from compressed binary data or load bitmaps from `https://developer.android.com/reference/android/net/Uri.html`. |
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder#setCallback(androidx.media3.session.MediaSession.Callback)(https://developer.android.com/reference/androidx/media3/session/MediaSession.Callback callback)` Sets a callback for the `https://developer.android.com/reference/androidx/media3/session/MediaSession` to handle incoming requests from {link MediaController}. |
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | `@https://developer.android.com/reference/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder#setCommandButtonsForMediaItems(java.util.List<androidx.media3.session.CommandButton>)(https://developer.android.com/reference/java/util/List.html<https://developer.android.com/reference/androidx/media3/session/CommandButton> commandButtons)` Sets `https://developer.android.com/reference/androidx/media3/session/CommandButton` that can be added as `https://developer.android.com/reference/androidx/media3/common/MediaMetadata.Builder#setSupportedCommands(java.util.List<java.lang.String>)`. |
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html @https://developer.android.com/reference/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder#setCustomLayout(java.util.List<androidx.media3.session.CommandButton>)(https://developer.android.com/reference/java/util/List.html<https://developer.android.com/reference/androidx/media3/session/CommandButton> customLayout)` Sets the custom layout of the session. |
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html @https://developer.android.com/reference/androidx/media3/common/util/ExperimentalApi https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder#setExperimentalSetUseLegacySurfaceHandling(boolean)( boolean useLegacySurfaceHandling )` Sets whether to use the legacy surface handling logic by ignoring the surface size. |
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder#setExtras(android.os.Bundle)(https://developer.android.com/reference/android/os/Bundle.html tokenExtras)` Sets an extras `https://developer.android.com/reference/android/os/Bundle.html` for the `https://developer.android.com/reference/androidx/media3/session/MediaSession#getToken()`. |
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder#setId(java.lang.String)(https://developer.android.com/reference/java/lang/String.html id)` Sets an ID of the `https://developer.android.com/reference/androidx/media3/session/MediaSession`. |
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html @https://developer.android.com/reference/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder#setMediaButtonPreferences(java.util.List<androidx.media3.session.CommandButton>)(https://developer.android.com/reference/java/util/List.html<https://developer.android.com/reference/androidx/media3/session/CommandButton> mediaButtonPreferences)` Sets the media button preferences. |
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | `@https://developer.android.com/reference/androidx/media3/common/util/UnstableApi @https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html @https://developer.android.com/reference/androidx/annotation/RequiresPermission(value = "android.permission.OVERRIDE_MEDIA_SESSION_OWNER") https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder#setPackageNameOverride(java.lang.String)(https://developer.android.com/reference/java/lang/String.html packageNameOverride)` Overrides the package name of the session created. |
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | `@https://developer.android.com/reference/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder#setPeriodicPositionUpdateEnabled(boolean)(boolean isEnabled)` Sets whether periodic position updates should be sent to controllers while playing. |
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder#setSessionActivity(android.app.PendingIntent)(https://developer.android.com/reference/android/app/PendingIntent.html pendingIntent)` Sets a `https://developer.android.com/reference/android/app/PendingIntent.html` to launch an `https://developer.android.com/reference/android/app/Activity.html` for the `https://developer.android.com/reference/androidx/media3/session/MediaSession`. |
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder#setSessionExtras(android.os.Bundle)(https://developer.android.com/reference/android/os/Bundle.html sessionExtras)` Sets the `https://developer.android.com/reference/androidx/media3/session/MediaSession#getSessionExtras()`. |
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | `@https://developer.android.com/reference/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder#setShowPlayButtonIfPlaybackIsSuppressed(boolean)( boolean showPlayButtonIfPlaybackIsSuppressed )` Sets whether a play button is shown if playback is `https://developer.android.com/reference/androidx/media3/common/Player#getPlaybackSuppressionReason()`. |

| ### Protected methods |
|---|---|
| `final void` | `@https://checkerframework.org/api/org/checkerframework/checker/nullness/qual/EnsuresNonNull.html(value = "bitmapLoader") https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder#ensureBitmapLoaderIsSizeLimited()()` Updates bitmap loader to ensure its using the maximum media session size limit. |

## Public constructors

### Builder

```
public Builder(Context context, Player player)
```

Creates a builder for `https://developer.android.com/reference/androidx/media3/session/MediaSession`.

| Parameters |
|---|---|
| `https://developer.android.com/reference/android/content/Context.html context` | The context. |
| `https://developer.android.com/reference/androidx/media3/common/Player player` | The underlying player to perform playback and handle player commands. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if `https://developer.android.com/reference/androidx/media3/common/Player#canAdvertiseSession()` returns false. |

## Public methods

### build

```
public MediaSession build()
```

Builds a `https://developer.android.com/reference/androidx/media3/session/MediaSession`.

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media3/session/MediaSession` | A new session. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if a `https://developer.android.com/reference/androidx/media3/session/MediaSession` with the same `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder#setId(java.lang.String)` already exists in the package. |

### setBitmapLoader

```
@UnstableApi
public MediaSession.Builder setBitmapLoader(BitmapLoader bitmapLoader)
```

Sets a `https://developer.android.com/reference/androidx/media3/common/util/BitmapLoader` for the `https://developer.android.com/reference/androidx/media3/session/MediaSession` to decode bitmaps from compressed binary data or load bitmaps from `https://developer.android.com/reference/android/net/Uri.html`.

The provided instance will likely be called repeatedly with the same request, so it would be best if any provided instance does some caching. Simple caching can be added to any `https://developer.android.com/reference/androidx/media3/common/util/BitmapLoader` implementation by wrapping it in `https://developer.android.com/reference/androidx/media3/session/CacheBitmapLoader` before passing it to this method.

If no instance is set, a `https://developer.android.com/reference/androidx/media3/session/CacheBitmapLoader` with a `https://developer.android.com/reference/androidx/media3/datasource/DataSourceBitmapLoader` inside will be used.

| Parameters |
|---|---|
| `https://developer.android.com/reference/androidx/media3/common/util/BitmapLoader bitmapLoader` | The bitmap loader `https://developer.android.com/reference/androidx/media3/common/util/BitmapLoader`. |

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | The builder to allow chaining. |

### setCallback

```
public MediaSession.Builder setCallback(MediaSession.Callback callback)
```

Sets a callback for the `https://developer.android.com/reference/androidx/media3/session/MediaSession` to handle incoming requests from {link MediaController}.

Apps that want to allow controllers to `https://developer.android.com/reference/androidx/media3/session/MediaController#setMediaItems(java.util.List<androidx.media3.common.MediaItem>)` or `https://developer.android.com/reference/androidx/media3/session/MediaController#addMediaItems(java.util.List<androidx.media3.common.MediaItem>)` media items to the playlist, must use a callback and override its `https://developer.android.com/reference/androidx/media3/session/MediaSession.Callback#onSetMediaItems(androidx.media3.session.MediaSession,androidx.media3.session.MediaSession.ControllerInfo,java.util.List<androidx.media3.common.MediaItem>,int,long)` or `https://developer.android.com/reference/androidx/media3/session/MediaSession.Callback#onSetMediaItems(androidx.media3.session.MediaSession,androidx.media3.session.MediaSession.ControllerInfo,java.util.List<androidx.media3.common.MediaItem>,int,long)` methods.

| Parameters |
|---|---|
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Callback callback` | The callback. |

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | The builder to allow chaining. |

### setCommandButtonsForMediaItems

```
@UnstableApi
public MediaSession.Builder setCommandButtonsForMediaItems(List<CommandButton> commandButtons)
```

Sets `https://developer.android.com/reference/androidx/media3/session/CommandButton` that can be added as `https://developer.android.com/reference/androidx/media3/common/MediaMetadata.Builder#setSupportedCommands(java.util.List<java.lang.String>)`.

| Parameters |
|---|---|
| `https://developer.android.com/reference/java/util/List.html<https://developer.android.com/reference/androidx/media3/session/CommandButton> commandButtons` | The command buttons. |

### setCustomLayout

```
@CanIgnoreReturnValue
@UnstableApi
public MediaSession.Builder setCustomLayout(List<CommandButton> customLayout)
```

Sets the custom layout of the session.

This method will be deprecated, prefer to use `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder#setMediaButtonPreferences(java.util.List<androidx.media3.session.CommandButton>)`. Note that the media button preferences use `https://developer.android.com/reference/androidx/media3/session/CommandButton#slots()` to define the allowed button placement.

The button are converted to custom actions in the platform media session playback state for platform or legacy `android.support.v4.media.session.MediaControllerCompat` controllers (see `
PlaybackStateCompat.Builder#addCustomAction(PlaybackStateCompat.CustomAction)`). When converting, the `https://developer.android.com/reference/androidx/media3/session/SessionCommand#customExtras()` is used for the extras of the platform custom action.

Controllers that connect have the custom layout of the session available with the initial connection result by default. A custom layout specific to a controller can be set when the controller `https://developer.android.com/reference/androidx/media3/session/MediaSession.Callback#onConnectAsync(androidx.media3.session.MediaSession,androidx.media3.session.MediaSession.ControllerInfo)` by using an `https://developer.android.com/reference/androidx/media3/session/MediaSession.ConnectionResult.AcceptedResultBuilder`.

Use `MediaSession.setCustomLayout(..)` to update the custom layout during the life time of the session.

On the controller side, the `https://developer.android.com/reference/androidx/media3/session/CommandButton#isEnabled()` flag is set to `false` if the available commands of a controller do not allow to use a button.

| Parameters |
|---|---|
| `https://developer.android.com/reference/java/util/List.html<https://developer.android.com/reference/androidx/media3/session/CommandButton> customLayout` | The ordered list of `https://developer.android.com/reference/androidx/media3/session/CommandButton`. |

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | The builder to allow chaining. |

### setExperimentalSetUseLegacySurfaceHandling

```
@CanIgnoreReturnValue
@ExperimentalApi
public MediaSession.Builder setExperimentalSetUseLegacySurfaceHandling(
    boolean useLegacySurfaceHandling
)
```

Sets whether to use the legacy surface handling logic by ignoring the surface size.

When set to `true`, the session will call `https://developer.android.com/reference/androidx/media3/common/Player#setVideoSurface(android.view.Surface)` directly, which may not work correctly with video effects. This is intended as a temporary opt-out for applications that experience issues with the new SurfaceHolder-based approach.

This method is experimental and may be removed in a future release.

| Parameters |
|---|---|
| `boolean useLegacySurfaceHandling` | Whether to use the legacy surface handling logic. |

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | This builder. |

### setExtras

```
public MediaSession.Builder setExtras(Bundle tokenExtras)
```

Sets an extras `https://developer.android.com/reference/android/os/Bundle.html` for the `https://developer.android.com/reference/androidx/media3/session/MediaSession#getToken()`. If not set, `https://developer.android.com/reference/android/os/Bundle.html#EMPTY` is used.

A controller has access to these extras through the `https://developer.android.com/reference/androidx/media3/session/MediaController#getConnectedToken()`.

| Parameters |
|---|---|
| `https://developer.android.com/reference/android/os/Bundle.html tokenExtras` | The extras `https://developer.android.com/reference/android/os/Bundle.html`. |

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | The builder to allow chaining. |

### setId

```
public MediaSession.Builder setId(String id)
```

Sets an ID of the `https://developer.android.com/reference/androidx/media3/session/MediaSession`. If not set, an empty string will be used.

Use this if and only if your app supports multiple playback at the same time and also wants to provide external apps to have finer-grained controls.

| Parameters |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html id` | The ID. Must be unique among all `https://developer.android.com/reference/androidx/media3/session/MediaSession` per package. |

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | The builder to allow chaining. |

### setMediaButtonPreferences

```
@CanIgnoreReturnValue
@UnstableApi
public MediaSession.Builder setMediaButtonPreferences(List<CommandButton> mediaButtonPreferences)
```

Sets the media button preferences.

The button are converted to custom actions in the platform media session playback state for platform or legacy `android.support.v4.media.session.MediaControllerCompat` controllers (see `
PlaybackStateCompat.Builder#addCustomAction(PlaybackStateCompat.CustomAction)`). When converting, the `https://developer.android.com/reference/androidx/media3/session/SessionCommand#customExtras()` is used for the extras of the platform custom action.

Controllers that connect have the media button preferences of the session available with the initial connection result by default. Media button preferences specific to a controller can be set when the controller `https://developer.android.com/reference/androidx/media3/session/MediaSession.Callback#onConnectAsync(androidx.media3.session.MediaSession,androidx.media3.session.MediaSession.ControllerInfo)` by using an `https://developer.android.com/reference/androidx/media3/session/MediaSession.ConnectionResult.AcceptedResultBuilder`.

Use `MediaSession.setMediaButtonPreferences(..)` to update the media button preferences during the life time of the session.

On the controller side, the `https://developer.android.com/reference/androidx/media3/session/CommandButton#isEnabled()` flag is set to `false` if the available commands of a controller do not allow to use a button.

| Parameters |
|---|---|
| `https://developer.android.com/reference/java/util/List.html<https://developer.android.com/reference/androidx/media3/session/CommandButton> mediaButtonPreferences` | The ordered list of `https://developer.android.com/reference/androidx/media3/session/CommandButton`. |

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | The builder to allow chaining. |

### setPackageNameOverride

```
@UnstableApi
@CanIgnoreReturnValue
@RequiresPermission(value = "android.permission.OVERRIDE_MEDIA_SESSION_OWNER")
public MediaSession.Builder setPackageNameOverride(String packageNameOverride)
```

Overrides the package name of the session created.

This method must not be used if the provided `packageNameOverride` is same as the package name of the application creating the session.

Interoperability: The value set by this method is ignored on API levels below 37 for legacy sessions and controllers.

| Parameters |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html packageNameOverride` | The package name override of the session when created. |

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | This builder. |

### setPeriodicPositionUpdateEnabled

```
@UnstableApi
public MediaSession.Builder setPeriodicPositionUpdateEnabled(boolean isEnabled)
```

Sets whether periodic position updates should be sent to controllers while playing. If false, no periodic position updates are sent to controllers.

The default is `true`.

| Parameters |
|---|---|
| `boolean isEnabled` | Whether periodic position update is enabled. |

### setSessionActivity

```
public MediaSession.Builder setSessionActivity(PendingIntent pendingIntent)
```

Sets a `https://developer.android.com/reference/android/app/PendingIntent.html` to launch an `https://developer.android.com/reference/android/app/Activity.html` for the `https://developer.android.com/reference/androidx/media3/session/MediaSession`. This can be used as a quick link to an ongoing media screen.

A client can use this pending intent to start an activity belonging to this session. On API levels below 33 the pending intent can be used `https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder#setContentIntent(android.app.PendingIntent)`. Tapping the notification will then send that pending intent and open the activity (see ['Start an Activity from a Notification'](https://developer.android.com/training/notify-user/navigation)). For API levels starting with 33, the media notification reads the pending intent directly from the session.

| Parameters |
|---|---|
| `https://developer.android.com/reference/android/app/PendingIntent.html pendingIntent` | The pending intent. |

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | The builder to allow chaining. |

### setSessionExtras

```
public MediaSession.Builder setSessionExtras(Bundle sessionExtras)
```

Sets the `https://developer.android.com/reference/androidx/media3/session/MediaSession#getSessionExtras()`. If not set, `https://developer.android.com/reference/android/os/Bundle.html#EMPTY` is used.

A controller has access to session extras through `https://developer.android.com/reference/androidx/media3/session/MediaController#getSessionExtras()`.

| Parameters |
|---|---|
| `https://developer.android.com/reference/android/os/Bundle.html sessionExtras` | The session extras `https://developer.android.com/reference/android/os/Bundle.html`. |

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media3/session/MediaSession.Builder` | The builder to allow chaining. |

### setShowPlayButtonIfPlaybackIsSuppressed

```
@UnstableApi
public MediaSession.Builder setShowPlayButtonIfPlaybackIsSuppressed(
    boolean showPlayButtonIfPlaybackIsSuppressed
)
```

Sets whether a play button is shown if playback is `https://developer.android.com/reference/androidx/media3/common/Player#getPlaybackSuppressionReason()`.

The default is `true`.

| Parameters |
|---|---|
| `boolean showPlayButtonIfPlaybackIsSuppressed` | Whether to show a play button if playback is `https://developer.android.com/reference/androidx/media3/common/Player#getPlaybackSuppressionReason()`. |

## Protected methods

### ensureBitmapLoaderIsSizeLimited

```
@EnsuresNonNull(value = "bitmapLoader")
protected final void ensureBitmapLoaderIsSizeLimited()
```

Updates bitmap loader to ensure its using the maximum media session size limit.