mt_audio #

A stream-based audio module for Flutter. Provides background playback, system notifications, queue management, and first-class Android Auto & Apple CarPlay support -- all behind a single facade class and zero external state management dependencies.

This package reduces implementation overhead when combining packages such as just_audio and audio_service. It provides a simple wrapper API that captures our long-standing Flutter audio expertise in a single dependency.

Features #

• Background playback with lock screen controls and media notifications
• Queue management - add, insert, remove, reorder, shuffle
• Seek forward / backward with configurable intervals
• Playback speed control (0.5x - 2.0x)
• Repeat modes - off, one, all
• Live stream support with ICY metadata
• Android Auto integration via delegate pattern
• Apple CarPlay integration with list, grid, and tab bar templates
• Pre-built widgets - seek bar, play/pause, skip, speed selector, queue list, artwork, now playing info, and a full player builder
• State management agnostic - rxdart BehaviorSubject streams with synchronous getters
• Audio session handling - automatic interruption and becoming-noisy management

Core Stack #

Installation #

Add to your pubspec.yaml:

dependencies:
  mt_audio: ^0.2.0-beta.3

Platform Setup #

Android #

1. AndroidManifest.xml

Open android/app/src/main/AndroidManifest.xml and apply the following changes.

Add the tools namespace to the root <manifest> element:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

Add required permissions:

<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"/>

Replace the default activity class name with the audio_service wrapper:

<activity android:name="com.ryanheise.audioservice.AudioServiceActivity" ...>
  ...
</activity>

Add the audio service and media button receiver inside <application>:

<service android:name="com.ryanheise.audioservice.AudioService"
    android:foregroundServiceType="mediaPlayback"
    android:exported="true"
    tools:ignore="Instantiatable">
    <intent-filter>
        <action android:name="android.media.browse.MediaBrowserService" />
    </intent-filter>
</service>

<receiver android:name="com.ryanheise.audioservice.MediaButtonReceiver"
    android:exported="true"
    tools:ignore="Instantiatable">
    <intent-filter>
        <action android:name="android.intent.action.MEDIA_BUTTON" />
    </intent-filter>
</receiver>

2. HTTP streaming (optional)

If you stream audio over plain HTTP (not HTTPS), add to the <application> element:

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

3. Android Auto (optional)

To enable Android Auto media browsing, create android/app/src/main/res/xml/automotive_app_desc.xml:

<automotiveApp>
    <uses name="media"/>
</automotiveApp>

Then reference it in your AndroidManifest.xml inside <application>:

<meta-data
    android:name="com.google.android.gms.car.application"
    android:resource="@xml/automotive_app_desc"/>

iOS #

1. Info.plist

Add background audio mode to ios/Runner/Info.plist:

<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

If streaming over plain HTTP, also add:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

2. CarPlay (optional)

CarPlay requires additional setup. See the Apple CarPlay Integration section below.

Podfile -- ensure minimum iOS 14.0:

platform :ios, '14.0'

AppDelegate.swift -- replace with a shared Flutter engine to support both phone and CarPlay scenes:

import UIKit
import Flutter

let flutterEngine = FlutterEngine(
    name: "SharedEngine", project: nil, allowHeadlessExecution: true
)

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
    override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        flutterEngine.run()
        GeneratedPluginRegistrant.register(with: flutterEngine)
        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }
}

SceneDelegate.swift -- create ios/Runner/SceneDelegate.swift:

@available(iOS 13.0, *)
class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession,
               options connectionOptions: UIScene.ConnectionOptions) {
        guard let windowScene = scene as? UIWindowScene else { return }
        window = UIWindow(windowScene: windowScene)
        let controller = FlutterViewController(
            engine: flutterEngine, nibName: nil, bundle: nil
        )
        controller.loadDefaultSplashScreenView()
        window?.rootViewController = controller
        window?.makeKeyAndVisible()
    }
}

Info.plist -- add scene manifest with both phone and CarPlay scenes:

