audio_player_manager 1.0.0
audio_player_manager: ^1.0.0 copied to clipboard
A comprehensive Flutter audio player manager package that provides a simple and easy to use API for playing audio files with support for just_audio and audioplayers packages.
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
andjust_audio
backends - π± Platform Support: Works on Android, iOS, Web, Windows, macOS, and Linux
- πΎ Smart Caching: Extensible caching interface for offline playback
- π 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: ^1.0.0
audioplayers: ^6.0.0 # Required for AudioPlayers backend
π Quick Start #
Basic Audio Playbook #
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.loadAudio(track);
await audioPlayer.play();
// Listen to playback state
audioPlayer.playbackStateStream.listen((state) {
print('State: ${state.state}');
print('Position: ${state.position}');
print('Duration: ${state.duration}');
});
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 cacheService = await DefaultCacheService.create();
final metadataService = await DefaultMetadataService.create();
final playlistService = await DefaultPlaylistService.create();
final audioPlayer = await AudioPlayerFactory.createPlayer(
type: AudioPlayerType.audioPlayers,
config: AudioPlayerConfig.defaultConfig(),
cacheService: cacheService,
metadataService: metadataService,
playlistService: playlistService,
);
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.setShuffle(true);
// Seek to position
await audioPlayer.seekTo(Duration(minutes: 2, seconds: 30));
Caching for Offline Playback #
// Cache audio for offline playback
await cacheService.cacheAudio('https://example.com/audio.mp3');
// Check cache status
final isOfflineAvailable = cacheService.isCached('https://example.com/audio.mp3');
// Get cached file path
final cachedPath = cacheService.getCachedPath('https://example.com/audio.mp3');
// Clear cache
await cacheService.clearCache();
Metadata Extraction #
final metadataService = await DefaultMetadataService.create();
// Extract metadata from URL
final metadata = await metadataService.extractMetadata('https://example.com/audio.mp3');
print('Title: ${metadata?.title}');
print('Artist: ${metadata?.artist}');
print('Duration: ${metadata?.duration}');
ποΈ 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,
crossfadeDuration: Duration(seconds: 2),
bufferDuration: Duration(seconds: 20),
enableAudioEffects: false,
);
π€ Extending the Package #
Custom Cache Implementation #
class MyCustomCacheService implements CacheService {
// Implement your custom caching logic
// Could use Hive, SQLite, or cloud storage
@override
Future<void> initialize() async {
// Initialize your storage
}
@override
Future<void> cacheAudio(String url, {String? trackId}) async {
// Your caching implementation
}
// ... implement other methods
}
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 playbackAudioPlayerFactory
: Factory for creating player instancesAudioTrack
: Represents an audio trackPlaylist
: Represents a collection of tracksPlaybackState
: Current state of the player
Services #
CacheService
: Interface for audio cachingMetadataService
: Interface for metadata extractionPlaylistService
: Interface for playlist management
Models #
AudioMetadata
: Audio file metadataAudioPlayerConfig
: Player configurationPlaybackState
: Current playback state
π§ͺ Testing #
// Mock services for testing
final mockCacheService = MockCacheService();
final mockMetadataService = MockMetadataService();
final mockPlaylistService = MockPlaylistService();
final player = await AudioPlayerFactory.createPlayer(
type: AudioPlayerType.audioPlayers,
config: AudioPlayerConfig.defaultConfig(),
cacheService: mockCacheService,
metadataService: mockMetadataService,
playlistService: mockPlaylistService,
);
π Troubleshooting #
Common Issues #
- Audio doesn't play: Check that the URL is accessible and the audio format is supported
- Background playback not working: Ensure proper platform setup for background audio
- Caching not working: Verify storage permissions and available space
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" />
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
π Support #
- π Issues: GitHub Issues
- π¬ Discussions: GitHub Discussions