flutter_media_session — Interactive Guide

Installation

Target Platforms

Player Adapter

Extra Features

1. Install Package

Add flutter_media_session to your Flutter dependencies using the command line or editing pubspec.yaml.

Add Dependency

Add flutter_media_session to your Flutter project using the command line:

BASH

flutter pub add flutter_media_session

Or manually add it to your pubspec.yaml under dependencies:

YAML

dependencies:
  flutter:
    sdk: flutter
  flutter_media_session: ^3.1.0

Then run flutter pub get to install the package.

2. Select Target Platforms

Choose all platforms your app supports. Configure each selected platform and mark it complete when ready.

Android Setup

flutter_media_session uses AndroidX Media3 under the hood.

Zero Initial Configuration

For standard audio apps, Android requires no code changes or manifest edits before running:

Permissions: When you call activate(), the plugin automatically requests the POST_NOTIFICATIONS runtime permission on Android 13+ (API 33+).
Foreground Service: The media playback foreground service is automatically registered and managed.

DART

final session = FlutterMediaSession();
await session.activate();

Stripping Connected Device Permission (Optional)

By default, the plugin declares FOREGROUND_SERVICE_CONNECTED_DEVICE for cast/remote device control. If you strip this permission, Android 14+ requires overriding the service in AndroidManifest.xml:

XML

<!-- android/app/src/main/AndroidManifest.xml -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    
    <uses-permission 
        android:name="android.permission.FOREGROUND_SERVICE_CONNECTED_DEVICE" 
        tools:node="remove" />

    <application ...>
        <service
            android:name="dev.wyrin.flutter_media_session.FlutterMediaSessionService"
            android:foregroundServiceType="mediaPlayback"
            tools:replace="android:foregroundServiceType" />
    </application>
</manifest>

Custom notification buttons and drawable icons can be configured in Step 3 (Action Slot Layout & Custom Actions).

iOS Setup

flutter_media_session uses MPRemoteCommandCenter and MPNowPlayingInfoCenter on iOS.

Background Audio Mode

Add the audio background mode to your iOS project's Info.plist:

XML

<!-- ios/Runner/Info.plist -->
<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

Audio Session

AVAudioSession is automatically initialized and configured when you invoke session.activate(). You do not need to configure playback categories manually unless you have specialized capture or ducking requirements.

macOS Setup

flutter_media_session integrates directly with macOS MPNowPlayingInfoCenter and system media keys.

Zero Configuration

macOS requires no plist keys, entitlements, or sandbox additions for basic media playback, lock screen controls, and Control Center media widgets.

Simply activate the session in Dart:

DART

final session = FlutterMediaSession();
await session.activate();

Windows Setup

flutter_media_session uses WinRT SystemMediaTransportControls (SMTC).

Window Initialization Requirement

SMTC handles are bound per-window via Win32 HWND. Make sure session.activate() is invoked after the Flutter engine creates the main window (e.g. after runApp):

DART

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(const MyApp());
  
  // Activate after the native window is created
  final session = FlutterMediaSession();
  await session.activate();
}

App Title & Icon Identity: By default, unpackaged Windows applications show up as "Unknown Application" in SMTC. See Step 3: Windows AUMID Identity for full MSIX packaging or Start Menu shortcut registration.

Web Setup

flutter_media_session binds directly to the standard browser navigator.mediaSession API.

Zero Configuration

Web apps require no HTML headers, external JS scripts, or manifest permissions.

DART

final session = FlutterMediaSession();
await session.activate();

Browser Note: Browsers enforce user-activation policies. Audio playback and lock screen controls activate once the user interacts with the page (e.g., clicking a play button).

3 platforms selected

2. Bind Player Adapter

Select your playback engine to inspect adapter parameters, setup code, and two-way sync.

Just Audio Adapter

The JustAudioMediaSessionAdapter synchronizes just_audio [AudioPlayer] with FlutterMediaSession.

Constructor Parameters

Parameter	Type	Required?	Default	Description
`player`	`AudioPlayer`	Yes	—	The active `just_audio` player instance.
`metadataMapper`	`MediaMetadata Function(AudioPlayer)?`	No	`null`	Custom resolver for metadata from player or current item tag.
`manageLifecycle`	`bool`	No	`false`	When `true`, automatically activates the session on bind.

Setup & Binding

DART

import 'package:flutter_media_session/flutter_media_session.dart';
import 'package:just_audio/just_audio.dart';

final player = AudioPlayer();
final session = FlutterMediaSession();

