just_audio

The player's state is composed of two orthogonal states: playing and processingState.

• playing: Typically maps to the app's play/pause button. It only changes in response to direct method calls (with some exceptions like phone call interruptions or background media notifications).
• processingState: Reflects the state of the underlying audio decoder. It changes in response to method calls AND asynchronous events in the audio pipeline (e.g., buffering, loading, or reaching the end of a stream).

Key behaviors to note:

• Even if playing == true, no sound is audible unless processingState == ready (buffers are filled).
• During network buffering, playing remains true, but processingState becomes buffering.
• When a track ends, playing remains true, but no sound is audible until a seek occurs. You can listen for processingState == completed to programmatically pause or rewind.

To react to both states simultaneously in your UI, listen to the playerStateStream, which emits events containing the latest values for both playing and processingState.

To use just_audio, create an AudioPlayer instance and load a source using setUrl. Supported schemes include https:, file:, and asset:. You can then control playback using play(), pause(), stop(), seek(), setSpeed(), and setVolume().

import 'package:just_audio/just_audio.dart';

final player = AudioPlayer();                   // Create a player
final duration = await player.setUrl(           // Load a URL
    'https://foo.com/bar.mp3');                 // Schemes: (https: | file: | asset: )
player.play();                                  // Play without waiting for completion
await player.play();                            // Play while waiting for completion
await player.pause();                           // Pause but remain ready to play
await player.seek(Duration(seconds: 10));       // Jump to the 10 second position
await player.setSpeed(2.0);                     // Twice as fast
await player.setVolume(0.5);                    // Half as loud
await player.stop();                            // Stop and free resources

To enable background playback on Android, you must modify your AndroidManifest.xml to include specific permissions, update your main activity, and register the required service and receiver.

Permissions:

• android.permission.WAKE_LOCK
• android.permission.FOREGROUND_SERVICE
• android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK (Required if targeting SDK 34+)

Activity: Change the android:name attribute of your existing <activity> element to com.ryanheise.audioservice.AudioServiceActivity. If your app requires a FragmentActivity, use com.ryanheise.audioservice.AudioServiceFragmentActivity instead.

Service and Receiver: You must add the com.ryanheise.audioservice.AudioService and com.ryanheise.audioservice.MediaButtonReceiver elements within the <application> tag.

Note: For Android 12+, you must set android:exported="true" on components with intent filters. Use tools:ignore="Instantiatable" to suppress lint warnings if necessary.

<manifest xmlns:tools="http://schemas.android.com/tools" ...>
  <!-- ADD THESE TWO PERMISSIONS -->
  <uses-permission android:name="android.permission.WAKE_LOCK"/>
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
  <!-- ALSO ADD THIS PERMISSION IF TARGETING SDK 34 -->
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK"/>
  
  <application ...>
    
    ...
    
    <!-- EDIT THE android:name ATTRIBUTE IN YOUR EXISTING "ACTIVITY" ELEMENT -->
    <activity android:name="com.ryanheise.audioservice.AudioServiceActivity" ...>
      ...
    </activity>
    
    <!-- ADD THIS "SERVICE" element -->
    <service android:name="com.ryanheise.audioservice.AudioService"
        android:foregroundServiceType="mediaPlayback"
        android:exported="true" tools:ignore="Instantiatable">
      <intent-filter>
        <action android:name="android.media.browse.MediaBrowserService" />
      </intent-filter>
    </service>

    <!-- ADD THIS "RECEIVER" element -->
    <receiver android:name="com.ryanheise.audioservice.MediaButtonReceiver"
        android:exported="true" tools:ignore="Instantiatable">
      <intent-filter>
        <action android:name="android.intent.action.MEDIA_BUTTON" />
      </intent-filter>
    </receiver> 
  </application>
</manifest>

To add background playback and remote control support (notifications, lock screen, headset buttons, etc.), add just_audio_background to your pubspec.yaml.

You must initialize the package in your app's main method using JustAudioBackground.init(). This method accepts configuration for Android notification channels.

Note: This package is designed for the simple use case of a single AudioPlayer instance. For complex requirements or multiple players, use the audio_service package directly.

dependencies:
  just_audio: any # substitute version number
  just_audio_background: any # substitute version number

Future<void> main() async {
  await JustAudioBackground.init(
    androidNotificationChannelId: 'com.ryanheise.bg_demo.channel.audio',
    androidNotificationChannelName: 'Audio playback',
    androidNotificationOngoing: true,
  );
  runApp(MyApp());
}

To access audio files on the Internet, add the INTERNET permission to your AndroidManifest.xml.

If you need to connect to non-HTTPS (HTTP) URLs, or if you use features like headers, caching, or stream audio sources (which rely on a localhost proxy), you must enable cleartext traffic. You can do this globally by adding android:usesCleartextTraffic="true" to the application element, or more securely by defining a network_security_config.xml that only permits cleartext for 127.0.0.1.

<!-- Permission for Internet access -->
<uses-permission android:name="android.permission.INTERNET"/>

<!-- Global cleartext access (less secure) -->
<application ... android:usesCleartextTraffic="true">

<!-- Secure approach: network_security_config.xml -->
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
	<domain-config cleartextTrafficPermitted="true">
		<domain includeSubdomains="false">127.0.0.1</domain>
	</domain-config>
</network-security-config>

<!-- Reference config in AndroidManifest.xml -->
<application ... android:networkSecurityConfig="@xml/network_security_config">