audioplayers

The audioplayers example application demonstrates the core features of the plugin through several functional tabs:

• Src (Sources): Demonstrates how to play audio from different origins:
  • Url: Remote audio from the internet.
  • Asset: Bundled app assets.
  • Device File: Local files from a specified device path.
  • Byte Array: Audio data from a byte array.
• Ctrl (Controls): Manages playback properties like volume, balance, and rate.
• Stream: Monitors and displays real-time stream updates and properties.
• Ctx (Context): Customizes the audio context specifically for mobile devices.
• Log: Provides a view of system logs.

The example also includes a PlayerWidget, which serves as a pre-built, simple audio player interface for quick integration.

An AudioPlayer instance acts like a single playback device (e.g., a boombox) that can play one audio source at a time. You can instantiate multiple AudioPlayer objects to play multiple audios simultaneously or to manage different audio sources independently.

final player = AudioPlayer();

To add support for a new platform, you must implement the AudioplayersPlatformInterface and the GlobalAudioplayersPlatformInterface.

1. Extend AudioplayersPlatformInterface with your platform-specific logic.
2. Register your implementation by assigning it to the instance property of both interfaces during plugin registration.

Note: This package is typically a dependency of the main audioplayers plugin and does not need to be added manually to your pubspec.yaml unless you are building a platform implementation.

The audioplayers plugin sets minSdk to 19, but official support and testing are only guaranteed for Android SDK >= 23.

Key platform-specific behaviors for Android:

• Byte Arrays: Supported natively on SDK >= 23.
• Playback Rate: Supported on SDK >= 23.
• Low Latency Mode (LLM): Supported on SDK >= 21, except when using the audioplayers_android_exo implementation.
• Advanced Controls: Features like duck audio, respect silence, stay awake, and playing route are supported on Android except when in Low Latency Mode (LLM).

The following functionalities are not provided by the audioplayers package:

• Audio Recording: Use a package like audio_recorder for recording from the microphone.
• Playlists: You must implement playlist logic yourself (e.g., playing multiple audios in sequence).
• Music Metadata: The library does not extract metadata (author, track, etc.) from files like MP3s.
• UI/Interfaces: The library is for audio playback logic; use Flutter to build your own user interfaces.

Since Flutter does not natively support playing audio directly from assets, the AudioCache class handles this by copying assets to a temporary folder on the device to be played as local files. It maintains a cache of these files to allow for immediate replay without the delay of re-copying.

By default, AudioPlayer uses a shared global instance of AudioCache with a prefix of "/assets" (following Flutter conventions).

final player = AudioPlayer();
await player.play(AssetSource('audio/my-audio.wav'));

The AudioCache API has been deprecated for general playback. Instead, use the Source sealed class to define where audio is coming from. The AudioPlayer now accepts these Source objects directly via setSource().

Available Source types:

• UrlSource: For remote audio from an internet URL.
• DeviceFileSource: For files located on the user's device.
• AssetSource: For audio files bundled within your app's assets directory. Using AssetSource automatically handles caching via AudioCache internally.
• BytesSource: For passing raw audio bytes directly (platform support varies).

To play audio in a Flutter application, import the audioplayers package, instantiate an AudioPlayer, and use the play method with a UrlSource (or other source types).

import 'package:audioplayers/audioplayers.dart';
// ...
final player = AudioPlayer();
await player.play(UrlSource('https://example.com/my-audio.wav'));

You can customize how assets are resolved by changing the AudioCache prefix. You can apply changes globally for all players or locally to a specific player instance.

Global configuration: Set AudioCache.instance to a new AudioCache with a custom prefix (e.g., an empty string to remove the default /assets prefix).

Per-player configuration: Assign a new AudioCache instance to the player.audioCache property. This is useful when loading assets from different packages.