// Create adapter (manageLifecycle: true automatically calls session.activate() on bind)
final adapter = JustAudioMediaSessionAdapter(
  player,
  manageLifecycle: true,
);

session.bind(adapter);

Remote Transport Commands

When bound, the adapter automatically listens to system media commands (play, pause, stop, seekTo, skipToNext, skipToPrevious, repeat, shuffle) and controls AudioPlayer.

Custom Actions or Additional Command Interception

If you have custom actions (e.g. favorite) or want to intercept additional commands alongside just_audio:

DART

// You can listen to custom actions via the platform action stream:
FlutterMediaSessionPlatform.instance.onMediaAction.listen((action) {
  if (action.name == 'favorite') {
    // Handle like / favorite toggle
  }
});

Media Kit Adapter

The MediaKitMediaSessionAdapter synchronizes media_kit [Player] with FlutterMediaSession.

Constructor Parameters

Parameter	Type	Required?	Default	Description
`player`	`Player`	Yes	—	The active `media_kit` player instance.
`metadataMapper`	`MediaMetadata Function(Player)?`	No	`null`	Custom resolver for metadata from player or current playlist item.
`manageLifecycle`	`bool`	No	`false`	When `true`, automatically activates the session on bind.

Setup & Binding

DART

import 'package:flutter_media_session/flutter_media_session.dart';
import 'package:media_kit/media_kit.dart';

final player = Player();
final session = FlutterMediaSession();

// Create adapter (manageLifecycle: true automatically calls session.activate() on bind)
final adapter = MediaKitMediaSessionAdapter(
  player,
  manageLifecycle: true,
);

session.bind(adapter);

Remote Transport Commands

When bound, the adapter translates system transport actions (play, pause, stop, seekTo, skipToNext, skipToPrevious) directly to Player methods.

Custom Actions or Additional Command Interception

To handle custom actions while using media_kit:

DART

FlutterMediaSessionPlatform.instance.onMediaAction.listen((action) {
  if (action.name == 'favorite') {
    // Handle like / favorite toggle
  }
});

Manual Integration

For custom engines or native decoders, push state and listen for actions directly via FlutterMediaSessionPlatform.instance.

1. Update Metadata: `updateMetadata(MediaMetadata metadata)`

Field	Type	Required?	Default	Description
`title`	`String`	Yes	—	Title of current track/media.
`artist`	`String?`	No	`null`	Artist or author name.
`album`	`String?`	No	`null`	Album, show, or series title.
`artUri`	`String?`	No	`null`	URL or local file URI for artwork.
`duration`	`Duration?`	No	`null`	Total track duration.

DART

await FlutterMediaSessionPlatform.instance.updateMetadata(
  const MediaMetadata(
    title: 'Custom Stream',
    artist: 'Independent Creator',
    album: 'Podcast Episode 12',
    artUri: 'https://example.com/cover.png',
    duration: Duration(minutes: 45),
  ),
);

2. Update Playback State: `updatePlaybackState(PlaybackState state)`

Field	Type	Required?	Default	Description
`status`	`PlaybackStatus`	Yes	—	`none`, `stopped`, `paused`, `playing`, `buffering`, `error`.
`position`	`Duration`	No	`Duration.zero`	Current playback position.
`speed`	`double`	No	`1.0`	Playback speed rate.
`bufferedPosition`	`Duration`	No	`Duration.zero`	Buffered/cached audio position.
`repeatMode`	`MediaRepeatMode`	No	`.none`	`.none`, `.one`, `.all`.
`shuffleModeEnabled`	`bool`	No	`false`	Whether shuffle is currently on.

DART

await FlutterMediaSessionPlatform.instance.updatePlaybackState(
  const PlaybackState(
    status: PlaybackStatus.playing,
    position: Duration(minutes: 12, seconds: 30),
    speed: 1.0,
    bufferedPosition: Duration(minutes: 14),
  ),
);

3. Action Handlers: `session.setActionHandler(...)`

Use session.setActionHandler to easily wire playback callbacks without manually managing stream subscriptions:

DART

final session = FlutterMediaSession();

session.setActionHandler(
  onPlay: () => myPlayer.play(),
  onPause: () => myPlayer.pause(),
  onStop: () => myPlayer.stop(),
  onSeekTo: (position) => myPlayer.seek(position),
  onSkipToNext: () => playlist.next(),
  onSkipToPrevious: () => playlist.previous(),
  onRewind: () => myPlayer.seek(myPlayer.position - const Duration(seconds: 15)),
  onFastForward: () => myPlayer.seek(myPlayer.position + const Duration(seconds: 30)),
);

