flutter_media_session 3.2.0
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.
3.2.0 #
Features #
- Linux: Added native MPRIS 2 support via D-Bus (
org.mpris.MediaPlayer2), enabling media controls in GNOME, KDE Plasma, Cinnamon, XFCE, and other desktop environments, as well as CLI tools such asplayerctl. - Core: Added
setAppId(String id, {String? displayName, String? iconPath})as a unified cross-platform replacement forsetWindowsAppUserModelId. On Windows it sets the AUMID; on Linux it sets the MPRISDesktopEntryandIdentity.
Deprecations #
- Core:
setWindowsAppUserModelIdis deprecated in favour ofsetAppId. It will be removed inv4.0.0. Migrate by renaming the call and removing thePlatform.isWindowsguard where appropriate.
3.1.0 #
Features #
- Android: Added
ActionSlotLayoutandsetActionLayoutto customize media notification button ordering and compact view slots.
Improvements #
- Android: Cleaned up duplicate media button and action registration logs.
- Example: Added action slot layout configuration in the settings panel.
Bug Fixes #
- Android: Fixed media notification momentarily disappearing during track changes by maintaining buffering state during track transitions instead of transitioning to idle.
- Web: Fixed media card pause action not updating playback status and button to play by ensuring both play and pause handlers remain registered when either action is available.
- Windows: Fixed SMTC play/pause state desynchronization by enabling both play and pause controls when either action is available and applying immediate status updates on transport control clicks.
- Core: Included both
MediaAction.playandMediaAction.pauseinActionSlotLayout.allActionswhen either action is present in slots. - Core: Made
setActionLayouta safe no-op on non-Android platforms, preventing slot layouts from overwriting previously configured available actions. - Darwin: Ensured both play and pause commands are enabled in
MPRemoteCommandCenterwhen either action is available.
3.0.9 #
Bug Fixes #
- Android: Removed redundant
onStartCommandmedia button handling inFlutterMediaSessionServiceto eliminate duplicate event dispatch and prevent state desynchronization between the service notification and player callback.
3.0.8 #
Improvements #
- Added library documentation comments and explicit constructor documentation across public API elements.
- Fixed unresolved doc references and refined comment formatting for pub.dev analysis.
3.0.7 #
Bug Fixes #
- Android: Cleaned up legacy media button routing and explicitly canceled notifications on deactivation to ensure complete dismissal.
3.0.6 #
Bug Fixes #
- Android:
- Added
MediaButtonRoutingCompataudio track hook to ensure OS hardware media button dispatch routes to the active session UID. - Enhanced
MediaButtonReceiverandFlutterMediaSessionServiceforeground lifecycle and media button event routing. - Added consumer ProGuard rules (
consumer-rules.pro) for Android media button compatibility classes.
- Added
3.0.5 #
Bug Fixes #
- Android:
- Registered explicit
MediaButtonReceiverPendingIntentonto legacySessionCompatto ensure hardware media buttons are routed to the session. - Started
FlutterMediaSessionServiceviaContextCompat.startForegroundServiceto keep background media controls reliable.
- Registered explicit
- Windows:
- Fixed an Access Violation crash (
0xc0000005) inupdateMetadatawhen using local artwork paths withseekToenabled by passing variables as by-value coroutine parameters. - Handled
Stop,FastForward, andRewindbutton events in SMTCButtonPressedcallbacks.
- Fixed an Access Violation crash (
Improvements #
- Example:
- Displayed application version in the AppBar using
package_info_plus. - Added
stopaction handling and simplified platform-specific settings.
- Displayed application version in the AppBar using
3.0.4 #
Bug Fixes #
- Android:
- Fixed lingering notifications and zombie media controls on deactivation, and ensured state recovery upon re-activation.
- Directly intercepted and dispatched
ACTION_DOWNmedia button events (play, pause, next, previous, stop) to Flutter inonMediaButtonEvent. - Automatically deactivated and released media session resources when the Flutter engine detaches.
- Example: Re-bound adapter on activation and auto-resumed playback after
seekTo.
3.0.3 #
Bug Fixes #
- Android: Fixed hardware media button interactions by updating
MediaButtonReceiverto Media3 (androidx.media3.session.MediaButtonReceiver), addingandroid.intent.action.MEDIA_BUTTONto the service intent-filter, and overridingonMediaButtonEventinCustomMediaSessionCallback.
Improvements #
- Re-exported
flutter_media_session_platform_interface.dartdirectly fromflutter_media_session.dart, allowing customMediaSessionAdapterimplementations with a single import. - Updated
example/README.mdanddoc/usage.mdsnippets to align with 3.x adapter patterns and removed deprecated 2.x API references.
3.0.2 #
Bug Fixes #
- Android:
- Fixed missing custom buttons (e.g., Shuffle, Repeat) in release builds by adding resource shrinking keep rules (
keep.xml) and enhancing drawable resource resolution. - Synchronized updated player commands dynamically to active system controllers in
updateAvailableActions, enabling immediate seek bar updates when togglingseekTo. - Ignored system seek gestures in
handleSeekwhenMediaAction.seekTois disabled. - Fixed an issue where background keep-alive (
setBackgroundKeepAlive) could disconnect when playback was paused on Android 12+ (e.g., while casting to a TV).
- Fixed missing custom buttons (e.g., Shuffle, Repeat) in release builds by adding resource shrinking keep rules (
3.0.1 #
Bug Fixes #
- Example:
- Added
<uses-permission android:name="android.permission.INTERNET" />andandroid:usesCleartextTraffic="true"toexample/android/app/src/main/AndroidManifest.xml. - Restored reliable public sample audio URLs (
soundhelix.com) and cover images inexample/lib/main.dart.
- Added
3.0.0 #
Features #
- Background Keep-Alive (
setBackgroundKeepAlive): Added an opt-in API that keeps backgrounded sessions alive when audio is rendered off-device (e.g., Chromecast/DLNA). Off by default; uses the best available primitive per platform:- Android: Partial wake lock (CPU) + high-performance Wi-Fi lock (radio), under
mediaPlayback|connectedDeviceforeground service type. - macOS:
IOPMAssertionto prevent idle system sleep. - Windows:
SetThreadExecutionStateto prevent system sleep. - Web: Best-effort Screen Wake Lock.
- iOS: No-op (depends on native audio playback).
- Android: Partial wake lock (CPU) + high-performance Wi-Fi lock (radio), under
- Android: Added dynamic Android Gradle Plugin (AGP) version detection to support both older KGP versions and the new built-in Kotlin mechanism in AGP 9.0+, preventing compile errors and JVM target mismatches.
- Darwin: Improved thread safety, resource management, and error handling in
MediaSessionManager. - iOS / macOS: Added repeat/shuffle synchronization via
changeShuffleModeCommand/changeRepeatModeCommand. - Added customizable skip intervals (
setSkipIntervals). - Android: Synchronized
shuffleModeEnabledwith Media3'sSimpleBasePlayerstate.
Breaking Changes #
- Removed deprecated legacy direct-sync APIs from the public
FlutterMediaSessionclass:updateMetadata,updatePlaybackState,updateAvailableActions,onMediaAction, andrequestNotificationPermission. UseFlutterMediaSessionPlatform.instancefor direct manual updates. - Removed deprecated
setHandlesInterruptionsin favor ofsetAutoHandleInterruptions. - Refactored
JustAudioMediaSessionAdapterandMediaKitMediaSessionAdapterto update state directly viaFlutterMediaSessionPlatform.instance.
Bug Fixes #
- Example: Fixed a reload bug by resetting the loaded URL when deactivating the media session.
2.3.0 #
Features #
- iOS / macOS: Registered native
changeShuffleModeCommandandchangeRepeatModeCommandto sync repeat and shuffle modes. - iOS / macOS: Added customizable skip intervals for rewind and fast-forward commands (
setSkipIntervals). - Android: Synchronized
shuffleModeEnabledwith Media3'sSimpleBasePlayerstate.
Bug Fixes #
- Example: Fixed a reload bug by resetting the loaded URL when deactivating the media session.
2.2.0 #
Features #
- Introduced
MediaSessionAdapterinterface to decouple player implementations from media session controls. - Provided copy-ready adapter classes for
just_audioandmedia_kitindoc/adapters/and the wiki, keeping the core package free of third-party player dependencies. - Added lifecycle state management:
Idle→Active→Bound→Unbound→Deactivated.
Improvements #
- API: Renamed
setHandlesInterruptionstosetAutoHandleInterruptionsacross platform interfaces, Android, Windows, and Dart layers. - Windows:
- Added metadata deduplication caching in C++ to prevent cover art flashing on state changes.
- Fixed shuffle/repeat button states resetting or locking to "Closed" in the OS UI via robust type parsing and synchronous WinRT callback feedback.
- Darwin: Updated
Package.swiftto correctly declare theFlutterFrameworkdependency, resolving iOS/macOS compiler warnings.
Deprecations #
- Marked legacy manual sync APIs as deprecated (
updateMetadata,updatePlaybackState,updateAvailableActions,onMediaAction). Scheduled for removal in3.0.0.
2.1.3 #
Features #
- Added
MediaAction.shuffleandMediaAction.repeatfor native shuffle and repeat toggles.
Improvements #
- Windows:
- Enhanced artwork handling for local file paths (converting to
file://URIs). - Improved timeline synchronization to prevent progress bar drift in system controls.
- Added native Shuffle and Repeat button support in SMTC.
- Added safety checks and error handling for SMTC updates.
- Enhanced artwork handling for local file paths (converting to
- Android: Refined custom action rendering and fixed potential slider rendering issues.
- Example: Modularized UI components and implemented a "ping-pong" player strategy for smoother track transitions on Windows.
2.1.0 #
Features #
- Android: Added support for custom notification buttons (e.g., Like, Shuffle) via Media3.
- Extended
MediaActionwith custom labels and Android drawable resources. MediaSessionServicenow dynamically updates custom layout commands.- Added input validation and size-limited caching for custom action parameters.
- Extended
- iOS / macOS: Added support for
MPNowPlayingInfoCenterandMPRemoteCommandCenter. - Android: Added
setHandlesInterruptions(bool)for automatic audio focus handling during calls or interruptions. - Windows: Resolved the "Unknown Application" display issue using dynamic AUMID registration and Start Menu shortcut creation.
Bug Fixes #
- Android: Exposed playback state via accessor for better integration with custom services (PR #16).
- Windows: Improved COM lifecycle management and path traversal handling.
- Example: Fixed a
Sliderrendering assertion failure when durations were zero or negative. - Web: Improved
updateAvailableActionsparity.
Improvements #
- Updated documentation and example app to demonstrate new platform features.
2.0.0 #
Features #
- Added
updateAvailableActionsAPI to dynamically toggle system media controls (Play, Pause, Skip, Seek, etc.).
Improvements #
- Improved Web Media Session playback buffering and synchronized seeking logic.
- Enhanced debounced seeking strategy across all platforms.
- Improved documentation and fixed cross-platform link consistency.
Bug Fixes #
- Fixed Android and Windows media progress bar synchronization with advanced position extrapolation.
1.0.0 #
Initial release.
Features #
- Added support for Android (Media3), Windows (SMTC), and Web (Media Session API).
- Synchronized track metadata (title, artist, album, artwork).
- Synchronized playback states (playing, paused, position, speed).
- Added media action handling (play, pause, next, previous) from system controls.