Flutter Audio Player Manager #

A comprehensive Flutter audio player manager package that provides a unified interface for multiple audio player implementations with advanced features like playlist management and extensible caching.

✨ Features #

• 🎵 Multiple Audio Engine Support: Choose between audioplayers and just_audio backends
• 📱 Platform Support: Works on Android, iOS, Web, Windows, macOS, and Linux
• 💾 Smart Caching: Integrated with flutter_app_cache_manager for advanced audio caching
• 📋 Playlist Management: Create, modify, and manage playlists
• 🔀 Advanced Controls: Shuffle, repeat modes, and gapless playback
• 📊 Metadata Support: Extract and display audio metadata and artwork
• 🎛️ Audio Effects: Volume control and playback speed adjustment
• 🔧 Highly Configurable: Extensive configuration options for all features
• 🧪 Well Tested: Comprehensive test coverage
• 📚 Clean Architecture: Follows SOLID principles with dependency injection

📦 Installation #

Add this package to your pubspec.yaml:

dependencies:
  audio_player_manager: ^x.y.z
  audioplayers: ^x.y.z  # Required for AudioPlayers backend
  flutter_app_cache_manager: ^x.y.z  # Optional for advanced caching

🚀 Quick Start #

Basic Audio Playback #

import 'package:audio_player_manager/audio_player_manager.dart';

// Create an audio player with default services
final audioPlayer = await AudioPlayerFactory.createWithDefaultServices(
  config: AudioPlayerConfig.defaultConfig(),
);

// Create an audio track
final track = AudioTrack(
  id: 'track_1',
  title: 'My Song',
  artist: 'Artist Name',
  url: 'https://example.com/audio.mp3',
  sourceType: AudioSourceType.network,
);

// Load and play
await audioPlayer.loadTrack(track);
await audioPlayer.play();

// Listen to playback state
audioPlayer.playbackStateStream.listen((state) {
  print('State: ${state.state}');
  print('Position: ${state.position}');
  print('Duration: ${state.duration}');
});

Advanced Caching with flutter_app_cache_manager #

import 'package:audio_player_manager/audio_player_manager.dart';
import 'package:flutter_app_cache_manager/flutter_app_cache_manager.dart';

// Create a cache manager with custom configuration
final CacheConfigurationModel audioConfig = CacheConfigurationModel.audioConfig();
final BaseCacheManagerInterface cacheManager =
    await FlutterCacheManagerImpl.create(audioConfig);

// Create audio player with cache manager
final audioPlayer = await AudioPlayerFactory.createWithDefaultServices(
  config: AudioPlayerConfig(
    enableCaching: true,
    maxCacheSize: 500 * 1024 * 1024, // 500 MB
  ),
  cacheManager: cacheManager,
);

// The audio player will now automatically cache network audio files
final track = AudioTrack(
  id: 'track_1',
  title: 'My Song',
  artist: 'Artist Name',
  url: 'https://example.com/audio.mp3',
  sourceType: AudioSourceType.network,
);

// This will cache the audio automatically if enableCaching is true
await audioPlayer.loadTrack(track);
await audioPlayer.play();

// Manually cache a track for offline playback
await audioPlayer.cacheTrack(track);

// Check cache status
final cacheState = audioPlayer.currentCacheState;
print('Cache state: $cacheState');

// Clear all cached audio
await audioPlayer.clearCache();

Playlist Management #

// Create a playlist
final playlist = Playlist(
  id: 'my_playlist',
  name: 'My Favorite Songs',
  description: 'A collection of my favorite tracks',
  tracks: [
    AudioTrack(
      id: 'track_1',
      title: 'Song 1',
      artist: 'Artist 1',
      url: 'https://example.com/song1.mp3',
      sourceType: AudioSourceType.network,
    ),
    AudioTrack(
      id: 'track_2',
      title: 'Song 2',
      artist: 'Artist 2',
      url: 'https://example.com/song2.mp3',
      sourceType: AudioSourceType.network,
    ),
  ],
  createdAt: DateTime.now(),
  updatedAt: DateTime.now(),
);

// Load and play playlist
await audioPlayer.loadPlaylist(playlist);
await audioPlayer.play();

// Navigate through playlist
await audioPlayer.skipToNext();
await audioPlayer.skipToPrevious();
await audioPlayer.skipToIndex(2);

Custom Services Setup #

// Create services manually for more control
final CacheConfigurationModel audioConfig = CacheConfigurationModel.audioConfig();
final BaseCacheManagerInterface cacheManager =
    await FlutterCacheManagerImpl.create(audioConfig);