Supported Handlers

Parameter	Type	Required?	Description
`onPlay`	`VoidCallback?`	No	Called on play / resume command.
`onPause`	`VoidCallback?`	No	Called on pause command.
`onStop`	`VoidCallback?`	No	Called on stop command.
`onSkipToNext`	`VoidCallback?`	No	Called on next track command.
`onSkipToPrevious`	`VoidCallback?`	No	Called on previous track command.
`onSeekTo`	`void Function(Duration)?`	No	Called on scrubber seek with target `Duration`.
`onRewind`	`VoidCallback?`	No	Called on rewind interval command.
`onFastForward`	`VoidCallback?`	No	Called on fast-forward interval command.
`onShuffle`	`VoidCallback?`	No	Called on shuffle toggle.
`onRepeat`	`VoidCallback?`	No	Called on repeat mode toggle.

Note for Custom Actions: For custom actions created via MediaAction.custom(...), listen directly to FlutterMediaSessionPlatform.instance.onMediaAction and check action.name.

4. Extra Features & Controls

Select and configure additional capabilities. Each feature lists supported platforms and all Dart API parameters.

Platforms:

Action Slot Layout & Icons

Action Slot Layout

Customizes the order and placement of media buttons on Android notifications and compact lock screen views.

Methods & Constructors

FlutterMediaSessionPlatform.instance.setActionLayout(ActionSlotLayout layout)

`ActionSlotLayout.symmetrical`

Parameter	Type	Required?	Default	Description
`left`	`MediaAction?`	No	`null`	Custom action or feature placed on far left (slot 0).
`skipPrevious`	`MediaAction`	No	`MediaAction.skipToPrevious`	Previous track button.
`playPause`	`MediaAction`	No	`MediaAction.play`	Center toggle button.
`skipNext`	`MediaAction`	No	`MediaAction.skipToNext`	Next track button.
`right`	`MediaAction?`	No	`null`	Custom action or feature placed on far right (slot 4).
`compactActionIndices`	`List<int>?`	No	`[1, 2, 3]`	Up to 3 slot indices shown in collapsed notification.

DART

await FlutterMediaSessionPlatform.instance.setActionLayout(
  ActionSlotLayout.symmetrical(
    left: MediaAction.custom(name: 'favorite', customLabel: 'Like', customIconResource: 'ic_heart'),
    right: MediaAction.repeat,
  ),
);

Symmetrical layout: [Repeat, Prev, Pause, Next, Shuffle]

Sequential layout: [Prev, Pause, Next, Repeat, Shuffle]

`ActionSlotLayout.sequential`

Parameter	Type	Required?	Default	Description
`skipPrevious`	`MediaAction`	No	`MediaAction.skipToPrevious`	Previous track button.
`playPause`	`MediaAction`	No	`MediaAction.play`	Center toggle button.
`skipNext`	`MediaAction`	No	`MediaAction.skipToNext`	Next track button.
`custom1`	`MediaAction?`	No	`null`	4th slot button.
`custom2`	`MediaAction?`	No	`null`	5th slot button.
`compactActionIndices`	`List<int>?`	No	`[0, 1, 2]`	Up to 3 slot indices for compact view.

`ActionSlotLayout(slots, {compactActionIndices})`

Parameter	Type	Required?	Default	Description
`slots`	`List<MediaAction>`	Yes	—	Explicit list of up to 5 action slots.
`compactActionIndices`	`List<int>?`	No	`null`	Explicit 0-based indices for compact mode (max 3).

Custom Actions & Drawable Icons (Android)

Android notifications allow up to 5 buttons in expanded view. You can define custom buttons using MediaAction.custom:

DART

final favoriteAction = MediaAction.custom(
  name: 'favorite',
  customLabel: 'Favorite',
  customIconResource: 'ic_heart', // Name of drawable resource without extension
);

Standard 3-button controls (Prev, Play/Pause, Next)

Expanded 5-button controls with custom actions & slot mapping

Resource Placement

Place custom vector or PNG icons in your Android app module:

Path: android/app/src/main/res/drawable/ic_heart.xml (or .png)
In Dart, pass only the resource name 'ic_heart' (omit directory and .xml/.png extension).

Background Keep-Alive

Prevents OS sleep and network throttling while streaming audio in the background or off-device casting.

Method Signature

FlutterMediaSessionPlatform.instance.setBackgroundKeepAlive(bool enabled)

