# bluefireteam/audioplayers: six platforms, one Dart API, and a table of what is missing

> audioplayers is a Flutter plugin for playing several audio files at once on Android, iOS, web, Linux, Windows and macOS, and the project is unusually honest about the cost of that breadth by publishing a feature parity table that lists where support stops. It is maintained by volunteers, shipped through pub.dev with prereleases, and its documentation describes only the newest version.

**bluefireteam/audioplayers** — A Flutter package to play multiple audio files simultaneously (Android/iOS/web/Linux/Windows/macOS)

- Repository: https://github.com/bluefireteam/audioplayers
- Website: https://pub.dartlang.org/packages/audioplayers
- Stars: 2,143 · Forks: 895
- Language: Dart
- License: MIT
- Published: 2026-09-30 · Updated: 2026-09-30 · Language: en
- Canonical page: https://hysenlabs.com/projects/bluefireteam-audioplayers

## The six platform claim, and the table that qualifies it

The description is a single sentence and it is a strong one: a Flutter plugin to play multiple audio files simultaneously, working for Android, iOS, Linux, macOS, Windows and web. One API, six targets, and the reason to want it is the simultaneous part, since the ordinary single player case is well served and the interesting case is a game or an application mixing music with effects. A few lines later the README qualifies the claim, and the qualification is the most useful thing in the document. It says not all features are available on all platforms, and points to a feature parity table held in a separate file that relates which features can be used on each target. That file is not reproduced anywhere in the README, so an adopter has to go and open it, and its existence changes how the headline sentence should be read. Six platforms is the reach; the table is the depth, and the depth is not uniform. The project treats the table as a live artefact rather than a caveat, since it invites feature requests against it, asks contributors to update it when they submit a pull request, and links to it from the help process as the place to check whether a missing feature is already known. That is better practice than most plugins manage, and it is also an admission that a federated plugin has a long tail of per platform differences that no amount of Dart can hide.

## Dart over native code, in a Melos monorepo with a four tab example

The top-level file list explains how the cross platform claim is implemented. There is a clang format configuration and a swift format configuration, so the repository contains C and Swift code alongside Dart, which is what a plugin with per platform native implementations looks like rather than a pure Dart wrapper. There is a packages directory, and the example application lives inside it at a path under the audioplayers package, so the library, its example and anything else in the family are managed as one monorepo. The badge in the README says the project is maintained with Melos, which is the Dart monorepo tool, and that is what a repository with a packages directory and a root pubspec is set up for. Everything else at the top level is documentation, and the documentation is unusually complete as a set of separate files: a getting started guide, a troubleshooting guide, a migration guide, a contributing guide, the parity table and a changelog. The README even carries a code comment noting that a changelog exists both at the root and inside the package, so the one you are reading depends on where you are. The example application is the fastest way to understand the API surface, because its four tabs are named after what the plugin does rather than after screens: sources, controls, streams and audio context. That naming tells you the model is player plus source, with a control surface, a streaming path, and a notion of the platform audio context underneath all three.

## Three lines to play a file, and what they leave to the tutorial

The getting started snippet is the shortest honest introduction the project could give, and it is four lines of code:

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

The shape tells you the abstraction. A player is constructed, and playback takes a source object rather than a string, and the source type in the example is a URL source, so the same call site can carry a different source type for a different origin without the calling code changing. That is the whole reason to use a plugin rather than a platform channel, and it is also the reason the parity table exists, since every source type has to be implemented on every target. What the snippet does not tell you is nearly everything that matters in production. The README itself redirects to the getting started guide for high level information, then to the generated API reference and to the dartdocs, and says the code is well documented. It does not mention the package installation line, background playback, audio focus, interruption handling, mixing behaviour, or what happens when a source is a large file rather than a short sample. The controls tab of the example is where that behaviour is demonstrated rather than described, which is a reasonable way to learn an audio library and a poor way to evaluate one, since you cannot read an answer off a screenshot. The audio context tab is the one to look at first on mobile, because that is where the platform's own rules about your app's audio meet your code.

## Documentation that only describes the newest release, and the tags that fix it

One line in the README governs how you should read everything else here. It says the documentation is kept up to date to reflect the content of the current newest release, and that if you want older information and guidance you should check out the tag related to the version you are looking for. That is an honest and unusual position, and it has a direct consequence. There is no versioned documentation site, so a project pinned to an older release has no matching guide unless someone checks out that tag and reads the markdown in the repository, which is a real cost when a build is held at a version for a year. It also means the tutorial you read describes behaviour that may not exist in the version your lock file resolved, and the mismatch is invisible until runtime. The project handles the other side of this properly, with a migration guide and a changelog, and it points at both specifically for people moving across major versions, which is when a breaking change is actually expected. Taken together, the documentation policy is coherent even if inconvenient. The current docs are trustworthy for the current release. The historical record lives in tags. The breaking changes are enumerated. What does not exist is a way to read current documentation for an old version, so if your application is going to sit on a pinned release, pin it deliberately and keep the tag checked out alongside it.

## The support ladder, and the statement that issues can be closed

