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 #

1. Add Firebase configuration:

   • Download google-services.json from Firebase Console
   • Place it in android/app/ directory

2. 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'
}

3. 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 #

1. Run the example app:

   cd example
   flutter run
   

2. Get FCM token: The app will display your device's FCM token

3. 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"
    }
  }'

4. 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 #

Note: This plugin currently supports Android only.

Troubleshooting #

Audio not stopping from terminated state #

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

Audio not playing #

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

Build issues #

1. Update Gradle to version 8.1.1 or higher
2. Ensure compileSdkVersion is 34 or higher
3. 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.