feat!: Update flame_audio to AP 1.0.0 (#1724)

doc/flame_audio/audio.md

@@ -1,6 +1,6 @@
 # Audio
 
-Playing audio is essential for any game, so we made it simple!
+Playing audio is essential for most games, so we made it simple!
 
 First you have to add [flame_audio](https://github.com/flame-engine/flame_audio) to your dependency
 list in your `pubspec.yaml` file:
@@ -12,11 +12,10 @@ dependencies:
 
 The latest version can be found on [pub.dev](https://pub.dev/packages/flame_audio/install).
 
-After installing the `flame_audio` package you can add audio files in the assets section of your
+After installing the `flame_audio` package, you can add audio files in the assets section of your
 `pubspec.yaml` file. Make sure that the audio files exists in the paths that you provide.
 
-The default directory for `FlameAudio` is `assets/audio` (which can be changed) and for `AudioPool`
-the default directory is `assets/audio/sfx`.
+The default directory for `FlameAudio` is `assets/audio` (which can be changed by providing your own instance of `AudioCache`).
 
 For the examples below, your `pubspec.yaml` file needs to contain something like this:
 
@@ -27,9 +26,6 @@ flutter:
     - assets/audio/music.mp3
 ```
 
-(The default directory for `FlameAudio` is `assets/audio` (which can be changed) and for `AudioPool`
-the default directory is `assets/audio/sfx`.)
-
 Then you have the following methods at your disposal:
 
 ```dart
@@ -63,13 +59,29 @@ You can use [the `Bgm` class](bgm.md) (via `FlameAudio.bgm`) to play looping bac
 tracks. The `Bgm` class lets Flame automatically manage the pausing and resuming of background music
 tracks when the game is backgrounded or comes back to the foreground.
 
+You can use [the `AudioPool` class](audio_pool.md) if you want to fire quick sound effects in a very
+efficient manner. `AudioPool` will keep a pool of `AudioPlayer`s preloaded with a given sound, and
+allow you to play them very fast in quick succession. 
+
 Some file formats that work across devices and that we recommend are: MP3, OGG and WAV.
 
 This bridge library (flame_audio) uses [audioplayers](https://github.com/bluefireteam/audioplayers)
 in order to allow for playing multiple sounds simultaneously (crucial in a game). You can check the
 link for a more in-depth explanation.
 
-Finally, you can pre-load your audios. Audios need to be stored in the memory the first time they
+Both on `play` and `loop` you can pass an additional optional double parameter, the `volume`
+(defaults to `1.0`).
+
+Both the `play` and `loop` methods return an instance of an `AudioPlayer` from the
+[audioplayers](https://github.com/bluefireteam/audioplayers) lib, that allows you to stop, pause and
+configure other parameters.
+
+In fact you can always use `AudioPlayer`s directly to gain full control over how your audio is played
+-- the `FlameAudio` class is just a wrapper for common functionality.
+
+## Caching
+
+You can pre-load your assets. Audios need to be stored in the memory the first time they
 are requested; therefore, the first time you play each mp3 you might get a delay. In order to
 pre-load your audios, just use:
 
@@ -81,7 +93,7 @@ You can load all your audios in the beginning in your game's `onLoad` method so
 play smoothly. To load multiple audio files, use the `loadAll` method:
 
 ```dart
-await FlameAudio.audioCache.loadAll(['explosion.mp3', 'music.mp3'])
+await FlameAudio.audioCache.loadAll(['explosion.mp3', 'music.mp3']);
 ```
 
 Finally, you can use the `clear` method to remove a file that has been loaded into the cache:
@@ -93,13 +105,4 @@ FlameAudio.audioCache.clear('explosion.mp3');
 There is also a `clearCache` method, that clears the whole cache.
 
 This might be useful if, for instance, your game has multiple levels and each has a different
-set of sounds and music.
-
-Both load methods return a `Future` for the `File`s loaded.
-
-Both on `play` and `loop` you can pass an additional optional double parameter, the `volume`
-(defaults to `1.0`).
-
-Both the `play` and `loop` methods return an instance of an `AudioPlayer` from the
-[audioplayers](https://github.com/bluefireteam/audioplayers) lib, that allows you to stop, pause and
-configure other parameters.
+set of sounds and music.

doc/flame_audio/audio_pool.md

@@ -0,0 +1,15 @@
+# AudioPool
+
+An AudioPool is a provider of AudioPlayers that are pre-loaded with
+local assets to minimize delays.
+
+A single AudioPool always plays the same sound, usually a quick sound
+effect, like a laser shooting from your ship or a jump sound for your
+platformer.
+
+The advantage of using Audio Pool is that by configuring a minimum
+(starting) size, and a maximum size, the pool will create and preload
+some players, and allow them to be re-used many times.
+
+You can use the helper method `FlameAudio.createPool` to create AudioPool
+instances using the same global `FlameAudio.audioCache`.

doc/flame_audio/bgm.md

@@ -1,22 +1,12 @@
 # Looping Background Music
 
-With the `Bgm` class you can manage looping of background music tracks with regards to application
+With the `Bgm` class, you can manage looping of background music tracks with regards to application
 (or game) lifecycle state changes.
 
 When the application is terminated, or sent to background, `Bgm` will automatically pause
 the currently playing music track. Similarly, when the application is resumed, `Bgm` will resume the
 background music. Manually pausing and resuming your tracks is also supported.
 
-The `Bgm` class is handled by the [flame_audio](https://github.com/flame-engine/flame_audio) library
-so you first have to add that to your dependency list in your `pubspec.yaml` file:
-
-```yaml
-dependencies:
-  flame_audio: <VERSION>
-```
-
-The latest version can be found on [pub.dev](https://pub.dev/packages/flame_audio/install).
-
 For this class to function properly, the observer must be registered by calling the following:
 
 ```dart
@@ -42,32 +32,20 @@ import 'package:flame_audio/flame_audio.dart';
 FlameAudio.bgm.play('adventure-track.mp3');
 ```
 
-**Note:** The `Bgm` class will always use the static instance of `FlameAudio` for storing cached
-music files.
-
 You must have an appropriate folder structure and add the files to the `pubspec.yaml` file, as
 explained in [Flame Audio documentation](audio.md).
 
 
 ## Caching music files
 
-The following functions can be used to preload (and unload) music files into the cache. These
-functions are just aliases for the ones in `FlameAudio` with the same names.
+The `Bgm` class will use the static instance of `FlameAudio` for storing cached
+music files by default.
 
-Again, please refer to the [Flame Audio documentation](audio.md) if you need more info.
-
-```dart
-import 'package:flame_audio/flame_audio.dart';
-
-FlameAudio.bgm.load('adventure-track.mp3');
-FlameAudio.bgm.loadAll([
-  'menu.mp3',
-  'dungeon.mp3',
-]);
-FlameAudio.bgm.clear('adventure-track.mp3');
-FlameAudio.bgm.clearCache();
-```
+So in order to pre-load music, you can use the same recommendations from the
+[Flame Audio documentation](audio.md).
 
+You can optionally create your own `Bgm` instances with different backing `AudioCache`s,
+if you so desire.
 
 ## Methods
 
@@ -81,11 +59,11 @@ You can pass an additional optional `double` parameter which is the `volume` (de
 Examples:
 
 ```dart
-FlameAudio.bgm.play('bgm/boss-fight/level-382.mp3');
+FlameAudio.bgm.play('music/boss-fight/level-382.mp3');
 ```
 
 ```dart
-FlameAudio.bgm.play('bgm/world-map.mp3', volume: .25);
+FlameAudio.bgm.play('music/world-map.mp3', volume: .25);
 ```
 
 

doc/flame_audio/flame_audio.md

@@ -6,4 +6,5 @@
 
     General audio    <audio.md>
     Background music <bgm.md>
+    AudioPool        <audio_pool.md>
 ```

examples/lib/main.dart

@@ -1,5 +1,6 @@
 import 'package:dashbook/dashbook.dart';
 import 'package:examples/stories/animations/animations.dart';
+import 'package:examples/stories/bridge_libraries/audio/audio.dart';
 import 'package:examples/stories/bridge_libraries/forge2d/flame_forge2d.dart';
 import 'package:examples/stories/camera_and_viewport/camera_and_viewport.dart';
 import 'package:examples/stories/collision_detection/collision_detection.dart';
@@ -27,6 +28,7 @@ void main() {
   addGameStories(dashbook);
 
   // Feature examples
+  addAudioStories(dashbook);
   addAnimationStories(dashbook);
   addCameraAndViewportStories(dashbook);
   addCollisionDetectionStories(dashbook);

examples/lib/stories/bridge_libraries/audio/audio.dart

@@ -0,0 +1,13 @@
+import 'package:dashbook/dashbook.dart';
+import 'package:examples/commons/commons.dart';
+import 'package:examples/stories/bridge_libraries/audio/basic_audio_example.dart';
+import 'package:flame/game.dart';
+
+void addAudioStories(Dashbook dashbook) {
+  dashbook.storiesOf('Audio').add(
+        'Basic Audio',
+        (_) => GameWidget(game: BasicAudioExample()),
+        codeLink: baseLink('audio/basic_audio_example.dart'),
+        info: BasicAudioExample.description,
+      );
+}

examples/lib/stories/bridge_libraries/audio/basic_audio_example.dart

@@ -0,0 +1,84 @@
+import 'package:flame/components.dart';
+import 'package:flame/extensions.dart';
+import 'package:flame/game.dart';
+import 'package:flame/input.dart';
+import 'package:flame/palette.dart';
+import 'package:flame_audio/audio_pool.dart';
+import 'package:flame_audio/flame_audio.dart';
+import 'package:flutter/painting.dart';
+
+class BasicAudioExample extends FlameGame with TapDetector {
+  static const String description = '''
+    This example showcases the most basic Flame Audio functionalities.
+
+    1. Use the static FlameAudio class to easily fire a sfx using the default
+    configs for the button tap.
+    2. Uses a custom AudioPool for extremely efficient audio loading and pooling
+    for tapping elsewhere.
+    3. Uses the Bgm utility for background music.
+  ''';
+
+  static Paint black = BasicPalette.black.paint();
+  static Paint gray = const PaletteEntry(Color(0xFFCCCCCC)).paint();
+  static TextPaint text = TextPaint(
+    style: TextStyle(color: BasicPalette.white.color),
+  );
+
+  late AudioPool pool;
+
+  @override
+  Future<void> onLoad() async {
+    pool = await FlameAudio.createPool(
+      'sfx/fire_2.mp3',
+      minPlayers: 3,
+      maxPlayers: 4,
+    );
+    startBgmMusic();
+  }
+
+  Rect get button => Rect.fromLTWH(20, size.y - 300, size.x - 40, 200);
+
+  void startBgmMusic() {
+    FlameAudio.bgm.initialize();
+    FlameAudio.bgm.play('music/bg_music.ogg');
+  }
+
+  void fireOne() {
+    FlameAudio.play('sfx/fire_1.mp3');
+  }
+
+  void fireTwo() {
+    pool.start();
+  }
+
+  @override
+  void render(Canvas canvas) {
+    super.render(canvas);
+    canvas.drawRect(size.toRect(), black);
+
+    text.render(
+      canvas,
+      '(click anywhere for 1)',
+      Vector2(size.x / 2, 200),
+      anchor: Anchor.topCenter,
+    );
+
+    canvas.drawRect(button, gray);
+
+    text.render(
+      canvas,
+      'click here for 2',
+      Vector2(size.x / 2, size.y - 200),
+      anchor: Anchor.bottomCenter,
+    );
+  }
+
+  @override
+  void onTapDown(TapDownInfo details) {
+    if (button.containsPoint(details.eventPosition.game)) {
+      fireTwo();
+    } else {
+      fireOne();
+    }
+  }
+}

examples/pubspec.yaml

@@ -12,6 +12,7 @@ environment:
 dependencies:
   dashbook: 0.1.6
   flame: ^1.2.0
+  flame_audio: ^1.1.0
   flame_forge2d: ^0.11.0
   flame_svg: ^1.3.0
   flutter:
@@ -35,3 +36,5 @@ flutter:
     - assets/images/layers/
     - assets/images/parallax/
     - assets/svgs/
+    - assets/audio/music/
+    - assets/audio/sfx/

packages/flame_audio/example/lib/main.dart

@@ -29,7 +29,11 @@ class AudioGame extends FlameGame with TapDetector {
 
   @override
   Future<void> onLoad() async {
-    pool = await AudioPool.create('fire_2.mp3', minPlayers: 3, maxPlayers: 4);
+    pool = await FlameAudio.createPool(
+      'sfx/fire_2.mp3',
+      minPlayers: 3,
+      maxPlayers: 4,
+    );
     startBgmMusic();
   }
 
@@ -41,7 +45,7 @@ class AudioGame extends FlameGame with TapDetector {
   }
 
   void fireOne() {
-    FlameAudio.audioCache.play('sfx/fire_1.mp3');
+    FlameAudio.play('sfx/fire_1.mp3');
   }
 
   void fireTwo() {