<key>UIApplicationSceneManifest</key>
<dict>
    <key>UIApplicationSupportsMultipleScenes</key>
    <true/>
    <key>UISceneConfigurations</key>
    <dict>
        <key>CPTemplateApplicationSceneSessionRoleApplication</key>
        <array>
            <dict>
                <key>UISceneConfigurationName</key>
                <string>CarPlay Configuration</string>
                <key>UISceneDelegateClassName</key>
                <string>mt_carplay.FlutterCarPlaySceneDelegate</string>
            </dict>
        </array>
        <key>UIWindowSceneSessionRoleApplication</key>
        <array>
            <dict>
                <key>UISceneConfigurationName</key>
                <string>Default Configuration</string>
                <key>UISceneDelegateClassName</key>
                <string>$(PRODUCT_MODULE_NAME).SceneDelegate</string>
                <key>UISceneStoryboardFile</key>
                <string>Main</string>
            </dict>
        </array>
    </dict>
</dict>

Entitlements -- in Xcode, enable the com.apple.developer.carplay-audio entitlement. You must first request CarPlay Audio access from Apple via https://developer.apple.com/contact/carplay and update your provisioning profile.

Quick Start #

Initialize the player #

import 'package:mt_audio/mt_audio.dart';

final player = await MtAudioPlayer.init(
  config: MtAudioPlayerConfig(
    notificationChannelId: 'audio_playback',
    notificationChannelName: 'Audio Playback',
    notificationIcon: 'mipmap/ic_launcher',
    ffRewindInterval: Duration(seconds: 10),
  ),
);

Set an audio source #

// Single track
await player.setAudioItem(
  MtAudioItem(
    id: '1',
    uri: Uri.parse('https://example.com/audio.mp3'),
    title: 'My Song',
    artist: 'Artist Name',
    artworkUri: Uri.parse('https://example.com/artwork.jpg'),
    duration: Duration(minutes: 3, seconds: 45),
  ),
);

// Playlist
await player.setPlaylist(
  [item1, item2, item3],
  initialIndex: 0,
);

// Live stream (isLive flag on the item controls live behavior)
await player.setAudioItem(
  MtAudioItem(
    id: 'live',
    uri: Uri.parse('https://example.com/stream'),
    title: 'Live Radio',
    isLive: true,
  ),
);

Control playback #

await player.play();
await player.pause();
await player.stop();

// Seeking
await player.seekTo(Duration(seconds: 30));
await player.seekForward();
await player.seekBackward();

// Queue navigation
await player.skipToNext();
await player.skipToPrevious();
await player.skipToIndex(2);

// Playback modes
await player.setRepeatMode(MtRepeatMode.all);
await player.setShuffleMode(true);
await player.setSpeed(1.5);
await player.setVolume(0.8);

Listen to state changes #

All state is exposed via BehaviorSubject streams that always hold a current value. Synchronous getters (e.g. player.currentPlaybackState) are available for one-off reads.

// Playback state
player.playbackStateStream.listen((state) {
  print('Status: ${state.status}');   // MtPlaybackStatus enum
  print('Playing: ${state.isPlaying}');
  print('Speed: ${state.speed}');
  print('Repeat: ${state.repeatMode}');
});

// Position updates
player.positionStateStream.listen((state) {
  print('Position: ${state.position}');
  print('Duration: ${state.duration}');
  print('Progress: ${state.progress}'); // 0.0 to 1.0
});

// Queue updates
player.queueStateStream.listen((state) {
  print('Queue: ${state.queue.length} items');
  print('Index: ${state.queueIndex}');
  print('Has next: ${state.hasNext}');
});

// Current item
player.currentItemStream.listen((item) {
  print('Now playing: ${item?.title}');
});

// Errors
player.errorStream.listen((error) {
  if (error != null) {
    print('Error [${error.code}]: ${error.message}');
  }
});

// ICY metadata (live streams)
player.icyMetadataStream.listen((metadata) {
  print('Stream title: ${metadata?.info?.title}');
});

Manage the queue #

await player.addToQueue(newItem);
await player.insertInQueue(2, newItem);
await player.removeFromQueue(3);
await player.reorderQueue(oldIndex: 2, newIndex: 5);
await player.clearQueue();

Widgets #

All widgets take MtAudioPlayer player as a required parameter and use StreamBuilder internally -- no external state management needed.

Seek Bar #

MtSeekBar(
  player: player,
  showLabels: true,
)

Play / Pause Button #

MtPlayPauseButton(
  player: player,
  size: 64.0,
  color: Colors.white,
  playIcon: Icons.play_arrow,   // customizable
  pauseIcon: Icons.pause,       // customizable
)

Skip Buttons (fast forward / rewind by interval) #

Row(
  children: [
    MtSkipButton(player: player, direction: MtSkipDirection.backward),
    MtPlayPauseButton(player: player),
    MtSkipButton(player: player, direction: MtSkipDirection.forward),
  ],
)

