Skip to main content

flutter_media_session 3.2.0 copy "flutter_media_session: ^3.2.0" to clipboard
flutter_media_session: ^3.2.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.

Banner

flutter_media_session #

pub package pub points CI License: MIT Platform

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_audio or media_kit and 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
Android notification Chrome media session Windows SMTC

Platform Support #

Platform Minimum Version
Android Android Android 7.0 (API 24+)
Apple iOS iOS 12.0+
Apple macOS macOS 10.15+
Windows Windows Windows 10 1809+ (Build 17763+)
Linux Linux 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: ^3.2.0

Full documentation, tutorials, and setup guides are available at docs.wyrin.dev/flutter-media-session.

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 AVAudioSession category to .playback upon 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, and ACCESS_WIFI_STATE) are declared in the plugin's AndroidManifest.xml and 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, and libgtk-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 #

Adapters handle the stream subscriptions and state mapping between your player and the media session. Ready-to-use adapter guides are available on the Documentation site and 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:

👉 docs.wyrin.dev/flutter-media-session

For offline reference, local documentation is also included in the repository:

4
likes
160
points
2.73k
downloads

Documentation

API reference

Publisher

verified publisherwyrin.dev

Weekly Downloads

Sync media metadata, background audio playback, and hardware media buttons with OS controls across Android, iOS, macOS, Windows, Linux, and Web.

Repository (GitHub)
View/report issues
Contributing

Topics

#media #audio #playback #media-session #lockscreen

License

MIT (license)

Dependencies

flutter, flutter_web_plugins, plugin_platform_interface, web

More

Packages that depend on flutter_media_session

Packages that implement flutter_media_session