audiofileplayer 1.1.1

  • Readme
  • Changelog
  • Example
  • Installing
  • 85

audiofileplayer #

A Flutter plugin for audio playback. Supports

  • Reading audio data from Flutter project assets, byte arrays, and remote URLs.
  • Seek to position.
  • Callbacks for loaded audio duration, current position, and playback completion.
  • Looping.
  • Volume.
  • Pause/Resume.
  • Multiple audio players, with memory management.
  • Background audio playback.
  • Setting supported media actions and metadata for the OS's display.
  • Custom media buttons in the Android notification.

Getting Started #

To use this plugin, add audiofileplayer as a dependency in your pubspec.yaml file.

Examples #

Please see the top of audiofileplayer.dart for more information, and see the example app showing the following use cases in action.

One-shot playback #

// Play a sound as a one-shot, releasing its resources when it finishes playing.
Audio.load('assets/foo.wav')..play()..dispose();

Re-use an Audio object #

// Load from assets, store as a variable.
Audio audio = Audio.load('assets/bar.mp3');
...
/// Use the [Audio];
audio.play();
...
audio.pause();
...
audio.resume();

/// You must call dispose() when the [Audio] will no longer be used (for example, in State.dispose()). Note that
/// [dispose] will not stop playback, but will internally release resources once the audio finishes playing.
audio
    ..pause();
    ..dispose();

Use callbacks to get information #

Audio audio = Audio.load('assets/baz.mp4',
    // Called when audio has finished playing.
    onComplete: () => _handleOnComplete(),
    // Called when audio has loaded and knows its duration.
    onDuration: (double durationSeconds) => _handleDuration(durationSeconds),
    // Called repeatedly with updated playback position.
    onPosition: (double positionSeconds) => _handleOnPosition(positionSeconds));

The finer points of dispose()

See the header comment of audiofileplayer.dart for more info on using dispose().

Using background audio #

Setup #

To play background audio, you will need to update a few platform-specific files for your app. (For reference, the example app contains all these changes.)

iOS #

Enable the "audio" background mode capability in one of two ways:

  • Open your app's autogenerated Runner.xcodeproj file in XCode. See this documentation or
  • Edit the Info.plist file to add
<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

Android #

To use the plugin's custom foreground service, add this within the <manifest> tag of your app's AndroidManifest.xml...

<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>

...and this within the <application> tag of your AndroidManifest.xml.

<service android:name="com.google.flutter.plugins.audiofileplayer.AudiofileplayerService">
    <intent-filter>
        <action android:name="android.media.browse.MediaBrowserService" />
    </intent-filter>
    <intent-filter>
        <action android:name="android.intent.action.MEDIA_BUTTON" />
    </intent-filter>
</service>

<receiver android:name="androidx.media.session.MediaButtonReceiver" >
    <intent-filter>
        <action android:name="android.intent.action.MEDIA_BUTTON" />
    </intent-filter>
</receiver>

If you'd like to specify custom buttons in the notification (beyond the 'built-in' buttons, which have icons provided), then add icons for them to the "drawable" resource folder(s). These should be approx 32x32 pts in order to display correctly.

Usage #

For an Audio object to continue playing while the app is minimized, set the playInBackground flag when loading.

Audio backgroundAudio = Audio.load('assets/foo.wav', playInBackground = true);

It is up to you to communicate information to the OS, in order to:

  • display metadata (title/artist/artwork/etc).
  • specify which transport controls are active/supported. This will be reflected in external controllers (bluetooth/watch/auto/etc)
  • inform progress bars for display.
  • for Android, specify buttons within the notification.

Communicating with the OS's media system is covered by these methods on the AudioSystem singleton instance. See audio_system.dart for full documentation. See the example app for a complete example using all of these.

void setPlaybackState(bool isPlaying, double positionSeconds);
void setMetadata(AudioMetadata metadata);
void setSupportedMediaActions(Set<MediaActionType> actions,;
      {double skipIntervalSeconds});
void setAndroidNotificationButtons(List<dynamic> androidMediaButtons,
      {List<int> androidCompactIndices})
void stopBackgroundDisplay();

Additional platform-specific notes. #

iOS audio category #

You can programatically choose from one of three audio categories on iOS. This affects whether audio will play in the background, or when the 'silent' hardware switch is on. See iOS doc.

This plugin supports switching between the 'playback', 'ambient solo', and 'ambient mixed' categories. For audio to play in the background, the category must be set to 'playback' (which is the default). See the IosAudioCategory enum, and the setIosAudioCategory method.

iOS remote audio loading #

If your app attempts to load a remote URL that doesn't use HTTPS, e.g. Audio.loadFromRemoteUrl('http://www.foo.com/bar.mp3) then you will get a security error. To allow loading from non-HTTPS URLs, add the NSAppTransportSecurity entry to your Info.plist file. iOS doc.

Android remote audio loading #

If your app loads remote audio files, you will need this permission in your AndroidManifest.xml.

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

1.1.1 - 28 Dec 2019 #

  • README tweaks.

1.1.0 - 24 Dec 2019 #

  • Proper background audio on Android (using MediaBrowserService).
  • Caller can set supported media actions, metadata, and Android notification buttons.
  • Minor breaking change: 'shouldPlayInBackground' static flag is removed, and a per-Audio 'playInBackground' flag is used on each Audio load.
  • Expanded documentation.

1.0.3 - 2 Dec 2019 #

  • Support older versions of Android.
  • Fix error handling in Dart lib, so failed loads get cleaned up before calling onError().

1.0.2 - 21 Nov 2019 #

  • Fix background audio on iOS, add ability to specify iOS audio category (which defaults to 'playback').

1.0.1 - 21 Nov 2019 #

  • Fix new build issues in podfile, add pubspec.yaml dependency versions

1.0.0 - 7 Nov 2019 #

  • Initial open source release

example/README.md

audiofileplayer_example #

Demonstrates how to use the audiofileplayer plugin.

Getting Started #

This project is a starting point for a Flutter application.

A few resources to get you started if this is your first Flutter project:

For help getting started with Flutter, view our online documentation, which offers tutorials, samples, guidance on mobile development, and a full API reference.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  audiofileplayer: ^1.1.1

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:audiofileplayer/audiofileplayer.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
78
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
80
Overall:
Weighted score of the above. [more]
85
Learn more about scoring.

We analyzed this package on Jan 16, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.0
  • pana: 0.13.4
  • Flutter: 1.12.13+hotfix.5

Health suggestions

Format lib/audiofileplayer.dart.

Run flutter format to format lib/audiofileplayer.dart.

Maintenance suggestions

The package description is too short. (-20 points)

Add more detail to the description field of pubspec.yaml. Use 60 to 180 characters to describe the package, what it does, and its target use case.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.2.0 <3.0.0
flutter 0.0.0
logging ^0.11.3 0.11.4
meta ^1.1.6 1.1.8
uuid ^2.0.4 2.0.4
Transitive dependencies
charcode 1.1.2
collection 1.14.11 1.14.12
convert 2.1.1
crypto 2.1.4
sky_engine 0.0.99
typed_data 1.1.6
vector_math 2.0.8
Dev dependencies
flutter_test