Parameter	Type	Required?	Default	Description
`enabled`	`bool`	Yes	—	`true` to acquire wake lock and high-perf WiFi mode; `false` to release.

DART

// Enable wake locks and WiFi high-performance mode
await FlutterMediaSessionPlatform.instance.setBackgroundKeepAlive(true);

// Release wake locks when playback stops
await FlutterMediaSessionPlatform.instance.setBackgroundKeepAlive(false);

Platform Behaviors

Android: Acquires PARTIAL_WAKE_LOCK + WIFI_MODE_FULL_HIGH_PERF. Requires android.permission.WAKE_LOCK.
Web: Calls navigator.wakeLock.request('screen'). Revokes automatically if tab is hidden.
iOS / macOS / Windows: Managed via audio session background mode (no-op).

Skip & Rewind Intervals

Customizes the skip backward and skip forward step durations on lock screen remote command centers.

Method Signature

FlutterMediaSessionPlatform.instance.setSkipIntervals({int forwardSeconds = 10, int backwardSeconds = 10})

Parameter	Type	Required?	Default	Description
`forwardSeconds`	`int`	No	`10`	Fast-forward duration in seconds.
`backwardSeconds`	`int`	No	`10`	Rewind duration in seconds.

DART

await FlutterMediaSessionPlatform.instance.setSkipIntervals(
  forwardSeconds: 30,
  backwardSeconds: 15,
);

Supported natively on iOS and macOS (MPRemoteCommandCenter), and Web (MediaSession).

Audio Interruptions & Focus

Audio Interruptions

Configures whether the plugin automatically manages OS audio focus changes (e.g. phone calls, GPS prompts).

Method Signature

FlutterMediaSessionPlatform.instance.setAutoHandleInterruptions(bool enabled)

Parameter	Type	Required?	Default	Description
`enabled`	`bool`	Yes	—	`true` to let the plugin handle focus and emit pause/play events; `false` to disable.

DART

await FlutterMediaSessionPlatform.instance.setAutoHandleInterruptions(true);

Important: Leave enabled: false if your player engine already manages audio focus (such as just_audio with AudioSession or media_kit). Turn this on for bare video or audio decoders without built-in focus management.

Available Actions Filtering

Available Actions

Explicitly restricts or declares which actions are enabled in system controls. By default (null), all supported actions are enabled.

Method Signature

FlutterMediaSessionPlatform.instance.updateAvailableActions(Set<MediaAction>? actions)

Parameter	Type	Required?	Default	Description
`actions`	`Set<MediaAction>?`	No	`null`	Allowed set of actions. Pass `null` to enable all actions (default).

Standard Media Actions List

MediaAction provides 10 built-in standard actions:

Static Constant	Name String	Description
`MediaAction.play`	`'play'`	Resume playback
`MediaAction.pause`	`'pause'`	Pause playback
`MediaAction.stop`	`'stop'`	Stop playback
`MediaAction.skipToNext`	`'skipToNext'`	Skip to next track
`MediaAction.skipToPrevious`	`'skipToPrevious'`	Skip to previous track
`MediaAction.seekTo`	`'seekTo'`	Scrub/seek to a specific position
`MediaAction.rewind`	`'rewind'`	Rewind by standard interval (e.g. 10s/15s)
`MediaAction.fastForward`	`'fastForward'`	Fast-forward by standard interval (e.g. 10s/30s)
`MediaAction.shuffle`	`'shuffle'`	Toggle shuffle mode
`MediaAction.repeat`	`'repeat'`	Toggle repeat mode

Custom Actions (Android)

You can also create custom actions using MediaAction.custom:

DART

final favoriteAction = MediaAction.custom(
  name: 'favorite',
  customLabel: 'Favorite',
  customIconResource: 'ic_heart', // Located in android/app/src/main/res/drawable/
);

Usage Example

DART

// Whitelist specific controls (e.g. for a podcast player with seek & intervals)
await FlutterMediaSessionPlatform.instance.updateAvailableActions({
  MediaAction.play,
  MediaAction.pause,
  MediaAction.stop,
  MediaAction.rewind,
  MediaAction.fastForward,
  MediaAction.seekTo,
});

// Reset to enable all supported actions
await FlutterMediaSessionPlatform.instance.updateAvailableActions(null);

Actions omitted from the set are either hidden or disabled in the system notification shade, lock screen, and SMTC.

Session Lifecycle

Controls starting, stopping, and releasing the platform media controls and background services.

Methods

`FlutterMediaSession().activate()`

