docs: update AudioCache explanation, migration guide, replace package READMEs

README.md

@@ -0,0 +1 @@
+packages/audioplayers/README.md

contributing.md

@@ -4,17 +4,50 @@ Thanks for using audioplayers and especially for your interest in contributing t
 
 Please read this document carefully before doing anything else!
 
+## Environment Setup
+
+Audioplayers is set up to run with the most recent `stable` version of Flutter, so make sure your version
+matches that:
+
+```bash
+flutter channel stable
+```
+
+Also, audioplayers uses [Melos](https://github.com/invertase/melos) to manage the project and dependencies.
+
+To install Melos, run the following command from your terminal:
+
+```bash
+flutter pub global activate melos
+```
+
+Next, at the root of your locally cloned repository bootstrap the projects dependencies:
+
+```bash
+melos bootstrap
+```
+
+The bootstrap command locally links all dependencies within the project without having to
+provide manual [`dependency_overrides`](https://dart.dev/tools/pub/pubspec). 
+This allows all plugins, examples and tests to build from the local clone project. 
+You should only need to run this command once.
+
+> You do not need to run `flutter pub get` once bootstrap has been completed.
+
 ## Old Issues/PRs
 
-We have many existing open issues and a few open PRs that were created before this doc was created. We will try to respect their ignorance of this file's existence by doing our best effort to answer/address/fix/merge them as we normally would up to this point (i.e. as time permits). However, if an existing issue or PR is too blatant of an outlier from these rules, we reserve the right of asking, in the issue/PR for the author (or someone) to fix it so that it falls under the new rules (i.e. apply the templates, etc). If we need to do that, we will give two weeks for the issue/PR to be updated to follow the rules, otherwise it will be closed.
+We have many existing open issues and a few open PRs that were created before this doc was created. We will try to respect their ignorance of this file's existence by doing our best effort to answer/address/fix/merge them as we normally would up to this point (i.e. as time permits). 
+However, if an existing issue or PR is too blatant of an outlier from these rules, we reserve the right of asking, in the issue/PR for the author (or someone) to fix it so that it falls under the new rules (i.e. apply the templates, etc). 
+If we need to do that, we will give two weeks for the issue/PR to be updated to follow the rules, otherwise it will be closed.
 
 Of course, anyone is free to open a similar followup at any time, as long as the new one follows the rules.
 
 With that particular comment in mind, consider the following rules to apply to all new issues only.
 
 ## General Rules
 
-This document is divided in sections for each kind of contribution you have, but for any of them, basically for any form of communication between members of the community, you must follow these rules. I am adding them here at the top because they apply to all sections but also because they are the uttermost important thing for us.
+This document is divided in sections for each kind of contribution you have, but for any of them, basically for any form of communication between members of the community, you must follow these rules. 
+I am adding them here at the top because they apply to all sections but also because they are the uttermost important thing for us.
 
 * Read this doc, the readme and everything else required carefully
 * Use clear, correct and acceptable English
@@ -43,7 +76,7 @@ If you still have a question, then you might have a legit question! However issu
 
  * [Our discord channel](https://discord.gg/ny7eThk): This is [Fire Slime Games](https://fireslime.xyz/) discord server, the people that are also behind Flame/audioplayers. We have a channel on the server dedicated for audioplayers questions. There you will be able to find many people, often knowing much more than we do, eager to help you out (as long as you followed all the steps). This is the quicker way to get help!
 
- * The `flame` tag on [Stack Overflow](https://stackoverflow.com/questions/tagged/flame): Since audioplayers is part of the flame project, feel free to use the [flame] tag on Stack Overflow to get people from the community to help. This might be a bit more involved than discord but if you make a properly acceptable Stack Overflow question, people will be much more willing to help you with hard problems. Also, you are leaving some documentation for future generations!
+ * The `flutter-audioplayers` tag on [Stack Overflow](https://stackoverflow.com/questions/tagged/flutter-audioplayers): Feel free to use the [flutter-audioplayers] tag on Stack Overflow to get people from the community to help. This might be a bit more involved than discord but if you make a properly acceptable Stack Overflow question, people will be much more willing to help you with hard problems. Also, you are leaving some documentation for future generations!
 
 ### Bugs / Issue Reports
 
@@ -67,10 +100,10 @@ Once your feature got approved to start developing, feel free to send your PRs!
 
  * Start your PR title with a [conventional commit](https://www.conventionalcommits.org) type (feat:, fix: etc).
  * Your build must pass. Please make sure everything is green!
- * Follow guidelines. For the Dart side, follow [Flame's official style guide](https://github.com/flame-engine/flame/blob/main/STYLEGUIDE.md). We don't have a code analyzer for the native side (yet!), but please follow the code around you to make it properly formatted and linted. There is nothing worse than badly formatted code!
+ * Follow guidelines. For the Dart side, follow [Flame's official style guide](https://github.com/flame-engine/flame/blob/main/doc/development/style_guide.md). We don't have a code analyzer for the native side (yet!), but please follow the code around you to make it properly formatted and linted. There is nothing worse than badly formatted code!
  * Write clean, beautiful and easy to understand code, with comments if necessary and docs if applicable.
  * Update our README/getting started/feature parity table/any other docs accordingly to your change, making it clear which platforms are supported.
  * Try to support all platforms where it makes sense. This is a hard thing to ask, and we understand and we will merge PRs that only work on one platform as well. But if you have the time, please help us with feature parity.
  * Make sure your change is testable on the `example` app. If necessary, add to it. This is **mandatory**. We need to be able to at least manually try your feature. Tests are even better of course (see below).
  * Try to add tests, if possible. We don't strive for 100% coverage, but we have very basic driver tests and unit tests where it makes sense (not all places can be tested for an audio player app).
- * Do not add a new version to the changelog, bump versions or anything like that. We will deal with the release process using `melos` whenever there is something to release.
+ * Do not add a new version to the changelog, bump versions or anything like that. We will deal with the release process using `melos` whenever there is something to release.

feature_parity_table.md

@@ -2,17 +2,7 @@
 
 Not every feature is available on every platform yet. Use this table to keep track of our work and progress, and please help out if you want to. :)
 
-## Note on Linux Support
-
-This is the current status of Desktop for us:
-
-* [DONE] Add platform interface, refactor API so native implementations are cleaner
-* [DONE] Federate plugin and provide structure to add multi-platform support
-* [DONE] Add macOS support through Darwin (existing)
-* [DONE] (thanks @azchohfi) Add Windows support
-* [DONE] Add Linux support
-
-If you would like to assist us on implementing further steps, please reach our on our [Discord](https://discord.gg/pxrBmy4) server so we can coordinate efforts.
+If you would like to assist us implement a missing feature, please browse the [issue tracker](https://github.com/bluefireteam/audioplayers/issues) and reach out to us on our [Discord](https://discord.gg/pxrBmy4) server so we can coordinate efforts.
 
 ## Note on Android Support
 

getting_started.md

@@ -8,8 +8,8 @@ In order to install this package, add the [latest version](pub.dev/packages/audi
 
 For building and running for certain platforms you need pay attention to additional steps:
 
-* [Linux Setup](packages/audioplayers_linux/setup.md) (`audioplayers_linux`).
-* [Windows Setup](packages/audioplayers_windows/setup.md) (`audioplayers_windows`).
+* [Linux Setup](packages/audioplayers_linux/README.md#setup-for-linux) (`audioplayers_linux`).
+* [Windows Setup](packages/audioplayers_windows/README.md#setup-for-windows) (`audioplayers_windows`).
 
 ## AudioPlayer
 
@@ -307,15 +307,17 @@ Or to handle global events:
 
 ### AudioCache
 
-In order to play Local Assets, you must use the `AudioCache` class. AudioCache is not available for Flutter Web.
-
-Flutter does not provide an easy way to play audio on your assets, but this class helps a lot. It actually copies the asset to a temporary folder in the device, where it is then played as a Local File.
-
+Flutter does not provide an easy way to play audio on your local assets, but that's where the `AudioCache` class comes into play. 
+It actually copies the asset to a temporary folder in the device, where it is then played as a Local File.
 It works as a cache because it keeps track of the copied files so that you can replay them without delay.
 
+If desired, you can change the `AudioCache` per player via the `AudioPlayer().audioCache` property or for all players via `AudioCache.instance`.
+
 ### playerId
 
-By default, each time you initialize a new instance of AudioPlayer, a unique playerId is generated and assigned to it using the [uuid package](https://pub.dev/packages/uuid). This is used internally to route messages between multiple players, and it allows you to control multiple audios at the same time. If you want to specify the playerId, you can do so when creating the playing:
+By default, each time you initialize a new instance of AudioPlayer, a unique playerId is generated and assigned to it using the [uuid package](https://pub.dev/packages/uuid). 
+This is used internally to route messages between multiple players, and it allows you to control multiple audios at the same time. 
+If you want to specify the playerId, you can do so when creating the playing:
 
 ```dart
   final player = AudioPlayer(playerId: 'my_unique_playerId');

migration_guide.md

@@ -1,5 +1,11 @@
 # Migration Guide
 
+## Migrate from v1 to higher versions
+
+We recommend following the migration instructions for the breaking changes in the [changelog](CHANGELOG.md).
+
+## Migrate from v0 to v1
+
 Despite several major infrastructural changes in v1.0.0, it should be very easy to migrate for end users, as things overall just got simpler.
 
 This document contains the list of major changes to be aware of.
@@ -11,13 +17,13 @@ First step is to add the latest version (see [pub.dev](https://pub.dev/packages/
     audioplayers: ^2.0.0
 ```
 
-## Federation, simplified platform interface
+### Federation, simplified platform interface
 
 This change is here as an introduction but should require no change whatsoever on users side. But we split the package using the official [Federation](https://docs.flutter.dev/development/packages-and-plugins/developing-packages) process from Flutter. You still only need to import the final package `audioplayers` into your project, but know that that will fetch the relevant implementations for each platform you support as `audioplayers_x` packages.
 
 In order to support this, we also created a vastly simplified `audioplayers_platform_interface` that is allowing us to add support for other platforms (eg desktop) much easier but removing any shortcuts or duplicated methods and leaving everything that can, to be implemented on the Dart side. Platforms have to deal with only the most basic building blocks they have to implement, and nothing else.
 
-## AudioCache is dead, long live Sources
+### AudioCache is dead, long live Sources
 
 One of the main changes was my desire to "kill" the AudioCache API due to the vast confusion that it caused with users (despite our best efforts documenting everything).
 
@@ -32,7 +38,7 @@ What is a Source? It's a sealed class that can be one of:
 
 If you use **AssetSource**, the AudioPlayer will use its instance of AudioCache (which defaults to the global cache if unchanged) automatically. This unifies all playing APIs under AudioPlayer and entirely removes the AudioCache detail for most users.
 
-## Simplified APIs, one method per task
+### Simplified APIs, one method per task
 
 We removed multiple overrides and used the concept of Sources to unify methods under AP. Now we have base, separated methods for:
 
@@ -52,13 +58,13 @@ We still have (other than the handy `setSourceX` methods) one shortcut left: the
 
 All in one go. We might decide whether to keep this shortcut or what parameters exactly to have on a next refactor. But for now we are very happy that we no longer have `play` and `playBytes` being essentially clones with different sources on `AudioPlayer` and then `AudioCache` having its own versions + looping versions (it was chaotic before).
 
-## Enum name consolidation, some files were shuffled around
+### Enum name consolidation, some files were shuffled around
 
 As per Dart's new best practices, all enums on the Dart side now have lowercase constants.
 
 Also, some files might have been shuffled around (even between packages), but nothing that your IDE won't be able to quickly sort out.
 
-## AudioContext
+### AudioContext
 
 For some people, this will be irrelevant. For others, this might be the biggest change. Basically we collected all the random flags and parameters that were related to audio context/session configuration spread through the codebase on different methods, at different stages, into a single, unified configuration object called AudioContext, that can be set globally or per player (only for Android).