Advanced Music Player Plugin

A feature-rich Flutter music player plugin providing advanced playback controls, background audio support, local file management, and reactive UI widgets.

Features

• Background Playback: seamless audio playback even when the app is minimized or the screen is off (powered by MediaSessionService on Android and background modes on iOS).
• Queue Management: standard queue operations including next, previous, seek, shuffle, and repeat modes.
• Local Audio Fetching: Automatically scan and play local audio files from the device storage.
• Duration Synchronization: Accurate, reactive tracking of current playback position and total track duration.
• Reactive UI Widgets: Built-in state management for position streams and player state, making UI updates smooth and efficient.
• Permission Handling: built-in methods to request necessary storage/audio permissions, handling Android 13+ differences transparently.

Architecture

This plugin uses a MethodChannel to communicate between Flutter and the native platform:

• Android: Implemented using androidx.media3 (ExoPlayer) within a MediaSessionService. This ensures the player is identified by the OS as a media playback service, allowing controlling from the notification shade and lock screen.
• iOS: (Implementation pending/Coming soon) Uses AVAudioPlayer or AVPlayer.

The Flutter side provides a singleton AdvancedMusicPlayer class that exposes streams (playerStateStream, positionStream, durationStream) for reactive UI updates.

Setup

Android

1. Permissions: Ensure your android/app/src/main/AndroidManifest.xml includes the necessary permissions (automatically handled if you use the plugin's requestStoragePermission()):

   <uses-permission android:name="android.permission.INTERNET"/>
   <uses-permission android:name="android.permission.WAKE_LOCK"/>
   <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
   <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK"/>
   <!-- Dynamically requested at runtime -->
   <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
   <uses-permission android:name="android.permission.READ_MEDIA_AUDIO"/>
   

2. Service Declaration: The plugin automatically declares its MusicService in its own manifest, which is merged with your app's manifest. No extra manual service declaration is typically needed in your app's AndroidManifest.xml.

iOS

1. Add the following keys to your Info.plist:
   • UIBackgroundModes: Add audio to allow background playback.
   • NSMicrophoneUsageDescription: (If required by store submission, though typically not used for playback only).
   • NSAppleMusicUsageDescription: For accessing media library.

Usage

Initialization

Initialize the player early in your app lifecycle.

final player = AdvancedMusicPlayer();
await player.initialize();

Permissions & Local Files

To fetch local songs, request permission first. The plugin handles the complexity of Android 13+ vs older versions.

// Request permission
bool granted = await player.requestStoragePermission();

if (granted) {
  // Fetch system audio files
  List<AudioTrack> localSongs = await player.getSystemAudioFiles();
  
  // Set queue and play
  await player.setQueue(localSongs);
}

Playback Controls

// Play specific URL
await player.playUrl(
  'https://example.com/song.mp3',
  title: 'My Song',
  artist: 'Great Artist',
);

// Standard controls
await player.play();
await player.pause();
await player.stop();
await player.next();
await player.previous();
await player.seek(Duration(seconds: 30));

// Modes
player.setShuffleMode(true);
player.setRepeatMode(RepeatMode.all); // none, all, one

Reactive UI Widgets

The plugin includes pre-built widgets that listen to the player's streams, removing the need for setState boilerplate in your UI.

AdvancedPlayerSlider

A slider that automatically updates with playback position and lets the user drag to seek. It now automatically syncs with the track's duration.

AdvancedPlayerSlider(
  activeColor: Colors.blue,
  inactiveColor: Colors.grey,
  thumbColor: Colors.blueAccent,
  timeLabelStyle: TextStyle(color: Colors.black),
)

PlayPauseButton

A button that toggles between Play and Pause states with a smooth transition animation.

PlayPauseButton(
  size: 48.0,
  color: Colors.blue,
  playIcon: Icons.play_arrow,
  pauseIcon: Icons.pause,
  // Optional: Use custom widgets instead of icons
  playWidget: SvgPicture.asset('assets/play.svg'),
  pauseWidget: SvgPicture.asset('assets/pause.svg'),
  animationDuration: Duration(milliseconds: 300),
  // Optional: Custom animation (e.g., Rotation)
  transitionBuilder: (child, animation) {
    return RotationTransition(turns: animation, child: child);
  },
)

API Reference

AdvancedMusicPlayer

• Future<void> initialize(): Sets up method channels and listeners.
• Stream<Duration> get positionStream: Emits standard playback position updates.
• Stream<Duration> get durationStream: Emits the total duration of the current track.
• Stream<PlayerState> get playerStateStream: Emits stopped, playing, paused, or buffering.
• Future<bool> requestStoragePermission(): Requests platform-appropriate storage/audio permissions.
• Future<List<AudioTrack>> getSystemAudioFiles(): Scans device for audio files.
• Future<void> setQueue(List<AudioTrack> tracks, {int initialIndex}): Replaces current queue and plays.
• Future<void> playUrl(...): Plays a single track immediately.

AudioTrack

A simple data class for track info:

• String source: URL or file path.
• String title: Track title.
• String artist: Artist name.
• String artworkUrl: (Optional) URL for album art.