audio_service

The audio_service plugin works by encapsulating your audio logic within an AudioHandler. This handler implements standard system callbacks that respond to media playback requests from various sources (e.g., lock screen, headset buttons, Android Auto, Apple CarPlay) in a uniform way.

You implement these callbacks to trigger your specific audio engine (like just_audio for music or flutter_tts for speech). The AudioHandler acts as the single source of truth, broadcasting state changes to both the system (notifications/controls) and your Flutter UI.

class MyAudioHandler extends BaseAudioHandler
    with QueueHandler, 
    SeekHandler {

  final _player = AudioPlayer(); // e.g. just_audio
  
  Future<void> play() => _player.play();
  Future<void> pause() => _player.pause();
  Future<void> stop() => _player.stop();
  Future<void> seek(Duration position) => _player.seek(position);
  Future<void> skipToQueueItem(int i) => _player.seek(Duration.zero, index: i);
}

To manage how your app interacts with other audio apps (e.g., ducking volume vs. pausing), use the audio_session package. This allows you to define usage scenarios like speech() for podcast players.

If your audio plugin does not automatically activate the session, you can manually call session.setActive(true). You can also listen to session.interruptionEventStream to handle interruptions or session.becomingNoisyEventStream to handle headphone unplugging events.

Note: If using multiple audio plugins, apply your preferred configuration using audio_session after all other audio plugins have loaded to prevent them from overriding your settings.

final session = await AudioSession.instance;
await session.configure(AudioSessionConfiguration.speech());

// Manually activate if the plugin doesn't
if (await session.setActive(true)) {
  // Now play audio.
} else {
  // The request was denied
}

To enable background audio services on Android, you must modify AndroidManifest.xml and handle resource preservation.

1. Update AndroidManifest.xml

Add the required permissions, update your existing activity, and add the AudioService and MediaButtonReceiver elements.

2. Handle Foreground Service Restrictions

On Android 12+, to avoid ForegroundServiceStartNotAllowedException, you can:

• Set androidStopForegroundOnPause to false in your AudioServiceConfig (keeps the service in the foreground during pause).
• Or, keep the default true and request the user to disable battery optimization using the optimize_battery package.

3. Prevent Icon Stripping

If using custom notification icons, create android/app/src/main/res/raw/keep.xml to prevent R8 from stripping them during build.

<!-- AndroidManifest.xml snippet -->
<manifest xmlns:tools="http://schemas.android.com/tools" ...>
  <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"/>
  
  <application ...>
    <activity android:name="com.ryanheise.audioservice.AudioServiceActivity" ...> ... </activity>
    
    <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> 
  </application>
</manifest>

The AudioHandler is the primary interface for controlling audio playback and providing state updates. It allows your app to be controlled by external agents like lock screens, headsets, and car audio systems.

Important: You cannot subclass AudioHandler directly. You must subclass BaseAudioHandler (or CompositeAudioHandler for multiple behaviors) and then implement the required methods.

Key capabilities include:

• Playback Control: play(), pause(), stop(), seek(Duration position), skipToNext(), skipToPrevious().
• Queue Management: addQueueItem(), updateQueue(), removeQueueItem(), skipToQueueItem(int index).
• Media Management: prepareFromMediaId(), playMediaItem(), updateMediaItem().
• State Observation: Accessing playbackState, mediaItem, queue, and customEvent streams.
• Custom Actions: Using customAction(String name, [Map<String, dynamic>? extras]) to implement app-specific logic.

// Example of what an implementation might look like (conceptually)
class MyAudioHandler extends BaseAudioHandler {
  @override
  Future<void> play() async {
    // implementation logic
  }

  @override
  Future<void> pause() async {
    // implementation logic
  }
  
  // ... other overrides
}

The audio_service plugin uses MediaAction to represent the intent of a user interaction and MediaControl to represent the actual button shown in the UI (Android notification, iOS control center, etc.).

Supported MediaActions

Common actions include:

• MediaAction.play, MediaAction.pause, MediaAction.stop
• MediaAction.skipToNext, MediaAction.skipToPrevious
• MediaAction.seek, MediaAction.playPause
• MediaAction.setRepeatMode, MediaAction.setShuffleMode
• MediaAction.custom (for user-defined actions)

MediaControl

Each MediaControl maps a MediaAction to a specific UI element. You can use predefined controls or create custom ones:

• Predefined: MediaControl.play, MediaControl.pause, MediaControl.stop, MediaControl.next, etc.
• Custom: Use MediaControl.custom to define a unique action name and optional extras.

// Example of a custom control
MediaControl.custom(
  androidIcon: 'drawable/ic_custom_action',
  label: 'My Custom Action',
  name: 'my_action_name',
  extras: {'key': 'value'},
);