quran_audio — Documentation

Usage Example

Play a Surah

Play a full surah (single MP3 file per surah):

// Play Surah Al-Baqarah
QuranAudio.playSurah(2);

// Play Surah Al-Fatihah
QuranAudio.playSurah(1);

Play a Specific Ayah

Play a specific ayah by surah number and ayah number:

// Play Ayat al-Kursi (2:255), continue to following ayahs
QuranAudio.playAyah(
  surah: 2,
  ayah: 255,
  singleAyah: false, // false = continue to next ayahs
);

// Play a single ayah then stop
QuranAudio.playAyah(
  surah: 36,
  ayah: 1,
  singleAyah: true,
);

Playback Controls

Controls automatically execute on the currently active system — no need to know which is running.

QuranAudio.pause();               // Pause (active system)
QuranAudio.resume();              // Resume (active system)
QuranAudio.stop();                // Stop completely
QuranAudio.next();                // Next (surah or ayah)
QuranAudio.previous();            // Previous (surah or ayah)
QuranAudio.seek(Duration(minutes: 5));  // Seek to position
QuranAudio.togglePlayPause();     // Toggle play/pause

Complete Audio Example

class AudioPlayerScreen extends StatelessWidget {
  const AudioPlayerScreen({super.key});

  @override
  Widget build(BuildContext context) {
    final c = QuranAudio.surahController;
    return Scaffold(
      appBar: AppBar(title: const Text('Quran Audio Player')),
      body: Column(
        children: [
          // Reactive now-playing display
          Obx(() {
            final surahNo = c.currentSurahNumber.value;
            final meta = QuranAudio.surah(surahNo);
            return Text('${meta.name} — ${meta.englishName}');
          }),

          // Control buttons
          Row(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              IconButton(
                onPressed: QuranAudio.previous,
                icon: const Icon(Icons.skip_previous),
              ),
              IconButton(
                onPressed: QuranAudio.togglePlayPause,
                icon: const Icon(Icons.play_arrow),
              ),
              IconButton(
                onPressed: QuranAudio.next,
                icon: const Icon(Icons.skip_next),
              ),
              IconButton(
                onPressed: QuranAudio.stop,
                icon: const Icon(Icons.stop),
              ),
            ],
          ),

          // Progress bar
          StreamBuilder<PositionData>(
            stream: QuranAudio.positionDataStream,
            builder: (context, snap) {
              final d = snap.data;
              return Slider(
                value: d?.position.inSeconds.toDouble() ?? 0,
                max: d?.duration.inSeconds.toDouble() ?? 1,
                onChanged: (v) => QuranAudio.seek(
                  Duration(seconds: v.toInt()),
                ),
              );
            },
          ),

          // Play buttons
          ElevatedButton(
            onPressed: () => QuranAudio.playSurah(1),
            child: const Text('Play Al-Fatihah'),
          ),
          ElevatedButton(
            onPressed: () => QuranAudio.playAyah(surah: 2, ayah: 255),
            child: const Text('Play Ayat al-Kursi'),
          ),
        ],
      ),
    );
  }
}