Initializes platform media controls, registers foreground service on Android (auto-requesting POST_NOTIFICATIONS permission if needed), and binds to OS media hubs (Now Playing / SMTC / MediaSession API).

DART

final session = FlutterMediaSession();
await session.activate();

`FlutterMediaSession().deactivate()`

Removes OS notifications, stops foreground services, releases wake locks, and removes transport controls from the OS lock screen.

DART

await session.deactivate();

Adapter Lifecycles: When using an adapter with manageLifecycle: true, the adapter automatically activates the session when bound and deactivates it when unbound.

Windows AUMID Identity

Windows SMTC identifies applications using an Application User Model ID (AUMID) to display your app's title and icon instead of "Unknown Application".

Default SMTC without AUMID (Unknown app)

With AUMID configured (App title and icon)

1. Unpackaged / Portable Distribution (`.zip` / Portable EXE)

For portable distributions or development builds without an installer, call setWindowsAppUserModelId before activating:

DART

import 'dart:io';
import 'package:flutter/material.dart';
import 'package:flutter_media_session/flutter_media_session.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  if (Platform.isWindows) {
    // Call early before activating media sessions
    await FlutterMediaSession().setWindowsAppUserModelId(
      'Com.Company.MyApp',
      displayName: 'My Media Player', // Creates Start Menu shortcut required by SMTC
      iconPath: r'C:\path\to\icon.ico', // Optional icon path
    );
  }

  runApp(const MyApp());
}

Parameters

Parameter	Type	Required?	Default	Description
`id`	`String`	Yes	—	Unique identifier string (e.g. `Com.Company.MyApp`).
`displayName`	`String?`	No	`null`	Display name for dynamic Start Menu shortcut. Omit if using an installer (InnoSetup, MSIX) that already creates shortcuts.
`iconPath`	`String?`	No	`null`	Optional absolute path to `.ico` file for the shortcut icon.

2. Packaged MSIX Distribution

When packaging via MSIX (e.g. using msix:create), Windows automatically assigns the AUMID from your package identity:

YAML

# pubspec.yaml
msix_config:
  display_name: My Media Player
  publisher_display_name: My Company
  identity_name: com.mycompany.mymediaplayer
  msix_version: 1.0.0.0
  logo_path: windows/runner/resources/app_icon.ico

Note: Inside an MSIX container, flutter_media_session detects package identity automatically and bypasses manual shortcut generation.

1. Install Package

Add Dependency

2. Select Target Platforms

Android Setup

Zero Initial Configuration

Stripping Connected Device Permission (Optional)

iOS Setup

Background Audio Mode

Audio Session

macOS Setup

Zero Configuration

Windows Setup

Window Initialization Requirement

Web Setup

Zero Configuration

2. Bind Player Adapter

Just Audio Adapter

Constructor Parameters

Setup & Binding

Remote Transport Commands

Custom Actions or Additional Command Interception

Media Kit Adapter

Constructor Parameters

Setup & Binding

Remote Transport Commands

Custom Actions or Additional Command Interception

Manual Integration

1. Update Metadata: updateMetadata(MediaMetadata metadata)

2. Update Playback State: updatePlaybackState(PlaybackState state)

3. Action Handlers: session.setActionHandler(...)

Supported Handlers

4. Extra Features & Controls

Action Slot Layout

Methods & Constructors

ActionSlotLayout.symmetrical

ActionSlotLayout.sequential

ActionSlotLayout(slots, {compactActionIndices})

Custom Actions & Drawable Icons (Android)

Resource Placement

Background Keep-Alive

Method Signature

Platform Behaviors

Skip & Rewind Intervals

Method Signature

Audio Interruptions

Method Signature

Available Actions

Method Signature

Standard Media Actions List

Custom Actions (Android)

Usage Example

Session Lifecycle

Methods

FlutterMediaSession().activate()

FlutterMediaSession().deactivate()

Windows AUMID Identity

1. Unpackaged / Portable Distribution (.zip / Portable EXE)

Parameters

2. Packaged MSIX Distribution

Guide & Documentation Feedback

1. Update Metadata: `updateMetadata(MediaMetadata metadata)`

2. Update Playback State: `updatePlaybackState(PlaybackState state)`

3. Action Handlers: `session.setActionHandler(...)`

`ActionSlotLayout.symmetrical`

`ActionSlotLayout.sequential`

`ActionSlotLayout(slots, {compactActionIndices})`

`FlutterMediaSession().activate()`

`FlutterMediaSession().deactivate()`

1. Unpackaged / Portable Distribution (`.zip` / Portable EXE)