Update to audioplayers v4

Author: DoumanAsh

README.md

@@ -19,7 +19,7 @@ _The difference between packages and plugins is that packages don't include any
 ## 🖥️ Supported Platforms
 Although flutter-pi is only tested on a Rasberry Pi 4 2GB, it should work fine on other linux platforms, with the following conditions:
 
-- support for hardware 3D acceleration. more precisely support for kernel-modesetting (KMS) and the direct rendering infrastructure (DRI) 
+- support for hardware 3D acceleration. more precisely support for kernel-modesetting (KMS) and the direct rendering infrastructure (DRI)
 - CPU architecture is one of ARMv7, ARMv8, x86 or x86 64bit.
 
 This means flutter-pi won't work on a Pi Zero (only the first one) or Pi 1.
@@ -33,16 +33,16 @@ If you encounter issues running flutter-pi on any of the supported platforms lis
 
 ## 📑 Contents
 
-1. **[Building flutter-pi on the Raspberry Pi](#-building-flutter-pi-on-the-raspberry-pi)**  
-1.1 [Dependencies](#dependencies)  
-1.2 [Compiling](#compiling)  
-2. **[Running your App on the Raspberry Pi](#-running-your-app-on-the-raspberry-pi)**  
-2.1 [Configuring your Raspberry Pi](#configuring-your-raspberry-pi)  
-2.2 [Building the App](#building-the-app-new-method-linux-only)  
-2.3 [Running your App with flutter-pi](#running-your-app-with-flutter-pi)  
-2.4 [gstreamer video player](#gstreamer-video-player)  
-3. **[Performance](#-performance)**  
-3.1 [Graphics Performance](#graphics-performance)  
+1. **[Building flutter-pi on the Raspberry Pi](#-building-flutter-pi-on-the-raspberry-pi)**
+1.1 [Dependencies](#dependencies)
+1.2 [Compiling](#compiling)
+2. **[Running your App on the Raspberry Pi](#-running-your-app-on-the-raspberry-pi)**
+2.1 [Configuring your Raspberry Pi](#configuring-your-raspberry-pi)
+2.2 [Building the App](#building-the-app-new-method-linux-only)
+2.3 [Running your App with flutter-pi](#running-your-app-with-flutter-pi)
+2.4 [gstreamer video player](#gstreamer-video-player)
+3. **[Performance](#-performance)**
+3.1 [Graphics Performance](#graphics-performance)
 3.2 [Touchscreen latency](#touchscreen-latency)
 4. **[Useful Dart Packages](#-useful-dart-packages)**
 5. **[Discord](#-discord)**
@@ -62,7 +62,7 @@ If you encounter issues running flutter-pi on any of the supported platforms lis
 
       <details>
       <summary>More Info</summary>
-    
+
       flutter-pi needs flutters `icudtl.dat` and `libflutter_engine.so.{debug,profile,release}` at runtime, depending on the runtime mode used.
       You actually have two options here:
 
@@ -71,7 +71,7 @@ If you encounter issues running flutter-pi on any of the supported platforms lis
 
       </details>
 
-    
+
     </details>
 
 3. Install cmake, graphics, system libraries and fonts:
@@ -85,15 +85,15 @@ If you encounter issues running flutter-pi on any of the supported platforms lis
     ```
     <details>
       <summary>More Info</summary>
-      
+
       - flutter-pi needs the mesa OpenGL ES and EGL implementation and libdrm & libgbm. It may work with non-mesa implementations too, but that's untested.
       - The flutter engine depends on the _Arial_ font. Since that doesn't come included with Raspbian, you need to install it.
       - `libsystemd` is not systemd, it's just an utility library. It provides the event loop and dbus support for flutter-pi.
       - `libinput-dev`, `libudev-dev` and `libxkbcommon-dev` are needed for (touch, mouse, raw keyboard and text) input support.
       - `libudev-dev` is required, but actual udev is not. Flutter-pi will just open all `event` devices inside `/dev/input` (unless overwritten using `-i`) if udev is not present.
       - `gpiod` and `libgpiod-dev` where required in the past, but aren't anymore since the `flutter_gpiod` plugin will directly access the kernel interface.
     </details>
-    
+
 4. Update the system fonts.
     ```bash
     sudo fc-cache
@@ -122,12 +122,12 @@ If you encounter issues running flutter-pi on any of the supported platforms lis
     ```bash
     sudo raspi-config
     ```
-    
+
 2. Switch to console mode:
    `System Options -> Boot / Auto Login` and select `Console` or `Console (Autologin)`.
 
-3. *You can skip this if you're on Raspberry Pi 4 with Raspbian Bullseye*  
-    Enable the V3D graphics driver:  
+3. *You can skip this if you're on Raspberry Pi 4 with Raspbian Bullseye*
+    Enable the V3D graphics driver:
    `Advanced Options -> GL Driver -> GL (Fake KMS)`
 
 4. Configure the GPU memory
@@ -144,7 +144,7 @@ If you encounter issues running flutter-pi on any of the supported platforms lis
 
 <details>
   <summary>More information</summary>
-  
+
   - flutter-pi requires that no other process, like a X11- or wayland-server, is using the video output. So to disable the desktop environment, we boot into console instead.
   - The old broadcom-proprietary GL driver was bugged and not working with flutter, so we have to use the Fake KMS driver.
   - Actually, you can also configure 16MB of GPU memory if you want to. 64MB are needed when you want to use the [`omxplayer_video_player`](https://pub.dev/packages/omxplayer_video_player) plugin.
@@ -159,7 +159,7 @@ _One-time setup:_
 2. Install the [flutterpi_tool](https://pub.dev/packages/flutterpi_tool):
    Run `flutter pub global activate flutterpi_tool` (One time only)
 3. If running `flutterpi_tool` directly doesn't work, follow https://dart.dev/tools/pub/cmd/pub-global#running-a-script-from-your-path
-   to add the dart global bin directory to your path.  
+   to add the dart global bin directory to your path.
    Alternatively, you can launch the tool via:
    `flutter pub global run flutterpi_tool ...`
 
@@ -168,7 +168,7 @@ _Building the app bundle:_
 2. Run `flutterpi_tool build` to build the app.
     - This will build the app for ARM 32-bit debug mode.
     - `flutterpi_tool build --help` gives more usage information.
-    - For example, to build for 64-bit ARM, release mode, with a Raspberry Pi 4 tuned engine, use:  
+    - For example, to build for 64-bit ARM, release mode, with a Raspberry Pi 4 tuned engine, use:
        `flutterpi_tool build --arch=arm64 --cpu=pi4 --release`
 3. Deploy the bundle to the Raspberry Pi using `rsync` or `scp`:
     - Using `rsync` (available on linux and macOS or on Windows when using [WSL](https://docs.microsoft.com/de-de/windows/wsl/install-win10))
@@ -197,15 +197,15 @@ rsync -a ./build/flutter_assets/ pi@raspberrypi:/home/pi/flutter_gallery/
 <details>
 
 <summary>Instructions</summary>
-    
+
 1. Make sure you've installed the flutter SDK. **You must** use a flutter SDK that's compatible to the installed engine binaries.
-   - for the flutter SDK, use flutter stable and keep it up to date.  
-   - always use the latest available [engine binaries](https://github.com/ardera/flutter-engine-binaries-for-arm)  
-   
+   - for the flutter SDK, use flutter stable and keep it up to date.
+   - always use the latest available [engine binaries](https://github.com/ardera/flutter-engine-binaries-for-arm)
+
    If you encounter error messages like `Invalid kernel binary format version`, `Invalid SDK hash` or `Invalid engine hash`:
    1. Make sure your flutter SDK is on `stable` and up to date and your engine binaries are up to date.
    2. If you made sure that's the case and the error still happens, create a new issue.
-   
+
 2. Open terminal or commandline and `cd` into your app directory.
 
 3. `flutter build bundle`
@@ -219,7 +219,7 @@ rsync -a ./build/flutter_assets/ pi@raspberrypi:/home/pi/flutter_gallery/
        ```bash
        scp -r ./build/flutter_assets/ pi@raspberrypi:/home/pi/my_apps_flutter_assets
        ```
-       
+
 #### Example
 1. We'll build the asset bundle for `flutter_gallery` and deploy it using `rsync` in this example.
 ```bash
@@ -233,7 +233,7 @@ rsync -a ./build/flutter_assets/ pi@raspberrypi:/home/pi/flutter_gallery/
 
 <details>
   <summary>More information</summary>
-    
+
   - flutter_gallery is developed against flutter master. `d77920b4ced4a105ad35659fbe3958800d418fb9` is currently the latest flutter gallery
     commit working with flutter stable.
 </details>
@@ -373,7 +373,7 @@ OPTIONS:
   --pixelformat <format>     Selects the pixel format to use for the framebuffers.
                              If this is not specified, a good pixel format will
                              be selected automatically.
-                             Available pixel formats: RGB565, ARGB4444, XRGB4444, ARGB1555, XRGB1555, ARGB8888, XRGB8888, BGRA8888, BGRX8888, RGBA8888, RGBX8888, 
+                             Available pixel formats: RGB565, ARGB4444, XRGB4444, ARGB1555, XRGB1555, ARGB8888, XRGB8888, BGRA8888, BGRX8888, RGBA8888, RGBX8888,
   --videomode widthxheight
   --videomode widthxheight@hz  Uses an output videomode that satisfies the argument.
                              If no hz value is given, the highest possible refreshrate
@@ -407,12 +407,27 @@ of the flutter app you're trying to run.
 `[flutter engine options...]` will be passed as commandline arguments to the flutter engine. You can find a list of commandline options for the flutter engine [Here](https://github.com/flutter/engine/blob/master/shell/common/switches.h).
 
 ### gstreamer video player
-Gstreamer video player is a newer video player based on gstreamer. The older video player (omxplayer_video_player) was based on deprecated omxplayer and it was kind of a hack. So I recommend using the gstreamer one instead. 
+Gstreamer video player is a newer video player based on gstreamer. The older video player (omxplayer_video_player) was based on deprecated omxplayer and it was kind of a hack. So I recommend using the gstreamer one instead.
 
 To use the gstreamer video player, just rebuild flutter-pi (delete your build folder and reconfigure) and make sure the necessary gstreamer packages are installed. (See [dependencies](#dependencies))
 
 And then, just use the stuff in the official [video_player](https://pub.dev/packages/video_player) package. (`VideoPlayer`, `VideoPlayerController`, etc, there's nothing specific you need to do on the dart-side)
 
+### audioplayers
+
+As of current moment flutter-pi implements plugin for `audioplayers: ^4.0.0`.
+
+There are several things you need to keep in mind:
+
+- As flutter-pi is intended for use on constrained systems like raspberry pi, you should avoid creating multiple temporary instances and instead prefer to use one global instance of `AudioPlayer`. There is limit you can easily hit if you're going to spam multiple instances of `AudioPlayer`
+- Plugin was tested to work with ALSA and `pulseaudio` might prevent the plugin from playing audio correctly:
+    - Hence please make sure you delete `pulseaudio` package from your system.
+    - Make sure you have `gstreamer1.0-alsa` package installed in addition to packages needed for gstreamer video player.
+    - Make sure you can list audio devices using command: `aplay -L`
+        - If there is error, please investigate why and fix it before using audio
+        - One of the common reasons is outdated ALSA config in which case you should delete existing config and replace it with up to date one
+- Finally, if you want to verify your audio setup is good, you can use `gst-launch` command to invoke `playbin` on audio file directly.
+
 ## 📊 Performance
 ### Graphics Performance
 Graphics performance is actually pretty good. With most of the apps inside the `flutter SDK -> examples -> catalog` directory I get smooth 50-60fps on the Pi 4 2GB and Pi 3 A+.
@@ -432,6 +447,7 @@ This is why I created my own (userspace) touchscreen driver, for improved latenc
 | linux_spidev ([package](https://pub.dev/packages/linux_spidev/)) ([repo](https://github.com/ardera/flutter_packages/tree/main/packages/linux_spidev)) | 🖨 peripherals | Hannes Winkler | SPI bus support for dart/flutter, uses kernel interfaces directly for more performance. |
 | dart_periphery ([package](https://pub.dev/packages/dart_periphery)) ([repo](https://github.com/pezi/dart_periphery)) | 🖨 peripherals | [Peter Sauer](https://github.com/pezi/) | All-in-one package GPIO, I2C, SPI, Serial, PWM, Led, MMIO support using c-periphery. |
 | flutterpi_gstreamer_video_player ([package](https://pub.dev/packages/flutterpi_gstreamer_video_player)) ([repo](https://github.com/ardera/flutter_packages/tree/main/packages/flutterpi_gstreamer_video_player)) | ⏯️ multimedia | Hannes Winkler | Official video player implementation for flutter-pi. See [GStreamer video player](#gstreamer-video-player) section above. |
+| audioplayers ([package](https://pub.dev/packages/audioplayers)) ([repo](https://github.com/bluefireteam/audioplayers/tree/main/packages/audioplayers)) | ⏯️ multimedia | Blue Fire | flutter-pi implements audio plugin v4. |
 
 ## 💬 Discord
 There a `#custom-embedders` channel on the [flutter discord](https://github.com/flutter/flutter/wiki/Chat) which you can use if you have any questions regarding flutter-pi or generally, anything related to embedding the engine for which you don't want to open issue about or write an email.

include/plugins/audioplayers.h

@@ -30,6 +30,8 @@ void audio_player_set_volume(struct audio_player *self, double volume);
 
 void audio_player_set_playback_rate(struct audio_player *self, double rate);
 
+void audio_player_set_balance(struct audio_player *self, double balance);
+
 void audio_player_set_position(struct audio_player *self, int64_t position);
 
 void audio_player_set_source_url(struct audio_player *self, char *url);

src/plugins/audioplayers/README.md

@@ -0,0 +1,17 @@
+## audioplayers plugin
+
+### Requirements
+
+- `audioplayers` version `^4.0.0`
+- Working gstreamer installation, including corresponding audio plugin (e.g. `gstreamer1.0-alsa`)
+
+### Troubleshooting
+
+- Check that you can list ALSA devices via command `aplay -L`;
+- Check that you can launch `playbin` on any audio file via `gst-launch`;
+- Make sure `pulseaudio` is deleted
+
+### pulseaudio
+
+Please note that plugin was not tested with `pulseaudio` and it is up to you to make gstreamer work via it.
+As `pulseaudio` takes full control over audio devices, `ALSA` will no longer function correctly with `pulseaudio` installed