Getting started

Android

The required permissions for audio playback (WAKE_LOCK, and FOREGROUND_SERVICE_MEDIA_PLAYOUT) are automatically added by the package. You don't need to manually edit your AndroidManifest.xml.

Additionally, to enable system-integrated audio controls (notification/lockscreen) using audio_service, your app's MainActivity must extend AudioServiceActivity:

Kotlin:

import com.ryanheise.audioservice.AudioServiceActivity

class MainActivity: AudioServiceActivity()

Java:

import com.ryanheise.audioservice.AudioServiceActivity;

public class MainActivity extends AudioServiceActivity {}

If you don't apply this change, the audio will still work locally, but system controls won't be available.

iOS

For background audio playback, you must add the following to your app's Info.plist:

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

macOS

macOS requires a network entitlement. Open macos/Runner/DebugProfile.entitlements and add:

<key>com.apple.security.network.client</key>
<true/>

⚠️ Also add the same key to macos/Runner/Release.entitlements, otherwise release builds cannot reach the network for audio streaming.

The library works out of the box on macOS (just_audio uses the native AVAudioPlayer backend). The minimum deployment target should be macOS 11.0.

Windows & Linux

No manual setup is required. The library automatically initializes the media_kit audio backend on Windows and Linux via just_audio_media_kit during QuranAudio.init(). Just run:

flutter run -d windows   # or -d linux

Note: System media notifications (lock-screen controls) are not available on Windows, Linux, or macOS — this is an audio_service limitation. Audio playback itself works fully on all desktop platforms.

Web

The library works on web in streaming-only mode (no offline downloads, since browsers have no file system). QuranAudio.init() handles everything automatically:

flutter run -d chrome

• ✅ Play surahs & ayahs (streamed from network URLs)
• ✅ Reciter selection, repeat modes, playback controls
• ❌ Offline downloads (not possible on web — use streaming instead)
• ❌ System media notifications (not supported on web by audio_service)

Installation

In the pubspec.yaml of your flutter project, add the following dependency:

dependencies:
  ...
  quran_audio: ^1.0.0

Import it:

import 'package:quran_audio/quran_audio.dart';

Initialize it:

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  // Initialize the entire library in one step
  await QuranAudio.init();
  runApp(const MyApp());
}

💡 QuranAudio.init() accepts optional parameters:

await QuranAudio.init(
  enableSystemNotifications: true,   // false = no notifications (lighter, for web/tests)
  androidNotificationChannelId: 'com.myapp.quran',
  androidNotificationChannelName: 'Quran Playback',
  notificationIconSource: 'assets/images/logo.png', // custom icon (asset/url/file)
);

By default, QuranAudio.init() uses the library's bundled icon for the system media notification. To change it at runtime, see Notification Icon.