Track Skip Buttons (next / previous track) #

Row(
  children: [
    MtTrackSkipButton(player: player, direction: MtTrackSkipDirection.previous),
    MtPlayPauseButton(player: player),
    MtTrackSkipButton(player: player, direction: MtTrackSkipDirection.next),
  ],
)

Speed Selector #

MtSpeedSelector(
  player: player,
  speeds: [0.5, 0.75, 1.0, 1.25, 1.5, 2.0],
)

Artwork & Now Playing Info #

Column(
  children: [
    MtArtwork(
      artworkUri: player.currentItem?.artworkUri,
      size: 300,
      borderRadius: 8.0,
    ),
    SizedBox(height: 16),
    MtNowPlayingInfo(
      player: player,
      showAlbum: true,
    ),
  ],
)

Queue List #

MtQueueListView(
  player: player,
  enableReorder: true,
  enableDismiss: true,
)

Custom UI with MtPlayerBuilder #

MtPlayerBuilder combines all player streams into a single MtPlayerState object, making it easy to build fully custom UIs:

MtPlayerBuilder(
  player: player,
  builder: (context, state) {
    return Column(
      children: [
        Text(state.currentItem?.title ?? 'No track'),
        Text('${state.position} / ${state.duration}'),
        Slider(
          value: state.progress,
          onChanged: (value) {
            final duration = state.duration;
            if (duration != null) {
              player.seekTo(Duration(
                milliseconds: (value * duration.inMilliseconds).round(),
              ));
            }
          },
        ),
        Row(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            IconButton(
              icon: Icon(Icons.skip_previous),
              onPressed: player.skipToPrevious,
            ),
            IconButton(
              icon: Icon(state.isPlaying ? Icons.pause : Icons.play_arrow),
              onPressed: state.isPlaying ? player.pause : player.play,
            ),
            IconButton(
              icon: Icon(Icons.skip_next),
              onPressed: player.skipToNext,
            ),
          ],
        ),
      ],
    );
  },
)

MtPlayerState exposes: playbackState, positionState, queueState, currentItem, speed, isPlaying, isPaused, isLoading, position, duration, progress.

Android Auto Integration #

1. Implement the delegate #

class MyAndroidAutoDelegate implements MtAndroidAutoDelegate {
  MyAndroidAutoDelegate({required this.player});
  final MtAudioPlayer player;

  @override
  Future<List<MtMediaLibraryItem>> getChildren(String? parentMediaId) async {
    if (parentMediaId == null || parentMediaId == 'root') {
      return const [
        MtBrowsableItem(id: 'songs', title: 'Songs'),
        MtBrowsableItem(id: 'radio', title: 'Live Radio'),
      ];
    }

    if (parentMediaId == 'songs') {
      return tracks.map((t) => MtPlayableItem(item: t)).toList();
    }

    return [];
  }

  @override
  Future<void> onPlayFromMediaId(String mediaId) async {
    final track = await repository.getTrackById(mediaId);
    await player.setAudioItem(track);
    await player.play();
  }

  @override
  Future<List<MtAudioItem>> search(String query) async {
    return tracks.where((t) => t.title.contains(query)).toList();
  }

  @override
  void onConnect() {}

  @override
  void onDisconnect() {}
}

Item types:

2. Pass factory during initialization #

The delegate factory receives the MtAudioPlayer instance, solving the circular dependency:

final player = await MtAudioPlayer.init(
  config: MtAudioPlayerConfig(
    notificationChannelId: 'audio',
    notificationChannelName: 'Audio',
    androidAutoDelegateFactory: (player) =>
        MyAndroidAutoDelegate(player: player),
  ),
);

Apple CarPlay Integration #

1. Implement the delegate #

class MyCarPlayDelegate extends MtCarPlayDelegate {
  MyCarPlayDelegate({required this.player});
  final MtAudioPlayer player;

  @override
  MtCarPlayRootConfig get rootConfig => MtCarPlayRootConfig.list(
    title: 'My Music App',
    systemIcon: 'music.note.list',
  );

  @override
  Future<List<MtCarPlayItem>> getChildren(String? parentId) async {
    if (parentId == null) {
      return [
        MtCarPlayBrowsableItem(id: 'songs', title: 'Songs', subtitle: '5 tracks'),
        MtCarPlayBrowsableItem(
          id: 'genres',
          title: 'Genres',
          templateType: MtCarPlayTemplateType.grid,
        ),
      ];
    }

    if (parentId == 'songs') {
      return tracks.map((t) => MtCarPlayPlayableItem(item: t)).toList();
    }

    return [];
  }

