flutter_downloaded_audio_play_in_notification

A Flutter plugin for playing downloaded audio files in notifications with background playback support. This plugin allows you to play custom audio files when notifications are received, even when the app is in terminated state.

Features

✅ Play custom audio files from URLs in notifications
✅ Background audio playback support
✅ Audio playback when app is terminated
✅ Stop audio from notification tap
✅ Android native implementation with ExoPlayer
✅ Firebase Cloud Messaging integration
✅ Robust audio stopping from terminated state

Screenshots

App Screenshot

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_downloaded_audio_play_in_notification: ^1.0.0

Android Setup

Add Firebase configuration:
- Download google-services.json from Firebase Console
- Place it in android/app/ directory
Update your android/app/build.gradle:

android {
    compileSdkVersion 34
    
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 34
    }
}

dependencies {
    implementation 'com.google.firebase:firebase-messaging:23.4.0'
    implementation 'com.google.android.exoplayer:exoplayer:2.19.1'
}

Update your android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

<application>
    <!-- Add these services -->
    <service
        android:name="com.binimise.notification_audio_plugin.AlarmService"
        android:enabled="true"
        android:exported="false" />
    
    <receiver
        android:name="com.binimise.notification_audio_plugin.AudioStopReceiver"
        android:enabled="true"
        android:exported="true">
        <intent-filter>
            <action android:name="com.binimise.notification_audio_plugin.STOP_AUDIO" />
        </intent-filter>
    </receiver>
</application>

Usage

Basic Audio Playback

import 'package:flutter_downloaded_audio_play_in_notification/flutter_downloaded_audio_play_in_notification.dart';

final audioPlugin = NotificationAudioPlugin();

// Play audio from URL
await audioPlugin.playAudioFromUrl(
  'https://example.com/audio/notification.mp3',
  title: 'Notification Title',
  body: 'Notification Body',
);

// Stop audio
await audioPlugin.stopAudio();

Advanced Usage with Notification Service

import 'package:flutter_downloaded_audio_play_in_notification/flutter_downloaded_audio_play_in_notification.dart';
import 'package:firebase_messaging/firebase_messaging.dart';

class NotificationService {
  final NotificationAudioPlugin _audio = NotificationAudioPlugin();
  
  Future<void> handleMessage(RemoteMessage message) async {
    // Play custom audio when notification received
    if (message.data.containsKey('audio_url')) {
      await _audio.playAudioFromUrl(
        message.data['audio_url'],
        title: message.notification?.title ?? 'Notification',
        body: message.notification?.body ?? '',
      );
    }
  }
  
  Future<void> stopAudio() async {
    await _audio.stopAudio();
  }
}

Handling Terminated State

The plugin handles audio playback and stopping even when the app is terminated:

// In your main.dart or notification service
Future<void> initializeNotifications() async {
  // Configure Firebase Messaging
  FirebaseMessaging.onMessageOpenedApp.listen((RemoteMessage message) {
    // App opened from background/terminated state
    if (message.data.containsKey('audio_url')) {
      // Audio will be stopped automatically when notification tapped
    }
  });
  
  // Handle app opened from terminated state
  final initialMessage = await FirebaseMessaging.instance.getInitialMessage();
  if (initialMessage != null) {
    // Audio stopping is handled automatically by the plugin
  }
}

API Reference

NotificationAudioPlugin

Methods

Future<void> playAudioFromUrl(String url, {String? title, String? body})
- Plays audio from the given URL
- Optionally shows a notification with title and body
- Downloads and caches the audio file
Future<void> stopAudio()
- Stops the currently playing audio
- Works from any app state (foreground, background, terminated)
Future<void> stopAlarm()
- Stops alarm-specific audio playback
- More aggressive stopping mechanism
Future<Map<String, dynamic>?> resetSettings()
- Resets plugin settings to default
- Can help stop stubborn audio playback

Example App

Check out the example directory for a complete working example that demonstrates:

Firebase Cloud Messaging integration
Custom audio playback in notifications
Audio stopping from terminated state
Test interface with stop button

Testing the Example

Run the example app:
```
cd example
flutter run
```
Get FCM token: The app will display your device's FCM token
Send test notification: Use the provided curl command or Firebase Console to send a notification with audio:

curl -X POST https://fcm.googleapis.com/fcm/send \
  -H "Authorization: key=YOUR_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "YOUR_FCM_TOKEN",
    "notification": {
      "title": "Test Audio Notification",
      "body": "Tap to stop audio"
    },
    "data": {
      "audio_url": "https://samplelib.com/lib/preview/wav/sample-15s.wav",
      "click_action": "STOP_AUDIO"
    }
  }'

Test terminated state:
- Play audio using the test notification
- Terminate the app (swipe away from recent apps)
- Send another notification
- Tap the notification - audio should stop immediately when app opens

Platform Support

Feature	Android	iOS
Audio Playback	✅	❌
Background Playback	✅	❌
Terminated State	✅	❌
Notification Integration	✅	❌

Note: This plugin currently supports Android only.

Troubleshooting

Audio not stopping from terminated state

Ensure AlarmService is declared in AndroidManifest.xml
Check that AudioStopReceiver is properly registered
Verify Firebase configuration is correct
Make sure notification tap handling is implemented

Audio not playing

Check internet permission in AndroidManifest.xml
Verify audio URL is accessible and in supported format (MP3, WAV, etc.)
Ensure ExoPlayer dependencies are properly configured
Check device volume and notification settings

Build issues

Update Gradle to version 8.1.1 or higher
Ensure compileSdkVersion is 34 or higher
Check that all dependencies are compatible

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.