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.
Libraries
- flutter_media_session
- The primary library for controlling system media sessions and player integration.
- flutter_media_session_method_channel
- The method channel implementation library for Flutter Media Session.
- flutter_media_session_platform_interface
- The platform interface library for Flutter Media Session.
- flutter_media_session_web


