flutter_media_session 2.6.0
flutter_media_session: ^2.6.0 copied to clipboard
Sync media metadata, background audio playback, and hardware media buttons with OS controls across Android, iOS, macOS, Windows, Linux, and Web.
flutter_media_session #
A Flutter plugin that connects media playback, background audio service, and hardware media buttons to OS media hubs — Android notifications, iOS Lock Screen & Dynamic Island, macOS Control Center, Windows SMTC, Linux MPRIS, and the Web Media Session API.
Handle lock screen controls, headset/keyboard media buttons (play, pause, next, prev, seek), background playback keep-alive, and playback metadata without bundling a heavyweight audio player. Wire it directly into your own player (just_audio, media_kit, audioplayers, etc.) via lightweight adapters.
Features #
- Cross-platform OS integration — Android media notifications (Media3), iOS/macOS Lock Screen & Now Playing, Windows SMTC volume flyout, and Web MediaSession API, all from a single Dart API.
- Adapter pattern — drop in a ready-made adapter for
just_audioormedia_kitand metadata / playback state sync is handled automatically. - Configurable action slots — control which transport buttons appear in Android notifications via
ActionSlotLayout, including custom actions with your own icons. - Remote command routing — receive play, pause, seek, skip, shuffle, and repeat commands from lock screens, headsets, and system media hubs through a unified callback interface.
- Background keep-alive — optionally acquire a wake lock to sustain playback while the app is backgrounded.
| Android | Web (Chrome) | Windows 11 |
![]() |
![]() |
![]() |
Platform Support #
| Platform | Minimum Version |
|---|---|
| Android 7.0 (API 24+) | |
| iOS 12.0+ | |
| macOS 10.15+ | |
| Windows 10 1809+ (Build 17763+) | |
| D-Bus MPRIS 2 | |
| Web | Modern Browsers |
For architecture and native backend details, see the Architecture Guide.
Installation #
Run this command:
flutter pub add flutter_media_session
Or add flutter_media_session manually to your pubspec.yaml:
dependencies:
flutter_media_session: ^2.6.0
Note: This branch maintains the v2 legacy release line. For the latest 3.x features and documentation, visit the main branch.
Platform Prerequisites #
iOS #
To keep media controls responsive and receive remote commands while your application is backgrounded, add UIBackgroundModes with audio to ios/Runner/Info.plist:
<key>UIBackgroundModes</key>
<array>
<string>audio</string>
</array>
Note: While the plugin configures
AVAudioSessioncategory to.playbackupon activation, iOS background execution relies on the application actively playing audio through an audio session.
Android #
- Permissions: Core permissions (
FOREGROUND_SERVICE,FOREGROUND_SERVICE_MEDIA_PLAYBACK,FOREGROUND_SERVICE_CONNECTED_DEVICE,POST_NOTIFICATIONS,WAKE_LOCK, andACCESS_WIFI_STATE) are declared in the plugin'sAndroidManifest.xmland merged automatically by Gradle. (To strip unused casting permissions, see Opting Out of Permissions.) - Android 13+ (API 33+): Notification posting requires runtime permission. Calling
FlutterMediaSession().activate()automatically requests notification permission on Android. - Custom Icons: Custom notification action drawables must exist in your application's
android/app/src/main/res/drawable*folders.
Windows #
- Packaged Apps (MSIX): When packaged via MSIX, Windows assigns the App User Model ID (AUMID) automatically from the manifest. No configuration required.
- Unpackaged / Portable Apps: To display your application's name and icon instead of "Unknown Application" in the volume flyout, refer to the Windows Setup Guide.
Linux #
- Build Dependencies: Requires
clang,cmake,ninja-build,pkg-config, andlibgtk-3-dev. - Runtime: Connects directly to the session bus via GDBus and exports MPRIS 2 interfaces (
org.mpris.MediaPlayer2). No additional runtime daemon required. For details, see the Linux Setup Guide.
macOS & Web #
No configuration required.
Quick Start #
Approach A: Using a Player Adapter (Recommended) #
Adapters handle the stream subscriptions and state mapping between your player and the media session. Ready-to-use adapter guides are available in doc/adapters/:
import 'package:flutter_media_session/flutter_media_session.dart';
import 'package:just_audio/just_audio.dart';
// Import your adapter implementation (see doc/adapters/just_audio.md)
import 'just_audio_media_session_adapter.dart';
final player = AudioPlayer();
final session = FlutterMediaSession();
// 1. Activate session (starts Android foreground service, binds SMTC / NowPlaying)
await session.activate();
// 2. Bind adapter to automatically synchronize metadata, playback states, and commands
session.bind(JustAudioMediaSessionAdapter(player));
Approach B: Direct API Usage #
You can also push metadata and playback states manually, and receive system actions via high-level callbacks or streams:
import 'package:flutter_media_session/flutter_media_session.dart';
final session = FlutterMediaSession();
// 1. Activate native session
await session.activate();
// 2. Update media metadata
await FlutterMediaSessionPlatform.instance.updateMetadata(
const MediaMetadata(
title: 'Song Title',
artist: 'Artist Name',
album: 'Album Title',
artworkUri: 'https://example.com/cover.jpg',
duration: Duration(minutes: 3, seconds: 30),
),
);
// 3. Update playback state
await FlutterMediaSessionPlatform.instance.updatePlaybackState(
const PlaybackState(
status: PlaybackStatus.playing,
position: Duration(seconds: 45),
speed: 1.0,
),
);
// 4. Handle incoming system media actions
session.setActionHandler(
onPlay: () => myAudioPlayer.resume(),
onPause: () => myAudioPlayer.pause(),
onSeekTo: (position) => myAudioPlayer.seek(position),
onSkipToNext: () => myPlaylist.next(),
onSkipToPrevious: () => myPlaylist.previous(),
);
Documentation #
For full documentation, guides, and tutorials, visit:
For offline reference, local documentation is also included in the repository:
- Usage Guide: API reference, writing custom adapters, Android notification layouts (
ActionSlotLayout), audio interruption handling, and background keep-alive. - Player Adapter Guides:
- Windows Setup Guide: Resolving the "Unknown Application" display name issue via MSIX or shortcut registration.
- Linux Setup Guide: Build requirements, MPRIS 2 D-Bus interface mapping, and
playerctlverification. - Architecture & Design Decisions: Platform internals, foreground service lifecycle, and native thread dispatching.
- Release Guide: Release verification and CI publishing workflow.


