audio_manager #

A Flutter plugin for music playback, notification handling, lock-screen controls, and desktop system media controls.

Screenshots #

Android	iOS	macOS

Supported platforms #

Installation #

Add the dependency to pubspec.yaml:

dependencies:
  audio_manager: ^1.0.0

iOS #

The plugin supports both CocoaPods and Swift Package Manager (SPM) on iOS. Flutter 3.24+ integrates it via SPM automatically; otherwise it falls back to CocoaPods.

Add the following permissions in the info.plist file

	<key>UIBackgroundModes</key>
	<array>
		<string>audio</string>
	</array>
	<key>NSAppTransportSecurity</key>
	<dict>
		<key>NSAllowsArbitraryLoads</key>
		<true/>
	</dict>

• ⚠️ Some methods are invalid in the simulator, please use the real machine
• ⚠️ Only add UIBackgroundModes -> audio when your app really keeps playing audio in the background. If the app does not provide background audio, App Store review may reject it with guideline 2.5.4.

Android #

Since Android9.0 (API 28), the application disables HTTP plaintext requests by default. To allow requests, add android:usesCleartextTraffic="true" in AndroidManifest.xml

<application
	...
	android:usesCleartextTraffic="true"
	...
>

• ⚠️ Android minimum supported version 23 (app/build.gradle -> minSdkVersion: 23)
• ⚠️ Compile against Android SDK 34 or newer when targeting Android 12+ apps. The plugin now requires explicit PendingIntent flags, a media playback foreground service type, and Android 13+ receiver export flags.
• ⚠️ Android notification and lock-screen controls use MediaSession / MediaStyle. Custom notification icons and full custom layouts are not exposed by the public API.

Desktop (macOS / Windows / Linux) #

Desktop playback integrates with the system media controls: macOS Now Playing / Control Center, Windows SMTC (taskbar media flyout), and Linux MPRIS.

• macOS: to stream network audio, add the com.apple.security.network.client entitlement to the app's entitlements files (DebugProfile.entitlements / Release.entitlements):

  <key>com.apple.security.network.client</key>
  <true/>
  

• Linux: requires GStreamer development packages to build (gst_player lives in gst-plugins-bad):

  sudo apt install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libgstreamer-plugins-bad1.0-dev
  

• Windows: built with the Windows 10 SDK (C++/WinRT); requires Visual Studio 2022+.

Usage #

The plugin uses a singleton. Get AudioManager.instance and start playback directly.

Quick start #

You can use local assets, local files, or network resources.

// Initial playback. Preloaded playback information
AudioManager.instance
	.start(
		"assets/audio.mp3",
		// "network format resource"
		// "local resource (file://${file.path})"
		"title",
		desc: "desc",
		// cover: "network cover image resource"
		cover: "assets/ic_launcher.png")
	.then((err) {
	print(err);
});

// Play or pause; that is, pause if currently playing, otherwise play
AudioManager.instance.playOrPause();

// events callback
AudioManager.instance.onEvents((events, args) {
	print("$events, $args");
});

Update metadata while playing #

await AudioManager.instance.updateInfo(
  title: "new title",
  desc: "new artist",
  coverUrl: "https://example.com/new-cover.png",
  titleMaxLines: 2,
  showPreviousButton: true,
  showStopButton: false,
);

Playback speed is supported through AudioManager.instance.setRate(AudioRate.rate150).

Query state from background handlers #

Firebase background isolates cannot reliably receive AudioManager.onEvents. For short-lived checks, query the native state directly:

final state = await AudioManager.instance.currentState();
print(state["isPlaying"]);
print(state["title"]);