Getting flutter audio_service background playback right is the difference between a music or radio app people love and one they uninstall after a day. Listeners expect the sound to keep going when they lock the phone, switch to another app or press pause on their headphones. In this guide, we walk through the setup for Android and iOS in plain language, so even beginners can follow along.
Whether you are building a radio station app, a podcast player or an audiobook app for your business, the steps below will help you avoid the most common mistakes.
What Is audio_service and Why Do You Need It?
By default, a Flutter app can play sound only while it is open on the screen. Once the user leaves, the operating system may pause or stop your app to save battery. The audio_service package solves this by running your audio inside a proper background media session.
With it, your app can:
- Keep playing audio when the screen is locked or the app is minimised
- Show play, pause and skip controls in the notification and on the lock screen
- Respond to headphone buttons, Bluetooth devices and car systems
- Display the track title, artist and artwork to the listener
One important point: audio_service does not play sound by itself. It manages the session and controls. You pair it with a player package, most commonly just_audio, which handles the actual streaming and playback.
Step 1: Add the Packages
Open your pubspec.yaml file and add audio_service and just_audio under dependencies. Many developers also add audio_session, which helps configure how your app behaves alongside other sounds, such as phone calls or navigation voices.
Run flutter pub get to install them. Always check each package's page for the latest version and any updated setup notes, because the configuration can change between releases.
Step 2: Create Your Audio Handler
The heart of any flutter audio_service background setup is the audio handler. This is a class you write that extends BaseAudioHandler. It connects the system controls to your player.
What the handler should do
- Create a just_audio player inside the class.
- Override methods such as play, pause, stop and seek, and call the matching player functions.
- Listen to the player's events and update the playbackState so the notification shows the correct button (play or pause).
- Set the mediaItem with title, artist and artwork so listeners see what is playing.
Initialise it at startup
In your main() function, call AudioService.init() before running the app, passing your handler and a config. The config lets you set the Android notification channel ID and name, and choose whether the notification stays ongoing while playing. Initialise it only once; calling it multiple times is a frequent cause of crashes.
Step 3: Android Setup
Android needs a few changes in android/app/src/main/AndroidManifest.xml. Skipping any of these is the number one reason audio stops or the notification never appears.
Permissions
- WAKE_LOCK keeps the device processing audio while the screen is off.
- FOREGROUND_SERVICE and, on newer Android versions, FOREGROUND_SERVICE_MEDIA_PLAYBACK allow the background media service.
- POST_NOTIFICATIONS is needed on Android 13 and later so your media notification can be shown.
- INTERNET if you stream radio or online audio.
Service, receiver and activity
Declare the AudioService service with the media browser intent filter and a mediaPlayback foreground service type. Also declare the MediaButtonReceiver so headphone buttons work.
Finally, change your main activity so it extends AudioServiceActivity instead of the default FlutterActivity (or follow the package's alternative instructions if you use a custom activity). This small step is easy to forget, and without it the connection between Flutter and the service can fail.
You will also need a small monochrome notification icon in your drawable folder. Coloured icons often show up as plain white squares.
Step 4: iOS Setup
iOS is simpler, but strict. Open ios/Runner/Info.plist and add the UIBackgroundModes key with the value audio. You can also enable it in Xcode under Signing & Capabilities by adding Background Modes and ticking "Audio, AirPlay, and Picture in Picture".
Next, use the audio_session package to configure the session for music or playback. This tells iOS your app is a real audio app, so it will not be silenced by the mute switch and will keep playing in the background.
If you stream over plain HTTP (common with older radio streams), iOS may block the connection. Use HTTPS streams whenever possible, or configure App Transport Security exceptions carefully.
Common Problems and How to Fix Them
Even with a careful flutter audio_service background setup, a few issues pop up again and again:
- Audio stops after a few minutes on Android: Some phone brands use aggressive battery saving. Make sure the foreground service is running and ask users to allow unrestricted battery usage if needed.
- Notification buttons don't change: Your handler is not updating playbackState correctly. Broadcast state every time the player changes.
- No lock screen info on iOS: The mediaItem is missing or set before the handler is ready.
- App crashes on launch: AudioService.init() is called twice or the main activity wasn't updated.
- Live radio shows a strange duration: For live streams, leave the duration empty so the seek bar does not confuse listeners.
Tip: Always test on real devices, not just emulators. Lock the screen, switch apps, unplug headphones and receive a call to see how your app behaves.
Build It Yourself or Start With a Ready App?
Learning to set up flutter audio_service background playback is a great skill, but for a business owner, time matters. If your goal is to launch a radio station app quickly, starting from a tested product can save weeks of debugging.
For example, our Single Radio Flutter app for Android & iOS includes a music visualizer, sleep timer and AdMob support, ready for you to brand as your own. If you need streaming for your station too, take a look at our SonicPanel Radio plans on the hosting page.
Need features that go beyond a ready-made app, such as playlists, user accounts or a custom design? Our team builds cross-platform apps with one codebase for both stores through Flutter App Development.
Final Thoughts
A reliable flutter audio_service background setup comes down to four things: a solid audio handler, correct Android manifest entries, the iOS audio background mode, and thorough testing on real phones. Get these right and your listeners will enjoy smooth, uninterrupted audio wherever they are.
Ready to launch your audio or radio app without the headaches? Tell us about your project and get a free quote from the Anow Hosting team today.
Frequently asked questions
What does the audio_service package do in Flutter?
It lets your Flutter app keep playing audio when the screen is off or the app is in the background. It also shows media controls on the lock screen, in the notification area and on connected devices like headphones.
Does audio_service play audio by itself?
No. audio_service handles the background session and media controls. You pair it with a player package such as just_audio to actually play the sound.
Why does my Flutter audio stop on iOS when the app is closed?
Usually the Audio background mode is missing from Info.plist. Add the audio value under UIBackgroundModes and configure the audio session for playback.
Why is there no notification on Android?
Check that your AndroidManifest.xml declares the AudioService service and media button receiver, that your main activity uses AudioServiceActivity, and that the notification permission is granted on newer Android versions.
Can I get a ready-made Flutter radio app instead of building one?
Yes. Anow Hosting offers a ready Flutter radio app for Android and iOS, and also custom Flutter app development if you need something tailored.
