Skip to content
pubscout

audio_service

0.18.19, released 5 months ago by ryanheise.com

Flutter plugin for background audio playback with media controls.

$ flutter pub add audio_service
Source repository

What it does

Provides a way to run audio code in the background while the screen is off. It exposes a standard AudioHandler API that forwards media actions to your own player implementation and updates system notifications, lock screen, headset buttons and Android Auto/Apple CarPlay.

AI-written summary of version 0.18.19, based on the package's README and metadata. Report an inaccuracy

Use it when

  • You need background audio that continues when the app is minimized or the screen is locked
  • You want system media controls, notifications, lock‑screen or Android Auto integration
  • You need a unified API that works on Android, iOS, web and macOS

Skip it when

  • Your app only plays short foreground sounds and doesn’t need background playback
  • You prefer a zero‑native‑code solution for simple audio
  • You already use a full‑featured media player that handles its own background service

Strengths

  • Full platform support (Android, iOS, web, macOS, Linux via MPRIS)
  • Works with any audio engine (just_audio, flutter_tts, etc.)
  • Rich feature set: queue, shuffle, repeat, custom actions, lock‑screen UI

Weaknesses

  • Requires native configuration (Android manifest, iOS background modes)
  • Adds complexity compared to plain audio players
  • May be overkill for simple use‑cases

Setup

Kind
Plugin (native code)
Effort
Medium
Code generation
No
Direct dependencies
7

Add Android permissions and notification channel in AndroidManifest.xml, enable Background Modes (Audio) in Xcode, configure AudioServiceConfig with channel IDs, and ensure a compatible audio player (e.g., just_audio) is used inside the AudioHandler.

import 'package:audio_service/audio_service.dart';
import 'package:just_audio/just_audio.dart';

class MyAudioHandler extends BaseAudioHandler with QueueHandler, SeekHandler {
  final _player = AudioPlayer();
  @override Future<void> play() => _player.play();
  @override Future<void> pause() => _player.pause();
  @override Future<void> stop() => _player.stop();
  @override Future<void> seek(Duration position) => _player.seek(position);
}

Future<void> main() async {
  final audioHandler = await AudioService.init(
    builder: () => MyAudioHandler(),
    config: AudioServiceConfig(
      androidNotificationChannelId: 'com.example.channel.audio',
      androidNotificationChannelName: 'Audio Playback',
    ),
  );
  runApp(MyApp());
}

Alternatives

Packages that do the same job and could replace audio_service.

Works with

Packages commonly used together with audio_service: ones it builds on, ones built on it, and its own family.