The help section is a numbered procedure and it is worth reading as a policy rather than as advice. The order is: read the getting started tutorial carefully and re-read it; check the troubleshooting guide, which the project says covers most problems; if you are reporting a missing feature or requesting one, check the feature parity table first to see whether it is already known; ask in the project's Discord; ask on Stack Overflow instead if you prefer, using the flutter audioplayers tag so followers can answer; and only then use the issue creation page, following the step by step, and then following the template. The template instruction is unusually precise, telling people not to include the literal text of the template but to replace each section with what belongs in it, and not to skip the mandatory sections. The last line is the one to weigh. It says any issue created outside that sequence can be flagged or closed by the team. So the project is explicit that it will decline reports that arrive without the preliminary work, which is defensible for a volunteer maintained package and irritating if you have already found the real cause. The mitigation is in the list itself, since step one and step two would have found it in most cases, and the parity table answers the feature question faster than an issue would. If you do file one, the template fields are the minimum the maintainers need, and filling them properly is the difference between a triageable report and a closed one.

## Prereleases on pub.dev, no GitHub releases, and no commercial backing

The publishing model is worth understanding before you depend on it. The repository publishes no GitHub releases at all, so the version history lives on the package registry, and the version badge in the README is configured to include prereleases, which tells you the project ships prerelease versions to that registry alongside stable ones. That is a double edged detail. It means you can pin a specific prerelease when you need a fix that has not reached stable, and it means a resolution strategy that accepts prereleases can land your build on a version nobody is using in production. An explicit version constraint is the safe choice, and the parity table and changelog give you the information to make it deliberately. The licence is MIT, with a LICENSE file at the top level, so there is no obligation attached to using it. The funding and governance picture is stated as plainly as the technical one. The project says the software was made by the community, on spare time, with no commercial affiliation, that it is provided as is, and it points at OpenCollective, GitHub Sponsors and Patreon. Read alongside the support policy above, that describes a package whose maintenance capacity is whatever volunteers choose to give it, which is a completely reasonable thing to build on and a real consideration for a dependency in an application you have to keep working. The last push was on 2026-07-23, so the code is being touched, and the continuity mechanism the project relies on is the contributing guide and the parity table rather than a paid maintainer.

## One federated plugin against six native implementations

The alternative is to skip the plugin and use each platform's own audio facility through your own platform channel code. The difference in approach is not about quality, it is about where the unevenness lands. With the plugin, the unevenness is in the parity table, where you discover that a feature you want exists on two of your six targets and you write a conditional or a fallback. With native code, the unevenness is in your own repository, where six implementations have to be written, tested and kept in step, and where each platform's full audio facility is available including the parts the plugin has not implemented. The first is a much smaller project with a documented ceiling. The second is a much larger one with no ceiling and no external dependency to wait on. The tie breaker is usually how much of the platform's audio behaviour you actually need. If the requirement is a few overlapping clips with volume control, the plugin's covered set is almost certainly sufficient and the parity table will confirm it in a minute. If the requirement involves anything the table marks as missing on a target you ship, the plugin stops being a shortcut at exactly the point where the work is hardest, and the conditional you would write is more code than the platform channel it replaces. The cost of the native route is not the first implementation, it is every one after it, across six platforms, forever.

## Conclusion

audioplayers is the right choice for a Flutter app that needs overlapping audio on several targets without writing six platform integrations, and the wrong choice for an app whose audio must behave identically everywhere, because the parity table is the project's own statement that it does not. Read that table for your specific targets before anything else, since the README's six platform claim and the table's gaps are both true and only one of them is in the README. Then decide how you will pin. The package publishes prereleases to pub.dev, the repository publishes no GitHub releases, and the documentation in the repository describes only the current newest version, so a version constraint plus a checked out tag is the only combination that gives you matching documentation for the code you are compiling. Two smaller checks are worth making. Cross a major version only with the migration guide open, since the changelog and the guide are separate documents and both exist, and expect to file issues through a template, because the project states plainly that reports which skip its process can be closed.

## FAQ

### How do I add audioplayers to a Flutter project?

It is a package published on pub.dev, from the same team that maintains the repository, and the README does not print a dependency line. It points at the getting started guide and the package page instead. Because the documentation in the repository describes only the current newest release, pin the version and check out the matching tag if you need guidance for it.

### Does audioplayers support every feature on every platform?

No. The README says plainly that not all features are available on all platforms and points to a feature parity table in the repository that relates which features work on which target. That file, not the platform list, is what should decide whether the package fits your targets.

### What is the quickest way to see what the API can do?

The example application, which is organised into four tabs named sources, controls, streams and audio context, and which is also published as a live example. For reference detail the project points at the generated API reference on pub.dev and the dartdocs in the source.

### Why was my issue closed?

The project publishes a numbered help process and states that issues created outside it can be flagged or closed. The sequence is the getting started guide, the troubleshooting guide, the feature parity table for anything missing, Discord, Stack Overflow with the package tag, and only then the issue form, completed with every mandatory template section filled in rather than the template text left in place.

### Are there prerelease versions of audioplayers?

The version badge in the README is configured to include prereleases, so prerelease versions are published to the package registry. The repository itself publishes no GitHub releases, so the registry is where the version history lives, and an explicit version constraint is the way to keep a build off an unintended prerelease.

## Sources

- [bluefireteam/audioplayers on GitHub](https://github.com/bluefireteam/audioplayers)
- [Issues](https://github.com/bluefireteam/audioplayers/issues)
- [License: MIT](https://github.com/bluefireteam/audioplayers/blob/main/LICENSE)
- [Project website](https://pub.dartlang.org/packages/audioplayers)
- [README](https://github.com/bluefireteam/audioplayers/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bluefireteam-audioplayers