kd_youtube_background_audio 0.0.4

A robust Flutter package to reliably extract and play YouTube audio in the background. Handles muxed streams, Doze mode, and web CORS proxies.

KD YouTube Background Audio

A robust, production-ready Flutter package designed to reliably extract and play YouTube audio in the background. Built on top of just_audio and youtube_explode_dart, it specifically addresses the challenges of YouTube stream extraction and background playback persistence.

🚀 Key Features

• 🎧 Seamless Background Playback: Full integration with audio_service for lock-screen controls and notification center integration.
• 🛡️ Enhanced Stream Stability: Automatically utilizes muxed streams to bypass YouTube's aggressive blocking of audio-only streams.
• 🌐 Universal Web Support: Includes built-in CORS proxy configuration to ensure reliability on Flutter Web.
• 🔄 Resilient Playback: Intelligent handling of stream drops with automatic recovery and position preservation.
• 📱 Resource Efficiency: Optimized for low memory footprint during background execution.

📦 Installation

Add the dependency to your pubspec.yaml:

flutter pub add kd_youtube_background_audio

🛠️ Platform Setup

Android

Add the following to your AndroidManifest.xml within the <application> tag:

<service android:name="com.ryanheise.audioservice.AudioService"
    android:foregroundServiceType="mediaPlayback"
    android:export="true"
    tools:ignore="Instantiatable">
    <intent-filter>
        <action android:name="android.intent.action.MEDIA_BUTTON" />
    </intent-filter>
</service>

<receiver android:name="com.ryanheise.audioservice.MediaButtonReceiver"
    android:export="true"
    tools:ignore="Instantiatable">
    <intent-filter>
        <action android:name="android.intent.action.MEDIA_BUTTON" />
    </intent-filter>
</receiver>

iOS

Add the audio background mode to your Info.plist:

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

💻 Usage

1. Initialize the Audio Handler

Initialize the service in your main.dart before calling runApp:

import 'package:kd_youtube_background_audio/kd_youtube_background_audio.dart';

void main() async {
  final audioHandler = await AudioService.init(
    builder: () => KdYoutubeAudioHandler(
      // Optional: Set a CORS proxy for Web stability
      corsProxyUrl: kIsWeb ? 'https://your-cors-proxy.com/' : null,
    ),
    config: const AudioServiceConfig(
      androidNotificationChannelId: 'com.your.app.audio',
      androidNotificationChannelName: 'Music Playback',
      androidNotificationOngoing: true,
    ),
  );
  
  runApp(MyApp(audioHandler: audioHandler));
}

2. Play from YouTube

Extract and play audio directly using a YouTube Video ID. Title and artist are now optional and will be auto-fetched if not provided!

// Basic usage (Auto-fetches title, artist, and thumbnail)
await audioHandler.playFromYoutube(videoId: 'dQw4w9WgXcQ');

// Custom metadata usage
await audioHandler.playFromYoutube(
  videoId: 'dQw4w9WgXcQ',
  title: 'Custom Title',
  artist: 'Custom Artist',
  useMuxed: true, 
);

3. Extract Metadata

You can also fetch video metadata directly without playing it:

final metadata = await KdYoutubeExtractor.getMetadata('dQw4w9WgXcQ');

print('Title: ${metadata.title}');
print('Author: ${metadata.author}');
print('Duration: ${metadata.duration}');
print('Thumbnail: ${metadata.thumbnailUrl}');

🤝 Contributing

Contributions are welcome! If you encounter any issues or have feature suggestions, please open an issue or submit a pull request on the GitHub repository.

📄 License

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

👨‍💻 Maintainer

Developed with ❤️ by [KhvichaDev].