  @override
  Future<void> onPlayFromMediaId(String mediaId) async {
    final track = await repository.getTrackById(mediaId);
    await player.setAudioItem(track);
    await player.play();
  }
}

Item types:

2. Sections with headers (optional) #

Override getSections for grouped content with section headers:

@override
Future<List<MtCarPlaySection>> getSections(String? parentId) async {
  if (parentId == null) {
    return [
      MtCarPlaySection(
        header: 'Recently Played',
        items: recentTracks.map((t) => MtCarPlayPlayableItem(item: t)).toList(),
      ),
      MtCarPlaySection(
        header: 'Browse',
        items: [
          MtCarPlayBrowsableItem(id: 'songs', title: 'All Songs'),
          MtCarPlayBrowsableItem(id: 'albums', title: 'Albums'),
        ],
      ),
    ];
  }
  return super.getSections(parentId);
}

3. Tab Bar root template (optional) #

For apps with multiple content categories, use a tab bar at root level:

@override
MtCarPlayRootConfig get rootConfig => MtCarPlayRootConfig.tabBar(
  title: 'My Music App',
  tabBarConfig: MtCarPlayTabBarConfig(
    tabs: [
      MtCarPlayTab(title: 'Library', systemIcon: 'music.note.house', rootId: 'library'),
      MtCarPlayTab(title: 'Playlists', systemIcon: 'list.bullet', rootId: 'playlists'),
      MtCarPlayTab(title: 'Radio', systemIcon: 'radio', rootId: 'radio'),
    ],
  ),
);

4. Pass factory during initialization #

final player = await MtAudioPlayer.init(
  config: MtAudioPlayerConfig(
    notificationChannelId: 'audio',
    notificationChannelName: 'Audio',
    carPlayDelegateFactory: (player) =>
        MyCarPlayDelegate(player: player),
  ),
);

5. Programmatic control #

final carPlay = player.carPlay;

// Connection status
if (carPlay?.isConnected ?? false) { ... }
carPlay?.connectionStream.listen((connected) { ... });

// Navigation
await carPlay?.refresh();       // Reload content after data changes
await carPlay?.pop();
await carPlay?.popToRoot();
await carPlay?.showNowPlaying();

CarPlay capabilities #

Architecture #

Consumer App
    |
    v
MtAudioPlayer  (public facade -- single entry point)
    |
    +---> MtAudioHandler       (internal: bridges just_audio <-> audio_service)
    +---> MtAudioSessionManager (internal: audio interruptions & becoming noisy)
    +---> MtCarPlayHandler      (public: CarPlay lifecycle & templates)

• MtAudioPlayer -- the only class consumers instantiate. Created via async factory MtAudioPlayer.init().
• Models -- immutable, Equatable-based state classes: MtAudioItem, MtPlaybackState, MtPositionState, MtQueueState, MtAudioError.
• Widgets -- pre-built StreamBuilder-based UI components.
• Delegates -- abstract classes for Android Auto (MtAndroidAutoDelegate) and CarPlay (MtCarPlayDelegate) that the consumer implements.

Troubleshooting #

No sound on iOS #

• Ensure audio background mode is enabled in Info.plist
• Audio session configuration is handled automatically by mt_audio

Notification not showing on Android #

• Verify FOREGROUND_SERVICE and FOREGROUND_SERVICE_MEDIA_PLAYBACK permissions
• Check that the notification channel ID matches your MtAudioPlayerConfig
• Ensure the AudioService service is declared in the manifest

Android Auto not working #

• Verify automotive_app_desc.xml exists and is referenced in the manifest
• Confirm androidAutoDelegateFactory is provided during initialization
• Test with the Android Auto Desktop Head Unit (DHU)

CarPlay not working #

• Verify com.apple.developer.carplay-audio entitlement is enabled
• Check that CarPlay Audio is enabled in your provisioning profile
• Ensure carPlayDelegateFactory is provided during initialization
• Test with the Xcode CarPlay Simulator first

License #

This package is licensed under the MIT License. See LICENSE.

Third-party sample assets #

The example app uses third-party sample media and images for demonstration only. See THIRD_PARTY_ASSETS.md for sources, usage notes, and attribution details.