final playlistService = await DefaultPlaylistService.create();

final audioPlayer = await AudioPlayerFactory.createPlayer(
  type: AudioPlayerType.audioPlayers,
  config: AudioPlayerConfig.defaultConfig(),
  playlistService: playlistService,
  cacheManager: cacheManager,
);

Advanced Playback Features #

// Set playback speed
await audioPlayer.setSpeed(1.5); // 1.5x speed

// Set volume
await audioPlayer.setVolume(0.8);

// Set repeat mode
await audioPlayer.setRepeatMode(RepeatMode.all);

// Enable shuffle
await audioPlayer.setShuffleMode(ShuffleMode.songs);

// Seek to position
await audioPlayer.seek(Duration(minutes: 2, seconds: 30));

Cache Event Monitoring #

// Listen to cache state changes
audioPlayer.cacheStateStream.listen((cacheState) {
  switch (cacheState) {
    case AudioCacheState.notCached:
      print('Audio not cached');
      break;
    case AudioCacheState.caching:
      print('Caching audio...');
      break;
    case AudioCacheState.cached:
      print('Audio cached successfully');
      break;
    case AudioCacheState.failed:
      print('Caching failed');
      break;
  }
});

🏗️ Architecture #

This package follows Clean Architecture principles:

lib/
├── src/
│   ├── core/                 # Core interfaces and enums
│   ├── models/               # Data models
│   ├── implementations/      # Player implementations
│   ├── services/            # Service interfaces and implementations
│   └── utils/               # Utilities and factories

🔧 Configuration #

final config = AudioPlayerConfig(
  enableBackgroundPlayback: true,
  enableGaplessPlayback: true,
  enableCaching: true,
  crossfadeDuration: Duration(seconds: 2),
  bufferDuration: Duration(seconds: 20),
  maxCacheSize: 1024 * 1024 * 1024, // 1 GB
  enableAudioEffects: false,
);

🤝 Extending the Package #

Custom Cache Implementation #

The package integrates seamlessly with flutter_app_cache_manager which provides advanced caching features:

// flutter_app_cache_manager is already integrated
// Just pass it to the audio player factory
final CacheConfigurationModel audioConfig = CacheConfigurationModel.audioConfig();
final BaseCacheManagerInterface cacheManager =
    await FlutterCacheManagerImpl.create(audioConfig);
final audioPlayer = await AudioPlayerFactory.createWithDefaultServices(
  config: config,
  cacheManager: cacheManager,
);

Custom Metadata Service #

class MyMetadataService implements MetadataService {
  @override
  Future<AudioMetadata?> extractMetadata(String url) async {
    // Use metadata_god, flutter_audio_metadata, or custom logic
    // Return AudioMetadata object
  }

  // ... implement other methods
}

📚 API Reference #

Core Classes #

• AudioPlayerInterface: Main interface for audio playback
• AudioPlayerFactory: Factory for creating player instances
• AudioTrack: Represents an audio track
• Playlist: Represents a collection of tracks
• PlaybackState: Current state of the player

Services #

• PlaylistService: Interface for playlist management
• Caching is handled by flutter_app_cache_manager integration

Models #

• AudioPlayerConfig: Player configuration
• PlaybackState: Current playback state

Cache Integration #

• BaseCacheManagerInterface: From flutter_app_cache_manager package
• AudioCacheState: Enum for cache states (notCached, caching, cached, failed)

🧪 Testing #

// Mock services for testing
final mockCacheManager = MockAudioCacheManager();
final mockPlaylistService = MockPlaylistService();

final player = await AudioPlayerFactory.createPlayer(
  type: AudioPlayerType.audioPlayers,
  config: AudioPlayerConfig.defaultConfig(),
  playlistService: mockPlaylistService,
  cacheManager: mockCacheManager,
);

🐛 Troubleshooting #

Common Issues #

1. Audio doesn't play: Check that the URL is accessible and the audio format is supported
2. Background playback not working: Ensure proper platform setup for background audio
3. Caching not working: Verify storage permissions and available space, ensure enableCaching is true

Platform Setup #

Android

Add to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

iOS

Add to ios/Runner/Info.plist:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

🤝 Contributing #

Contributions are welcome! Please read our Contributing Guide for details.

📄 License #

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

🙏 Acknowledgments #

• just_audio - Excellent audio player plugin
• audioplayers - Versatile audio player plugin
• flutter_shared_utilities - Shared utilities for Flutter
• flutter_app_cache_manager - Advanced caching capabilities

📞 Support #

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions